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.

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 `EXPORT_SOBJECTS` permission. Applications require `EXPORT` permissions to retrieve secret objects.	Users require the `GET_SOBJECTS` permission. Applications do not require special permissions.

3.0 Opaque Objects Using API

3.1 Log in to Fortanix DSM

Run the following command to 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

Run the following command to select the account:

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

Use the following API to create an opaque security object:

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>: It is base64 encoded string for your passphrase or 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

Use the following API to export the value of opaque object:

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

Run the following command to 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

Run the following command to select the account:

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

Use the following API to create a Secret security object:

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

5.1 Log in to Fortanix DSM

Run the following command to log in to Fortanix DSM:

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

5.2 Import an Opaque Object

Run the following command to create an opaque object:

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

5.3 Export an Opaque Object

Run the following command to export an opaque object:

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

6.0 Secret Objects Using Fortanix DSM-CLI

6.1 Log in to Fortanix DSM

Run the following command to log in to Fortanix DSM:

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

6.2 Import a Secret Object

Run the following command to create a secret object::

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

6.3 Export a Secret Object

Run the following command to export a secret object:

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