Luna CSP Registration Utilities

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

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

The Luna CSP 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 CSP utilities are installed in <client_install_dir>/CSP. The installation includes LunaCSP.dll, the library used by CSP to interact with Cryptoki.dll, and the following utilities:

>register

•Registering Partitions/HA Groups to CSP

•Registering Cryptographic Algorithms to be Used in Software

•Enabling Key Counting

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

>keymap — Used to manage keys on the partition for use with Microsoft CSP

register

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

>Register application partitions/HA groups and their passwords/challenge secrets for use with the Luna CSP (see Registering Partitions/HA Groups to CSP).

>Register which non-RSA cryptographic algorithms you want performed in software only (see Registering Cryptographic Algorithms to be Used 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.

Syntax

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

Argument	Shortcut	Description
/algorithms	/a	Register algorithms that will be used in software by Microsoft CSP (i.e. not on the HSM). Only non-RSA algorithms can be configured to run in software; RSA algorithms will always run on the HSM hardware.
/cryptouser	/c	Register the password/challenge for the Crypto User (read-only crypto role). If this option is not specified, the Crypto Officer password/challenge is registered.
/highavail	/h	Register the virtual partition of a high-availability (HA) group.
/library	/l	Register the library and associated provider names for use with CSP. The following providers are registered: >Luna enhanced RSA and AES provider for Microsoft Windows >Luna Cryptographic Services for Microsoft Windows >Luna SChannel Cryptography Services for Microsoft Windows NOTE   This operation is required only for 32-bit client libraries, which have been discontinued in Luna HSM Client 10.1.0 and newer.
/partition	/p	Register a partition and its password/challenge. You are prompted to select which available partitions to register to the CSP. This is the default option. If you type register with no additional parameters, then /partition is assumed. For example, register /strongprotect is the same as register /partition /strongprotect.
/password		Specify the user password or challenge for the desired role. By default, this is the Crypto Officer. This option requires minimum Luna HSM Client 10.5.1.
/strongprotect	/s	Strongly protect the challenge for registered partitions. This option ensures that only existing client users can access the CSP partitions. After running register /strongprotect, new users are not allowed to use CSP.
/usagelimit	/u	Set the maximum usage limit for RSA keys using CSP. Enter 0 to register unlimited uses.

Registering Partitions/HA Groups to CSP

Use the register utility to register application partitions or HA virtual slots to the CSP. The Crypto Officer or Crypto User must complete this procedure, depending on which role you wish to use.

NOTE   You cannot register a combination of HA groups and application partitions; either physical or virtual slots may be registered to the CSP at one time.

To register an application partition or HA group to the CSP

1.In a command prompt, navigate to the Luna CSP install directory and register the desired application partition(s) or HA group(s). Specify /cryptouser to register the CU role. Otherwise, the CO role will be registered. If you want to register both roles, you can run the command twice, once with /cryptouser and once without.

register [/highavail] [/cryptouser]

You are prompted (y/n) to decide whether to register each available partition or HA virtual slot.

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

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

4.Ensure the security of the registered role passwords/challenges by specifying /strongprotect.

register /strongprotect

5.If you are using a 32-bit CSP provider, register the library. If you are using a 64-bit CSP provider, this is done automatically.

register /library

You can now run all applications as usual.

Registering Cryptographic Algorithms to be Used in Software

Certain symmetric operations such as hashing may be completed faster in software than on the Luna PCIe HSM 7. The register /algorithms command allows you to choose which algorithms to de-register from the Luna PCIe HSM 7. This may improve performance for operations that use these algorithms, but there is a security cost (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 a command prompt, navigate to the Luna CSP install directory and register the desired algorithms to be used in software.

register /algorithms

You are prompted (y/n) to decide whether each available algorithm should be used in software.

Enabling Key Counting

Key counting allows you to specify the maximum number of times that a key can be used.

To enable key counting

1.In a command prompt, navigate to the Luna CSP install directory and register the key usage limit.

register /usagelimit

You are prompted to enter a key usage limit. You can turn the feature off (unlimited uses) by entering 0.

ms2Luna

Use the ms2Luna utility (<client_install_dir>/CSP/ms2Luna.exe) to migrate existing Microsoft CSP 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 register utility.

>Private keys must be exportable to be migrated to the HSM.

To migrate Microsoft CSP keys to the Luna PCIe HSM 7

1.In a command prompt, navigate to the Luna CSP install directory and migrate your existing keys to the HSM.

ms2Luna

You are prompted for the CSP certificate thumbprint.

keymap

Use the keymap utility (<client_install_dir>/CSP/keymap.exe) to manage keys for use with CSP. CSP needs three objects for a certificate to work:

>Private key

>Public key

>A container: data object containing the certificate's association with the keys

A container is automatically created for all keypairs created using the CSP. For existing keypairs that were created outside the CSP, you must create a container and associate it with each keypair to make them available to the CSP.

When you run the keymap utility and select an available slot, the following options are available:

Option	Name	Description
1	Browse Objects	List the objects on the slot (public keys, private keys, and containers) that can be used by the CSP.
2	Create Key Container	Create a key container that can be used by the CSP.
3	View Key Container	Display information about a key container and the keys associated with it.
4	Associate Keys With Container	Map a keypair to an existing container. There are two possible algorithm mappings, depending on the intended purpose of the keypair: >Signature: keypair will be used for signing operations >Exchange: keypair will be used for key exchange
5	Do Nothing	Take no action.
99	Destroy Key Container	Destroy a key container object. This has no effect on the keys associated with a container.
0	Exit	Exit the keymap utility.