This respository exists to provide supplemental documentation with regard to using the Yubico YubiHSM2 device with the Yubico provided Cryptography API: Next Generation (CNG) Key Storage Provider (KSP).
YubiHSM2: https://www.yubico.com/products/yubihsm/
The CNG KSP for YubiHSM2 is included as part of the YubiHSM2 SDK found here: https://developers.yubico.com/YubiHSM2/Releases/
The MSI is digitally signed, be sure to verify the signature before deploying the package to target servers.
It does not need to be installed on the server device that the YubiHSM2 is physically installed into where the connector is running, unless the server is also going to be a client. Install as you would any MSI using the command line or GUI.
msiexec.exe /i "yubihsm-cngprovider-windows-amd64.msi" /passive ACCEPT=yes
If you are running the client and server on the same machine, using the default port, and using the default authentication key (authkey) and the default password (which of course should NEVER be done in a production environment), you would configure the the CNG provider using the below three registry values using PowerShell, regedit.exe, or any other means.
Set-ItemProperty -path HKLM:\SOFTWARE\Yubico\YubiHSM -name AuthKeysetID -Type DWord -Value 1
Set-ItemProperty -path HKLM:\SOFTWARE\Yubico\YubiHSM -name AuthKeysetPassword -Type String -Value password
Set-ItemProperty -path HKLM:\SOFTWARE\Yubico\YubiHSM -name ConnectorURL -Type String -Value http://127.0.0.1:12345
See (https://developers.yubico.com/YubiHSM2/Concepts/Object.html). These authkeys can be thought of as synonymous with user accounts in a Windows environment. Each authkey can have a different password, just like each user on a Windows system can have a different password.
See (https://developers.yubico.com/YubiHSM2/Concepts/Domain.html). This has nothing at all to do with traditional Windows domains, but rather can be thought of as synonymous with security groups used in a Windows environment for authorization. Each authkey (or any other object) can belong to one or more domains. This provides logical seperation of keys when multiple applications are utilizing the same YubiHSM2 device.
For example, a single YubiHSM2 device might be physically installed into a server in a datacenter. This server can be running any operating system supported by the YubiHSM connector service. Two or more authkeys might have been created (https://developers.yubico.com/YubiHSM2/Commands/Put_Authkey.html) with different domains specified. Two or more other Windows servers, perhaps virtual machines running on a hypervisor in the same datacenter, may have the Yubico CNG provider installed and registry values configured to connect to the server using the same ConnectorURL value, but different AuthKeysetID and AuthKeysetPassword values. In this configuration, asymmetric keys (or any other objects) created in a session authenticated to the YubiHSM connector with an authkey associated with one domain cannot be manipulated in any way by a session authenticated to the same YubiHSM connector with an authkey not associated to same domain. This would be helpful in installations of something like Active Directory Certificate Services where multiple Certificate Authorities are installed and connected to the same YubiHSM2 device. Conversely, if two or more servers are configured with the same authkey and password, or different authkeys that were created associated to the same domain, asymmetric keys (or any other objects) can be used by sessions on different servers simultaniously. This can be verify helpful in situations where a single key needs to be securely utilized by multiple load balanced servers in a farm or array, such as an Active Directory Federation Services deployment or an Online Certificate Status Protocol array deployment.