primekey enterprise java bean certificate authority (ejbca) ·...

Integration GuidePrimeKey Enterprise Java Bean Certificate Authority (EJBCA)Ubuntu

Integration Guide: PrimeKey Enterprise Java Bean Certificate Authority (EJBCA)

Imprint

copyright 2015 Utimaco IS GmbHGermanusstrasse 4D-52080 AachenGermany

phone +49 (0)241 / 1696-200fax +49 (0)241 / 1696-199web http://hsm.utimaco.comemail [email protected] version 1.2.0date December 2015author System Engineering HSMdocument no. SGCS_IG_EJBCA

all rights reserved No part of this documentation may be reproduced in any form (printing, photocopyor according to any other process) without the written approval of Utimaco IS GmbHor be processed, reproduced or distributed using electronic systems.Utimaco IS GmbH reserves the right to modify or amend the documentation at anytime without prior notice. Utimaco IS GmbH assumes no liability for typographicalerrors and damages incurred due to them.All trademarks and registered trademarks are the property of their respective owners.

http://hsm.utimaco.com

mailto:[email protected]

Contents1 Introduction 4

2 Overview 4

3 Requirements 5

4 Components 6

4.1 Download and Install the JDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

4.2 Download and Install Apache Ant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

4.3 Download JBoss Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

4.4 Download EJCBA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

5 Installation of EJBCA 8

5.1 Setup the Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

5.2 EJBCA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

5.3 JBoss Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

5.4 PKCS#11 Token Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

5.5 Install EJBCA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

5.6 Setup PKCS#11 Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

6 Further Information 15


1 IntroductionThis article provides an integration guide for configuring EJBCA (Enterprise Java Bean Certification

Authority) with the CryptoServer (HSM) using the PKCS#11 R2 API. In the course of this guide it

is focused on the integration procedures necessary to run EJBCA with the CryptoServer. Further

information details to setup EJBCA as Certificate Authority can be found on EJBCA website.

2 OverviewPrimeKey Enterprise Java Bean Certificate Authority (EJBCA) is an open source application which is de-

signed tomanage the digital keys and certificates that make up the digital identities required to trans-

parently automate all security-related processes in an organization. As the organization’s CA system,

PrimeKey EJBCA Security Manager software enables the use of digital signatures, digital receipts, en-

cryption and permissions management services across a wide variety of applications and solutions.

To enhance security of keys and certificates generated and used by a CA, EJBCA can be configured to

use a Hardware Security Module (HSM). Enabling the use of a hardware security module with EJBCA

not only strengthens protection of keys and certificates but also might be a necessary step towards

legal conformity and certification.

CryptoServer is a hardware security module developed by Utimaco IS GmbH , i.e. a physically pro-

tected specialized computer unit designed to perform sensitive cryptographic tasks and to securely

manage and store cryptographic keys and data. It can be used as a universal, independent security

component for heterogeneous computer systems.

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

3 RequirementsYou should have prepared an installed Ubuntu operating system. If you are using a PCI(e) card you

also have to compile and install the necessary driver for that card.

Software- and Hardware Requirements

HSMModel CryptoServer CS-Series/S-Series/Se-Series LAN

CryptoServer Simulator

HSM Firmware SecurityServer 3.21.0

Software JBoss AS 7.1.1 Final

EJBCA 6.2.0 CE

Apache Ant 1.9.3

OpenJDK 1.7.0


4 ComponentsIn this section, we are going to describe how to install and configure all the components those are

necessary for setting up an EJBCA. When all the components are installed successfully, we move

forward to the actual EJBCA installation (section 5) and HSM configuration (section ??).

4.1 Download and Install the JDKThe JDK used in this guide was OpenJDK and One can install the JDK by using following command

in a terminal window.CONSOLE

# sudo apt-get install openjdk-7-jdk

4.2 Download and Install Apache AntApache Ant can be downloaded and installed by typing below command into a terminal window. The

version of Apache Ant which we used for the present integration guide is 1.9.3.CONSOLE

# sudo apt-get install ant ant-optional

4.3 Download JBoss Application ServerFor your reference, we used JBoss 7.1.1 Final as our application server in this guide. Download JBoss

fromJBoss and unzip the downloaded file to a directory of your choice. The path /opt/pki/ is our instal-

lation path which we will use throughout this guide. Let us assume that we installed the application

server under /opt/pki/jboss. When installation is done, create a user and group named as jboss with

a working directory /opt/pki/jboss.CONSOLE

# groupadd jboss

# useradd -d /opt/pki/jboss -g jboss jboss

# passwd jboss

If you use different installation path other than above path, then modify the path value whenever

needed according to your path.

http://sourceforge.net/projects/jboss/files/JBoss/

4.4 Download EJCBADownload EJBCA from EJBCA website and unzip it to the directory of your choice. In this article, we

used the path /opt/ejbca as our installation path.

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


5 Installation of EJBCAWe are going to install EJBCA with only a management Certificate Authority first. As next the con-

figuration extended to include PKCS#11 token in EJBCA. PKCS#11 token enables the usage of the

CryptoServer as key storage for further Certificate Authorities instances in EJBCA.

5.1 Setup the Environment VariablesTo run all installed tools properly, a series of environment variables has to be created first. Create a file

named as a ejbca.sh in /etc/profile.d and add these lines to this file. Always remember that provided

paths in this article depend on your installation and needs to be adjustedwhen your installation differs

from this article.

/etc/profile.d/ejbca.sh

#!/bin/sh

export JAVA_HOME=/usr/lib/jvm/java-7-openjdk-amd64

export JBOSS_HOME=/opt/jboss

export PATH=$JAVA_HOME/bin:$ANT_HOME/bin:$PATH

Once you are done editing the ejbca.sh file, save and close it. Copy the file ejbca.sh in the /etc/profile.d

directory. It will be executed whenever a bash login shell is entered.

5.2 EJBCAThis article installs EJBCAwithout an external database or other extra enabled features of EJBCA. Ba-

sically the file ejbca.properties needs to adjusted, so that EJBCA knows it’s run time environment

and operation mode. JBoss 7.1.1 Final application server is used here, so appserver.home and

appserver.type needs to be changed here. For test puproses only switch ejbca.productionmode to

false to indicate test mode.

/opt/ejbca/conf/ejbca.properties

...

# Application server home directory used during development. The path

# can not end with a slash or backslash.

# Default: $APPSRV_HOME

appserver.home=/opt/jboss

# See also the section ’cluster configuration’ for other JBoss options, for example

# for deploying on JBoss EAP.

# Which application server is used? Normally this is auto-detected from ’appserver.home’

# and should not be configured.

# Possible values: jboss, glassfish (, weblogic)

# Default: <auto-detect>

appserver.type=jboss

# To prevent accidental runs of tests or deploying the wrong thing in a production

# environment, we

# could prevent this by setting this variable to either ”true” or ”false”.

# Setting this value to ’false’ will allow system tests to alter the configuration

# of the running

# EJBCA instance.

# Default: true

#ejbca.productionmode=true

ejbca.productionmode=false

# Set to true to allow dynamic re-configuration using properties files in the file

# system. Using this you can place a file /etc/ejbca/conf/ocsp.properties in the file

# system and

# override default values compiled into ejbca.ear.

# Currently this works for most values in ejbca.properties, web.properties,

# cmp.properties, externalra-caservice.properties, ocsp.properties,

# extendedkeyusage.properties, jaxws.properties, xkms.properties

#

...

We also include support for PKCS#11 token and specifically the Utimaco PKCS#11 implementation.

Uncomment cryptotoken.p11.lib.31.name and cryptotoken.p11.lib.31.file parameter inweb.properties file.

Adjust cryptotoken.p11.lib.31.file parameter to your install location of libcs_pkcs11_R2.so including the

path. Make sure you have setup a PKCS#11 environment already.

/opt/ejbca/conf/web.properties

...

# Available PKCS#11 CryptoToken libraries and their display names

# If a library file’s presence is not detected it will not show up in the Admin GUI.

# Default values (see src/java/defaultvalues.properties for most up to date values):

cryptotoken.p11.lib.31.name=Utimaco

cryptotoken.p11.lib.31.file=/usr/lib/libcs_pkcs11_R2.so

...

5.3 JBoss Application ServerTo enable PKCS#11 token support for EJBCA, JBoss application server needs to be configured to allow

Sun PKCS#11 JCE provider to be included into JBoss classpath and accessible by EJBCA. Adjust the

modules.xml (modules/sun/jdk/main/modules.xml) file in JBoss modules path and add these lines

• <path name=”sun/security/x509″/>

• <path name=”sun/security/pkcs11″/>

• <path name=”sun/security/pkcs11/wrapper”/>

into paths section of XML structure.

modules/sun/jdk/main/modules.xml

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

...

<module xmlns=”urn:jboss:module:1.1” name=”sun.jdk”>

<resources>



<resource-root path=”service-loader-resources”/>

</resources>

<dependencies>

<system export=”true”>

<paths>

<path name=”sun/security/x509”/>

<path name=”sun/security/pkcs11”/>

<path name=”sun/security/pkcs11/wrapper”/>

<path name=”com/sun/script/javascript”/>

<path name=”com/sun/jndi/dns”/>

<path name=”com/sun/jndi/ldap”/>

<path name=”com/sun/jndi/url”/>

<path name=”com/sun/jndi/url/dns”/>

<path name=”com/sun/security/auth”/>

<path name=”com/sun/security/auth/login”/>

<path name=”com/sun/security/auth/module”/>

<path name=”sun/misc”/>

<path name=”sun/io”/>

<path name=”sun/nio”/>

<path name=”sun/nio/ch”/>

<path name=”sun/security”/>

<path name=”sun/security/krb5”/>

<path name=”sun/util”/>

<path name=”sun/util/calendar”/>

<path name=”sun/util/locale”/>

<path name=”sun/security/provider”/>

<path name=”META-INF/services”/>

</paths>

<exports>

<include-set>

<path name=”META-INF/services”/>

</include-set>


</exports>

</system>

</dependencies>

</module>

5.4 PKCS#11 Token KeysThe EJBCA requires some cryptographic keys to be installed before the PKCS#11 Token can be used.

For this article it is assumed that the PKCS#11 slot user has password user1. To generate the appro-

priate keys run the following commands using the p11tool2 for your PKCS#11 slot (e.g. slot one).CONSOLE

# ./p11tool2 Slot=1 LoginUser=user1 PubKeyAttr=CKA_LABEL=”signKey”,

CKA_ID=”signKey”, \

CKA_MODULUS_BITS=4096 \

PrvKeyAttr=CKA_LABEL=”signKey”,

CKA_ID=”signKey” \

GenerateKeyPair=RSA

# ./p11tool2 Slot=1 LoginUser=user1 PubKeyAttr=CKA_LABEL=”defauktKey”,

CKA_ID=”defauktKey”,CKA_MODULUS_BITS=2048 \

PrvKeyAttr=CKA_LABEL=”defauktKey”,

CKA_ID=defauktKey \

GenerateKeyPair=RSA

# ./p11tool2 Slot=1 LoginUser=user1 PubKeyAttr=CKA_LABEL=”testKey”,

CKA_ID=”testKey”,

CKA_MODULUS_BITS=1024 \

PrvKeyAttr=CKA_LABEL=”testKey”,

CKA_ID=”testKey” \

GenerateKeyPair=RSA

5.5 Install EJBCA• Start JBoss application server

CONSOLE

# /opt/jboss-as-7.1.1.Final/bin/standalone.sh

• Build and deploy EJBCA application

CONSOLE

# cd /opt/ejbca_ce_6_2_0

# ant deploy

Wait until EJBCA application has been deployed by JBoss application server

• Create initial Management CA and TLS keystores

CONSOLE

# ant install

• Restart JBoss application server. Press CTRL+C to shutdown JBoss application server

CONSOLE

# /opt/jboss-as-7.1.1.Final/bin/standalone.sh</li>

• Copy ejbca_6_0_3/p12/superadmin.p12 file to your admin desktop machine and import super-

admin.p12 in the certificate store of your web browser

• Open EJBCA application using the web browser with this URL https://your server ip:8443/ejbca

to check if installation was successful

5.6 Setup PKCS#11 TokenAfter EJBCA application has been deployed to JBoss application server and has been checked that

EJBCA application is accessible via web browser, there is only the management Certificate Authority

available at this moment. To create another Certificate Authority based on a PKCS#11 token you

need to create another crypto token in EJBCA. Follow the next steps to create a new crypto token.

• Connect to your EJBCA instance via web browser (e.g. https://your server ip:8443/ejbca)

• Authenticate with superadmin.p12 certificate


• Select Administration menu item Miscellaneous -> Administration

• Select Crypto Tokens menu item CA Functions -> Crypto Tokens

• Press create new...

• Enter name for the new crypto token (e.g. New CryptoToken)

• Select PKCS#11 token type

• Enter PKCS#11 user password for Authentication Code/Repeat Authentication Code

• Check Auto-activation

• Select Utimaco as PKCS#11 library

• Enter slot number for PKCS#11 Reference

• Press Save button to finish crypto token creation

The new crypto token now appears in the list of available crypto tokens. Switch now to CA Functions ->

Certification Authorities to create a newCertificate Authority. When creating a newCertificate Authority

select the new crypto token based on PKCS#11. For further details on how to setup a Certificate

Authority we refer to the user manual of EJBCA.

http://www.ejbca.org/docs/userguide.html

6 Further InformationThis document forms a part of the information and support which is provided by the Utimaco IS

GmbH . Additional documentation can be found on the product CD in the documentation directory.

All CryptoServer product documentation is also available at theUtimaco ISGmbH website: http://hsm.utimaco.com

http://hsm.utimaco.com

Contact

Utimaco IS GmbHGermanusstraße 4D - 52080 AachenGermany

phone +49 241 1696 - 200fax +49 241 1696 - 199

web https://hsm.utimaco.comemail [email protected]

https://hsm.utimaco.com

mailto:[email protected]

primekey enterprise java bean certificate authority (ejbca) ·...

Documents