Keys and Certificates Tab

Partition SOClosedSecurity officer - UKC partition administrator role. ˃ Keys and Certificates

→ presents the following:

Table of Keys and Certificates

Each row in the table presents the following attributes:

  • Name of the material. The icon next to the name indicates the type of material: key or certificate.
  • UID - of the material.

    • Note
    In the case of the key+certificate, it presents the UID of the key. To get the certificate's UID, use the Show Info command.

  • State- See Phases and Keystates.

    • Note
    In the Active, Deactivated, and Compromised states, the state value is followed by the " / Disabled" indication if the use of the key has been suspended (disabled). See Suspension and Resumption of a Key. In the other key states, this indication is not relevant, and it is not shown.

  • Keystore - the name of the keystore that safeguards and applies the key material.
  • Object type - The value depends on the object represented by the UID:
    • For keys: Private, Public, Secret, or Split key.
    • For certificates: Certificate.
  • Algorithm - the type of algorithm used by the key.
  • Size - the key size in bits.
  • Groups - Membership in Key-Groups.
  • Description - optional description.
  • Last changed - timestamp of the last change.
  • [] - see Keys and Certificates Tab

Note
A key approaching a certain automatic action date (such as automatic rotation, activation, deactivation) is colored red. The red Key Alerts badge is updated accordingly.

Example. The following capture shows the Root partition's keys and certificates. They are created during the system bootstrap. See the description here.

Key Create Options

Click the +Create button to generate a New Key or

Click the ▼ arrow next to the button and choose one of the following options: 
Import
Join Split Key
Link External Key

Notes
1. The Link option is shown only if the managed partition has external keystores.
2. Following the EKMClosedEnterprise Key Management - previous name of the product. service restart on the connected EP, it may take up to 30 secs for the Link option to appear in the list.

New Key

Partition SO ˃ Keys and Certificates ˃ Create

→ The New Key dialog appears.

  • Name - mandatory. See Name and Description.
  • Description - optional.

    • Note
    The absence of the description does not violate the Enforce-unique requirement.

  • Keystore - optional. Default: Unbound. Otherwise, see Create External Key.
  • Groups - optional. Default: "default". As needed, specify membership in the key groups. See Membership in Key-Groups. You can:
    • Select the group name from the drop-down list.
    • Create a group name on the spot by typing a new name. In such a case, the new key-group name shall be added to the list of the available key-groups.

      • Note
      Every key is a permanent member of the default key group. This membership can't be revoked.

  • Key type ▼ - click ▼ and select the key type.
    • Size ▼ - if presented - select the required one.
    • Curve ▼ - if presented - select the required one.

      • Note
      The content of the list depends on the Partition Key Usage Policy. If the required key type is not listed, check that it is allow-listed in the partition's policy. See Partition Settings in UI.

  • Usage ▼ - If omitted - the default Purpose in CORE is presented.As needed, modify it.

      If the key represents a key from an external keystore, its purpose must match capabilities provided by the keystore. See Purpose of External Key.

  • Export Permission ▼ - if presented - select the required one. See Key Material Exportability.
  • Trusted - if presented - checkmark as needed. See Trusted Material.
  • Activation mode ▼ - see Phases and Keystates.
    • If you selected Scheduled, the Activate at dialog appears. Enter the date manually or click ▼ to present the calendar.
  • Deactivation mode ▼ - see Phases and Keystates.
    • If you selected Scheduled, the Deactivate at dialog appears. Enter the date manually or click ▼ to present the calendar.
  • Automatic key rotation - to activate it, click the check-box and specify the rotation period.

    • → The key rotation settings appear. See Key Rotation Interval.

    Note
    If you change the Keystore setting - all other settings are reset to the default values of the new keystore. You will have to restore the required values.

Click Add Key.

Note: Edwards and Montgomery Curves

The Edwards (Ed) and Montgomery(X) curves are both identified as CURVE25519 and CURVE448. To differentiate among them, specified the permitted operations:

  1. To define Edwards Ed25519 or Ed448, use CURVE25519 or CURVE448 and specify SIGN as the mandatory operation.
  2. To define Montgomery X25519 or X448, use CURVE25519 or CURVE448 and omit SIGN from the permitted operations while specifying DERIVE as the mandatory operation.

Join Split Key

Partition SO ˃ Keys and Certificates ˃ Create ▼

click ▼ and click Join

→ The Join Split Keys dialog appears:

  1. Assign the name and the type of the key.
  2. Start typing the name of a split key part in the Split key parts box. The split keys that match your string as you type shall appear in the candidate box.

  3. To reconstruct the key, you must provide all parts.
    • The system will guide regarding the expected number of parts.

      • Note
      The material size of the selected parts must match the size required by the reconstructed key. Since we are importing HEX files, the size of the file (in bytes) should be 2X the size of the key material (in bytes).

  4. You may ask the system to delete the split parts once the reconstruction is completed.

The rest of the dialog follows the steps specified in New Key.

Note
This operation is logged in the audit log file as the Join operation.

Import

Partition SO ˃ Keys and Certificates ˃ Create ▼

Click ▼ and click Import

→ The Import Key or Certificate 3-step chart appears.

Click Choose File button and select the file to be imported.

If prompted, provide the required passphrase.

→ The Import Key or Certificate dialog appears.

CORE uses heuristics to identify a class of possible objects that the imported data may apply to. It presents the corresponding dialog where you may be asked to further select the specific type, such as :
Type of a Secret key
Type of a Split key
Private key or Private key with the certificate (and its chain)
Certificate (and its chain)
Public key

→ The imported object name is filled in as the file name (without extension).

Note
If the file name contains special characters, then the name may appear differently in UCLClosedUnbound Command Language. See Keyname Permitted Characters. Further on, if the imported data is designated to an external keystore, specific keystore restrictions regarding the name may apply.

Import Secret Key

Supported import file formats: BIN and JSON (wrapped key).

Select the expected type.

Follow the steps specified in the New Key dialog and click Import.

Import Split Key

Supported import file formats: HEX

The Import Split KeyClosedA split key is a symmetric or a private key that has been split into a number of parts, dialog appears:

  1. Name - mandatory.

    2. Tip
    This key-split will be later manually combined with the other key-splits to reconstruct the original key material (see Join Split KeyClosedA split key is a symmetric or a private key that has been split into a number of parts,. The Join command assists you in selecting the required split keys by presenting the split key names with the leading characters that match your string while you enter it in the Join command dialog.

  2. Description - optional.
  3. Split key parts - number of parts required to reassemble the key.
  4. Split key identifier - distinctive identifier in the group.

    Must be in the range of [1 to the number of parts]. It is checked during the join command to assure that all provided parts are distinctive.

  5. Groups - specify the designated key groups. The membership in the default group is always enabled and can't be changed.

Click Import.

Import Private Key

The supported import file formats are: PEMClosedBase64 encoded DER wrapped by "--- BEGIN <type> ---" and "--- END <type> ----" (PKCSClosedPublic-Key Cryptography Standards - Industry-standard cryptography specifications.#1 and PKC#8), JSON (wrapped key).

Follow the steps specified in the New Key dialog and click Import.

Import Private Key with Certificate

The supported import file formats are: PFXClosedAn archive file format for storing cryptography objects using Base64 encoding.

The dialog presents the following options:

  • Import both key and certificate.
  • Import key only.

Follow the steps specified in the New Key dialog and click Import.

If you selected to import keys and certificate(s), the certificate (or chain of certificate) in the selected file is imported implicitly.

Note
Certificates are assigned to the same key groups as the key.

Note
Importing files that contain key and certificate (certificate chain):
The import command parses the file and creates separate UIDs for the key material and each certificate. However, to examine the 1st certificate and its UID, use the Key with the Certificate show-command.

Warning
The command imports only one key and one certificate chain. Check the result if the provided file contains multiple keys and multiple certificate chains.

Import Certificate

Supported import file formats: PKC#8,

The Import Certificate dialog appears:

  1. Name - mandatory.
  2. Description - optional.
  3. Groups - specify the designated key groups. The membership in the default group is always enabled and can't be changed.

Click Import.


Note. The system rejects importing a certificate that is already stored in the partition. Yet a key may have various certificates as shown below.

A key in many certificates

Import Public Key

Supported import file formats: PEMClosedBase64 encoded DER wrapped by "--- BEGIN <type> ---" and "--- END <type> ----" (PKC#1, PKC#8).

To use the RSA key for wrapping, encryption, and verification of a signature, import it from the PEMClosedBase64 encoded DER wrapped by "--- BEGIN <type> ---" and "--- END <type> ----" file containing only its public part. The file must be encoded in the following formats

→ The Import Key or Certificate expands to the following dialog:

  • Name - by default, contains the file name without extension.
  • Description - optional.

  • Groups - specify the designated key groups. The membership in the default group is always enabled and can't be changed.
  • Trusted - enables using it for exporting other key material that must be wrapped by a trusted key. This setting is permanent.
  • Activation and Deactivation - as needed, specify the activation and deactivation mode of the key.

Key Commands

Export Options

Partition SO ˃ Keys and Certificates ˃ select key ˃ [] ˃ Export

The Export command appears among the key commands if the Export Permissions and Methods requirements are met. The exported data is stored in the browser's download folder. By default, the filename is concatenated from the following strings:

<key-name>-<key-type>-<the last six characters of its UID>

For various options and file formats of exporting a secret, a private or public key, and a certificate with/out a key, see Export Options and File Formats.

Show Info Options

Partition SO ˃ Keys and Certificates ˃ select key ˃ [] ˃ Show Info

→ Presents two tabs (Summary and Details) and opens the Summary tab.

The output depends on the material's type:

Key Info

Presents two options: Summary and Details

Note
The CORE system uses UTC timestamps. The Key Summary converts the timestamps to the local time. To see the UTC timestamp, use the Key Details display.

The Summary output presents the following elements only if they apply. Elements that do not apply are not shown.

The authenticity of the presented data is confirmed by the Integrity confirmed statement.

Certificate Info

In addition to displaying the certificate data, it shows the following CORE metadata values:

Key with the Certificate

Presents the Key Info followed by the Certificate Info.

Commands

Partition SO ˃ Keys and Certificates ˃ select key ˃ []

→ The list of commands appears.

Note
The list of the presented commands depends on the type of the selected key and its key state.

Rekey

Partition SO ˃ Keys and Certificates ˃ select key ˃ [] ˃ Rekey

The command generates a new key (Key-Rotation) with instant or delayed activation of the key. The offset option (see Key-Rotation) allows adjusting the activity period of the new key relative to the current time.

  • If it is not specified - the Activation and Deactivation dates of the new key are copied from the existing key.
  • If specified (including the value 0), the Activation and Deactivation dates are adjusted relative to the current time + offset.

The re-key operation can be applied only once. To continue rotating the key, apply the re-key to the latest version of the key. This process creates a chain of keys.

Specify the offset argument to adjust the new key's timing settings relative to the command's execution time. In particular, the offset adjusts the deactivation (and activation) dates. The offset is specified in the units of days: 

  • offset = 0 - a zero offset triggers instant activation of the new key, yet the deactivation date is adjusted as needed.
  • offset = 1 to 3650 - during this period, the new key is in the pre-active state.

    • In particular, requests to use a key by-name will be declined because the name now points at the pre-activated key.

On the following capture, the Activation and Deactivation times of the new key (A2, D2) are compared with the times (A1, D1) of the base key.

Rekey offset

Note
The deferred activation of the new key does not affect the previous version of the key that continues providing the service as long as it remains active.

Disable and Enable

Partition SO ˃ Keys and Certificates ˃ select key ˃ [] ˃ Disable/Enable

This command allows for suspending (disable) and resuming the usability of the key. See Suspension and Resumption of a Key. This command applicable keys in the active or revoked states. See Phases and Keystates.

The suspended keys are shown in the key table with the "Disabled" tag appended to its State value. For example, Active / Disabled.

Tip
To show only the suspended keys, enter "Disabled" in the search filter.

Note
Key+Certificate
In this case, the status change applies to the key UID only. To enable/disable the certificate, use the ucl disable/enable -u <certificate's UID> command.

Edit

Partition SO ˃ Keys and Certificates ˃ select key ˃ [] ˃ Edit

The Edit command allows changing the attributes of a key that are listed below.

→ The Edit Key dialog appears with the following entries. For the description of applicable values, see the corresponding items in New Key.

  • Name
  • Description
  • Groups
  • Automatic key rotation - appears if the key is eligible for the rotation.

Note
Key+Certificate - the change applies to both of them (except the key rotation).

Relink and Unlink

Partition SO ˃ Keys and Certificates ˃ select key ˃ [] ˃ Relink/Unlink

These commands apply to UIDs representing keys in the external keystores. See Relink External Key and Unlink External Key.

Revoke

Partition SO ˃ Keys and Certificates ˃ select key ˃ [] ˃ Revoke

Use this command to revoke the applicability of the key material in crypto-protectClosedCrypro operations that require use of private or secret material: Decrypt, Unwrap, Sign, Derive operations. See Phases and Keystates. This command presents a dialog that prompts you to select the reason for the revocation and to specify the text that will appear in the Audit log:

  • If the key or its CA were compromised, select the "<> compromise" reason. By selecting these reasons, you change the state of the key to Compromised.
  • Any other reason changes the key state to Deactivated. See Key Revocation Options.

Note
Key+Certificate
Revocation of a key with the associated certificate revokes both items.

Mark as Compromised

Partition SO ˃ Keys and Certificates ˃ select key ˃ [] ˃Mark as compromised

Use this command to add the reason to an already revoked or destroyed object.

Note
Key+Certificate
Compromise of a key with the associated certificate tags both items as compromised.

Delete and Destroy

Partition SO ˃ Keys and Certificates ˃ select key ˃ [] ˃ Delete/Destroy

Use this command to stop using the key material in crypto-protectClosedCrypro operations that require use of private or secret material: Decrypt, Unwrap, Sign, Derive and crypto-processClosedCrypro operations that use public material of asymmetric keys and secret of symmetric keys: Encrypt, Wrap, Verify. operations. See Phases and Keystates. This command presents a dialog that prompts you to select the Key Destruction Options:

  • Destroy - the metadata remains available in the CORE database.
    • Key - The key is no longer listed in the Keys and Certificates table unless the "Include destroyed" indicator selector is enabled.
    • Key+Certificate :
    • External Key - Destroy External Key.
  • Delete -
    • Key - the key and all its metadata are completely erased from the CORE database.
    • Key+Certificate - both are completely erased from the CORE database.
    • External Key - Delete External Key

Note
In partitions with hundreds of keys, it may take time to refresh the presented page.

External Key Management

External Key Create Options

This section complements the corresponding CORE key management sections for a generation or importing the key material in/to external keystores.

Create External Key

The creation of an external key adds the following to the New Key dialog:

  • Keystore Presents the list of keystores accessible from the partition. See Table of Keystores.

    Note
    Once you change the keystore type, all other key attributes are reset to their default values in the selected keystore.

  • BYOKClosedBring Your Own Key Default: Yes.

    • Specifies the origin of the key material, what is stored in CORE, and how the external keystore provider should handle the key material:

    • NO:
      • We ask the external keystore to generate a key using the provided specification. Then, we link to it.
      • In CORE, the key is marked: local=false, isExternal=true.
    • YES:
      • We generate the key in the CORE and securely forward it to the external keystore.
      • The keystore specifies the forwarding method and conditions. See Prerequisites for creating BYOK key in CORE.
      • In CORE, the key is marked: local=true, isExternal=true..

Nonetheless, the creation of an external key has the following differences:

  1. The content of the Description applies to CORE only.
  2. The exportability of a BYOKClosedBring Your Own Key key from CORE doesn't depend on the exportability of the key from the keystore.
  3. Crypto operations permitted to a key must match capabilities provided by the keystore provider.

    4. Keys in an external keystore must be created by explicitly listing the permitted crypto operations. Relying on the CORE default permitted crypto operations might create unexpected results.

For the list of the supported key types and algorithms in the external keystores refer to:

Prerequisites for creating BYOK key in CORE

In general, the settings of a key must comply with the keystore provider's BYOKClosedBring Your Own Key generation requirements.

For example, if the generation of BYOKClosedBring Your Own Key key implies that the provider imports the key then:

  • The key must be set as exportable (from CORE ).
  • The user must be authorized to perform the following operations:
    • to export the key.
    • to wrap the exported key with the type of the wrapping key.

Import Key to External Keystore

CORE implements importing of a key to an external keystore as follows:

  1. The key material is imported to CORE.
  2. CORE uses the imported material to generate a BYOKClosedBring Your Own Key key in the keystore.
  3. The keystore applies its mechanism to obtain the key.

Note
In particular, the CORE settings of a key must comply with the keystore provider's BYOKClosedBring Your Own Key mechanism requirements. For example, it must be set exportable to be carried to the external keystore if this is how the keystore obtains it (though it may be marked non-exportable in the keystore).

Link External Key

This option appears in a partition that has at least one connection to the external keystore.

Partition SO ˃ Keys and Certificates ˃ Create ▼

click ▼ and click Link

→ The Link dialog appears

  • Keystore - alias name of the keystore. See Table of Keystores.
  • External ID - ID of the key in the external keystore. The format of this value is specific to each keystore provider. Copy it as it is presented in the external keystore's management interface. For example:

    Key Id in Azure KV:

    Key ID in Azure

    Key Id in GCP:

    Key ID in Azure

    For example: projects/ub-kms/locations/us-east1/keyRings/test-kr/cryptoKeys/rsa-gen/cryptoKeyVersions/7 Note that the name includes cryptoKeyVersions value.

    Note
    The CORE name of a key is derived from the name used in the external keystore.

  • Groups - See the definition in New Key.
  • Activation mode ▼ - See the definition in New Key.
  • Deactivation mode ▼ - See the definition in New Key.

Note
CORE shall not link to a key that is pending deletion or is in the soft deletion state in the external keystore.

External Key Management Options

Edit External Key

  • Changing the name of a key may be declined by the keystore provider.
  • Modifying the description of a key affects its CORE setting only.

Relink External Key

This command obtains the corresponding key metadata from the external keystore and uses it to update the metadata of the UID in CORE. It updates the following settings:

  • Name
  • Description
  • Status (Enabled/Disabled)

    • For example, if the key in the external keystore has been disabled using the external keystore management tools, the relink command disables its representative in CORE.

Export External Key

In general, external keystores block the key material export. Yet since BYOKClosedBring Your Own Key key material is also stored in CORE, its export conditions are defined by CORE:

Unlink External Key

This command disconnects the CORE UID from the external key. It impacts the UID as follows:

Disable or Enable External Key

The command is forwarded to the external keystore provider.

Revoke External Key

UID is revoked. The key-delete request is forwarded to the external keystore. See the note in Delete External Key.

Destroy External Key

UID is destroyed (in KMIPClosedKey Management Interoperability Protocol - an extensible communication protocol that defines message formats for the manipulation of cryptographic keys on a key management server terms). The key-delete request is forwarded to the external keystore. See the note in Delete External Key.

Delete External Key

Sends the delete request to the external keystore and deletes UID from the CORE.

Note
The external keystores may have different delete protocols and methods to restore the deleted key. Usually, the key material and metadata are saved. An attempt to generate new key material with the same name may be declined due to the collision. See the keystore provider's documentation.