Keys and Certificates Tab
Partition SOSecurity officer - UKC partition administrator role. ˃ Keys and Certificates
→ presents the following:
- Key Create Options
- Table of Keys and Certificates including
- Keys and Certificates Tab in the [
] button.
- Include destroyed slider. It allows including the destroyed keys in the table.
- Keys and Certificates Tab in the [
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.
- State- See Phases and Keystates.
- 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
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.
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.
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 EKMEnterprise 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.
- 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 thedefault
key group. This membership can't be revoked.
Note
The absence of the description does not violate the Enforce-unique requirement.
- 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.
If the key represents a key from an external keystore, its purpose must match capabilities provided by the keystore. See Purpose of External Key.
- If you selected Scheduled, the Activate at dialog appears. Enter the date manually or click ▼ to present the calendar.
- If you selected Scheduled, the Deactivate at dialog appears. Enter the date manually or click ▼ to present the calendar.
→ 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:
- To define Edwards Ed25519 or Ed448, use CURVE25519 or CURVE448 and specify SIGN as the mandatory operation.
- 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:
- Assign the name and the type of the key.
- 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.
- 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). - 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 UCLUnbound 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 KeyA split key is a symmetric or a private key that has been split into a number of parts, dialog appears:
- Name - mandatory.
- Description - optional.
- Split key parts - number of parts required to reassemble the key.
- 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.
- Groups - specify the designated key groups. The membership in the
default
group is always enabled and can't be changed.
Tip
This key-split will be later manually combined with the other key-splits to reconstruct the original key material (see Join Split KeyA 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.
Click
Import
.
Import Private Key
The supported import file formats are: PEMBase64 encoded DER wrapped by "--- BEGIN <type> ---" and "--- END <type> ----" (PKCS
Public-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: PFXAn 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:
- Name - mandatory.
- Description - optional.
- 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.
Import Public Key
Supported import file formats: PEMBase64 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 PEMBase64 encoded DER wrapped by "--- BEGIN <type> ---" and "--- END <type> ----" file containing only its public part. The file must be encoded in the following formats
- PKCS
Public-Key Cryptography Standards - Industry-standard cryptography specifications.#1
- PKCS
Public-Key Cryptography Standards - Industry-standard cryptography specifications.#8
→ 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.
- Name - the name of the key.
- UID Info:
- UID - UID of the key
- Description - it appears if the description is not empty.
- Previous - it appears if the key was created by rotating the "previous" key.
- Next - it appears if the key was rotated, resulting in the "next" key.
- External keystore specific data - appears if the key is stored in the external keystore:
- External keystore - external keystore name.
- External ID - key identification in the external keystore.
Note
To examine the BYOKBring Your Own Key setting - use the Details>keyStoreProperties.
- Key-state info
- 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. - Revocation reason - appears if the key was revoked. See Key Revocation Reason.
- State - see Phases and Keystates.
- FIPS
Federal Information Processing Standards - standards developed by the United States federal government for use in computer systems by non-military government agencies and government contractors - (appears if the system operates in FIPS mode
UKC system mode that allows processing FIPS-certified and not-certified keys)
- true - the key is processed in FIPS mode
UKC system mode that allows processing FIPS-certified and not-certified keys.
- false - the key is processed in non-FIPS mode
UKC system advanced execution mode that hasn't yet received the FIPS certification.
- true - the key is processed in FIPS mode
- Key type - see Table of Keys and Certificates.
- Permitted operations - it appears if the user has an option to select the permitted operations, for example, in the case of RSA or ECC
Elliptic-curve cryptography - an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields key.
- Attributes - appears if one of the following is true:
Local
- see Local Key.Trusted
- see Trusted key.
Note
The absence of the Attribute field indicates that the key is imported and not trusted. - Groups -see Table of Keys and Certificates.
- Key Check Value (KCV
Key Check Value. PKCS#11 CKA_CHECK_VALUE) appears for symmetric keys and their split parts. See Key Check Value.
- Certificate Info appears If the UID represents both the key and its certificate.
- Life-cycle info:
- Created at - date and time when the key was created or imported.
- Last updated at - date and time of the last change.
- Activation details:
- Activate at - If the key is in the PreActive state.
- Activated at - If the key has been activated manually or as scheduled.
- Deactivation details:
- Deactivate at - If the key is in the PreActive or Active states.
- Deactivated at - if the key has been revoked manually or according to the scheduled termination.
- The details of the secret's breach appear if the key material has been compromised
- Compromised at - indicates the date when the key was revoked due to the breach.
- Compromise occurrence - indicates the date when the breach occurred. If the date is unknown - it is set to the creation date.
- The end-of-life details appear if the key was destroyed:
- Destroyed at - the date when the key secret and public material were destroyed.
- The following details appear if the key is scheduled for the periodic rotation:
- Rotation interval (in days) - the rotation cycle.
- Next rotation - the upcoming rotation date.
Note
In the Detailed info display, this field is called "Id" (the KMIPKey Management Interoperability Protocol - an extensible communication protocol that defines message formats for the manipulation of cryptographic keys on a key management server term).
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:
- Certificate version - describes the version of the encoded certificate. For SSL
Secure Sockets Layer - a cryptographic protocol that provides communications security over a computer network. certificates, the x509 version is 3.
- Serial number - unique certificate's identifier generated by Issuer.
- Certificate UID - UID of the certificate in the CORE.
- Subject - Distinguished Name (DN
Distinguished name - user's full name with a list of attributes that distiguish it from the other users with the same name) of the client to whom the certificate belongs. It contains fields such as CommonName, OrganizationalUnit, Organization.
- Issuer - the Issuer of the certificate.
- Validity - specifies the certificate's "not before" and "not after" dates.
- Signature algorithm - the algorithm that signed the certificate.
- Signature - the value of the signature.
- Thumbprint (SHA
Secure Hash Algorithm - a family of cryptographic hash functions-1) - the hash value of the certificate in DER
Binary file, serialized ASN.1 structure format.
- Public key - the public key that is signed by this certificate.
- Groups -see Table of Keys and Certificates.
- Created - date.
- Last updated - timestamp of the last change.
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.
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-protectCrypro 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-protectCrypro operations that require use of private or secret material: Decrypt, Unwrap, Sign, Derive and crypto-process
Crypro 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 :
- Key - as above. But the certificate data no longer appears in the Show Info command.
- Certificate - Certificate remains present in the CORE database. To view it, use UCL
Unbound Command Language CLI
Command Line Interface commands.
- 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.
- BYOK
Bring Your Own Key Default: Yes.
- 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
..
Specifies the origin of the key material, what is stored in CORE, and how the external keystore provider should handle the key material:
Nonetheless, the creation of an external key has the following differences:
- The content of the Description applies to CORE only.
- The exportability of a BYOK
Bring Your Own Key key from CORE doesn't depend on the exportability of the key from the keystore.
- Crypto operations permitted to a key must match capabilities provided by the keystore provider.
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:
- Azure - KV Key Types and Create Options.
- AWS - KMS Key Types and Create Options.
- GCP - GCP Key Types and Create Options.
Prerequisites for creating BYOK key in CORE
In general, the settings of a key must comply with the keystore provider's BYOKBring Your Own Key generation requirements.
For example, if the generation of BYOKBring 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:
- The key material is imported to CORE.
- CORE uses the imported material to generate a BYOK
Bring Your Own Key key in the keystore.
- 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 BYOKBring 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 AWS KMSKey Management System:
Key Id in GCP:
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 BYOKBring Your Own Key key material is also stored in CORE, its export conditions are defined by CORE:
- Non-BYOK
Bring Your Own Key - export of key material is forbidden. CORE export commands still can export proxies (OpenSSL, GPG
GNU Privacy Guard - PGP cryptography implementation) that allow access to the key material.
- BYOK
Bring Your Own Key - export rules and conditions are defined by CORE.
Unlink External Key
This command disconnects the CORE UID from the external key. It impacts the UID as follows:
- Non-BYOK
Bring Your Own Key - the UID is discarded
- BYOK
Bring Your Own Key - UID is modified by removing reference to the external key.
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 KMIPKey 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.