Wrapping a Key

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

This operation allows a Security-object to be encrypted by another key for export and transfer out of Fortanix DSM to other systems.

Requirements:

  • The target key to be wrapped, need to be marked Exportable.

  • The wrapping key needs to have WRAPKEY operation enabled.

  • Symmetric keys (AES, DES, DES3), HMAC keys, Opaque objects, and Secret objects can be wrapped with other symmetric or asymmetric keys.

    • Note: Asymmetric Keys (RSA/DSA), cannot wrap keys/secrets with a size larger than the key size.

  • Asymmetric keys (RSA/DSA) can be wrapped with symmetric keys (AES etc) only. Wrapping an asymmetric key with an asymmetric key is not supported.

  • The wrapping parameters will follow the same guidelines as general Encryption operation by the wrapping key. See the Encryption section for more details.

C#

public void wrapKey() {
//kid of key being wrapped
WrapKeyRequest wrapKeyRequest = new WrapKeyRequest(Alg: ObjectType.AES, Kid: kid, Mode: CryptMode.CBC);
WrappingAndUnwrappingApi wrappingAndUnwrappingApi = new WrappingAndUnwrappingApi();
//kid of wrapping key
WrapKeyResponse wrapResponse =  wrappingAndUnwrappingApi.WrapKey(kid, wrapKeyRequest); 
}

Go

//Wrapping Key with an AES Key
wrapKeyReq := sdkms.WrapKeyRequest {
            Subject: sdkms.SobjectById(<Target Key UUID>),
            Alg: sdkms.AlgorithmAes,
            Key: sdkms.SobjectById(<Wrapping Key UUID>),
            Mode: sdkms.CryptModeSymmetric(sdkms.CipherModeCbc),
}
wrapKeyResp, err := client.Wrap(ctx, wrapKeyReq)
wrapKeyResp.WrappedKey //wrapped key bytes

Java

// Wrapping Key with an AES Key
WrapKeyRequest wrapKeyRequest = new WrapKeyRequest()
                  .alg(ObjectType.AES)
                  .kid(<Target Key UUID>)
                  .mode(CryptMode.CBC);
WrappingAndUnwrappingApi wrappingAndUnwrappingApi = new WrappingAndUnwrappingApi(apiClient);
WrapKeyResponse wrapKeyResponse = wrappingAndUnwrappingApi
            .wrapKey(<Wrapping Key UUID>, wrapKeyRequest);
wrapKeyResponse.wrappedKey // wrapped key bytes

Python

#Wrapping Key with an AES Key
api_instance = sdkms.v1.WrappingAndUnwrappingApi(api_client=client)

request = sdkms.v1.WrapKeyRequest(alg=ObjectType.AES, kid=<target Key UUID>, mode=CryptMode.CBC)
wrapping_response = api_instance
                     .wrap_key(<Wrapping Key UUID, request)
wrapping_response.wrapped_key #wrapped key bytes

PHP

public function wrapKey() {
    //  kid of key being wrapped
    $wrapKeyRequestBody = array('alg' => $objType::AES, 'mode' => $cryptMode::CBC, 'kid' => kid);
    $wrapKeyRequest = new Swagger\Client\Model\WrapKeyRequest($wrapKeyRequestBody);
    $wrappingAndUnwrappingApi = new Swagger\Client\Api\WrappingAndUnwrappingApi($client);
    // kid of wrapping key
    $wrapKeyResponse = $wrappingAndUnwrappingApi->wrapKey(kid, $wrapKeyRequest);
}

Javascript

var wrapKeyCallback = function(error, data, response) {
    if (error) {
        console.error("Error: " + JSON.stringify(response));
    } else {
        console.log('Key wrapped successfully. result: ' + JSON.stringify(data));
    }
};

//  kid of key being wrapped
var wrapKeyRequest = new FortanixSdkmsRestApi.WrapKeyRequest.constructFromObject({"alg": "AES", "kid": kid, "mode": "CBC"});
var wrappingAndUnwrappingApi = new FortanixSdkmsRestApi.WrappingAndUnwrappingApi();
// kid of wrapping key
wrappingAndUnwrappingApi.wrapKey(kid, wrapKeyRequest, wrapKeyCallback);

REST API using curl

$ curl <Endpoint URL>/crypto/v1/wrapkey -H 'Authorization: Bearer YhXwwa-6C...ig5g' -d '{"key": {"kid": "Wrapping-Key-UUID"}, "subject": {"kid": "Target Key UUID"}, "alg": "AES", "mode": "CBC"}'

{"wrapped_key": "YiBmaHViIGNpdXJl…ZyB1eXZpZyB2ZQoK", "iv" = "Y25lYm4gdmVidmllamJ2ZWlqYgo="}

Related articles