Creating a Security Object

  • Updated on Dec 10, 2024
  • Published on Jun 3, 2024
  • 4 minute(s) read

Fortanix DSM can generate new security objects (Cryptographic and MAC keys) with random bytes.

Creating keys is performed with a generateSecurityObject API. The API input body, SobjectRequest object defines the properties of the key that will be created. The ObjectType, KeySize, and EllipticCurve properties of the SobjectRequest determine what type of key will be created. The name property is required and must be unique.

If you do not override the default enabled operations, the new key will be supporting all operations that make sense for the type of key. By default, security objects will not have the “Export” operation enabled. So, for example, RSA keys will have the Sign, Verify, Encrypt, Decrypt, WrapKey, UnwrapKey, DeriveKey, and AppManageable operations. They will not have the MacGenerate or MacVerify operations since those operations are not defined for RSA keys.

WARNING

Enabled operations may be removed from keys, but they cannot be added.

The enabled operations are specified using the KeyOps property of the SobjectRequest. This property is a List. The generated key will be created with its enabled operations equal to the list provided.

If you want to create keys that can be exported from Fortanix DSM, you will need to request that the key be created with the Export operation enabled along with any other operations you wish to enable on the key.

For example, to create a 2048 RSA key that is exportable and may only be used for signing and verifying signature, use this SobjectRequest as shown below:

C++

CK_OBJECT_HANDLE generate_key(CK_FUNCTION_LIST_PTR p11, CK_SESSION_HANDLE hSession, CK_ULONG len) {
CK_RV rv;
CK_MECHANISM mechKeyGen = {
CKM_AES_KEY_GEN, NULL_PTR, 0
};
CK_BBOOL _true = CK_TRUE;
CK_OBJECT_HANDLE hKey;

CK_ATTRIBUTE keyTemplate[] = {
{CKA_VALUE_LEN, &len, sizeof(len)},
{CKA_ENCRYPT, &_true, sizeof(_true)},
{CKA_DECRYPT, &_true, sizeof(_true)}
};

rv = p11->C_GenerateKey(hSession, &mechKeyGen, keyTemplate, sizeof(keyTemplate)/sizeof(*keyTemplate), &hKey);
if (rv == CKR_OK) return hKey; else return CK_INVALID_HANDLE;
}

C#

SecurityObjectsApi sObjectApi = new SecurityObjectsApi();

#Generate RSA Key
SobjectRequest sobjectRequest = new SobjectRequest(
      Name: "Name", 
      KeySize: 2048, 
      ObjType: ObjectType.RSA,
      KeyOps: new List() { KeyOperations.SIGN, KeyOperations.VERIFY, KeyOperations.EXPORT});
KeyObject keyObject = sObjectApi.GenerateSecurityObject(sobjectRequest);

#Generate AES Key
SobjectRequest sobjectRequest = new SobjectRequest(
      Name: "Name", 
      KeySize: 128, 
      ObjType: ObjectType.AES);
KeyObject keyObject = sObjectApi.GenerateSecurityObject(sobjectRequest);

#Generate EC Key
SobjectRequest sobjectRequest = new SobjectRequest()
      Name: "Name", 
      EllipticCurve: EllipticCurve.NISTP256, 
      ObjType: ObjectType.EC);
KeyObject keyObject = sObjectApi.GenerateSecurityObject(sobjectRequest);

Go

#Generate RSA Key
keyName := "name"
objType := sdkms.ObjectTypeRsa
keySize := 2048
sobjectReq := sdkms.SobjectRequest{
      Name: &name,
      ObjType: &objType,
      KeySize: &keySize,
}
sobject, err := client.CreateSobject(ctx, sobjectReq)

#Generate AES Key
objType := sdkms.ObjectTypeAes
keySize := 256
sobjectReq := sdkms.SobjectRequest{
      Name: &name,
      ObjType: &objType,
      KeySize: &keySize,
}
sobject, err := client.CreateSobject(ctx, sobjectReq)

#Generate EC Key
keyName := "name"
objType := sdkms.ObjectTypeEc
curve := sdkms.EllipticCurveNistP256
sobjectReq := sdkms.SobjectRequest{
      Name: &name,
      ObjType: &objType,
      EllipticCurve: &curve,
}
sobject, err := client.CreateSobject(ctx, sobjectReq)

Java

//Generate RSA Key
SobjectRequest sobjectRequest = new SobjectRequest()
          .name("Name")
          .keySize(2048)
          .objType(ObjectType.RSA);
          .keyOps(Arrays.asList(KeyOperations.SIGN, KeyOperations.VERIFY, KeyOperations.EXPORT));
SecurityObjectsApi securityObjectsApi = new SecurityObjectsApi(apiClient);
KeyObject keyObject = securityObjectsApi.generateSecurityObject(sobjectRequest);

// Generate AES Key
SobjectRequest sobjectRequest = new SobjectRequest()
          .name("Name")
          .keySize(128)
          .objType(ObjectType.AES);
SecurityObjectsApi securityObjectsApi = new SecurityObjectsApi(apiClient);
KeyObject keyObject = securityObjectsApi.generateSecurityObject(sobjectRequest);

// Generate EC Key
SobjectRequest sobjectRequest = new SobjectRequest()
          .name("Name")
          .ellipticCurve(EllipticCurve.NISTP256)
          .objType(ObjectType.EC);
SecurityObjectsApi securityObjectsApi = new SecurityObjectsApi(apiClient);
KeyObject keyObject = securityObjectsApi.generateSecurityObject(sobjectRequest);

Python

api_instance = sdkms.v1.SecurityObjectsApi(api_client=client)

#Generate RSA Key
request = sdkms.v1.SobjectRequest(name='Name', key_size=2048, obj_type= sdkms.v1.ObjectType.RSA)
key = api_instance.generate_security_object(request)

#Generate AES Key
request = sdkms.v1.SobjectRequest(name='Name', key_size=128, obj_type= sdkms.v1.ObjectType.AES)
key = api_instance.generate_security_object(request)

#Generate EC Key
request = sdkms.v1.SobjectRequest(name='Name', elliptic_curve= sdkms.v1.EllipticCurve.NISTP256,
            obj_type= sdkms.v1.ObjectType.EC)
key = api_instance.generate_security_object(request)

PHP

public function generateKey() {
    $securityObjectApi = new Swagger\Client\Api\SecurityObjectsApi($client);
    $ObjectobjType = new Swagger\Client\Model\ObjectType();
    $securityObjectRequest = array('name' => 'Name', 'key_size' => 128, 'obj_type' => $objType::AES);
    $securityObjectResponse = $securityObjectApi->generateSecurityObject($request);
}

Javascript

var generateKeyCallback = function(error, data, response) {
    if (error) {
        console.error("Error: " + JSON.stringify(response));
    } else {
        console.log('Security Object Create: ' + JSON.stringify(data));
    }
};

var securityObjectApi = new FortanixSdkmsRestApi.SecurityObjectsApi()
var securityObjectRequest = FortanixSdkmsRestApi.SobjectRequest.constructFromObject({"name": "Name", "key_size": 128, "obj_type": "AES"})
securityObjectApi.generateSecurityObject(securityObjectRequest, generateKeyCallback);

REST API using curl

#Generate RSA Key
curl /crypto/v1/keys -H 'Authorization: Bearer YhXwwa-6C...ig5g' -d '{"name": "Name", "key_size": 2048, "obj_type": "RSA", "group_id": "keygroupid"}'

#Generate AES Key
curl /crypto/v1/keys -H 'Authorization: Bearer YhXwwa-6C...ig5g' -d '{"name": "Name", "key_size": 128, "obj_type": "AES", "group_id": "keygroupid"}'

#Generate EC Key
curl /crypto/v1/keys -H 'Authorization: Bearer YhXwwa-6C...ig5g' -d '{"name": "Name", "elliptic_curve": "NISTP256", "obj_type": "EC", "group_id": "keygroupid"}'

Related articles