1.0 Overview
The Fortanix-Data-Security-Manager (DSM) can import keys and opaque objects (generally cryptographic certificates) that were created outside of Fortanix DSM. Note that except for public keys and certificates, it is generally more secure to create keys inside of Fortanix Data Security Manager or first wrap the key and import the wrapped key into Fortanix Data Security Manager.
2.0 Prerequisites
Importing a security objects (key) 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 Only Unencrypted Keys May be Imported
The key value must be unencrypted (that is, not encrypted or password-protected). If the key you are importing an encrypted key, you must first decrypt the key, either in your application or using a program such as openssl. Alternatively, you may import wrapped keys into Fortanix Data Security Manager.
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 may authenticate as a user or as an app. Both users and applications may import security objects, but only apps can perform cryptographic operations using those security objects.
5.0 Create a SecurityObjectsApi Client Object
Importing keys is performed with a SecurityObjectsApi object.
import com.fortanix.sdkms.v1.api.SecurityObjectsApi();
SecurityObjectsApi sobjectsApi = new SecurityObjectsApi();
6.0 Construct an SobjectRequest Object
The SobjectRequest object defines the properties of the key that will be imported, including the key material to be used for the key. The objType property of the SobjectRequest determine what type of key will be imported. The keySize and ellipticCurve properties of the SobjectRequest are ignored, as the key size or curve can be determined from the key material. The name property is required and must be unique. The value property provides the key material. The required format of value depends on what type of object is being imported.
The list of supported cryptographic algorithms and key sizes is in the Fortanix Data Security Manager Developer’s Guide.
For example, to create an SobjectRequest for importing an 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).value(<key value as byte[]>);
To create an SobjectRequest for importing an 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.RSA).value(<key value as byte[]>);
To create an SobjectRequest for importing an elliptic key:
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).value(<key value as byte[]>);
7.0 Imported Object Encoding
The imported object value must be in the correct format, which depends on the type of the imported key.
7.1 Symmetric Keys
Symmetric keys (AES, DES, and DES3) should be raw binary bytes containing the key material. For example, a 128-bit AES key should be 16 bytes of data, and 56-bit DES key should be 7 bytes of data.
7.2 RSA Keys
RSA keys should be in DER format. openssl rsa can be used to convert keys between PEM and DER
7.3 Elliptic Curve Keys
Elliptic curve keys should also be in DER format.
8.0 Optionally Assign Enabled Cryptographic Operations
If you do not override the default enabled operations, the imported 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 imported key will be created with its enabled operations equal to the list provided.
If you want to import keys that can be exported from Fortanix DSM, you will need to request that the key be imported 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)
.value(<key value as byte[]>)
.keyOps(Arrays.asList(KeyOperations.SIGN,
KeyOperations.VERIFY,
KeyOperations.EXPORT));
9.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.
10.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.
11.0 Make the Import Security Object Call
The key is imported by calling the importSecurityObject() 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);