Sync Windows Certificate Store

To align certificates stored in the UKCUnbound Key Control - The name of Unbound's key management product. partition with the Windows certificate store, use one of the following commands:

• ucl sync-cert (Windows) - syncs certificate(s) from the specified UKCUnbound Key Control - The name of Unbound's key management product. partition to the specified Windows cert-store if the client's cert-auto-sync setting is disabled (the default state).
• ucl import-store - copies certificates from the specified store to the specified partition.

Besides, the ucl import command provides an option for importing the certificate to both the specified partition and the specified Windows store when executed in the Windows client.

ucl sync-cert (Windows)

Introduction

This command copies certificates from the specified UKCUnbound Key Control - The name of Unbound's key management product. partition to the specified Windows cert-store.

It doesn't require UKCUnbound Key Control - The name of Unbound's key management product. user credentials, but the specified partition must be registered by the client machine.

The command has two options :

• Sync the certificates tagged with Provider Name: Dyadic Security in the specified Windows store with the certificates stored in the specified partition. This option performs the following:
  • Clears all certificates tagged with Provider Name: Dyadic Security from the specified store.
  • Copies all certificates from the specified partition to the store and tags them with the Provider Name: Dyadic Security tag.
• Copy a single certificate. In this case, other certificates tagged with Provider Name: Dyadic Security in the cert-store are not affected.

In addition, the command's options allow:

• Specifying the certificate processing method by the Windows applications:
  • --ksp. This option tags the certificate provider as Dyadic Security Key Storage Provider (KSP/CNG).
  • --csp. This option tags the certificate provider as Dyadic Security Base Cryptographic Provider (CSP).
    

Refer to CSP vs KSP Consideration.


Important
Windows CSP processing can handle only RSA keys. Because of that, ECCElliptic-curve cryptography - an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields-key certificates are omitted when the --csp option is specified.

• --process_ca. For each copied certificate, also copy certificates from its trust chain, if they are stored in the UKCUnbound Key Control - The name of Unbound's key management product. partition.

Notes and Prerequisites

• If the client's cert-auto-sync setting is enabled, this command doesn't update the specified Windows cert-store. Instead, it presents the corresponding warning.
• If you plan to sync a key store with multiple partitions, make sure that no two certificates in the selected partitions share the same name.

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

Command Options

Syntax:

Options:

• --partition - is optional if the client is registered with a single partition.
• --uid - if specified, must be UID of a certificate.
  
  
• --local and --store - refer to Windows cert-store specification.

Important
To use the --local option, execute the command using Windows elevated mode ("Run as Administrator"):
- To elevate the Run Command, refer to Elevated Run.
- To elevate the PowerShell Command, refer to Elevated PS.

• --csp | --ksp - refer to CSP vs KSP Consideration.
  If omitted, the output depends on the client's setting cert-store-csp (as follows:
  • cert-store-csp == 0 results in KSP-based processing (the default).
  • cert-store-csp == 1 results in CSP-based processing.
• --process_ca - this option directs the client to copy all certificates specified in the certificate's trust chain AND present in the partition to the corresponding trust stores ("Root" and "CA").

UKC Certificates in the Windows Store

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 UKCUnbound Key Control - The name of Unbound's key management product. provider's certificates, grep the "Dyadic" string in the output. The following example shows two certificates handled by UKCUnbound Key Control - The name of Unbound's key management product.:

• My sign cert
• My Self-Signed Root CA

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

In this case, the provider name is Dyadic Security Key Storage Provider. It directs Windows to apply the KSP method when handling these certificates. Refer to Examine the Provider's Name for additional examples.

Sync-cert Examples

• If you are a client of a single partition, to sync all certificates from it with the "Dyadic" certificates in the \currentuser\My\ cert store:

ucl sync-cert

If you are a client of multiple partitions, specify the partition you want to sync. For example, to sync the partition CodeSign1:
• To the \currentuser\My\ cert store:

ucl sync-cert -p CodeSign1

• To the \localmachine\My\ cert store: 

ucl sync-cert --local -p CodeSign1

Storing certificates in the \localmachine stores requires elevated privileges. Run the command using the Run as Administrator CMD or PowerShell prompt.

If you are a client of multiple partitions, specify the partition you want to sync. For example, to sync the partition CodeSign1:
• To the \currentuser\My\ cert store:

ucl sync-cert -p CodeSign1

• To the \localmachine\My\ cert store: 

ucl sync-cert --local -p CodeSign1

Storing certificates in the \localmachine stores requires elevated privileges. Run the command using the Run as Administrator CMD or PowerShell prompt.

• To copy trust certificates from a certificate's trust chain, use the --process-ca option. Trust certificates stored in the same partition are copied to the \localmachine\CA\ and the \localmachine\Root\ stores.

  Example:

ucl sync-cert -p CodeSign1 --process-ca

Storing certificates in the \localmachine stores requires elevated privileges. Run the command using the Run as Administrator CMD or PowerShell prompt.

Windows cert-store specification

The --local and --store parameters specify the Windows cert-store as follows: 

• To address the cert:\currentuser\<store-name> store:
  1. Omit the --local option.
  2. The accessed store is
     • cert:\currentuser\My if the --store option is omitted.
     • cert:\currentuser\<store-name> if --store <store-name> is specified.
• To address the cert:\localmachine\<store-name> store:
  1. Use the --local option.
  2. The accessed store is
     • cert:\localmachine\My if the --store option is omitted.
     • cert:\localmachine\<store-name> if --store <store-name> is specified.

Tip
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

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 ECCElliptic-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. Refer to Key Storage and Retrieval.

We recommend starting by importing the certificate with the --ksp option regardless of the 32-bit or 64-bit MachineType of the application. If using this option fails, delete the certificate from the store and re-import it using the --csp option.

UKCUnbound Key Control - The name of Unbound's key management product. client running in the Windows Server 2008 R2 supports the KSP method only.

Tip
To find the NN-bit MachineType of your application, use the Microsoft sigcheck tool sigcheck. For example,
sigcheck "C:\Program Files (x86)\Window Kits\10\bin\10.0.17763.0\x64\signtool.exe"
Among the other properties, it shows MachineType: 64-bit.

Examine the Provider's Name

UKCUnbound Key Control - The name of Unbound's key management product. client registers a certificate in the Windows cert-store using the following Provider Name tags:

• KSP- Provider Name:: Dyadic Security Key Storage Provider.
  This provider name is specified when the --csp option is omitted.
  
• CSP- Provider Name:: Dyadic Security Base Cryptographic Provider.
  This provider name is specified when the --csp option is specified.

To examine a certificates provider's name, you must use certmgr.exe in the Windows PowerShell:

1. Make sure certmgr.exe is specified in the client settings. For example,

PS C:> Get-ItemProperty -Path HKLM:\SOFTWARE\DyadicSec\sdk

InstallDir : C:\Program Files\Dyadic\ekm-client\
servers : 192.168.0.102:443
Build : 2.0.1901.33123
cert-auto-sync : 1
cert-app-list : signtool|mmc|powershell|certmgr
cert-store-csp : 1

2. Run certmgr.exe to examine the Cert:\currentuser\my store and filter the output to show the Dyadic entries:

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

Provider Type:: 24 Provider Name:: Dyadic Security Base Cryptographic Provider Container: My sign cert KeySpec: 1
Provider Type:: 24 Provider Name:: Dyadic Security Base Cryptographic Provider Container: My Self-Signed Root CA KeySpec: 1
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

Tip
To examine certificates and their provider names in the \localmachine\my\ store, run
certmgr.exe -r localmachine-s my | Select-string Dyadic

Verification

Verification includes two steps:

1. Confirmation that the certificate with the expected SHASecure 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 SHASecure 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).

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

If any of the tests fail, rerun the ucl sync-cert command with the relevant parameters and repeat the test.

ucl import-store

This command performs the following:

• Imports a certificate(s) with exportable key(s) from one of the following Microsoft certificate stores to the specified UKCUnbound Key Control - The name of Unbound's key management product. partition.
  • cert:\currentuser\My if the --local option is omitted.
  • cert:\localmachine\My, if the --local option is specified.

  The command presents the Windows popup that allows selecting multiple certificates from the presented list.
  The popup masks all certificates already stored in the specified partition.

• Changes the Provider's Name associated with the certificate stored in the cert-store to "Dyadic Security".
• Deletes the key stored in the cert-store if the --xorg option is specified.

Syntax:

Example:

Important
To use the --local option, execute the command using Windows elevated mode ("Run as Administrator"):
- To elevate the Run Command, refer to Elevated Run.
- To elevate the PowerShell Command, refer to Elevated PS.