Using Opaque and Secret Objects

  • Updated on Apr 2, 2025
  • Published on Jul 24, 2024
  • 5 minute(s) read

1.0 Definitions

1.1 Opaque Objects

In addition to keys for the algorithms such as AES, ECDSA, ECDH, RSA, DES, and so on described in Algorithm Support, Fortanix-Data-Security-Manager (DSM) has the ability to store “opaque” objects. An opaque object can be used to store arbitrary data, which may or may not be sensitive. Fortanix DSM does not perform cryptographic operations using opaque objects, but clients can fetch the value of the opaque object from Fortanix DSM.

For information on key-value pairs, refer to User's Guide: Plugin Library.

NOTE

These security objects have the Export permission turned on by default.

Possible uses of opaque objects include:

  • Storing passwords or other non-cryptographic secrets

  • Storing keys for algorithms not natively supported by Fortanix DSM

1.2 Secret Objects

A Secret type of Security-object is used to store a secret value that is not a key or certificate. For example, passphrase, password, and so on.

2.0 Fortanix Data Security Manager Secret Objects vs Opaque Objects

The following table highlights the differences and similarities between an Opaque and a Secret Object.

SECRET OBJECTS

OPAQUE OBJECTS

Definition

A Secret type of security object is used to store a secret value that is not a key or certificate. For example: passphrase, password, and so on.

An Opaque type of security object is used to store arbitrary data, which may or may not be sensitive.

Audit logging support

Yes

Accessing the values of Secret objects is audit logged.

No

Maximum size supported

512 kilobytes

512 kilobytes

Can be imported using the web interface

Yes

Yes

Crypto operations support

No

No

By default, import operation stores the object as an exportable security object

Yes

Yes

3.0 Opaque Objects Using API

3.1 Log in to Fortanix Data Security Manager

Log in to Fortanix Data Security Manager using the following command:

curl -X POST "https://<fortanix_dsm_url>/sys/v1/session/auth" \
-u :PASS

The command above will generate the following response:

{
"token_type":"Bearer","expires_in":3600,"access_token":"wO9gVTTESKyCpdF-CnoOA-WLqEzaCDzQiCMNxOidtM-7MNmp0PhZU5xZSPgWj2yBzfxhsT-N4tpoep8HAH_Ejg","entity_id":"b4ff897f-97be-4cac-b7d3-878ea5d5a652"
}

3.2 Select Account

Select the account using the following command:

curl -X POST "https://<fortanix_dsm_url>/sys/v1/session/select_account" \ 
-H "Authorization: Bearer i7iy-bt9dXXHmQ0DDDTfeKJomNwu7XTN9edpOUhJpP7dQvIpcZt2wfvWjXn93XfHsZ2yavaopetVxDIAdb9H3Q" \ 
-d "{\"acct_id\": \"c86838af-70cb-48d7-81b5-b7c38c152412\"}"

The command above will generate the following response:

{
 "cookie":"sdkms_admin_auth=; Domain=<fortanix_dsm_url>; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Secure"
 }

3.3 Import an Opaque Object

To create an opaque security object, use the API:

curl -X PUT "https://<fortanix_dsm_url>/crypto/v1/keys" \
-H "Authorization: Bearer i7iy-bt9dXXHmQ0DDDTfeKJomNwu7XTN9edpOUhJpP7dQvIpcZt2wfvWjXn93XfHsZ2yavaopetVxDIAdb9H3Q" \
-d "{\"name\" : \"opq1\", \"obj_type\" : \"OPAQUE\", \"value\": \"<base64 encoded phrase>\", \"group_id\": \"5b623820-f980-46c6-9512-5058b61840f8\"}"

In the specification above,

<base64 encoded phrase>: is a base64 encoded string for your passphrase/secrets. For example: 01.

name: Name of the security object to create or import. Security object names must be unique within an account.

object_type: Type of security object. The default value is "OPAQUE".

value: When importing a security object, this field contains the binary contents to import. When creating a security object, this field is unused. The value of an OPAQUE or CERTIFICATE object is always returned. For other objects, the value is returned only with /crypto/v1/keys/export API (if the object is exportable).

The code snippet above returns the following response containing the key_id (kid).

{
 "acct_id": "c86838af-70cb-48d7-81b5-b7c38c152412",
 "activation_date": "20191127T063211Z",
 "created_at": "20191127T063211Z",
 "creator": {
 "user": "b4ff897f-97be-4cac-b7d3-878ea5d5a652"
 },
 "enabled": true, 
 "key_ops": [
 "EXPORT",
 "APPMANAGEABLE"
 ],
 "key_size": 8,
 "kid": "14f7b611-f886-4328-9e93-2aff20daff33",
 "lastused_at": "19700101T000000Z",
 "name": " opq1",
 "never_exportable": false,
 "obj_type": "OPAQUE",
 "origin": "External",
 "public_only": false,
 "state": "Active",
 "group_id": "5b623820-f980-46c6-9512-5058b61840f8"
}

3.4 Export the Value of Opaque Object

To export the value of opaque object, use the API:

curl -X GET "https://<fortanix_dsm_url>/crypto/v1/keys/ffa75177-019f-4602-9038-f0971c2eea45" \
-H "Authorization: Bearer 8k3EfJrEYD0IkmP08llvM83x93RTtSOvdHmB99h9Zsu80WKcVLgtQYvUDwfEqcimZMEee1_2SzUaKlPFJ6cjsw"

The command above will return the following response:

{
 "acct_id": "c86838af-70cb-48d7-81b5-b7c38c152412",
 "activation_date": "20191113T122032Z",
 "created_at": "20191113T122032Z",
 "creator": {
 "user": "b4ff897f-97be-4cac-b7d3-878ea5d5a652"
 },
 "enabled": true,
 "key_ops": [
 "EXPORT",
 "APPMANAGEABLE"
 ],
 "key_size": 8,
 "kid": "ffa75177-019f-4602-9038-f0971c2eea45",
 "lastused_at": "19700101T000000Z",
 "name": "opq1",
 "never_exportable": false,
 "obj_type": "OPAQUE",
 "origin": "External",
 "public_only": false,
 "state": "Active",
 "value": "0w==",
 "group_id": "5b623820-f980-46c6-9512-5058b61840f8"
}

The command above returns the value of the opaque object.

4.0 Secret Object Using API

4.1 Log in to Fortanix Data Security Manager

Log in to Fortanix Data Security Manager using the following command:

curl -X POST "https://<fortanix_dsm_url>/sys/v1/session/auth" \
-u :PASS

The command above will generate the following response:

{
"token_type":"Bearer","expires_in":3600,"access_token":"wO9gVTTESKyCpdF-CnoOA-WLqEzaCDzQiCMNxOidtM-7MNmp0PhZU5xZSPgWj2yBzfxhsT-N4tpoep8HAH_Ejg","entity_id":"b4ff897f-97be-4cac-b7d3-878ea5d5a652"
}

4.2 Select Account

Select the account using the following command:

curl -X POST "https://<fortanix_dsm_url>//sys/v1/session/select_account" \
 -H "Authorization: Bearer i7iy-bt9dXXHmQ0DDDTfeKJomNwu7XTN9edpOUhJpP7dQvIpcZt2wfvWjXn93XfHsZ2yavaopetVxDIAdb9H3Q" \
 -d "{\"acct_id\": \"c86838af-70cb-48d7-81b5-b7c38c152412\"}"

The command above will generate the following response:

{
 "cookie":"sdkms_admin_auth=; Domain=<fortanix_dsm_url>; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Secure"
 }

4.3 Import a Secret Object

To create a Secret security object, use the API:

curl -X PUT "https://<fortanix_dsm_url>/crypto/v1/keys" \
-H "Authorization: Bearer i7iy-bt9dXXHmQ0DDDTfeKJomNwu7XTN9edpOUhJpP7dQvIpcZt2wfvWjXn93XfHsZ2yavaopetVxDIAdb9H3Q" \
-d "{\"name\" : \"opq1\", \"obj_type\" : \"SECRET\", \"value\": \"\", \"group_id\": \"5b623820-f980-46c6-9512-5058b61840f8\"}"

In the specification above,

<base64 encoded phrase>: is a base64 encoded string for your passphrase/secrets. For example: 01.

name: Name of the security object to create or import. Security object names must be unique within an account.

object_type: Type of security object. The default value is "SECRET".

value: When importing a security object, this field contains the binary contents to import. When creating a security object, this field is unused. The value of an OPAQUE or CERTIFICATE object is always returned. For other objects, the value is returned only with /crypto/v1/keys/export API (if the object is exportable).

The code snippet above returns the following response containing the key_id (kid).

{
 "acct_id": "c86838af-70cb-48d7-81b5-b7c38c152412",
 "activation_date": "20191127T063211Z",
 "created_at": "20191127T063211Z",
 "creator": {
 "user": "b4ff897f-97be-4cac-b7d3-878ea5d5a652"
 },
 "enabled": true, 
 "key_ops": [
 "EXPORT",
 "APPMANAGEABLE"
 ],
 "key_size": 8,
 "kid": "14f7b611-f886-4328-9e93-2aff20daff33",
 "lastused_at": "19700101T000000Z",
 "name": " secret_obj",
 "never_exportable": false,
 "obj_type": "SECRET",
 "origin": "External",
 "public_only": false,
 "state": "Active",
 "group_id": "5b623820-f980-46c6-9512-5058b61840f8"
}

4.4 Export the Value of Secret Object

To export the value of the secret object, use the API:

curl -X POST "https://<fortanix_dsm_url>/crypto/v1/keys/export" \
-H "Authorization: Bearer i7iy-bt9dXXHmQ0DDDTfeKJomNwu7XTN9edpOUhJpP7dQvIpcZt2wfvWjXn93XfHsZ2yavaopetVxDIAdb9H3Q" \
-d "{\"name\": \"secret_obj\"}"

The command above will return the following response:

{
 "acct_id": "c86838af-70cb-48d7-81b5-b7c38c152412",
 "activation_date": "20191113T122032Z",
 "created_at": "20191113T122032Z",
 "creator": {
 "user": "b4ff897f-97be-4cac-b7d3-878ea5d5a652"
 },
 "enabled": true,
 "key_ops": [
 "EXPORT",
 "APPMANAGEABLE"
 ],
 "key_size": 8,
 "kid": "14f7b611-f886-4328-9e93-2aff20daff33",
 "lastused_at": "19700101T000000Z",
 "name": "secret_obj",
 "never_exportable": false,
 "obj_type": "SECRET",
 "origin": "External",
 "public_only": false,
 "state": "Active",
 "value": "0w==",
 "group_id": "5b623820-f980-46c6-9512-5058b61840f8"
}

The command above returns the value of the secret object.

5.0 Opaque Objects Using Fortanix Data Security Manager-CLI

5.1 Log in to Fortanix Data Security Manager

Log in to Fortanix DSM using the following command:

sdkms-cli user-login --username <dsm-username> --account-name <dsm-account-name>

5.2 Import an Opaque Object

To create an opaque object, use the following command:

sdkms-cli import-secret --in <opaque-object-path> --name <name> --obj-type OPAQUE --group-id <group-id>  

5.3 Export an Opaque Object

To export an opaque object, use the following command:

sdkms-cli export-object --kid <security-object-uuid>

6.0 Secret Objects Using Fortanix Data Security Manager-CLI

6.1 Log in to Fortanix Data Security Manager

Log in to Fortanix DSM using the following command:

sdkms-cli user-login --username <dsm-username> --account-name <dsm-account-name>

6.2 Import a Secret Object

To create a secret object, use the following command:

sdkms-cli import-secret --in <secret-object-path> --name <name> --obj-type SECRET --group-id <group-id>

6.3 Export a Secret Object

To export a secret object, use the following command:

sdkms-cli export-object --kid <security-object-uuid>