Please Note:

Key Management Operations

The XML Interface accepts requests to:

Generate keys (see KeyGenRequest)
Generate new key versions (see KeyVersionGenRequest)
Modify key properties (see KeyModifyRequest)
Change the state of a key version (see KeyVersionModifyRequest)
Delete keys (see KeyDelRequest)
Get information about a specific key (see KeyInfoRequest)
Get the names of all keys available to the client (see KeyNamesRequest)
Get information about all keys available to the client (see KeyQueryRequest)
Copy a key's bytes and metadata (see KeyCloneRequest)

A cryptographic key is required to perform a cryptographic operation. The exact content and meaning of the key depends on the cryptographic operation.

Encryption and decryption operations expect following keys:
- DESede
- AES
- ARIA
- RSA
- EC
- SEED
Signature creation and verification operations expect RSA and EC keys.
MAC generation and verification operations expect HMAC keys.

KeyGenRequest

Creates a new key on the server.

<KeyGenRequest>
<ID>...</ID>
<KeyName>...</KeyName>             # optional
<KeySize>...</KeySize>                 # optional
<Aliases>                              # optional, supported for 6.3 and higher
    <Alias>
        <Name>...</Name>
        <Type>...</Type>
    </Alias>
    ...
</Aliases>
<RandomKey/>                                    # optional
<Algorithm>...</Algorithm>
   <CurveID>...</CurveID>                        # optional
   <DerivationAlgorithm>….</DerivationAlgorithm>   # optional
   <IkmKeyName>….</IkmKeyName>                     # optional
   <Salt>….</Salt>                                 # optional
   <Info>….</Info>                                 # optional
   <GenerateKeyID/>                         # optional, supported for 6.0 or higher
<VersionedKey/>                             # optional
<KeyVersionState>...</KeyVersionState>       # optional
<Exportable/>                               # optional
<Deletable/>                                # optional
<Owner>...</Owner>                          # optional
<Permissions>...</Permissions>              # optional
<KeyRotation>                               # optional, supported for 6.3 and higher 
    <Frequency>....</Frequency>       
</KeyRotation>
<CustomAttributeList>
<CustomAttribute>
    <Name>...</Name>
    <Type>...</Type>            # Optional, supported for 3.0, 6.1, and higher
    <Value>...</Value>
</CustomAttribute>
</CustomAttributeList>
</KeyGenRequest>

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. It is mandatory to include either `RandomKey` child element or the `KeyName` child element. The key name should not contain special characters such as angular brackets (`<`,`>`) and backslash (`\`).
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, 192, 256 • ARIA - 128, 192, 256 • DESede - 112, 168 • HmacSHA1 - variable (valid key sizes are multiples of 8 between 128 and 256), 160 • HmacSHA256 - 128, 192, 256, 512 • HmacSHA384 - 192, 288, 384 • HmacSHA512 - 256, 384, 512 • RSA - 512, 1024, 2048, 3072, 4096 • EC-224,225,256,384,512,521 • SEED - 128
Aliases	Specifies the list of Alias elements. The maximum allowed count is 20.
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 element.
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.
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 • ARIA • DESede • HmacSHA1 • HmacSHA256 • HmacSHA384 • HmacSHA512 • RSA • EC • SEED NOTE: CipherTrust Manager supports generation of the symmetric keys (Such as: AES, ARIA, DESede, HmacSHA1, HmacSHA256, HmacSHA384, HmacSHA512, SEED) when DerivationAlgorithm is HKDF.
VersionedKey	Indicates that this is a versioned key. Using KeyGenRequest to create a version key automatically creates the first version of the key. To create subsequent versions, use KeyVersionGenRequest.
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.
Exportable	Indicates that the owner of the key can export it 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 owner of the key can delete it 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.
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. Only present and applicable for symmetric keys.
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 and AES keys.
MACV	Indicates that the group can use the key to verify MACs. Available for HMAC and AES keys.
SIGN	Indicates that the group can use the key to create signatures. Available for RSA and EC keys.
SIGNV	Indicates that the group can use the key to verify signatures. Available for RSA and EC keys.
UsePrivate	Indicates that the group can use the private portion of the key to decrypt data. Available for RSA and EC keys.
UsePublic	Indicates that the group can use the public portion of the key to encrypt data. Available for RSA and EC 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 (format: "yyyy-mm-dd hr:mm:ss") • Interval NOTE: If is not specified, then data-type of for the new custom attribute is selected as String.
Value	Specifies the value of the attribute. This value must be base64 encoded, and the 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.
Curve ID	Indicates the named curve id for EC algorithm This is a mandatory tag if the value of algorithm is EC. Supported values for Curveid: • secp224k1 • secp224r1 • secp256k1 • secp384r1 • secp521r1 • prime256v1 • brainpoolP224r1 • brainpoolP224t1 • brainpoolP256r1 • brainpoolP256t1 • brainpoolP384r1 • brainpoolP384t1 • brainpoolP512r1 • brainpoolP512t1
DerivationAlgorithm	HKDF/ Possible values for hashAlgo are: • HKDF/SHA1 • HKDF/SHA224 • HKDF/SHA256 • HKDF/SHA384 • HKDF/SHA512 NOTE: If no hashAlgo is given, SHA256 is used. Example HKDF.
IkmKeyName	Any symmetric key existing on the KeySecure. Mandatory while using HKDF key generation.
Salt	Random HEX bytes of any length. Optional for HKDF key generation.
Info	Random HEX bytes of any length. Optional for HKDF key generation.
GenerateKeyID	Generates key's keyId identifier of type long. This element is optional.

Warning

For non-versioned keys created on NAE interface, do not create a new version from any other interface such as GUI, REST, or KMIP. This can lead to data corruption on the NAE interface.

KeyGenResponse

Server response to a KeyGenResponse.

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

Note

KeyGenRequest creates following key-IDs: uuid, muid, and keyid for legacy DSM. keyid is only created when GenerateKeyID tag is mentioned and XML protocol version in 6.0 or higher. You can also use these key-IDs to search for keys using KeyNamesRequest. For more details regarding its usage, refer to KeyImportRequest.

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, 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.
Fingerprint	Contains the fingerprint of the generated key.
KeyName	Contains the name of the key.

Generating an AES Key

In the example below, the client creates an AES key named key_a.

<KeyGenRequest>
    <ID>3</ID>
    <KeyName>key_a</KeyName>
    <KeySize>256</KeySize>
    <Algorithm>AES</Algorithm>
    <Exportable/>
    <Deletable/>
</KeyGenRequest>
<KeyGenResponse>
    <ID>3</ID>
    <Success>true</Success>
    <Fingerprint>C0698613D81AC601</Fingerprint>
    <KeyName>key_a</KeyName>
</KeyGenResponse>

In the example below, the client creates an AES key named key_b with a String type CustomAttribute.

<KeyGenRequest>
    <ID>4</ID>
    <KeyName>key_b</KeyName>
    <KeySize>256</KeySize>
    <Algorithm>AES</Algorithm>
    <Exportable/>
    <Deletable/>
    <CustomAttributeList>
    <CustomAttribute>
    <Name>Key1</Name>
    <Type>String</Type>
    <Value>U3VyeWF3YW5zaGk=</Value>
    </CustomAttribute>
    <CustomAttribute>
    <Name>Key2</Name>
    <Type>Integer</Type>
    <Value>MjE0NzQ4MzY0Ng==</Value>
    </CustomAttribute>
    <CustomAttribute>
    <Name>Key3</Name>
    <Type>Boolean</Type>
    <Value>dHJ1ZQ==</Value>
    </CustomAttribute>
    <CustomAttribute>
    <Name>key4</Name>
    <Type>Date/Time</Type>
    <Value>MjAyMC0wMi0wNyAxMTozODo1OQ==</Value>
    </CustomAttribute>
    </CustomAttributeList>
</KeyGenRequest>
<KeyGenResponse>
    <ID>4</ID>
    <Success>true</Success>
    <Fingerprint>AFF129ACC98838D1</Fingerprint>
    <KeyName>key_b</KeyName>
</KeyGenResponse>

Generating an RSA Key

In the example below, the client creates an RSA key named key_b.

<KeyGenRequest>
    <ID>5</ID>
    <KeyName>key_b</KeyName>
    <KeySize>512</KeySize>
    <Algorithm>RSA</Algorithm>
    <Exportable/> 
</KeyGenRequest>
<KeyGenResponse>
    <ID>5</ID>
    <Success>true</Success>
    <Fingerprint>C0E01D79C0F29C14</Fingerprint>
    <KeyName>key_b</KeyName>
    </KeyGenResponse>
    Generating an EC Key
    <KeyGenRequest>
    <ID>1</ID>
    <KeyName>key_ecc</KeyName>                   
    <KeySize>224</KeySize>              
    <Algorithm>EC</Algorithm>
        <CurveID>secp224r1</CurveID>                                             
    <Exportable/>                    
    <Deletable/>                                 
    <CustomAttributeList>
    <CustomAttribute>
    <Name>key_name</Name>
    <Value>WVdKag==</Value>
    </CustomAttribute>
    </CustomAttributeList>
    </KeyGenRequest>
    <KeyGenResponse>
    <ID>1</ID>
    <Success>true</Success>
    <Fingerprint>92FCC3AB223A72B0</Fingerprint>
    <KeyName>key_ecc</KeyName>
</KeyGenResponse>

Generating an AES key using HKDF

In the example below, the client creates an AES key using HKDF key named derived256key.

<KeyGenRequest>
    <ID>5</ID>
    <KeyName>derived256key</KeyName>
    <KeySize>256</KeySize>
    <Algorithm>AES</Algorithm>
    <DerivationAlgorithm>HKDF/SHA384</DerivationAlgorithm>
    <IkmKeyName>aes256key</IkmKeyName>
    <Salt>ABCD</Salt>
    <Info>ABCD</Info>
</KeyGenRequest>
<KeyGenResponse>
    <ID>5</ID>
    <Success>true</Success>
    <Fingerprint>9F02D1C689BA020F</Fingerprint>
    <KeyName>derived256key</KeyName>
</KeyGenResponse>

Generating a Key and Setting Permissions

In the example below, the client creates a DESede key and sets encryption and decryption permissions for group1 and group2.

<KeyGenRequest>
    <ID>6</ID>
    <KeyName>key_c</KeyName>
    <Algorithm>DESede</Algorithm>
    <Permissions>
    <Group>group1</Group>
    <Encrypt/>
    <Group>group2</Group>
    <Encrypt/>
    <Decrypt/>
    </Permissions>
</KeyGenRequest>
<KeyGenResponse>
    <ID>6</ID>
    <Success>true</Success>
    <Fingerprint>2B5D754C65392AEC</Fingerprint>
    <KeyName>key_c</KeyName>
</KeyGenResponse>

Creating a New Versioned Key

In the example below, the client creates a new versioned key. This automatically creates version 1 of that key.

<KeyGenRequest>
    <ID>13</ID>
    <KeyName>aes-12v</KeyName>
    <KeySize>192</KeySize>
    <Algorithm>AES</Algorithm>
    <VersionedKey/>
    <Deletable/>
    <Exportable/>
</KeyGenRequest>
<KeyGenResponse>
    <ID>13</ID>
    <Success>true</Success>
    <Fingerprint>B13C56AC6BF2B5E1</Fingerprint>
    <KeyName>aes-12v</KeyName>
</KeyGenResponse>

KeyVersionGenRequest

Creates a new version of a versioned key. Sending this request for a non-versioned key is an error. KeyVersionGenRequest element has the following structure:

<KeyVersionGenRequest>
    <ID>...</ID>
    <KeyName>...</KeyName>
    <KeyVersionState>...</KeyVersionState> #optional
</KeyVersionGenRequest>

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.

KeyVersionGenResponse

Server response to a KeyVersionGenRequest.

<KeyVersionGenResponse>
    <ID>...</ID>
    <Success>true</Success>
    <KeyName>...</KeyName>
    <KeyVersion>...</KeyVersion>
    <Fingerprint>...</Fingerprint>
</KeyVersionGenResponse>

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 generated key.

Creating a New Version of a Versioned Key

In the example below, the client creates a new version of key aes-12v.

<KeyVersionGenRequest>
    <ID>14</ID>
    <KeyName>aes-12v</KeyName>
</KeyVersionGenRequest>
<KeyVersionGenResponse>
    <ID>14</ID>
    <Success>true</Success>
    <KeyName>aes-12v</KeyName>
    <KeyVersion>2</KeyVersion>
    <Fingerprint>278D9810FBD7F411</Fingerprint>
</KeyVersionGenResponse>

KeyModifyRequest

Modify a key's owner or add, update or remove custom attributes.

Use the KeyModifyRequest element to do one of the following:

Change the key owner using the Owner element.
Add or update custom attributes using the CustomAttributeList element and corresponding child elements.
Modify the key permissions.
Delete an existing custom attribute using the DeleteCustomAttribute element.

Delete single or multiple aliases using the Name element of the DeleteAlias element.

<KeyModifyRequest>
    <ID>...</ID>
    <KeyName>...</KeyName>
    <Aliases>                              # optional, supported for 6.3 and higher
        <Alias>
            <Name>...</Name>
            <Type>...</Type>
        </Alias>
        ...
    </Aliases>
    <DeleteAlias>
        <Name>...</Name>
        <Name>...</Name>
    </DeleteAlias>
    <KeyMUID>...</KeyMUID>              # to set muid if not set already        
    <ExternalKeyID>...</ExternalKeyID>   # to set keyId if not set already
    <Permissions>...</Permissions>          # optional
    <Owner>...</Owner>                   # include to change key owner
    <CustomAttributeList>            # include to add or update 
    <CustomAttribute>           # custom attributes
        <Name>...</Name>
        <Type>...</Type>        # Optional, supported for 3.0, 6.1, and higher
        <Value>...</Value>
    </CustomAttribute>
    ...
    </CustomAttributeList>
    <DeleteCustomAttribute>      # include to delete an existing
        <Name>...</Name>         # custom attribute
        <Name>...</Name>
    </DeleteCustomAttribute>
    <DeleteAllCustomAttributes/>    # include to delete all custom attributes
    <KeyRotation>                   # optional, supported for 6.3 and higher 
        <Frequency>....</Frequency>       
    </KeyRotation>
    <Exportable/>                   # optional
    <Deletable/>                    # optional
    <NonExportable/>                # optional
    <NonDeletable/>                 # optional
</KeyModifyRequest>

Element	Description
ID	Contains the user-specified request ID.
KeyName	Contains the name of the key to modify.
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 element.
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.
DeleteAlias	Contains the aliases that will be deleted. Deletes single or multiple aliases.
Name	Specifies the name of the alias to delete.
muid	Use this element to set a muid, if it is not already set. 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	Use this element to set a keyId, if it is not already set. keyId is a 32 bit DPM key identifier. It is specified in Long type format. For example: `<ExternalKeyID>9934567890</ExternalKeyID>`
Permissions	Specifies the key usage permissions granted to specific groups. This element is optional. When used, it overwrites the existing key permissions. Any previous permission settings that are not included in this modification request are erased. Thus, to make a change to a key's existing permissions, you must include the full list of permissions for all groups and modify the list by adding or removing groups and permission elements as needed. 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 functionality is only available to the key owner, so your application must authenticate as the owner of the key to modify its permissions. NOTE: This parameter will be updated in all versions of the key.
Owner	Contains the name of the new key owner. This element can only be used to change the name of the key owner. Only a key owner with User Administration Permission can change ownership.
CustomAttributeList	Contains the custom attributes that will be added or updated. Child elements are `CustomAttribute`, `Name`, `Type`, and `Value`. Values 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. NOTE: This parameter will be updated in all versions of the key.
CustomAttribute	When a custom attribute is present, this element contains one `Name`, one `Type`, and one `Value` element. NOTE: This parameter will be updated in all versions of the key.
Name	Indicates the name of the custom attribute.
Type	Data type of the Custom Attribute. It is an optional element and can be one of the following types: • String • Integer • Long Integer • Big Integer • Enumeration • Boolean • Byte String • Date/Time • Interval NOTE: • Data-type of <Value> for a new custom attribute is selected as String. • Data-type for <Value> remains the same for an existing custom attribute and can not be changed.
Value	Specifies the value of the attribute. This value must be base64 encoded, and the 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.
DeleteCustomAttribute	Deletes the Custom Attributes listed in the `Name` element. NOTE: This parameter will be updated in all versions of the key.
DeleteAllCustomAttributes	Deletes all the Custom Attributes of the key (`Name` and `Value` elements are lost). NOTE: This parameter will be updated in all versions of the key.
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.
Exportable	Indicates that the owner of the key can export it 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 owner of the key can delete it from the server using a client request. Keys created on the server are not, by default, deletable. This element is optional.
NonExportable	Revokes the optional Exportable element.
NonDeletable	Revokes the optional Deletable element.

KeyModifyResponse

Server response to a KeyModifyRequest.

<KeyModifyResponse>
    <ID>...</ID>
    <Success>true</Success>
</KeyModifyResponse>

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 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.

Deleting a Custom Attribute

<KeyModifyRequest>
  <ID>XMLID60</ID>
  <KeyName>des-56</KeyName>
  <DeleteCustomAttribute>
    <Name>name1</Name>
  </DeleteCustomAttribute>
</KeyModifyRequest>
<KeyModifyResponse>
  <ID>XMLID60</ID>
  <Success>true</Success>
</KeyModifyResponse>

Changing the Key Owner

<KeyModifyRequest>
  <ID>XMLID126</ID>
  <KeyName>aes-256</KeyName>
  <Owner>john</Owner>
</KeyModifyRequest>
<KeyModifyResponse>
  <ID>XMLID126</ID>
  <Success>true</Success>
</KeyModifyResponse>

Changing Key Permissions for a Group

<KeyModifyRequest>
  <ID>XMLID129</ID>
  <KeyName>aes-256</KeyName>
  <Permissions>
    <Group>GroupOne</Group>
      <Encrypt/>
      <Decrypt/>
    <Group>GroupTwo</Group>
      <Encrypt/>
      <Decrypt/>
  </Permissions>
</KeyModifyRequest>
<KeyModifyResponse>
  <ID>XMLID129</ID>
  <Success>true</Success>
</KeyModifyResponse>

The request above grants encrypt and decrypt permissions to GroupOne and GroupTwo. The example below then erases decrypt permissions for GroupTwo by omitting the element.

<KeyModifyRequest>
  <ID>XMLID129</ID>
  <KeyName>aes-256</KeyName>
  <Permissions>
    <Group>GroupOne</Group>
      <Encrypt/>
      <Decrypt/>
    <Group>GroupTwo</Group>
      <Encrypt/>
  </Permissions>
</KeyModifyRequest>
<KeyModifyResponse>
  <ID>XMLID129</ID>
  <Success>true</Success>
</KeyModifyResponse>

To remove all permissions for GroupOne, simply omit that group from the request:

<KeyModifyRequest>
  <ID>XMLID129</ID>
  <KeyName>aes-256</KeyName>
  <Permissions>
    <Group>GroupTwo</Group>
      <Encrypt/>
  </Permissions>
</KeyModifyRequest>
<KeyModifyResponse>
  <ID>XMLID129</ID>
  <Success>true</Success>
</KeyModifyResponse>

Setting External IDs of the key

<KeyModifyRequest>
    <ID>123</ID>
    <KeyName>vm_demo_k3</KeyName>
    <KeyMUID>ad4a816b-2500-4346-a815-a949adea32376d2c89a7-5830-476a-b5d0-b2edaca55d7e</KeyMUID>
    <ExternalKeyID>989954321</ExternalKeyID>
</KeyModifyRequest>
<KeyModifyResponse>
    <ID>123</ID>
    <Success>true</Success>
</KeyModifyResponse>

KeyVersionModifyRequest

Modifies the state of a key version. You can also add/modify/delete the custom attribute in a key version.

<KeyVersionModifyRequest>
    <ID>...</ID>
    <KeyName>...</KeyName>
    <KeyVersion>...</KeyVersion>
    <KeyVersionState>...</KeyVersionState>
    <CustomAttributeList>            # include to add or update 
    <CustomAttribute>           # custom attributes
        <Name>...</Name>
        <Type>...</Type>        # supported for 3.0, 6.1, and higher
        <Value>...</Value>
    </CustomAttribute>
    ...
    </CustomAttributeList>
    <DeleteCustomAttribute>      # include to delete an existing
        <Name>...</Name>         # custom attribute
        <Name>...</Name>
    </DeleteCustomAttribute>
    <DeleteAllCustomAttributes/>    # include to delete all custom attributes
</KeyVersionModifyRequest>

Element	Description
ID	Contains the user-specified request ID.
KeyName	Contains the name of the key to modify.
KeyVersion	Contains the version of the key to modify.
KeyVersion State	Contains the new key state. Valid values are: • Active • Restricted • Retired
CustomAttributeList	Contains the custom attributes that will be added or updated. Child elements are `CustomAttribute`, `Name`, `Type`, and `Value`. Values 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.
CustomAttribute	When a custom attribute is present, this element contains one `Name`, one `Type`, and one `Value` element.
Name	Indicates the name of the custom attribute.
Type	Data type of the Custom Attribute. It can be one of the following types: • String • Integer • Long Integer • Big Integer • Enumeration • Boolean • Byte String • Date/Time • Interval NOTE: • Data-type of <Value> for a new custom attribute is selected as String. • Data-type for <Value> remains the same for an existing custom attribute and can not be changed.
Value	Specifies the value of the attribute. This value must be base64 encoded, and the 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.
DeleteCustomAttribute	Deletes the Custom Attributes listed in the `Name` element.
DeleteAllCustomAttributes	Deletes all the Custom Attributes of the key (`Name` and `Value` elements are lost).

KeyVersionModifyResponse

Server response to a KeyVersionModifyRequest.

<KeyVersionModifyResponse>
    <ID>...</ID>
    <Success>true</Success>
    <KeyName>...</KeyName>
</KeyVersionModifyResponse>

Element	Description
KeyName	Contains the name of the key that was modified.

Modifying the State of a Key Version

In the example below, the client restricts the use of version 1 of aes-12v.

<KeyVersionModifyRequest>
    <ID>15</ID>
    <KeyName>aes-12v</KeyName>
    <KeyVersion>1</KeyVersion>
    <KeyVersionState>Restricted</KeyVersionState>
</KeyVersionModifyRequest>
<KeyVersionModifyResponse>
    <ID>15</ID>
    <Success>true</Success>
    <KeyName>aes-12v</KeyName>
</KeyVersionModifyResponse>

KeyDelRequest

Deletes a key.

<KeyDelRequest>
    <ID>...</ID>
    <KeyName>...</KeyName>
</KeyDelRequest>

Element	Description
ID	Contains the user-specified request ID.
KeyName	Contains the name of the key to delete. The key must have been marked deletable when it was created. Deletable global keys can be deleted by any user. Deletable non-global keys can only be deleted by their owner.

KeyDelResponse

Server response to a KeyDelRequest.

This element has the following structure:

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

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.
Fingerprint	Contains the fingerprint of the generated key.
KeyName	Contains the name of the deleted key.

Deleting a Key

In the example below, the client deletes key_a.

<KeyDelRequest>
    <ID>12</ID> 
    <KeyName>key_a</KeyName> 
    </KeyDelRequest>
<KeyDelResponse>
    <ID>12</ID>
    <Success>true</Success>
    <Fingerprint>C0698613D81AC601</Fingerprint>
    <KeyName>key_a</KeyName>
</KeyDelResponse>

KeyInfoRequest

Returns information about a specific key.

The server returns information such as the algorithms that can be used with the key, the size of the key, whether the key is exportable and/or deletable, and the permissions that the client has for the specified key (encrypt, decrypt, etc.). In addition, the server returns the fingerprint of the key. If the request is for information about the public key from a certificate, then the server omits the fingerprint information in the response.

<KeyInfoRequest>
    <ID>...</ID>
    <KeyName>...</KeyName>
    <IDType>...</IDType>            #optional, supported for 6.2 or higher
    <AllVersions/>                  #optional
    <KeyVersion>...</KeyVersion>    #optional
    <GetPermissions/>               #optional
    <GetKeyIDs/>                    #optional, supported for 6.0 or higher
</KeyInfoRequest>

Element	Description
ID	Contains the user-specified request ID.
KeyName	Contains the identifier of the key.
IDType	Identifier in KeyName is treated according to the value specified in this tag. Possible values are: • Name (Default) • UUID • MUID • KeyID • Alias NOTE: KeyVersion and AllVersions parameters are only supported with Name as the IDType. Specifying any other IDType for these two parameters will result in error.
GetKeyIDs	Displays all the indentifiers of the key: uuid, muid, and keyid. This element is optional.
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.
GetPermissions	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.
KeyVersion	Contains the version of the key (only used for versioned keys).

KeyInfoResponse

Server response to a KeyInfoRequest.

<KeyInfoResponse>
<ID>...</ID> 
<Success>true</Success>
<KeyName>...</KeyName>
<Aliases>                    # optional, supported for 6.5 and higher
    <Alias>
        <Name>...</Name>
        <Type>...</Type>
    </Alias>
    ...
</Aliases>
<CurveID>...</CurveID>      # optional, only in case of EC keys
<Algorithms>
<Algorithm>...</Algorithm>
<Algorithm>...</Algorithm>
...
</Algorithms>
<KeySize>...</KeySize>  
<Exportable/>           # These elements are only present if the 
<Deletable/>            # operation is available
<Encrypt/>          # 
<Decrypt/>          # 
<Sign/>             # 
<SignV/>            # 
<MAC/>              # 
<MACV/>             # 
<UsePublic/>            # 
<UsePrivate/>           # 
<VersionedKey/>              # These elements are only present 
<NumKeyVersions>...</NumKeyVersions>     # for versioned keys
<NumActiveVersions>...</NumActiveVersions>   #
<NumRestrictedVersions>...</NumRestrictedVersions> #
<NumRetiredVersions>...</NumRetiredVersions> #
<NumWipedVersions>...</NumWipedVersions> #
<CustomAttributeList>       # Present only when there are multiple Custom Attributes 
<CustomAttribute>   
    <Name>...</Name>
    <Type>...</Type>        # Optional, supported for 3.0, 6.1, and higher       
    <Value>...</Value>      # Optional
</CustomAttribute>
</CustomAttributeList>
<KeyRotation>               # if rotation frequency is non zero
   <Frequency>...</Frequency>       
</KeyRotation>
<KeyInfoDataList>
<KeyInfoData>
<KeyVersion>...</KeyVersion> # optional
<KeyVersionState>...</KeyVersionState> # optional
<KeyState>...</KeyState> # Optional, supported for 6.9 and higher
<KeyCreationDate>...</KeyCreationDate>
<Fingerprint>...</Fingerprint>
<DefaultIV>...</DefaultIV>
</KeyInfoData>
...
</KeyInfoDataList>
<IsOwner/>
<Policies> # if Policies for this key exist
   <PolicyEncrypt>
      <UsagePeriods> # Mandatory for "Always" policies and policies with
                     # defined usage periods. UsagePeriods does not exist
                     # for "Never" policies. UsagePeriods contains
                     # combined usage periods for all policies and groups
                     # for Encrypt operations.
        <UsagePeriod>
            <OpsPerHour>-1</OpsPerHour>     # Mandatory, -1 means no restrictions
            <Begin>
                 <DayOfWeek>1</DayOfWeek>   # Mandatory: 0-6. 0 is Sunday.
                 <HourOfDay>01</HourOfDay>  # Mandatory: 00-23
                 <Minute>00</Minute>        # Mandatory: 00-59
            </Begin>
            <End>
                 <DayOfWeek>6</DayOfWeek>
                 <HourOfDay>19</HourOfDay>
                 <Minute>00</Minute>
            </End>
         </UsagePeriod>
        ...
      </UsagePeriods>
   </PolicyEncrypt>
   <PolicyDecrypt>
      <UsagePeriods>
      ...
      </UsagePeriods>
   </PolicyDecrypt>
   <PolicyExport>
      <UsagePeriods>
      ...
      </UsagePeriods>
   </PolicyExport>
</Policies>
...
</KeyInfoResponse>

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 subject of the query.
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.
CurveID	It is optional only in case of EC keys.
Algorithms	The Algorithms element lists the set of algorithms with which this key can be used.
Algorithm	Contains a standard identifier string for the cryptographic algorithm. See Supported Key Algorithms for more information on supported algorithms and key sizes.
KeySize	Contains the key size.
Exportable	Indicates that the key is exportable.
Deletable	Indicates that the key is deletable.
Encrypt	Indicates that the key is capable of encryption. Only present and applicable for symmetric keys.
Decrypt	Indicates that the key is capable of decryption. Only present and applicable for symmetric keys.
Sign	Indicates that the key is capable of creating signatures.
SignV	Indicates that the key is capable of verifying signatures.
MAC	Indicates that the key is capable of creating MACs.
MACV	Indicates that the key is capable of verifying MACs.
UsePublic	Indicates that the the public portion of the key can encrypt data. Only present and applicable for asymmetric keys.
UsePrivate	Indicates that the private portion of the key can decrypt data. Only present and applicable for asymmetric keys.
VersionedKey	Indicates that the key is a versioned key.
NumKey Versions	Shows the number of key versions for the key.
NumActive Versions	Shows the number of active key versions.
NumRestricted Versions	Shows the number of restricted key versions.
NumRetired Versions	Shows the number of retired key versions.
NumWipedVersions	Shows the number of wiped key versions.
CustomAttributeList	Contains the list of custom attributes. The actual values are base64 encoded. This element is not included if the key does not have any associated custom attributes.
CustomAttribute	When a custom attribute is present, this element contains one Name, one Type, and one Value element.
Name	Indicates the name of the custom attribute.
Type	Data type of Custom Attribute. It is an optional tag and can be one of the following types: • String • Integer • Long Integer • Big Integer • Enumeration • Boolean • Byte String • Date/Time • Interval NOTE If `<Type>` is not specified, then data-type of `<Value>` for a new custom attribute is selected as String.
Value	Specifies the value of the attribute. This value must be base64 encoded, and the 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.
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.
KeyInfoDataList	Contains the version information (if applicable) and fingerprint. For versioned key returns only the last version.
KeyInfoData	Contains the key version information (if applicable) and fingerprint. One KeyInfoData element will exist for each key version. Non-versioned keys will have only one element.
KeyVersion	Shows the key version.
KeyVersion State	Shows the state of a key version.
KeyState	Shows the state of a non-versioned key.
KeyCreationDate	Shows the key's creation date and time. The creation date and time displays according to the time zone set on the CipherTrust Manager.
Fingerprint	Contains the key's fingerprint.
IsOwner	Present if the User issuing the KeyInfoRequest command is the Key Owner.
Policies	Contains PolicyEncrypt, PolicyDecrypt, and PolicyExport groups, which in turn each contain a UsagePeriods element.
UsagePeriods	Contains 1 or more UsagePeriod elements. OpsPerHour is a required UsagePeriod element; others are optional. UsagePeriods contains combined usage periods for all policies and groups for the policy type. The policy type is PolicyEncrypt, PolicyDecrypt, PolicyExport, PolicyMac, PolicyMacV, PolicySign, and PolicySignV.
UsagePeriod	Contains OpsPerHour and optionally one each of Begin and End DateTime groups.
Begin/End	Indicates the usage period during which encrypt, decrypt, and export are allowed. If "Always" is set in the Console, the Begin and End represent all days, hours, and minutes. NOTE: These tags do no any effect on the request. These tags are hardcoded and are added for backward compatibility.

Requesting information for a key using its UUID

<KeyInfoRequest>
    <ID>1</ID>
    <KeyName>2b314105-9d6f-426f-a560-8001b9fdb054</KeyName>
    <IDType>UUID</IDType>
</KeyInfoRequest>
<KeyInfoResponse>
    <ID>1</ID>
    <Success>true</Success>
    <KeyName>TestKeyForDoc</KeyName>
    <Algorithms>
    <Algorithm>AES</Algorithm>
    </Algorithms>
    <KeySize>256</KeySize>
    <Exportable/>
    <Deletable/>
    <Encrypt/>
    <Decrypt/>
    <VersionedKey/>
    <NumKeyVersions>36</NumKeyVersions>
    <NumActiveVersions>36</NumActiveVersions>
    <NumRestrictedVersions>0</NumRestrictedVersions>
    <NumRetiredVersions>0</NumRetiredVersions>
    <NumWipedVersions>0</NumWipedVersions>
    <IsOwner/>
    <KeyInfoDataList>
    <KeyInfoData>
    <KeyVersion>24</KeyVersion>
    <KeyVersionState>Active</KeyVersionState>
    <KeyCreationDate>2020-08-13 05:25:36.180148 +0000 UTC</KeyCreationDate>
    <Fingerprint>F09969696224EA1A</Fingerprint>
    <DefaultIV>c6f669a9126c70fb6f46f1feefd895af</DefaultIV>
    </KeyInfoData>
    </KeyInfoDataList>
</KeyInfoResponse>

Requesting Information about a Specific Key

In the example below, the client requests information about key_a.

<KeyInfoRequest>
    <ID>4</ID>
    <KeyName>key_a</KeyName>
</KeyInfoRequest>
<KeyInfoResponse>
    <ID>4</ID>
    <Success>true</Success>
    <KeyName>key_a</KeyName>
    <Algorithms>
    <Algorithm>AES</Algorithm>
    <Algorithm>AES/CBC/NoPadding</Algorithm>
    <Algorithm>AES/CBC/PKCS5Padding</Algorithm>
    <Algorithm>AES/ECB/NoPadding</Algorithm>
    <Algorithm>AES/ECB/PKCS5Padding</Algorithm>
    </Algorithms>
    <KeySize>256</KeySize>
    <Exportable/>
    <Deletable/>
    <Encrypt/>
    <Decrypt/>
    <KeyInfoDataList>
    <KeyInfoData>
    <KeyCreationDate>2014-07-14 18:34:30</KeyCreationDate>
    <Fingerprint>C0698613D81AC601</Fingerprint>
    </KeyInfoData>
    </KeyInfoDataList>
</KeyInfoResponse>

Requesting Information about a Versioned Key

In the example below, the client requests information about a versioned key.

<KeyInfoRequest>
    <ID>16</ID>
    <KeyName>aes-12v</KeyName>
    <AllVersions/>
</KeyInfoRequest>
<KeyInfoResponse>
    <ID>16</ID>
    <Success>true</Success>
    <KeyName>aes-12v</KeyName>
    <Algorithms>
    <Algorithm>AES</Algorithm>
    <Algorithm>AES/CBC/NoPadding</Algorithm>
    <Algorithm>AES/CBC/PKCS5Padding</Algorithm>
    <Algorithm>AES/ECB/NoPadding</Algorithm>
    <Algorithm>AES/ECB/PKCS5Padding</Algorithm>
    </Algorithms>
    <KeySize>192</KeySize>
    <Exportable/>
    <Deletable/>
    <Encrypt/>
    <Decrypt/>
    <VersionedKey/>
    <NumKeyVersions>2</NumKeyVersions>
    <NumActiveVersions>1</NumActiveVersions>
    <NumRestrictedVersions>1</NumRestrictedVersions>
    <NumRetiredVersions>0</NumRetiredVersions>
    <KeyInfoDataList>
    <KeyInfoData>
    <KeyVersion>2</KeyVersion>
    <KeyVersionState>Active</KeyVersionState>
    <KeyCreationDate>2014-07-14 18:35:08</KeyCreationDate>
    <Fingerprint>278D9810FBD7F411</Fingerprint>
    <DefaultIV>823871E6169A4696C3C2C9D09235D9C2</DefaultIV>
    </KeyInfoData>
    <KeyInfoData>
    <KeyVersion>1</KeyVersion>
    <KeyVersionState>Restricted</KeyVersionState>
    <KeyCreationDate>2014-07-14 18:35:25</KeyCreationDate>
    <Fingerprint>B13C56AC6BF2B5E1</Fingerprint>
    <DefaultIV>64265680ED943872A549C05111603CEC</DefaultIV>
    </KeyInfoData>
    </KeyInfoDataList>
</KeyInfoResponse>

In the example below, the client requests information about key_b.

<KeyInfoRequest>
    <ID>5</ID>
    <KeyName>key_b</KeyName>
</KeyInfoRequest>
<KeyInfoResponse>
    <ID>5</ID>
    <Success>true</Success>
     <KeyName>key_b</KeyName>
    <Algorithms>
            <Algorithm>AES</Algorithm>
    </Algorithms>
    <KeySize>256</KeySize>
    <Exportable/>
    <Deletable/>
     <Encrypt/>
     <Decrypt/>
    <CustomAttributeList>
            <CustomAttribute>
                <Name>Key1</Name>
                <Type>String</Type>
                <Value>U3VyeWF3YW5zaGk=</Value>
            </CustomAttribute>
            <CustomAttribute>
                <Name>Key2</Name>
                <Type>Integer</Type>
                <Value>MjE0NzQ4MzY0Ng==</Value>
            </CustomAttribute>
            <CustomAttribute>
                <Name>Key3</Name>
                <Type>Boolean</Type>
                <Value>dHJ1ZQ==</Value>
            </CustomAttribute>
            <CustomAttribute>
                <Name>key4</Name>
                <Type>Date/Time</Type>
                <Value>MjAyMC0wMi0wNyAxMTozODo1OQ==</Value>
            </CustomAttribute>
    </CustomAttributeList>
    <KeyInfoDataList>
            <KeyInfoData>
                <KeyCreationDate>2020-02-13 10:54:25.869567 +0000 UTC</KeyCreationDate>
                <Fingerprint>38BC5DB37057C50F</Fingerprint>
                <DefaultIV>96a6b2cd12ab40b4045c43347fe60754</DefaultIV>
            </KeyInfoData>
    </KeyInfoDataList>
</KeyInfoResponse>

Requesting Information for all key identifiers

<KeyInfoRequest>
    <ID>123</ID>
    <KeyIDs/>
    <AllVersions/>
    <KeyName>d1</KeyName>
</KeyInfoRequest>
<KeyInfoResponse>
    <ID>123</ID>
    <Success>true</Success>
    <Version>6.0</Version>
    <KeyName>d1</KeyName>
    <Algorithms>
        <Algorithm>RSA</Algorithm>
    </Algorithms>
    <KeySize>1024</KeySize>
    <Encrypt/>
    <Decrypt/>
    <Sign/>
    <SignV/>
    <UsePublic/>
    <UsePrivate/>
    <VersionedKey/>
        <NumKeyVersions>2</NumKeyVersions>
        <NumActiveVersions>2</NumActiveVersions>
        <NumRestrictedVersions>0</NumRestrictedVersions>
        <NumRetiredVersions>0</NumRetiredVersions>
        <NumWipedVersions>0</NumWipedVersions>
        <Policies>
            <PolicyEncrypt>
                <UsagePeriods></UsagePeriods>
            </PolicyEncrypt>
            <PolicyDecrypt>
                <UsagePeriods></UsagePeriods>
            </PolicyDecrypt>
            <PolicyExport>
                <UsagePeriods></UsagePeriods>
            </PolicyExport>
            <PolicyMac>
                <UsagePeriods></UsagePeriods>
            </PolicyMac>
            <PolicyMacv>
                <UsagePeriods></UsagePeriods>
            </PolicyMacv>
            <PolicySign>
                <UsagePeriods></UsagePeriods>
            </PolicySign>
            <PolicySignv>
                <UsagePeriods></UsagePeriods>
            </PolicySignv>
        </Policies>
        <KeyInfoDataList>
            <KeyInfoData>
                <KeyVersion>1</KeyVersion>
                <KeyVersionState>Active</KeyVersionState>
                <KeyCreationDate>2019-12-13 10:20:07.26642 +0000 UTC</KeyCreationDate>
                <Fingerprint>07987AB591712544</Fingerprint>
                <KeyUUID>cfbabdc2-7c47-4ba5-a933-bd8e13e29c1e</KeyUUID>
                <KeyMUID>cfbabdc2-7c47-4ba5-a933-bd8e13e29c1efadbfe5c-d922-4884-
                9659-0d60350fbcb3</KeyMUID>
                <ExternalKeyID>2220948856</ExternalKeyID>
            </KeyInfoData>
            <KeyInfoData>
            <KeyVersion>2</KeyVersion>
            <KeyVersionState>Active</KeyVersionState>
            <KeyCreationDate>2019-12-13 10:20:25.453338 +0000 UTC</KeyCreationDate>
            <Fingerprint>99CB862075FC2DC9</Fingerprint>
            <KeyUUID>307a24b9-807d-4217-81e6-9e6b6b1e103f</KeyUUID>
            <KeyMUID>307a24b9-807d-4217-81e6-9e6b6b1e103f54854d29-73c5-4152-ac54-9cb69
            5264797</KeyMUID>
            <ExternalKeyID>662097815</ExternalKeyID>
        </KeyInfoData>
    </KeyInfoDataList>
</KeyInfoResponse>

Example of a Policy with an "Always" UsagePeriod

<PolicyEncrypt>
   <UsagePeriods>
      <UsagePeriod>
         <OpsPerHour>-1</OpsPerHour>
         <Begin>
            <DayOfWeek>0</DayOfWeek>
            <HourOfDay>00</HourOfDay>
            <Minute>00</Minute>
         </Begin>
         <End>
            <DayOfWeek>6</DayOfWeek>
            <HourOfDay>23</HourOfDay>
            <Minute>59</Minute></End>
     </UsagePeriod>
   </UsagePeriods>
</PolicyEncrypt>

Example of a Policy with a "Never" UsagePeriod

<PolicyEncrypt/>

KeyNamesRequest

Returns names of all keys on the CipherTrust Manager in a chronological order.

The client can request the server to return the names of all keys available to the client by using the KeyNamesRequest element.

For unauthenticated clients, this request queries the global keys only.
For authenticated clients, this request queries global keys, keys owned by the client, and keys for which the client has some defined permissions.

The server returns a list of names of the keys available to the client. Optionally, the KeyNamesRequest command can specify that only keys with custom attributes or the key fingerprint matching the request be returned.

Note

AttributeValue is allowed only when AttributeName is specified. If AttributeName is not specified, AttributeValue has no effect.

The KeyNamesRequest command is used to search the following attributes:

To Search KeyNames based on Single Attribute

<KeyNamesRequest>
    <ID>...</ID>
    <AttributeName>...</AttributeName>   # optional
    <AttributeValue>...</AttributeValue> # optional
    <Fingerprint>...</Fingerprint>   # optional
    <KeyOffset>...</ KeyOffset>      # optional
    <MaxKeys>...</MaxKeys>               # optional
</KeyNamesRequest>

To Search KeyNames based on Multiple Attributes

<KeyNamesRequest>
    <ID>...</ID>
    <Fingerprint>...</Fingerprint>                    # optional
    <KeyOffset>...</ KeyOffset>                       # optional
    <MaxKeys>...</MaxKeys>                            # optional
    <ConjunctiveOperator>.....</conjunctiveOperator>  #Optional
    <CustomAttributeList>
        <CustomAttribute>
            <Name>...</Name>             
            <Value>...</Value>          
        </CustomAttribute>
        <CustomAttribute>
           <Name>...</Name>              
           <Value>...</Value>            
        </CustomAttribute>      
    </CustomAttributeList>  
</KeyNamesRequest>

To Search KeyNames using uuid

<KeyNamesRequest>
    <ID>...</ID>
    <KeyUUID>...</KeyUUID>
</KeyNamesRequest>

To Search KeyNames using muid

<KeyNamesRequest>
    <ID>...</ID>
    <KeyMUID>...</KeyMUID>
</KeyNamesRequest>

To Search KeyNames using keyId

<KeyNamesRequest>
    <ID>...</ID>
    <ExternalKeyID>...</ExternalKeyID>
</KeyNamesRequest>

To Search KeyNames

<KeyNamesRequest>
    <ID>...</ID>
    <ExternalKeyID>...</ExternalKeyID>
</KeyNamesRequest>

To retrieve all types of objects (keys, certificates, secret objects, etc.)

<KeyNamesRequest>
    <ID>...</ID>
    <AllObjects/>       # optional, supported for 6.1 or higher
</KeyNamesRequest>

Element	Description
ID	Contains the user-specified request ID.
AttributeName	Name of Custom Attributes to search.
AttributeValue	The desired value of the attribute. String, integer, and DataTime types are supported value types.
CustomAttributeList	Lists multiple attributes to search.
CustomAttribute	Lists single attribute to search.
Name	Name of Custom Attributes.
Value	Value of Custom Attributes. NOTE: This value must be passed in the BASE64 format.
ConjuctiveOperator	Supports only two operators "AND" and "OR". Values other than "AND" and "OR" will be considered as "OR". Default value is "AND".
Fingerprint	The key fingerprint.
KeyOffset	It is the offset from where records need to be returned from the result set. In case, it is not provided, the default value "0" (zero) is assumed and the response will contain records from the beginning.
MaxKeys	It represent the maximum number of keys which a client expect in one response. If it is not provided, 10000 keys will be returned in `<KeyNamesResponse>`.
uuid	Universally Unique Identifier (uuid) is a 128 bits DPM key identfier.
muid	Multiversally Unique Identifier (muid) is a 256 bits DPM key identfier.
keyId	It is a 32 bit DPM key identifier.
AllObjects	If this tag is specified, then all types of objects (keys, certificates, secret objects, etc.) are returned in response.

Examples Requesting Names of Keys

In the examples below, the client requests names from all the keys on the server.

Example 1

Returns names of all keys available to the client

<KeyNamesRequest>
    <ID>125</ID>
</KeyNamesRequest>

Example 2

Returns the names of all keys that have the custom attribute Contact Information

<KeyNamesRequest>
    <ID>125</ID>
    <AttributeName>Contact Information</AttributeName> 
</KeyNamesRequest>

Example 3

Returns the names of all keys that have the following custom attributes

x-age and the value 32 (In BASE64 format, the value of 32 is MzI=)

x-abc and the value 5 (In BASE64 format, the value of 5 is NQ==)

<KeyNamesRequest>
<ID>125</ID>
<ConjunctiveOperator>OR</conjunctiveOperator> 
  <CutomAttributeList>
     <CustomAttribute>
        <Name>x-age</Name>
        <Value>MzI=</Value>
     </CustomAttribute>
     <CustomAttribute>
        <Name>x-abc</Name>
        <Value>NQ==</Value>
     </CustomAttribute>
  </CustomAttributeList>
</KeyNamesRequest>

Example 4

Returns the names of all keys that have the custom attribute x-birthday and the value 1999-09-09 01:01:01

<KeyNamesRequest>
    <ID>125</ID>
    <AttributeName>x-birthday</AttributeName>
    <AttributeValue>1999-09-09 01:01:01</AttributeValue>
</KeyNamesRequest>

Example 5

Returns the name of the key that has the given fingerprint

<KeyNamesRequest>
    <ID>125</ID>
    <Fingerprint>C6EB938010B7C4E3</Fingerprint>
</KeyNamesRequest>

Example 6

Keys from KeyOffset 2

<KeyNamesRequest>
    <ID>1233</ID>
    <KeyOffset>2</KeyOffset>
</KeyNamesRequest>

Example 7

Keys from KeyOffset 2 and MaxKeys 3

<KeyNamesRequest>
    <ID>1233</ID>
    <KeyOffset>2</KeyOffset>
    <MaxKeys>3</MaxKeys>
</KeyNamesRequest>

Example 8

Keys from specified external key-Ids

<KeyNamesRequest>
    <ID>125</ID>
    <KeyUUID>426ba632-2244-4ae1-8b3a-ad8162a1df47</KeyUUID>
    </KeyNamesRequest>
    <KeyNamesRequest>
    <ID>125</ID>
    <KeyMUID>ad4a816b-2500-4346-a815-a949adea32376d2c89a7-5830-476a-b5d0-b2edaca55d7e</KeyMUID>
</KeyNamesRequest>
    <KeyNamesRequest>
    <ID>125</ID>
    <ExternalKeyID>989954321</ExternalKeyID>
</KeyNamesRequest>

Example 9

Request to retrieve all types of objects

<KeyNamesRequest>
    <ID>125</ID>
    <AllObjects/>
</KeyNamesRequest>
<KeyNamesResponse>
    <ID>125</ID>
    <Success>true</Success>
    <KeysCount>2</KeysCount>
    <TotalKeysCount>2</TotalKeysCount>
    <KeyName>MySecret1234</KeyName>
    <KeyName>Sample_Aes_128Key</KeyName>
</KeyNamesResponse>

KeyNamesResponse

Server response to a KeyNamesRequest.

Note

This response only includes the keys that the user has permission to see.

Response

<KeyNamesResponse>
    <ID>...</ID>
    <Success>true</Success>
    <KeysCount>….</KeysCount>        # Number of keys returned
    <TotalKeysCount>….</TotalKeysCount > # Total number of keys found
    <KeyName>...</KeyName>           # First key
    <KeyName>...</KeyName>           # Second key
     ...
</KeyNamesResponse>

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 element 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.
KeyCount	It indicates the number of keys returned in KeyNamesResponse. It’s value can be less than MaxKeys in case the filter criterion returned less records.
Total KeyCount	Indicates the total number of keys that are available for a given query.
KeyName	The rest of the key names response consists of one or more KeyName elements.

KeyQueryRequest

Returns information about all of the keys on the CipherTrust Manager.

The client can request the server to return information about all keys available to the client by using the KeyQueryRequest element. For unauthenticated clients, such a request will query the global keys only. For authenticated clients, this request will query global keys, keys owned by the client, and keys for which the client has some defined permissions.

<KeyQueryRequest>
    <ID>...</ID>
    <OpaqueObjects/>    # optional, supported for 7.0 or higher
    <AllObjects/>       # optional, supported for 6.1 or higher
</KeyQueryRequest>

Element	Description
ID	Contains the user-specified request ID.
OpaqueObjects	If specified, then all types of opaque objects are returned in the response. Note:The `OpaqueObjects` and `AllObjects` tags cannot be used simultaneously in a KeyQueryRequest.
AllObjects	If specified, then all types of objects (keys, certificates, secret objects, etc.) are returned in the response. Note: The `OpaqueObjects` and `AllObjects` tags cannot be used simultaneously in a KeyQueryRequest.

KeyQueryResponse

Server response to a KeyQueryRequest.

Note

This response will include global keys and the keys that the user has permission to see.

Response

<KeyQueryResponse>
    <ID>...</ID>
    <Success>true</Success>
    <KeyName>...</KeyName>
    <Algorithms>
    <Algorithm>...</Algorithm>
    ...
    </Algorithms>
    <KeySize>...</KeySize>          
    <Exportable/>           # These elements are only
    <Deletable/>            # present if the operation
    <Encrypt/>          # is available
    <Decrypt/>          
    <Sign/>         
    <SignV/>            
    <MAC/>          
    <MACV/>         
    <UsePublic/>            
    <UsePrivate/>           
    <VersionedKey/>             # These elements are only present 
    <NumKeyVersions>...</NumKeyVersions>    # for versioned keys
    <NumActiveVersions>...</NumActiveVersions> 
    <NumRestrictedVersions>...</NumRestrictedVersions> 
    <NumRetiredVersions>...</NumRetiredVersions> 
    <NumWipedVersions>...</NumWipedVersions>
    <KeyInfoDataList>
    <KeyInfoData>
    <KeyVersion>...</KeyVersion> # optional
    <KeyVersionState>...</KeyVersionState> # optional
    <KeyState>...</KeyState> # Optional, supported for 6.9 and higher
    <Fingerprint>...</Fingerprint>
    <DefaultIV>...</DefaultIV>
    </KeyInfoData>
    ...
    </KeyInfoDataList>
    <KeyName>...</KeyName>          # Second key
         ...         
</KeyQueryResponse>

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	The rest of the key query response consists of each KeyName, followed by the information for that key. Refer to Key Management Operations for information on these child elements.
Algorithms	The Algorithms element lists the set of algorithms with which this key can be used.
Algorithm	Contains a standard identifier string for the cryptographic algorithm. See Supported Key Algorithms for more information on supported algorithms and key sizes.
KeySize	Contains the key size.
Exportable	Indicates that the key is exportable.
Deletable	Indicates that the key is deletable.
Encrypt	Indicates that the client can use the key to encrypt. Only present and applicable for symmetric keys.
Decrypt	Indicates that the client can use the key to decrypt.
Sign	Indicates that the client can use the key to create signatures.
SignV	Indicates that the client can use the key to verify signatures.
MAC	Indicates that the client can use the key to create MACs.
MACV	Indicates that the client can use the key to verify MACs.
UsePublic	Indicates that the client can use the public portion of the key to encrypt data.
UsePrivate	Indicates that the client can use the private portion of the key to decrypt data.
VersionedKey	Indicates that the key is a versioned key.
NumKey Versions	Shows the number of key versions for the key.
NumActive Versions	Shows the number of active key versions.
NumRestricted Versions	Shows the number of restricted key versions.
NumRetired Versions	Shows the number of retired key versions.
KeyInfoDataList	Contains the version information (if applicable) and fingerprint.
KeyInfoData	Contains the key version information (if applicable) and fingerprint. One KeyInfoData element will exist for each key version. Non-versioned keys will have only one element.
KeyVersion	Shows the key version.
KeyVersion State	Shows the state of a key version.
KeyState	Shows the state of a non-versioned key.
Fingerprint	Contains the key's fingerprint.
AllObjects	If this tag is specified, then all types of objects (keys, certificates, secret objects etc) are returned in response.

Requesting Information about All Keys

In the example below, the client requests information about all of the keys on the server.

<KeyQueryRequest>
    <ID>8</ID> 
</KeyQueryRequest>
<KeyQueryResponse>
    <ID>8</ID>
    <Success>true</Success>
    <KeyName>key_a</KeyName>
    <Algorithms>
    <Algorithm>AES</Algorithm>
    <Algorithm>AES/CBC/NoPadding</Algorithm>
    <Algorithm>AES/CBC/PKCS5Padding</Algorithm>
    <Algorithm>AES/ECB/NoPadding</Algorithm>
    <Algorithm>AES/ECB/PKCS5Padding</Algorithm>
    </Algorithms>
    <KeySize>256</KeySize>
    <Exportable/>
    <Deletable/>
    <Encrypt/>
    <Decrypt/>
    <Fingerprint>C0698613D81AC601</Fingerprint>
    <KeyName>key_b</KeyName>
    <Algorithms>
    <Algorithm>RSA</Algorithm>
    <Algorithm>SHA1withRSA</Algorithm>
    </Algorithms>
    <KeySize>512</KeySize>
    <Exportable/>
    <Sign/>
    <SignV/>
    <UsePublic/>
    <UsePrivate/>
    <Fingerprint>C0E01D79C0F29C14</Fingerprint>
    <KeyName>key_c</KeyName>
    <Algorithms>
    <Algorithm>DESede</Algorithm>
    <Algorithm>DESede/CBC/NoPadding</Algorithm>
    <Algorithm>DESede/CBC/PKCS5Padding</Algorithm>
    <Algorithm>DESede/ECB/NoPadding</Algorithm>
    <Algorithm>DESede/ECB/PKCS5Padding</Algorithm>
    </Algorithms>
    <KeySize>168</KeySize>
    <Encrypt/>
    <Decrypt/>
    <Fingerprint>2B5D754C65392AEC</Fingerprint>
</KeyQueryResponse>

Requesting information about secret objects along with keys

<KeyQueryRequest>
    <ID>124</ID>
    <AllObjects/>
</KeyQueryRequest>
<KeyQueryResponse>
    <ID>124</ID>
    <Success>true</Success>
    <KeyName>Sample_Aes_128Key</KeyName>
    <Algorithms>
    <Algorithm>AES</Algorithm>
    </Algorithms>
    <KeySize>128</KeySize>
    <Exportable/>
    <Deletable/>
    <Encrypt/>
    <Decrypt/>
    <Sign/>
    <SignV/>
    <MAC/>
    <MACV/>
    <KeyInfoDataList>
    <KeyInfoData>
    <Fingerprint>22EBFE970DCC2CB7</Fingerprint>
    <DefaultIV>5d72bb03b17e84b4e695752abca62013</DefaultIV>
    </KeyInfoData>
    </KeyInfoDataList>
    <KeyName>MySecret1234</KeyName>
    <Algorithms>
    <Algorithm>OPAQUE</Algorithm>
    </Algorithms>
    <KeySize>256</KeySize>
    <Exportable/>
    <Deletable/>
    <KeyInfoDataList>
    <KeyInfoData>
    <Fingerprint>970093678B182127</Fingerprint>
    <DefaultIV>411edd4a3c327b6e7adbee629e887fbe</DefaultIV>
    </KeyInfoData>
    </KeyInfoDataList>
</KeyQueryResponse>

KeyCloneRequest

Clones an existing key. The new key will have exactly the same key bytes, owner, permissions, meta data; only the name will be different.

Note

If the key is not a global key, the client must be the key owner.

Request

<KeyCloneRequest>
    <ID>...</ID>
    <KeyName>...</KeyName>
    <NewKeyName>...</NewKeyName>
</KeyCloneRequest>

Element	Description
ID	Contains the user-specified request ID.
KeyName	Contains the name of the key that will be cloned.
NewKeyName	Contains the name for the new key.

KeyCloneResponse

Server response to KeyCloneResponse.

<KeyCloneResponse>
    <ID>...</ID>
    <Success>true</Success>
    <Fingerprint>...</Fingerprint>
    <KeyName>newkeyname</KeyName>
</KeyCloneResponse>

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.
Fingerprint	Contains the fingerprint of the cloned key.
KeyName	Contains the new key name.

Cloning a Key

<KeyCloneRequest>
  <ID>XMLID32</ID>
  <KeyName>des-56</KeyName>
  <NewKeyName>des-56-clone</NewKeyName>
</KeyCloneRequest>
<KeyCloneResponse>
  <ID>XMLID32</ID>
  <Success>true</Success>
  <Fingerprint>D66373996DC4979D</Fingerprint>
  <KeyName>des-56-clone</KeyName>
</KeyCloneResponse>

Suggest A Change

Key Management Operations

KeyGenRequest

KeyGenResponse

Generating an AES Key

Generating an RSA Key

Generating an AES key using HKDF

Generating a Key and Setting Permissions

Creating a New Versioned Key

KeyVersionGenRequest

KeyVersionGenResponse

Creating a New Version of a Versioned Key

KeyModifyRequest

KeyModifyResponse

Deleting a Custom Attribute

Changing the Key Owner

Changing Key Permissions for a Group

Setting External IDs of the key

KeyVersionModifyRequest

KeyVersionModifyResponse

Modifying the State of a Key Version

KeyDelRequest

KeyDelResponse

Deleting a Key

KeyInfoRequest

KeyInfoResponse

Requesting information for a key using its UUID

Requesting Information about a Specific Key

Requesting Information about a Versioned Key

Requesting Information for all key identifiers

Example of a Policy with an "Always" UsagePeriod

Example of a Policy with a "Never" UsagePeriod

KeyNamesRequest

To Search KeyNames based on Single Attribute

To Search KeyNames based on Multiple Attributes

To Search KeyNames using uuid

To Search KeyNames using muid

To Search KeyNames using keyId

To Search KeyNames

To retrieve all types of objects (keys, certificates, secret objects, etc.)

Examples Requesting Names of Keys

Example 1

Example 2

Example 3

Example 4

Example 5

Example 6

Example 7

Example 8

Example 9

KeyNamesResponse

KeyQueryRequest

KeyQueryResponse

Requesting Information about All Keys

Requesting information about secret objects along with keys

KeyCloneRequest

KeyCloneResponse

Cloning a Key

On this page