INTEGRATION GUIDE · Install and configure EJBCA using SafeNet Luna HSM or HSMoD service About EJBCA EJBCA is an enterprise class PKI Certificate Authority (CA) software, built using

EJBCA INTEGRATION GUIDE

EJBCA: INTEGRATION GUIDE 007-013323-001, Rev. L, February 2019 Copyright © 2019 Gemalto

2

Document Information

Document Part Number 007-013323-001

Release Date February 2019

Revision History

Revision Date Reason

L February 2019 Update

Trademarks, Copyrights, and Third-Party Software

© 2019 Gemalto. All rights reserved. Gemalto and the Gemalto logo are trademarks and service marks of

Gemalto N.V. 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.

Disclaimer

All information herein is either public information or is the property of and owned solely by Gemalto NV.

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 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


3

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.

Contents


4

CONTENTS

PREFACE.............................................................................................................................. 6

Scope ................................................................................................................................................................. 6 Document Conventions ...................................................................................................................................... 6

Command Syntax and Typeface Conventions ............................................................................................... 7 Support Contacts ............................................................................................................................................... 8

Customer Support Portal ................................................................................................................................ 8 Telephone Support ......................................................................................................................................... 8 Email Support ................................................................................................................................................. 8

CHAPTER 1: Introduction.................................................................................................. 9

About EJBCA ..................................................................................................................................................... 9 Third Party Application Details ........................................................................................................................ 9 Supported Platforms ....................................................................................................................................... 9

Prerequisites .................................................................................................................................................... 10 Configuring SafeNet Luna HSM ................................................................................................................... 10 Configuring PED Authenticated SafeNet Luna HSM (v7.x) .......................................................................... 11 Provision your HSM on Demand Service ..................................................................................................... 11 Constraints on HSMoD Services .................................................................................................................. 11 Using SafeNet HSM in FIPS Mode ............................................................................................................... 12 Set up EJBCA ............................................................................................................................................... 12

CHAPTER 2: Integrating SafeNet HSM with EJBCA ....................................................... 14

Configuring the PKCS#11 Provider on EJBCA ................................................................................................ 14 Generating the keys for EJBCA ....................................................................................................................... 16 Installing the Required Software Packages ..................................................................................................... 17 Setting up MySQL Server for EJBCA .............................................................................................................. 17 Creating the User Account for JBOSS and EJBCA ......................................................................................... 18 Installing and Configuring JBOSS .................................................................................................................... 19 Preparing the EJBCA Configuration Files ........................................................................................................ 21 Installing the EJBCA ........................................................................................................................................ 24 Importing the Super-Administrator Token ........................................................................................................ 25 Enabling Key Recovery .................................................................................................................................... 26 Creating the Root CA ....................................................................................................................................... 26 Creating the Sub-CA's ..................................................................................................................................... 27 Creating Certificate Profiles for End Entities .................................................................................................... 28 Creating the End Entity Profiles ....................................................................................................................... 28 Configuring the Publish Queue Process Service ............................................................................................. 29 Configuring the CRL Updater ........................................................................................................................... 30

CHAPTER 3: Integrating SafeNet HSM with PrimeKey EJBCA Enterprise Cloud Edition from Amazon Web Services (AWS) ..................................................................................... 31

Creating the PKCS11 Crypto Token on EJBCA .............................................................................................. 31 Generating the keys for EJBCA ....................................................................................................................... 32

Contents


5

Creating the Root CA ....................................................................................................................................... 33 Creating the Sub-CA's ..................................................................................................................................... 34

Preface


6

PREFACE

This document is intended to guide administrators through the steps for integrating EJBCA with a SafeNet

Luna HSM or HSM on Demand Service. This guide provides the necessary information to install, and

configure EJBCA and secure the EJBCA Certificate Authority (CA) master key using a SafeNet Luna HSM

or HSM on Demand Service.

Scope This guide demonstrates installing and configuring an EJBCA test environment that secures the Certificate

Authority (CA) Private Key within a SafeNet Luna HSM or HSM on Demand Service.

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:

NOTE: Take note. Notes contain important or helpful information.

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

Preface


7

Command Syntax and Typeface Conventions

Convention Description

bold The bold attribute is used to indicate the following:

Command-line commands and options (Type dir /p.)

Button names (Click Save As.)

Check box and radio button names (Select the Print Duplex check box.)

Window titles (On the Protect Document window, click Yes.)

Field names (User Name: Enter the name of the user.)

Menu names (On the File menu, click Save.) (Click Menu > Go To >

Folders.)

User input (In the Date box, type April 1.)

italic The italic attribute is used for emphasis or to indicate a related document. (See the Installation Guide for more information.)

Double quote marks Double quote marks enclose references to other sections within the document.

<variable> In command descriptions, angle brackets represent variables. You must substitute a value for command line arguments that are enclosed in angle brackets.

[ optional ]

[ <optional> ]

[ a | b | c ]

[<a> | <b> | <c>]

Square brackets enclose optional keywords or <variables> in a command line description. Optionally enter the keyword or <variable> that is enclosed in square brackets, if it is necessary or desirable to complete the task.

Square brackets enclose optional alternate keywords or variables in a command line description. Choose one command line argument enclosed within the braces, if desired. Choices are separated by vertical (OR) bars.

{ a | b | c }

{ <a> | <b> | <c> }

Braces enclose required alternate keywords or <variables> in a command line description. You must choose one command line argument enclosed within the braces. Choices are separated by vertical (OR) bars.

Preface


8

Support Contacts If you encounter a problem while installing, registering, or operating this product, refer to the

documentation. If you cannot resolve the issue, contact your supplier or Gemalto Customer Support.

Gemalto Customer Support operates 24 hours a day, 7 days a week. Your level of access to this service is

governed by the support plan arrangements made between Gemalto and your organization. Please consult

this support plan for further information about your entitlements, including the hours when telephone

support is available to you.

Customer Support Portal

The Customer Support Portal, at https://supportportal.gemalto.com, is a where you can find solutions for

most common problems. The Customer Support Portal is a comprehensive, fully searchable database of

support resources, including software and firmware downloads, release notes listing known problems and

workarounds, a knowledge base, FAQs, product documentation, technical notes, and more. You can also

use the portal to create and manage support cases.

NOTE: You require an account to access the Customer Support Portal. To create a new account, go to the portal and click on the REGISTER link.

Telephone Support

If you have an urgent problem, or cannot access the Customer Support Portal, you can contact Gemalto

Customer Support by telephone at +1 410-931-7520. Additional local telephone support numbers are listed

on the support portal.

Email Support

You can also contact technical support by email at [email protected].

https://supportportal.gemalto.com/

https://supportportal.gemalto.com/

mailto:[email protected]

CHAPTER 1: Introduction


9


SafeNet Luna HSM or HSM on Demand (HSMoD) Service secures the EJBCA Certificate Authority (CA) master

key, off-loading cryptographic operations from the server to the HSM.

The integration between SafeNet Luna HSM or HSMoD service and EJBCA uses the industry standard

PKCS#11 interface. EJBCA generates 2048 bit RSA keys on the SafeNet Luna HSM or HSMoD service and the

2048 bit RSA keys are used by the CA for Certificate and CRL signing.

The installation is performed in several steps:

Install and configure SafeNet Luna HSM or HSMoD service

Install and configure EJBCA using SafeNet Luna HSM or HSMoD service

About EJBCA

EJBCA is an enterprise class PKI Certificate Authority (CA) software, built using Java (JEE) technology. It is a

robust, high performance, platform independent, flexible, and component based CA to be used stand-alone or

integrated with other applications.

The following diagram shows an example setup of a secure CA that receives certificate requests.

Third Party Application Details

This integration uses the following third party applications:

EJBCA

You can download EJBCA from the PrimeKey support site: http://www.ejbca.org/download.html

Supported Platforms

List of the platforms which are tested with the following HSMs:

SafeNet Luna HSM: SafeNet Luna HSM appliances are purposefully designed to provide a balance of security,

high performance, and usability that makes them an ideal choice for enterprise, financial, and government

organizations. SafeNet Luna HSMs physically and logically secure cryptographic keys and accelerate

cryptographic processing.

The SafeNet Luna HSM on premise offerings include the SafeNet Luna Network HSM, SafeNet PCIe HSM, and

SafeNet Luna USB HSMs. SafeNet Luna HSMs are also available for access as an offering from cloud service

providers such as IBM cloud HSM and AWS cloud HSM classic

http://www.ejbca.org/download.html



10

The following platforms are supported:

RHEL

NOTE: EJBCA is tested with Luna Clients in HA and FIPS Mode.

SafeNet DPoD: SafeNet Data Protection on Demand (DPoD) is a cloud-based platform that provides on-

demand HSM and Key Management services through a simple graphical user interface. With DPoD, security is

simple, cost effective and easy to manage because there is no hardware to buy, deploy and maintain. As an

Application Owner, you click and deploy services, generate usage reports and maintain just the services you

need.

The following platforms are supported:

RHEL

Prerequisites Before you proceed with the integration, complete the following:

Configuring SafeNet Luna HSM

If you are using a SafeNet Luna HSM, ensure the following:

1. Ensure the HSM is set up, initialized, provisioned and ready for deployment. Refer to the SafeNet Luna HSM Product Documentation for more information.

2. Create a partition on the SafeNet Luna HSM for use with EJBCA.

3. If using a SafeNet Luna Network HSM, register a client for the system and assign the client to each partition to create an NTLS connection for the three partitions. Initialize the Crypto Officer and Crypto User roles for each registered partition.

4. Ensure that each partition is successfully registered and configured. The command to see the registered partitions is:

# /usr/safenet/lunaclient/bin/lunacm

LunaCM v7.1.0-379. Copyright (c) 2006-2017 SafeNet.

Available HSMs:

Slot Id -> 0

Label -> ejbca_part

Serial Number -> 1238712343066

Model -> LunaSA 7.1.0

Firmware Version -> 7.1.0

Configuration -> Luna User Partition With SO (PED) Key Export With

Cloning Mode

Slot Description -> Net Token Slot



11

NOTE: Follow the SafeNet Luna Network HSM Product Documentation for detailed steps for creating the NTLS connection, initializing the partitions, and initializing the Security Officer, Crypto Officer, and Crypto User roles.

Configuring PED Authenticated SafeNet Luna HSM (v7.x)

For PED based SafeNet Luna HSM ensure ProtectedAuthenticationPathFlagStatus is set to ‘1’ in

Misc Section of Chrystoki.conf (Linux) file.

Misc = {

ProtectedAuthenticationPathFlagStatus = 1;

}

Provision your HSM on Demand Service

This service provides your client machine with access to an HSM Application Partition for storing cryptographic

objects used by your applications. Application partitions can be assigned to a single client, or multiple clients

can be assigned to, and share, a single application partition.

To use the HSM on Demand service you need to provision your application partition, starting by initializing the

following roles:

Security Officer (SO) - responsible for setting the partition policies and for creating the Crypto Officer.

Crypto Officer (CO) - responsible for creating, modifying and deleting crypto objects within the partition.

The CO can use the crypto objects and create an optional, limited-capability role called Crypto User that can

use the crypto objects but cannot modify them.

Crypto User (CU) - optional role that can use crypto objects while performing cryptographic operations.

NOTE: Refer to the SafeNet Data Protection on Demand Application Owner Quick Start Guide for procedural information on configuring the HSM on Demand service and create a service client.

The HSM on Demand service client package is a zip file that contains system information needed to connect your client machine to an existing HSM on Demand service

Constraints on HSMoD Services

Please take the following limitations into consideration when provisioning your HSMoD services:

HSM on Demand Service in FIPS mode

HSMoD services operate in a FIPS and non-FIPS mode. If your organization requires non-FIPS algorithms for

your operations, ensure you enable the Allow non-FIPS approved algorithms check box when configuring

your HSM on Demand service. The FIPS mode is enabled by default.

Refer to the Mechanism List in the SDK Reference Guide for more information about available FIPS and non-

FIPS algorithms.



12

Verify HSM on Demand <slot> value

LunaCM commands work on the current slot. If there is only one slot, then it is always the current slot. If you are

completing an integration using HSMoD services, you need to verify which slot on the HSMoD service you send

the commands to. If there is more than one slot, then use the slot set command to direct a command to a

specified slot. You can use slot list to determine which slot numbers are in use by which HSMoD service.

Using SafeNet HSM 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. This means that RSA PKCS and X9.31 key generation is no longer approved for operation in a FIPS-

compliant HSM. If you are using the SafeNet Luna HSM or an HSMoD service in FIPS mode, you have to make

the following change in configuration file:

Misc = {

RSAKeyGenMechRemap = 1;

}

The above setting redirects the older calling mechanism to a new approved mechanism when SafeNet Luna

HSM or the HSMoD service is in FIPS mode.

Set up EJBCA

Before proceeding, we recommend you familiarize yourself with EJBCA. Refer to the EJBCA documentation for

more information on installation and pre-installation requirements at the EJBCA website

https://www.ejbca.org/docs/installation.html.

Install EJBCA on the target machine to continue the integration process.

The machine is labelled in the set up as follows:

ca.example.com: EJBCA Certificate Authority.

Set ca.example.com at the first line in /etc/hosts file.

Additionally, the EJBCA system requires the following software:

Open JDK 6 or Open JDK 7

Apache Ant Build Tool

JBoss Server

My SQL

My SQL JDBC Driver

1. To set up EJBCA Download the following software to the ca.example.com server:

Apache Ant Build Tool: http://archive.apache.org/dist/ant/binaries/

JBoss Server: http://jbossas.jboss.org/downloads

EJBCA: https://www.ejbca.org/download.html

2. Unzip the EJBCA, JBOSS, and ANT files in the /opt/ directory. Execute the following commands:

# unzip /home/apache-ant-1.9.6-bin.zip -d /opt/

https://www.ejbca.org/docs/installation.html

http://archive.apache.org/dist/ant/binaries/

http://jbossas.jboss.org/downloads

https://www.ejbca.org/download.html



13

# unzip /home/jboss-as-7.1.1.Final.zip -d /opt/

# unzip /home/ejbca_ce_6_3_1_1.zip -d /opt/

3. After you unzip the files, we recommend renaming the directories for convenience. Execute the following commands:

# mv /opt/apache-ant-1.9.6 /opt/apache-ant

# mv /opt/jboss-as-7.1.1 /opt/jboss

# mv /opt/ejbca_ce_6_3_1_1 -d /opt/ejbca

4. Set the following variables on ca.example.com to use the Java JDK:

# export JAVA_HOME=<Path to Java JDK>

# export PATH=$JAVA_HOME/bin:$PATH

# export ANT_HOME=/opt/apache-ant

# export JBOSS_HOME=/opt/jboss

# export PATH=$JBOSS_HOME/bin:$PATH

# export APPSRV_HOME=$JBOSS_HOME

# export PATH=$ANT_HOME/bin:$PATH

# export EJBCA_HOME=/opt/ejbca

# export CLASSPATH=$JAVA_HOME/jre/lib/ext:$CLASSPATH

CHAPTER 2: Integrating SafeNet HSM with EJBCA


14


To set up EJBCA Application Server using a SafeNet Luna HSM or HSM on Demand (HSMoD) service,

complete the following steps:

Configuring the PKCS#11 Provider on EJBCA

Generating the keys for EJBCA

Installing the Required Software Packages

Creating the User Account for JBOSS and EJBCA

Installing and Configuring JBOSS

Installing the EJBCA

Importing the Super-Administrator Token

Enabling Key Recovery

Creating the Root CA

Creating the Sub-CA's

Creating Certificate Profiles for End Entities

Creating the End Entity Profiles

Configuring the Publish Queue Process Service

Configuring the CRL Updater

Configuring the PKCS#11 Provider on EJBCA Set up the PKCS#11 on the EJBCA server to enable the EJBCA server to use the SafeNet Luna HSM or

HSMoD service.

To configure the PKCS11 Provider on EJBCA

1. Create a Luna configuration file.

# vi $JAVA_HOME/jre/lib/security/luna.cfg

Add the following to the luna.cfg file:

#SafeNet Luna

name = Luna

library = /usr/safenet/lunaclient/lib/libCryptoki2_64.so

description = Luna config



15

slot = 1

attributes(*,*,*) = {

CKA_TOKEN = true

}

attributes(*,CKO_SECRET_KEY,*) = {

CKA_CLASS=4

CKA_PRIVATE= true

CKA_KEY_TYPE = 21

CKA_SENSITIVE= true

CKA_ENCRYPT= true

CKA_DECRYPT= true

CKA_WRAP= true

CKA_UNWRAP= true

}

attributes(*,CKO_PRIVATE_KEY,*) = {

CKA_CLASS=3

CKA_LABEL=true

CKA_PRIVATE = true

CKA_DECRYPT=true

CKA_SIGN=true

CKA_UNWRAP=true

}

attributes(*,CKO_PUBLIC_KEY,*) = {

CKA_CLASS=2

CKA_LABEL=true

CKA_ENCRYPT = true

CKA_VERIFY=true

CKA_WRAP=true

}

2. Modify the java.security file to include the PKCS11 Provider. Open the java.security file and

make the following changes depending on the Java JDK version you are using:

For Java 6:

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



16

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:


${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


${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

3. Ensure that the nss.cfg file has the following entry:

nssLibraryDirectory = /usr/lib64

4. Ensure that the PKCS11 provider jar is available in the $JAVA_HOME/jre/lib/ext location.

Generating the keys for EJBCA Generate the EJBCA security keys using the EJBCA client tool box. The tool

EJBCA_HOME/dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool is used to

administer and generate keys.

To generate the keys for EJBCA

1. Generate the keys using the EJBCA client tool box.

# cd $EJBCA_HOME

# ant clientToolBox

# dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool generate

/usr/safenet/lunaclient/lib/libCryptoki2_64.so 2048 signKey 1


/usr/safenet/lunaclient/lib/libCryptoki2_64.so 2048 defaultKey 1



17


/usr/safenet/lunaclient/lib/libCryptoki2_64.so 2048 myKey 1

The command line will prompt you for the token password. Enter the SafeNet Luna HSM partition or HSMoD service password.

The keys will generate. These keys are used to create the initial Admin CA, Root CA, and Server CA.

2. To test the keys on the HSM that will be used by EJBCA, use the following command and enter the partition password if prompted:

# dist/clientToolBox/ejbcaClientToolBox.sh PKCS11HSMKeyTool test

/usr/safenet/lunaclient/lib/libCryptoki2_64.so 1

NOTE: 1 is the Slot ID and libCryptoki2_64.so is the HSM cryptographic library.

Installing the Required Software Packages Install the MySQL Server and MySQL JDBC Driver. If your server is not registered with the official RHN

repositories, you must attach the RedHat installation DVD as a local repository.

1. Open the RHEL disc repository.

# yum repolist

# mount | grep iso9660

# vi /etc/yum.repos.d/RHEL_6.5_Disc.repo

2. Add the following to the end of the file:

[RHEL_6.5_Disc]

name=RHEL_6.5_x86_64_Disc

baseurl="file:///media/RHEL_6.5 x86_64 Disc 1/"

gpgcheck=0

3. Verify that the repolist shows the following entry:

# yum repolist

4. Install the MySQL Server and MySQL JDBC.

# yum install mysql-server

# yum install mysql-connector-java

Setting up MySQL Server for EJBCA Update the MySQL configuration file to use UTF-8 at all times. This is beneficial to the user if they add non-

Latin characters to the subject’s Domain Name or anywhere else in the EJBCA front-end.

To set up MySQL Server for EJBCA

1. If you are configuring MySQL Server for EJBCA on a RHEL 6.5 operating system open the MySQL server configuration file in a text editor. If you are not configuring MySQL server for EJBCA on a RHEL 6.5 operating system, proceed to step 4.



18

# vi /etc/my.cnf

2. Enter the following contents at the end of the file:

[client]

default-character-set=utf8

[mysqld]

default-character-set=utf8

default-collation=utf8_unicode_ci

character-set-server=utf8

init-connect='SET NAMES utf8'

character-set-client = utf8

3. Start the MySQL server to apply the changes:

# service mysqld start

The MySQL Server will start up and is now configured to use UTF-8.

4. Create a database to store the EJBCA data. Additionally, grant the appropriate permissions for the database user.

# 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;

NOTE: This sample identifies the EJBCA user as “ejbca” and the user password as “ejbca.” You can use any label or password for the EJBCA user.

5. Restart MySQL.

# service mysqld restart

6. Verify the ejbca user is able to log in to mysql user and test their access to the database:

# mysql -u ejbca -p

mysql> use ejbca;

mysql> show grants for ejbca@localhost;

mysql> exit;

Creating the User Account for JBOSS and EJBCA Create the user accounts which are necessary for allowing the system to execute operations on the JBOSS or

EJBCA on behalf of the user.



19

To create the user account for JBOSS and EJBCA

1. Execute:

# adduser ejbca

# passwd ejbca

The system will prompt you for the user password. Enter the password for the EJBCA user. The password

you entered when executing the # passwd ejbca operation. This password is necessary for logging into

the ca.example.com server.

Installing and Configuring JBOSS Install and configure the JBOSS server to support the EJBCA installation.

To install and configure JBOSS

1. Navigate to the JBOSS directory and open the module file.

# 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. Create the directory that will hold JBOSS’ link to mysql-connector-java.jar and the link.

# 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. Open the module.xml file that describes the connector.

# vi module.xml

5. Add the following to the module.xml file:

<?xml version="1.0" encoding="UTF-8"?>

<module xmlns="urn:jboss:module:1.0" name="com.mysql">

<resources>

<resource-root path="mysql-connector-java.jar"/>

</resources>

<dependencies>

<module name="javax.api"/>

<module name="javax.transaction.api"/>

</dependencies>



20

</module>

6. Set the ejbca user as the owner of the JBOSS directory tree and then start the JBOSS server.

# chown -R ejbca:ejbca /opt/jboss/

# cd $JBOSS_HOME/bin

# ./standalone.sh

7. Open a new terminal window and log in as the ejbca user. Export the following environment variables:









# export CLASSPATH=$JAVA_HOME/jre/lib/ext:$CLASSPATHOpen a new terminal and

logged in as ejbca user and export the environment variables defined in the

Configuring Installing and Deploying the EJBCA section.

8. When the JBOSS server starts, verify the system has an output similar to the following:

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)

9. Backup the configuration file:

# cd $JBOSS_HOME/standalone/configuration

# cp standalone.xml standalone.xml.initial

10. Open the JBOSS command line interface.


# sh jboss-cli.sh

11. Execute the Registration commands using the MySQL Connector.

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

NOTE: This command defines the MySQL driver in /opt/jboss-as-7.1.1Final/standalone/configurations/standalone.xml and then reloads JBOSS.

If the changes are successful, the following content displays in the JBOSS console logs:



21

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)

12. By default, the standalone instance uses an h2/hsqldb database connector and an example database. This configuration is not necessary and you should disable it in the standalone.xml configuration file. Open the standalone.xml configuration file in a text editor:

# vi $JBOSS_HOME/standalone/configuration/standalone.xml

13. Remove the following sections from the standalone.xml configuration file:

<datasource jndi-name="java:jboss/datasources/ExampleDS" pool-name="ExampleDS"

enabled="true" use-java-context="true">

<connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1</connection-url>

<driver>h2</driver>

<security>

<user-name>sa</user-name>

<password>sa</password>

</security>

</datasource>

Remove:

<driver name="h2" module="com.h2database.h2">

<xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>

</driver>

14. Restart JBOSS. Verify in the JBOSS console logs that you can no longer see:


(ServerService Thread Pool -- 27) JBAS010403: Deploying JDBC-compliant driver

class org.h2.Driver (version 1.3)

Verify in the JBOSS console logs that you can see:


(ServerService Thread Pool -- 27) JBAS010404: Deploying non-JDBC-compliant

driver class com.mysql.jdbc.Driver (version 5.1)

Preparing the EJBCA Configuration Files Setup the configuration files for the EJBCA. The configuration files are available in the $EJBCA_HOME/conf/

directory.

To prepare the EJBCA configuration files

1. Navigate to the EJBCA configuration file directory.

# cd $EJBCA_HOME/conf

2. Create a copy of the sample EJBCA configuration file:

# cp ejbca.properties.sample ejbca.properties



22

3. Make the following changes in the ejbca.properties and save the file:

# Application server home directory used during development.

appserver.home=/opt/jboss

# Which application server is used?

appserver.type=jboss

# EJBCA instance.

ejbca.productionmode=ca

4. Create a copy of the sample database properties configuration file:

# cp database.properties.sample database.properties

5. Make the following changes in database.properties and save the file:

# JNDI name of the DataSource used for EJBCA's database access.

datasource.jndi-name=EjbcaDS

# The database name selected for deployment, used to copy XDoclet merge files.

database.name=mysql

# Database connection URL.

database.url=jdbc:mysql://127.0.0.1:3306/ejbca?characterEncoding=UTF-8

# JDBC driver classname.

database.driver=com.mysql.jdbc.Driver

# Database username.

database.username=ejbca

# Database password.

database.password=ejbca

NOTE: If using RHEL 7, set the Database Connection URL parameter “database.url” to point to “jdbc:mysql://127.0.0.1:3306/ejbca?”.

For example: database.url=jdbc:mysql://127.0.0.1:3306/ejbca?.

Additionally, remove the characterEncoding=UTF-8 section from the syntax.

6. Create a copy of the sample install properties configuration file:

# cp install.properties.sample install.properties

Make the following changes in install.properties and save the file:

# Enter a short name for the administrative CA.

ca.name=AdminCA1

# The Distinguished Name of the administrative CA.

ca.dn=CN=AdminCA1,O=EJBCA Sample,C=SE

# The token type the administrative CA will use.

ca.tokentype=org.cesecore.keys.token.PKCS11CryptoToken

# Password for the administrative CA token.



23

ca.tokenpassword=<Partition_password>

# Configuration file were you define key name, password and key alias for the

HSM

ca.tokenproperties=/opt/ejbca/conf/catoken.properties

# The keyspec for the administrative CAs key.

ca.keyspec=2048

# The keytype for the administrative CA, can be RSA, ECDSA or DSA

ca.keytype=RSA

# Default signing algorithm for the administrative CA.

ca.signaturealgorithm=SHA256WithRSA

# The validity in days for the administrative CA, only digits.

ca.validity=3650

# The policy id of the administrative CA. Policy id determines which PKI policy

the CA uses.

ca.policy=null

7. Create a copy of the sample catoken properties configuration file:

# cp catoken.properties.sample catoken.properties

Make the following changes in catoken.properties and save the file:

# Configuration file were you define key name, password and key alias for the

HSM.

sharedLibrary=/usr/safenet/lunaclient/lib/libCryptoki2_64.so

slotLabelType=SLOT_NUMBER

slotLabelValue=1

pin=userpin1

certSignKey=signKey

crlSignKey=signKey

defaultKey=signKey

8. Create a copy of the sample web properties configuration file:

# cp web.properties.sample web.properties

Make the following changes in web.properties and save the file:

# Password for java trust keystore (p12/truststore.jks).

java.trustpassword=changeit

# The CN and DN of the super administrator.

superadmin.cn=SuperAdmin

superadmin.dn=CN=${superadmin.cn},O=EJBCA Sample,C=SE

# The password used to protect the generated super administrator P12 keystore.

superadmin.password=ejbca



24

# Set this to false if you want to fetch the certificate from the EJBCA public

web

# pages, instead of importing the P12-keystore. This can be used to put the

initial

# superadmin-certificate on a smart card.

superadmin.batch=false

# The password used to protect the web servers SSL keystore.

httpsserver.password=serverpwd

# The CA servers DNS host name, must exist on client using the admin GUI.

httpsserver.hostname=ca.example.com

# The Distinguished Name of the SSL server certificate used by the

administrative web gui.

httpsserver.dn=CN=${httpsserver.hostname},O=EJBCA Sample,C=SE

NOTE: The configuration samples are provided for the objective of this guide. You should adjust these settings according to your environment or organization’s security infrastructure.

Installing the EJBCA Install EJBCA on the host system to integrate EJBCA with the SafeNet Luna HSM or HSMoD service. Start the

JBOSS application server as an instance and install EJBCA on the system.

To install the EJBCA

1. Set the ejbca user as the owner of both the JBOSS and EJBCA directory tree.

# chown -R ejbca:ejbca /opt/jboss

# chown -R ejbca:ejbca /opt/ejbca

2. Open a new terminal on ca.example.com and execute the following environment variables:










3. Start the JBOSS application server.


# ./standalone.sh



25

Once the server has started up, the following displays:

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)

Verify the server starts without error. See the JBOSS server logs at the following location: "$JBOSS_HOME/server/default/log/server.log"

4. Open a new terminal on ca.example.com and log in as the ejbca user. Execute the following environment variables:










5. Deploy EJBCA.

# cd $EJBCA_HOME

# ant deploy

The BUILD SUCCESSFUL message displays on successful deployment.

The deployment command may take a while. When the EJBCA deployment has finished, wait for the JBOSS to complete deployment.

Once the server has started up, the following line displays:

14:33:26,946 INFO [org.jboss.as.server] (DeploymentScanner-threads - 2)

JBAS018559: Deployed "ejbca.ear"

6. Install EJBCA and finalize the deployment.

# ant install

The BUILD SUCCESSFUL message displays on successful installation.

7. Once the installation completes, start the JBOSS by executing the following command on the JBOSS terminal:

# ./standalone.sh

Importing the Super-Administrator Token Import the EJBCA Super-Administrator token into the web application. The certificate can then be installed from

the web server to the EJBCA workstation for use in configuring the EJBCA Certification Authority (CA) server.



26

To import the Super-Administrator token

1. Open a web browser to access the EJBCA web page. Enter the following URL:

http://<hostname/IP address>:8080/ejbca

The EJBCA public web page displays.

NOTE: The value for <hostname/IP address> is available in the output of ./standalone.sh. This is the command that was used in the section Installing the EJBCA to start JBOSS.

2. Click Create Browser Certificate under the Enroll section.

3. In the Authentication section, enter the system Username and Password. Click OK. On the EJBCA Certificate Enrollment page click the Enroll button under the Options section. This imports the certificate from EJBCA to the system. This certificate is for communicating with the EJBCA for administrative operations.

4. Verify the certificate import. If you can access the EJBCA Administration Interface by clicking on administration, the certificate import was successful.

Enabling Key Recovery An important aspect when generating private keys is their secrecy and safekeeping. Private keys whose

primary use is non-repudiation should not be backed up

Alternatively, private keys whose primary use is encryption should be backed up, as it is essential to maintain a

copy of and access to the key. If a private encryption key is lost, any data encrypted by the key is rendered

useless.

To enable key recovery

1. Go to the Administration > System Configuration page.

2. Click the Enable Key Recovery check box.

3. Click Save.

Creating the Root CA Verify that the SafeNet Luna HSM or HSM on Demand service PKCS#11 cryptographic token exists and use

the token to create the EJBCA root CA.

To create the root CA

1. Click Crypto Tokens in the EJBCA web portal. Verify that the PKCS#11 token is listed under the Manage Crypto Tokens. Also verify that it displays the SafeNet PKCS#11 library along with the Slot ID and ensure that the library is in the activated and used state.

NOTE: This guide uses AdminCA1 as the Crypto Token label.

2. Click Certification Authorities and enter ExampleRootCA as the name of the new certification authority, then click the Create button. Make the following setting changes:

Signing Algorithm: SHA256WithRSA



27

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

3. Click Create.

4. When the operation completes a new certificate authority will be available in the list of certification authorities.

Creating the Sub-CA's Configure the CA role hierarchy. Create the sub-CA user roles on the system. Create a clone of the sub-CA

template and modify the template configuration for your environment.

To clone the Sub-CA template

1. Open the Certificate Profiles page, from the List of Certificate Profiles.

2. Click the Clone button next to the SUBCA profile.

3. Enter Example Sub-CA in the Name of new certificate profile field.

4. Click Create from Template.

A new certificate profile appears with properties copied from the SUBCA profile.

To create the Sub-CA’s

1. Select the newly created Example Sub-CA and click the Edit button. Change the following options for this profile to the provided value:

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.

3. Create the CA for issuing certificates to the servers. Open the Certification Authorities page, and enter ExampleServerCA in the Add CA box. Click the Create button. Make the following changes on the page:



28


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 basic CA hierarchy.

Creating Certificate Profiles for End Entities Create certificate profiles for the end entities. Base these profiles on the default EJBCA profiles.

To create certificate profiles for end entities


2. Click the Clone button next to the SERVER profile.

3. Enter ExampleServer in the Name of new certificate profile field.



5. Select the ExampleServer certificate profile and click Edit. Make the following changes to the certificate profile:

Available bit lengths: 1024, 2048



Available CAs: ExampleServerCA

6. Click Save. This concludes the creation of basic certificate profiles.

Creating the End Entity Profiles Create the End Entity profiles using the cloned EJBCA certificate profile.



29

To create the end entity profiles

1. Click the End Entity Profiles page and enter Server in the Add Profile text box. Click Add.

2. Select the ExampleServer server profile and click Edit End Entity Profile.

3. Add the following Subject DN attributes and mark them all as Required and Modifiable.

O, Organization

C, Country (ISO 3166)

4. Change the ExampleServer Server profile fields as follows:

Username: Server

Password: Server

Batch generation (clear text pwd storage) use: On

CN, Common name: Server

O, Organization: Example Inc

C, Country (ISO 3166): RS

Default Certificate Profile: ExampleServer

Available Certificate Profiles: ExampleServer

Default CA: ExampleServerCA

Available CAs: ExampleServerCA

Default Token: User Generated

Available Tokens: User Generated

5. Click Save.

All the basic necessary end entity profiles are now available.

Configuring the Publish Queue Process Service Once you begin publishing certificates and CRLs to remote locations, we recommend configuring the Publish

Queue Process Service to allow EJBCA to continue to publish certificates and CRL’s following a network

outage or incident.

To configure the Publish Queue Process service

1. Navigate to the Administration > Services page.

2. Enter Publish Queue Process Service in the Add Service box.

3. Click Add.

4. Select the Publish Queue Process Service and click Edit Service. Enter the following information:

Select Worker: Publish Queue Process Service

Select Interval: Periodical Interval

Period: 1 minutes

Select Action: No Action



30

Active: On

Pin to Specific Node(s): ca.example.com

Description: Publish certificates and CRL's from the publisher queue.

5. Click Save and apply the changes.

Configuring the CRL Updater Configure the CRL updater. The CRL updater generates CRL’s and regenerates CRL’s and certificates as soon

as they expire.

To configure the CRL updater

1. Navigate to the Administration > Services page.

2. Enter CRL Updater in the Add Service box.

3. Click Add.

4. Select the CRL Updater service and click Edit Service. Enter the following information:

Select Worker: CRL Updater

CAs to Check: ExampleRootCA, ExampleServerCA

Select Interval: Periodical Interval

Period: 5 minutes

Select Action: No Action

Active: On

Pin to Specific Node(s): ca.example.com

Description: Updates the CRL's if necessary. Checks are made every 5 minutes.

5. Click Save and apply the changes.

This concludes the initial deployment, installation, and configuration of an EJBCA as certification authority using a SafeNet Luna HSM or HSM on Demand service to secure the EJBCA CA signing keys.

CHAPTER 3: Integrating SafeNet HSM with PrimeKey EJBCA Enterprise Cloud Edition from Amazon Web Services

(AWS)


31

CHAPTER 3: Integrating SafeNet HSM with PrimeKey EJBCA Enterprise Cloud Edition from Amazon Web Services (AWS)

PrimeKey EJBCA Enterprise Cloud Edition from Amazon Web Services (AWS) comes setup with a pre-

configured management CA in Soft Token. The EJBCA Enterprise Cloud Edition from AWS uses the SafeNet

HSM to create the Root certificate and generate CA keys.

To set up PrimeKey EJBCA Enterprise Cloud Edition from AWS using a SafeNet HSM, complete the following:

Configuring the PKCS#11 Provider on EJBCA

Generating the keys for EJBCA

Creating the Root CA

Creating the Sub-CA's

Before you begin the integration, ensure the following:

1. PrimeKey EJBCA Enterprise Cloud Edition from Amazon Web Services (AWS) marketplace is deployed and accessible. The EJBCA Enterprise Edition documentation is available at: https://download.primekey.com/docs/EJBCA-Enterprise-Cloud/latest/

2. The SafeNet HSM client is installed and configured on the EJBCA instance and an NTLS connection has been established between the client and the SafeNet HSM. See Configuring SafeNet Luna HSM in the Prerequisites section for further details.

3. Configure the EJBCA web portal. Follow the instructions available in the EJBCA Enterprise Cloud Edition AWS Launch Guide for further details about launching the EJBCA.

Creating the PKCS11 Crypto Token on EJBCA Access the EJBCA Admin web portal graphical user interface (GUI), and generate cryptographic tokens.

To create the PKCS11 crypto token on EJBCA

1. Open a web browser and access the EJBCA Admin Web at the URL:

https://<AWS Public DNS Name or AWS Public IP Address>/ejbca/adminweb

2. Login to the EJBCA web portal.

3. Select Crypto Tokens under CA Functions. The Manage Crypto Tokens [?] page displays.

4. Scroll to the bottom of the table and click Create new… The New Crypto Token page displays.

5. Enter the details to create a PKCS11 token using the SafeNet HSM and Luna Client.

The Authentication Code is the SafeNet HSM Crypto Officer password.

https://download.primekey.com/docs/EJBCA-Enterprise-Cloud/latest/

https://download.primekey.com/docs/EJBCA-Enterprise-Cloud/latest/ejbca-ece-launch-guide.pdf

https://download.primekey.com/docs/EJBCA-Enterprise-Cloud/latest/ejbca-ece-launch-guide.pdf


(AWS)


32

Click Save when complete.

6. The message “CryptoToken created successfully” displays.

Generating the keys for EJBCA Generate the encryption keys for EJBCA using the EJBCA Admin web portal and the SafeNet Crypto Token.


(AWS)


33

To generate the keys for EJBCA

1. Access the Crypto Token : SafeNet.

2. Scroll to the bottom of the page and enter a Key Name. Open the Key Size drop-down menu and set a key size.

3. Click Generate new key pair.

Repeat this procedure two more times to generate additional keys for the Root CA and Sub CA.

Creating the Root CA Verify the availability of the SafeNet Luna HSM PKCS#11 cryptographic token, and use the token to create the

EJBCA Root CA.

To create the root CA

1. Click Crypto Tokens in the EJBCA web portal and verify that the PKCS#11 token is listed in the Manage Crypto Tokens [?] table. Additionally, verify that the entry displays the SafeNet PKCS#11 library, the slot ID, and that the library entries are positive in the Active and Used state.


(AWS)


34

NOTE: This guide uses SafeNet as the Crypto Token label.

2. Click Certification Authorities and enter ExampleRootCA as the name of the new certification authority.

3. Make the following settings changes:


Crypto Token: SafeNet.

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

4. Click Create.

When the operation completes a new certificate authority will be available in the list of CA’s.

Creating the Sub-CA's Create the sub-CA user roles on the system to complete configuring the CA role hierarchy. Create a clone of

the sub-CA template and modify the clone template configuration to operate in your environment.


(AWS)


35

To clone the Sub-CA template


2. Click the Clone button next to the SUBCA profile.

3. Enter Example Sub-CA in the Name of new certificate profile field.



To create the Sub-CA’s

1. Select the newly created Example Sub-CA and click the Edit button. Change the following options for this profile to the provided value:

Available bit lengths: 2048 bits

Validity: 15y

Allow validity override: Off



Available CAs: ExampleRootCA

2. Click Save.

3. Create the CA for issuing certificates to the servers. Open the Certification Authorities page, and enter ExampleServerCA in the Add CA box. Click the Create button. Make the following changes to the provided values:


Crypto Token: SafeNet.

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 basic CA hierarchy.

Refer to the section Creating End Entity Profiles to create the End Entity. This completes the EJBCA Enterprise Cloud Edition from Amazon Web Services Integration with SafeNet HSM.

Documents

INTEGRATION GUIDE · Install and configure EJBCA using SafeNet Luna HSM or HSMoD service About EJBCA EJBCA is an enterprise class PKI Certificate Authority (CA) software, built using