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

Secret Management Operations

search

Please Note:

Secret Management Operations

Secrets are managed objects that can store user defined data. This data can be:

  • blob

  • password

  • seed

There are two types of objects used to store secrets:

  • Secret Object: It can have password or seed as the data type. The seed may be used for cryptographic operations in the future, which is why it is a separate type. The password is a convenient way to store simple text strings.

  • Opaque Object: It is of blob data type. It can be used to store arbitrary data.

CipherTrust Manager's Network Attached Encryption (NAE) protocol only supports Opaques Objects for XML interface 6.1 or higher.

Secrets support many of the same attributes that keys do. They can be made un-deletable, support meta-data, etc. They also support most of the same lifecycle states as keys.

The XML Interface enables you to:

SecretObjectImportRequest

Import a secret object.

<SecretObjectImportRequest>
<ID>......</ID>
<ObjectName>......</ObjectName>
<ObjectData>......</ObjectData>
<ObjectDataType>......</ObjectDataType>
<ObjectUUID>.......</ObjectUUID>               # optional
<ObjectMUID>........</ObjectMUID>              # optional
<ExternalObjectID>.......</ExternalObjectID>   # optional
<Exportable/>
<Deletable/>
<Aliases>                       # optional, supported for 6.8 and higher
    <Alias>
        <Name>...</Name>
        <Type>...</Type>
    </Alias>
    ...
</Aliases>
<Permissions>...</Permissions>   # optional, supported for 6.5 and higher
<CustomAttributeList>            # optional,supported for 6.5 and higher
    <CustomAttribute>            # supported for 6.5 and higher
        <Name>...</Name>         # supported for 6.5 and higher
        <Type>...</Type>         # optional, supported for 6.5 and higher
        <Value>...</Value>       # supported for 6.5 and higher 
    </CustomAttribute>
    ...
</CustomAttributeList>
</SecretObjectImportRequest>
Element Description
ID Contains the user-specified request ID.
ObjectName Name of the secret object.
ObjectData Data to be imported as an opaque object.
ObjectDataType Data type of the object.
NOTE: Currently, only opaque objects are supported.
ObjectUUID Used to set a UUID. It is an optional element. If not provided, a randomly generated value is used.
ObjectMUID Used to set a MUID. It is an optional element.
ExternalObjectID Used to set an ObjectID. It is an optional element.
Aliases Specifies the list of Alias elements.
Alias Alias is unique for each secret object. 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 String type.
NOTE: If <Type> is not specified, the data type of the <Name> element is selected as String.
Permissions Specifies the secret object usage permissions granted to specific groups.
An owner of a secret object can grant secret object usage permissions to specific user groups by adding the Permissions element, and the Group and appropriate secret object usage permission elements: Encrypt, Decrypt, SIGN, and SIGNV. This element is optional.
Group Specifies the group that has permission to use secret object. It is a child element of the Permissions element.
Encrypt Indicates that the group can use the secret object to encrypt data. Only present and applicable for symmetric keys.
Decrypt Indicates that the group can use the secret object to decrypt data.
SIGN Indicates that the group can use the secret object to create signatures.
SIGNV Indicates that the group can use the secret object to verify signatures.
CustomAttributeList Specifies the list of custom attributes. This element can contain multiple CustomeAttribute 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. It can be one of the following types:
• String
• Integer
• Long Integer
• Big Integer
• Enumeration
• Boolean
• Byte String
• Date/Time (default format: "yyyy-mm-dd hr:mm:ss")
• Interval
NOTE: If <Type> is not specified, then String is selected as the default data-type for <Value>.
Value Specifies the value of the attribute. This value must be base64 encoded, and input is considered as text. If your original data contains non-printable characters, convert the original data to hex values, and then convert the hex values to base64.

SecretObjectImportResponse

Server response to SecretObjectImportRequest.

<SecretObjectImportResponse>
    <ID>......</ID>
    <Success>.....</Success>
    <Fingerprint>......</Fingerprint>
    <ObjectName>......</ObjectName>
</SecretObjectImportResponse>
Element Description
ID Contains the user-specified request ID.
ObjectName Name of the secret object.
Fingerprint Contains the fingerprint of the secret object.
Example
<SecretObjectImportRequest>
    <ID>1</ID>
    <ObjectName>Sample_Secret1</ObjectName>
    <ObjectData>ABCDEF</ObjectData>
    <ObjectDataType>opaque</ObjectDataType>
    <ObjectUUID>jaiufhsfiuv</ObjectUUID>
    <ObjectMUID>jaiufhsfiuvehyufjbkdhkv</ObjectMUID>
    <ExternalObjectID>98765</ExternalObjectID>
    <Exportable/>
    <Deletable/>
</SecretObjectImportRequest>
<SecretObjectImportResponse>
    <ID>1</ID>
    <Success>true</Success>
    <Fingerprint>970093678B182127</Fingerprint>
    <ObjectName>Sample_Secret1</ObjectName>
</SecretObjectImportResponse>

SecretObjectExportRequest

Export a Secret Object.

<SecretObjectExportRequest>
    <ID>......</ID>
    <ObjectName>......</ObjectName>
    <Alias>.....</Alias>
</SecretObjectExportRequest>
Element Description
ID Contains the user-specified request ID.
ObjectName Indicates the name of the secret object. You can use ObjectName/Alias to export a secret object.
Alias Indicates the alias name of the secret object. You can use Alias/ObjectName to export a secret object.

SecretObjectExportResponse

Server response to SecretObjectExportRequest.

<SecretObjectExportResponse>
    <ID>......</ID>
    <Success>true</Success>
    <ObjectName>......</ObjectName>
    <ObjectData>......</ObjectData>
    <ObjectType>......</ObjectType>
    <Fingerprint>......</Fingerprint>
    <ObjectLength>.....</ObjectLength>
</SecretObjectExportResponse>
Element Description
ID Contains the user-specified request ID.
ObjectName Name of the secret object.
ObjectData The data of the opaque object.
ObjectType Data type of the object.
NOTE: Currently, only Opaque Objects are supported.
Fingerprint Contains the fingerprint of the secret object.
ObjectLength Contains the length of the object material/data.
Example
<SecretObjectExportRequest>
    <ID>123</ID>
    <ObjectName>MySecret1234</ObjectName>
</SecretObjectExportRequest>
<SecretObjectExportResponse>
    <ID>123</ID>
    <Success>true</Success>
    <ObjectName>MySecret1234</ObjectName>
    <ObjectData>ABCDEFG</ObjectData>
    <ObjectType>Opaque Object</ObjectType>
    <Fingerprint>93BE4612C41D23AF</Fingerprint>
    <ObjectLength>7</ObjectLength>
</SecretObjectExportResponse>

SecretObjectInfoRequest

Return information about a secret object.

<SecretObjectInfoRequest>
    <ID>......</ID>
    <ObjectName>......</ObjectName>
    <IDType>......</IDType>                # optional, supported for 6.4 or higher 
    <GetObjectIDs/>                      #optional
</SecretObjectInfoRequest>
Element Description
ID Contains the user-specified request ID.
ObjectName Name of the secret object.
IDType Identifier in the ObjectName is managed according to the value specified in this tag. Possible values are:
• Name (Default)
• UUID
• MUID
• ObjectId
• Alias (supported for 6.8 or higher)
GetObjectIDs Displays all the identifiers of the object such as UUID, MUID, and ObjectID. This element is optional.

SecretObjectInfoResponse

Server response to SecretObjectInfoRequest.

    <SecretObjectInfoResponse>
    <ID>......</ID>
    <Success>......</Success>
    <ObjectName>......</ObjectName>
    <Fingerprint>......</Fingerprint>
    <ObjectType>opaque</ObjectType>
    <ObjectCreationDate>......</ObjectCreationDate>
    <ObjectUpdatedAt>......</ObjectUpdatedAt>
    <Exportable/>
    <Deletable/>
    <Aliases>                #  available only for 6.8 and higher
        <Alias>
            <Name></Name>
            <Type></Type>
        </Alias>
        ...
    </Aliases>
    <ObjectUUID>.......</ObjectUUID>               
    <ObjectMUID>........</ObjectMUID>              
    <ExternalObjectID>.......</ExternalObjectID>  
    <Encrypt/>                  #  available only for 6.5 and higher     
    <Decrypt/>                  #  available only for 6.5 and higher
    <Sign/>                     #  available only for 6.5 and higher
    <SignV/>                    #  available only for 6.5 and higher
    <CustomAttributeList>       #  present only when there are multiple custom attributes 
        <CustomAttribute>            # supported for 6.5 and higher
            <Name>...</Name>        # supported for 6.5 and higher 
            <Type>...</Type>        # optional, supported for 6.5 and higher       
            <Value>...</Value>      # optional, supported for 6.5 and higher
        </CustomAttribute>
    </CustomAttributeList>
</SecretObjectInfoResponse>
Element Description
ID Contains the user-specified request ID.
ObjectName Name of the secret object.
Fingerprint Contains the fingerprint of the secret object.
ObjectType Data type of the object.
NOTE: Currently, only Opaque Objects are supported.
ObjectCreationDate Date and time when the object was created.
ObjectUpdatedAt Date and time when the object was most recently updated.
Aliases Specifies the list of Alias elements.
Alias Alias is unique for each secret object. 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.
ObjectUUID Shows the UUID of the secret object.
ObjectMUID Shows the MUID of the secret object.
ExternalObjectID Shows the ExternalObjectID of the secret object.
Encrypt Indicates that the secret object is capable of encryption. Only present and applicable for symmetric keys.
Decrypt Indicates that the secret object is capable of decryption.
Sign Indicates that the secret object is capable of creating signatures.
SignV Indicates that the secret object is capable of verifying signatures.
CustomAttributeList Specifies the list of custom attributes. This element can contain multiple CustomeAttribute 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. 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:
• 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 cannot be changed.
Value Specifies the value of the attribute. This value must be base64 encoded, and input is considered as text. If your original data contains non-printable characters, convert the original data to hex values, and then convert the hex values to base64.
Example
<SecretObjectInfoRequest>
    <ID>2</ID>
    <ObjectName>Sample_Secret1</ObjectName>
    <GetObjectIDs/>
</SecretObjectInfoRequest>
<SecretObjectInfoResponse>
    <ID>2</ID>
    <Success>true</Success>
    <ObjectName>Sample_Secret1</ObjectName>
    <Fingerprint>970093678B182127</Fingerprint>
    <ObjectType>Opaque Object</ObjectType>
    <ObjectCreationDate>2021-01-20 06:12:34.29376 +0000 UTC</ObjectCreationDate>
    <ObjectUpdatedAt>2021-01-20 06:12:34.29376 +0000 UTC</ObjectUpdatedAt>
    <Exportable/>
    <Deletable/>
    <IsOwner/>
    <ObjectUUID>jaiufhsfiuv</ObjectUUID>
    <ObjectMUID>jaiufhsfiuvehyufjbkdhkv</ObjectMUID>
    <ExternalObjectID>98765</ExternalObjectID>
</SecretObjectInfoResponse>
Example - Requesting information of a object using UUID
<SecretObjectInfoRequest>
    <ID>02</ID>
    <ObjectName>1ba3bbe9-152c-4584-bbae-6cc4afeb590e</ObjectName>
    <IDType>UUID</IDType>
</SecretObjectInfoRequest>
<SecretObjectInfoResponse>
    <ID>02</ID>
    <Success>true</Success>
    <ObjectName>Sample_Secret1</ObjectName>
    <Fingerprint>970093678B182127</Fingerprint>
    <ObjectType>Opaque Object</ObjectType>
    <ObjectCreationDate>2021-02-10 07:29:26.588881 +0000 UTC</ObjectCreationDate>
    <ObjectUpdatedAt>2021-02-10 07:29:26.588881 +0000 UTC</ObjectUpdatedAt>
    <Exportable/>
    <Deletable/>
    <IsOwner/>
</SecretObjectInfoResponse>

SecretObjectModifyRequest

Modify a secret object.

<SecretObjectModifyRequest>
<ID>.....</ID>
<ObjectName>.....</ObjectName>
<Owner>.....</Owner>
<ObjectMUID>.....</ObjectMUID>               # optional
<ExternalObjectID>.....</ExternalObjectID>   # optional
<Exportable/>
<Deletable/>
<NonExportable/>
<NonDeletable/>
<Aliases>                              # optional, supported for 6.8 and higher
    <Alias>
        <Name>...</Name>
        <Type>...</Type>
    </Alias>
    ...
</Aliases>
<DeleteAlias>
    <Name>...</Name>
    <Name>...</Name>
</DeleteAlias>
<Permissions>...</Permissions>          # optional, supported for 6.5 and higher
<CustomAttributeList>            # include to add or update 
<CustomAttribute>           # custom attributes
    <Name>...</Name>        # Supported for 6.5 and higher
    <Type>...</Type>        # Optional, supported for 6.5 and higher
    <Value>...</Value>      # Supported for 6.5 and higher
</CustomAttribute>
...
</CustomAttributeList>       
<DeleteCustomAttribute>      # include to delete an existing, supported for 6.5 and higher
    <Name>...</Name>         # custom attribute, supported for 6.5 and higher
    <Name>...</Name>            # Supported for 6.5 and higher
</DeleteCustomAttribute>        # Supported for 6.5 and higher
<DeleteAllCustomAttributes/>    # include to delete all custom attributes, supported for 6.5 and higher
</SecretObjectModifyRequest>

Above example is for reference only. Following tags must not be specified together in a single request, as it causes errors:
• <Deletable> and <NonDeletable>
• <Exportable> and <NonExportable>

Element Description
ID Contains the user-specified request ID.
ObjectName Name of the secret object.
ObjectMUID Used to set a MUID, if not set already.
ExternalObjectID Used to set an objectId, if not set already. It is specified in the Long type format.
Exportable Used to make the secret object exportable.
NonExportable Used to make the secret object non-exportable.
Deletable Used to make the secret object deletable.
NonDeletable Used to make the secret object non-deletable.
Aliases Specifies the list of Alias elements.
Alias Alias is unique for each secret object. 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 String type.
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.
Owner Used to modify the Owner for the Secret Object. The specified owner must already exist.
Permissions Specifies the secret object usage permissions granted to specific groups. This element is optional. When used, it overwrites the existing secret object permissions.
Any previous permission settings that are not included in this modification request are erased. Thus, to make a change to a secret object'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 secret object can grant secret object usage permissions to specific user groups by adding the Permissions element, and the Group and appropriate secret object usage permission elements: Encrypt, Decrypt, SIGN, and SIGNV.
This functionality is available only to the key owner, therefore your application must authenticate as the owner of the secret object to modify its permissions.
Groups Specifies the group that has permission to use secret object. It is a child element of the Permissions element.
Encrypt Indicates that the group can use the secret object to encrypt data. Only present and applicable for symmetric keys.
Decrypt Indicates that the group can use the secret object to decrypt data.
Sign Indicates that the group can use the secret object to create signatures.
SignV Indicates that the group can use the secret object to verify signatures.
CustomAttributeList Contains the custom attributes that will be added or updated. Child elements are CustomAttribute, Name, 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 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:
• 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 of the key's Custom Attributes (Name and Value elements are lost).

SecretObjectModifyResponse

Server response to SecretObjectModifyRequest.

<SecretObjectModifyResponse>
    <ID>.....</ID>
    <Success>.....</Success>
</SecretObjectModifyResponse>
Element Description
ID Contains the user-specified request ID.
Example 1
<SecretObjectModifyRequest>
    <ID>3</ID>
    <ObjectName>Sample_Secret2</ObjectName>
    <ObjectMUID>zxcvbnmlkjhgfetryuicvbnmtryui</ObjectMUID>
    <ExternalObjectID>1256789</ExternalObjectID>
</SecretObjectModifyRequest>
<SecretObjectModifyResponse>
    <ID>3</ID>
    <Success>true</Success>

Example 2
<SecretObjectModifyRequest>
    <ID>test1</ID>
    <ObjectName>Secret</ObjectName>
    <NonExportable/>
    <NonDeletable/>
</SecretObjectModifyRequest>
<SecretObjectModifyResponse>
    <ID>test1</ID>
    <Success>true</Success>
</SecretObjectModifyResponse>

SecretObjectDeleteRequest

To delete a secret object.

<SecretObjectDeleteRequest>
    <ID>...</ID>
    <ObjectName>....</ObjectName>
</SecretObjectDeleteRequest>
Element Description
ID Contains the user-specified request ID.
ObjectName Name of the secret object.

SecretObjectDeleteResponse

Server response to SecretObjectDeleteRequest.

<SecretObjectDeleteResponse>
    <ID>.....</ID>
    <Success>.....</Success>
</SecretObjectDeleteResponse>

Example:

<SecretObjectDeleteRequest>
    <ID>Id</ID>
    <ObjectName>Secret_Object_1</ObjectName>
</SecretObjectDeleteRequest>
<SecretObjectDeleteResponse>
    <ID>Id</ID>
    <Success>true</Success>
</SecretObjectDeleteResponse>