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.
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:
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 1CODE
Step 6: We recommend running from a directory owned by yourself (not having to use sudo) instead of running from the
The following shows and example of running from your own directory:
$ /usr/lunasa/bin/ctp firstname.lastname@example.org: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 miltonBASH
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 partition2BASH
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
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.
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.
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
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
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
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
Note that 87 needs to be replaced with the handle of the private key found when running the list command.