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

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 Manager 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 or NAE depending on the interface you want to update.

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.

   • In the NAE tab you can check or uncheck Decrypt, Encrypt, 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 Manager 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.

Versioned Keys

KeySecure Classic

A KeySecure Classic versioned key is a key that maintains a single set of key metadata but contains multiple sets of key data. Each set of key data belongs to a unique version of the key.

A KeySecure Classic crypto operation using a versioned key prepends a header containing key version information to the resulting ciphertext. A crypto operation using an unversioned key does not prepend the ciphertext with this header.

CipherTrust Manager

The CipherTrust Manager handling of versioned keys depends on the interface used and the setting of key flag (versionedKey). For backward compatibility with KeySecure Classic, when the NAE-XML interface is used and if the key flag (versionedKey = true), the key is handled as a versioned key and the crypto operation prepends a header to the resulting ciphertext. When the REST interface is used, crypto operations always produce unadorned ciphertext with no header, as KeySecure Classic produces when using unversioned keys.

Similarly, if you perform the inverse crypto operations on the ciphertext encrypted using a versioned key such as decrypt or verify, the operation must be done via the NAE-XML interface, since the REST interface does not handle these header bytes.

To maintain backward compatibility with KeySecure Classic, when you create a key through the NAE-XML interface with the <Versioned/> element present, CipherTrust Manager server adds a flag to the key (versionedKey = true). This flag indicates that when the key is used via the NAE-XML interface, the key should behave like a legacy NAE-XML versioned key (i.e. the produced ciphertext results that contain the legacy header bytes). This internal flag is only honored when the key is used via the NAE-XML interface; the flag has no effect on REST interface interactions.

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.

Equivalencies to NAE States

As of CipherTrust Manager version 2.5, all values for the <KeyVersionState> element in the NAE-XML interface map directly to the above key states. Changing a key state in the KMIP, REST API, GUI, or CLI results in a <KeyVersionState> change in NAE-XML. Similarly, changing <KeyVersionState> in NAE-XML results in a key state change in KMIP, REST API, GUI and CLI.

The following table shows the equivalent key states to the NAE-XML <KeyVersionState> element.

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
  

  To cause the same state transition in the NAE-XML interface, change the <KeyVersionState> element from Retired to Active.

• 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
  

  To cause the same state transition in the NAE-XML interface, change the <KeyVersionState> element from Restricted to Active.

• 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
  

  To cause the same state transition in the NAE-XML interface, change the <KeyVersionState> element from Retired to Restricted.

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.

  Note

  • Only CTE Administrators (users of the CTE Admins group) can delete the CTE keys.

  • An in-use CTE key cannot be deleted. Before you delete a CTE key, make sure that no key rule is using the key.

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