SafeNet 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 SafeNet CSP for applications running in older Windows crypto environments (running CAPI), and SafeNet 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 your HSM tokens with SafeNet KSP, your KSP code should work the same whether a SafeNet HSM (crypto provider) or the default provider is selected.

The SafeNet KSP utilities are installed in C:\Program Files\SafeNet\Protect Toolkit 5\KSP\. The installation includes the following utilities:

>kspcmd

•Configuring the KSP Using the Command Line

>KspConfig

•Configuring the KSP Using the GUI

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

kspcmd

You can use this utility (C:\Program Files\SafeNet\Protect Toolkit 5\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 <token_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 token and its user PIN to the KSP. You can specify the following options: /s <token_label> [Mandatory] The label of the token 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 token.
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 tokens. The user 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 token PIN 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 SafeNet 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 token and its user PIN to the KSP.

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

You are prompted to enter the user PIN for the token.

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 (C:\Program Files\SafeNet\Protect Toolkit 5\KSP\KspConfig.exe) to register the KSP library and partitions using a GUI.

Configuring the KSP Using the GUI

You can use the KspConfig utility to configure the KSP for use with your tokens. The user 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 token PIN 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 SafeNet 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.

C:\Program Files\SafeNet\Protect Toolkit 5\Protect Toolkit C SDK\bin\hsm\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 token to register. Enter the user PIN and click Register Slot.

4.Select the SYSTEM user and NT-AUTHORITY domain and register for the token.

5.Repeat steps 3-4 for any other available tokens you want to register with the KSP.

You can now begin using your applications to perform crypto operations on the registered tokens.

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 <tokennum> /n <keyname> /t <target>
listkeys /s <tokennum> [/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 <tokennum> [Mandatory] The number of the token 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 <tokennum> [Mandatory] The number of the token where the key(s) are located. /user [Optional] List keys bound to the currently logged-in user/hostname.