The SafeNet CSP Registration Tool and Utilities

This section describes how to use the SafeNet CSP registration tool and related utilities to configure the SafeNet Luna Network HSM client to use a SafeNet Luna Network HSM with Microsoft Certificate Services. You must be the Administrator or a member of the Administrators group to run the SafeNet CSP tools.

The SafeNet CSP can be used by any application that acquires the context of the SafeNet CSP. All users who login and use the applications that acquired the context have access to the SafeNet CSP. After you register the SafeNet Luna Network HSM partitions with SafeNet CSP, your CSP and KSP code should work in the same manner whether our HSM (crypto provider) is selected, or the default provider is used.

NOTE The SafeNet CSP is an optional installation. It is installed by default in <luna_client_install_dir>/CSP. If the CSP is not installed, re-run the installer.

The Keymap Utility

Use the keymap utility if you have previously been using another provider (with its keys in the SafeNet Luna Network HSM) and wish to migrate to MS CSP keeping your established keys. The keymap utility simply creates on the SafeNet Luna Network HSM the data object that MS CSP expects, which in turn makes your existing keys available to MS CSP. See <luna_client_install_dir>/CSP/keymap.exe.

Example

C:\artifacts\sa64client_installer>C:\git\crypto\CSP\keymap\output\SA64client\win64-cl-x86-dbg\bin\keymap.exe

Initializing the library...Detecting available slots...OK.

List of available slots:
Slot# 1.
Slot# 2.
Slot# 3.
Slot# 4.
Slot# 5.
Slot# 6.
Slot# 7.
Slot# 8.

Opening a session on one of the available slots.
Enter slot ID on which to open a session, valid range: [1 to 8] or 0 to quit: 4
Opening a session on slot 4...
Enter challenge for partition:*******
OK

1 Browse Objects
2 Create Key Container
3 View Key Container
4 Associate Keys With Container
5 Do Nothing
99 Destroy Key Container
0 Exit
Choice: 1

Available KeyContainer objects on the token.

Available RSA Public Key objects on the token.
Handle: 180 Label: Multitoken RSA 1024-bit Public Key for Wrap

Available RSA Private Key objects on the token.
Handle: 181 Label: Multitoken RSA 1024-bit Private Key for Unwrap

1 Browse Objects
2 Create Key Container
3 View Key Container
4 Associate Keys With Container
5 Do Nothing
99 Destroy Key Container
0 Exit
Choice: 0

OK.
Application Exiting.
C:\artifacts\sa64client_installer>

The ms2Luna Utility

Use the ms2Luna utility if you already have MS CSP in use with software key storage and you now wish to continue with your keys held on the SafeNet Luna Network HSM. See <luna_client_install_dir>/CSP/ms2luna.exe.

The CSP Registration Tool

You can use the CSP registration tool (<luna_client_install_dir>/CSP/register.exe) to perform the following functions:

>Register HSM partitions for use with the SafeNet CSP. The password for each HSM Partition is secured such that only the user for which the password was secured is able to un-secure it. See Registering Partitions

>Register which non-RSA cryptographic algorithms you want performed in software only. See Registering the Cryptographic Algorithms to be Performed in Software

>Enable key counting in KSP/CSP. See Enabling Key Counting.

>Register the provider library with the Windows OS to make it available for applications.

Command Syntax

register.exe [/partition | /algorithms | /library | /usagelimit] [/highavailability] [/strongprotect] [/cryptouser] [/?]

Parameter	Shortcut	Description
/partition	/p	Register a partition and its encrypted challenge. You are prompted through the required steps to select and register a SafeNet Luna Network HSM partition. This is the default option. If you type register with no additional parameters, then /partition is assumed. For example, if you type register /highavail or register /strongprotect, then /partition is invoked and the additional option that you selected (i.e., /highavail or /strongprotect) is run along with it . That is, typing register /highavail is the same as typing register /partition /highavail.
/highavail	/h	Register only high availability (HA) partitions.
/strongprotect	/s	Strongly protect the challenge for registered partition
/algorithms	/a	Register the desired software ONLY algorithms
/library	/l	Register CSP library and signature in the registry
/usagelimit	/u	Register CSP RSA key maximum usage limit
/cryptouser	/c	Use CSP as Crypto User

NOTE Before using the 32-bit CSP provider, it is necessary to register the library with Windows. To do this, complete the 32-bit client setup, then run the 32-bit register.exe with the /library option, as shown:

C:\Program Files\SafeNet\LunaClient\win32\CSP>register.exe /library
register v7.2.0
Success registering SOFTWARE\Microsoft\Cryptography\Defaults\Provider\Luna enhanced RSA and AES provider for Microsoft Windows !
Success registering SOFTWARE\Microsoft\Cryptography\Defaults\Provider\Luna Cryptographic Services for Microsoft Windows !
Success registering SOFTWARE\Microsoft\Cryptography\Defaults\Provider\Luna SChannel Cryptographic Services for Microsoft Windows !

Registering Partitions

The syntax used to register partitions depends on whether the partitions use high availability (HA) or not, as detailed in the following procedures.

To register a standard HSM partition:

1.In the install directory for CSP enter the register command and respond to the prompts:

C:\Program Files\SafeNetLunaClient\CSP> register

For example:

*****************************************************************
          SafeNet Luna CSP, Partition Registration 
   Protect the HSM's challenge for the selected partitions. 
   NOTE:
        This is a WEAK protection of the challenge!
        After you have configured all applications that will use
        the Luna CSP, and run them once, you MUST run: 
            register /partition /strongprotect *
        to strongly protect the registered challenges! 
***************************************************************** 
This procedure is a destructive procedure and will completely replace 
any previous settings!
Do you wish to continue?: [y/n]
Do you want to register the partition named 'nes'? [y/n]:
Please enter the SafeNet Luna Network HSM challenge for the partition 'nes' :
Success registering the ENCRYPTED challenge for partition 'nes'.
Only the Luna CSP will be able to use this data!
Registered 1 partition(s) for use by the Luna CSP!

All available Partitions are presented for you to register or not.

2.Install and/or configure your application(s).

3.Run each of your applications once to use SafeNet CSP.

4.Enter the following command to strongly protect the registered challenges:

CAUTION! You must run register /strongprotect to ensure the protection of the HSM partition passwords.

NOTE Once you run the /strongprotect option, only those users that existed previous to the /strongprotect command are allowed to use the SafeNet CSP. If the /strongprotect option is not used, then any/all users can use the SafeNet CSP.

5. If you are using a 64-bit CSP provider, skip this step as it is automatically done for you.

Enter the following command to reconnect to the library:

register.exe /library

6.Run all applications as usual.

To register an HA partition:

When registering an HA Partition for use, follow these steps.

1.Enter the following command and respond to the prompts:

C:\Program Files\SafeNet\LunaClient\CSP> register /highavail

NOTE Use the /highavail option only if you have HA set up for your SafeNet Luna Network HSMs.

2.For example:

**************************************************************
SafeNet Luna CSP, Partition Registration 
Protect the HSM's challenge for the selected partitions. 
NOTE:
This is a WEAK protection of the challenge!
After you have configured all applications that will use
the Luna CSP, and run them once, you MUST run: 
 register /partition /strongprotect *
to strongly protect the registered challenges! 
************************************************************** 
This procedure is a destructive procedure and will completely replace 
any previous settings!
Do you wish to continue?: [y/n]
Do you want to register the partition named 'nes'? [y/n]:
Please enter the SafeNet Luna Network HSM challenge for the partition 'nes' :
Success registering the ENCRYPTED challenge for partition 'nes'.
Only the Luna CSP will be able to use this data!
Registered 1 partition(s) for use by the Luna CSP!

NOTE If you are using HA, then only the HA virtual partition is presented for registering.

3.Install and/or configure your application(s).

4.Run each of your applications once to use SafeNet CSP.

5.Enter the following command to strongly protect the registered challenges:

CAUTION! You must run register /strongprotect to ensure the protection of the HSM partition passwords.

6.If you are using a 64-bit CSP provider, skip this step as it is automatically done for you.

Enter the following command to reconnect to the library:

register.exe /library

7.Run all applications as usual.

Registering the Cryptographic Algorithms to be Performed in Software

Certain operations (symmetric), such as the hash operation may be performed faster in software than on the SafeNet Luna Network HSM. The register /algorithms command allows you to choose which algorithms to de-register from the SafeNet Luna Network HSM. The trade-off is a gain in speed, at the cost of some security (exposing the operation in software). Signing and other asymmetric operations are always done on the HSM.

To register algorithms for software-only use:

1.In the install directory for CSP enter the register /algorithms command and respond to the prompts:

C:\Program Files\SafeNet\LunaClient\CSP> register /algorithms

2.You are prompted for yes or no responses about which algorithms are to be registered for software-only use. For example:

************************************************************************
SafeNet Luna CSP, Algorithm Registration 

Register algorithms to be done in software by the Microsoft CSP(s).
BY DEFAULT, ALL ALGORITHMS ARE DONE IN HARDWARE BY THE SafeNet Luna Network HSM. 
ONLY NON RSA ALGORITHMS MAY BE CONFIGURED FOR SOFTWARE.
RSA PUBLIC/PRIVATE ALGORITHMS WILL ALWAYS BE IN HARDWARE.
************************************************************************
Do you want algorithm 'CALG_RC2', done in software?(y/n): 
Do you want algorithm 'CALG_RC4', done in software?(y/n): 
Do you want algorithm 'CALG_RC5', done in software?(y/n): 
Do you want algorithm 'CALG_DES', done in software?(y/n): 
Do you want algorithm 'CALG_3DES_112', done in software?(y/n): 
Do you want algorithm 'CALG_3DES', done in software?(y/n): 
Do you want algorithm 'CALG_MD2', done in software?(y/n): 
Do you want algorithm 'CALG_MD5', done in software?(y/n): 
Do you want algorithm 'CALG_SHA', done in software?(y/n): 
Do you want algorithm 'CALG_MAC', done in software?(y/n): 
Do you want algorithm 'CALG_HMAC', done in software?(y/n): 
Success registering software only algorithms:
CALG_RC2,CALG_RC4,CALG_RC5,...!

If you chose no for all prompts, then all algorithms revert to hardware and the following is displayed:

All algorithms have been de-registered and will now only be done in hardware!

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:

In the install directory for the CSP, 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\CSP> register /usagelimit

For example:

C:\Program Files\SafeNet\LunaClient\CSP>register /usagelimit
register v1.0.1

Enter the key usage limit: 2000
     
Successfully configured the key usage limit to 2000 uses.