EJBCA SafeNet Luna HSM IntegrationGuide RevJ
EJBCA SafeNet Luna HSM IntegrationGuide RevJ
Integration Guide
All information herein is either public information or is the property of and owned solely by Gemalto and/or its
subsidiaries who shall have and keep the sole right to file patent applications or any other kind of intellectual
property protection in connection with such information.
Nothing herein shall be construed as implying or granting to you any rights, by license, grant or otherwise, under
any intellectual and/or industrial property rights of or concerning any of Gemalto’s information.
This document can be used for informational, non-commercial, internal and personal use only provided that:
The copyright notice below, the confidentiality and proprietary legend and this full warning notice appear in
all copies.
This document shall not be posted on any publicly accessible network computer or broadcast in any media
and no modification of any part of this document shall be made.
Use for any other purpose is expressly prohibited and may result in severe civil and criminal liabilities.
The information contained in this document is provided "AS IS" without any warranty of any kind. Unless
otherwise expressly agreed in writing, Gemalto makes no warranty as to the value or accuracy of information
contained herein.
The document could include technical inaccuracies or typographical errors. Changes are periodically added to
the information herein. Furthermore, Gemalto reserves the right to make any change or improvement in the
specifications data, information, and the like described herein, at any time.
Gemalto hereby disclaims all warranties and conditions with regard to the information contained herein,
including all implied warranties of merchantability, fitness for a particular purpose, title and non-infringement. In
no event shall Gemalto be liable, whether in contract, tort or otherwise, for any indirect, special or consequential
damages or any damages whatsoever including but not limited to damages resulting from loss of use, data,
profits, revenues, or customers, arising out of or in connection with the use or performance of information
contained in this document.
Gemalto does not and shall not warrant that this product will be resistant to all possible attacks and shall not
incur, and disclaims, any liability in this respect. Even if each product is compliant with current security
standards in force on the date of their design, security mechanisms' resistance necessarily evolves according to
the state of the art in security and notably under the emergence of new attacks. Under no circumstances, shall
Gemalto be held liable for any third party actions and in particular in case of any successful attack against
systems or equipment incorporating Gemalto products. Gemalto disclaims any liability with respect to security
for direct, indirect, incidental or consequential damages that result from any use of its products. It is further
stressed that independent testing and verification by the person using the product is particularly encouraged,
especially in any application in which defective, incorrect or insecure functioning could result in damage to
persons or property, denial of service or loss of privacy.
© 2015-18 Gemalto. All rights reserved. Gemalto and the Gemalto logo are trademarks and service marks of
Gemalto and/or its subsidiaries and are registered in certain countries. All other trademarks and service marks,
whether registered or not in specific countries, are the property of their respective owners.
Contents
Preface .................................................................................................................................. 4
Scope .............................................................................................................................................................. 4
Document Conventions .................................................................................................................................. 4
Command Syntax and Typeface Conventions ......................................................................................... 5
Support Contacts ...................................................................................................................................... 6
1 Introduction ...................................................................................................................... 7
Overview ......................................................................................................................................................... 7
Understanding the EJBCA .............................................................................................................................. 7
3rd Party Application Details .................................................................................................................... 8
Supported Platforms ....................................................................................................................................... 8
SafeNet Luna HSM (v7.x) ........................................................................................................................ 8
SafeNet Luna HSM (v5.x/6.x)................................................................................................................... 8
Prerequisites ................................................................................................................................................... 9
Configuring PED Auth SafeNet Luna HSM (v6.1/v7.0) ............................................................................ 9
Configuring PED Auth SafeNet Luna HSM (v6.2.x/v6.3.0/v7.x) ............................................................ 10
Configuring SafeNet Luna Network HSM 7.x ......................................................................................... 10
Configuring SafeNet Luna Network HSM (v5.x/6.x) ............................................................................... 13
Using Luna 6.x/7.x in FIPS Mode ........................................................................................................... 14
EJBCA Setup ......................................................................................................................................... 14
Preface
This document is intended to guide administrators through the steps for EJBCA and SafeNet Luna HSM
integration. This guide provides the necessary information to install, configure, and integrate EJBCA with
SafeNet Luna Hardware Security Modules (HSM).
Scope
This guide provides instructions for setting up a small test lab with EJBCA running with SafeNet Luna HSM for
securing the private keys of CA. It explains how to install and configure the software that is required for setting
up EJBCA while storing private key on SafeNet Luna HSM.
Document Conventions
This section provides information on the conventions used in this template.
Notes
Notes are used to alert you to important or helpful information. These elements use the following format:
Cautions
Cautions are used to alert you to important information that may help prevent unexpected results or data loss.
These elements use the following format:
CAUTION: Exercise caution. Caution alerts contain important information that may
help prevent unexpected results or data loss.
Warnings
Warnings are used to alert you to the potential for catastrophic data loss or personal injury. These elements use
the following format:
WARNING: Be extremely careful and obey all safety and security measures. In
this situation you might do something that could result in catastrophic data loss or
personal injury.
italic The italic attribute is used for emphasis or to indicate a related document. (See the
Installation Guide for more information.)
Support Contacts
Address Gemalto
4690 Millennium Drive
Belcamp, Maryland 21017, USA
Phone US 1-800-545-6608
International 1-410-931-7520
1
Introduction
Overview
SafeNet Luna HSM integrates with EJBCA to provide significant performance improvements by off-loading
cryptographic operations from the server to HSM. In addition, SafeNet Luna HSM provides extra security by
protecting the CA private keys within a FIPS 140-2 certified hardware security module.
This integration between SafeNet Luna HSM and EJBCA uses the industry standard PKCS#11 interface.
EJBCA generates the 2048 bit RSA keys on SafeNet Luna HSM and it is used by the CA for Certificate and
CRL signing.
The installation is performed in several steps:
Install and configure SafeNet Luna HSM.
Install and configure EJBCA using SafeNet Luna HSM.
Supported Platforms
SafeNet Luna HSM (v7.x)
The following platforms are tested with SafeNet Luna HSM:
Red Hat Enterprise Linux Luna Network HSM 6.4.0 7.1.1 Open JDK 7
7.0(64-bit) Appliance Software
v7.2.0
Firmware v7.2.0
Luna HSM Client 7.2.0
Red Hat Enterprise Linux Luna Network HSM 6.4.0 7.1.1 Open JDK 7
7.0(64-bit) Appliance Software
v7.1.0
Firmware v7.1.0
Luna HSM Client 7.1.0
Red Hat Enterprise Linux Luna Network HSM 6.4.0 7.1.1 Open JDK 7
6.5(64-bit) Appliance Software
v7.0.0
Firmware v7.0.1
Luna HSM Client 7.0.0
Red Hat Enterprise Linux Luna SA Appliance 6.4.0 7.1.1 Open JDK 7
6.5 (64 bit) Software v6.3.0
Firmware 6.10.9 & 6.27.0
Luna Client 6.3.0
Red Hat Enterprise Linux Luna SA Appliance 6.4.0 7.1.1 Open JDK 7
6.5 (64 bit) Software v6.2.2
Firmware 6.10.9 & 6.24.3
Luna Client 6.2.2
Red Hat Enterprise Linux Luna SA Appliance 6.4.0 7.1.1 Open JDK 7
6.5 (64 bit) Software v6.2.1
Firmware 6.10.9
Luna Client 6.2.1
Red Hat Enterprise Linux Luna SA Appliance 6.3.1.1 7.1.1 Open JDK 7
6.5 (64 bit) Software v6.2.1
Firmware 6.10.9 & 6.24.2
Luna Client 6.2.1
Red Hat Enterprise Linux Luna SA Appliance 6.3.1.1 7.1.1 Open JDK 7
6.5 (64 bit) Software v6.1
Firmware 6.10.9
Luna Client 6.1
Red Hat Enterprise Linux Luna SA Appliance 6.3.1.1 7.1.1 Open JDK 6
6.5 (64 bit) Software v5.4.7
Firmware 6.10.9
Luna Client 5.4.1
NOTE: EJBCA is tested with Luna Clients in HA & FIPS Mode also.
Prerequisites
Configuring PED Auth SafeNet Luna HSM (v6.1/v7.0)
You need to obtain the following patch to work with PED based SafeNet Luna HSM when using the version 6.1
and 7.0:
DOC ID: DOW4166
NOTE: The below configuration is only applicable for Version 6.1/7.0 of PED
based SafeNet Luna HSM.
CONFIGURATION:
1. Copy the libshim.so to <lunaclient installation>/lib directory. It is advised to first rename the previous shim.
2. Point the application to the libshim.so instead of the Cryptoki shared object library. To point it, open the
/etc/Chrystoki.conf file and make the following changes:
For Linux,
Chrystoki2 = {
LibUNIX64 = /usr/safenet/lunaclient/lib/libshim.so;
}
Shim2 = {
LibUNIX64 = /usr/safenet/lunaclient/lib/libCryptoki2_64.so;
}
Misc = {
:
ApplicationInstance=SA5_COMPATIBILITY;
FunctionBindLevel=2;
:
}
Contact Customer Support if you need assistance regarding the above configuration.
c. The application partition SO can create the Crypto Officer, but only the Crypto Officer can create the
Crypto User. Therefore, the SO must log out to allow the Crypto Officer to log in.
Type role logout.
lunacm:> role logout
NOTE: The black Crypto Officer PED key/Crypto Officer Password (in case
of PW-Auth) is valid for the initial login only. You must change the initial
credential on the key using the command role changepw during the initial
login session, or a subsequent login. Failing to change the credential will
result in a CKR_PIN_EXPIRED error while performing role-dependent
actions.
Where <username> is the name of the user you want to add to the hsmusers group.
NOTE: The user you delete will continue to have access to the HSM until you
reboot the client workstation.
NOTE: The above configuration is valid for Luna 7.x and Luna 6.x (F/W Version
6.22.0 and above only).
Also please make the following changes in Chrystoki.conf for Luna Client 6.x/7.x to list the registered partition
with Slot ID 1 instead of 0:
Presentation = {
OneBaseSlotId =1;
}
EJBCA Setup
Before proceeding, it is recommended to familiarize yourself with EJBCA. Refer to the EJBCA documentation
for more information to install and pre-installation requirements.
https://www.ejbca.org/docs/installation.html
EJBCA must be installed on the target machine to carry on with the integration process. Details of the target
machine are as follows:
An RHEL machine required to setup an EJBCA Certification Authority.
The machine utilized is denoted in the setup is as follows:
ca.example.com: EJBCA Certificate Authority
Set the ca.example.com at the first line in /etc/hosts file.
2
Integrating SafeNet Luna HSM with EJBCA
# export PATH=$ANT_HOME/bin:$PATH
# export EJBCA_HOME=/opt/ejbca
# export CLASSPATH=$JAVA_HOME/jre/lib/ext:$CLASSPATH
2. Modify the java.security file to include the PKCS11 Provider. Open the java.security file and do the
following changes:
For Java 6:
# vi $JAVA_HOME/jre/lib/security/java.security
security.provider.1=sun.security.provider.Sun
security.provider.2=sun.security.rsa.SunRsaSign
security.provider.3=com.sun.net.ssl.internal.ssl.Provider
security.provider.4=com.sun.crypto.provider.SunJCE
security.provider.5=sun.security.jgss.SunProvider
security.provider.6=sun.security.pkcs11.SunPKCS11 ${java.home}/lib/security/luna.cfg
security.provider.7=com.sun.security.sasl.Provider
security.provider.8=org.jcp.xml.dsig.internal.dom.XMLDSigRI
security.provider.9=sun.security.smartcardio.SunPCSC
For Java 7:
# vi $JAVA_HOME/jre/lib/security/java.security
security.provider.1=sun.security.pkcs11.SunPKCS11 ${java.home}/lib/security/nss.cfg
security.provider.2=sun.security.provider.Sun
security.provider.3=sun.security.rsa.SunRsaSign
security.provider.4=sun.security.ec.SunEC
security.provider.5=com.sun.net.ssl.internal.ssl.Provider
security.provider.6=sun.security.pkcs11.SunPKCS11 ${java.home}/lib/security/luna.cfg
security.provider.7=com.sun.crypto.provider.SunJCE
security.provider.8=sun.security.jgss.SunProvider
security.provider.9=com.sun.security.sasl.Provider
security.provider.10=org.jcp.xml.dsig.internal.dom.XMLDSigRI
security.provider.11=sun.security.smartcardio.SunPCSC
[mysqld]
default-character-set=utf8
default-collation=utf8_unicode_ci
character-set-server=utf8
init-connect='SET NAMES utf8'
character-set-client = utf8
2. After this you need to start the MySQL server to apply the changes:
# service mysqld start
Once the MySQL server has been installed and set-up to use UTF-8, it is necessary to create the database
to store EJBCA data, as well as to create and grant appropriate permissions to the user, used for accessing
the database:
# mysql -u root -p
mysql> create database ejbca;
mysql> grant all privileges on ejbca.* to 'ejbca'@'localhost' identified by 'ejbca';
mysql> flush privileges;
mysql> exit;
3. After setting the user ejbca and password ‘ejbca’ restart the MySQL, you can replace the username and
password as per your choice:
# service mysqld restart
4. Verify that ejbca user is able to log in to mysql user and test their access on the database:
# mysql -u ejbca -p
mysql> use ejbca;
mysql> show grants for ejbca@localhost;
mysql> exit;
Installing JBOSS
Install JBOSS. No need to configure every detail (no mail, default logging), but enough details to get the
platform running and tweaked the way EJBCA needs for installation.
1. Tweak the JBOSS configuration by enabling certain security functions that EJBCA requires.
# cd $JBOSS_HOME/modules/sun/jdk/main
# vi module.xml
2. Add the following entries to the system export paths:
<path name="sun/security/x509"/>
<path name="sun/security/pkcs11"/>
<path name="sun/security/pkcs11/wrapper"/>
<path name="sun/security/action"/>
3. Now, create the directory that will hold JBOSS’ link to mysql-connector-java.jar, and the link itself:
# mkdir -p $JBOSS_HOME/modules/com/mysql/main
# cd $JBOSS_HOME/modules/com/mysql/main
# ln -s /usr/share/java/mysql-connector-java.jar mysql-connector-java.jar
4. Now, build the module.xml file that describes the connector.
# vi module.xml
6. Now first make the ejbca user as the owner of the JBOSS directory tree and then start the JBOSS Server.
# chown -R ejbca:ejbca /opt/jboss/
7. Open a new terminal and logged in as ejbca user and export the environment variables defined in the
Configuring Installing and Deploying the EJBCA section.
# cd $JBOSS_HOME/bin
# ./standalone.sh
8. When the JBOSS successfully started ensure that something like this at the end:
11:12:00,514 INFO [org.jboss.as] (Controller Boot Thread) JBAS015874: JBoss AS
7.1.1.Final "Brontes" started in 6329ms - Started 133 of 208 services (74 services are
passive or on-demand)
Now when the JBOSS service is running, Enable MySQL connector using the JBOSS command line
interface, which will update the configuration of the standalone instance. But before making any changes,
first backup the configuration file:
# cd $JBOSS_HOME/standalone/configuration
# cp standalone.xml standalone.xml.initial
9. Run registration command from the jboss CLI (the small text is a single line):
# cd $JBOSS_HOME/bin
# sh jboss-cli.sh
connect
/subsystem=datasources/jdbc-driver=com.mysql.jdbc.Driver:add(driver-
name=com.mysql.jdbc.Driver,driver-module-name=com.mysql,driver-xa-datasource-class-
name=com.mysql.jdbc.jdbc.jdbc2.optional.MysqlXADataSource)
exit
This cli action defines our MySQL driver in /opt/jboss-as-
7.1.1.Final/standalone/configuration/standalone.xml, and then reloads JBOSS.
If changes have been successful, following message displays in the console logs of JBOSS:
11:16:18,349 INFO [org.jboss.as.connector.subsystems.datasources] (ServerService Thread
Pool -- 27) JBAS010404: Deploying non-JDBC-compliant driver class com.mysql.jdbc.Driver
(version 5.1)
By default, the standalone instance is defined with an h2/hsqldb database connector, and an example
database. If left unchanged, EJBCA is preconfigured to use it for example purposes. It is not required and
you need to disable it in the standalone.xml configuration file.
# vi $JBOSS_HOME/standalone/configuration/standalone.xml
Also remove:
<driver name="h2" module="com.h2database.h2">
<xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
</driver>
Now, watch the console log after restarting JBOSS, you should no longer see:
11:16:18,156 INFO [org.jboss.as.connector.subsystems.datasources] (ServerService Thread
Pool -- 27) JBAS010403: Deploying JDBC-compliant driver class org.h2.Driver (version 1.3)
NOTE: For RHEL 7, edit the parameter database.url with below entry
database.url=jdbc:mysql://127.0.0.1:3306/ejbca? And remove
characterEncoding=UTF-8
NOTE: The configuration setting is done here for the objective of this guide,
change these settings according to your environment.
Installing EJBCA
The installation itself is more or less a straightforward process. The ejbca user must be the owner of both the
JBOSS directory tree and the EJBCA directory tree. Before running our initial deployment, it's a requirement to
ensure that this is the true.
# chown -R ejbca:ejbca /opt/jboss
# chown -R ejbca:ejbca /opt/ejbca
It is necessary to run the JBoss AS instance in order to get on with the next step. To perform this task, open a
new terminal on ca.example.com and export the environment variables defined in the Configuring Installing and
Deploying the EJBCA section.
# cd $JBOSS_HOME/bin
# ./standalone.sh
Once the server has started up, the following line displays at the end:
14:20:49,326 INFO [org.jboss.as] (Controller Boot Thread) JBAS015874: JBoss AS 7.1.1.Final
"Brontes" started in 5907ms - Started 130 of 204 services (74 services are passive or on-demand)
Ensure that the server starts without any error. See the server logs of JBOSS Server at the following
location: "$JBOSS_HOME/server/default/log/server.log"
Once the instance is up and running, proceeds with the installation of EJBCA. Open a new terminal and log in
as ejbca user on ca.example.com server and export the environment variables defined in the Configuring
Installing and Deploying the EJBCA section.
# cd $EJBCA_HOME
# ant deploy
BUILD SUCCESSFUL message displays when deployment completed successfully. The deployment command
might take a while, after deployment has finished wait for the JBOSS to complete deployment.
Once the server has started up, the following line displays:
3. Enter the Username and Password in Authentication section and click OK.
4. Click the Enroll button under Options section on the EJBCA Certificate Enrollment page. It imports the
certificate and this certificate will be used for communicating the EJBCA for Administrative settings.
5. Once this has been completed, it should be possible to access the administration interface of the EJBCA by
clicking the Administration.
Create Root CA
Ensure that the PKCS#11 token using SafeNet Luna HSM has been created successfully. Click the Crypto
Tokens and verify that the PKCS#11 token is listed under the Manage Crypto Tokens. Also ensure that it
displays the SafeNet PKCS#11 library along with the Slot ID. You need to verify that it is in activated and used
state.
NOTE: AdminCA1 is the name of the Crypto Token as per the settings
mentioned in this guide.
With basic installation done, it is time to set up the certification authority hierarchy. The starting point is the Root
CA. Click Certification Authorities and enter ExampleRootCA as the name of new certification authority, then
click the Create button. Make the following changes:
Signing Algorithm: SHA256WithRSA
Crypto Token: AdminCA1.
defaultKey=defaultKey
certSignKey=signKey
Description: Root CA for Example Inc
Subject DN: CN=ExampleRootCA,O=Example Inc,C=RS
Validity: 20y
Issuing Distribution Point on CRLs: On
Default CRL Dist. Point: Click on Generate button.
CRL Expire Period: 1y
CRL Overlap Time: 2d
Once information is filled, click the Create button. Wait until the operation finishes. Once it is completed, a new
certification authority will be available in the list of Certification Authorities.
Create Sub-CA's
Open the Certificate Profiles page, from List of Certificate Profiles, click the Clone button against the
SUBCA profile, enter Example Sub-CA in the Name of new certificate profile box, and click the Create from
Template button. It creates a new certificate profile with properties copied from the SUBCA profile.
1. Select the newly created Example Sub-CA and click the Edit button. The following options for this profile
should be changed:
Available bit lengths: 2048 bits
Validity: 15y
Allow validity override: Off
CRL Distribution Points: On
Use CA defined CRL Dist. Point: On
Available CAs: ExampleRootCA
2. Click Save to commit the changes.
3. The next CA in line is the certification authority which will issue certificates for servers. Open the
Certification Authorities page, and enter ExampleServerCA in the Add CA box, then click the Create
button. Make the following changes on the page:
Signing Algorithm: SHA256WithRSA
Crypto Token: AdminCA1.
defaultKey=myKey
Description: Example's CA in charge of issuing certificates for servers within the organization.
Subject DN: CN=ExampleServerCA,O=Example Inc,C=RS
Signed By: ExampleRootCA
Certificate Profile: Sub-CA
Validity (*y *mo *d) or end date of the certificate: 15y
Use Issuing Distribution Point on CRLs: On
Default CRL Dist. Point: Click on Generate button
CRL Expire Period (*y *mo *d *h *m): 14d
CRL Overlap Time (*y *mo *d *h *m): 12h
4. Click the Create button to finalize the creation of basic CA hierarchy.