ucl export

Exports keys, certificates, and secrets.

For the background material, see Export Permissions and Methods and Export Options and File Formats.

Keys:

Export Public Key

Export Wrapped Key

Export for Integration:

exporting to OpenSSL applications, see Export Obfuscated Private Key

exporting to PGPPretty Good Privacy - PKI implementation keyrings, see Export to PGP Keyring

Note: ucl export (unlike UI export) doesn't support exporting plain key material.

Certificates:

Export Certificate

Export Certificate with Private Key

For exporting to Windows certificate stores, see ucl sync-cert (Windows)

For exporting to MacOS, see ucl sync-cert (MacOS)

Secrets

Export Secret

Common parameters:

Note
If the "name" is associated with multiple elements, the system will make its best effort to identify the required object based on the other command parameters. If the heuristics are non-conclusive, the system responds with the following guidance Name parameter ambiguous, provide UID instead.

Export Public Key

Exports public key of an asymmetric key:

• RSA or ECCElliptic-curve cryptography - an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields in the PEMBase64 encoded DER wrapped by "--- BEGIN <type> ---" and "--- END <type> ----" format
• RSA only in the PGPPretty Good Privacy - PKI implementation Public Key format if the UID includes both private and public parts.

Syntax:

Example of PGPPretty Good Privacy - PKI implementation Public Key format:

ucl export -n MyPGPkey -f PGPPretty Good Privacy - PKI implementation -o MyPGPkey.pgp



-----BEGIN PGP PUBLIC KEY BLOCK-----

Version: EKM

The content of the public key material in the Base64 encoding

=qqVY
-----END PGP PUBLIC KEY BLOCK-----

Export Wrapped Key

This command exports the wrapped key material and additional metadata to the JSON file. Refer to JSON of Key Wrapped by AES.

The following keys may be used for wrapping the exported material:

AES key

Keys that may be exported: AES, XTS, 3DES, CHACHA20, HMACHash-based Message Authentication Code - A MAC involving a cryptographic hash function and a secret cryptographic key.

Mode: GCM, NISTWRAPAES Key Wrap (KW) specified by NIST Special Publication 800-38F, ECB, CBC

Default: GCM

Keys that may be exported: RCA, ECCElliptic-curve cryptography - an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields

Mode: GCM, NISTWRAPAES Key Wrap (KW) specified by NIST Special Publication 800-38F

Default: GCM

NISTWRAPAES Key Wrap (KW) specified by NIST Special Publication 800-38F mode is also known as AES-KWP (AES Key Wrap with Padding). NIST.SP.800-38F.

Public RSA key

Keys that may be exported: AES, XTS, 3DES, CHACHA20, HMACHash-based Message Authentication Code - A MAC involving a cryptographic hash function and a secret cryptographic key.

Padding: PKCSPublic-Key Cryptography Standards - Industry-standard cryptography specifications.#1, OAEPOptimal Asymmetric Encryption Padding - A padding scheme often used together with RSA encryption of symmetric keys.

Default: OAEPOptimal Asymmetric Encryption Padding - A padding scheme often used together with RSA encryption of symmetric keys.

• aad - BASE64-encoded additional authenticated data
• Wrapping Options

--wrap-key, --wrap-key-name

The UID (or name) of the key that is used to wrap the imported material.

Required type: ECCElliptic-curve cryptography - an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields or imported RSA-public

Must allow unwrapping operation.

--mech - (mechanism)

When wrapped with AES, it indicates the mode

When wrapped with RSA Public key, it indicates the padding

The OAEPOptimal Asymmetric Encryption Padding - A padding scheme often used together with RSA encryption of symmetric keys. padding must be further refined:

--hash

The hash type.

See Supported HASH Options.

Default: SHA256

OpenSSL name - rsa_hash_md.

 

--mgf

The padding mask generation function.

See Supported HASH Options.

Default: SHA256

OpenSSL name - rsa_mgf1_md.

 

--oaep-label

An optional string.

Default: empty string.

OpenSSL name - rsa_oaep_label.

JSON of Key Wrapped by AES

In this example:

• We are exporting UID e334f5d971909625 wrapped by AES key "aes-w".
• We generated AADAdditional Authentication Data ( UGFzc3dvcmQxIQ==) by encoding "Password1!" in BASE-64 format.

The generated file aes1-wrapped.json doesn't include the AADAdditional Authentication Data but otherwise provides all necessary data to unwrap it:

ucl export -u e334f5d971909625 --wrap-key-name aes-w --mech GCM \
--aad UGFzc3dvcmQxIQ== -o ./aes1-wrapped.json

• keyData is BASE64-encoded result of wrapping uid by wrapKey.uid.

To import wrapped key using the JSON file, you will need:

• AADAdditional Authentication Data. It is used in the exporting (in BASE64 encoding)
• At least the following elements in the JSON file:

Example:

Assuming that the above data is stored in ./aes-min-wrapped.json file, we can import this key. In this example, the new key will have the default AES metadata settings.

ucl import -i aes3-wrapped.json --unwrap -u 99f711267cf5fbff --unwrap-aad UGFzc3dvcmQxIQ==

New key UID=867562bec294edc0

Note
JSON file for importing a wrapped ECCElliptic-curve cryptography - an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields key must also specify the curve type. For example:
"keyType": "ECCElliptic-curve cryptography - an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields"
"curve": <"P256" | "P384" | "P384" | "P521" | "SECP256K1" | "CURVE25519" | "CURVE448" >

JSON of Key Wrapped by RSA-Pub

To export AES key wrapped by a public RSA key:

1. Import a public RSA key

Note
To use a private RSA key from your partition as a wrapping key:
1. Export its public key.
2. Import the public key back to the partition.

2. Use it in the export command as the wrapping key.

For example, if the name of the public RSA key is rsa4wrap, and the name of the key to be exported is aes4export, then the resulting JSON looks as follows:

Note
The UID saved in the "wrapKey" is the UID of the public key that was used for wrapping.
When importing this JSON-wrapped key back to the partition, the corresponding private RSA key will used for the unwrapping.

Quickstart

In this quickstart we duplicate an AES key from partition A to partition B:

1. In partition B (the receiving partition):
   1. Generate RSA key.
   2. Export its public key (B-PUB).
   3. Import it back. Note its UID. We will use in step 3.
2. In partition A:
   1. Import B-PUB
   2. Use it to export A-AES to a-aes.json file
3. In partition B:
   1. Edit the a-aes.json file and replace the "wrapKey": { "uid": "*********",...} with the UID of B-PUB saved in step 1.c.
   2. Import the a-aes.json file.

Export Obfuscated Private Key

This option creates a PEMBase64 encoded DER wrapped by "--- BEGIN <type> ---" and "--- END <type> ----" file for use by OpenSSL applications. The file contains a handle to the key's UID and a filler string. It applies to RSA and ECCElliptic-curve cryptography - an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields keys. See Obfuscated Key.

Syntax:

Example:

ucl export \

-n "my rsa key" -o from-my-rsa-key-obfuscated.pem \

--obfuscate

-----BEGIN RSA PRIVATE KEY-----
Encoded reference to the UID of the key
UNBOUND/UNBOUND/UNBOUND/..../UNBOUND
-----END RSA PRIVATE KEY-----

Note
In the ECCElliptic-curve cryptography - an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields key case, the content is enclosed by
-----BEGIN EC PRIVATE KEY-----
-----END EC PRIVATE KEY-----

Export Certificate with Private Key

This option exports certificate object and its associated private key object to PFXAn archive file format for storing cryptography objects using Base64 encoding (P12) file. To protect the file, add the --file-pass specification.

Note
The private key must be exportable.

Syntax:

Export Certificate

Exports the certificate object in the following formats:

• CERCertificate file in PEM format using binary encoding.
• PEMBase64 encoded DER wrapped by "--- BEGIN <type> ---" and "--- END <type> ----" using Base64 encoding.
  

Syntax:

Example:

ucl export -n "My sign cert" -o from-my-signing-cert.pem -f PEMBase64 encoded DER wrapped by "--- BEGIN <type> ---" and "--- END <type> ----"

-----BEGIN CERTIFICATE-----
The content of the certificate in the Base64 encoding
-----END CERTIFICATE-----

Export Secret

Note: "Secret" here means object of type secret and not the secret key.

Exports (or prints) the raw data of the specified secret.

Syntax:

Note
To show the secret in the CLICommand Line Interface console, specify CON as the output file. Use capital letters in the CON.

Example: