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
	ECCElliptic-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
	HMACHash-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
	ECCElliptic-curve cryptography - an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields
Split key	AES, TDES, HMACHash-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

Notes

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:

• Azure - KV Key Types and Create Options.
• AWS - KMS Key Types and Create Options.
• GCP - GCP Key Types and Create Options.

ECC applications

ECDSAElliptic 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

ECDHDiffie–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:
   • P256 is known as SECG' secp256r1 and ANSI' prime256v1.
   • P384 is known as SECG' secp384r1.
     See RFC 8422 Appendix A - Equivalent 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.

• It is spaceless CSVComma Separated Values list of key group names. See Membership in Key-Groups.
• Regardless of the setting, each key is also a permanent member of the default key group.

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:

• S for Sign
• E for Encrypt
• C for deCrypt
• D for Derive
• W for Wrap
• U for Unwrap
• M for MACActivation Code

• V for Verify or MACMessage Authentication Code - for example, CMAC, GMAC, HMAC. Verify

For example:

• To create an ECCElliptic-curve cryptography - an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields key for the ECDSAElliptic Curve Digital Signature Algorithm - A variant of the Digital Signature Algorithm (DSA) which uses elliptic curve cryptography. application, specify the --purpose S option.
• To create an ECCElliptic-curve cryptography - an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields key for the ECDHDiffie–Hellman (ECDH) is a key agreement protocol used to establish shared secret by deriving it from EC keys. application, specify the --purpose CD option.
• To create a symmetric key that allows encrypt and decrypt operations, specify --purpose EC.

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-BYOKBring 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:

• If --byok is omitted: CORE generates a non-BYOKBring Your Own Key key in the specified keystore and links it.
• If --byok is specified: The key is generated in CORE and securely transferred to the external keystore as BYOKBring Your Own Key.

Note
To perform a secure transfer of a key to the keystore, the transfer must issued by a user with appropriate privileges. See Prerequisites for creating BYOK key in CORE.

ucl generate –t RSA

Generates an RSA key. Syntax:

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:

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

ECDSAElliptic 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

ECDHDiffie–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:
   • P256 is known as SECG' secp256r1 and ANSI' prime256v1.
   • P384 is known as SECG' secp384r1.
     See RFC 8422 Appendix A - Equivalent Curves.

Examples::

• Generate ECDSAElliptic Curve Digital Signature Algorithm - A variant of the Digital Signature Algorithm (DSA) which uses elliptic curve cryptography. key

ucl generate -t ECC --curve CURVE25519 --name ecdsa1 --purpose S

• Generate ECDHDiffie–Hellman (ECDH) is a key agreement protocol used to establish shared secret by deriving it from EC keys. key

ucl generate -t ECC --curve CURVE25519 --name ecdh1 --purpose CD

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 EKMEnterprise Key Management - previous name of the product. Service.

ucl generate –t AES

Generates an AES key.

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 purpose: encrypt/decrypt only. See XTS-AES.

Syntax:

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

ucl generate -t TDES

Examples:

ucl generate -t HMAC

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

Syntax:

Example:

ucl generate -p CodeSign1 -t HMAC -s 256

ucl generate -t CHACHA20

ucl generate -t PRF

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

Syntax:

ucl generate -t PWD

PWD keys are designated for password encryption and verification

Syntax: