Using Opaque and Secret Objects

1.0 Definitions

1.1 Opaque Objects

In addition to keys for algorithms such as AES, ECDSA, ECDH, RSA, DES, and others as described in Algorithm Support, Fortanix-Data-Security-Manager (DSM) can store “opaque” objects.

An Opaque object is a type of security object used to store arbitrary data, that Fortanix DSM does not interpret or process cryptographically. Opaque objects are treated as non-secret data by Fortanix DSM and are intended for scenarios where data must be stored and retrieved exactly as provided.

Fortanix DSM does not perform cryptographic operations using opaque objects. Clients can retrieve the value of an opaque object directly using a GET operation.

NOTE
Opaque objects should not be used to store passwords, cryptographic keys, secrets, or other sensitive data.
Their values can be retrieved directly and are not protected in the same way as Secret objects.

Opaque objects are suitable for storing non-sensitive data, such as:

Application metadata or identifiers.
Configuration blobs or reference data.
Arbitrary data that must be fetched exactly as stored.

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, a passphrase, a password, and so on. Their values are only retrievable through the Export API, and such access is audit logged.

2.0 Fortanix DSM 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, not for secret management.
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
Permissions to retrieve the value of the object	Users require the `GET_SOBJECTS` permission. Applications do not require special permissions.	Users require the `EXPORT_SOBJECTS` permission. Applications require `EXPORT` permissions to retrieve secret objects..

3.0 Opaque Objects Using API

3.1 Log in to Fortanix DSM

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 DSM

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

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

5.1 Log in to Fortanix DSM

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

6.1 Log in to Fortanix DSM

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>