Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

back

CipherTrust Manager Administration

Keys

search

Please Note:

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.

AlgorithmSizes (* = default)
aes128, 192, 256*
tdes128, 192*
rsa512, 1024*, 2048, 3072, 4096
hmac-sha1>= 128, 160*
hmac-sha256128, 192, 256*
hmac-sha384192, 288, 384*
hmac-sha512256, 384, 512*

Supported Elliptic curve (ec) curves (size is defined by the curve): brainpoolP224r1, brainpoolP224t1, brainpoolP256r1, brainpoolP256t1, brainpoolP384r1, brainpoolP384t1, brainpoolP512r1, brainpoolP512t1, prime256v1, secp224k1, secp224r1, secp256k1, secp384r1, secp521r1.

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.

Object TypeKey Formats
Symmetric• raw
• opaque
Private Key• pkcs1
• pkcs8
• pkcs12
Public Key• pkcs1
• pkcs8
Certificate• pkcs12
• x.509
Opaque• raw
Secret• raw
Split Key• raw
Template• raw
PGP• raw

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.

To create a key

Key can be created using the GUI, KSCTL, or API.

The CTE keys must be:
• AES128, AES-256, ARIA-128, or ARIA-256
• Shared with the CTE Clients group
• Set as exportable
Only the clients that support the CBC CS1 encryption mode can have GuardPoints that use a policy with a CBC CS1 key.

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

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.

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.

The (versionedKey = true) flag can be created through the REST interface. Detailed documentation is available in the "API playground". To create the (versionedKey = true) flag via the GUI, under the Key Details page > NAE tab, enable the Versioned Key checkbox.

When using NAE, 'VersionedKey' information stored in KeySecure Classic and CipherTrust Manager cannot be exported by or imported from either product. If 'VersionedKey' must be set, it must be noted by the operator that it exists and turned on in the GUI after the import has occurred. An alternative to export/import is to run a migration from KeySecure Classic to the CipherTrust Manager as this operation preserves 'VersionedKey' information.

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.

NAE-XML KeyVersionStateEquivalent Key State(s)Allowed operations
Pre-activePre-activeNone
ActiveActive with Protect Stop Date unset, or set in the futureAny cryptographic operation
RestrictedActive with Protect Stop Date set in the past, CompromisedDecryption, signature verification, unwrapping, and MAC verification
RetiredDeactivatedNone
WipedDestroyed, DestroyedCompromisedNone

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.

You cannot reactivate a key through requests to the KMIP interface.

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.

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