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.

Create a New Key Through ksctl CLI

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 a New key Using a Template Through the ksctl CLI

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.

Create a New Key Through the Web Console UI

1. Login to the desired CipherTrust Manager domain.

2. Navigate to Keys.

3. Click + Add Key.

   The Add Key dialog displays.

4. (Optional) Provide a Key Name, Description, one or more Aliases, one or more Alternative Names, and one or more Key Labels. If you don't provide a key name, one will be auto-generated.

5. (Optional) Provide a key template, if desired. A key template must already exist.

   1. Enable the Create with key template checkbox.

   2. Click Choose to browse for key templates.

      A window launches displaying the available templates.

   3. Browse through the list or type the template name in the search box to find the desired template.

   4. Select the radio button next to the desired template name, and click Select.

      You are returned to the Add Key dialog.

      The template auto-fills values for Algorithm, Size/Curve, Key Properties, and Key Usage in the rest of the Key Usage dialog.

6. Click Next.

   The Key Attributes section is displayed.

7. Specify the Object Type to create.

   • Symmetric Key includes AES, TDES, HMAC, ARIA, or SEED keys.

   • "Public/Private Key Pair includes RSA and EC keys.

8. Click Generate Key Material.

9. If you have not used a key template, or if you are signed in as a privileged user and want to override key template values, specify more values. Otherwise, skip to step 11.

   Note

   If you are signed in as a restricted user and have provided a key template, you cannot edit these values, and are immediately directed to review the key values. CipherTrust Manager applies the key template parameters in this case.

   1. Select an Algorithm from the dropdown. For most algorithms, you must also select a Size from the dropdown. For EC key type, you select a Curve.

   2. You can optionally provide Key Properties.

   3. You can optionally provide Key Usage.

10. Click Next.

11. Review your selections. Click Back or Edit to modify any selection. Click Add Key to confirm.

    The key details page is displayed.

Importing an Existing Key or Certificate through the Web Console UI

Only privileged users can import existing keys or certificates into a CipherTrust Manager domain. A key template is optional.

You can import plaintext keys/certificates (unencrypted), or keys/certificates wrapped (encrypted) with another key. Supported key types for import are AES, TDES, HMAC, RSA, EC, ARIA, or SEED. The supported certificate format for import is X.509 with DER or PEM encoding.

Wrapping a Key for Import

If you choose to import a wrapped key, the wrapping key must be present on CipherTrust Manager. You can use a wrapping key with a supported wrapping key algorithm generated on CipherTrust Manager or generated externally. The high-level wrapping process varies based on your choice:

• CipherTrust Manager-generated wrapping key: Export the wrapping key to the location of the desired key, use the wrapping key to wrap the desired key, and import the wrapped key.

• External wrapping key: Use the wrapping key to wrap the desired key, import the wrapping key to CipherTrust Manager, and import the wrapped key.

Supported wrapping key algorithms are AES128, AES192, AES256, RSA2048, RSA3072, or RSA4096. Supported wrapping methods are AES key wrap, AES key wrap with padding, RSA encryption, and RSA AES key wrap with padding, depending on which key type you are wrapping.

There are performance and convenience considerations for each wrapping method. In general, AES wrapping methods are faster and require less processing power than RSA encryption. However, there are more steps involved to securely transfer an AES key between CipherTrust Manager and an external system as compared to an RSA key.

We have the following guidelines to help you plan secure and efficient key wrapping outside of CipherTrust Manager.

• Generate the wrapping key on CipherTrust Manager. CipherTrust Manager's key generation uses high-quality, trusted entropy sources.

• Use CipherTrust Application Data Protection (CADP) to wrap keys on external systems. The following pages demonstrate key wrapping on each CADP client type.

  • Wrapping keys with CADP for C

  • Wrapping keys with CADP for Java

  • Wrapping keys with CADP for .NET Core

• For a one-time import of less than a hundred symmetric keys, use RSA encryption. Generate an RSA key pair on CipherTrust Manager, export the public to the other system, wrap the symmetric keys, and import the wrapped keys. CipherTrust Manager can decrypt the key material with the private RSA key already present.

• If you are importing more than a hundred keys, or you expect to import keys repeatedly, use AES key wrap or AES key wrap with padding. To securely share an AES key for wrapping between CipherTrust Manager and the other system, follow one of these two options:

  • CipherTrust Manager-generated AES key: Generate an RSA key pair on the other system, and import the public key to CipherTrust Manager. When you export the AES key from CipherTrust Manager, wrap it with RSA encryption using the public RSA key. Transfer the wrapped AES key to the other system, which can then unwrap the AES key with the private key.

  • Externally-generated AES key: Generate an RSA key pair in CipherTrust Manager, and export the public key to the other system. Wrap the AES key with RSA encryption on the other system. Import the wrapped key, so that CipherTrust Manager can unwrap with the RSA private key.

Import a Key

To import a key:

1. Login to the desired CipherTrust Manager domain as a privileged user.

2. Navigate to Keys.

3. Click + Add Key.

   The Add Key dialog displays.

4. (Optional) Provide a Key Name, Description, one or more Aliases, one or more Alternative Names, and one or more Key Labels. If you don't provide a key name, one will be auto-generated.

5. (Optional) Provide a key template, if desired.

   1. Enable the Create with key template checkbox.

   2. Type the key template name into the text field or click Choose to select a key template from the list.

6. Click Next.

   The Key Attributes section is displayed.

7. Specify the Object Type to import.

   • Symmetric key: This includes AES, TDES, HMAC, ARIA, or SEED keys.

   • Certificate: This includes X.509 certificates with PEM or DER encoding.

   • Public/Private Key Pair: This includes RSA and EC keys.

8. Under Key Material Origin, select Import Key Material or Import Wrapped Key Material.

9. Specify related settings for the key you are importing.

   Note

   No additional settings are required for certificate import.

   Symmetric key

   To import key material, you must select HEX or Base64 encoding for symmetric keys.

   To import wrapped key material, only Base64 encoding is supported. You do not make an encoding selection for wrapped key material.

   Public/Private Key Pair

   If the key is in PKCS#12 format, toggle the PKCS#12 format to on.

10. Provide the Key Material as a file upload or text.

11. You can optionally provide Key Properties and Key Usage.

    Note

    These values are auto-filled if you specified a key template in step 5. You can change the values to override the template values.

12. Click Next.

13. (Public/Private Key PKCS#12 import only) Provide Private Key Credentials.

    1. Select the Credential Type, Use Password or Use Secret.

       Password

       Type the base64-encoded password in the Password text box.

       Secret

       Search for a secret on the CipherTrust Manager by name. The search is conducted on all keys of object type "secret data". Enable the radio button for the desired secret.

    2. Click Next.

14. (Import wrapped key material only) Select the wrapping method and wrapping key.

    1. For the Wrapping Encryption Algorithm, select AES Key Wrap, AES Key Wrap with Padding, RSA Encryption, or RSA AES Key Wrap with Padding. The options displayed depend on the format of the imported key. Refer to Wrapping a Key for Import for details of supported wrapping methods.

    2. For RSA AES Key Wrap with Padding method, you must also select AES Key Size and RSA Padding values from dropdowns.

    3. Search for the wrapping key's name in the list. There is a search bar provided.

    4. Enable the radio button for the desired wrapping key.

    5. Click Next.

15. Review the details of the key to import. Click Back or Edit to modify any selection. Click Add Key to confirm.

    The key details page is displayed.

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.

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.