Certificate Commands

This section specifies UCLClosedUnbound Command Language commands addressing:

For the general certificate import and export command description, see:

ucl csr

It generates CSRClosedCertificate Signing Request - a message sent from an applicant to a certificate authority in order to apply for a digital identity certificate and signs it with the key (including key stored in the external key store).

Prerequisites:

  • The user's role description must include permission to perform the Sign operation using the specified key.
  • The referred key must allow its use for signing.
ucl csr <-u <UID> | -n <key name> > // CSR is generated for this asymmetric key
-p <arg> // partition
--subject "<subject string in quotes>" // see CSR Distinguished Name Special Characters -o <output file>.<csr> // CSR file [-f --format <DER | PEM>] // CSR file format. Default: DER [--hash <SHA1, SHA256, SHA284, SHA512>] // default: SHA256

Example:

We will generate CSRClosedCertificate Signing Request - a message sent from an applicant to a certificate authority in order to apply for a digital identity certificate for the following subject (and sign it using the RSA key by name csr-key):

  • CN=Provider
  • OU=Support & Sales
  • O=A+PlusComma, Ltd.

Generate csr-sign-key:

ucl generate -t rsa --name csr-sign-key

Generate test.csr in PEMClosedBase64 encoded DER wrapped by "--- BEGIN <type> ---" and "--- END <type> ----" format and sign it using the key

ucl csr --name csr-sign-key -o test.csr -f PEM \
--subject "CN=Provider, OU=Support & Sales, O=A\+PlusComma\, Ltd."

Note
The (+) and (,) characters in O=A\+PlusComma\, Ltd. are escaped by the backward slash (\). See CSR Distinguished Name Special Characters.

Note
CN, OU, and the other strings in the --subject parameter are limited to 64 characters by the X.509 spec.

ucl self-sign

It generates self-signed certificate for a key in the CORE partition and stores in the specified file. By default, the certificate is also kept in the partition. Notes:

  • The certificate's issuer is set as specified by the certificate's subject.
  • The certificate object name is the name of the key used to generate it.
  • The same certificate may be created multiple times.

Syntax:

ucl self-sign <-u <UID> | -n <key name> >
-p <arg> // partition name
--subject "<subject string in quotes>" // see CSR Distinguished Name Special Characters -o <output file>.<cer> // certificate file [-f --format <DER | PEM>] // certificate file format. Default: DER [--no-import] // Default: certificate is stored in the partition --days <validity period> // number of days this certificate may be used [--hash <SHA1, SHA256, SHA284, SHA512>] // Default: SHA256

In the following example we:

ucl generate -t rsa -n rsa1
ucl self-sign -n rsa1 -o rsa1-cert.pem --format PEM --subject "CN=Provider" -days 100
  • Inspect the result:
ucl list | grep rsa1
Certificate : UID=d801ba09c7ad5f38 Name="rsa1" Private RSA key : UID=f32f47e2aa81ea60 Name="rsa1"

ucl import-store (Windows)

This command copies certificates from the specified My certificate store to the specified partition. The possible certificate stores are: 

  • cert:\currentuser\My ( the default)
  • cert:\localmachine\My
ucl import-store -p <partition name> [--local] // Use cert-store \localmachine\My. [--xorg] // Delete original key material
--local
To use this option, run the command in the elevated mode ("Run as Administrator"). Refer to the following instructions:
- To elevate the Run Command, see Elevated Run.
- To elevate the PowerShell Command, see Elevated PS.

Example. To import certificates from cert:\currentuser\My to Codesign1 partition:

ucl import-store -p CodeSign1

Note
To import a certificate stored in a file to both the CORE partition and Windows cert-store, see Import Certificate on Windows.

ucl sync-cert (Windows)

This command copies certificate(s) from the CORE partition to Windows cert-store and tags them with Provider Name: Dyadic Security. The default cert-store is cert:\currentuser\My. The command has two modes:

  • Sync all certificates (default). It clears all certificates tagged with Provider Name: Dyadic Security from the specified store and copies all certificates from the specified partition to it.
  • Copy a single certificate (--uid).
ucl sync-cert [-p --partition <arg>] // the name of the partition> [--uid <certificate UID>] // copy the specific certificate. Default: sync all certificates. [--local] // use LocalMachine stores scope. Default: CurrentUser. [--store <storename>] // the name of cert-store in the selected scope. Default: My [--csp | --ksp] // the key-material processing method. Default: depends on cert-store-csp setting [--process_ca] // Copy certificates in the trust chain
--uid
Default: all certificates are synced.
--local
target the cert:\localmachine\<store>
Default: cert:\currentuser\<store>
--store
cert-store name. Refer to Store Names
Default: My
--csp | --ksp - see CSP vs. KSP Consideration.
If omitted, the selection depends on the client appliance setting cert-store-csp (Client Appliance Settings Summary). The default processing type is KSP. To use CSP processing, set cert-store-csp = 1.
--process_ca
Default - do not copy the certificate's trust chain. Else, copy to the Root and CA stores.

Note
To update cert:\localmachine\<store>, run the command in elevated mode. Refer to ucl import-store (Windows).

Note
To skip the expired certificates, enable the check-exp setting in the CORE Client Appliance Settings.

CSP vs. KSP Consideration

Windows certificate store provides two methods for using the key material associated with a certificate: CSP and KSP (CNG). The KSP method supports a wider range of capabilities (such as ECCClosedElliptic-curve cryptography - an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields-key certificates) but may not work with legacy applications. See Key Storage and Retrieval.

CORE provides two plugins required to meet the certificate processing methods used by the Windows applications. The method is specified by command parameter --ksp | --csp. If omitted, the cert-store-csp CORE Client Appliance Settings is checked:

  • 0 (the default) This option tags the certificate provider as Dyadic Security Key Storage Provider (KSP/CNG).
  • 1 This option tags the certificate provider as Dyadic Security Base Cryptographic Provider (CSP).

We recommend starting by importing the certificate with the default --ksp option. If this option fails, delete the certificate from the store and re-import it using the --csp option.

Troubleshooting

Examine Cert-Stores

To examine the content of a cert store run the certmgr.exe in PowerShell.

certmgr.exe [-r <currentUser|localMachine>] [-s <StoreName>]

Example:

certmgr.exe -r currentuser -s my

To filter the output to show only the CORE provider's certificates, use "Dyadic" to filter out the other certificates.

certmgr.exe -r currentuser -s my | Select-string Dyadic

Provider Type:: 0 Provider Name:: Dyadic Security Key Storage Provider Container: My sign cert
Provider Type:: 0 Provider Name:: Dyadic Security Key Storage Provider Container: My Self-Signed Root CA

The output indicates that handling of "My sign cert" and "My Self-Signed Root CA" shall be carried by Dyadic Security Key Storage Provider (KSP)CORE client registers a certificate in the Windows cert-store using the following Provider Name tags:

  • KSP- Provider Name:: Dyadic Security Key Storage Provider.
  • CSP- Provider Name:: Dyadic Security Base Cryptographic Provider.

Tip
You can use PowerShell for Certificate Providers commands.
To list certificates using PowerShell, run
Get-ChildItem -Path Cert:\<currentuser | localmachine>\<store-name>\
For example,
Get-ChildItem -Path Cert:\localmachine\my\
Get-ChildItem -Path Cert:\currentuser\my\

You may also use the dir alias of this command as follows:
dir cert:\localmachine\my
dir cert:\currentuser\my

Verification

Verification includes two steps:

  1. Confirmation that the certificate with the expected SHAClosedSecure Hash Algorithm - a family of cryptographic hash functions-1 is listed in the specified cert-store.
    • List all entries in the partition
    • ucl list -p <partition>

      Partition 0 codesign: 2 objects found
      Certificate : UID=bf0fb6699dc32861 Name="sign-key1-cert"
      Private RSA key : UID=40f04996623cd79e Name="sign-key1

    • Find SHA1 thumbprint of the required certificate
    • ucl show --uid bf0fb6699dc32861 --sha1

      eb78caf29c72fb9bad3272beb8e060411ee2c7dd

    • Using PowerShell, list the certificates and their SHAClosedSecure Hash Algorithm - a family of cryptographic hash functions-1 thumbprints in the cert-store. For example,
    • dir cert:\currentuser\my

      PSParentPath: Microsoft.PowerShell.Security\Certificate::currentuser\my
      Thumbprint Subject
      ---------- -------
      EB78CAF29C72FB9BAD3272BEB8E060411EE2C7DD CN=builder1, OU=QA, O=Unbound
      7497D9309226F37E7D107BBD13D9E2DB0E6DD65D CN=Unbound 26B3F59A3A4CA438C9C55F9D7F598E2B7603C70F CN=Unbound UKC Root CA G1.

  2. Confirmation that it will be processed by the expected method (CSP vs. KSP).
  3. To examine the certificate's Provider Name, run the following command:

    certmgr.exe -r currentuser -s my

    Search in the output for the certificate with the required SHA1 Thumbprint:: value and examine the Provider Name::

    // deleted
    SHA1 Thumbprint::
    EB78CAF29C72FB9BAD3272BEB8E060411EE2C7DD
    // deleted
    Provider Type:: 0
    Provider Name:: Dyadic Security Key Storage Provider
    Provider Container: <name of the key>
    // deleted

ucl sync-cert (MacOS)

This command collects certificates managed by the specified CORE partition and stores their representatives in an internal MacOS file that the Sign MacOS Application uses.

To avoid copying the expired certificates, enable the client's check-exp setting.

Syntax:

ucl sync-cert -p [--partition ] | -s [--slot] <arg> // the name or slot number of the partition

Options:

  • --partition - specifies the CORE partition.
    It is optional if the client is registered with a single partition.