Generating Security Objects

  • Updated on Apr 2, 2025
  • Published on Jun 21, 2024
  • 4 minute(s) read

1.0 Overview

The Fortanix-Data-Security-Manager (DSM) can generate new random security objects (keys and MAC secrets).

2.0 Prerequisites

Generating new security objects (keys) requires a Fortanix DSM account, a group, and a user or application configured in that group. See the Fortanix Data Security Manager Getting Started Guide for more details.

3.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 may authenticate as a user or as an app. Both users and applications may generate new security objects, but only apps can perform cryptographic operations using those security objects.

4.0 Create a SecurityObjectsApi Client Object

Creating keys is performed with a SecurityObjectsApi object.

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

SecurityObjectsApi sobjectsApi = new SecurityObjectsApi();

5.0 Construct an SobjectRequest Object

The SobjectRequest object defines the properties of the key that will be created. The objType and keySize or ellipticCurve properties of the SobjectRequest determine what type of key will be created. The name property is required and must be unique.

The list of supported cryptographic algorithms and key sizes is in the Fortanix DSM Developer’s Guide.

For example, to create an SobjectRequest for a 2048 bit RSA key:

import com.fortanix.sdkms.v1.model.ObjectType;
import com.fortanix.sdkms.v1.model.SobjectRequest;

SobjectRequest keyRequest = new SobjectRequest().name("my rsa key").objType(ObjectType.RSA).keySize(2048);

To create an SobjectRequest for a 256 bit AES key:

import com.fortanix.sdkms.v1.model.ObjectType;
import com.fortanix.sdkms.v1.model.SobjectRequest;

SobjectRequest keyRequest = new SobjectRequest().name("my aes key").objType(ObjectType.AES).keySize(256);

To create an SobjectRequest for an elliptic key on curve NistP256:

import com.fortanix.sdkms.v1.model.EllipticCurve;
import com.fortanix.sdkms.v1.model.ObjectType;
import com.fortanix.sdkms.v1.model.SobjectRequest;

SobjectRequest keyRequest = new SobjectRequest().name("my ec key").objType(ObjectType.EC).ellipticCurve(NISTP256);

6.0 Optionally Assign Enabled Cryptographic Operations

If you do not override the default enabled operations, the new key will be created with all operations that make sense for the type of key, except that by default keys will not have the Export operation. 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. Note that enabled operations may be removed from keys, but they cannot be added.

The enabled operations are specified via 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:

import java.util.Arrays;
import com.fortanix.sdkms.v1.model.KeyOperations;
import com.fortanix.sdkms.v1.model.ObjectType;
import com.fortanix.sdkms.v1.model.SobjectRequest;

SobjectRequest keyRequest = new SobjectRequest()
        .objType(ObjectType.RSA)
        .keySize(256)
        .keyOps(Arrays.asList(KeyOperations.SIGN,
                              KeyOperations.VERIFY,
                              KeyOperations.EXPORT));

7.0 Optional Custom Metadata

You may add arbitrary key-value pairs to security objects that can later be retrieved. These are specified via the customMetadata property of the SobjectRequest object.

8.0 Other Optional Fields

The groupId property of the SobjectRequest can be used to specify the group in which the new Security-object should be created. If a group ID is not specified, the default group for the user or app will be used. If specified, the group must be a group that the authenticated user or app belongs to.

The description property of the SobjectRequest object can be used to specify a description for the newly created security object.

The enabled property of the SobjectRequest object can be used to enable or disable the key when it is created. New keys will be enabled by default. Keys may be created in a disabled state and then later enabled.

9.0 Make the Generate Security Object Call

The key is generated by calling the generateSecurityObject() method of the SecurityObjectsApi object. The SobjectRequest is passed to generateSecurityObject(), which returns the KeyObject with metadata about the created key.

import com.fortanix.sdkms.v1.api.KeyObject;
import com.fortanix.sdkms.v1.api.SecurityObjectsApi;

SecurityObjectsApi sobjectsApi = new SecurityObjectsApi();
KeyObject key = sobjectsApi.generateSecurityObject(keyRequest);

Related articles