Key Management Commands

General Notes

Key-pairs (private and public key)

  • Creation of an asymmetric key generates only its private part.
  • To add its public key as a separate object (UID), follow this steps:
    • use the private key to generate and export its public part.
    • import the public part to the partition.
  • If a partition contains both parts (as unique UIDs), operation on one part impacts the other part as follows:
    • rotating (rekey) the private part also rotates the public part.
    • other operations do not impact the matching part. For example, you may destroy the private key leaving. This action doesn't impacts the public key.

Keys with Certificates:

  • Separate UIDs represent a key and its certificate in UCLClosedUnbound Command Language.

  • The following UCLClosedUnbound Command Language commands impact both the key and its certificate
  • ucl delete/activate/revoke/enable/disable/show

  • An import of a key with the certificate chain uses the following naming convention:
    • Name of Key UID - the specified name.
    • Name of its Certificate UID - the specified name.
    • Name of the first certificate in its CA trust chain - <the specified name>-chain0. The -chain<N> sequence continues according to the number of certificates in the chain.

Authorization policies:

  • Partition policy
    • Partition's setting only-crypto does not permit key material management to principals entitled with the USER role.
    • Partition's crypto policy settings may forbid the use of certain crypto algorithms, crypto operations, key-types, and key attributes.
  • Role-based permissions:
  • Trust certification
    • Only SOs can generate or import key material and declare it as "trusted".

ucl list

Lists keys in the specified partition. The --with-destroyed option includes UIDs whose key-material have been destroyed, but the metadata (including the reason and date they were destroyed) was kept in the database.

ucl list [-p [--partition ] <arg> [--with-destroyed] // Default - without destroyed.

Example:

ucl list -p CodeSign1

Partition 2 CodeSign1: 21 objects found

Secret AES key: UID=a69ece81b24e083e Description="“Trusted1" Name="AES256trusted1"

Private RSA key: UID=e1434c31734a1f77 Description="“Trusted1" Name="RSA40 Private ECC key: UID=7a258e0e3d1edfac Description="“Test1" Name="ECCp256Stest1"

//truncated

Note
This command:
1. Does not accept --user and --password parameters.

This command no longer


2. It shows in ASCII hex format a key-name that contains an underscore "_".

ucl show

Shows key data or specific attributes (such as the certificate's sha1 ).

ucl show -u [--uid ] | -n [--name] <arg> // the name or UID of the object [--sha1-only] // Show SHA1 hash value only. Filter the rest.

Example

ucl show --name Cert1 -p codesign10 --sha1-only

93c46386555d4db6c790529bf6b1918c4ec18630

The authenticity of the presented data is confirmed by the Integrity confirmed statement.

ucl activate

Use this command to activate a key that was created, but its activation has been postponed.

ucl activate
-u --uid | -n --name <arg> // the name or UID of the object [<-p --partition <arg>] // the name of the partition

ucl revoke

Use this command to revoke the key.

ucl activate
-u --uid | -n --name <arg> // the name or UID of the object [-p --partition <arg>] // the name of the partition>

ucl enable

Use this command to cancel the suspension of a key.

ucl enable
-u --uid | -n --name <arg> // the name or UID of the object [-p --partition <arg>] // the name of the partition>

ucl disable

Use this command to suspend the use of a key temporarily.

ucl disable
-u --uid | -n --name <arg> // the name or UID of the object [-p --partition <arg>] // the name of the partition>

ucl delete

This command allows for the complete or partial erasing of the specified object (key, certificate, key+certificate, secret). The partial delete clears the key-material leaving its metadata intact.

The command requires confirmation unless it is executed with the --yes option.

ucl delete
-u --uid | -n --name <arg> // the name or UID of the object [--this-object-only] // only the specified UID is deleted [-y --yes ] // Skip confirmation (default: confirmation is required) [--full] // Delete the object completely.(default: partial delete) [-p --partition <arg>] // the name of the partition>
--uid
If the specified key UID has the associated certificate (or vice versa) - both UIDs are affected.
--this-object-only
Delete only the specific UID. The associated peer, if any, is not deleted.
--full
Erase the object (and its associated peer, if any) from the CORE database.
--yes
Bypass confirmation. This flag is case-sensitive.

ucl change-info

Allows updating the metadata associated with the key material.

Note
To execute the ucl change-info command, your role description must include permission to access the key and perform the Attr-Modify operation. See Metadata Operations.

ucl change-info < -u <UID> | -n <name> > // specify either object's UID or its name [--newname <new name>] // change the name [--newdesc <new description>] // change the description [--key-only] // in a key+certificate, change only the key [-g --group <spaceless CSV list of key-group names>] // must specify at least one value [--activation-date <yyyy-mm-ddThh:mm:ssZ>] // UTC key activation date [--deactivation-date <yyyy-mm-ddThh:mm:ssZ>] // UTC key revocation date [-p --partition <arg>] // the name of the partition>
  • --group. A spaceless CSVClosedComma Separated Values list of key-group names. See Membership in Key-Groups.
    • To reset the group list, use --group default.
    • To add or delete a group, respecify the expected list of groups.
  • Note
    By default, each key is a member of the default key-group of the partition. This membership is permanent. There is no need to list it, except when you want to reset the list to the minimum.

  • --newname.
  • Note
    By default, duplicate names within a partition are allowed. To eliminate such possibility, enable the partition's enforce-unique-name setting.
    Likewise, to enforce uniqueness of description, enable the partition's enforce-unique-desc setting.

    Special values:

    • Byte Array name:
      To assign a name using an arbitrary Byte Array, start the name with the 0x prefix followed by the hexadecimal encoding of the entries in the array. For example, to assign to the imported key a name that has 12 in the 1st byte and 34 in the 2nd byte, use --name 0x1234.

      Important
      To use this capability, the --name parameter must have an even number of hexadecimal characters.
      Names with the odd number of hexadecimal characters (e.g., 0x123) or names that start with 0x but contain non-hexadecimal characters (e.g. 0xMyName) are stored using ASCII encoding.
      Notes
      1. All characters in a name are significant. For example, 0x1234 and 0x00001234 are different names.
      2. To assign the name "1234" using its ASCII encoding, don't prefix the name with the 0x prefix.

  • --activation-date

      A modification of the activation-date applies when the key is in the pre-activate phase (see Phases and Keystates). Changing it to the current time of day activates the key instantly.

  • --deactivation-date

      A modification of the deactivation-date applies when the key is in the pre-activate or active phase (see Phases and Key States). Changing it to the current time-of-day deactivates the key instantly.