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

The Luna KSP is an optional client feature. During client installation, select CSP (CAPI) / KSPCNG) to install it. To install the feature later, run the client installer again, select the option, and click Modify.

By default, the Luna KSP utilities are installed in <client_install_dir>/KSP. The installation includes the following utilities:

>kspcmd

•Configuring the KSP Using the Command Line

>KspConfig

•Configuring the KSP Using the GUI

>ms2Luna — Used to migrate Microsoft CSP keys to a Luna PCIe HSM partition

>ksputil — Used to display and manage partition keys that are visible to the KSP

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>
password /s <slot_label> [/u <username>] [/d <domain>]
usagelimit
viewslots

Argument	Shortcut	Description
library <path\cryptoki.dll>	l	Register the library and associated provider names with KSP.
password	p	Register the designated slot and its Crypto Officer password/challenge 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, all users on the client will be able to access this partition via KSP. /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/challenge 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/challenge to the KSP.

kspcmd password /s <slot_label> [/u <username>] [/d <domain>]

You are prompted to enter the CO password/challenge 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.

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.

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/challenge 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/challenge 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/HA group on the Luna PCIe HSM. It requires the thumbprint of a certificate held in the client's keystore.

Prerequisites

>You must already have registered a partition/HA group 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 PCIe 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: /s <slotnum> [Mandatory] The slot number of the partition where the key(s) are located. /n <keyname> [Mandatory] The name of the key(s) to bind to the new domain. /d <domain> [Mandatory] The domain to which keys will be bound.
listkeys	l	DIsplay a list of KSP-visible keys. Available options: /s <slotnum> [Mandatory] The slot number of the partition where the key(s) are located. /user [Optional] List keys bound to the currently logged-in user/hostname.

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