Luna CSP Registration Utilities
This section describes how to use the Luna CSP registration tool and related utilities to configure the
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 Network HSM 7 partitions with Luna CSP, your CSP and KSP code should work the same whether the Luna Network 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:
•Registering Partitions/HA Groups to CSP
•Registering Cryptographic Algorithms to be Used in Software
>ms2Luna — Used to migrate Microsoft CSP keys to a Luna Network 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
>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.
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>
Syntax
register.exe [/partition | /algorithms | /library | /usagelimit] [/password]
| 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
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)
register
You are prompted (y/n) to decide whether to register each available partition
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 Network HSM 7. The register /algorithms command allows you to choose which algorithms to de-register from the Luna Network 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
Prerequisites
>You must already have registered a partition
>Private keys must be exportable to be migrated to the HSM.
To migrate Microsoft CSP keys to the Luna Network 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. |
