Introduction

HSM and Client Setup

HSM Client Software Setup

Build and install the safenet patched openssl into /usr/local/openssl-0.9.8e-safenet

Build and install the safenet sautil into /usr/lunasa/bin (64 bit client only)

Install the safenet sautil into /usr/lunasa/bin (32 bit client only)

Configure the Safenet client software

HSM Initialization and Initial Setup

Setup client network table entries for HSM communication

Setup the HSM administrator password

Set the HSM timezone date and time

Set the HSM network addresss and mask

Set the HSM hostname

Initialize the HSM and the Administrator and Domain PED keys

Generate the new HSM server certificate and private key

Setup the LunaSA HSM partition keys and access

Activate the HSM partition

Download the HSM server certificate and make and upload a client access certificate

Register the client with the HSM and assign accesses to our newly created partition

HSM Key Generation and Archiving

Netbook preparation

Fedora Core 12 Live USB key preparation

Boot the Netbook using the Live USB Key

Install the Safenet Software in the Netbook

Configure the Netbook network

Clear out any previous HSM partition data

Download the HSM server certificate and make and upload a client access certificate

Register the client with the HSM and assign accesses to our newly created partition

Generate the key pairs on the netbook client

Import the key pairs into the HSM

Save the Encrypted Private keys and the keyfiles on both USB sticks and on 2 CDROMS

Boot the Netbook into Windoze to clear out any dynamic RAM memory traces

Backup HSM Partition Contents to a Luna HSM Backup Token

Backup the partition contents to the backup token

Create a Limited Capabilities Partiton User

Configure NTP

Useful HSM commands

Restore an HSM (or initialize a second fallback HSM) with backed up partition data

Restore an unknown administrator password

Restore an HSM to factory default settings (except for the network)

Initialize the HSM

Set the HSM network addresss and mask

Clear out all objects in a partition

Display the contents of a "key" access file

List all objects in a partition

Reset the client "connection" configuration

Show HSM information including listing all partitions

Test the HSM private key usage

Re-Activate the HSM partition after a 2 hour power failure

Copy SupportInfo and Syslogs off HSM

Introduction

The Cilogon project needed a pair of redundant Certificate Authority (CA) servers with the private keys kept as protected as possible. Drawing upon experience in another project, we decided to keep the private keys within a pair of redundant network attached Hardware Security Modules (HSMs) that would also allow cryptographic operations using the keys to be done inside the HSMs, never allowing the private keys to reside on the CA servers.

The Luna SA HSM from Safenet is, in their own words, an "Ethernet-attached Hardware Security Module (HSM) ... offering hardware key management and cryptographic acceleration". After evaluating this and offerings from other vendors, we chose this unit for its ability to let Linux based client systems perform cryptographic private/public key operations using a modified openssl command, while keeping the private keys safe in the HSM unit and never needing to have the private keys resident on the client systems. All cryptographic operations using the private keys are performed inside the HSM, with results returned to the client system and made available through the modified openssl command on the client.

Normally, the HSM unit is set up by having the HSM unit generate its own set of private keys internally, without ever allowing them to be exported outside the HSM except in an encrypted form known only to the HSM manufacturer that only another similar HSM unit can understand and import for redundancy.  In our case, not to be tied to the HSM vendor forever, and to allow for emergency Certificate Authority operations in the event of HSM failures, we generated the private keys outside the HSM units on a one-time dedicated computer, imported them into our pair of HSM units, and then stored the private keys with a separate passcode on various non-volatile media (including paper printouts) in one safe, with the keys passcode stored in another safe.

The first section HSM Client Software Setup details the software changes necessary on our CA servers to use the HSM network units.

After that, the HSM Initialization and Initial Setup section covers initializing the HSM and readying it for importing of the private keys.

Then, the HSM Key Generation and Archiving section details generating private keys on a dedicated netbook computer, importing them into the HSM, and then archiving the private  keys.

For further information or if you have any questions, contact Jim Basney at jbasney@illinois.edu.

See also the manual on falco.ncsa.uiuc.edu:~jbasney/LunaSADocs or on marco1.cites.illinois.edu:/root/safenet . Open the file START_HERE.html with any web browser (e.g. firefox).

HSM and Client Setup

HSM Client Software Setup

First we had to install the Safenet LunaSA Software and Utilities. We combined the software that came with the HSMs on CDROM, with some updated versions of a few critical software components provided by Safenet through the web. 

Copy the Safenet software into /root/safenet, or if using a later provided version unpack the supplied LunaSA software tarball into /root/safenet:

# cd /root

# mkdir safenet

# cp -pr /media/610036-041MI/linux safenet/

# cp -pr /media/610036-041MI/source safenet/

# cd safenet/linux/64

# ./install.sh

...

Do you agree to the License contained in the product packaging?

...

(y/n) y

...

Would you like to install the Luna JSP for Luna SA? (y/n)

y

...

Would you like to install the SDK for Luna SA? (y/n)

y

...

Build and install the safenet patched openssl into /usr/local/openssl-0.9.8e-safenet

While it may be possible to use a standard distribution openssl at a later time, currently a patched version from Safenet needs to be used.

# cd /root/safenet/source/apache

# tar xpzf openssl-0.9.8e.tar.gz

# cd openssl-0.9.8e

# ./config --prefix=/usr/local/openssl-0.9.8e-safenet shared

...

# make

...

# make test

...

# make install

...

# cp -p linux/sautil /usr/lunasa/bin

#

Since the LunaCA3 openssl engine has the engine identifier "LunaCA3", and the openssl installs that loadable engine with the name "lunaca3", make a symbolic file link so that it works to specify the engine:

# cd /usr/local/openssl-0.9.8e-safenet/lib/engines

# ln -s liblunaca3.so libLunaCA3.so

#

Make sure that openssl now includes the safenet engine:

# /usr/local/openssl-safenet/bin/openssl/openssl engine LunaCA3 -v

(LunaCA3) Luna CA3 engine support

enginearg, openSession, closeSession, login, logout, engineinit,

CONF_PATH, ENGINE_INIT

#

Build and install the safenet sautil into /usr/lunasa/bin (64 bit client only)

Since the sautil utility that was supplied then as part of the Safenet software won't run on a 64 bit system because of library incompatibilities, obtain the latest sautil.zip source from Safenet and put it into /root/safenet.

# cd /root/safenet

# unzip sautil.zip

...

# cd sautil

# make

...

# mv /usr/local/sautil/bin/sautil /usr/lunasa/bin/

#

Install the safenet sautil into /usr/lunasa/bin (32 bit client only)

# cp -p /root/safenet/source/apache/linux/sautil /usr/lunasa/bin/

#

Configure the Safenet client software

Add or verify these lines in the /etc/Chrystoki.conf file (note the 64 references in bold, if on a 64 bit processor these need to be in):

Chrystoki2 = {

   LibUNIX64=/usr/lib/libCryptoki2_64.so;

}

Misc = {

AppIdMajor=10;

AppIdMinor=11;

Apache=1;

}

EngineLunaCA3 = {

LibPath64=/usr/lib/libCryptoki2_64.so;

EngineInit=1:10:11;

}

LunaSA Client = {

ClientPrivKeyFile = /usr/lunasa/cert/client/HSM_PRIVATE_NETWORK_IP_ADDRESSKey.pem;

ClientCertFile = /usr/lunasa/cert/client/HSM_PRIVATE_NETWORK_IP_ADDRESS.pem;

ServerPort00 = 1792;

ServerName00 = HSM_PRIVATE_NETWORK_IP_ADDRESS;

NetClient=1;

ServerCAFile=/usr/lunasa/cert/server/server.pem;

SSLConfigFile=/usr/lunasa/bin/openssl.cnf;

ReceiveTimeout=20000;

}

HSM Initialization and Initial Setup

Setup client network table entries for HSM communication

In the client /etc/hosts files, add these lines so that the client and the HSM can talk to each other on the private network:

HSM_PRIVATE_NETWORK_IP_ADDRESS         HSM_PRIVATE_NETWORK_SHORT_NAME

HOST_PRIVATE_NETWORK_IP_ADDRESS        HOST_PRIVATE_NETWORK_FQDN

Setup the HSM administrator password

The first time you log into a fresh HSM, the admin password must be initialized:

# ssh admin@HSM_PRIVATE_NETWORK_IP_ADDRESS

...

*****************************************************

**                                                 **

**   For security purposes, you must change your   **

**   admin password.                               **

**                                                 **

**   Please ensure you store your new admin        **

**   password in a secure location.                **

**                                                 **

**               DO NOT LOSE IT!                   **

**                                                 **

*****************************************************

...

Changing password for user admin

New UNIX password: HSM_ADMIN_PASSWORD

Retype new UNIX password: HSM_ADMIN_PASSWORD

passwd: all authentication tokens updated successfully

Password change successful.

[DEFAULTHOSTNAME] lunash:>

Set the HSM timezone date and time

The HSM certificate that is used for communication depends on this.

[DEFAULTHOSTNAME] lunash:>sysconf -timezone -set US/Central  

Timezone set to US/Central

Command Result : 0 (Success)

[DEFAULTHOSTNAME] lunash:>sysconf -time HH:MM YYYYMMDD

Tue Apr 20 14:04:00 CDT 2010

Command Result : 0 (Success)

[DEFAULTHOSTNAME] lunash:>status date

Tue Apr 20 14:04:06 CDT 2010

Command Result : 0 (Success)

[DEFAULTHOSTNAME] lunash:>

Set the HSM network addresss and mask

[DEFAULTHOSTNAME] lunash:>network interface static -d eth0 -ip HSM_PRIVATE_NETWORK_IP_ADDRESS -n PRIVATE_NETWORK_NETMASK

NOTICE: The network service must be restarted for new network settings to take e

ffect.

If you are sure that you wish to restart the network, then type 'proceed', other

wise type 'quit'

> proceed

Proceeding...

Restarting network service...

Shutting down loopback interface:  [  OK  ]

Setting network parameters:  [  OK  ]

Bringing up loopback interface:  [  OK  ]

Bringing up interface eth0:  [  OK  ]

Command Result : 0 (Success)

[DEFAULTHOSTNAME] lunash:>network show

   Hostname:          DEFAULTHOSTNAME

   Domain:            <not set>

   IP Address (eth0): HSM_PRIVATE_NETWORK_IP_ADDRESS

   HW Address (eth0): 00:00:50:58:73:C7

   Mask (eth0):       PRIVATE_NETWORK_NETMASK

   Gateway (eth0):    0.0.0.0

   Name Servers:      <not set>

   Search Domain(s):

Kernel IP routing table

Destination     Gateway         Genmask         Flags Metric Ref    Use Iface

HSM_PRIVATE_NETWORK_IP_ADDRESS  0.0.0.0  PRIVATE_NETWORK_NETMASK   U     0      0        0 eth0

127.0.0.0                 0.0.0.0    255.0.0.0             U     0      0        0 lo

Link status

eth0: no link

eth1: no link

Command Result : 0 (Success)

[DEFAULTHOSTNAME] lunash:>

Set the HSM hostname

[DEFAULTHOSTNAME] lunash:>net hostname HSM_PRIVATE_NETWORK_SHORT_NAME

Success: Hostname hsm set.

Command Result : 0 (Success)

[HSM_PRIVATE_NETWORK_SHORT_NAME] lunash:

Initialize the HSM and the Administrator and Domain PED keys

[HSM_PRIVATE_NETWORK_SHORT_NAME] lunash:>hsm init -label hsm

CAUTION:  Are you sure you wish to re-initialize this HSM?

          All partitions and data will be erased.

          Type 'proceed' to initialize the HSM, or 'quit'

          to quit now.

          > proceed

Luna PED operation required to initialize HSM - use Default (gray) and Security Officer (blue) PED keys, please note that the gray key is not required if using a PED 2.

At this point the PED unit displays:

Insert a SO / HSM Admin PED Key

Press ENTER.

Find an already labelled, or label a new, Safenet PED key (USB stick) with the "BLUE SO/HSM ADMIN" label and insert it into the PED unit. Press <ENTER>.

Follow the PED unit directions, and (re)label two BLUE SO/HSM ADMIN keys, and two RED DOMAIN keys.

...

Luna PED operation required to login as HSM Administrator - use Security Officer (blue) PED key.

...

Luna PED operation required to generate cloning domain - use Domain (red) PED key.

...

'hsm init' successful.

Please wait while the HSM is reset to complete the

initialization process.

Command Result : 0 (Success)

[HSM_PRIVATE_NETWORK_SHORT_NAME] lunash:>

At this point, all partition and key content data inside the HSM has been initialized.

Generate the new HSM server certificate and private key

[HSM_PRIVATE_NETWORK_SHORT_NAME] lunash:>sysconf regenCert HSM_PRIVATE_NETWORK_IP_ADDRESS

WARNING !!  This command will overwrite the current server certificate and private key.

            All clients will have to add this server again with this new certificate.

If you are sure that you wish to proceed, then type 'proceed', otherwise type 'quit'

> proceed

Proceeding...

'sysconf regenCert' successful. NTLS must be (re)started before clients can connect.

Please use the 'ntls show' command to ensure that NTLS is bound to an appropriate network device or IP address/hostname

for the network device(s) NTLS should be active on. Use 'ntls bind' to change this binding if necessary.

Command Result : 0 (Success)

[HSM_PRIVATE_NETWORK_SHORT_NAME] lunash:>ntls bind eth0

Success: NTLS binding network device eth0 set.

NOTICE: The NTLS service must be restarted for new settings to take effect.

If you are sure that you wish to restart NTLS, then type 'proceed', otherwise type 'quit'

> proceed

Proceeding...

Restarting NTLS service...

Stopping ntls:                                             [  OK  ]

Starting ntls:                                             [  OK  ]

Command Result : 0 (Success)

[HSM_PRIVATE_NETWORK_SHORT_NAME] lunash:>

Setup the LunaSA HSM partition keys and access

[HSM_PRIVATE_NETWORK_SHORT_NAME] lunash:>hsm login

Luna PED operation required to login as HSM Administrator - use Security Officer (blue) PED key.

'hsm login' successful.

Command Result : 0 (Success)

[HSM_PRIVATE_NETWORK_SHORT_NAME]lunash:> partition create partition PARTITION_NAME

...

> proceed

...

You will have to insert and initialize however many BLACK Partition Ower PED keys. Towards the end a very long very nonsensical password will be generated by the HSM and displayed on the PED unit display. You have a relatively short time to copy it down elsewhere. IT WILL NEVER BE DISPLAYED AGAIN.

...

'partition create' successful

lunash:>

Review the partition configuration:

[HSM_PRIVATE_NETWORK_SHORT_NAME]lunash:> partition -showPolicies -partition PARTITION_NAME

...

[HSM_PRIVATE_NETWORK_SHORT_NAME]lunash:>

Activate the HSM partition

[HSM_PRIVATE_NETWORK_SHORT_NAME] lunash:>par changePo -po 22 -par PARTITION_NAME -value 1

'partition changePolicy' successful.

Policy "Allow activation" is now set to: 1

Command Result : 0 (Success)

[HSM_PRIVATE_NETWORK_SHORT_NAME] lunash:>par changePo -po 23 -par PARTITION_NAME -value 1

'partition changePolicy' successful.

Policy "Allow auto-activation" is now set to: 1

Notice:  Auto activation parameters will be stored during

         next activation. It is recommended you activate

         this partition now.

Command Result : 0 (Success)

[HSM_PRIVATE_NETWORK_SHORT_NAME] lunash:>par activate -par PARTITION_NAME

  Please enter the password for the partition:

  > PARTITION_PASSWORD

Luna PED operation required to activate partition on HSM - use User or Partition Owner (black) PED key.

'partition activate' successful

Command Result : 0 (Success)

[HSM_PRIVATE_NETWORK_SHORT_NAME] lunash:>

Download the HSM server certificate and make and upload a client access certificate

One set of documentation says that the only required field in the client access certificate is the name which must be the client IP address. When you run the vtl createCert -n <clientHostIPAddress> command (below), be sure to input the IP address as reported by "ifconfig".

First, download the HSM's server.pem certificate to the local machine.

# cd /usr/lunasa/cert/server

# ctp admin@HSM_PRIVATE_NETWORK_IP_ADDRESS:server.pem tempserver.pem

admin@HSM_PRIVATE_NETWORK_IP_ADDRESS's password: HSM_ADMIN_PASSSWORD

...

# mv tempserver.pem HSM_PRIVATE_NETWORK_IP_ADDRESSCert.pem

# cat HSM_PRIVATE_NETWORK_IP_ADDRESSCert.pem >> server.pem

Note that in the steps above, we downloaded the server.pem certificate from the private network HSM (e.g. 192.168.10.50) to a tempserver.pem file, and then renamed that to 192.168.10.50Cert.pem. We then added that certificate to the server.pem file. This is necessary to accommodate BOTH HSMs (HSM(1) and HSM2) since only the server.pem file is referenced by the /etc/Chrystoki.conf file. By placing both HSMs' server certificates in a single server.pem file, the local server can access either HSM.

Next, create a client access certificate and upload it to the HSM. Note that you will need to do this for each client machine that is to have access to the HSMs. You will need to upload the client access certificate to each HSM.

# cd ../client

# hostname

CLIENT_HOSTNAME

$ ifconfig | grep 192.168.10

              inet addr:192.168.10.2  Bcast:192.168.10.255  Mask:255.255.255.0

       (Here, 192.168.10.2 is the CLIENT_PRIVATE_NETWORK_IP_ADDRESS)

# vtl createCert -n CLIENT_PRIVATE_NETWORK_IP_ADDRESS

# ls -l

-rw-r--r-- 1 root root 834 Mar 25 13:43 CLIENT_IP_ADDRESS.pem

-rw-r--r-- 1 root root 963 Mar 25 13:43 CLIENT_IP_ADDRESSKey.pem

# ctp CLIENT_IP_ADDRESS.pem admin@HSM_PRIVATE_NETWORK_IP_ADDRESS:

admin@HSM_PRIVATE_NETWORK_IP_ADDRESS's password: HSM_ADMIN_PASSSWORD

...

#

Register the client with the HSM and assign accesses to our newly created partition

In the HSM login shell (you did keep a login going to the HSM, didn't you?):

[HSM_PRIVATE_NETWORK_SHORT_NAME]lunash:> client -register -client CLIENT_HOSTNAME -ip CLIENT_IP_ADDRESS

...

'client register' successful.

...

[HSM_PRIVATE_NETWORK_SHORT_NAME] lunash:> client assignPartition -client CLIENT_HOSTNAME -partition PARTITION_NAME

...

'client assignPartition' successful.

...

[HSM_PRIVATE_NETWORK_SHORT_NAME] lunash:> client show -c CLIENT_HOSTNAME

...

ClientID: CLIENT_HOSTNAME

IPAddress: CLIENT_IP_ADDRESS

Partitions: "PARTITION_NAME"

...

[HSM_PRIVATE_NETWORK_SHORT_NAME] lunash:>

Register the HSM server certificate with the client:

# vtl verify

The following Luna SA Slots/Partitions were found:

Slot Serial # Label

==== ======== =====

1 900255012 PARTITION_NAME

#

Verify being able to open and close a slot:

# salogin -o -s 1 -i 10:11 &&  salogin -c -s 1 -i 10:11 && echo success

...

success

#

HSM Key Generation and Archiving

Netbook preparation

Turn off the radio wifi device and the Bluetooth in the Netbook BIOS (under Advanced->WLAN Control and Advanced->Bluetooth). Under the BIOS Boot menu, disable all boot options except for USB Storage and hard disk, set USB to the first boot position, then hard disk after that.

Fedora Core 12 Live USB key preparation

Create a Fedora 12 Live Install USB system using the liveusb-creator software system hosted at https://fedorahosted.org/liveusb-creator/. Set the Persistent Storage to at least 1000 MB. After creating the USB key, verify the downloaded Fedora Core 12 Live ISO:

$ cd /cygdrive/c/Program\ Files/LiveUSB

$ curl https://fedoraproject.org/static/fedora.gpg | gpg --im

...

gpg: /home/ngorsuch/.gnupg/trustdb.gpg: trustdb created

gpg: key D22E77F2: public key "Fedora (11) <fedora@fedoraproject.org>" imported

gpg: key 57BBCCBA: public key "Fedora (12) <fedora@fedoraproject.org>" imported

gpg: key E8E40FDE: public key "Fedora (13) <fedora@fedoraproject.org>" imported

gpg: key 217521F6: public key "Fedora EPEL <epel@fedoraproject.org>" imported

gpg: Total number processed: 4

gpg:               imported: 4  (RSA: 3)

$ wget http://mirror.anl.gov/pub/fedora/linux/releases/12/Live/i686/Fedora-12-i686-Live-CHECKSUM

...

$ ls -l Fedora*

-rw-r--r--  1 ngorsuch None       964 Nov  9  2009 Fedora-12-i686-Live-CHECKSUM

-rwx------+ 1 ngorsuch None 685768704 Jun  2 13:41 Fedora-12-i686-Live.iso

$ gpg --verify *-CHECKSUM

...

gpg: Good signature from "Fedora (12) <fedora@fedoraproject.org>"

...

Primary key fingerprint: 6BF1 78D2 8A78 9C74 AC0D  C63B 9D1C C348 57BB CCBA

$ sha256sum -c *-CHECKSUM

Fedora-12-i686-Live.iso: OK

$ sha256sum Fedora-12-i686-Live.iso

5ad27455df004ee23fbc5a05dfa039a14e59956dccf4e767d493601e0bfa4001 *Fedora-12-i686-Live.iso

$ cat Fedora-12-i686-Live-CHECKSUM

...

5ad27455df004ee23fbc5a05dfa039a14e59956dccf4e767d493601e0bfa4001  Fedora-12-i686-Live.iso

...

$

On another USB key, put these files:

compat-libstdc++-296-2.96-143.i686.rpm from http://mirror.anl.gov/pub/fedora/linux/releases/12/Everything/i386/os/Packages/compat-libstdc++-296-2.96-143.i686.rpm  or some other reputable Fedora Core 12 archive.

This other USB key will be used as one of the private key pair storage devices, so you might want to put some other things like HSM administrative and partition passwords to save typing later in this procedure.

Boot the Netbook using the Live USB Key

With only the Netbook and the HSM connected on a private network, boot the Netbook using the Live USB Key.

Set the date/time and time zone to the same as has been set up on the HSM using the dropdown System->Administration->Date & Time.

Install the libc compatibility rpm compat-libstdc++-296-2.96-143.i686.rpm that was stored on the other USB key.

Install the Safenet Software in the Netbook

Use a USB CDROM drive and copy the safenet software onto the persistant storage on the LiveUSB "disk" using something like this:

$ su

# cd /root

# mkdir safenet

# cp -pr /media/610036-041MI/linux safenet/

# cp -pr /media/610036-041MI/source safenet/

# cd safenet/linux/32

# ./install.sh

...

Do you agree to the License contained in the product packaging?

...

(y/n) y

...

(ignore messages about missing shared libraries: libstdc++ libc)

...

Would you like to install the Luna JSP for Luna SA? (y/n)

y

...

Would you like to install the SDK for Luna SA? (y/n)

y

...

# cp -p /root/safenet/source/apache/linu/sautil /usr/lunasa/bin/

# export PATH=$PATH:/usr/lunasa/bin

#

Configure the Netbook network

# ifconfig eth0 NETBOOK_PRIVATE_NETWORK_IP_ADDRESS netmask PRIVATE_NETWORK_NETMASK up

# cat <<EOF  >>/etc/hosts

NETBOOK_PRIVATE_NETWORK_IP_ADDRESS NETBOOK_SHORT_HOSTNAME

HSM_PRIVATE_NETWORK_IP_ADDRESS hsm

EOF

# ping -c 1 hsm

...

#

Clear out any previous HSM partition data

# ssh admin@hsm

admin@'s password: HSM_ADMIN_PASSSWORD

[hsm] lunash:> hsm show

...

Partition: NNNNNNNNNN,        Name: cilogon

...

[hsm] lunash:> partition clear -partition cilogon

...

          Type 'proceed' to clear the partition, or 'quit'

          to quit now.

          > proceed

...

[hsm] lunash:> partition showContents -partition cilogon

...

[hsm] lunash:>

Download the HSM server certificate and make and upload a client access certificate

One set of documentation says that the only required field in the client access certificate is the name which must be the client IP address. But the other says that the names of the client access certificate files must start with what the output of the client hostname command. When you run the vtl createCert -n <clientHostname> command (below), be sure to input the hostname exactly as reported (uppercase/lowercase). If you create a certificate using a hostname parameter that is not an exact case-match for the client’s hostname, the client may not be able to set up an access link to the remote HSM.

# cd /usr/lunasa/cert/server

# ctp admin@HSM_PRIVATE_NETWORK_IP_ADDRESS:server.pem .

admin@HSM_PRIVATE_NETWORK_IP_ADDRESS's password: HSM_ADMIN_PASSSWORD

...

# cd ../client

# hostname NETBOOK_SHORT_HOSTNAME

# hostname

NETBOOK_SHORT_HOSTNAME

# vtl createCert -n NETBOOK_PRIVATE_NETWORK_IP_ADDRESS

# ls -l

-rw-r--r-- 1 root root 834 Mar 25 13:43 NETBOOK_PRIVATE_NETWORK_IP_ADDRESS.pem

-rw-r--r-- 1 root root 963 Mar 25 13:43 NETBOOK_PRIVATE_NETWORK_IP_ADDRESSKey.pem

# ctp NETBOOK_PRIVATE_NETWORK_IP_ADDRESS.pem admin@HSM_PRIVATE_NETWORK_IP_ADDRESS:

admin@HSM_PRIVATE_NETWORK_IP_ADDRESS's password: HSM_ADMIN_PASSSWORD

...

#

Register the client with the HSM and assign accesses to our newly created partition

In the HSM login shell (you did keep a login going to the HSM, didn't you?):

[NETBOOK_SHORT_HOSTNAME]lunash:> client -register -client NETBOOK_SHORT_HOSTNAME -ip NETBOOK_PRIVATE_NETWORK_IP_ADDRESS

...

'client register' successful.

...

[NETBOOK_SHORT_HOSTNAME] lunash:> client assignPartition -client NETBOOK_SHORT_HOSTNAME -partition cilogon

...

'client assignPartition' successful.

...

[NETBOOK_SHORT_HOSTNAME] lunash:> client show -c NETBOOK_SHORT_HOSTNAME

...

ClientID: NETBOOK_SHORT_HOSTNAME

IPAddress: NETBOOK_PRIVATE_NETWORK_IP_ADDRESS

Partitions: "cilogon"

...

[NETBOOK_SHORT_HOSTNAME] lunash:>

As root on our netbook client:

# vtl addserver -n HSM_PRIVATE_NETWORK_IP_ADDRESS -c /usr/lunasa/cert/server/server.pem

...

# vtl verify

...

Slot      Serial #          Label

...

1          .........             cilogon

#

If there is a problem with the vtl verify, it means there is a problem with the /etc/Chrystoki.conf file.

All the "vtl addServer" and "vtl deleteServer" commands do is manipulate that file, which should end up looking something like this:

...

LunaSA Client = {

   ServerPort00 = 1792;

   ServerName00 = HSM_PRIVATE_NETWORK_IP_ADDRESS;

   ...

   ServerCAFile=/usr/lunasa/cert/server/server.pem;

   ...

}

...

Verify being able to open and close a slot:

# salogin -o -s 1 -i 10:11 &&  salogin -c -s 1 -i 10:11 && echo success

...

success

#

Generate the key pairs on the netbook client

# mkdir /root/keys

# cd /root/keys

# for n in 1 2 3 4 5 6 7 8 9 ; do /usr/bin/openssl genrsa -des3 -out k$n.with.passphrase.pem -passout pass:KEYS_PASSPHRASE 2048 ; done

Generating RSA private key, 2048 bit long modulus

.....................................+++

.............+++

e is 65537 (0x10001)

(9 more times)

# for n in 1 2 3 4 5 6 7 8 9 ; do /usr/bin/openssl rsa -in k$n.with.passphrase.pem -passin pass:KEYS_PASSPHRASE -out k$n.without.passphrase.pem ; done

writing RSA key

...

writing RSA key

# ls -l

-rw-r--r-- 1 root root 1743 Jun  4 10:31 k1.with.passphrase.pem

-rw-r--r-- 1 root root 1675 Jun  4 10:32 k1.without.passphrase.pem

...

-rw-r--r-- 1 root root 1743 Jun  4 10:31 k9.with.passphrase.pem

-rw-r--r-- 1 root root 1675 Jun  4 10:32 k9.without.passphrase.pem

#

Note that the files k?.without.passphrase.pem now contain the private keys which will be imported into the HSM.

Import the key pairs into the HSM

# for n in 1 2 3 4 5 6 7 8 9 ; do

> cmu importkey -in k$n.without.passphrase.pem -keyalg RSA && cmu list -keyType=rsa

> done

...

Please enter password for token in slot 1 : PARTITION_PASSWORD

...

Please enter password for token in slot 1 : PARTITION_PASSWORD

handle=KEY_1_HANDLE_NUMBER label=CMU Unwrapped RSA Private Key

...

Please enter password for token in slot 1 : PARTITION_PASSWORD

...

Please enter password for token in slot 1 : PARTITION_PASSWORD

handle=KEY_1_HANDLE_NUMBER label=CMU Unwrapped RSA Private Key

handle=KEY_2_HANDLE_NUMBER label=CMU Unwrapped RSA Private Key

(7 more times, each time note the order of the key handle numbers)

...

Please enter password for token in slot 1 : PARTITION_PASSWORD

...

Please enter password for token in slot 1 : PARTITION_PASSWORD

handle=KEY_1_HANDLE_NUMBER label=CMU Unwrapped RSA Private Key

handle=KEY_2_HANDLE_NUMBER label=CMU Unwrapped RSA Private Key

handle=KEY_3_HANDLE_NUMBER label=CMU Unwrapped RSA Private Key

handle=KEY_4_HANDLE_NUMBER label=CMU Unwrapped RSA Private Key

handle=KEY_5_HANDLE_NUMBER label=CMU Unwrapped RSA Private Key

handle=KEY_6_HANDLE_NUMBER label=CMU Unwrapped RSA Private Key

handle=KEY_7_HANDLE_NUMBER label=CMU Unwrapped RSA Private Key

handle=KEY_8_HANDLE_NUMBER label=CMU Unwrapped RSA Private Key

handle=KEY_9_HANDLE_NUMBER label=CMU Unwrapped RSA Private Key

The next part may have to be adjusted, because the key numbers 1 through 9 usually end up being assigned key handle numbers 8 through 16 contiguously. The idea here is to watch what happens each time and adjust the following, so that the key handle numbers and the key indexes matching is known.

# for n in 1 2 3 4 5 6 7 8 9 ; do

> handle="`expr $n + 7`"

> cmu setAttribute -handle=$handle -extractable=False -label="KEY$n"

> done

...

Please enter password for token in slot 8 : PARTITION_PASSWORD

(8 more times)

# cmu list -keyType=rsa

Please enter password for token in slot 1 : PARTITION_PASSWORD

handle=8       label=KEY1

...

handle=16       label=KEY9

#

All cryptographic operations using the modified openssl that communicates with the network HSM will use these "key" files to tell the HSM which stored keys to use internally.

Save the Encrypted Private keys and the keyfiles on both USB sticks and on 2 CDROMS

# cd /root/keys

# shred --remove k?.without.passphrase.pem

# cp -p k?.with.passphrase.pem /media/KINGSTON/

For the CDROM writer, you will have to copy these files to a non-root readable directory, and make them readable by world.

# mkdir /tmp/stuff

# chmod 777 /tmp/stuff

# cp-p /root/keys/k*.with.passphrase.pem /tmp/stuff

# chmod go+r /tmp/stuff/*

#

Use the Fedora CDROM writing utility to write out the encrypted private keys:

/tmp/stuff/*

Then delete the /tmp/stuff directory, before shutting down the Fedora system.

# shred --remove /tmp/stuff/*

# rmdir /tmp/stuff

#

Boot the Netbook into Windoze to clear out any dynamic RAM memory traces

... obviously by taking out the Live USB key and rebooting.

Backup HSM Partition Contents to a Luna HSM Backup Token

Backup the partition contents to the backup token

Log into the HSM as admin, then do this:

[hsm] lunssh:>hsm showPolicies

...

Description            Value   ...

...

Allow cloning            On    ...

...

[hsm] lunash:>partition backup -partition cilogon -password PARTITION_PASSWORD

... BLUE BLUE RED BLACK BLACK ...

Object "KEY1" (handle 8) cloned to handle 6 on target

Object "KEY2" (handle 9) cloned to handle 7 on target

Object "KEY3" (handle 10) cloned to handle 8 on target

Object "KEY4" (handle 11) cloned to handle 9 on target

Object "KEY5" (handle 12) cloned to handle 10 on target

Object "KEY6" (handle 13) cloned to handle 11 on target

Object "KEY7" (handle 14) cloned to handle 12 on target

Object "KEY8" (handle 15) cloned to handle 13 on target

Object "KEY9" (handle 16) cloned to handle 14 on target

...

'partition backup' successful.

[hsm] lunash:>

Create a Limited Capabilities Partiton User

A partition user (as opposed to a partition owner) can only use the objects in a partition, but cannot modify, create, delete, or move partition objects (private keys). The partition user can reference the private keys and do encryption/decryption/signing commands using them. SafeNet also refers to partition users as "Crypto Users". Log into the HSM as the administrator (you will need the PED keypad attached to the HSM and the "SO/HSM ADMIN" PED key inserted. You will only have a short amount of time to write down the partition user password!!!!!

[hsm] lunsah:>hsm login -password HSM_ADMIN_PASSWORD

...

[ enter the HSM administrator PIN on the PED keypad ]

...

'hsm login' successful.

[hsm] lunash:>partition createuser -partition cilogon

...

[ QUICKLY COPY THE USER PASSWORD THAT DISPLAYS ON THE PED KEYPAD DISPLAY ]

...

'partition createuser' successful.

[hsm] lunash:>

You will then want to change the partition user password to match any other hsm user partition passwords like this:

[hsm] lunash:>partition changePw -cu -partition cilogon -oldpw PED_KEYPAD_PASSWORD -newpw PARTITION_USER_PASSWORD

passwd: all authentication tokens updated successfully

Command Result: 0 (Success)

[hsm] lunash:>

Configure NTP

The SafeNet troubleshooting guide says that incorrect system date/time "is the number one, most frequent, cause of difficulty" so using NTP to keep the system clock accurate is a good idea. Since our HSMs are on a private network without public network connectivity, we need to run our own NTP servers on the private network on systems that also have public connectivity. The HSMs appear to be by default configured to look for an NTP server at 127.127.1.0 so we need to delete that server from the configuration and add our own:

[hsm2] lunash:>sysconf ntp addserver 192.168.10.2

[hsm2] lunash:>sysconf ntp addserver 192.168.10.202

[hsm2] lunash:>sysconf ntp del 127.127.1.0

Then we check that NTP is running OK:

[hsm2] lunash:>sysconf ntp status

[hsm2] lunash:>sysconf ntp log tail

Useful HSM commands

Restore an HSM (or initialize a second fallback HSM) with backed up partition data

Restore an unknown administrator password

This only works on the serial console port, and is the last resort, as this will also "zeroize" the HSM, wiping it of all settings and data. Connect a Null Modem DB-9 female-to-female cable from the HSM console port to a USB to serial converter. Use HyperTerminal or a similar program, and set the serial port to 115200 buad 8 data no parity 1 stop bit. Try to login on the console 3 times to the admin account, giving a bad password each time. This will wipe out the HSM's contents (they call it "zeroizing") and then ask if you want the administrator password set to the default factory password:

Luna SA Build [Build lunasa_4.4.0-27  20090703 16:11]

Authorized Use Only

DEFAULTHOSTNAME login: admin

Password: BAD

Login incorrect

Luna SA Build [Build lunasa_4.4.0-27  20090703 16:11]

Authorized Use Only

DEFAULTHOSTNAME login: admin

Password: WORSE

Login incorrect

Luna SA Build [Build lunasa_4.4.0-27  20090703 16:11]

Authorized Use Only

DEFAULTHOSTNAME login: admin

Password: WORST

Login incorrect

Luna SA Build [Build lunasa_4.4.0-27  20090703 16:11]

Authorized Use Only

DEFAULTHOSTNAME login: admin

 *****************************************************

 **                                                                                            **

 **    It appears that you are having trouble                                     **

 **    remembering the 'admin' account password!                              **

 **                                                                                        **

 **    Your HSM is currently zeroized so 'admin'                              **

 **    recovery is not possible.                                                    **

 **                                                                                        **

 **    Do you wish to reset the 'admin' account                                 **

 **    to the factory default password?                                            **

 **                                                                                        **

 **    Type 'proceed' to reset the 'admin' account                          **

 **    password, or 'quit' to continue without                                     **

 **    reset.                                                                                 **

 **    > proceed

 **                                                                                                 **

 **    Success:  The password for the 'admin'                                **

 **              account is reset to the factory                                     **

 **              default. The HSM is zeroized.                                        **

 **              You will need to log in as                                              **

 **              'admin' and run 'hsm init' to                                       **

 **              re-initialize the HSM before                                           **

 **              you may use it again.                                              **

 **                                                                                        **

 *****************************************************

DEFAULTHOSTNAME login: admin

Password: chrysalis

...

Changing password for user admin

New UNIX password: HSM_ADMIN_PASSWORD

Retype new UNIX password: HSM_ADMIN_PASSWORD

passwd: all authentication tokens updated successfully

Password change successful.

[DEFAULTHOSTNAME] lunash:>?

Restore an HSM to factory default settings (except for the network)

This needs to be done so that the remote PED vector (red "keys") is set, and can only be done using the serial console:

[hsm2] lunash:>hsm factoryReset

CAUTION:  Are you sure you wish to reset this HSM to factory

          default settings? All partitions and data will be erased.

          Partition policies will be reverted to factory settings.

          HSM level policies will not be changed.

          Type 'proceed' to return the HSM to factory default, or

          'quit' to quit now.

          > proceed

'hsm factoryReset' successful.

Please wait while the HSM is reset to complete the

process.

The remote PED vector (RPV) has been erased on HSM.

Command Result : 0 (Success)

[hsm2] lunash:>

This does not reset everything in the HSM. Among other things, the network information and hostname are retained. To do anything useful after a factoryReset, the HSM has to be init'ed after that.

Initialize the HSM

THIS WILL WIPE ALL HSM CONTENTS!!!! After logging in through either the console serial port or through the network (see the above section if the HSM administrator password is corrupted), do this:

[DEFAULTHOSTNAME] lunash:>hsm init -label hsm2

CAUTION:  Are you sure you wish to re-initialize this HSM?

          All partitions and data will be erased.

          Type 'proceed' to initialize the HSM, or 'quit'

          to quit now.

          > proceed

Luna PED operation required to initialize HSM - use Default (gray) and Security

Officer (blue) PED keys, please note that the gray key is not required if using

a PED 2.

The PED keypad will ask for a blue SO/HSM ADMIN "key". Insert it.

The PED will then ask if you want to re-use or initialize the "key".

Tell it to re-use it.

As part of the initialization process you will have to type in the HSM_ADMIN_PIN number associated with your already set up admin "key".

Luna PED operation required to login as HSM Administrator - use Security Officer

 (blue) PED key.

Prior to the actual initialization, the HSM will have the PED demand an appropriate ADMIN "key". Use the same ones and

type in again the same HSM_ADMIN_PIN numbers.

'hsm init' successful.

Please wait while the HSM is reset to complete the

initialization process.

Command Result : 0 (Success)

[DEFAULTHOSTNAME] lunash:>

You will then have to do these actions, just as was done for the initial HSM:

Set the HSM timezone date and time

Set the HSM hostname and network information

Configure NTP

Generate the new HSM server certificate and private key

Note the following should not have any partition keys re-initialized:

Setup the LunaSA HSM partition keys and access

But you will have to write down TEMPORARY_PARTITION_PASSWORD that is displayed only briefly on the PED.

Then you will probably want to change the partition password to the same as was used before from the backed up HSM:

[hsm2] lunash:>partition changePw -newpw PARTITION_PASSWORD -oldpw TEMPORARY_PARTITION_PASSWORD -partition PARTITION_NAME

Luna PED operation required to activate partition on HSM - use User or Partition Owner (black) PED key.

'partition changePw' successful.

Command Result : 0 (Success)

[hsm2] lunash:>

Activate the HSM partition

Then restore the partition contents from the backup smartcard token (this will require the partition partition owner hsm key, but will require the system administrator overall pin number, NOT the partition pin number):

[hsm2] lunash:>partition restore -replace -partition PARTITION_NAME -password PARTITION_PASSWORD

Luna PED operation required to login to partition backup space on token - use User or Partition Owner (black) PED key.

Object "KEY1" (handle 6) cloned to handle 6 on target

Object "KEY2" (handle 7) cloned to handle 7 on target

Object "KEY3" (handle 8) cloned to handle 8 on target

Object "KEY4" (handle 9) cloned to handle 9 on target

Object "KEY5" (handle 10) cloned to handle 10 on target

Object "KEY6" (handle 11) cloned to handle 11 on target

Object "KEY7" (handle 12) cloned to handle 12 on target

Object "KEY8" (handle 13) cloned to handle 13 on target

Object "KEY9" (handle 14) cloned to handle 14 on target

'partition restore' successful.

Command Result : 0 (Success)

[hsm2] lunash:>

For each client you will have to do these:

Download the HSM server certificate and make and upload a client access certificate

Register the client with the HSM and assign accesses to our newly created partition

Set the HSM network addresss and mask

[DEFAULTHOSTNAME] lunash:>network interface static -d eth0 -ip HSM_PRIVATE_NETWORK_IP_ADDRESS -n PRIVATE_NETWORK_NETMASK

NOTICE: The network service must be restarted for new network settings to take e

ffect.

If you are sure that you wish to restart the network, then type 'proceed', other

wise type 'quit'

> proceed

Proceeding...

Restarting network service...

Shutting down loopback interface:  [  OK  ]

Setting network parameters:  [  OK  ]

Bringing up loopback interface:  [  OK  ]

Bringing up interface eth0:  [  OK  ]

Command Result : 0 (Success)

[DEFAULTHOSTNAME] lunash:>network show

   Hostname:          DEFAULTHOSTNAME

   Domain:            <not set>

   IP Address (eth0): HSM_PRIVATE_NETWORK_IP_ADDRESS

   HW Address (eth0): 00:00:50:58:73:C7

   Mask (eth0):       PRIVATE_NETWORK_NETMASK

   Gateway (eth0):    0.0.0.0

   Name Servers:      <not set>

   Search Domain(s):

Kernel IP routing table

Destination     Gateway         Genmask         Flags Metric Ref    Use Iface

HSM_PRIVATE_NETWORK_IP_ADDRESS  0.0.0.0  PRIVATE_NETWORK_NETMASK   U     0      0        0 eth0

127.0.0.0                 0.0.0.0    255.0.0.0             U     0      0        0 lo

Link status

eth0: no link

eth1: no link

Command Result : 0 (Success)

[DEFAULTHOSTNAME] lunash:>

Clear out all objects in a partition

# ssh -l admin@HSM_PRIVATE_NETWORK_IP_ADDRESS

admin@HSM_PRIVATE_NETWORK_IP_ADDRESS's password: HSM_ADMIN_PASSSWORD

[HSM_PRIVATE_NETWORK_SHORT_NAME] lunash:> partition clear -partition PARTITION_NAME

...

          Type 'proceed' to clear the partition, or 'quit'

          to quit now.

          > proceed

...

[HSM_PRIVATE_NETWORK_SHORT_NAME] lunash:>

Display the contents of a "key" access file

List all objects in a partition

# ssh -l admin@HSM_PRIVATE_NETWORK_IP_ADDRESS

admin@HSM_PRIVATE_NETWORK_IP_ADDRESS's password: HSM_ADMIN_PASSSWORD

[HSM_PRIVATE_NETWORK_SHORT_NAME] lunash:> partition showContents -partition PARTITION_NAME

...

[HSM_PRIVATE_NETWORK_SHORT_NAME] lunash:>

Reset the client "connection" configuration

This is useful when anything changes and you start getting these kinds of errors:

Certificate/cakey sign

failed. error:8008E08F:Luna CA3 engine:LUNACA3_F_FIND_RSA:no such key

error:8007308F:Luna CA3 engine:LUNA_RSA_PRIVATE_ENCRYPT:no such key

These commands reset configuration data on the client side (it really just redoes the /etc/Chrystoki.conf configuration file):

# vtl deleteServer -n HSM_PRIVATE_NETWORK_IP_ADDRESS

# vtl addServer -n HSM_PRIVATE_NETWORK_IP_ADDRESS -c /usr/lunasa/cert/server/HSM_PRIVATE_NETWORK_IP_ADDRESSCert.pem

# 

Show HSM information including listing all partitions

# ssh -l admin@HSM_PRIVATE_NETWORK_IP_ADDRESS

admin@HSM_PRIVATE_NETWORK_IP_ADDRESS's password: HSM_ADMIN_PASSSWORD

[HSM_PRIVATE_NETWORK_SHORT_NAME] lunash:> hsm show

...

[HSM_PRIVATE_NETWORK_SHORT_NAME] lunash:>

Test the HSM private key usage

Use these commands:

OPENSSL=/usr/local/openssl-0.9.8e-safenet/bin/openssl

KEYFILE=/opt/basic/k1.keyfile.pem

TMPDIR=/root/tmp

rm -rf $TMPDIR

mkdir $TMPDIR

cd $TMPDIR

cp -p $KEYFILE k1.keyfile.pem

$OPENSSL rsa -engine LunaCA3 -in k1.keyfile.pem -out k1.public.pem -outform PEM -pubout

hostname > file.txt

$OPENSSL rsautl -engine LunaCA3 -encrypt -inkey k1.public.pem -pubin -in file.txt -out file.ssl

$OPENSSL rsautl -engine LunaCA3 -decrypt -inkey k1.keyfile.pem -in file.ssl -out decrypted.txt

cmp file.txt decrypted.txt

These commands are in a script file at /root/verifyhsm.

This script has also been included in the /etc/init.d/HSM file as the "status" sub-command,

so the command "service HSM status" will show whether or not the HSM is accessible and that cryptographic operations can be done with it.

Re-Activate the HSM partition after a 2 hour power failure

After a 2 hour power failure, the HSM goes into the "out of service" mode. To put it back in service, you need:

Under normal operating conditions, or if the last power failure has been too short to put the HSM out of service the front display will show "Insrv" at the beginning of the bottom line. If the HSM is out of service, the bottom line will show "Out of srvc".

 

# ssh -l admin@HSM_PRIVATE_NETWORK_IP_ADDRESS

admin@HSM_PRIVATE_NETWORK_IP_ADDRESS's password: HSM_ADMIN_PASSSWORD

[HSM_PRIVATE_NETWORK_SHORT_NAME] lunash:>par show

[ Note the partition name(s). ]

[HSM_PRIVATE_NETWORK_SHORT_NAME] lunash:>par activate -par PARTITION_NAME

  Please enter the password for the partition:

  > PARTITION_PASSWORD

Luna PED operation required to activate partition on HSM - use User or Partition Owner (black) PED key.

[ Connect PED and insert Partition Owner (black) PED key (USB key) at this time if you haven't already. ]

[ Then select option #1 on the PED keypad. Then input the partition PIN numbers on the PED keypad ]

'partition activate' successful

Command Result : 0 (Success)

Now is a good time to check the system clock. If it's off, set it:

[HSM_PRIVATE_NETWORK_SHORT_NAME] lunash:>status date

  Fri Jul 29 16:04:54 CDT 2011

[HSM_PRIVATE_NETWORK_SHORT_NAME] lunash:>sysconf time 15:43

Might as well also check disk space and syslogs

[HSM_PRIVATE_NETWORK_SHORT_NAME] lunash:>status disk

[HSM_PRIVATE_NETWORK_SHORT_NAME] lunash:>syslog tail

When all of our (one) partition is re-activated, the front panel should show "Insrv" again. Remember, the HSM's can take up to a minute to reboot before the display is activated.

Copy SupportInfo and Syslogs off HSM

 Whenever opening a support ticket with SafeNet, the following is typically required. First generate the supportInfo.txt and logs.tgz files on the HSM:

# ssh -l admin@HSM_PRIVATE_NETWORK_IP_ADDRESS

admin@HSM_PRIVATE_NETWORK_IP_ADDRESS's password: HSM_ADMIN_PASSSWORD

[HSM_PRIVATE_NETWORK_SHORT_NAME] lunash:>hsm supportInfo

[HSM_PRIVATE_NETWORK_SHORT_NAME] lunash:>syslog tarlog

[HSM_PRIVATE_NETWORK_SHORT_NAME] lunash:>exit

Then use the ctp command to fetch them from the HSM:

# ctp admin@HSM_PRIVATE_NETWORK_IP_ADDRESS:supportInfo.txt .

# ctp admin@HSM_PRIVATE_NETWORK_IP_ADDRESS:logs.tgz .