nCipher Modules

Integration Guide for Red Hat Certificate System

8.0

www.thalesgroup.com/iss

Version:

1.0

Date:

6 September 2011

Copyright 2011 Thales e-Security Limited. All rights reserved.

Version:

1.0

Date:

06 September 2011

2011

nCipher Modules: Integration Guide for Red Hat Certificate System 8.0 1.0

nShiNov10

Copyright in this document is the property of Thales e-Security Limited. It is not to be reproduced, modified,
adapted, published, translated in any material form (including storage in any medium by electronic means
whether or not transiently or incidentally) in whole or in part nor disclosed to any third party without the prior
written permission of Thales e-Security Limited neither shall it be used otherwise than for the purpose for which
it is supplied.
CodeSafe, KeySafe, nCipher, nFast, nForce, nShield, payShield, and Ultrasign are registered trademarks of
Thales e-Security Limited.
CipherTools, CryptoStor, CryptoStor Tape, keyAuthority, KeyVault, nCore, netHSM, nFast Ultra, nForce Ultra,
nShield Connect, nToken, SafeBuilder, SEE, and Trust Appliance are trademarks of Thales e-Security Limited.
All other trademarks are the property of the respective trademark holders.
Information in this document is subject to change without notice.
Thales e-Security Limited makes no warranty of any kind with regard to this information, including, but not limited
to, the implied warranties of merchantability and fitness for a particular purpose. Thales e-Security Limited shall
not be liable for errors contained herein or for incidental or consequential damages concerned with the
furnishing, performance or use of this material.
These installation instructions are intended to provide step-by-step instructions for installing Thales software
with third-party software. These instructions do not cover all situations and are intended as a supplement to the
documentation provided with Thales products. Disclaimer: Thales e-Security Limited disclaims all liabilities
regarding third-party products and only provides warranties and liabilities with its own products as addressed
in the Terms and Conditions for Sale.

Contents

Chapter 1:

Chapter 2:

Introduction

Supported nCipher functionality

Requirements

Procedures

Installing the HSM

Installing the support software and creating the Security World

Installing and configuring Red Hat Certificate System 8.0

Installing and configuring the Red Hat Directory Server 8.1

Installing and configuring the Red Hat Certificate System 8.0

Chapter 3:

Troubleshooting

Addresses

nCipher Modules: Integration Guide for Red Hat Certificate System 8.0 1.0

8
10

16
18

Chapter 1: Introduction

Red Hat Certificate System provides a powerful security framework to manage user identities and
ensure privacy of communications. Handling all the major functions of the identity life cycle, Red
Hat Certificate System simplifies enterprise-wide deployment and adoption of a Public Key
Infrastructure.
Red Hat Certificate System works behind the scenes to issue, renew, suspend, revoke, and
manage single and dual key X.509v3 certificates needed to handle strong authentication, single
sign-on, and secure communications. Support for Global Platform permits direct communication
between a registration authority and a smart card for key management tasks such as enrollment
and PIN reset.
This guide explains how to set up and configure a Red Hat Certificate System 8.0 installation with
Thales nCipher Hardware Security Modules (HSMs). The instructions in this document have
been thoroughly tested and provide a straightforward method for integrating the Thales nCipher
HSM with Red Hat Certificate System. There may be other untested ways to achieve
interoperability.
This guide might not cover every step in the process of setting up all software. For more detail
about installing Red Hat Certificate System, see the Red Hat Certificate System documentation
supplied on CD-ROM/DVD-ROM. Some packages require that other packages already be
configured, initialized, and running before they can be installed successfully.
The integration between the HSM and Red Hat Certificate System uses the PKCS #11
cryptographic API. The integration has been successfully tested in the following configuration.
Operating system

Red Hat Enterprise Linux 5.6 Linux

x86_64

Red Hat
Thales
Certificate nCipher
System
version
8.0

11.50

nShield Solo netHSM

support
support

nShield
Connect
support

Yes

Yes

For more information about OS support, contact your Red Hat sales representative, or Support at
Thales nCipher. For more information about contacting Thales nCipher, see the contact
information in the Addresses section at the end of this guide.

nCipher Modules: Integration Guide for Red Hat Certificate System 8.0 1.0

Supported nCipher functionality

Additional documentation produced to support your Thales nCipher product can be found in the
document directory of the CD-ROM or DVD-ROM for that product.
Note

Throughout this guide, the term HSM refers to nShield Solo, nShield Connect, and netHSM
products. (nShield Solo products were formerly known as nShield.)

Supported nCipher functionality

Key Generation

Yes

1-of-N Operator Card Set

Yes

Strict FIPS Support

Yes

Key Management

Yes

K-of-N Operator Card Set

Load Sharing

Yes

Key Import

Softcards

Yes

Fail Over

Yes

Key Recovery

Module-only Key

Requirements
To integrate the HSM and Red Hat Certificate System, you need the server and client machines
to be setup as follows:
Hardware

Software

Server

Red Hat Enterprise Linux 5.6

Thales nCipher support software

11.50
Red Hat Certificate System 8.0
Red Hat Directory Server 8.1

Client

Windows Operating System (Tested with Windows

Server 2003)

Firefox 3.15.0 or latest

We also recommend that there be an agreed organizational Certificate Practices Statement and
Security Policy/Procedure in place covering administration of the HSM. In particular, these
documents should specify the following aspects of HSM administration:

The number and quorum of Administrator Cards in the Administrator Card Set (ACS), and
the policy for managing these cards.

Whether the application keys are to be protected by Softcard or Operator Card Set (OCS).

The number and quorum of Operator Cards in the OCS (only 1-of-N is supported), and the
policy for managing these cards.

Whether the security world should be compliant with FIPS 140-2 level 3.

For more information, see the User Guide for the HSM.

nCipher Modules: Integration Guide for Red Hat Certificate System 8.0 1.0

Chapter 2: Procedures

To integrate Red Hat Certificate System 8.0 with an HSM on Red Hat Enterprise Linux 5.6
x86_64 bit operating system:
1

Install the HSM.

2 Install the nShield support software, and then create the Security World.
3

Install and configure Red Hat Certificate System 8.0.

These procedures are described in the following sections.

Installing the HSM

Install the HSM using the instructions in the documentation for the HSM. We recommend that
you install the HSM before configuring the nCipher software.

Installing the support software and creating the Security

World
To install the Thales nCipher support software and create the Security World:
1

Install the latest version of the support software and create a Security World as described in
the User Guide for the HSM.
Note

We recommend that you uninstall any existing Thales nCipher software before installing the
new software.

nCipher Modules: Integration Guide for Red Hat Certificate System 8.0 1.0

Installing and configuring Red Hat Certificate System 8.0

Configure environment variables in the cknfastrc file:

a

Create a file called cknfastrc in the directory where the nShield support software is
installed. The default directory is /opt/nfast.

For OCS and Softcard protection, add the following environment variables to the file:

CKNFAST_NO_ACCELERATOR_SLOTS=1
CKNFAST_LOADSHARING=1
CKNFAST_OVERRIDE_SECURITY_ASSURANCES=tokenkeys
CKNFAST_NO_UNWRAP=1

For more information, see the PKCS #11 library environment variables in the User Guide for the
HSM.

Installing and configuring Red Hat Certificate System 8.0

Red Hat Certificate System is a highly configurable set of components which create and manage
certificates and keys at every point of the certificate lifecycle.
The core of the Certificate System is the Certificate Manager. This is the only required
subsystem, and it handles the actual certificate management tasks. The other subsystems can be
added for extra functionality.
The Certificate Authority (CA) is a subsystem used to manage certificates, keys, and CRLs
through every step of the cycle of a certificate. Before installing the CA, check the requirements
and dependencies for the specific platform, and check which packages are installed. Before
proceeding further, see the Red Hat Certificate System Installation Guide, Install_Guide.pdf.
This section describes how to quickly set up and configure Red Hat Certificate System 8.0 on
Red Hat Enterprise Linux 5.6 x86_64 bit platform:
1

Check that Java -1.6.0-openjdk is installed:

[root@hostname ~]# yum info java-1.6.0-openjdk

If not, use the following command to install it:

[root@hostname ~]# yum install java-1.6.0-openjdk

nCipher Modules: Integration Guide for Red Hat Certificate System 8.0 1.0

Installing and configuring Red Hat Certificate System 8.0

2 Check that pki-selinux is installed:

[root@hostname ~]# yum info pki-selinux

If not, use the following command to install it:

[root@hostname ~]# yum install pki-selinux

3 Check that httpd is installed:

[root@hostname ~]# yum info httpd

If not, use the following command to install it:

[root@hostname ~]# yum install httpd

Check the status of SELinux as follows:

[root@hostname ~]# sestatus

This command should produce the following output:

SELinux status: disabled

In the file /etc/selinux/config, change the SELinux status to Permissive.

Restart the machine when the file is edited.

Installing and configuring the Red Hat Directory Server 8.1

1

All subsystems require access to Red Hat Directory Server 8.1 on the local machine or a
remote machine. This Directory Server instance is used by the subsystems to store their
system certificates and user data. The Directory Server used by the Certificate System
subsystems can be installed on Red Hat Enterprise Linux 5.6 x86_64-bit. Check that the Red
Hat Directory Server is already installed. For example:

[root@hostname bin]# yum info redhat-ds

If the redhat-ds is not installed, download the redhat-ds iso file from the Red Hat Network
channel, and then perform the following steps.

nCipher Modules: Integration Guide for Red Hat Certificate System 8.0 1.0

Installing and configuring Red Hat Certificate System 8.0

3 Create a folder called disk in /mnt.

4

Create a folder called localrepo in /opt.

Mount the package rhel-dirserv-8.1-x86_64-disc1.iso:

[root@hostname home]# mount -o loop rhel-dirserv-8.1-x86_64-disc1.iso /mnt/disk

6 Copy the folder RPMS into /opt/localrepo/:

[root@hostname RedHat]# cp -rf RPMS/ /opt/localrepo

Backup the folder repodata in /opt/localrepo/RPMS as follows:

[root@hostname RPMS]# cp -rf repodata/ /tmp/

To create the yum local repository, edit the yum.conf in /etc as follows:

[root@hostname etc]# vi yum.conf

[main]
cachedir=/var/cache/yum
keepcache=0
debuglevel=2
logfile=/var/log/yum.log
distroverpkg=redhat-release
tolerant=1
exactarch=1
obsoletes=1
gpgcheck=1
plugins=1
# Note: yum-RHN-plugin doesn't honor this.
metadata_expire=1h
[localrepo]
name=RHEL 5 $releasever - $basearch
baseurl=file:///opt/localrepo/RPMS
enabled=1
# Default.
# installonly_limit = 3
# PUT YOUR REPOS HERE OR IN separate files named file.repo
# in /etc/yum.repos.d

To create the yum local repository, use the following command:

[root@hostname RPMS]# createrepo /opt/localrepo/RPMS/

11/11 - adminutil-1.1.8-2.el5dsrv.x86_64.rpm

nCipher Modules: Integration Guide for Red Hat Certificate System 8.0 1.0

Installing and configuring Red Hat Certificate System 8.0

10 To install Red Hat Directory Server, use the following command:

[root@hostname RPMS]#yum install redhat-ds-8.1.0-1.el5dsrv.x86_64.rpm

11 To configure the Red Hat Directory Server, use the following commands:
root@hostname RPMS]# cd /usr/sbin
[root@hostname sbin]# ./setup-ds-admin.pl

12 When prompted:
a

Continue with the setup.

Agree to the license terms.

Continue with the setup.

Select Express as the setup type.

Do not register the software with an existing configuration directory server.

Enter a password for administrator ID.

Enter a password for Directory Manager DN.

Continue with setting up your servers.

Installing and configuring the Red Hat Certificate System 8.0

1

The individual subsystems for Red Hat Certificate System are installed and then configured
individually. The initial installation is done using package management tools such as RPM.
The subsystem setup is done using an HTML-based configuration wizard. Download the
Certificate System packages from the Red Hat Network channel. For installing Red Hat
Certificate system 8.0, create a folder called localrepo1 in /opt.

Mount the Red Hat Certificate system 8.0 package RHEL5.3-RHCertSystem-8.0-x86_64disc1-ftp.iso, and then copy the folder RPMS into /opt/localrepo1:

[root@hostname etc]# mount -o loop RHEL5.3-RHCertSystem-8.0-x86_64-disc1-ftp.iso /mnt/disk/

[root@hostname etc]# cd /mnt/disk/RedHat/
[root@hostname RedHat]# cp -rf RPMS/ /opt/localrepo1

nCipher Modules: Integration Guide for Red Hat Certificate System 8.0 1.0

10

Installing and configuring Red Hat Certificate System 8.0

To create the yum local repository, edit the yum.conf in /etc as follows:

[root@hostname etc]# vi yum.conf

[main]
cachedir=/var/cache/yum
keepcache=0
debuglevel=2
logfile=/var/log/yum.log
distroverpkg=redhat-release
tolerant=1
exactarch=1
obsoletes=1
gpgcheck=1
plugins=1
# Note: yum-RHN-plugin doesn't honor this.
metadata_expire=1h
[localrepo]
name=RHEL 5 $releasever - $basearch
baseurl=file:///opt/localrepo1/RPMS
enabled=1
# Default.
# installonly_limit = 3
# PUT YOUR REPOS HERE OR IN separate files named file.repo
# in /etc/yum.repos.d

Back up the repodata in /opt/localrepo1/RPMS as follows:

[root@hostname RPMS]# cp -rf repodata/ /tmp/

Use the following command to create the yum local repository:

[root@hostname RPMS]# createrepo /opt/localrepo1/RPMS/

38/38 - pki-util-javadoc-8.0.0-16.el5pki.noarch.rpm

nCipher Modules: Integration Guide for Red Hat Certificate System 8.0 1.0

11

Installing and configuring Red Hat Certificate System 8.0

6 To install pki-ca:
[root@hostname RPMS]# yum install pki-ca-8.0.0-21.el5pki.noarch.rpm

Note

Interoperating subsystems within Red Hat Certificate System carry out all common PKI
operations, such as:

Issuing, renewing, and revoking certificates.

Archiving and recovering keys.

Publishing CRLs.

Verifying certificate status.

The CA is a subsystem that manages certificates at every stage, from requests through to
enrollment. The CA also publishes certificates and lists of revoked certificates for use by
clients such as the OCSP or web servers. The CA is the core of the PKI, and issues and
revokes all certificates. The CA is also the core of the Certificate System.

Check the status:

[root@hostname bin]# service pki-ca status

pki-ca (pid 3967) is running ...
'pki-ca' must still be CONFIGURED!
(see /var/log/pki-ca-install.log)

Verify the nfast entry CS.cfg file in /etc/pki-ca:

---preop.configModules.module1.userFriendlyName=Thales nCipher's nFast Token Hardware Module

preop.configModules.module1.commonName=nfast
preop.configModules.module1.imagePath=../img/clearpixel.gif
----

nCipher Modules: Integration Guide for Red Hat Certificate System 8.0 1.0

12

Installing and configuring Red Hat Certificate System 8.0

Run the following command in /var/lib/pki-ca/alias/ to add the Thales nCipher module:

[root@hostname alias]# modutil -dbdir . -nocertdb -add nethsm libfile

/opt/nfast/toolkits/pkcs11/libcknfast.so

Note

For 64-bit environments, run the following command:

[root@hostname alias]# modutil -dbdir . -nocertdb -add nethsm

/opt/nfast/toolkits/pkcs11/libcknfast-64.so

-libfile

10 To list the added module, run the following command:

[root@hostname alias]# modutil -dbdir . -nocertdb list
Listing of PKCS #11 Modules
----------------------------------------------------------1. NSS Internal PKCS #11 Module
slots: 2 slots attached
status: loaded
slot: NSS Internal Cryptographic Services
token: NSS Generic Crypto Services
slot: NSS User Private Key and Certificate Services
token: NSS Certificate DB
2. nfast
library name: /opt/nfast/toolkits/pkcs11/libcknfast.so
slots: 1 slot attached
status: loaded
slot: DD16-DA9E-D5AD #1 nFast PCI device, bus 1, slot 1. slot 0
token: ocs
-----------------------------------------------------------

Note

The output shown above is displayed when OCS protection is used.

11 SE Linux policies are created and configured automatically to enable Certificate System
instances to run with SE Linux in enforcing or permissive modes. In enforcing mode, any
hardware tokens that use the Certificate System instances must also be configured to run with
SE Linux in enforcing mode, otherwise the HSM will not be available during subsystem
installation. Before installing any Certificate System instances, run the following command
to reset the context of files in /dev/nfast to match the newly-installed policy:
[root@hostname alias]#/sbin/restorecon -R /dev/nfast

nCipher Modules: Integration Guide for Red Hat Certificate System 8.0 1.0

13

Installing and configuring Red Hat Certificate System 8.0

12 Run the following command to view the Tokeninfo:

[root@hostname
Database Path:
Found external
Found external
Found external
[root@hostname

Note

alias]# TokenInfo /var/lib/pki-ca/alias/

/var/lib/pki-ca/alias/
module 'NSS Internal PKCS #11 Module'
module 'nfast'
token 'ocs'
alias]#

The output shown above is displayed when OCS protection is used.

13 Before creating the Security Domain, add pkiuser in /etc/group:

--nfast:x:106:pkiuser
---

14 To allow access for the Thales nCipher library, run the following commands:
[root@hostnamehome]# chcon -t bin_t '/opt/nfast/toolkits/pkcs11/libcknfast.so'
[root@hostname home]# semanage fcontext -a -t bin_t '/opt/nfast/toolkits/pkcs11/libcknfast.so'

Note

For 64-bit environments, run the following commands:

[root@hostnamehome]# chcon -t bin_t '/opt/nfast/toolkits/pkcs11/libcknfast-64.so'

[root@hostname home]# semanage fcontext -a -t bin_t '/opt/nfast/toolkits/pkcs11/libcknfast-64.so'

15 Open
https://hostname:9445/ca/admin/console/config/login?pin=xxxxxxxxxxxxxxxxxxxxxxxx. A
similar URL can found in /var/log/pki-ca-install.log.
16 In the Create a Security Domain panel, enter Red Hat Security as Security Domain Name.
17 In the Sub System Type panel, select Configure this instance as a New CA Subsystem, and then
select Certificate Authority as the Subsystem name.
18 In the PKI Hierarchy panel, select Make this Selfsigned Root CA.
19 In the Internal Database panel, fill in the correct LDAP server information.
20 In the Key Store panel, select Thales nCipher Hardware as the default login.

nCipher Modules: Integration Guide for Red Hat Certificate System 8.0 1.0

14

Installing and configuring Red Hat Certificate System 8.0

21 In the Key Pairs panel, select Use the following custom key Size. Select RSA as the key type,
and then enter the key size, for example 1024, 2048, or 4096.
22 In the Subject Name panel, select Next.
23 In the Requests and Certificates panel, select Apply, and then select Next.
24 In the Administrator panel, enter the correct details.
25 Click Next through the remaining panels to import the agent certificate into the browser and
complete the configuration.
26 When configuration is complete, run the following command to restart the subsystem:
# service pki-ca restart

If the configuration is successful, this command generates the following output:

[root@hostname RPMS]# /sbin/service pki-ca restart
Stopping pki-ca: ...............................
[ OK ]
Starting pki-ca:
[ OK ]
pki-ca (pid 5946) is running ...
Unsecure Port
= http://hostname:9180/ca/ee/ca
Secure Agent Port = https://hostname:9443/ca/agent/ca
Secure EE Port
= https://hostname:9444/ca/ee/ca
Secure Admin Port = https://hostname:9445/ca/services
PKI Console Port = pkiconsole https://hostname:9445/ca
Tomcat Port
= 9701 (for shutdown)
PKI Instance Name:
pki-ca
PKI Subsystem Type: Root CA (Security Domain)
Registered PKI Security Domain Information:
====================================================================
Name: Red Hat Security
URL:
https://hostname:9445
===================================================================

nCipher Modules: Integration Guide for Red Hat Certificate System 8.0 1.0

15

Chapter 3: Troubleshooting

The following tables provide troubleshooting guidelines.

Problem

Bind error in Internal Database panel.

Cause

Password might be incorrect, or an entry in /etc/pki-ca/CS.cfg file is not present.

Resolution

Recheck the Directory Server password, and check if the following variable is present in
/etc/pki-ca/CS.cfg: preop.configModules.module1.commonName=nfast.

Problem

Key generation failure in Key Pairs panel.

Cause

The variable CKNFAST_OVERRIDE_SECURITY_ASSURANCES=tokenkeys is not present in the

cknfastrc file, and user pkiuser is not a member of the nfast group.

Resolution

1
2

Check in the cknfastrc file if the following variable is present:

CKNFAST_OVERRIDE_SECURITY_ASSURANCES=tokenkeys
Add pkiuser in /etc/groups/ as follows:

nfast:x:106:pkiuser

Problem

When trying to open https://hostname:9443/ca/services, the following error message

appears:

Error message - ssl_error_bad_cert_alert

When trying to open

https://hostname:9445/ca/admin/console/config/login?pin=xxxxxxxxxxxxxxxxxxxx, the

following error message appears:

Error Message - sec_error_reused_issuer_and_serial

Cause

There are old certificates in the browser certificate store.

Resolution

In the Firefox browser:

1 Navigate to Tools > Options > Encryption > View certificate.
2 Delete the following old certificates from Certificate stores:
Your certificate.
People.
Server.
Authorities.
Others.

nCipher Modules: Integration Guide for Red Hat Certificate System 8.0 1.0

16

Troubleshooting

Problem

The Certificate System CA Error Page appears when trying to open

https://hostname:9443/ca/services.

Cause

Thales nCipher hardware is not listed in Modutil list.

Resolution

Go to /var/lib/pki-ca/alias/ and run the following commands:

modutil -dbdir . -nocertdb -add nethsm -libfile /opt/nfast/toolkits/pkcs11/libcknfast.so
modutil -dbdir . -nocertdb list

For 64-bit environments, run the following commands:

modutil -dbdir . -nocertdb -add nethsm -libfile /opt/nfast/toolkits/pkcs11/libcknfast-64.so
modutil -dbdir . -nocertdb list

In the list that appears, the method of key protection is shown, for example Softcard or OCS.

Problem

The following error message appears in the Administrator panel:

java.lang.NullPointerException

Cause

Internet explorer is preventing java authentication.

Resolution

Use the latest version of the Firefox browser.

Problem

The following error message appears:

The error 800704c7 occurred. The credentials could not be generated IE browser
at administrator panel

Cause

Internet explorer is preventing java authentication.

Resolution

Use the latest version of the Firefox browser.

nCipher Modules: Integration Guide for Red Hat Certificate System 8.0 1.0

17

Addresses

Americas
2200 North Commerce Parkway, Suite 200, Weston, Florida 33326, USA
Tel: +1 888 744 4976 or + 1 954 888 6200
sales@thalesesec.com

Europe, Middle East, Africa

Meadow View House, Long Crendon, Aylesbury, Buckinghamshire HP18 9EQ, UK
Tel: + 44 (0)1844 201800
emea.sales@thales-esecurity.com

Asia Pacific
Units 4101, 41/F. 248 Queens Road East, Wanchai, Hong Kong, PRC
Tel: + 852 2815 8633
asia.sales@thales-esecurity.com

Internet addresses
Web site:
Support:
Online documentation:
International sales offices:

www.thalesgroup.com/iss
http://iss.thalesgroup.com/en/Support.aspx
http://iss.thalesgroup.com/Resources.aspx
http://iss.thalesgroup.com/en/Company/Contact%20Us.aspx