ucl import

Use the ucl import command to import the following crypto material:

Prerequisites

To execute the ucl import command:

  • The partition's policy must permit importing the specified material.
  • Your role must include the Import permission to all key-groups specified by the --groups parameter or to the default group if the --groups parameter is omitted.
  • If the imported key is wrapped, your role must permit the unwrap operation using the specified unwrapping key.

Common Import Options

All import commands share the following options:

[--name <the imported object's name>] // Default: "0x00<UID>" [--desc <description>] [--group <spaceless CSV list of group-names>] // Default: key-group "default"

Import Certificate

These options address importing a certificate file w/out its trust chain. If the input file contains a trust chain - the members of the trust are assigned to the distinctive UIDs and assigned the following names

  • Name of the Certificate UID - the specified name.
  • Name of the first certificate in its trust chain - the specified name>-chain0. The -chain<N> sequence continues according to the number of certificates in the chain.
ucl import -i <input file> Common Import Options
[--in-format <format>] // Input file format: CER, PFX [--file-pass <input file password>] // expected when importing PFX file [--process-ca] // See below [--renew] // See below
  • --process-ca
  • This option makes sure that the certificates in the trust chain are also stored in the partition.

  • --renew
    • If cert with the specified --name already exists in the partition, its name is changed by appending the time-of-day - see the example below.

Example:

  1. List the key material before the import command:
  2. ucl list

    Partition 0 test: 3 objects found Certificate : UID=b2178ba73e11196f Description="test-chain0" Name="test-chain0" Certificate : UID=dd015050469e4ef1 Description="test" Name="test" Private RSA key : UID=22feafafb961b10e Description="test" Name="test"
  3. Run the import command
  4. ucl import -i test-cert.pem --name test --desc test --renew

  5. List the key material after the import command:
  6. ucl list

    Partition 0 test: 5 objects found Certificate : UID=c353a879ab1101d9 Description="test" Name="test" Certificate : UID=dd015050469e4ef1 Description="test-2019-02-03 15:11:15" Name="test-2019-02-03 15:11:15" Certificate : UID=fa77ccc2f229de83 Description="test-chain0" Name="test-chain0" Private RSA key : UID=22feafafb961b10e Description="test-2019-02-03 15:11:15" Name="test-2019-02-03 15:11:15" Private RSA key : UID=3cac578654eefe26 Description="test" Name="test"

Note
It is possible to import multiple certificates with the same key.

Import Certificate on Windows

In the Windows client, the ucl import certificate command imports the certificate to the CORE and updates the specified Windows cert-store on the machine that runs the command. Default: Cert:\currentuser\My.

ucl import -i <input file> Common Import Options
[--in-format <format>] // Input file format: CER, PFX [--file-pass <input file password>] // expected when importing PFX file [--process-ca] // See Import Certificate [--renew] // See Import Certificate [--local] // Default: "Cert:\currentuser\<store>" [--store <cert-store >] // Default: "my" Common Import Options
--local
If this flag is omitted, the store is Cert:\currentuser\<store>
If it is specified, the store is Cert:\localappliance\<store>
--store
If this flag is omitted, the store is My store

In the following example, we import a certificate from the sign-cert.p12 file to the codesign partition and to the Cert:\currentuser\My store:

ucl import -p codesign -i sign-cert.p12 --file-pass *******

Private key UID=48132abf000d6feb
Certificate UID=b7ecd540fff29014

To examine the result of this command, run the following:

  1. Show the SHA1 thumbprint of the certificate imported to CORE:
  2. ucl show -p codesign -u b7ecd540fff29014 --sha1-only

    234245019464f73f82c11e9808fcbbee88258f08

  3. Make sure that the certificate with the same SHA1 appears in Cert:\currentuser\my:
  4. dir cert:\currentuser\my

    Thumbprint
    234245019464F73F82C11E9808FCBBEE88258F08

Import Public RSA Key

To use the RSA key for wrapping, encryption, and verification of a signature, import it from the PEMClosedBase64 encoded DER wrapped by "--- BEGIN <type> ---" and "--- END <type> ----" containing only the key's public part. Supported formats are:

  • PKC#8
  • -----BEGIN PUBLIC KEY----- pub-key data -----END PUBLIC KEY-----
ucl import -i <input file> Common Import Options
[--in-format <format>] // Input file format: PEM (also known as CER) [--trusted] // Default: false

Note
Use --trusted if this key shall be used to wrap material that must be wrapped using a trusted key.

Import Key and Certificate

If a PEMClosedBase64 encoded DER wrapped by "--- BEGIN <type> ---" and "--- END <type> ----" or PFXClosedAn archive file format for storing cryptography objects using Base64 encoding file contains both a key and its certificate, both materials are imported. The command options combine both the key and the certificate options:

Note: to import only the key material, use the --key-only option.

Import Plain Key

Use this method when the key material is provided in plain either in BIN(default), HEX, or BASE64 encoding.

ucl import -i <input file> Common Import Options
[--in-format <format>] // BIN (default), HEX, BASE64 -t --type <expected key type> // see Key Types and Purpose [--purpose <arg>] // [-g --groups <arg>] // see --group
[--ksname <keystore> [--byok]] // See --ksname and --byok
[--obfuscate] // generates also Obfuscated Key for imported RSA or ECC
[--exportable | --wrapped | --wrapped-with-trusted] // see Export Conditions. Default: non-exportable.
[-r --interval <arg> ] // Interval for Key Rotation (days). Default: no rotatation
// Activation/deactivation [--pre-active] // the key enters Pre-Operational. Default: false [--activation-date // in ISO8601 format: yyyy-mm-ddThh:mm:ssZ Default: now [--deactivation-date] // in ISO8601 format: yyyy-mm-ddThh:mm:ssZ Default: never // see Dates in Key's Lifecycle

Notes
Import of key material from the PEMClosedBase64 encoded DER wrapped by "--- BEGIN <type> ---" and "--- END <type> ----" file that contains metadata in its header (for example, PEMClosedBase64 encoded DER wrapped by "--- BEGIN <type> ---" and "--- END <type> ----" files in Docker Notary) preserves the header in the ApplicationInfos field of the key and restores it when the key material is exported.

It is mandatory to specify the expected key type when importing plain key material of a secret key.

Import Wrapped Key

A wrapped key must be provided in the JSON file together with other parameters required for unwrapping. See example in JSON of Key Wrapped by AES.

ucl import -i <input file> Common Import Options
-t --type <expected key type> // see Key Types and Purpose [--purpose <arg>] [-g --groups <arg>] // see --group
[--ksname <keystore> [--byok]] //See --ksname and --byok
[--obfuscate // generates also Obfuscated Key for imported RSA or ECC
[--exportable | --wrapped | --wrapped-with-trusted] // see Export Conditions. Default: non-exportable.
// Activation/deactivation [--pre-active] // the key enters Pre-Operational. Default: active [--activation-date // in ISO8601 format: yyyy-mm-ddThh:mm:ssZ Default: now [--deactivation-date] // in ISO8601 format: yyyy-mm-ddThh:mm:ssZ Default: never // see Dates in Key's Lifecycle
// Unwrapping parameters [ -u --uid <UID>] // UID of unwrapping key [--unwrap-key-name <key name>] // name of the unwrapping key [--unwrap-aad <BASE-64>] // Additional authenticated data (BASE64 encoded)
  • aad - BASE64-encoded additional authenticated data
  • --unwrap-uid, --unwrap-key-name

Example:

Assume that ./aes-min-wrapped.json contains the following data protected by BASE64 encoding of "Password1!" (UGFzc3dvcmQxIQ==)

{ "keyType" : "AES", "wrapMode" : "GCM", "keyData" : "YxYV3jCAuxWXxd2MUJp1tkmYegjezxDA\/u7sN3mur5BTVU7\/VIBnxNltB9Q=", "ivData : "dST9flLX7TEj+jdm", "wrapKey" : { "type" : "AES", "uid" : "99f711267cf5fbff" } }

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

Import Plain Secret

This option allows storing any file or input provided via CLIClosedCommand Line Interface as an MPCClosedMultiparty computation - A methodology for parties to jointly compute a function of their inputs while keeping those inputs private.-shares in the CORE cluster using MPCClosedMultiparty computation - A methodology for parties to jointly compute a function of their inputs while keeping those inputs private. shares.

ucl import -i <input file> Common Import Options
[--secret] // Import raw file or a string from CLI [--file-pass <input file password>

For example,

ucl import -p codesign10 --secret -i CON --name Password

Enter the secret data: *********
Retype: **********
Private key UID=2555214283f996d5

The secret data is tagged as "Data object" when listing the partition key material:

$ ucl list -p codesign10

Partition 0 codesign10: 5 objects found
Private RSA key: UID=ca1425e91eb68f36 Name="wsrootsign3.pfx"
Private RSA key: UID=d0c42164114c937a Name="0x00d0c42164114c937a"
Data object: UID=d538cc11380300f4 Name="Data file"
Data object: UID=2555214283f996d5 Name="Password"
Certificate: UID=35ebda16e14970c9 Name="wsrootsign3.pfx"

Notes
1. To show a secret, use the ucl export -o CON -u <uid> command. See the ucl export command.
2. By default, the max plain-text size of a secret is 4000 Bytes. To change this limit, refer to the static system setting inSystem Static Properties.