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