Home >

SDK Reference Guide > Microsoft Interfaces > KSP for CNG

KSP for CNG

CNG (Cryptography Next Generation) is Microsoft's cryptographic application programming environment (API) replacing the Windows cryptoAPI (CAPI). CNG is applicable to Windows Server 2008 and Windows Server 2012. CNG adds new algorithms along with additional flexibility and functionality, compared with the old API.

Just as SafeNet provides our CSP for applications running in older Windows crypto environments (and JSP for Java), we offer KSP to allow your Windows Server 2008 CNG applications to make use of the SafeNet HSM. You can still use CSP with Windows Server 2008 and CAPI for your legacy applications, but future development will all take place using CNG, for which you will need to install KSP.

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 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:  TRANSITION ISSUES 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.

Installing KSP

KSP is installed using the SafeNet Client installer. Note that it is not installed by default and must be explicitly selected when you install the SafeNet Client. You can also install KSP after you install the SafeNet 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 HSM.

Configuring KSP

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

1.Go to C:\Program Files\SafeNet\LunaClient\KSP and 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.Return to the "Domain" pull-down list 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.

If It Doesn't Work?

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 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

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]: