Keys

Keys are similar to SafeNet KeySecure Classic keys, with a few differences. Keys can be created, modified, imported, exported, and deleted. Keys can be symmetric or asymmetric, variable sizes, and can be constrained to particular usages.

Some of these curves have multiple names chosen by different standards organizations, as described in RFC 4492, although CipherTrust Data Security Platform Service only supports the names listed above.

Supported Key Formats

Supported key formats for REST API.

Secrets

In addition, secret objects and opaque objects are also managed through the Keys menu in the UI. These managed objects are available through the ksctl secret commands in the CLI, and v1/vault/secrets endpoints in the REST API.

Secrets are managed objects that can store user defined data. This data can be a blob, a password, or a seed. There are two types of objects used to store secrets: a "Secret Object" and an "Opaque Object". Secrets support many of the same attributes that keys do.

Create a key

A key can be created using the GUI, KSCTL, or API.

To create a key using KSCTL, execute the command:

ksctl keys create –alg AES --name “testAESkey”

The response looks like:

{
  "id": "f0c2b40017dca0cdbbda90e2d224d0dcb4488ec412e156a594af3bc11a879b1a",
  "uri": "kylo:kylo:vault:keys:testaeskey-v0",
  "account": "kylo:kylo:admin:accounts:kylo",
  "application": "ncryptify:gemalto:admin:apps:kylo",
  "devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
  "createdAt": "2018-04-23T17:57:15.899060389Z",
  "name": "testAESkey",
  "updatedAt": "2018-04-23T17:57:15.899060389Z",
  "usage": "blob",
  "usageMask": 12,
  "meta": {
    "ownerId": "local|ee328ec6-f37b-4e9c-85be-8867120b6b79"
  },
  "algorithm": "AES",
  "size": 256,
  "format": "raw",
  "unexportable": false,
  "undeletable": false,
  "defaultIV": "3ddc71eea888f8ec554b63759f371af9",
  "objectType": "Symmetric Key",
  "activationDate": "2018-04-23T17:57:15.886182496Z",
  "state": "Active",
  "keyCheckValue": "1f43a0"
}

Computing Key Check Value on CipherTrust Data Security Platform Service

For AES and TDES keys, the key checksum value (KCV) is computed by performing an encryption operation on a set of empty bytes.

The key check value is computed by encrypting 8 bytes for DES and 16 bytes for AES, each with null (0x00) bytes, with the key to be checked using the default cipher and mode (for example, ECB) and retaining the 3 highest-order bytes of the encrypted result.

Use the following command to get the Key Check Value for any symmetric AES or TDES keys. The object is specified by the key name or ID.

ksctl keys generate-kcv --name mykey

Configuring Key Rotation Frequency Days

The key rotation frequency days defines the number of days from key creation date to rotate the key. It should be greater than or equal to 0. Default is an empty string. If rotation-frequency-days is set to "0", the rotation-frequency-days will set to an empty string and auto rotation of the key will be disabled.

The upper limit for key rotation frequency days is 99999 days.

For more details, refer to Default Schedulers.

Example (Key Create)

ksctl keys create --name 'rotation_test' --rotation-frequency-days "5"

Response

{
    "id": "a5b10dded7d7471c96d0a7cc7240ce365678389075c54f82aede433dbfe075ce",
    "uri": "kylo:kylo:vault:keys:rotation-test-v0",
    "account": "kylo:kylo:admin:accounts:kylo",
    "application": "ncryptify:gemalto:admin:apps:kylo",
    "devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
    "createdAt": "2024-01-19T09:30:42.640298Z",
    "name": "rotation_test",
    "updatedAt": "2024-01-19T09:30:42.640298Z",
    "usage": "blob",
    "usageMask": 12,
    "meta": {
        "ownerId": "local|fc4915ff-3d3c-434f-8902-54a7f923a285"
    },
    "version": 0,
    "algorithm": "AES",
    "size": 256,
    "unexportable": false,
    "undeletable": false,
    "neverExported": true,
    "neverExportable": false,
    "emptyMaterial": false,
    "defaultIV": "1c2de986ac51f7731752fa3a2cf17da0",
    "sha1Fingerprint": "7ef3475b6c0d9891",
    "sha256Fingerprint": "98606d4b2e75ce40995c993bf1e2ecfb8343e06c5402883317bb763180daf6e7",
    "objectType": "Symmetric Key",
    "activationDate": "2024-01-19T09:30:42.638279Z",
    "scheduledRotationDate": "2024-01-24T09:30:42.638791218Z",
    "rotationFrequencyDays": "5",
    "state": "Active",
    "aliases": [
        {
            "alias": "rotation_test",
            "type": "string",
            "index": 0
        }
    ],
    "uuid": "c3d10d41-e65f-4e62-8381-c5df1004651e",
    "muid": "c3d10d41-e65f-4e62-8381-c5df1004651ed64e5c8d-3942-4593-ae54-9d80552dc078",
    "keyCheckValue": "4bb0ed"
}

Example (Key Update)

ksctl keys modify --name 'rotation_test' --rotation-frequency-days "10"

Response

 {
    "id": "5406bfa581ed4059a4d11caf8d081d27465681a2b3ca45a1b30d4b8e4ed73a3b",
    "uri": "kylo:kylo:vault:keys:rotation-test-v0",
    "account": "kylo:kylo:admin:accounts:kylo",
    "application": "ncryptify:gemalto:admin:apps:kylo",
    "devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
    "createdAt": "2024-04-22T06:22:13.805753Z",
    "name": "rotation_test",
    "updatedAt": "2024-04-22T06:23:00.824459Z",
    "activationDate": "2024-04-22T06:22:13.800364Z",
    "state": "Active",
    "scheduledRotationDate": "2024-05-02T06:22:13.805753Z",
    "rotationFrequencyDays": "10",
    "usage": "blob",
    "usageMask": 12,
    "meta": {
        "ownerId": "local|e72ec0c1-6e57-40ac-ace8-8a0bcf8db2ad",
        "permissions": {}
    },
    "objectType": "Symmetric Key",
    "aliases": [
        {
            "alias": "rotation_test",
            "type": "string",
            "index": 0
        }
    ],
    "sha1Fingerprint": "e4a574f3a53f114b",
    "sha256Fingerprint": "583480225a67b4c47e9aea74bb062aea5f4061fad299414b234ee2f69ed61bcc",
    "defaultIV": "cc4f89221c36f2286f569ff6d21176e6",
    "version": 0,
    "algorithm": "AES",
    "size": 256,
    "unexportable": true,
    "undeletable": true,
    "neverExported": true,
    "neverExportable": true,
    "emptyMaterial": false,
    "uuid": "dcfdefe6-388f-4078-97a3-513a50db1782",
    "muid": "dcfdefe6-388f-4078-97a3-513a50db17827db3f0a9-aad1-4b57-9fe8-f2cc87ef3764",
    "keyCheckValue": "b23bd4"
}

Setting Key Permissions

User groups can be granted permissions to perform operations with a particular key such as read, encrypt, and decrypt data. You can set key permissions on the Key Access section of a key's detail page or in the Meta tab. This is done after creation.

Key permissions act at the group level. The Key Usage settings set at creation, and modifiable under the KMIP tab in key details act at the key level. This means that if a key's Key Usage does not allow encryption, no group can encrypt with that key, no matter what Key Permissions are granted to the group.

Key permissions can be set using the GUI, KSCTL, or API.

To set key permissions using the GUI

1. Log on to the CipherTrust Data Security Platform Service console as administrator.

2. Open the Keys application.

3. Under Key Name column, click the key name link. The key details are displayed.

4. Expand the Key Access section.

5. Click General.

6. Change the Key Owner, if desired, from the dropdown.

7. Check or uncheck permissions for the listed groups. You can search for a group by name.

   • In the General tab you can check or uncheck Read, Use,Decrypt, Sign, Verify or All.

8. Click Update.

Making Keys Exportable or Deletable

You can control whether a key can be exported or deleted.

1. Log on to the CipherTrust Data Security Platform Service console as a user in the Key Admin or admin group, such as the admin user.

2. Open the Keys application.

3. Under Key Name column, click the key name link. The key details are displayed.

4. To enable or disable export for the key, click Exportable toggle near the top of the screen.

5. To enable or disable deletion for the key, click the Deletable toggle near the top of the screen.

In the example image below, the key is set to be both exportable and deletable.

Key States

A key can be in any of the following states at any given time:

• Pre-Active: The key exists, but should not be used for any cryptographic purpose.

• Active: By default, the key can be used for any cryptographic purpose.

  You can set the Protect Stop Date to a date in the past to restrict the key's usage to decryption, signature verification, unwrapping, and MAC verification operations. You can also reactivate to unset a Protect Stop Date that has passed and restore all cryptographic operations. These key state changes are available through the REST API and CLI interfaces.

• Deactivated: The key cannot be used for cryptographic operations. You can reactivate a deactivated key through the REST API and CLI interfaces.

• Compromised: The key should not be used for cryptographic operations such as encryption, signing, wrapping, MACing, and deriving. The key should only be used for decryption, signature verification, unwrapping, and MAC verification.

• Destroyed: The key should not be used for any cryptographic purpose.

• Destroyed Compromised: The key should not be used for any cryptographic purpose. Its compromised status should be retained for audit or security purposes.

You can set the Protect Stop Date to restrict or allow encryption, signing, wrapping, and MAC operations. In addition, you can reactivate a key to re-enable all or some cryptographic operations.

Besides reactivation, state transitions conform to the 1.4 KMIP specification.

Reactivate a Key

You can reactivate a key with the REST API /v1/vault/keys2/{id}/reactivate endpoint (described in the API playground), or the ksctl keys reactivate command.

There are three state transitions that occur through reactivation.

• Deactivated To Active: This returns a Deactivated key to an Active state without setting a Protect Stop Date. All cryptographic operations are allowed.

  Example CLI command:

  ksctl keys reactivate --name <key-id> --type name --reasontoreactivate DeactivatedToActive
  

  • Active Protect Stop to Active: This removes a Protect Stop Date for Active keys, if the Protect Stop Date has passed. All cryptographic operations are allowed.

  Example CLI command:

  ksctl keys reactivate --name <key-id> --type name --reasontoreactivate ActiveProtectStopToActive
  

  • Deactivated to Active with Protect Stop: This returns a Deactivated key to an Active state and sets the Protect Stop date to the current time. Decryption, signature verification, unwrapping, and MAC verification are allowed.

  Example CLI command:

  ksctl keys reactivate --name <key-id> --type name --reasontoreactivate DeactivatedToActiveProtectStop
  

Effects of Negative Actions on Keys

When you delete, destroy, revoke, or archive a key, the following happens:

• Delete: The key is deleted from the database altogether, including the key metadata and key material.

• Destroy: The key material is deleted from the database, while the key metadata is kept.

• Revoke: The key state is set depending on the provided revocation reason. A revocation reason of "key compromise" or "CA compromise" results in a key state of "Compromised". Any other revocation reason results in a key state of "Deactivated". The key material is available on the server.

  • Deactivated keys cannot be used for any cryptographic operation.

  • Compromised keys can be used only for decryption, signature verification, unwrapping, and MAC verification. They cannot be used for encryption, signing, wrapping, MACing, and deriving.

• Archive: The key cannot be used for any cryptographic operations. Later the key can be recovered and used or modified, as required.