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.

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

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.

  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

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>

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> 

Export an Opaque Object

To export an opaque object, use the following command:

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

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

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>

Export a Secret Object

To export a secret object, use the following command:

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

Comments

Please sign in to leave a comment.

Was this article helpful?
0 out of 0 found this helpful