1.0 Security Object Derivation
Fortanix-Data-Security-Manager (DSM) 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.
2.0 Prerequisites
Generating new security objects (keys) via derivation requires a Fortanix DSM account, a group, and a user or application configured in that group, and a key in that group. See the Fortanix Data Security Manager Getting Started Guide for more details.
3.0 Required Operations
The key being used to derive the new key must have the DeriveKey operation enabled.
4.0 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.
5.0 Create a SecurityObjectsApi Client Object
Deriving keys is performed with a SecurityObjectsApi object.
import com.fortanix.sdkms.v1.api.SecurityObjectsApi();
SecurityObjectsApi sobjectsApi = new SecurityObjectsApi();
6.0 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);
7.0 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);8.0 HMAC-Based Key Derivation
HMAC-based key derivation function (HKDF) is a new key derivation mechanism for the Fortanix DSM crypto API endpoint /crypto/v1/derive. This API has a mechanism field that will have a new variant DeriveKeyMechanism::hkdf HKDF gives a secret key as its output by extracting a strong pseudorandom key from the input provided to it.
The following is the request payload (PUT API) to import a SECRET key with a DERIVEKEY permission.
curl -k --location --request PUT 'https://qa1.sit.fortanix.net/crypto/v1/keys' \
--header 'Authorization: Bearer BecIP57dnV1rj8nlGEbxqMnKLA9s_Yf7uKN0hG9sCz-PG7OJ9BXnB8Ee5szHF-E9pUi13ZSvnjiGg0_CnFyQPg' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "test secret3",
"description": "",
"obj_type": "SECRET",
"key_ops": [
"APPMANAGEABLE",
"EXPORT",
"DERIVEKEY"
],
"value": "<base64 ecoded string>", //base64 encoded value
"expirationDate": null,
"enabled": true,
"group_id": "aee400e1-a83c-4480-bf3f-179a67652329"
}'
The following is the request payload (POST API) for deriving a key using hkdf mechanism:
curl -k --location --request POST 'https://qa1.sit.fortanix.net/crypto/v1/derive' \
--header 'Authorization: Bearer BecIP57dnV1rj8nlGEbxqMnKLA9s_Yf7uKN0hG9sCz-PG7OJ9BXnB8Ee5szHF-E9pUi13ZSvnjiGg0_CnFyQPg' \
--header 'Content-Type: application/json' \
--data-raw '{
"key": {
"kid": "c8a17ea9-e335-4083-9a9f-f080bd50788e"
},
"key_type": "AES",
"key_size": 256,
"name": "testhkdf3",
"mechanism": {
"hkdf": {
"hash_alg": "SHA256",
"info": "RGF0YWJhc2UgRW5jcnlwdGlvbkRhdGFiYXNlIEVuY3J5cHRpb24="
}
},
"transient": false,
"group_id": "aee400e1-a83c-4480-bf3f-179a67652329"
}' The following is the request payload (POST API) for encrypting the derived HKDF key using encrypt_data mechanism.
curl -k --location --request POST 'https://qa1.sit.fortanix.net/crypto/v1/keys/fc05122f-879f-49fd-8cbd-e47a64e2a91b/derive' \
--header 'Authorization: Basic OTgwNTI0MjktNWIwNi00YTNhLTg5NjktZWVkMTU5MjA2NWE2OjdxUlp5SnEwN0JiTldkMEVaZWdFZ0dxVlU4VktETjF3Wk9YUnYxR3ozVFV0Z0hFUnZHSngyNTFwZC1NU2Jjc2ZLalhJajY5M05GT0diZi05SkJtdnF3' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "testHKDF3",
"key_type": "AES",
"key_size": 128,
"mechanism": {
"encrypt_data": {
"alg": "AES",
"plain": "RGF0YWJhc2UgRW5jcnlwdERhdGFiYXNlIEVuY3J5cHQ=",
"mode": "ECB"
}
},
"group_id": "aee400e1-a83c-4480-bf3f-179a67652329"
}'