For information on how to install, configure, and integrate EJBCA with Thales Luna HSM, refer to Thales EJBCA with Thales Luna HSM Integration Guide.


Installation and Configuration Notes

The following covers notes on installation and configuration that may be relevant for your EJBCA integration.

Installation

For information on installing Luna HSM, refer to Thales Luna HSM documentation for more information.

Using Luna 6.x/7.x in FIPS Mode

Under FIPS 186-3/4, the RSA methods permitted for generating keys are 186-3 with primes and 186-3 with aux primes. Therefore, RSA PKCS and X9.31 key generation are no longer approved for operation in a FIPS compliant Luna HSM. If you are using the Luna HSM in FIPS mode, set the following setting in the configuration file to redirect the older calling mechanism to a new approved mechanism when in FIPS mode:

Misc = {
 RSAKeyGenMechRemap = 1;
}

Configuration

For configuration instructions, refer to the Luna SA Online Help – Document # 800274-xxx document provided on your installation CD.

Perform all of the steps in section A - Configuration (Setup Appliance after Installing) and note the following regarding the setup:

  • Step 3: Note that changing many of the policies will reset the HSM and you will not be able to change any of these policies later on.
  • Step 4: A new partition could be added at any time. Each partition will be represented as a PKCS#11 slot. Make sure to write the Record Partition Client Password (TP) in a text file. In the example, the password is btqx-EFGH-3456-7/K9 for the first created partition (slot 1). The TP will later be used as PIN for the slot.

  • Step 5: We recommend allowing partitions (p11 slots) to be "activated". If a partition is not activated, you will have to insert the black key in the PED and enter the PIN each time a resource in the HSM is used by the client. The following displays an example command to allow activating a partition:

    lunash:>partition changePolicy -partition partition1 -policy 22 -value 1
    CODE

  • Step 6: We recommend running from a directory owned by yourself (not having to use sudo) instead of running from the /usr/LunaSA/bin directory.
    The following shows and example of running from your own directory:

    $ /usr/lunasa/bin/ctp admin@lunasa.int.primekey.com:server.pem .
    BASH

    The following shows examples of when sudo must be used: registration of server and adding client certificates (root owned files and directories are used and updated):

    $ sudo /usr/lunasa/bin/vtl addServer -n lunasa.int.primekey.com -c server.pem
$ sudo /usr/lunasa/bin/vtl createCert -n milton
    BASH

  • Step 7: Each partition assigned to a client will be represented by a PKCS#11 slot for this client. Each newly added partition will be put last in the slot list, and the number of a slot will be slot list index plus 1 (list index starting with 0 and slot number starting with 1). To view the partition slot mapping on the client, run the following. The client may then use these slots with EJBCA and its tools.

    $ /usr/lunasa/bin/vtl verify

The following Luna SA Slots/Partitions were found: 

Slot    Serial #        Label
====    ========        =====
 1      950784001       partition1
 2      950784002       partition2
    BASH

Activating Slots

A partition (slot) must be activated before it can be used by a client as described in B - Administration & Maintenance > Activating and AutoActivating Partitions of the Luna SA Online Help – Document # 800274-xxx document provided on your installation CD. The partition policy required to do the activation must have been set (see step 5 above). The following displays an example for activating a partition using the password from the configuration in step 4 above:

lunash:>hsm login
lunash:>partition activate -partition partition1 -password btqx-EFGH-3456-7/K9
BASH

Generate Keys on a Slot

Keys can be generated in the Admin UI of EJBCA or using the clientToolBox CLI. The CLI is useful for quickly testing HSMs. Keys generated with the CLI are available from the UI as well, and vice versa.

The following displays an example for generating keys on a slot using the password btqx-EFGH-3456-7/K9 from the step 4 above:

$ ./ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /usr/lunasa/lib/libCryptoki2_64.so 2048 rsa2048_1 1
0    [main] INFO  org.ejbca.util.keystore.KeyTools  - Using SUN PKCS11 provider: sun.security.pkcs11.SunPKCS11
PKCS11 Token [SunPKCS11-Luna] Password: 
Created certificate with entry rsa2048_1.
$ ./ejbcaClientToolBox.sh PKCS11HSMKeyTool generate /usr/lunasa/lib/libCryptoki2_64.so secp160r1 secp160r1_1 1
0    [main] INFO  org.ejbca.util.keystore.KeyTools  - Using SUN PKCS11 provider: sun.security.pkcs11.SunPKCS11
PKCS11 Token [SunPKCS11-Luna] Password: 
Created certificate with entry secp160r1_1.
BASH

List and Test Keys Used by EJBCA

The following displays an example of listing and testing all keys that could be used by EJBCA:

$ ./ejbcaClientToolBox.sh PKCS11HSMKeyTool test /usr/lunasa/lib/libCryptoki2_64.so 1
Test of keystore with ID 1.
0    [main] INFO  org.ejbca.util.keystore.KeyTools  - Using SUN PKCS11 provider: sun.security.pkcs11.SunPKCS11
PKCS11 Token [SunPKCS11-libCryptoki2_64.so-slot2] Password: 

Testing of key: rsa2048_1
SunJCE version 1.7SunPKCS11-libCryptoki2_64.so-slot2 version 1.7; modulus length: 2048; byte length 245. The docoded byte string is equal to the original!
Signature test of key rsa2048_1: signature length 256; first byte 28; verifying true
Key statistics. 
Signings per second: 369; Decryptions per second: 135

Testing of key: secp160r1_1
Signature test of key secp160r1_1: signature length 48; first byte 30; verifying true
Key statistics. 
Signings per second: 68 No crypto available for this key. 
BASH

Create Crypto Token and CA in EJBCA

To create a CA, first create a Crypto Token in EJBCA. To create a PKCS11 Crypto Token, first ensure that EJBCA knows the location of the PKCS#11 driver library. References to the PKCS#11 library files are configured in conf/web.properties in EJBCA, and EJBCA recognizes the most common locations of Luna PKCS#11 drivers.

In the EJBCA Admin UI, click Crypto Tokens under CA Functions to generate a new PKCS#11 Crypto Token using the Luna library. With the created crypto token, then go ahead and create CAs, using keys on the HSM, by selecting the correct crypto token.

Sample CA Token Properties

The following displays a sample configuration of CA Token Properties for PKCS#11 token when creating a CA using the CLI, bin/ejbca.sh ca init, creating a new crypto token.

sharedLibrary=/usr/lunasa/lib/libCryptoki2_64.so
slotLabelType=SLOT_NUMBER
slotLabelValue=1
certSignKey=myECCKey
crlSignKey=myECCKey
defaultKey=default
BASH

CA Token properties when creating a CA using the CLI with an existing crypto token, or when using the command bin/ejbca.sh ca changecatoken is:

certSignKey=myECCKey
crlSignKey=myECCKey
defaultKey=default
CODE

Useful Luna Commands

The following lists useful native Luna cmu commands.

To list objects and their handles:

./cmu list -display=index,handle,class,keyType,label
BASH

If you have created keys with native commands, or imported keys, there is probably no certificate object as required by Java PKCS#11 provider. To create a self-signed certificate referencing the private handle, run:

./cmu selfSign -privatehandle=87 -CN="caSign00001" -startDate=20020101
-endDate=20451231 -serialNum=0133337f
BASH

Note that 87 needs to be replaced with the handle of the private key found when running the list command.