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.

Note

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:

Import secret object (see SecretObjectImportRequest)
Export secret object (see SecretObjectExportRequest)
Retrieve information about a secret object (see SecretObjectInfoRequest)
Modify a secret object (see SecretObjectModifyRequest)
Delete a secret object (see SecretObjectDeleteRequest)

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

Caution

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

Suggest A Change

Secret Management Operations

SecretObjectImportRequest

SecretObjectImportResponse

Example

SecretObjectExportRequest

SecretObjectExportResponse

Example

SecretObjectInfoRequest

SecretObjectInfoResponse

Example

Example - Requesting information of a object using UUID

SecretObjectModifyRequest

SecretObjectModifyResponse

Example 1

Example 2

SecretObjectDeleteRequest

SecretObjectDeleteResponse

On this page