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

ucl export -u <UID> | -n <name> -o <output file>

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:

Syntax:

ucl export < -u <UID> | -n <name> > // specify either key object's UID or its name [-f PGP] // PGP file, Default: PEM file -o <output file> // PEM file

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

ucl export -n MyPGPkey -f PGPClosedPretty 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, HMACClosedHash-based Message Authentication Code - A MAC involving a cryptographic hash function and a secret cryptographic key.
Mode: GCM, NISTWRAPClosedAES Key Wrap (KW) specified by NIST Special Publication 800-38F, ECB, CBC
Default: GCM
Keys that may be exported: RCA, ECCClosedElliptic-curve cryptography - an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields
Mode: GCM, NISTWRAPClosedAES Key Wrap (KW) specified by NIST Special Publication 800-38F
Default: GCM
Public RSA key
Keys that may be exported: AES, XTS, 3DES, CHACHA20, HMACClosedHash-based Message Authentication Code - A MAC involving a cryptographic hash function and a secret cryptographic key.
Padding: PKCSClosedPublic-Key Cryptography Standards - Industry-standard cryptography specifications.#1, OAEPClosedOptimal Asymmetric Encryption Padding - A padding scheme often used together with RSA encryption of symmetric keys.
Default: OAEPClosedOptimal Asymmetric Encryption Padding - A padding scheme often used together with RSA encryption of symmetric keys.
ucl export -u <UID> | -n <name> -o <output file>
[--aad arg] Additional authenticated data (base64 encoded)
--wrap-key arg Wrapping key UID --wrap-key-name arg Wrapping key name --mech arg Wrap mode. Supported values: AES - GCM, ECB, CBC, NISTWRAP. Default: GCM RSA - PKCS1, OAEP. Default: OAEP
--hash arg Padding hash type --mgf arg the type of Mask Generation Function (OAEP mode only) --oaep-label arg OAEP label (OAEP mode only)

JSON of Key Wrapped by AES

In this example:

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

The generated file aes1-wrapped.json doesn't include the AADClosedAdditional 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" : "YxYV3jCAuxWXxd2MUJp1tkmYegjezxDA\/u7sN3mur5BTVU7\/VIBnxNltB9Q=", "wrapKey" : { "uid" : "99f711267cf5fbff", "name" : "aes-w", "type" : "AES" },
"keyType": "AES", "name": "key4export", "uid": "e334f5d971909625", "description": "",
"ivData : "dST9flLX7TEj+jdm", "supportedOperations": [ "ENCRYPT", "DECRYPT" ], "wrapMode" : "GCM", "partition" : "test", "ukcVersion" : "2.0.2103.39678", "exportedAt" : "2021-05-08T06:07:18Z" }
  • keyData is BASE64-encoded result of wrapping uid by wrapKey.uid.

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

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 ECCClosedElliptic-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": "ECCClosedElliptic-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
  2. 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.

  3. 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:

{ "keyData": "njnNEcDZC3Hi9NS0F9tRmd9lmRBRiRY/..............truncated ........ "wrapKey": { "uid": "7450e08db9cf1b5f", "name": "rsa4wrap", "type": "RSA" },
"keyType": "AES", "name": "aes4export", "uid": "9cbcccb568728864", "description": "", "supportedOperations": [ "ENCRYPT", "DECRYPT" ],
"padding": "OAEP", "hashAlgorithm": "SHA256", "mgfHashAlgorithm": "SHA256", "partition": "test", "ukcVersion": "2.0.2106.42156", "exportedAt": "2021-10-19T18:52:14.663Z" }

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 PEMClosedBase64 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 ECCClosedElliptic-curve cryptography - an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields keys. See Obfuscated Key.

Syntax:

ucl export <-u <UID> | -n <name> -o <output file> --obfuscate

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 ECCClosedElliptic-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 PFXClosedAn 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:

ucl export < -u <UID> | -n <name> > // specify either object's UID or its name -o <output file> // PFX file --with-private // export key material (for exportable RSA keys) [--file-pass <password>] // a pass-phrase to protect the file

Export Certificate

Exports the certificate object in the following formats:

Syntax:

ucl export < -u <UID> | -n <name> > // specify the certificate object's UID or its name -o <output file> [-f <file format: CER | PEM >] //. Default: CER

Example:

ucl export -n "My sign cert" -o from-my-signing-cert.pem -f PEMClosedBase64 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:

ucl export < -u <UID> | -n <name> > // specify either object's UID or its name -o <output file> // -o CON shows the result in your CLI terminal.

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

Example:

ucl export -n my-secret -o CON