Unwrapping Security Objects

1.0 Overview

The Fortanix-Data-Security-Manager (DSM) can import security objects (keys) by unwrapping them.

2.0 Prerequisites

Unwrapping 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 is used to unwrap must have the UnwrapKey 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 unwrap security objects, but only apps can perform cryptographic operations using those security objects.

4.0 Create a WrappingAndUnwrappingApi Client Object

Unwrapping keys is performed with a WrappingAndUnwrappingApi object.

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

WrappingAndUnwrapping wrappingApi = new WrappingAndUnwrappingApi();

5.0 Construct an UnwrapKeyRequest Object

The UnwrapKeyRequest object provides the properties for the Security-object that is being imported, the wrapped security object contents, and information necessary to unwrap the security object.

The wrapped key is passed as the wrappedKey property of the UnwrapKeyRequest object. This property must be an array of bytes.

The objType, name, description, enabled, keyOps and customMetadata properties of the UnwrapKeyRequest object define the properties of the key that is being unwrapped. See Generating Security Objects for more details about these fields.

The alg, mode, iv, and tag properties of the UnwrapKeyReuqest object define how the wrapped key will be decrypted. These properties must match what was returned when the key was wrapped. See Public Key Cryptography and and Symmetric Cryptograph for details on these fields.

For example, to unwrap an AES key that wrapped with an RSA key:

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

UnwrapKeyRequest unwrapRequest = new UnwrapKeyRequest()
        // These are properties of the key we are unwrapping:
        .objType(ObjectType.AES)
        .name("new AES key")
	// These are details about how the key was wrapped:
	.alg(ObjectType.RSA);

6.0 Make the Unwrap Call

Unwrapping is performed with the unwrapKey() method of WrappingAndUnwrappingApi. This call returns a KeyObject with the properties of the unwrapped key.

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

KeyObject unwrappedKey = wrappingApi.unwrapKey(<UUID of the key being used to unwrap>, unwrapRequest);