Key Lifecycle

Phases and Key States

CORE implements KMIP 2.1 Section 4.57 State specification and extensions specified in NIST SP 800-57 Part 1 Rev 5 Section 7. It divides a lifecycle of a key into four phases:

Pre-operational.

A key is added to the CORE database.

It may be generated, derived from an existing key in CORE, or imported.

Its crypto attributes, purpose, and crypto metadata are set for a complete lifetime.

Activation of the key may be delayed for the specified or unspecified time.

 

Operational

The key is activated either by the system or by command.

It is used as designated by its purpose setting.

It may be suspended and resumed.

If allowed, its copy may be exported.

 

Post-Operational

The key is revoked by command or as scheduled.

The date and the reason for the revocation are added to the key's metadata.

Once revoked, the key can't be reactivated. Its use is limited as follows:

• It can't be used in operations that create new material:
  Encryption, wrapping, signing, MACMessage Authentication Code - for example, CMAC, GMAC, HMAC. generation, derivation.
• Its use in the following crypto-processing operations is disabled by default:
  Decryption, unwrapping, verification of a signature, or MACMessage Authentication Code - for example, CMAC, GMAC, HMAC..
  

Destroyed

A key is deprecated.

It may be completely deleted from the database or destroyed - leaving its deprecation date in the database.

Key Assembly from Split Keys

In addition to being generated, imported, or derived, a key may be assembled from parts distributed to several key holders for additional security. Such parts are imported to CORE and managed as key type "Split key" in compliance with the KMIP specification. Split keys may be imported to CORE, used to reconstruct the original key, and destroyed or kept for reference. See Split Keys.

Suspension and Resumption

CORE implements NIST SP 800-57 Part 1 Rev 5 Section 7.3 Suspended State for the temporary disabling and re-enabling of a key:

The applicability of key material in the Operational (and Post-Operational) phases may be suspended and resumed using the Disable and Enable commands. Its isEnabled setting indicates the current status of a key. Nonetheless, a suspended key:

• It may be exported.
• Its key material may be used for rotation and derivation.

Key Material Refresh

The refresh operation changes the key material of both MPCMultiparty computation - A methodology for parties to jointly compute a function of their inputs while keeping those inputs private. shares of a key without impacting the outcome of crypto operations that use this key. The refresh occurs periodically. Once all keys in the system are refreshed, the cycle restarts after the Refresh and Sync Timers.

Key Rotation

Introduction

The rotation of a key ("base key"):

• Generates a new key with the following settings cloned from the base key:
  • The crypto type and size/curve attributes.
  • Name, description, and other metadata settings.
  • Rotation settings (including the periodic rotation settings, if any).
• Resets the following metadata of the base key:
  • The name of the key - becomes its default UID-based name: "0x00<UID>".
  • The description field is cleared if the partition Enforce-unique
  • The automatic rotation settings are cleared.

Prerequisites for the base key:

• It must be in the operational phase.
• It must have an explicit name.

The new key links to its predecessor, and the predecessor links to the new key. A key may be rotated only once. By rotating the newest key, we create a chain of keys.

Notes:

• The key name is associated with the latest key in the chain.
  
• All keys in the chain can be referenced using their UIDs.
• Changing an attribute of a key does not propagate to other keys in the key chain.
• The activation of the rotated key may be delayed. See Manual Rotation.
• If a partition contains both private and public keys, the rotation of the private key also generates the corresponding public key. The public key name is reassigned to the new public key, while the previous public key is renamed to its UID.

The rotation can be done manually or scheduled for periodic rotation.

Periodic Rotation

You can configure the periodic key rotation when the key is created (either generated or imported) or later by updating its periodic rotation setting. Once set, the system rotates the key every N days (1-1095) as long as the periodic rotation is enabled.

Seven days before the due date, you will be alerted that a key is approaching its rotation date. On the due date, the rotation is performed at the key-rotation-time (Automatic Key-rotation Time).

Manual Rotation

You can use the ucl rekey command to rotate a key on demand. By default, the command instantly activates the new key. However, its deactivation date (if any) is also inherited from the base key.

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.

The effect of omitting the offset parameter or specifying its value is summarized in the following table.

Offset value	Activation time of the new key	Deactivation time of the new key	State of the new key
not specified	As of the existing key	As of the existing key	active
0	Set to "Now" (the time of the request)	Shifted accordingly	active
1 .. 3650	Set to "Now" + offset	Shifted accordingly	pre-active

Key Material Export

Export Permissions and Methods

By default, a public key is always exportable, while private or secret keys are never exportable. Nonetheless, while creating a private or secret key, it may be cleared for export with or without restrictions. In particular:

A private key may be exported if its settings indicate one of the following permissions:

- May be exported In plain.

- May be only exported if it is wrapped by a secret key from the same partition.

The wrapping key may be further required to be a trusted key.

A secret key may be exported if its settings indicate one of the following permissions:

- May be exported In plain.

- May only be exported if it is wrapped by a different secret key from the same partition.

- May only be exported if it is wrapped by a public RSA key from the same partition.

The wrapping key may be further required to be a trusted key.

Summary:

CORE supports four grades of export restrictions for private and secret keys that escalate from the "exportable (plain or wrapped)" to the "not exportable" (the default):

Plain or wrapped ("exportable" in terms of UCLUnbound Command Language)

The key material is exportable without restrictions.

Wrapped

To export a key material, the material must be wrapped using a wrapping key from the same partition, either trusted or not.

Wrapped with a trusted key

To export a key material, the material must be wrapped using a trusted wrapping key from the same partition.

Not Exportable

The key material is not exportable. It is the default setting.

The export restriction grade is set upon the creation of a key. It is a permanent setting.

Exportability of External Key from CORE

When a key in CORE represents a key from an external keystore, the key's exportability from CORE depends on the BYOKBring Your Own Key setting of the key:

non-BYOKBring Your Own Key

Such a key is not exportable from CORE.

Note
KMSKey Management System provider may allow key replication or backup and restore procedures used for the provider's internal purposes. Such procedures must be carried using the provider's tools.

BYOKBring Your Own Key

If CORE key settings indicate that the key is exportable, it may be exported from CORE using export methods specified by the key.

CORE Wrapping Capabilities

To qualify for wrapping other keys, a wrapping-key must meet the following requirements:

• The key must include WRAP among its permitted operations.
• The key must belong to the same partition as the key that will be exported.
• The key must be trusted if such a condition is specified in the export restrictions.

In addition, the following user-specific and partition-specific conditions must be met:

• A user issuing the export command must be authorized to use the selected key for wrapping and the selected key for exporting.
• The partition policy must allow wrapping with the selected key type and the specified wrapping parameters.

Wrapping using Public Keys

A public RSA key may be used to wrap and export a secret key using the following padding options:

• OAEPOptimal Asymmetric Encryption Padding - A padding scheme often used together with RSA encryption of symmetric keys. (default)
  • Hash: Supported HASH Options.
  • MGFMask Generation Function - A cryptographic primitive similar to a hash function except that it supports output of a variable length.: Supported HASH Options.
• PKCSPublic-Key Cryptography Standards - Industry-standard cryptography specifications.#1 v1.5

Wrapping using Secret Keys

The following symmetric keys may be used for wrapping an exported key material:

• AES
• CHACHA20
• TDES and DES

The key types that may be exported and the supported block modes are specified in the table below.

A Key to be Wrapped	The Wrapping Key (Type and Mode)
	AES	CHACHA20	TDES/DES
AES	ECB, CBC, OFB, CFB, CTR, GCM, CCM, NISTWRAPAES Key Wrap (KW) specified by NIST Special Publication 800-38F	CHACHA20_POLY_1305	ECB, CBC, OFB, CFB
TDES/DES	OFB, CFB, CTR, GCM, CCM, NISTWRAPAES Key Wrap (KW) specified by NIST Special Publication 800-38F	CHACHA20_POLY_1305	ECB, CBC, OFB, CFB
XTS	ECB, CBC, OFB, CFB, CTR, GCM, CCM, NISTWRAPAES Key Wrap (KW) specified by NIST Special Publication 800-38F	CHACHA20_POLY_1305	ECB, CBC, OFB, CFB
CHACHA20	ECB, CBC, OFB, CFB, CTR, GCM, CCM, NISTWRAPAES Key Wrap (KW) specified by NIST Special Publication 800-38F	CHACHA20_POLY_1305	ECB, CBC, OFB, CFB
HMACHash-based Message Authentication Code - A MAC involving a cryptographic hash function and a secret cryptographic key.	ECB, CBC, OFB, CFB, CTR, GCM, CCM, NISTWRAPAES Key Wrap (KW) specified by NIST Special Publication 800-38F	CHACHA20_POLY_1305	OFB, CFB
RSA	OFB, CFB, CTR, GCM, CCM, NISTWRAPAES Key Wrap (KW) specified by NIST Special Publication 800-38F	CHACHA20_POLY_1305	OFB, CFB
EC	OFB, CFB, CTR, GCM, CCM, NISTWRAPAES Key Wrap (KW) specified by NIST Special Publication 800-38F	CHACHA20_POLY_1305	OFB, CFB

Note:

1. AES-KW (AES Key Wrap mode) and AES-KWP (AES Key Wrap with Padding) are indicated here as NISTWRAPAES Key Wrap (KW) specified by NIST Special Publication 800-38F (NIST.SP.800-38F).

The CORE UI and UCLUnbound Command Language provide the following subset using AES keys only:

Exporting secret keys

Modes: GCM (default), NISTWRAPAES Key Wrap (KW) specified by NIST Special Publication 800-38F, ECB, CBC

 

Exporting private RSA keys (all sizes)

Modes: GCM (default), NISTWRAPAES Key Wrap (KW) specified by NIST Special Publication 800-38F

Exporting private ECCElliptic-curve cryptography - an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields keys (curves: P256, P384, P521, SecP256K1)

Modes: GCM (default), NISTWRAPAES Key Wrap (KW) specified by NIST Special Publication 800-38F

Export Options and File Formats

Symmetric Key Export Formats

Based on the export settings of a key, the options to export a secret key are:

Plain (exportable)

Output: BIN file with the key material only.

Wrapped with/out trusted key

Output: JSON file. See JSON Format of Wrapped Key.

Public Key Export Formats

CORE exports public RSA and ECCElliptic-curve cryptography - an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields keys in the PEMBase64 encoded DER wrapped by "--- BEGIN <type> ---" and "--- END <type> ----" files using the PKCSPublic-Key Cryptography Standards - Industry-standard cryptography specifications.#8 format in all cases except the following:

• UI exports a public RSA key in the PEMBase64 encoded DER wrapped by "--- BEGIN <type> ---" and "--- END <type> ----" file using (legacy) PKCSPublic-Key Cryptography Standards - Industry-standard cryptography specifications.#1 format.
  To convert such a file to PKCSPublic-Key Cryptography Standards - Industry-standard cryptography specifications.#8, use the openssl pkcs8 -topk8 command.

Note
- PKCSPublic-Key Cryptography Standards - Industry-standard cryptography specifications.#1 format explicitly specifies the key type. For example, "BEGIN RSA PUBLIC KEY".
- PKCSPublic-Key Cryptography Standards - Industry-standard cryptography specifications.#8 format doesn't specify the key type in its title. It only specifies that the material is a public key: "BEGIN PUBLIC KEY". The actual key type is encoded in the data that follows the header.

Private Key Export Formats

Based on the export settings of a key, the options to export a private key are:

Plain (exportable)

Output: PKCSPublic-Key Cryptography Standards - Industry-standard cryptography specifications.#8 PEMBase64 encoded DER wrapped by "--- BEGIN <type> ---" and "--- END <type> ----" file starting with "BEGIN PRIVATE KEY" statement.

Plain (exportable) protected by a passphrase

Output: PKCSPublic-Key Cryptography Standards - Industry-standard cryptography specifications.#8 PEMBase64 encoded DER wrapped by "--- BEGIN <type> ---" and "--- END <type> ----" file starting with "BEGIN ENCRYPTED PRIVATE KEY" statement.

Note. This option excludes EC CURVE 448 and 25519 keys.

Wrapped w/out trusted key

Output: JSON file. See JSON Format of Wrapped Key.

Notes

1. To convert PEMBase64 encoded DER wrapped by "--- BEGIN <type> ---" and "--- END <type> ----" format to DERBinary file, serialized ASN.1 structure for EC keys, see Command Line Elliptic Curve Operations.
2. To examine or convert CURVE 448 and 25519 keys, see OpenSSL PKEY Commands.

Certificate Export formats

To export a certificate not bonded with a private key, you may select PEMBase64 encoded DER wrapped by "--- BEGIN <type> ---" and "--- END <type> ----"-formatted output or its binary variant by specifying the CERCertificate file in PEM format file as the output file type.

Private Key with Certificate Export Formats

Given the private key and its certificate in the same partition, the exporting options are as follows:

• Regardless of the private key exportability, you can always export:
  • Its public key using the PEMBase64 encoded DER wrapped by "--- BEGIN <type> ---" and "--- END <type> ----" format as specified in Public Key Export Formats.
  • Its obfuscated private key for use by OpenSSL.
  • Certificate file in the PEMBase64 encoded DER wrapped by "--- BEGIN <type> ---" and "--- END <type> ----" format.
• The following export options depend on the export settings of a key:

Plain (exportable)

Its Private key in PKCSPublic-Key Cryptography Standards - Industry-standard cryptography specifications.#8 PEMBase64 encoded DER wrapped by "--- BEGIN <type> ---" and "--- END <type> ----" file starting with "BEGIN PRIVATE KEY" statement.

Its Private key with the complete certificate chain in PKCSPublic-Key Cryptography Standards - Industry-standard cryptography specifications.#12 (PFXAn archive file format for storing cryptography objects using Base64 encoding) format.

Wrapped w/out trusted key

Output: JSON file. See JSON Format of Wrapped Key.

Quick Start

In this quickstart, we generate an RSA key and create and import its self-signed certificate. With the key and the certificate in the partition, we export both to a PFXAn archive file format for storing cryptography objects using Base64 encoding file and check the result using OpenSSL.

1. Create an exportable RSA key.  To be included in the PFXAn archive file format for storing cryptography objects using Base64 encoding file, the key must be exportable in PLAIN.

   ucl generate -t rsa -n rsa-exp1 --exportable

2. Using this key, create a self-signed certificate. In the partition, the certificate object is bound to the key object.

   ucl self-sign -n rsa-exp1 --format PEM --subject "CN=UNBOUND" -days 1000

3. Note that the private key and its certificate have distinctive UIDs but share the same name.

   ucl list
   Private RSA key : UID=8219a17cfab45214 Name="rsa-exp1"
   Certificate : UID=971b76925313e26f Name="rsa-exp1"

4. To export the certificate and its private key we will have to refer to one of them by its UID.

   ucl export -u 8219a17cfab45214 --with-private -o rsa-exp1.pfx --file-pass Password1!

5. To check the file, use OpenSSL command.

   openssl pkcs12 -info -in rsa-exp1.pfx
   Password:

JSON Format of Wrapped Key

An export file containing the wrapped key uses JSON format to describe the wrapped and the wrapping key. It includes the wrapped key material in the BASE-64 encoding, the parameters used by wrapping, and the export timestamp.

Wrapping with secret key - EC key wrapped by AES 

In the following snapshot, the keyData contains an Ed25519 key wrapped by an AES key using GCM Mode. The AADAdditional Authentication Data data used in the export is excluded from the provided data.

Wrapping with secret key - AES key wrapped by RSA Public key

For example, if the name of the public RSA key is rsa4wrap, and the name of the key to be exported is aes4export, then the resulting JSON looks as follows:

Note
The UID saved in the "wrapKey" is the UID of the public key used for wrapping.
When importing this JSON-wrapped key back to the partition, the corresponding private RSA key will be used for the unwrapping.

Key Material Import

Private key material importing capabilities and formats mirror the exporting capabilities and formats specified in Key Material Export.

Key material import formats:

• When a key material is imported in plain, it may be provided in BIN, HEX, or encoded in BASE-64 and stored in the PEMBase64 encoded DER wrapped by "--- BEGIN <type> ---" and "--- END <type> ----"-formatted file.
• A private key may be imported in plain from the PKCSPublic-Key Cryptography Standards - Industry-standard cryptography specifications.#12(PFXAn archive file format for storing cryptography objects using Base64 encoding) file. You will have to provide the necessary passphrase.
• Wrapped key material must be provided in the JSON file described in the JSON Format of Wrapped Key. The minimum required info is specified in the following section.

Wrapped Import Mandatory Data

Unwrapping with Symmetric Key

The following values are required import wrapped Ed25519 key to partition "test" by unwrapping it with key "uid": "e06ac11d209b7298" in the "test" partition and using the specified mode and IV.

OAEPOptimal Asymmetric Encryption Padding - A padding scheme often used together with RSA encryption of symmetric keys. info (in BASE-64 encoding) is separated from this data.

Unwrapping with private RSA key

The following values are required import wrapped AES key to partition "test" by unwrapping it with key "uid": "951be9e4b40471e3" in the "test" partition and using the specified padding parameters

Split Keys

A split key is a part of a secret key that was broken into several parts and distributed to various locations for additional security. To reconstruct the original key, import and reassemble the parts in CORE.

To import a split key, its binary material must be converted to HEX format.

Tip
Conversion to HEX format doubles the size of a file. For example, the size of a BIN file that contains a split key of 3DES material is 24 bytes. The size of the corresponding hex file is 48 bytes.
In Linux, use the xxd -p <file.bin> - command to convert binary file to hex string. Note the terminating dash "-".

Split Key Specification

CORE implements the XOR method specified in KMIP 2.1 Split Key Methods. This method implies the following:

• all key blocks (binary) are of the size of the original key.
• To reconstruct a key, all its parts must be available in the partition.
• XOR of all key blocks reconstructs the original key material.

Once a key is reconstructed, its Key Check Value (KCVKey Check Value. PKCS#11 CKA_CHECK_VALUE) may be compared with the original KCVKey Check Value. PKCS#11 CKA_CHECK_VALUE. See Key Check Value (KCV).

Split Key Type

In compliance with KMIPKey Management Interoperability Protocol - an extensible communication protocol that defines message formats for the manipulation of cryptographic keys on a key management server, split keys are managed by CORE as KMIPKey Management Interoperability Protocol - an extensible communication protocol that defines message formats for the manipulation of cryptographic keys on a key management server objects of SplitKey key type.

Commands to create and use split keys are:

import - the method to create a split key in CORE.

join - the method to create a secret key from its split parts.

 

Commands applicable to a split key are:

show info

edit

delete

 

Split key states

The Join command can instantly use an imported split key. All other states in Phases and Key States are not relevant for a split key.

 

Key Groups membership

Key-group membership of a split key is as of a regular key.

In particular, to reconstruct a key from its split keys, all split keys must be members of key-group(s) listed among the user's permissions to run the JOIN operation.

Split Key Attributes

In addition to key material, a split key specifies the following

Split KeyA split key is a symmetric or a private key that has been split into a number of parts, Parts

The total number of generated parts.

Key Part Identifier

Specifies the part contained in this object starting from 1 and up to split key parts.

Split KeyA split key is a symmetric or a private key that has been split into a number of parts, Threshold

Indicates the minimum number of parts needed to reconstruct the entire key.

Split KeyA split key is a symmetric or a private key that has been split into a number of parts, Method

Indicates the method used to create the parts.

Key Block

Contains the key material that is carried by this part.