ucl generate

You may create private and secret keys in CORE and (or) in the specified external keystore.

Public keys may be only imported.

Key Types and Purpose

The ucl generate command

  • Creates a private or secret key in CORE and in external keystore.
  • Specifies its cryptographic properties and permitted operations.
  • Tags the key with the specified key group tags.
  • Optionally
    • creates its OpenSSL proxy
    • postpones its activation
    • defines the life span of a key

Prerequisites

For the ucl generate command to succeed, the following conditions must be met:

  1. The Partition Key Usage Policy must permit the generation of a key with the specified type and parameters.
  2. Your role description (for the designated key group(s)) must include:
    • Generate-Key permission to create a secret key.
    • Generate-KeyPair permission to create a private key.

Supported Key Types

The following table specifies key types, supported operations, and operations supported by default when generating or importing a key. The key types are grouped in the following classes:

Private key class
Imported or generated private key of an asymmetric key-pair.
Secret key class
Imported or generated symmetric key.
Public key class
Imported public key of an asymmetric key-pair.
Split keys
Parts of a secret key.
UB key class
standard keys optimized by Unbound to provide specific service. For example, PRF keys are generated and used to provide tokenization services.
Key Class Type Size / Curve Default size/curve Supported Operations Default Operations
Private key

RSA

2048, 3072, 4096 2048

 

Sign,

Decrypt,

Unwrap,

Derive

Sign,
Decrypt, Unwrap
ECCClosedElliptic-curve cryptography - an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields

P256, P384, P521,
SECP256K1,
CURVE25519, CURVE448

P256

Sign,

Derive

Secret key

AES

128, 192, 256 256

 

Encrypt, Decrypt

Wrap, Unwrap

Mac, Mac verify

Derive

 

Encrypt, Decrypt

XTS 256, 512 256
CHACHA20 256 256
TDES 192 192
DES 64 64
HMACClosedHash-based Message Authentication Code - A MAC involving a cryptographic hash function and a secret cryptographic key. 8 to 2048, increments of 8 128

Mac, Mac verify, Derive

Public key RSA See "Private key".   Verify, Encrypt, Wrap
ECCClosedElliptic-curve cryptography - an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields

Split key

AES, TDES, HMACClosedHash-based Message Authentication Code - A MAC involving a cryptographic hash function and a secret cryptographic key. See "Secret key".   Join
UB key PRF P256

Derive, Decrypt

  1. To use a public key of a private key, generate the public key and add it to the partition.
  2. "Default size/curve" and "Default operations" specify the size and permitted operations of a key that is created without specifying these properties.
  3. CURVE25519 and CURVE448 are Edwards (Ed) keys if the "Supported Operations" is SIGN and Montgomery(X) keys if it is DERIVE.

External Keys

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

ECC applications

ECDSAClosedElliptic Curve Digital Signature Algorithm - A variant of the Digital Signature Algorithm (DSA) which uses elliptic curve cryptography.
Operation: Sign
Elliptic curves: P256, P384, P521, SECP256K1, Ed25519, Ed448
ECDHClosedDiffie–Hellman (ECDH) is a key agreement protocol used to establish shared secret by deriving it from EC keys.
Operation: Key derivation
Elliptic curves:  P256, P384, P521, X25519, X448

Notes:

  1. To define Edwards Ed25519 or Ed448:
    • use CURVE25519 or CURVE448
    • make sure to specify SIGN among the permitted operations.
  2. To define Montgomery X25519 or X448:
    • use CURVE25519 or CURVE448
    • specify DERIVE as the mandatory operation.
    • Make sure to delete the SIGN operation from the permitted operations list.

  3. Other names used for curves:

Common UCL Generate Options

The following options are applicable to all key types created using the ucl generate command.

--type

Crypto algorithm used by a key.

--name

Default: 0x00 prefix followed by the hexadecimal encoding of its UID.

  • For the allowed character list, see Name and Description.
  • The name is mandatory if the key shall be stored in an external keystore.
  • By default, duplicate names within a partition are allowed. To avert a possible name ambiguity, enable the partition's enforce-unique-name setting. See ucl settings set.

--group

Default: the key group by name default.

A user must be authorized to create key material in all groups specified by the --groups option. For example, if a user is authorized to create a key in good and better groups but not in the best group, the following command will fail:

ucl generate -t <key type> --groups good,better,best --user user2 -w *******

Key generation failed.
User has no permissions to perform CreateKeyPair in groups [good, better, best]

--purpose

Default: refer to Key Types and Purpose.

A key is generated or imported for a specific purpose that cannot be changed. The intended usage of a key is specified in the permitted operations (purpose) setting that may select the options specified in the Supported Operations column. The options are specified using the following abbreviations that are concatenated into a single string:

For example:

The purpose setting notes:

  • It is permanent.
  • It is inherited by the descendants of the key that are generated from it using the derive or rekey (rotation) methods.
  • It has to be specified to permit a particular operation.
  • But it doesn't authorize the execution of the permitted operation by everyone. The authorization is governed by: 
    • The partition's policy.
    • Permissions that are granted to the user that executes the operation.

External keystore.
In some cases, the external key store provider may not support the set of purposes specified by the CORE user. In such a case, only a partial group of the settings is applied. Refer to Purpose of External Key.

--trusted

See Trusted Key.

Activity Period

Default: the key is activated instantly.

Options:

  • --pre-active The key shall be activated later.
  • --activation-date <date> scheduled activation date.
  • --deactivation-date <date> scheduled deactivation date.

Specification of the date:

  • The time is based on UCT (Zero Greenwich time). This is the time used by the CORE servers.
  • It is specified using the ISO8601 format: yyyy-mm-ddThh:mm:ssZ. (note "T" and "Z" characters).

For example, Sep2,2021 06:35:00 UCT time is encoded as 2021-09-02T06:35:00Z. To generate an RSA key that will be instantly activated and automatically deactivated on this date, see the following command:

$ ucl generate -t rsa -n rsa-0902 --deactivation-date 2021-09-02T06:35:00Z

Export Conditions

Default: non-exportable.

To specify export conditions, use one of the following options:

  • --exportable
  • --wrapped
  • --wrapped-with-trusted

This setting specifies the distinctive export requirements. See Key Material Export.

Note
A key material created in the external keystore (e.g. a non-BYOKClosedBring Your Own Key key) inherits the keystore provider's exportability settings. The common practice is to assign it as not exportable. Check with your keystore provider.

--interval

The key is rotated every <arg> day.

Default: no rotation.

--ksname and --byok

Default: Unbound

To store the key material in the external keystore, specify its name using --ksname. The --byok option controls who generates the key material and how it is stored in the external keystore:

ucl generate –t RSA

Generates an RSA key. Syntax:

ucl generate –t RSA [-s <arg>] // default: 2048 [--output <file path>] // See ucl generate [Common UCL Generate Options] // as needed

Example:

Generate (without activation) RSA 2048 key to be used for encryption and decryption by users that have access to key groups GR2 and GR3.

ucl generate -t rsa --name g2g3-rsa1 -g GR2,GR3 --purpose E --pre-activate

ucl generate –t ECC

Syntax:

ucl generate –t ECC [--curve <arg>] // default: P256 [--output <file path>] // See ucl export [Common UCL Generate Options] // as needed

Examples of ECCClosedElliptic-curve cryptography - an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields applications:

ECDSAClosedElliptic Curve Digital Signature Algorithm - A variant of the Digital Signature Algorithm (DSA) which uses elliptic curve cryptography.
Operation: Sign
Elliptic curves: P256, P384, P521, SECP256K1, Ed25519, Ed448
ECDHClosedDiffie–Hellman (ECDH) is a key agreement protocol used to establish shared secret by deriving it from EC keys.
Operation: Key derivation
Elliptic curves:  P256, P384, P521, X25519, X448

Notes:

  1. To define Edwards Ed25519 or Ed448:
    • use CURVE25519 or CURVE448
    • make sure to specify SIGN among the permitted operations.
  2. To define Montgomery X25519 or X448:
    • use CURVE25519 or CURVE448
    • specify DERIVE as the mandatory operation.
    • Make sure to delete the SIGN operation from the permitted operations list.

  3. Other names used for curves:

Examples::

Important
To use the SECP256K1 - based key on the RHEL platform, check the installed OpenSSL version by using the openssl version command. The required version is 1.0.2 or above.
To upgrade the OpenSSL, perform the following steps:
1. Run sudo yum update openssl command on both EP and partner server(s)
2. Restart the EKMClosedEnterprise Key Management - previous name of the product. Service.

ucl generate –t AES

Generates an AES key.

ucl generate –t AES [-s <arg>] // default: 256 [--trusted] // Default: false [--purpose <arg>] // See Prerequisites [Common UCL Generate Options] // as needed

Example:
Generate trusted AES key to be used for wrapping

ucl generate -p CodeSign1 -t AES -s 256 --name aes1 --trusted --purpose W --user so --password *********

ucl generate –t XTS

It generates an AES key for use in XTS-AES mode for sector-based disk encryption.

The supported purposeencrypt/decrypt only. See XTS-AES.

Syntax:

ucl generate –t XTS -s <arg> // default: 256 [--purpose <arg>] // Key Types and Purpose [Common UCL Generate Options] // as needed

Note
As per XTS-AES, size 256 results in 128bit AES key, and size 512 results in 256bit AES key.

ucl generate -t TDES

ucl generate –t 3DES [--purpose <arg>] // See Prerequisites [Common UCL Generate Options] // as needed

Examples:

ucl generate -p CodeSign1 -t TDES --name 3DESKey1

ucl generate -t HMAC

It generates a key for HMACClosedHash-based Message Authentication Code - A MAC involving a cryptographic hash function and a secret cryptographic key. Message AuthenticationClosedProcess used to achieve sufficient confidence in the binding between the Entity and the presented Identity. Code.

Syntax:

ucl generate –t HMAC [-s <key size: 8, 16, etc.. up to 2048>] // default: 128 [--purpose <arg>] // Key Types and Purpose [Common UCL Generate Options] // as needed

Example:

ucl generate -p CodeSign1 -t HMAC -s 256

ucl generate -t CHACHA20

ucl generate -t CHACHA20 [--purpose <arg>] // Key Types and Purpose [Common UCL Generate Options] // as needed

ucl generate -t PRF

PRF keys are designated for use in pseudo-random function (PRF) applications such as tokenization.

Syntax:

ucl generate -t PRF [--purpose <arg>] // See Prerequisites [Common UCL Generate Options] // as needed

ucl generate -t PWD

PWD keys are designated for password encryption and verification

Syntax:

ucl generate -t PWD [--purpose [V] ] // default: Verify [Common UCL Generate Options] // as needed