Using Opaque and Secret Objects

Definitions

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.

Possible uses of opaque objects include:

• Storing passwords or other non-cryptographic secrets
• Storing keys for algorithms not natively supported by Fortanix DSM

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.

Fortanix Data Security Manager Secret Objects vs Opaque Objects

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

Opaque Objects Using API

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 <user.name@company.com>: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"
}

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

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

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.

Secret Object Using API

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 <user.name@company.com>: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"
}

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

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\": \"<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 "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"
}

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.

Opaque Objects Using Fortanix Data Security Manager-CLI

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>

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

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

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

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

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