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 7 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) / KSP (CNG) 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 7 partition

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

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/challenge>] [/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. This feature requires minimum Luna HSM Client 10.4.0.
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, the currently logged-in user is registered.

>/c <co_password/challenge>

[Optional] The Crypto Officer password/challenge. You require minimum Luna HSM Client 10.4.0 to specify this option.

>/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>] [/c <co_password/challenge>] [/d <domain>]

You are prompted to enter the CO password/challenge for the slot, unless you specified it using the /c option (minimum Luna HSM Client 10.4.0 required).

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. This feature requires minimum Luna HSM Client 10.4.0.

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 Luna 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 Luna 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/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 7. 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 7

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