Deriving Security Objects

Updated: August 7, 2017

SmartKey can generate new keys by deriving them from existing keys and some additional data.

Currently, the only supported mechanism for deriving keys is by encrypting some data with a key.

Prerequisites

Generating new security objects (keys) via derivation requires an SmartKey account, a group, and a user or application configured in that group, and a key in that group. See the SmartKey Developer’s Guide for more details.

Required Operations

The key being used to derive the new key must have the DeriveKey operation enabled.

Authorization and Configuration

You must first authenticate and optionally configure a default API client as described in Configure API Client and Client Authentication. You must authenticate as an application. Users may not create new keys via derivation.

Create a SecurityObjectsApi Client Object

Deriving keys is performed with a SecurityObjectsApi object.

import com.fortanix.sdkms.v1.api.SecurityObjectsApi();

SecurityObjectsApi sobjectsApi = new SecurityObjectsApi();

Construct a DeriveKeyRequest Object

A DeriveKeyRequest object contains information about how the new key material is to be derived, as well as the properties that the new key should have.

The customMetadata, description, enabled, keyOps, keySize, keyType and name properties of the DeriveKeyRequest object define the properties of the key that is to be created. These properties have the same meaning as the like-named properties in the SobjectRequest object as described in Generating Security Objects.

The mechanism property of the DeriveKeyRequest object is a DeriveKeyMechanism object that describes how the new key is to be generated. Currently, the only supported mechanism is encrypting data. The encryptData property of the DeriveKeyMechanism object is an EncryptRequest object describes the data to be encrypted and how it is to be encrypted. Details of configuring EncryptRequest objects are in Public Key Cryptography or Symmetric Cryptography.

import com.fortanix.sdkms.v1.model.DeriveKeyMechanism;
import com.fortanix.sdkms.v1.model.DeriveKeyRequest;
import com.fortanix.sdkms.v1.model.EncryptRequest;
import com.fortanix.sdkms.v1.model.ObjectType;

EncryptRequest encryptRequest = new EncryptRequest().alg(ObjectType.<Deriving key type>).mode(<cipher mode>).plain(<data to encrypt as byte[]>);

DeriveKeyMechanism mechanism = new DeriveKeyMechanism().encryptData(encryptRequest);

DeriveKeyRequest deriveRequest = new DeriveKeyRequest().name("my new key").keyType(ObjectType.<type>).keySize(<size>).mechanism(mechanism);

Make the Derive Call

The new key is derived via the deriveKey() method of a SecurityObjectsApi() object. The key used to perform the derivation and the derive key request are passed to this method. The new key object’s properties are returned.

import com.fortanix.sdkms.v1.model.KeyObject;

KeyObject derivedKey = sobjectsApi.deriveKey(<UUID of the deriving key>, deriveRequest);