Procedures

Integration procedures include:

Installing the HSM.
Installing the Security World Software and create the security world.
Installing the Apache HTTP Server.
Testing CHIL.
Configuring the Apache HTTP Server to use the HSM.

This chapter describes these procedures.

Installing the HSM

Install the HSM by following the instructions in the Installation Guide for the HSM.

We recommend that you install the HSM before configuring the Security World Software with your Apache HTTP Server.

Installing the Security World Software and creating the security world

To install the Security World Software and create the security world:

On the computer that you want to make the Apache HTTP Server, install the latest version of the Security World Software as described in the Installation Guide for the HSM.

We recommend that you uninstall any existing nShield software before installing the new nShield software.
Create the security world as described in the User Guide, creating the ACS and OCS that you require.

Installing and configuring the Apache HTTP Server

To install the Apache HTTP Server:

sudo yum install httpd-tools openssl-libs mod_ssl

Testing CHIL

The nShield 12.40 Compatibility Package is required for the Cryptographic Hardware Interface Library (CHIL) plugin. Because this version of the library needs a gen2 Security World, either an old world needs to be loaded, or the utility new-world-1240 needs to be used to create a suitable Security World.

To check that CHIL is working:

# export LD_LIBRARY_PATH=/opt/nfast/toolkits/hwcrhk/
# openssl engine -t chil
(chil) CHIL hardware engine support
[ available ]

Configuring the Apache HTTP Server to use the HSM

Environment settings

For convenience:

export PATH=$PATH:/opt/nfast/bin

In /etc/sysconfig/httpd add the line

LD_LIBRARY_PATH=/opt/nfast/toolkits/hwcrhk

Set up Apache to use the CHIL library

Generate an embed key. Ensure that the key files are output to your home directory or another working directory.

# generatekey embed
protect: Protected by? (token, module) [token] > module
size: Key size? (bits, minimum 1024) [2048] >
OPTIONAL: pubexp: Public exponent for RSA key (hex)? []
> embedsavefile: Filename to write key to? []
> testkey
plainname: Key name? [] > testkey
x509country: Country code? [] > [...]
x509province: State or province? [] > [...]
x509locality: City or locality? [] > [...]
x509org: Organisation? [] > [...]
x509orgunit: Organisation unit? [] > [...]
x509dnscommon: Domain name? [] > [...]
x509email: Email address? [] > [...]
nvram: Blob in NVRAM (needs ACS)? (yes/no) [no] >
digest: Digest to sign cert req with? (md5, sha1, sha256, sha384, sha512)
[default sha256] >
key generation parameters:
operation       Operation to perform                generate
application     Application                         embed
protect         Protected by                        module
verify          Verify security of key              yes
type            Key type                            RSA
size            Key size                            2048
pubexp          Public exponent for RSA key (hex)
embedsavefile   Filename to write key to            testkey
plainname       Key name                            testkey
x509country     Country code                        [...]
x509province    State or province                   [...]
x509locality    City or locality                    [...]
x509org         Organisation                        [...]
x509orgunit     Organisation unit                   [...]
x509dnscommon   Domain name                         [...]
x509email       Email address                       [...]
nvram           Blob in NVRAM (needs ACS)           no
digest          Digest to sign cert req with        sha256
Key successfully generated.
Path to key: /opt/nfast/kmdata/local/key_embed_6d5706...
Path to CSR: <CURRENTFOLDER>/embed_6d5706..._req
Path to self-cert: <CURRENTFOLDER>/embed_6d5706..._selfcert

In the same folder as the self-cert there will also be a file called testkey.

Copy the files into the Apache installation using the following commands (adjust to the values you get):

cp <CURRENTFOLDER>/testkey /etc/pki/tls/private/testkey
cp <CURRENTFOLDER>/embed_6d5706..._selfcert /etc/pki/tls/certs/testkey_selfcert

In /etc/httpd/conf.d/ssl.conf, set

SSLCertificateFile /etc/pki/tls/certs/testkey_selfcert
SSLCertificateKeyFile /etc/pki/tls/private/testkey
SSLCryptoDevice chil

Open the firewall

firewall-cmd --zone=public --permanent --add-service=https
firewall-cmd --reload

Switch off SE Linux

If SE Linux is active, this might prevent Apache from loading our library. To switch it off:

setenforce 0

Start the HTTP daemon

service httpd start

https://<yourapacheserver> should work, and the certificate in the browser should show the information that was provided when creating the embed key above. For example:

Figure 2.1 HTTPD successfully started

Test the connection

Test the connection with a command similar to:

openssl s_client -crlf -connect localhost:443 -CAfile testkey_selfcert.pem
openssl s_client -crlf -connect localhost:443 -CAfile <CURRENTFOLDER>/embed_6d5706.._
selfcert

Check the following messages and fields in the output:

CONNECTED(00000003)
depth
Certificate chain information
Server certificate information
Session-ID
Master-Key
TLS session ticket:
Verify return code: 0 (ok)

Example output:

# openssl s_client -crlf -connect localhost:443 -CAfile embed_6d5706..._selfcert
CONNECTED(00000003)
depth=[...]
verify return:1
---
Certificate chain
0 s:/C=[...]
i:/C=[...]
---
Server certificate
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
subject=[...]
issuer=[...]
---
No client certificate CA names sent
Peer signing digest: SHA512
Server Temp Key: ECDH, P-256, 256 bits
---
SSL handshake has read 1570 bytes and written 415 bytes
---
New, TLSv1/SSLv3, Cipher is ECDHE-...
Server public key is 2048 bit
Secure Renegotiation IS supported
Compression: NONE
Expansion: NONE
No ALPN negotiated
SSL-Session:
Protocol : TLSv1.2
Cipher : ECDHE-...
Session-ID: [...]
Session-ID-ctx:
Master-Key: [...]
Key-Arg : None
Krb5 Principal: None
PSK identity: None
PSK identity hint: None
TLS session ticket lifetime hint: 300 (seconds)
TLS session ticket:
...
Start Time: 1579086822
Timeout : 300 (sec)
Verify return code: 0 (ok)
---

OCS protection

If OCS protection is required, create an OCS:

createocs -Q1/1 -Napacheocs -m 1

Leave the OCS in the card reader and generate an embed key as in Set up Apache to use the CHIL library, but choose the protection to be token.

The steps to copy certificates about is the same as for module-protected keys.

When you are starting Apache, you will have to preload the OCS so that the key can be used without the web server having to load it:

preload -f /var/run/httpd/preload -c apacheocs /usr/sbin/httpd -e debug -X

Softcard protection

If softcard protection is required, create a softcard:

ppmk -n apachesoft

Generate an embed key as in Set up Apache to use the CHIL library, but choose the protection to be softcard.

The steps to copy certificates about is the same as for module protected keys.

When you are starting Apache, you will have to preload the softcard so that the key can be used without the web server having to load it:

preload -f /var/run/httpd/preload -s apachesoft /usr/sbin/httpd -e debug -X