Your suggested change has been received. Thank you.

close

Suggest A Change

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

Thales Logo

All

  • All
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)
aria128, 192, 256*
seed128*
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 Curves (ec) (size is defined by the curve)
brainpoolP224r1brainpoolP224t1brainpoolP256r1brainpoolP256t1
brainpoolP384r1brainpoolP384t1brainpoolP512r1brainpoolP512t1
prime256v1secp224k1secp224r1secp256k1
secp384r1secp521r1curve25519

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.

Note

A key name should not contain special characters such as angular brackets (<,>) and backslash (\).

Note

The CipherTrust Manager checks and corrects the parity bits (in each byte, the least significant bit is an odd-parity generated bit) of the triple DES key. Note that there can exist keys represented by different materials, producing identical ciphertext for the same plaintext input, as their parity bits can be modified without affecting the encryption bits.

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

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.

Note

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",
  "keyCheckValue": "1f43a0"
}

Create Keys using Template

Keys can be created using templates by providing the template id in the request. The key parameters present in the template are used to create a key. Users can also provide parameters in the key create request with the template id.

To create a key using the template:

Syntax

ksctl keys create --name <template-name> --templateId <templateId>

Example Request

ksctl keys create --name "TemplateKey" --templateId "63da49f4-422c-4a88-8af0-b66a15ebaad0"

Example Response

{
    "id": "13b1564fcede4f59b285fe323f383b32d6f088e7850b4f95bc49a2d6ee50f9a1",
    "uri": "kylo:kylo:vault:keys:templatekey-v0",
    "account": "kylo:kylo:admin:accounts:kylo",
    "application": "ncryptify:gemalto:admin:apps:kylo",
    "devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
    "createdAt": "2024-05-01T10:24:21.429179Z",
    "name": "TemplateKey",
    "updatedAt": "2024-05-01T10:24:21.429179Z",
    "usage": "blob",
    "usageMask": 12,
    "meta": {
        "ownerId": "local|f718b511-0a3e-4a1f-b390-ec0d285b40d1"
    },
    "version": 0,
    "algorithm": "AES",
    "size": 256,
    "unexportable": false,
    "undeletable": false,
    "neverExported": true,
    "neverExportable": false,
    "emptyMaterial": false,
    "defaultIV": "d4ab6cc1c9c63900d0e8e14903986a5c",
    "sha1Fingerprint": "13f68100c120c731",
    "sha256Fingerprint": "8b45bf4ba07790c81b65fe5714a50c35d390a41264f727e6c3cc099ff319326c",
    "objectType": "Symmetric Key",
    "activationDate": "2024-05-01T10:24:21.422291Z",
    "state": "Active",
    "aliases": [
        {
            "alias": "TemplateKey",
            "type": "string",
            "index": 0
        }
    ],
    "uuid": "2c6cca78-195d-470f-a710-b80b80fc22b8",
    "muid": "2c6cca78-195d-470f-a710-b80b80fc22b842f6dae1-f235-471b-97f6-d772bf793cae",
    "keyCheckValue": "ea8324"
}

The parameters defined in the key create request and template takes precedence based on the access level of the user.

  • Privileged users

  • Restricted users

Privileged Users

Privileged users are members of Key Users/Key Admins/Admins groups. For privileged users, the precedence is given to the parameters defined in the key creation request over template parameters. The different parameters present in both key create request and template are merged. For Example, if a template is created for the AES Key and the key create request has the algorithm set to the RSA key. The preference will be given to the key create request parameters.

Example Request

ksctl keys create --name "TemplateKey_PriviledgedUser" --templateId "63da49f4-422c-4a88-8af0-b66a15ebaad0" --alg "RSA" --size 2048

Example Response

{
    "id": "e481e59d64394056ab35f8e9fe5b01cd9882d48a81424239b2e4682247eecc62",
    "uri": "kylo:kylo:vault:keys:templatekey-priviledgeduser-v0",
    "account": "kylo:kylo:admin:accounts:kylo",
    "application": "ncryptify:gemalto:admin:apps:kylo",
    "devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
    "createdAt": "2024-05-01T10:26:51.105523Z",
    "name": "TemplateKey_PriviledgedUser",
    "updatedAt": "2024-05-01T10:26:51.105523Z",
    "usage": "sign",
    "usageMask": 3,
    "meta": {
        "ownerId": "local|651c9169-6923-44cb-9745-fcb1a76eae50"
    },
    "version": 0,
    "algorithm": "RSA",
    "size": 2048,
    "unexportable": false,
    "undeletable": false,
    "neverExported": true,
    "neverExportable": false,
    "emptyMaterial": false,
    "publickey": "-----BEGIN PUBLIC KEY-----\nMIIB....N3y2n0d+Yjo/2OT9cCqNd2\nZwIDAQAB\n-----END PUBLIC KEY-----\n",
    "defaultIV": "fa63563ad4cd74268791d1dde384e28f",
    "sha1Fingerprint": "97a31b5a79418acc",
    "sha256Fingerprint": "0edb2b708ff8318dfc34cdd4a186e4501ca195608a252487d29738e90680cd99",
    "objectType": "Private Key",
    "activationDate": "2024-05-01T10:26:50.855956Z",
    "state": "Active",
    "aliases": [
        {
            "alias": "TemplateKey_PriviledgedUser",
            "type": "string",
            "index": 0
        }
    ],
    "links": [
        {
            "id": "26268b74-6a98-47f4-95bb-9d8ea2cd615b",
            "uri": "kylo:kylo:vault:links:26268b74-6a98-47f4-95bb-9d8ea2cd615b",
            "account": "kylo:kylo:admin:accounts:kylo",
            "application": "ncryptify:gemalto:admin:apps:kylo",
            "devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
            "createdAt": "2024-05-01T10:26:51.124271Z",
            "updatedAt": "2024-05-01T10:26:51.124271Z",
            "type": "publicKey",
            "source": "kylo:kylo:vault:keys:templatekey-priviledgeduser-v0",
            "sourceID": "e481e59d64394056ab35f8e9fe5b01cd9882d48a81424239b2e4682247eecc62",
            "target": "kylo:kylo:vault:keys:templatekey-priviledgeduser-pub-v0",
            "targetID": "b0110e3865574ec6ab599dab42a40e6d4379b7f1a4894bfeaa5bfca34128258b",
            "index": 0
        }
    ],
    "uuid": "c4d9f61d-4caf-4f63-b18e-93c6a504f124",
    "muid": "c4d9f61d-4caf-4f63-b18e-93c6a504f124b2e99c95-308b-4e42-bb1f-641e23cd9d34"
}

In the above example, the parameters defined in the key create request (alg "RSA", size 2048) take precedence over the template parameters.

Restricted Users

Restricted users are members of the "Restricted Key Users" group. For restricted users, precedence is given to the template parameters over key create request parameters. The different parameters present in both key create request and template are merged. The key parameters allowed for restricted users in the key create request are:

  • name

  • description

  • labels

  • aliases

  • material

  • password

  • meta (only ownerId)

For Restricted users, the "ownerId" defined in the template meta needs to be the same as provided in the key create request meta.

Example Request

ksctl keys create --name "TemplateKey_RestrictedUser" --templateId "63da49f4-422c-4a88-8af0-b66a15ebaad0" --labels "sales=HR"

Example Response

{
    "id": "0b1b7fb3f006461a97bdc87aa4cf09613b3af0cda0ba4f7c8ac4518f24ee474e",
    "uri": "kylo:kylo:vault:keys:templatekey-restricteduser-v0",
    "account": "kylo:kylo:admin:accounts:kylo",
    "application": "ncryptify:gemalto:admin:apps:kylo",
    "devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
    "createdAt": "2024-05-01T10:30:42.867234Z",
    "name": "TemplateKey_RestrictedUser",
    "updatedAt": "2024-05-01T10:30:42.867234Z",
    "usage": "blob",
    "usageMask": 12,
    "meta": {
        "ownerId": "local|622e0a4b-7bf9-4cfb-9226-ae716c716401"
    },
    "version": 0,
    "algorithm": "AES",
    "size": 256,
    "unexportable": false,
    "undeletable": false,
    "neverExported": true,
    "neverExportable": false,
    "emptyMaterial": false,
    "defaultIV": "03675c4382fd4e5c95b2643e8ea27723",
    "sha1Fingerprint": "61692c6192f36490",
    "sha256Fingerprint": "d974fc99c6492305902f03b73c779fc2278382bc2ca3bad05a5edb728c75cd29",
    "objectType": "Symmetric Key",
    "activationDate": "2024-05-01T10:30:42.866576Z",
    "state": "Active",
    "aliases": [
        {
            "alias": "TemplateKey_RestrictedUser",
            "type": "string",
            "index": 0
        }
    ],
    "uuid": "a3ea8fc4-6d58-4c1e-b46d-ac8926f82cbb",
    "muid": "a3ea8fc4-6d58-4c1e-b46d-ac8926f82cbb5461e345-45e6-45e5-8522-4ded58096d25",
    "labels": {
        "sales": "HR"
    },
    "keyCheckValue": "e749d7"
}

Create Template with keyAttributes Meta

Example Request

ksctl templates create --name 'Test Template with Meta'  --desc 'Symmetric'  --labels 'sale=HR' --meta '{ "color":"Red"}' --key_attributes '{ "algorithm": "AES", "size": 256 , "meta" : { "team": "finance", "customAttributes": [ {  "name": "x-nae-attr", "value": "test" } ] }}'

Example Response

{
    "id": "5d24661e-a569-4c95-9891-1e7e56ddaee5",
    "uri": "kylo:kylo:vault:templates:test-template-with-meta-5d24661e-a569-4c95-9891-1e7e56ddaee5",
    "account": "kylo:kylo:admin:accounts:kylo",
    "createdAt": "2024-05-01T10:35:50.27364Z",
    "updatedAt": "2024-05-01T10:35:50.27364Z",
    "name": "Test Template with Meta",
    "description": "Symmetric",
    "meta": {
        "color": "Red"
    },
    "labels": {
        "sale": "HR"
    },
    "key_attributes": {
        "algorithm": "AES",
        "size": 256,
        "meta": {
            "team": "finance",
            "customAttributes": [
                {
                    "name": "x-nae-attr",
                    "value": "test"
                }
            ]
        }
    }
}

Restricted Key Users Meta Merge

Example Request

ksctl keys create --name "TemplateKey_RestrictedUser_1" --templateId "5d24661e-a569-4c95-9891-1e7e56ddaee5" --labels "sales=finance"

Example Response

{
    "id": "27f09b43042b466c84eeea39787d1ad9f3ef5ba3b9a941099d53f213d71fdb23",
    "uri": "kylo:kylo:vault:keys:templatekey-restricteduser-1-v0",
    "account": "kylo:kylo:admin:accounts:kylo",
    "application": "ncryptify:gemalto:admin:apps:kylo",
    "devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
    "createdAt": "2024-05-01T10:38:23.402756Z",
    "name": "TemplateKey_RestrictedUser_1",
    "updatedAt": "2024-05-01T10:38:23.402756Z",
    "usage": "blob",
    "usageMask": 12,
    "meta": {
        "customAttributes": [
            {
                "name": "x-nae-attr",
                "value": "test"
            }
        ],
        "ownerId": "local|622e0a4b-7bf9-4cfb-9226-ae716c716401",
        "team": "finance"
    },
    "version": 0,
    "algorithm": "AES",
    "size": 256,
    "unexportable": false,
    "undeletable": false,
    "neverExported": true,
    "neverExportable": false,
    "emptyMaterial": false,
    "defaultIV": "a1baa294a74d8ed751052211db771b83",
    "sha1Fingerprint": "7cc7a011183f699c",
    "sha256Fingerprint": "840be93c6e77874ac99a40ae8bfa6c6705c392778b0fd2da73ebc3ecbc49a34d",
    "objectType": "Symmetric Key",
    "activationDate": "2024-05-01T10:38:23.402178Z",
    "state": "Active",
    "aliases": [
        {
            "alias": "TemplateKey_RestrictedUser_1",
            "type": "string",
            "index": 0
        }
    ],
    "uuid": "6607ab8c-dfb3-484e-826b-a4cd841778ea",
    "muid": "6607ab8c-dfb3-484e-826b-a4cd841778ea691235e2-9af0-4ad1-8c66-da629be3e5f2",
    "labels": {
        "sales": "finance"
    },
    "keyCheckValue": "2ba6d4"
}

In the above example, you can see that meta is merged.

Computing Key Check Value on CipherTrust Manager

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

Note

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.

Note

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.

Note

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.

    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.

On this page