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:
- The Partition Key Usage Policy must permit the generation of a key with the specified type and parameters.
- 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 |
ECC![]() |
P256, P384, P521, |
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 | |||
HMAC![]() |
8 to 2048, increments of 8 | 128 |
Mac, Mac verify, Derive |
||
Public key | RSA | See "Private key". | Verify, Encrypt, Wrap | ||
ECC![]() |
|||||
Split key |
AES, TDES, HMAC![]() |
See "Secret key". | Join | ||
UB key | PRF | P256 |
Derive, Decrypt |
- To use a public key of a private key, generate the public key and add it to the partition.
- "Default size/curve" and "Default operations" specify the size and permitted operations of a key that is created without specifying these properties.
- 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
- ECDSA
Elliptic 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
- ECDH
Diffie–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:
- To define Edwards Ed25519 or Ed448:
- use CURVE25519 or CURVE448
- make sure to specify SIGN among the permitted operations.
- 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.
- 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 CSV
Comma 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 MAC
Activation Code
-
V for Verify or MAC
Message Authentication Code - for example, CMAC, GMAC, HMAC. Verify
For example:
- To create an ECC
Elliptic-curve cryptography - an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields key for the ECDSA
Elliptic 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 ECC
Elliptic-curve cryptography - an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields key for the ECDH
Diffie–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:
- ECDSA
Elliptic 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
- ECDH
Diffie–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:
- To define Edwards Ed25519 or Ed448:
- use CURVE25519 or CURVE448
- make sure to specify SIGN among the permitted operations.
- 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.
- 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 ECDSA
Elliptic Curve Digital Signature Algorithm - A variant of the Digital Signature Algorithm (DSA) which uses elliptic curve cryptography. key
- Generate ECDH
Diffie–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 ecdsa1 --purpose S
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 Authentication
Process 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: