Wrapping Security Objects

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

1.0 Overview

The Fortanix-Data-Security-Manager (DSM) can export security objects (keys) by wrapping (encrypting) them.

2.0 Prerequisites

Wrapping security objects 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. The key being used to wrap must have the WrapKey operation enabled, and the key being wrapped must have the Export operation enabled.

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 wrap security objects.

4.0 Create a WrappingAndUnwrappingApi Client Object

Wrapping keys is performed with a WrappingAndUnwrappingApi object.

import com.fortanix.sdkms.v1.api.WrappingAndUnwrappingApi;

WrappingAndUnwrapping wrappingApi = new WrappingAndUnwrappingApi();

5.0 Construct a WrapKeyRequest Object

The WrapKeyRequest object defines what key will be wrapped and how it will be wrapped. The alg (encryption algorithm) and kid (key ID) properties are required. alg must be the encryption algorithm of the key that will be doing the wrapping (which is specified in the call to wrapKey and not in the WrapKeyRequest object). The kid property specifies what key will be wrapped (exported).

The mode, iv, tagLen, and ad properties are either ignored, optional, or required, depending on the encryption algorithm of the wrapping key and selected block cipher mode (if symmetric cryptography is used). See Public Key Cryptography and Symmetric Cryptography for more details on these parameters.

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

For example, to wrap using an RSA key:

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

WrapKeyRequest wrapRequest = new WrapKeyRequest().objType(ObjectType.RSA).kid(<UUID of key to be wrapped);

For example, to wrap using an AES key in GCM mode:

import com.fortanix.sdkms.v1.model.CipherMode;
import com.fortanix.sdkms.v1.model.ObjectType;
import com.fortanix.sdkms.v1.model.WrapKeyRequest;

WrapKeyRequest wrapRequest = new WrapKeyRequest().objType(ObjectType.AES).mode(CipherMode.GCM).tagLen(128).kid(<UUID of key to be wrapped>);

6.0 Make the WrapKey Call

Wrapping is performed with the wrapKey() method of WrappingAndUnwrappingApi. The wrapped key is returned as the wrappedKey property of the WrapKeyResponse object.

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

WrapKeyResponse wrapResponse = wrappingApi.wrapKey(<UUID of the key being used to wrap>, wrapRequest);
byte[] wrappedKey = wrapResponse.getWrappedKey();

Depending on the encryption algorithm and cipher mode used to wrap the key, you may also need the iv and tag properties of the WrapKeyResponse object in order to be able to later unwrap the key.

Related articles