KSP for CNG

CNG (Cryptography Next Generation) is Microsoft's cryptographic application programming environment (API) replacing the older Windows cryptoAPI (CAPI). CNG adds new algorithms along with additional flexibility and functionality.

SafeNet provides CSP for applications running in older Windows crypto environments (running CAPI), and 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 SafeNet cryptoki with CNG and to use the newer functions and algorithms in Microsoft IIS.

After you register the SafeNet Luna PCIe HSM partitions with SafeNet KSP, your KSP code should work in the same manner whether our HSM (crypto provider) is selected, or the default provider is used.

NOTE   Be aware when working in a mixed environment or updating applications that previously used CAPI and the SafeNet 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. The installation of certificate will fail.

This section contains directions for the following procedures:

>Installing KSP

>Configuring KSP with GUI

>Configuring KSP via the Command Line

>Enabling Key Counting

Installing KSP

KSP is installed using the SafeNet Luna Client installer. Note that it is not installed by default and must be explicitly selected when you install the SafeNet Luna Client. You can also install KSP after you install the SafeNet Luna Client by re-running the installer.

The KSP installer installs the following utilities in the C:\Program Files\SafeNet\LunaClient\KSP folder:

Utility name	Description
KspConfig.exe	A GUI utility used to configure KSP.
kspcmd.exe	A command-line utility used to configure KSP.
ksputil.exe	A command-line utility used to make keys available to other clients, such as in a clustering configuration.
ms2Luna.exe	A command-line utility used to migrate software-based keys to a SafeNet Luna PCIe HSM.

Configuring KSP with GUI

After installing KSP, use the KSP configuration wizard to register your HSM Partitions for use with CNG. The KSP configuration tool secures the Password for each HSM Partition such that only the user for which the password was secured is able to un-secure it.

Briefly, the important points are:

>Register the cryptoki to be used.

>Register the slot-to-be-used to the local admin (which allows the admin to interact with the slot).

>Register the slot-to-be-used to the local system (which allows the operating system to interact with the slot).

NOTE   Only the Administrator or a member of the Administrators group can run "KspConfig.exe". The SafeNet KSP can be used by any application that acquires the context of the SafeNet KSP. All users who login and use the applications that acquired the context have access to the SafeNet KSP.

To configure KSP with the GUI:

1. Go to C:\Program Files\SafeNet\LunaClient\KSP. Launch KspConfig.exe (the KSP configuration wizard).

2.In the left-hand pane (tree view) double-click "Register Or View Security Library"

3.In the right-hand pane, browse to the library C:\Program Files\SafeNet\LunaClient\cryptoki.dll and click Register.

4.When the success message appears, click OK.

5.Return to the left-hand pane and double-click "Register HSM Slots", and click [Next]. In general, we recommend that you register by slot label, rather than slot number, if you are using an HA configuration .

6.In the "Slot Password" field, type in the password for the indicated slot. To the right of the window, click the Register Slot button to register the slot for Domain/User. A success message appears.

Note that the "Register for User" field should be Administrator (or the admin equivalent account that will be managing this setup) and "Domain" should match the domain or local computer with which you are logged in.

7.Select "SYSTEM" under "Register for User" and select "NT AUTHORITY" under "Domain", supply the password for the slot being registered, and again click Register Slot to complete the KSP configuration.

8.Once you have the slots registered, you can begin connecting with your client application to perform crypto operations in your HSM Partitions (or HA virtual slots). If a SafeNet-tested Integration procedure for your application is not available for download from the SafeNet website, contact SafeNet Customer Support.

Configuring KSP via the Command Line

On headless or Core platforms with no graphical interface, use the following method to configure and register KSP.

In the SAFENET folder, the 'kspcmd' utility is used to manually register the users along with their domain

>“Administrator” user with the appropriate domain. In this example the domain is “WIN-VHH3R3QOVSQ”

>"SYSTEM" user with the "NT-AUTHORITY" domain

To configure KSP via the command line:

1.Open a 'CMD' window and browse to the "C:\Program Files\SafeNet\LunaClient" folder.

C:\Program Files\SafeNet\LunaClient>lunacm.exe

LunaCM v7.1.0. Copyright (c) 2006-2017 SafeNet.

  Available HSMs:
  Slot Id ->              0
  Label ->                Par7.1
  Serial Number ->        1213475834431 
  Model ->                LunaSA 7.1.0
  Firmware Version ->     7.1.0
  Configuration ->        Luna User Partition With SO (PW) Signing With Cloning Mode
  Slot Description ->     Net Token Slot

  Current Slot Id: 0  

2.Browse to "C:\Program Files\SafeNet\LunaClient\KSP" for 64-bit Client. 'kspcmd' utility is used to register KSP via command line.  

3.Register the PKCS library as configured in crystoki.ini .

C:\Program Files\SafeNet\LunaClient\KSP>kspcmd.exe library "C:\Program Files\SafeNet\LunaClient\cryptoki.dll"
This Servers Host Name is: WIN-VHH3R3QOVSQ and the logged on user is: Administrator@WIN-VHH3R3QOVSQ
Success registering the security library!

4.Run this command to register the user " Administrator " with domain " WIN-VHH3R3QOVSQ" .

C:\Program Files\SafeNet\LunaClient\KSP>kspcmd.exe p /s Par7.1 /u Administrator /d WIN-VHH3R3QOVSQ
This Servers Host Name is: WIN-VHH3R3QOVSQ and the logged on user is: Administrator@WIN-VHH3R3QOVSQ
Enter challenge for slot '0' <Just hit Enter when using PED>:********
The slot Par7.1 was successfully and securely registered for user Administrator at domain WIN-VHH3R3QOVSQ!  

5.Run this command to register the user "SYSTEM" with domain "NT-AUTHORITY" .

C:\Program Files\SafeNet\LunaClient\KSP>kspcmd.exe p /s Par7.1 /u SYSTEM /d NT_AUTHORITY
This Servers Host Name is: WIN-VHH3R3QOVSQ and the logged on user is: Administrator@WIN-VHH3R3QOVSQ
Enter challenge for slot '0' <Just hit Enter when using PED>:********
The slot Par7.1 was successfully and securely registered for user SYSTEM at domain NT_AUTHORITY!
You have now successfully registered SYSTEM with NT-AUTHORITY  

6.6. To verify that the library and domain has been registered :

a.Open the registry.  

b.Browse to HKEY_LOCAL_MACHINE\SOFTWARE\Safenet\SafeNetKSP\CurrentConfig  

You should have entry CryptokiLibrary = "C:\Program Files\SafeNet\LunaClient\cryptoki.dll"  

c.Browse to HKEY_LOCAL_MACHINE\SOFTWARE\Safenet\SafeNetKSP\Slots.  

You should have entries called "Administrator@WIN-VHH3R3QOVSQ" and "SYSTEM@NT-AUTHORITY"  

Troubleshooting

When you open the KspConfig program, if it fails to display a list of available slots, then it might be that you have not properly set up your SafeNet Luna PCIe HSM.

Open a Windows Command Prompt window, change directory to the "C:\Program Files\SafeNet\LunaClient\" directory, and use the "lunacm" command-line utility to see and modify the status of the HSM and HSM Partitions.

Algorithms Supported

Here, for comparison, are the algorithms supported by our CSP and KSP APIs.

Algorithms supported by the SafeNet 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 SafeNet 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

Enabling Key Counting

Key counting allows you to specify the maximum number of times that a key can be used. It sets the upper limit from 0 to MAX(UInt32).

To enable key counting:

1.Enter the following command and respond to the prompts. Enter the key usage limit, or enter 0 to turn off the feature:

C:\Program Files\SafeNet\LunaClient\KSP> kspcmd usagelimit <usage_limit_number>

For example:

C:\Program Files\SafeNet\LunaClient\KSP>kspcmd usageLimit 2000
This Servers Host Name is: LUNA_CLIENT and the logged on user is: admin@LUNA_CLIENT

Enter the key usage limit: 2000

Successfully configured the key usage limit to 2000 uses.


C:\Program Files\SafeNet\LunaClient\KSP>kspcmd u
This Servers Host Name is: LUNA_CLIENT and the logged on user is: admin@LUNA_CLIENT 

Warning, max key usage is already set to 2000.
Changing this will not modify previously created keys!
Only keys created subsequent to making this change will be affected!
Do you wish to continue?[y/n]: