Please Note:

Importing, Exporting, and Replicating Keys

The XML Interface enables you to:

Import symmetric keys (see KeyImportRequest)
Examples:
Export symmetric keys (see KeyExportRequest)
Examples:
Export public keys (see PublicKeyExportRequest)
Examples:
- Export an RSA Key

Plain text RSA private keys are imported and exported in PEM-encoded ASN.1 DER-encoded PKCS #1 format. In addition, the NAE Server is able to import and export encrypted RSA keys. They are imported and exported in PEM ASCII-encoded PKCS #12 format and can only be used with other NAE Servers.

The client can request that the server export a specified key to the client. That key must be exportable and accessible by the user. Global keys are available to any user; non-global keys are available to their owners. For information on generating exportable keys on the server, see Key Management Operations.

KeyImportRequest

Import a key.

<KeyImportRequest>
    <ID>...</ID>
    <KeyName>...</KeyName>
    <KeyUUID>...</KeyUUID>       #Optional
    <KeyMUID>...</KeyMUID>       #Optional
    <ExternalKeyID>...</ExternalKeyID>           #Optional
    <Algorithm>...</Algorithm>
    <VersionedKey/>                 # optional
    <KeyVersionState>...</KeyVersionState>       # optional
    <WrapAlgorithm>...</WrapAlgorithm>         # optional
    <HashAlgorithm>...</HashAlgorithm>          # optional
    <Salt>...</Salt>                    # optional
    <Info>...</info>                    # optional
    <OkmLen>...</OkmLen>                    # optional
    <WrapKeyName>...</WrapKeyName>                    # optional
    <Padded/>                    # optional
    <WrapFormat>...</WrapFormat>                   # optional
    <PBEParameters>...</PBEParameters>          #optional
    <Password>...</Password>
    <KeyData>...</KeyData>
    <Exportable/>
    <Deletable/>
    <Aliases>                        # optional, supported for 6.3 and higher
    <Alias>
        <Name>...</Name>
    </Alias>
    <Alias>
        <Name>...</Name>
        <Type>...</Type>
    </Alias>
    </Aliases>
    <KeyRotation>                    # optional, supported for 6.3 and higher 
        <Frequency>...</Frequency>       
    </KeyRotation>
</KeyImportRequest>
<KeyImportResponse>
   <ID>...</ID>
   <Success>true</Success>
   <Fingerprint>...</Fingerprint>
   <KeyName>...</KeyName>
</KeyImportResponse>

Import a key having Custom Attributes.

<KeyImportRequest>
    <ID>...</ID>
    <KeyName>...</KeyName>           # optional
    <RandomKey/>                     # optional
    <Algorithm>...</Algorithm>
    <KeySize>...</KeySize>           # optional
    <KeyData>...</KeyData>
    <Exportable/>                    # optional
    <Deletable/> # optional
    <Permissions>...</Permissions>   # optional
    <CustomAttributeList>            # optional
        <CustomAttribute>
            <Name>...</Name>
            <Type>...</Type>         # optional, supported for 3.0, 6.1, and higher
            <Value>...</Value>
        </CustomAttribute>
        ...
    </CustomAttributeList>
</KeyImportRequest>

Element	Description
ID	Contains the user-specified request ID.
KeyName	Specifies a name for the key. Key names must be unique: two keys cannot have the same name. If you do not include the KeyName element in the request, you must request a randomly-generated name for the key, using the RandomKey element. The KeyGenRequest element requires that you include either the RandomKey child element or the KeyName child element.
uuid	Universally Unique Identifier (uuid) is a 128 bits DPM key identfier. It is specified in 32 hexadecimal lowercase digits with 4 dashes. If the uuid is not specified by the user, then system autiomatically generates a uuid. For example, `<KeyUUID>426ba632-2244-4ae1-8b3a-ad8162a1df47</KeyUUID>`.
muid	Multiversally Unique Identifier (muid) is a 256 bits DPM key identfier. For example, `<KeyMUID>426ba632-2244-4ae1-8b3a-ad8162a1df476d2c89a7-5830-476a-b5d0-b2edaca55d7e</KeyMUID>`.
keyId	It is a 32 bit DPM key identifier. It is specified in Long type format. For example, `<ExternalKeyID>9934567890</ExternalKeyID>`.
RandomKey	Indicates that the server should generate a random unique key name for the generated key. The randomly-generated key name is guaranteed to be a cryptographically secure random string. If you do not include the RandomKey element in the request, you must specify a name for the key, using the KeyName element. The KeyGenRequest element requires that you include either the RandomKey child element or the KeyName child element.
Algorithm	Contains a standard identifier string for a cryptographic algorithm supported by the server. The length of the Algorithm string should not exceed 256 characters. The algorithm can be any of the following: • AES • DESede • ARIA • HmacSHA1 • HmacSHA256 • HmacSHA384 • HmacSHA512 • RSA • SEED • RSA-Certificate • EC-Certificate (represents ECC)
VersionedKey	Indicates that this is a versioned key. When you use the KeyImportRequest to create a version key, it automatically creates the first version of the key. To create the subsequent versions, use `KeyVersionGenRequest` or `KeyVersionImportRequest`.
KeyVersionState	The desired state of the first key version. Valid values are: • Pre-Active • Active • Restricted • Retired If you do not include this tag, the first key version is Active by default.
KeySize	Specifies the key size. If you do not specify a key size by including the KeySize element, the server uses the default key size for the algorithm, listed in bold below. The supportedkey sizes are: • AES - 128, 256,192 • DESede - 112, 168 • HmacSHA1 - variable, 160 • HmacSHA1-128 and 25 • HmacSHA256-128/192/256/512 • HmacSHA384-192/288/384 • HmacSHA512-256/384/512 • RSA-4096 • RSA - 512, 1024, 2048 • EC-secp224k1-225 • EC-secp224r1-224 • EC-secp256k1-256 • EC-secp384r1-384 • EC-secp521r1-521 • EC-prime256v1-256 • EC-brainpoolP224r1-224 • EC-brainpoolP224t1-224 • EC-brainpoolP256r1-256 • EC-brainpoolP256t1-256 • EC-brainpoolP384r1-384 • EC-brainpoolP384t1-384 • EC-brainpoolP512r1-512 • EC-brainpoolP512t1-512
KeyData	The KeyData element contains the actual key being imported. For import and export operations the KeyData element contains the ASCII-Hex-encoded bytes of the key.
Exportable	Indicates that the key can be exported from the server using a client XML request. Keys created on the server are not, by default, exportable. This element is optional.
Deletable	Indicates that the key can be deleted from the server using a client request. Keys created on the server are not, by default, deletable. This element is optional.
Aliases	Specifies the list of Alias elements.
Alias	Alias is unique for each key version. You can search the keys using Alias. This element contains `<Name>` and `<Type>` elements.
Name	Indicates the name of the Alias elements.
Type	Specifies the data type of an Alias (`<Name>`) element. It is an optional tag, and can be of the following types: • String • URI NOTE: If `<Type>` is not specified, the data type of the `<Name>` element is selected as String.
Permissions	Specifies the key usage permissions granted to specific groups. An owner of a key can grant key usage permissions to specific user groups by adding the Permissions element, and the Group and appropriate key usage permission elements: Encrypt, Decrypt, MAC, MACV, SIGN, SIGNV, UsePrivate, and UsePublic. This element is optional.
Group	Specifies the group that has permission to use key. A child element of the Permissions element.
Encrypt	Indicates that the group can use the key to encrypt data.
Decrypt	Indicates that the group can use the key to decrypt data.
MAC	Indicates that the group can use the key to create MACs. Available for HMAC keys.
MACV	Indicates that the group can use the key to verify MACs. Available for HMAC keys.
SIGN	Indicates that the group can use the key to create signatures. Available for RSA keys.
SIGNV	Indicates that the group can use the key to verify signatures. Available for RSA keys.
UsePrivate	Indicates that the group can use the private portion of the key to decrypt data. Available for RSA keys.
UsePublic	Indicates that the group can use the public portion of the key to encrypt data. Available for RSA keys.
KeyRotation	Specifies the key rotation attributes. This element is optional.
Frequency	When the KeyRotation attribute is present, this element contains the rotation frequency of a key. It specifies the number of days from the current date to rotate the key. It should be greater than or equal to 0. If set to 0, the auto rotation of key will be disabled. NOTE: The scheduler job that triggers the auto rotation of keys at the specified frequency is `system_auto_key_rotation`. For more details on the Scheduler, refer to Administration Guide.
CustomAttributeList	Specifies the list of custom attributes. This element can contain multiple CustomerAttribute elements. This element is optional.
CustomAttribute	When a custom attribute is present, this element contains one Name and one Value element.
Name	Indicates the name of the custom attribute.
Type	Data type of Custom Attribute. Can be one of the following types: • String • Integer • Long Integer • Big Integer • Enumeration • Boolean • Byte String • Date/Time (default format: "yyyy-mm-dd hr:mm:ss") • Interval *NOTE: If `<Type>` is not specified, then String is selected as the default data-type for `<Value>`.
Value	Specifies the value of the attribute. This value must be base64 encoded, and input is considered as text. If your original data contains non-printable characters, convert the original data to hex values, and then convert the hex values to base64.
WrapAlgorithm	Possible value: • PBE - For password based encryption • HKDF - In case of AES-UNWRAP, if this is specified, then the key will be derived from HKDF parameters.
PBEParameters	Click here for detailed description of PBE parameters.
HashAlgorithm	Possible values: SHA1, SHA224, SHA256, SHA384, SHA512.
Salt	Random HEX bytes of any length.
Info	Random HEX bytes of any length.
OkmLen	The desired OKM length in integer.
WrapKeyName	Key name to be used as unwrapping key. If it is a AES key, it does AES Unwrap. If it is RSA key, it does RSA Unwrap.
Padded	If specified, AES-UNWRAP padding is performed. (RFC 5649)
WrapFormat	Applicable for RSA Unwrap. The supported wrap formats are PKCS1v1.5 (default) and for the PKCS1v2.1 implementation formats are: • PKCS1v2.1/RSAOAEP-SHA1 • PKCS1v2.1/RSAOAEP-SHA256 • PKCS1v2.1/RSAOAEP-SHA384 • PKCS1v2.1/RSAOAEP-SHA512

KeyImportResponse

Server response to a KeyImportRequest

<KeyImportResponse>
<ID>...</ID>
<Success>true</Success>
<KeyName>...</KeyName>
<Fingerprint>...</Fingerprint>
</KeyImportResponse>

Element	Description
ID	Contains the user-specified request ID.
Success	Indicates if the operation was successful. true indicates success. false indicates failure. When the operation is successful, the response element will contain the elements described below. When the operation fails, the response element contains the FatalError and ErrorString elements to illustrate why the failure occurred and help you troubleshoot. For a list of possible error IDs and strings, see Error Messages.
KeyName	Contains the name of the key
Fingerprint	Contains the fingerprint of the key.

Import a Key

In the example below, the client imports a key with custom attributes.

<KeyImportRequest>
<ID>6</ID>
<KeyName>Key_c</KeyName>
<Algorithm>AES</Algorithm>
<KeyData>f00f09bf5058ff5b552490ab2e8991ae</KeyData>
<Exportable/>
<Deletable/>
</KeyImportRequest>
<KeyImportResponse>
<ID>6</ID>
<Success>true</Success>
<Fingerprint>6AC4C74C6458F8CE</Fingerprint>
<KeyName>Key_c</KeyName>
</KeyImportResponse>

Import a Key with Custom Attributes

In the example below, the client imports an AES key with custom attributes.

<KeyImportRequest>
    <ID>7</ID>
    <KeyName>key_d</KeyName>
    <Algorithm>AES</Algorithm>
    <KeySize>256</KeySize>
    <KeyData>29DE1ED3C0BD13334684CBF04497E44A1D63DCE0FDB7D5EA382470FF085DC317</KeyData>
    <Exportable/>
    <Deletable/>
    <CustomAttributeList>
        <CustomAttribute>
            <Name>ImportInt</Name>
            <Type>Integer</Type>
            <Value>MTAw</Value>
        </CustomAttribute>
    </CustomAttributeList>
</KeyImportRequest>
<KeyImportResponse>
    <ID>7</ID>
    <Success>true</Success>
    <Fingerprint>BF14803AADF4B8E9</Fingerprint>
    <KeyName>key_d</KeyName>
</KeyImportResponse>

Import a Key with External key-Ids

In the example below, the client imports an AES key.

<KeyImportRequest>
<ID>7</ID>
<KeyName>key_d</KeyName>
<KeyUUID>426ba632-2244-4ae1-8b3a-ad8162a1df47</KeyUUID>
<KeyMUID>426ba632-2244-4ae1-8b3a-ad8162a1df476d2c89a7-5830-476a-b5d0-b2edaca55d7e</KeyMUID>
<ExternalKeyID>9934567890</ExternalKeyID>
<Algorithm>AES</Algorithm>
<KeySize>256</KeySize>
<KeyData>...</KeyData>
<Exportable/>
<Deletable/>
</KeyImportRequest>
<KeyImportResponse>
<ID>7</ID>
<Success>true</Success>
<Fingerprint>BF14803AADF4B8E9</Fingerprint>
<KeyName>key_d</KeyName>
</KeyImportResponse>

Import a Key using Password Based Encryption (PBE) Parameters

In the example below, the client imports key with PBE parameters. The PBE parameters value must be same as used in the KeyExportRequest.

<KeyImportRequest>
    <ID>001</ID>
    <KeyName>test-key</KeyName>
    <Algorithm>AES</Algorithm>
    <KeySize>256</KeySize>
    <KeyData>Ax0zJk4V0zJo8k7CYHQ+3OHGx93uclqTa6gUkVxnYtI=</KeyData>
    <Exportable/>
    <Deletable/>
    <WrapAlgorithm>PBE</WrapAlgorithm>
    <PBEParameters>
      <HashAlgorithm>sha256</HashAlgorithm>
      <Password>PBEPassword</Password>
      <Iteration>10000</Iteration>
      <DkLen>32</DkLen>
      <Salt>92280e35fa929ec28fb140f2862c5a32</Salt>
      <Purpose>wrapPBE</Purpose>
   </PBEParameters>
</KeyImportRequest>

Import Certificate as a Managed Object using PKCS1

In the example below, the client imports a certificate using PKSC1.

<KeyImportRequest>
<ID>1000002</ID>
<KeyName>Cert_PKCS1_XML</KeyName>
<Algorithm>RSA-Certificate</Algorithm>
<KeyData>

-----BEGIN CERTIFICATE-----
MIIDvzCCAqegAwIWhcNMjMwOTE2MDQzODE5WjBnMQswCQYDVQQGEwJ1czEL
MAkGA1UECBMCY2ExFTATBgNVBAcTDHJlZHdvb2QgY2l0eTEQMA4GA1UEChMHc2Fm
ZW5ldDEUMB0 ......... rx12h6B5OWcCNOfbgTOnTisbC68tJ8w0p3wlU
spCdBamDZ6KjHq46CH8CWfQl19Gj4nYC4fytLhIDJov7LeNiEzTlQ48J0+75RTvycjWKibEI
-----END CERTIFICATE-----

-----BEGIN PRIVATE KEY-----
MIIEowIBAAKCAQEAhLItSYS7WHe22H+VOyj5GlAkwcylRsCAl/kbLBUW5adSB5K3
S4SWSV5ufwJZ9CXX0 ......... ypWx5VbvHAmHkLiVIs6Xq8FDtJ6sxXx++QJ3ea0GPf7A
mzXC86k6UN7ya29wDFuWwLK+gnwD2THORrdk5U+1B0PywK4JdDOR
-----END PRIVATE KEY-----
</KeyData>
<Exportable/>
<Deletable/>
</KeyImportRequest>
<KeyImportResponse>
<ID>1000002</ID>
<Success>true</Success>
<Fingerprint>81162B67DA2D7B5A</Fingerprint>
<KeyName>Cert_PKCS1_XML</KeyName>
</KeyImportResponse>

Import Certificate as a Managed Object using PKCS8

In the example below, the client imports a certificate using PKSC8.

<KeyImportRequest>
<ID>1000002</ID>
<KeyName>Cert_PKCS1_XML</KeyName>
<Algorithm>RSA-Certificate</Algorithm>
<KeyData>

-----BEGIN CERTIFICATE-----
MIIDvzCCAqegAwIBAgIDAKLeMA0GCSqGSIb3DQEBCwUAMIGbMQswCQYDVQQGEwJV
UzELMAkG ......... 9vKL1Ff7A55/alYey5WvQvIiNSOMNajHJzZCsmI6HW
4GcMTdFet6WLZlrrtfNF2aYZzaT8Z6Xq5WzhZI0aCprrXxJX3LD1yLniYtv+I3sn
-----END CERTIFICATE-----

-----BEGIN RSA PRIVATE KEY-----
MIIEvwIBADANBgkqhkiG9w0BAQEFAASCBgSlAgEAAoIBAQD7HkWRxyFZ7 HkWRxyFZ7HkWRxyFZnTwOcuZa ......... M+p2JD1B69yZaIX Kaavs6wmyCCctz5oF7HkWRxyFZ6Ox9VLbWY15BmNFu3w67Jvi+z/Rruwt/Qa
OMDN6GJbHF+NyP8VZPJ2Pwazrg==
-----END RSA PRIVATE KEY-----
</KeyData>
<Exportable/>
<Deletable/>
</KeyImportRequest>
<KeyImportResponse>
<ID>1000002</ID>
<Success>true</Success>
<Fingerprint>81162W958F2D7B5A</Fingerprint>
<KeyName>Cert_PKCS1_XML</KeyName>
</KeyImportResponse>

Import Certificate as a Managed Object using PKCS12

In the example below, the client imports a certificate using PKSC12.

<KeyImportRequest>
<ID>1000002</ID>
<KeyName>Cert_PKCS12_XML</KeyName>
<Algorithm>RSA-Certificate</Algorithm>
<Password>YXNkZjEyMzQ=</Password>
<KeyData>
MIIKMAIBAzCCCfYGCSqGSIb3DQEHAaCCCecEggnjMIIJ3zCCBH8GCSqGSIb3DQEHBqCCBHAwggRsAgEAMIIEZQYJKoZIhva ......... cNAQcBMBwGCiqGSIb3DQEMAQMwDgQIy
SS8AXipCEzdHu2xWn8epxP/viQmaMTwwFQYJKoZIhvcNAQkUMQgeBgBiAGEAejAjBgkqhkiG9w0BCRUxFgQUXESdPVXviBWt68FfXsKev4XRyT0wMTAhMAkGBSsOAwIaBm2FhTiiTlXbUM29TBAiN4BfHi6e53AICCAA=
</KeyData>
<Exportable/>
<Deletable/>
</KeyImportRequest>
<KeyImportResponse>
<ID>1000002</ID>
<Success>true</Success>
<Fingerprint>8E70949492BA7892</Fingerprint>
<KeyName>Cert_PKCS12_XML</KeyName>
</KeyImportResponse>

Import a Wrapped AES Key using RSA Unwrap with PKCS1v2.1/RSAOAEP-SHA512 Padding

<KeyImportRequest>
<ID>1000002</ID>
<KeyName>AES_Key_Name</KeyName>
<Algorithm>AES</Algorithm>
<KeySize>256</KeySize>
<KeyData>zPG+lxQBwlYiPq9XTtsPlJ4......gofUqxbm8DQ==</KeyData>
<WrapKeyName>NAME_OF_RSA_PRIVATE_KEY_TO_BE_USED_AS_UNWRAPPING_KEY</WrapKeyName>
<WrapFormat>PKCS1v2.1/RSAOAEP-SHA512</WrapFormat>
<Exportable/>
<Deletable/>
</KeyImportRequest>
<KeyImportResponse>
<ID>001</ID>
<Success>true</Success>
<Fingerprint>2FAFD1D920FD8ED0</Fingerprint>
<KeyName>AES_Key_Name</KeyName>
</KeyImportResponse>

Import a Wrapped RSA Key using AES Unwrap

<KeyImportRequest>
<ID>1000002</ID>
<KeyName>RSA_Key_Name</KeyName>
<Algorithm>RSA</Algorithm>
<KeySize>2048</KeySize>
<KeyData>jAp0gBXBOO5+XKZh2/s+oaEp31DCNVRgpDyOinli1/CEJJS851WWV6rSJk3Yhh/j5Y27mLJ2/FtmWpWGvNJcPYCgFJzAd4S6lxwubxzrs..............MKjvxYb5Uiys4uCQ75SNDmNDVwJkKt90J/K2bD8/VZ8rlhjnJY1lPHhBdlkzn9BvHQjaLh7bv+4Mqf2Ock4KQAOZKMv6HYoYcMnarCMxgrKFfhCoJ72ZMIdsF+e+ZtZjdAfad8KV+ko4BGn8H9/zkE8PaP+BwEyL2AdY9F0k31Fzy8w8Mo=</KeyData>
<WrapKeyName>NAME_OF_AES_KEY_TO_BE_USED_AS_UNWRAPPING_KEY</WrapKeyName>
<Exportable/>
<Deletable/>
</KeyImportRequest>
<KeyImportResponse>
<ID>001</ID>
<Success>true</Success>
<Fingerprint>2FAFD1D920FD8ED0</Fingerprint>
<KeyName>RSA_Key_Name</KeyName>
</KeyImportResponse>

Element	Description
ID	Contains the user-specified request ID.
KeyName	Specifies a name for the key. Key names must be unique: two keys cannot have the same name. If you do not include the KeyName element in the request, you must request a randomly-generated name for the key, using the RandomKey element. The KeyGenRequest element requires that you include either the RandomKey child element or the KeyName child element.
RandomKey	Indicates that the server should generate a random unique key name for the generated key. The randomly-generated key name is guaranteed to be a cryptographically secure random string. If you do not include the RandomKey element in the request, you must specify a name for the key, using the KeyName element. The KeyGenRequest element requires that you include either the RandomKey child element or the KeyName child element.
Algorithm	Contains a standard identifier string for a cryptographic algorithm supported by the server. The length of the Algorithm string should not exceed 256 characters. The algorithm can be any of the following: • AES • DESede • HmacSHA1 • RSA • SEED • RSA-Certificate • EC-CR (represents ECC)
KeyData	The KeyData element contains the actual key being imported. For import and export operations the KeyData element contains the ASCII-Hex-encoded bytes of the key.
Exportable	Indicates that the key can be exported from the server using a client XML request. Keys created on the server are not, by default, exportable. This element is optional.
Deletable	Indicates that the key can be deleted from the server using a client request. Keys created on the server are not, by default, deletable. This element is optional.
Permissions	Specifies the key usage permissions granted to specific groups. An owner of a key can grant key usage permissions to specific user groups by adding the Permissions element, and the Group and appropriate key usage permission elements: Encrypt, Decrypt, MAC, MACV, SIGN, SIGNV, UsePrivate, and UsePublic.This element is optional.
Password	The password (in base 64) used to encrypt the key.
Group	Specifies the group that has permission to use key. A child element of the Permissions element.
Encrypt	Indicates that the group can use the key to encrypt data.
Decrypt	Indicates that the group can use the key to decrypt data.
MAC	Indicates that the group can use the key to create MACs. Available for HMAC keys.
MACV	Indicates that the group can use the key to verify MACs. Available for HMAC keys.
SIGN	Indicates that the group can use the key to create signatures. Available for RSA keys.
SIGNV	Indicates that the group can use the key to verify signatures. Available for RSA keys.
UsePrivate	Indicates that the group can use the private portion of the key to decrypt data. Available for RSA keys.
UsePublic	Indicates that the group can use the public portion of the key to encrypt data. Available for RSA keys.
CustomAttributeList	Specifies the list of custom attributes. This element can contain multiple CustomerAttribute elements. This element is optional.
CustomAttribute	When a custom attribute is present, this element contains one Name and one Value element.
Name	Indicates the name of the custom attribute.
Type	Data type of Custom Attribute. Can be one of the following types: • String • Integer • Long Integer • Big Integer • Enumeration • Boolean • Byte String • Date/Time (default format: "yyyy-mm-dd hr:mm:ss") • Interval NOTE: If `<Type>` is not specified, then String is selected as the default data-type for `<Value>`.
Value	Specifies the value of the attribute. This value must be base64 encoded, and input is considered as text. If your original data contains non-printable characters, convert the original data to hex values, and then convert the hex values to base64.
KeySize	Specifies the key size. If you do not specify a key size by including the KeySize element, the server uses the default key size for the algorithm, listed in bold below. The available key sizes are: • AES - 128, 256,192 • DESede - 112, 168 • HmacSHA1 - variable, 160 • HmacSHA1-128 and 25 • HmacSHA256-128/192/256/512 • HmacSHA384-192/288/384 • HmacSHA512-256/384/512 • RSA-4096 • RSA - 512, 1024, 2048 • EC-secp224k1-225 • EC-secp224r1-224 • EC-secp256k1-256 • EC-secp384r1-384 • EC-secp521r1-521 • EC-prime256v1-256 • EC-brainpoolP224r1-224 • EC-brainpoolP224t1-224 • EC-brainpoolP256r1-256 • EC-brainpoolP256t1-256 • EC-brainpoolP384r1-384 • EC-brainpoolP384t1-384 • EC-brainpoolP512r1-512 • EC-brainpoolP512t1-512
WrapAlgorithm	This is an optional tag. Valid value: HKDF NOTE: This functionality can only be used for AES-Unwrap.The key is derived from HKDF parameters.
HashAlgorithm	This is an optional tag. Valid values: • SHA1 • SHA224 • SHA256 • SHA384 • SHA512
Salt	This is an optional tag. Random HEX bytes of any length
Info	This is an optional tag. Random HEX bytes of any length
OkmLen	This is an optional tag. The desired OKM length in integer
WrapKeyName	This is an optional tag. Key name to be used as unwrapping key. • If it is an AES key, it does AES Unwrap. • If it is a RSA key, it does RSA Unwrap.
Padded	This is an optional tag. • If specified, AES-UNWRAP padding is performed. (RFC 5649) • Else, AES-UNWRAP is performed. (RFC 3394)
WrapFormat	This is an optional tag. Applicable for RSA Unwrap.The supported wrap formats are PKCS1v1.5 (default) and for the PKCS1v2.1 implementation formats are: • PKCS1v2.1/RSAOAEP-SHA1 • PKCS1v2.1/RSAOAEP-SHA256 • PKCS1v2.1/RSAOAEP-SHA384 • PKCS1v2.1/RSAOAEP-SHA512

KeyVersionImportRequest

Import version of a NAE versioned key.

<KeyVersionImportRequest> 
    <ID>...</ID> 
    <KeyName>...</KeyName> 
    <KeyVersionState>...</KeyVersionState>  # optional
    <KeyVersionData>...</KeyVersionData>
</KeyVersionImportRequest>

Example

<KeyVersionImportRequest>
    <ID>001</ID>
    <KeyName>aes-key</KeyName>
    <KeyVersionState>Active</KeyVersionState>
    <KeyVersionData>0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20</KeyVersionData>
</KeyVersionImportRequest>

Element	Description
ID	Contains the user-specified request ID.
KeyName	The name of the key.
KeyVersionState	The desired state of the new key version. Valid values are: • Pre-Active • Active • Restricted • Retired If you do not include this tag, the new key version is `Active` by default.
KeyVersionData	Contains the actual key being imported for the new version of the key.

KeyVersionImportResponse

Server response to a KeyVersionImportResponse

<KeyVersionImportResponse>
    <ID>001</ID>
    <Success>true</Success>
    <KeyName>aes-key</KeyName>
    <KeyVersion>2</KeyVersion>
    <Fingerprint>4C9B68754CC4C6A5</Fingerprint>
</KeyVersionImportResponse>

Element	Description
ID	Contains the user-specified request ID.
KeyName	Contains the name of the key.
KeyVersion	Contains the current key version.
Fingerprint	Contains the fingerprint of the versioned key.

KeyExportRequest

Export a key. If key wrapping is used, all exported versions are wrapped with the same key and algorithm parameters.

<KeyExportRequest>
    <ID>...</ID>
    <KeyName>...</KeyName>                  # optional
    <KeyAlias>...</KeyAlias>                # optional
    <KeyVersion>...</KeyVersion>                    # optional
    <Format>...</Format>                    # optional
    <Password>...</Password>                        # optional
    <WrapPublicKey>...</WrapPublicKey>                  # optional
    <PBEParameters>...</PBEParameters>              # optional
    <IV>...</IV>                                # optional
    <AllVersions/>                              # optional
    <WrapFormat>....</WrapFormat>                   # optional
    <Algorithm>.….</Algorithm>                          # optional
    <WrapSymmetricKeyName>….</WrapSymmetricKeyName>         # optional
    <HashAlgorithm>...</HashAlgorithm>          # optional
    <Salt>...</Salt>                    # optional
    <Info>...</info>                    # optional
    <OkmLen>...</OkmLen>                    # optional
 </KeyExportRequest>

Element	Description
ID	Contains the user-specified request ID.
KeyName	The KeyName child element specifies which key the server should export.
KeyAlias	Defines the alias name of the key. It's mandatory for KeyExportRequest element to include either the KeyName child element or the KeyAlias child element.
KeyVersion	Indicates a specific key version. To retrieve all versions of a versioned key, use AllVersions.
Format	The requested format of the exported key. Valid values are: • PEM-PKCS#1 : Private key is exported in PKCS#1 format, public key pkcs#1 by default • PEM-PKCS#8: Private key is exported in PKCS#8 format, public key pkcs#1 by default (for ECC, public key SEC1 by default). If specified with wrapping, the PEM encoding of key will be wrapped. • DER-PKCS#8: Only valid with wrapping. If specified, the DER encoding of key will be wrapped. • PKCS#12 (Used for exporting certificates) • PEM-PKCS#6 (used for extended certificates , so private keys can not be exported) • PEM-PKCS#1-PKCS#8: Public key is exported in PKCS#1 and Private key is exported in PKCS#8 format • PEM-PKCS#6-PKCS#1: Public key is exported in PKCS#6 and Private key is exported in PKCS#1 format • PEM-PKCS#6-PKCS#8: Public key is exported in PKCS#6 and Private key is exported in PKCS#8 format • PEM-SEC1: default format for both public and private key, for ECC
Password	The password (in base 64) used to encrypt the exported key. This element is only used (and is required) when exporting asymmetric keys in PKCS#12 format.
WrapPublicKey	The RSA public key that will be used to wrap (encrypt) the key specified in the KeyName element.
PBEParameters	Click here for detailed description of PBE parameters.
AllVersions	Indicates that the request is to export all versions of a versioned key, regardless of their state. To retrieve a specific version, use KeyVersion.
WrapFormat	The supported wrap formats are PKCS1v1.5 (default) and for the PKCS1v2.1 implementation formats are: • PKCS1v2.1/RSAOAEP-SHA1 • PKCS1v2.1/RSAOAEP-SHA256 • PKCS1v2.1/RSAOAEP-SHA384 • PKCS1v2.1/RSAOAEP-SHA512
Algorithm	The algorithm used for wrapping. Valid values are: • PBE: For password based encryption • AES-WRAP: This standard is followed when AES is used as wrap algorithm. AES belongs to NIST approved KeyWrap. For more information visit: https://tools.ietf.org/html/rfc3394#section-1 • HKDF NOTE: AES-WRAP supports wrapping of all the symmetric keys and private asymmetric keys. While wrapping asymmetric keys, AES-256 keys are used and the Alternative Initial Value (AIV) is used as a default value mentioned in RFC 5649. For more information visit: https://tools.ietf.org/html/rfc5649
WrapSymmetricKeyName	This is an optional tag. The AES key that will be used to wrap the key specified in the KeyName element.
HashAlgorithm	This is an optional tag. Possible HashAlgorithm valid values: • SHA1 • SHA224 • SHA256 • SHA384 • SHA512
Salt	This is an optional tag. Random HEX bytes of any length.
Info	This is an optional tag. Random HEX bytes of any length.
OkmLen	This is an optional tag. The desired OKM length in integer.
Padded	This is an optional tag. • If specified, AES-WRAP padding is performed. (RFC 5649) • Else, AES-WRAP is performed. (RFC 3394)

The Password Based Encryption (PBE) is used to wrap/unwrap symmetric keys, private asymmetric keys, and certificates. The below table describes the PBE parameters.

Element	Description
HashAlgorithm	Possible values: • sha1 • sha256 • sha224 • sha384 • sha512 • sha512/224 • sha512/256 • sha3-224 • sha3-256 • sha3-384 • sha3-512
Password	Base password to generate derive keys. It cannot be used in conjunction with `passwordidentifier`. Password must be in range of 8 bytes to 128 bytes.
PasswordIdentifier	Secret password identifier for password. It cannot be used in conjunction with `password`.
PasswordIdentifierType	Specifies the type of the Password Identifier. If not set then default value is name. Options: • id • name • slug
Iteration	Iteration count increase the cost of producing keys from a password. Iteration must be in range of 1 to 1,00,00,000.
DkLen	Specifies the length of the derived key in octets. The `dklen` must be in the range of 14 bytes to 512 bytes.
Salt	A Hex encoded string. The `Salt` must be in range of 16 bytes to 512 bytes. Note: If salt is not provided, it is generated internally and will be used in the export response.
Purpose	Specifies the user defined purpose. If specified, it is prefixed to `Salt`. The `Purpose` must not be greater than 128 bytes.

KeyExportResponse

Server response to a KeyExportRequest.

<KeyExportResponse>
<ID>...</ID>
<Success>true</Success>
<KeyName>...</KeyName>
<KeyExportDataList>...</KeyExportDataList>
<KeyExportData>
<KeyVersion>...</KeyVersion> # only for versioned keys
<KeyData>...</KeyData>
<Fingerprint>...</Fingerprint>
</KeyExportData>
</KeyExportData>
</KeyExportResponse>

Element	Description
ID	Contains the user-specified request ID.
Success	Indicates if the operation was successful. true indicates success. false indicates failure. When the operation is successful, the response element will contain the elements described below. When the operation fails, the response element contains the FatalError and ErrorString elements to illustrate why the failure occurred and help you troubleshoot. For a list of possible error IDs and strings, see Error Messages.
KeyExportDataList	Contains the KeyExportData elements.
KeyExportData	Contains the key version (for versioned keys), key data, and fingerprint. There is one element for each exported key version.
KeyVersion	Contains the version of the key (only used for versioned keys).
KeyData	Contains the key data.
Fingerprint	Contains the fingerprint of the key.

Export a Key

In the example below, the client exports key_a using the KeyExportRequest element.

<KeyExportRequest>
<ID>9</ID>
<KeyName>key_a</KeyName> 
</KeyExportRequest>
<KeyExportResponse>
<ID>9</ID>
<Success>true</Success>
<KeyName>key_a</KeyName>
<KeyData>58BF7737F38B24A0BD1BD1FB9B88C7B25F0F2C5AB1D3CF6D9B90F031E2AE512F</KeyData>
<Fingerprint>C0698613D81AC601</Fingerprint>
</KeyExportResponse>

Export and Delete a Versioned Key

In the example below, the client exports and deletes a versioned key.

<KeyExportRequest>
<ID>17</ID>
<KeyName>aes-12v</KeyName>
</KeyExportRequest>
<KeyExportResponse>
<ID>17</ID>
<Success>true</Success>
<KeyName>aes-12v</KeyName>
<KeyExportDataList>
<KeyExportData>
<KeyVersion>2</KeyVersion>
<KeyData>A9BAA72AA124618A2C740BCEC433857EBB10763FB7A98C48</KeyData>
<Fingerprint>278D9810FBD7F411</Fingerprint>
</KeyExportData>
</KeyExportDataList>
</KeyExportResponse>
<KeyDelRequest>
<ID>18</ID>
<KeyName>aes-12v</KeyName>
</KeyDelRequest>
<KeyDelResponse>
<ID>18</ID>
<Success>true</Success>
<Fingerprint>278D9810FBD7F411</Fingerprint>
<KeyName>aes-12v</KeyName>
</KeyDelResponse>

Export a Key with PKCS1v2.1/RSAOAEP-SHA512 Padding

In the example below, the client exports key with PKCS1v2.1/RSAOAEP-SHA512 padding.

<KeyExportRequest>
<ID>123</ID>
<KeyName>hmac_1key</KeyName>
<WrapPublicKey>-----BEGIN RSA PUBLIC KEY-----
MIICCgKCAgEAvahj3FLByCbctHWoTp8tbHZmIyWRbqIZW+qeh6l8YjBd3dt/5ogq
hLGi4Vyj+b8YV805w7YiObm4exhQnYeiwlR89pKHdjY2M8W3lP6abonOe3dGHjRz
snFwEkMFBglEYnymovk2XPztyZuxXfSGBlFdmVzzdW8ZrrfsqQtHlBTd/iCVj5GV
HZOyspuwezF8nKMJlOz85F+bKc5pivrlqbtXU83tC8fQLVrwd1q1ADcd2YdJvHFV
khpbL+Z/AqMr+mKSuqDbBQNqSOdpSizNKxrck0tTYclhJCPG1xityskVZ1TRktfR
xKCDeoGtZ67Thfhg0mZ7d8/Nadm+TExJ0VqBPObPQJzlVPj8ZkYuUTXcPG+bPgvJ
aArANwpmzWnKUMNrXoxN1IlmKojh1ea5gZQ0xMzgzi3G29BJTkrsO9k6RypKj47G
832zU1ifFh4NuvSLqWMPiav8gMFlkckMqXCe/pImDMa3ByfGuPKKhox7mEVcMOq0
XhwvAAq5Iaw1j5BOhSlm2/J0zEjoMDHC2ZFwXPvZOqMwph8v/4adQAnJTe2DNFUL
+bKop6XIKm4zKtQc/KKFKkpigujnrb21nKNSAKhg+V+Vgn0I4kL4I0wgmjhcJUOh
/MCWLS/Jb6ZiSgztzrnz11RQ4+rPxcOXcbqcJnzSrqndOBNk21fhNJ8CAwEAAQ==
-----END RSA PUBLIC KEY-----
</WrapPublicKey>
<WrapFormat>PKCS1v2.1/RSAOAEP-SHA512</WrapFormat>
</KeyExportRequest>
<KeyExportResponse>
<ID>123</ID>
<Success>true</Success>
<KeyName>hmac_1key</KeyName>
<KeyExportDataList>
<KeyExportData>
<KeyData>eP4ljZvANh53Huso6Gr8ZGnGwb7N9JkTJOzkt012DfziYeIg7e19/P7
FVeVK3ZWC7QaizjybV80mrl7uu9USkR/N0mvxTpHiT4POQcqUK5ul3yTg4YCHpye
CAnFHc28VmH2Mvh174GL1XYy/SqzozVWwHxLGUf2UaLZyW7XPay6xvAfwYspNGod
uhR48r3MTU4wbi4AdNka0TBHN6+Jbmb+9Wj1vnd3F4OvKBPYmn/BLyNhLghlMHdx
Xba7dFFD/m2TTdKBMGAN67CM5Poj/TindQd3bdeVvAL3E9s8Ll9SnNDgBm4AC6EM
SXjB50K0bQZPOaMQ6Pc8xWyE9jTIoO4LXv3vbdXnqxd9Vof6DwSy4tvt8NLRbI/f
Rzd6OP747t66oBWQ4t3TscisMSr6uU8uzpGsxbfGae9nn7F81uvheyPbkqHVQ9JM
VKH6OMbwLXxIYuwdc5gSNoU41pY5q7IoXxd5bNdYo8kGEzbBitUN6hq5Y3d5msGc
49unlQq1rHxXgivUdgGfJCWYvfct51rJBvhuD2L29vANrF8pI7epOvqXpU/QQwoa
5knBXX3qpY2HmCKHlmCj1F4tUzc+WfrVB9fBaJHHU/tKMp2ehaIv4Yz1U+rWwJGM
dEwlUS+cc3Bp5nrI0WxE5L7ZJD1aooxhcK9O4jSWXcOOH7JETlm0=</KeyData>
<Fingerprint>C2D1AF00844F5799</Fingerprint>
</KeyExportData>
</KeyExportDataList>
</KeyExportResponse>

Export a Key using Password Based Encryption(PBE) Parameters

In the example below, the client exports key with PBE parameters.

<KeyExportRequest>
    <ID>001</ID>
    <KeyName>test-key</KeyName>
    <Algorithm>PBE</Algorithm>
    <PBEParameters>
      <HashAlgorithm>sha256</HashAlgorithm> 
      <Password>PBEPassword</Password> 
      <Iteration>10000</Iteration> 
      <DkLen>32</DkLen>  
      <Salt>92280e35fa929ec28fb140f2862c5a32</Salt> 
      <Purpose>PBEWrap</Purpose> 
    </PBEParameters>
</KeyExportRequest>

Element	Description
ID	Contains the user-specified request ID.
KeyName	Specifies which key the server should export.
Algorithm	Contains a standard identifier string for a cryptographic algorithm supported by the server. The length of the Algorithm string should not exceed 256 characters. The algorithm can be any of the following: • PBE • AES • DESede • ARIA • HmacSHA1 • HmacSHA256 • HmacSHA384 • HmacSHA512 • RSA • SEED • RSA-Certificate • EC-Certificate (represents ECC)
HashAlgorithm	Possible values: • sha256 • sha1 • sha224 • sha384 • sha512 • sha512/224 • sha512/256 • sha3-224 • "sha3-256 • sha3-384 • sha3-512
Password	Base password to generate derive keys. It cannot be used in conjunction with `passwordidentifier`. Password must be in range of 8 bytes to 128 bytes.
PasswordIdentifier	Secret password identifier for password. It cannot be used in conjunction with `password`.
PasswordIdentifierType	Specifies the type of the Password Identifier. If not set then default value is name. Options: • id • name • slug
Iteration	Iteration count increase the cost of producing keys from a password. Iteration must be in range of 1 to 1,00,00,000.
DkLen	Specifies the length of the derived key in octets. The `dklen` must be in the range of 14 bytes to 512 bytes.
Salt	A Hex encoded string. The `pbeSalt` must be in range of 16 bytes to 512 bytes. Note: If salt is not provided, it is generated internally and will be used in the export response.
Purpose	Specifies the user defined purpose. If specified, it is prefixed to `pbeSalt`. The `pbePurpose` must not be greater than 128 bytes.

Export an AES Key Wrapped with Another AES Key

In the example below, the client exports an AES 128 key wrapped with AES_256 key.

<KeyExportRequest>
<ID>test2</ID>
<KeyName>aes128key</KeyName>
<Algorithm>AES-WRAP</Algorithm>
<WrapSymmetricKeyName>aes256key</WrapSymmetricKeyName>
</KeyExportRequest>
<KeyExportResponse>
<ID>test2</ID>
<Success>true</Success>
<KeyName>a</KeyName>
<KeyExportDataList><KeyExportData>
<KeyData>I8/tuzsEwawHFTIblD9jJKyZrGlvcvhp</KeyData>
<Fingerprint>DB7B3327EE35316E</Fingerprint>
</KeyExportData></KeyExportDataList>
</KeyExportResponse>

PublicKeyExportRequest

Export the public portion of an RSA key.

<PublicKeyExportRequest>
<ID>...</ID>
<KeyName>...</KeyName>
<KeyVersion>...</KeyVersion> # optional
<AllVersions/> # optional
</PublicKeyExportRequest>

Element	Description
ID	Contains the user-specified request ID.
KeyName	Specifies which key the server should export.
PublicKeyExportResponse	Server response to a PublicKeyExportRequest

<PublicKeyExportResponse>
<ID>...</ID>
<Success>true</Success>
<KeyName>...</KeyName>
<KeyExportDataList>
<KeyExportData>
<KeyVersion>...</KeyVersion>
<KeyData>...</KeyData>
<Fingerprint>...</Fingerprint>
</KeyExportData>
</KeyExportDataList>
</PublicKeyExportResponse>

Element	Description
ID	Contains the user-specified request ID.
Success	Indicates if the operation was successful. true indicates success. false indicates failure. When the operation is successful, the response element will contain the KeyName, KeyData, and Fingerprint elements described below. When the operation fails, the response element contains the FatalError and ErrorString elements to illustrate why the failure occurred and help you troubleshoot. For a list of possible error IDs and strings, see Error Messages.
KeyName	Contains the key name.
KeyData	Contains the key data.
Fingerprint	Contains the fingerprint of the key.

Export an RSA Key

In the example below, the client exports an RSA public key.

<PublicKeyExportRequest>
<ID>11</ID>
<KeyName>key_b</KeyName> 
</PublicKeyExportRequest>
<PublicKeyExportResponse>
<ID>11</ID>
<Success>true</Success>
<KeyName>key_b</KeyName>
<KeyData>-----BEGIN RSA PUBLIC KEY-----
MEgCQQC7+Th9U8akLjyFLxSQnvSbVOYU/0pLWLGZpagnKZFAbE7qyTXKshH5Ku fY+gb5fpA7/bMEGYW9CNp9veuv0oq1AgMBAAE=
-----END RSA PUBLIC KEY-----
</KeyData>
<Fingerprint>C0E01D79C0F29C14</Fingerprint>
</PublicKeyExportResponse>

Suggest A Change

Importing, Exporting, and Replicating Keys

KeyImportRequest

KeyImportResponse

Import a Key

Import a Key with Custom Attributes

Import a Key with External key-Ids

Import a Key using Password Based Encryption (PBE) Parameters

Import Certificate as a Managed Object using PKCS1

Import Certificate as a Managed Object using PKCS8

Import Certificate as a Managed Object using PKCS12

Import a Wrapped AES Key using RSA Unwrap with PKCS1v2.1/RSAOAEP-SHA512 Padding

Import a Wrapped RSA Key using AES Unwrap

KeyVersionImportRequest

KeyVersionImportResponse

KeyExportRequest

KeyExportResponse

Export a Key

Export and Delete a Versioned Key

Export a Key with PKCS1v2.1/RSAOAEP-SHA512 Padding

Export a Key using Password Based Encryption(PBE) Parameters

Export an AES Key Wrapped with Another AES Key

PublicKeyExportRequest

Export an RSA Key

On this page