Luna KSP for CNG Registration Utilities
CNG (Cryptography Next Generation) is Microsoft's cryptographic application programming interface (API), replacing the older Windows cryptoAPI (CAPI). CNG adds new algorithms along with additional flexibility and functionality. Thales provides Luna CSP for applications running in older Windows crypto environments (running CAPI), and Luna KSP for newer Windows clients (running CNG). Consult Microsoft documentation to determine which one is appropriate for your client operating system.
KSP must be installed on any computer that is intended to act via CNG as a client of the HSM, running crypto operations in hardware. You need KSP to integrate Luna cryptoki with CNG and to use the newer functions and algorithms in Microsoft IIS.
After you register the Luna Cloud HSM partitions with Luna KSP, your KSP code should work the same whether a Luna HSM (crypto provider) or the default provider is selected.
NOTE Be aware when working in a mixed environment or updating applications that previously used CAPI and the Luna CSP - the new algorithms supported by CNG (such as SHA512 and ECDSA) in Certificate Services are not recognized by systems that use CAPI. If Certificate Services is configured to use any of these new algorithms then the signed certificates can be installed only on systems that are aware of these new algorithms. Any of the systems that use CAPI will not be able to use this feature and certificate installation will fail.
By default, the Luna KSP utilities are installed in <client_install_dir>/KSP. The installation includes the following utilities:
•Configuring the KSP Using the Command Line
•Configuring the KSP Using the GUI
>ms2Luna — Used to migrate Microsoft CSP keys to a Luna Cloud HSM partition
>ksputil — Used to display and manage partition keys that are visible to the KSP
The KSP library (SafeNetKSP.dll) is also included. Place this file in the system's SysWOW64 and system32 folders.
NOTE KSP works with Crypto Officer only.
For management and security and compliance reasons, you might prefer to limit your applications to read-only usage of keys such as the Crypto User role provides. However, since KSP cannot function as CU, you can simulate the CO/CU role separation - see Run a Windows CNG application as Crypto Officer limited to key handling ability at Crypto User level.
This allows you to use the full capability of Crypto Officer for partition and object management tasks, whenever necessary, and then resume running your CNG/KSP-using application as CO, but with reduced, read-only permissions.
kspcmd
You can use this utility (<client_install_dir>/KSP/kspcmd.exe) to register the KSP library and partitions via the Windows command line.
NOTE To register the library and partitions using a GUI, use KspConfig. It is unnecessary to use both utilities.
Syntax
kspcmd.exe
library <path\cryptoki.dll>
nonAdminuser
password /s <slot_label> [/u <username>] [/c <co_password>] [/d <domain>]
usagelimit
viewslots
| Argument | Shortcut | Description |
|---|---|---|
| library <path\cryptoki.dll> | l | Register the library and associated provider names with KSP. |
| nonAdminUser | n | Enable non-administrator users on the client to use Luna KSP. |
| password | p |
Register the designated slot and its Crypto Officer password to the KSP. You can specify the following options: >/s <slot_label> [Mandatory] The label of the partition being registered to the KSP. >/u <username> [Optional] The username to register for this partition. If this is not specified, the currently logged-in user is registered. >/c <co_password> [Optional] The Crypto Officer password. >/d <domain> [Optional] The domain to register for this partition. |
| usagelimit | u |
Set the maximum usage limit for RSA keys using KSP. Enter 0 to register unlimited uses. |
| viewslots | v | Display the registered slots by user/domain. |
Configuring the KSP Using the Command Line
You can use the kspcmd command-line tool to configure the KSP for use with your partitions. The Crypto Officer must complete this procedure using Administrator privileges on the client.
You can register the following user/domain combinations with the KSP:
>Administrator user with the domain specific to the client. Default Windows domains are in the format WIN-XXXXXXXXXXX.
>SYSTEM user with the NT-AUTHORITY domain
The configuration tool registers a Crypto Officer password to a specific user, so that only that user can unlock the partition.
To configure the KSP using the command line
1.In a command line, navigate to the Luna KSP install directory and register the cryptoki.dll library to the KSP.
kspcmd library /s <path\cryptoki.dll> [/u <username>] [/d <domain>]
2.Register the designated slot and its Crypto Officer password to the KSP.
kspcmd password /s <slot_label> [/u <username>] [/c <co_password>] [/d <domain>]
You are prompted to enter the CO password for the slot.
3.[Optional] Display the registered slots to ensure that registration is complete.
kspcmd viewslots
4.[Optional] Set the maximum usage limit for RSA keys using KSP.
kspcmd usagelimit
You are prompted to enter a usage limit. Enter 0 to register unlimited uses.
5.[Optional] Enable non-administrator users on the client to use Luna KSP.
kspcmd nonAdminUser
You are prompted to confirm this action. When the action succeeds, the following entry is added to the Windows registry with a value of 1:
HKEY_LOCAL_MACHINE\SOFTWARE\Safenet\SafeNetKSP\CurrentConfig\NAUaccess
To restrict non-admin users from Luna KSP in the future, set the value of this entry to 0, or delete the key from the registry.
KspConfig
You can use this tool (<client_install_dir>\KSP\KspConfig.exe) to register the KSP library and partitions using a GUI.
NOTE To register the library and partitions using the command line, use kspcmd. It is unnecessary to use both utilities.
NOTE CSP or KSP registration includes a step that verifies the DLLs are signed by our certificate that chains back to the DigiCert root of trust G4 (in compliance with industry security standards).
This step can fail if your Windows operating system does not have the required certificate. If you have been keeping your Windows OS updated, you should already have that certificate.
If your HSM Client host is connected to the internet, use the following commands to update the certificate manually:
certutil -urlcache -f http://cacerts.digicert.com/DigiCertTrustedRootG4.crt
certutil -addstore -f root DigiCertTrustedRootG4.crt
To manually update a non-connected host
1. Download the DigiCert Trusted Root G4 (http://cacerts.digicert.com/DigiCertTrustedRootG4.crt) to a separate internet-connected computer.
2.Transport the certificate, using your approved means, to the HSM Client host into a <downloaded cert path> location of your choice
3.Add the certificate to the certificate store using the command:
certutil -addstore -f root <downloaded cert path>
Configuring the KSP Using the GUI
You can use the KspConfig utility to configure the KSP for use with your partitions. The Crypto Officer must complete this procedure using Administrator privileges on the client.
You can register the following user/domain combinations with the KSP:
>Administrator user with the domain specific to the client. Default Windows domains are in the format WIN-XXXXXXXXXXX.
>SYSTEM user with the NT-AUTHORITY domain
The configuration tool registers a Crypto Officer password to a specific user, so that only that user can unlock the partition.
To configure the KSP using the GUI
1.In Windows Explorer, navigate to the Luna KSP install directory and launch KspConfig as the Administrator user.
2.In the left panel, double-click Register or View Security Library. Enter the filepath to cryptoki.dll or click Browse to locate it.
<client_install_dir>\cryptoki.dll
Click Register to complete the registration.
3.In the left panel, double-click Register HSM Slots. Select the Administrator user, client domain, and an available slot to register. Enter the CO password and click Register Slot.
4.Select the SYSTEM user and NT-AUTHORITY domain and register for the slot.
5.Repeat steps 3-4 for any other available slots you want to register with the KSP.
You can now begin using your applications to perform crypto operations on the registered slots.
ms2Luna
Use the ms2Luna utility (<client_install_dir>/KSP/ms2Luna.exe) to migrate existing Microsoft KSP keys held in software to a registered partition on the Luna Cloud HSM. It requires the thumbprint of a certificate held in the client's keystore.
Prerequisites
>You must already have registered a partition using the kspcmd or KspConfig utility.
>Private keys must be exportable to be migrated to the HSM.
To migrate Microsoft KSP keys to the Luna Cloud HSM
1.In a command prompt, navigate to the Luna KSP install directory and migrate your existing keys to the HSM.
ms2Luna
You are prompted for the KSP certificate thumbprint.
ksputil
KSP binds machine keys to the hostname of the crypto server that created the keys. You can use the ksputil utility to display and manage keys that are visible to the KSP.
Syntax
ksputil
clusterkeys /s <slotnum> /n <keyname> /t <target>
listkeys /s <slotnum> [/user]
| Argument | Shortcut | Description | ||||||
|---|---|---|---|---|---|---|---|---|
| clusterkeys | c |
Bind a specified keypair to a different server domain. Note that this does not change the bindings of existing keys; it creates a copy of the original keypair that is bound to the new domain. Available options:
|
||||||
| listkeys | l |
DIsplay a list of KSP-visible keys. Available options:
|
Algorithms Supported
Here, for comparison, are the algorithms supported by our CSP and KSP APIs.
Algorithms supported by the Luna CSP
CALG_RSA_SIGN
CALG_RSA_KEYX
CALG_RC2
CALG_RC4
CALG_RC5
CALG_DES
CALG_3DES_112
CALG_3DES
CALG_MD2
CALG_MD5
CALG_SHA
CALG_SHA_256
CALG_SHA_384
CALG_SHA_512
CALG_MAC
CALG_HMAC
Algorithms supported by the Luna KSP
NCRYPT_RSA_ALGORITHM
NCRYPT_DSA_ALGORITHM
NCRYPT_ECDSA_P256_ALGORITHM
NCRYPT_ECDSA_P384_ALGORITHM
NCRYPT_ECDSA_P521_ALGORITHM
NCRYPT_ECDH_P256_ALGORITHM
NCRYPT_ECDH_P384_ALGORITHM
NCRYPT_ECDH_P521_ALGORITHM
NCRYPT_DH_ALGORITHM
NCRYPT_RSA_ALGORITHM
