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 PGP
Pretty 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 ECC
Elliptic-curve cryptography - an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields in the
PEM
formatBase64 encoded DER wrapped by "--- BEGIN <type> ---" and "--- END <type> ----"
- RSA only in the PGP
Pretty 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 PGP
Pretty 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, HMAC
Hash-based Message Authentication Code - A MAC involving a cryptographic hash function and a secret cryptographic key.
- Mode: GCM, NISTWRAP
AES Key Wrap (KW) specified by NIST Special Publication 800-38F, ECB, CBC
- Default: GCM
- Keys that may be exported: RCA, ECC
Elliptic-curve cryptography - an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields
- Mode: GCM, NISTWRAP
AES Key Wrap (KW) specified by NIST Special Publication 800-38F
- Default: GCM
- Keys that may be exported: AES, XTS, 3DES, CHACHA20, HMAC
- Public RSA key
-
- Keys that may be exported: AES, XTS, 3DES, CHACHA20, HMAC
Hash-based Message Authentication Code - A MAC involving a cryptographic hash function and a secret cryptographic key.
- Padding: PKCS
Public-Key Cryptography Standards - Industry-standard cryptography specifications.#1, OAEP
Optimal Asymmetric Encryption Padding - A padding scheme often used together with RSA encryption of symmetric keys.
- Default: OAEP
Optimal Asymmetric Encryption Padding - A padding scheme often used together with RSA encryption of symmetric keys.
- Keys that may be exported: AES, XTS, 3DES, CHACHA20, HMAC
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: ECC
Elliptic-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
OAEP
padding must be further refined:Optimal Asymmetric Encryption Padding - A padding scheme often used together with RSA encryption of symmetric keys.
-
--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 AAD
Additional 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 wrappinguid
bywrapKey.uid.
To import wrapped key using the JSON file, you will need:
- AAD
Additional 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:
- Import a public RSA key
- Use it in the export command as the wrapping 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.
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:
- In partition B (the receiving partition):
- Generate RSA key.
- Export its public key (B-PUB).
- Import it back. Note its UID. We will use in step 3.
- In partition A:
- Import B-PUB
- Use it to export A-AES to a-aes.json file
- In partition B:
- Edit the a-aes.json file and replace the "wrapKey": { "uid": "*********",...} with the UID of B-PUB saved in step 1.c.
- 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 ECC
Elliptic-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 PFX
file. To protect the file, add the An archive file format for storing cryptography objects using Base64 encoding (P12)
--file-pass
specification.
Note
The private key must be exportable
.
Syntax:
Export Certificate
Exports the certificate object in the following formats:
CER
using binary encoding.Certificate file in PEM format
PEM
using Base64 encoding.Base64 encoded DER wrapped by "--- BEGIN <type> ---" and "--- END <type> ----"
Syntax:
Example:
ucl export -n "My sign cert" -o from-my-signing-cert.pem -f PEM
Base64 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: