Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo
back

NAE-XML Interface Development

Key Management Operations

search

Key Management Operations

The XML Interface accepts requests to:

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

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>

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.

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.

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

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

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.

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

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

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

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

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