Contribute in GitHub:

UKO key hierarchy setup

UKO requires the setup of a key hierarchy as shown in the following picture:

Note: All keys are always handled within the Hardware Security Module (HSM). The master keys reside within the HSM itself, while all other keys are either in the UKO key repository, local keystore, or both.

Key settings in the administration panel

The UKO is set in the Administration panel, which you can find in the left navigation bar.

To establish the key hierarchy, you need to specify the following values:

UKO recovery key label (AES), also called Disaster Recovery Key (DRK)
AES DATA keys KEK label (RSA)
AES CIPHER keys KEK label (AES)

In addition, the following key labels are required:

UKO integrity key label
UKO identity key label
UKO secrets encryption key label

You can find a detailed description of each key in the administration panel documentation.

Most of the keys will be generated by UKO after you specified the labels and clicked the Save changes button. Note that the liberty server ID ${UKO_SERVER_STC_USER} needs access to the corresponding CSFKEYS security profile.

The one key that needs to be provided upfront and cannot be generated by UKO is the recovery key.

Creating the recovery key

UKO requires the secure creation of the UKO Disaster Recovery Key (DRK). The DRK must be created in such a way that it is recoverable. The recommended approach is to store the DRK in parts, such that it can be reconstructed from these key parts. The following options for the DRK generation are available:

Trusted Key Entry (Trusted Key Entry)
EKMF Workstation
WDR Disaster recovery key generator
If you are only setting up UKO in a test, demonstration or Proof of Concept environment, you can create a fixed recovery key. This option is only for demonstration or testing purposes and must not be used for production.

Note: If TKE isn’t available, key parts and their corresponding key check values can be created and calculated using ICSF and then recorded on paper. Note that key part creation for the UKO DRK using ICSF isn’t considered secure. Keeping track of the paper copies of the key parts and storing them securely will be critical to prevent data loss in case the CKDS is corrupted. Each key part should be stored separately, such that no single individual has access to all parts. Entry of these key parts to build the DRK will require the use of the ICSF API.

Setting up hierarchy keys by using Trusted Key Entry (Trusted Key Entry)

When using TKE (recommended, especially for production systems), these key parts can be securely generated and stored on smart cards. Subsequently, the key parts can be loaded from the smart cards and can installed in the CKDS keystore using ICSF. Restoring the DRK follows the same key loading process using the existing key parts on smart cards.

The key must be an IMPORTER created with the following keywords:

IMPORT,GEN-IMEX,GEN-PUB,TRANSLAT,WR-AES,WR-RSA,WR-KEK

We also recommend limiting the key's export options:

NOEX-SYM,NOEX-RAW,NOEXUASY,NOEXAASY,NOEX-DES,NOEX-AES,NOEX-RSA

Select a label based on your naming convention, generate the key and import it into the local keystore using ICSF, so you can use it in the Settings.

Setting up hierarchy keys by using EKMF Workstation

If you have EKMF Workstation, you should use it to create the hierarchy keys. You can use the provided key templates for UKO as the basis for your setup. Import the key templates in UKO and generate the keys as you normally do. UKO automatically picks up the key labels from the repository when the keys are activated. It searches for the newest active keys created by the following key templates:

UKO Recovery Key: AES-W010
KEK for AES DATA Keys: RSA-W050
KEK for AES CIPHER Keys: AES-W011

For UKO users, these templates can be imported into the workstation using the EKMF_WEB_HIERARCHY.xml file included in the UKO release package.

Setting up hierarchy keys by using the WDR disaster recovery key generator

When you use ICSF then the recommendation is to enter CryptoExpress master keys via TKE (Trusted Key Entry workstation) and for the UKO disaster recovery key the recommendation is as well to enter it via TKE. Keys entered via TKE are never revealed outside the HW boundary. Furthermore TKE enables dual control, so that keys can be entered by several users that don't know the clear key value of the entire key. Also TKE offers to disable cryptographic functionality in the CryptoExpress, which effectively can prevent various unintended uses of the system.

This tool is for installations that aware of the risk and have decided to continue using CryptoExpress without TKE. It enables the creation of the UKO disaster recovery key with dual user control, and hereby also splitting the knowledge of the key as far as the limitations stated in the disclaimer.

After installing UKO, the tool will be available in the installation folder under /resources/wdr/. Refer to the $README file to install the package and afterwards to the $DOC file for the setup of the ISPF panels.

Setting up hierarchy keys by using a fixed value key for demo purposes

UKO provides a utility that can be used to create a known, fixed-value DRK that can be used for initial testing and isolated proof of concepts. The tool will create a 256 bit AES Importer key with the key value 3DF4B30AE33ED6E22EEBA06359512ACB2B7F9AA006105943C93E8BF30EACF700 and ENC-ZERO key check value '5D7DDC'. In case the DRK is lost from the CKDS, rerunning the utility will recreate the key and allowing recovery of the keys stored in the UKO repository. As the key value is known, this utility is only appropriate to use for functional testing and proof of concepts. A setup based on this key should not be considered secure. Do not use this key in production.