Procedures

Integration procedures include:

Installing and configuring the Apache HTTP server.
Install the HSM.
Install the Security World software and create the Security World.
Set up the PKCS11 engine.
Configure the Apache HTTP Server to use the PKCS #11 engine.
Test the PKCS #11 integration with the Apache HTTP Server and the HSM.

This chapter describes these procedures.

Installing and configuring the Apache HTTP server

To install the Apache HTTP Server on your Red Hat server:

% sudo yum install -y openssl-pkcs11 httpd httpd-tools openssl-libs mod_ssl opensc

Open the firewall

If the firewall is active, this might prevent Apache from loading the library. To open the firewall:

% sudo firewall-cmd --zone=public --permanent --add-service=http
% sudo firewall-cmd --zone=public --permanent --add-service=https
% sudo firewall-cmd --reload

Consult the security team in your organization for suitable setting of the firewall.

Switch off SE Linux

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

% sudo setenforce 0

Consult the security team in your organization for a suitable setting of the SE Linux policy to allow the web server read access to the files in /opt/nfast.

Restart the httpd service

% sudo service httpd restart

Check if Apache is running

Open a browser and access the following URL: http://<YOUR_IP_ADDRESS>. You should see a page similar to this:

Install the HSM

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

Entrust recommends that you install the HSM before configuring the Security World software with your Apache HTTP Server.

Install the Security World software and create 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.

Entrust recommends 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.

Set up the PKCS11 engine

To avoid problems associated with the Entrust supplied OpenSSL, which is used internally by generatekey to make certificates, ensure that /opt/nfast/bin is not at the front of your $PATH.

You can confirm that the right binary is being run with the following command:

% which openssl

/usr/bin/openssl

If this command returns anything inside /opt/nfast, check your $PATH variable.

Configuration

Find out where your OpenSSL configuration file is located:

% openssl version -d

OPENSSLDIR: "/etc/pki/tls"

The minimum configuration is similar to the following:

#
# OpenSSL example configuration file.
# This is mostly being used for generation of certificate requests.
#

# Note that you can include other files from the main configuration
# file using the .include directive.
#.include filename

# This definition stops the following lines generating an error if HOME isn't
# defined.
HOME = .
RANDFILE = $ENV::HOME/.rnd

# nShield PKCS11
openssl_conf = openssl_def
[openssl_def]
engines = engine_section
[engine_section]
pkcs11 = pkcs11_section
[pkcs11_section]
engine_id = pkcs11
dynamic_path = /usr/lib64/engines-1.1/pkcs11.so
MODULE_PATH = /opt/nfast/toolkits/pkcs11/libcknfast.so
init = 0
#!

The following message can appear when creating certificates:

unable to find 'distinguished_name' in config
problems making Certificate Request
140493626791824:error:0E06D06C:configuration file routines:NCONF_get_string:no value:conf_lib.c:324:group=req name=distinguished_name

If it does, you need to add the following to your OpenSSL configuration, adjusted to your organization’s values:

[req]
distinguished_name = req_distinguished_name
req_extensions = v3_req
prompt = no
[req_distinguished_name]
C = US
ST = FL
L = Sunrise
O = Entrust
OU = nShield
CN = www.entrust.com
[v3_req]
subjectAltName = @alt_names
[alt_names]
DNS.1 = www.entrust.com
DNS.2 = entrust.com

Make sure the server’s hostname matches the CN in the certificate.

Create a file called openssl.pkcs11.cnf with the settings above, and save it where your OpenSSL configuration settings are located:

Create/edit the /etc/pki/tls/openssl.pkcs11.cnf file:
```
% sudo vi /etc/pki/tls/openssl.pkcs11.cnf
```
Enter the settings above and save the file.

Set up /opt/nfast/cknfastrc

The following variables may need to be added to the /opt/nfast/cknfastrc file. They are referenced in this guide to address specific situations, and their use will depend on your current environment.

CKNFAST_DEBUG=10
CKNFAST_DEBUGFILE=/path/to/debug/file
CKNFAST_FAKE_ACCELERATOR_LOGIN=1
CKNFAST_LOADSHARING=1

If you omit CKNFAST_DEBUGFILE, log entries will be added to Apache’s error_log.

Turn debug off in a production environment.

Test the configuration

You must now test the new configuration file using OpenSSL:

Exporting the OPENSSL_CONF environment variable:

% export OPENSSL_CONF=/etc/pki/tls/openssl.pkcs11.cnf

Test the configuration:

% openssl engine -tt -c -v

There may be other output, but you should see this included:

(pkcs11) pkcs11 engine
[RSA, rsaEncryption, id-ecPublicKey]
[ available ]
SO_PATH, MODULE_PATH, PIN, VERBOSE, QUIET, INIT_ARGS, FORCE_LOGIN

Debugging notes

Security World permissions.

The following message can appear:
```
Unable to load module /opt/nfast/toolkits/pkcs11/libcknfast.so
```
If it does, it indicates that there is no Security World. Make sure you create a Security world first.
Debugging variables.

These variables can be used for debugging purpose. They can be set in /opt/nfast/cknfastr or as environment variables.
```
CKNFAST_DEBUG=10
CKNFAST_DEBUGFILE=/path
```
Missing PKCS #11 engine in the output.

If you don’t see the PKCS #11 engine in the output, check the dynamic_path line in the openssl.pkcs11.cnf configuration file. This may vary on other platforms and other operating system versions.
```
dynamic_path = /usr/lib64/engines-1.1/pkcs11.so
```

List available slots

First generate and insert your OCS in the normal way:

% pkcs11-tool --module /opt/nfast/toolkits/pkcs11/libcknfast.so -L

Available slots:
Slot 0 (0x1d622495): 6308-03E0-D947 Rt1
  token label        : accelerator
  token manufacturer : nCipher Corp. Ltd
  token model        :
  token flags        : rng, token initialized, PIN initialized, other flags=0x200
  hardware version   : 0.0
  firmware version   : 12.50
  serial num         : 6308-03E0-D947
  pin min/max        : 0/256
Slot 1 (0x1d622496): 6308-03E0-D947 Rt1 slot 0
  (empty)
Slot 2 (0x1d622497): 6308-03E0-D947 Rt1 slot 2
  (token not recognized)
Slot 3 (0x1d622498): 6308-03E0-D947 Rt1 slot 3
  (empty)

Configure the Apache HTTP Server to use the PKCS #11 engine

You need to update the Apache start-up file to tell it to use the new Open SSL configuration file, and to pass the necessary environment variables. These environment variables allow PKCS #11 engine to work.

Edit the file /usr/lib/systemd/system/httpd.service and add the environment variable under the “Service” section:
```
[Service]
Type=notify
Environment=LANG=C
Environment="OPENSSL_CONF=/etc/pki/tls/openssl.pkcs11.cnf"
```
Restart the daemon units:
```
% sudo systemctl daemon-reload
```
Restart the Apache service:
```
% sudo service httpd restart
```
Set the environment variable so that OpenSSL commands use the PKCS #11 engine:
```
% export OPENSSL_CONF=/etc/pki/tls/openssl.pkcs11.cnf
```

Test the PKCS #11 integration with the Apache HTTP Server and the HSM

This section describes the following scenarios that can be used by your organization according to the security guidelines that you follow:

Functionality test with non-HSM keys.
Module-only protection.
Softcard protection.
OCS protection.

A self-signed certificate is required for tests. In a production environment exposed to the internet, create the certificate request and sign it by the Trusted Certificate Authority.

Functionality test with non-HSM keys

You must now test that the Apache HTTP Server installation is operational and capable of serving https content. To do this, you must first create a software-based key and certificate.

Create a directory to hold the keys:
```
% mkdir keys; cd keys
```

Create a private key:

% openssl genrsa -engine pkcs11 2048 > pkcs11localhost.key

Create a self-signed certificate using this private key:

% openssl req -engine pkcs11 -new -x509 -days 365 -key pkcs11localhost.key -out pkcs11localhost.crt

Configure the Apache HTTP Server for SSL:

Copy the .key and .crt files:

% sudo cp pkcs11localhost.key /etc/pki/tls/private/.
% sudo cp pkcs11localhost.crt /etc/pki/tls/certs/.

Edit /etc/httpd/conf.d/ssl.conf and change the following lines to use the new .key and .crt files:

SSLCertificateFile /etc/pki/tls/certs/pkcs11localhost.crt
SSLCertificateKeyFile /etc/pki/tls/private/pcks11localhost.key
SSLCryptoDevice pkcs11

Restart the Apache service:
```
% sudo service httpd restart
```

Test the connection:

% openssl s_client -crlf -connect localhost:443 -CAfile pkcs11localhost.crt

CONNECTED(00000003)
depth=0 C = US, ST = FL, L = Sunrise, O = Entrust, OU = nShield, CN = www.entrust.com
verify return:1
---
Certificate chain
 0 s:/C=US/ST=FL/L=Sunrise/O=Entrust/OU=nShield/CN=www.entrust.com
   i:/C=US/ST=FL/L=Sunrise/O=Entrust/OU=nShield/CN=www.entrust.com
---
Server certificate
-----BEGIN CERTIFICATE-----
MIIDUDCCAjgCCQCx9G3D5F5XITANBgkqhkiG9w0BAQsFADBqMQswCQYDVQQGEwJV
UzELMAkGA1UECAwCRkwxEDAOBgNVBAcMB1N1bnJpc2UxEDAOBgNVBAoMB0VudHJ1
c3QxEDAOBgNVBAsMB25TaGllbGQxGDAWBgNVBAMMD3d3dy5lbnRydXN0LmNvbTAe
Fw0yMTAxMTExOTI5NDBaFw0yMjAxMTExOTI5NDBaMGoxCzAJBgNVBAYTAlVTMQsw
CQYDVQQIDAJGTDEQMA4GA1UEBwwHU3VucmlzZTEQMA4GA1UECgwHRW50cnVzdDEQ
MA4GA1UECwwHblNoaWVsZDEYMBYGA1UEAwwPd3d3LmVudHJ1c3QuY29tMIIBIjAN
BgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0/el/YjuScdeGwMEJicEbMWU4LdM
KRjj9Kp66YvjRThrdValJlCMkC5Gu+BRDg02OhPrl11w6z3TfUm0+Aa/BAkhUcec
VO4+6YZf6LXB3cgrkACr/5mxsthTkU218tT2TD6Rlm0phorQqsv3T2tA37URgMYm
h5G6wRuBWrOCbKjncjEzx475NYw0I6oetl97+gZKerKz0YjRvZ2p3IGcV6bSI/u7
r/T10XF9q8sc04kzNd4ssAOMzlkwmN7XKMeayatDSD6HxNAGXMyCaDW52PTLtvcy
rEIonIfufxOdb/322DkUB6LDjQQkq5v9smE9Hw7CeIt0CadJjdkePmiAVwIDAQAB
MA0GCSqGSIb3DQEBCwUAA4IBAQBgbzge0Gekt8xyjAn4v+0nuVm5k2CfQGNoFl+m
w1KeqsVAyRfwBNjRf7ceOfZTQrn1o44eOtTLmFlLfOyiQO2yYky6uJ28Lnv2Ju3A
nZj08Fnyn/AoaPFqAqAJbKffSesLdw8Qf1d9Wcr5mbJcDOiQQKOz/xHE1a9saf5X
7HfP1eN0no1OyjEs03hgxmaTPzB9EK26QpQPzZD99Z0a3O9qbcRboTIUYUF725c1
V1gzCxLABK/k6ahquEPKNxqpb0B+ccrfIhgVMe0x6HsAPi3/epAGj8HQybrG1C6q
A7ghHyWDR8pVrLmuuJmNtilN5woybmD13mqFBJZ3MbGy5zeK
-----END CERTIFICATE-----
subject=/C=US/ST=FL/L=Sunrise/O=Entrust/OU=nShield/CN=www.entrust.com
issuer=/C=US/ST=FL/L=Sunrise/O=Entrust/OU=nShield/CN=www.entrust.com
---
No client certificate CA names sent
Peer signing digest: SHA512
Server Temp Key: ECDH, P-256, 256 bits
---
SSL handshake has read 1543 bytes and written 415 bytes
---
New, TLSv1/SSLv3, Cipher is ECDHE-RSA-AES256-GCM-SHA384
Server public key is 2048 bit
Secure Renegotiation IS supported
Compression: NONE
Expansion: NONE
No ALPN negotiated
SSL-Session:
    Protocol  : TLSv1.2
    Cipher    : ECDHE-RSA-AES256-GCM-SHA384
    Session-ID: 381AF3AA705C0769B1E8118A3268621E1AD86176CFEE339D5CE966892D84EF66
    Session-ID-ctx:
    Master-Key: 5B787BFAC32C85916C85FB57BBE6DC43E36C7D6E4C6F095DD84F07DB642A8A3FE56F9FD789726FE79D9382D647862246
    Key-Arg   : None
    Krb5 Principal: None
    PSK identity: None
    PSK identity hint: None
    TLS session ticket lifetime hint: 300 (seconds)
    TLS session ticket:
    0000 - 3f 75 0d eb 59 32 90 56-17 6a 86 a5 28 2d ed 9b   ?u..Y2.V.j..(-..
    0010 - a8 a1 d7 2b ae 6d 4e d8-8d f9 7f d5 15 8c 2b d0   ...+.mN.......+.
    0020 - e0 9d d7 fc bb 61 4e 1f-63 61 41 03 5a 98 bf ed   .....aN.caA.Z...
    0030 - 50 b1 d0 36 30 a5 48 6c-d2 da 1a df 34 a5 57 02   P..60.Hl....4.W.
    0040 - d3 43 49 b5 27 dc 53 90-23 9e 1c 0d c2 54 d5 d3   .CI.'.S.#....T..
    0050 - e4 ca 32 e4 33 da 28 70-d3 1d 34 57 b1 10 c2 28   ..2.3.(p..4W...(
    0060 - 63 c5 5c 9a 9c ef d9 17-9c 72 65 41 35 eb 98 15   c.\......reA5...
    0070 - 2c 73 8a b1 99 4d 73 8f-7a b6 9b 4f 17 3c 91 4e   ,s...Ms.z..O.<.N
    0080 - 71 ab ad f8 ad a9 99 4d-fd 7b f2 db 12 1a ea 28   q......M.{.....(
    0090 - e2 1d b8 fe 67 9c 36 a3-e3 6a 81 5f 3c a1 a8 a6   ....g.6..j._<...
    00a0 - a9 7d bc 4c d6 a0 51 22-6d 51 87 70 bb b1 e0 4b   .}.L..Q"mQ.p...K
    00b0 - 95 94 60 0b e9 2e 49 8e-2d e5 4c 66 de 8f cc 1e   ..`...I.-.Lf....

    Start Time: 1610394029
    Timeout   : 300 (sec)
    Verify return code: 0 (ok)
---
closed

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)

Module protection

Create a key:

% generatekey -b -g -m1 pkcs11 plainname=modulersa type=rsa protect=module size=2048

key generation parameters:
 operation    Operation to perform               generate
 application  Application                        pkcs11
 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)
 plainname    Key name                           modulersa
 nvram        Blob in NVRAM (needs ACS)          no
Key successfully generated.
Path to key: /opt/nfast/kmdata/local/key_pkcs11_uae95fb7af0294b94f742b22c62812fd0f18e0cf24

Get the certificate using this key:

% openssl req -engine pkcs11 -x509 -out modulersa.crt -days 365 -key "pkcs11:token=accelerator;object=modulersa" -keyform engine -subj "/CN=modulersa"

Configure the Apache HTTP Server for SSL:

Copy the .crt file:

% sudo cp modulersa.crt /etc/pki/tls/certs/.

Edit /etc/httpd/conf.d/ssl.conf and change the following lines to use the new .key and .crt files:

SSLCertificateFile /etc/pki/tls/certs/modulersa.crt
SSLCertificateKeyFile "pkcs11:object=modulersa;token=accelerator"
SSLCryptoDevice pkcs11

Restart the Apache service:
```
% sudo service httpd restart
```

Test the connections:

% openssl s_client -crlf -connect localhost:443 -CAfile modulersa.crt

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)

Set up Softcard protection

To expose Softcards, the cknfast library has to be in load sharing mode (CKNFAST_LOADSHARING).

Edit the /opt/nfast/cknfastrc file, and add the following information before proceeding to set up Softcard protection:
```
CKNFAST_LOADSHARING=1
```
Create a Softcard:
```
% ppmk -n apachesoftcard
```
Use "123456" as the passphrase for the Softcard.

Create a key:

% generatekey -b -g -m1 pkcs11 plainname=softcardkey type=rsa protect=softcard recovery=no size=2048 softcard=apachesoftcard

key generation parameters:
 operation    Operation to perform               generate
 application  Application                        pkcs11
 protect      Protected by                       softcard
 softcard     Soft card to protect key           apachesoftcard
 recovery     Key recovery                       no
 verify       Verify security of key             yes
 type         Key type                           rsa
 size         Key size                           2048
 pubexp       Public exponent for RSA key (hex)
 plainname    Key name                           softcardkey
 nvram        Blob in NVRAM (needs ACS)          no
Please enter the pass phrase for softcard `apachesoftcard':

Please wait........
Key successfully generated.
Path to key: /opt/nfast/kmdata/local/key_pkcs11_ucb87f22b0df8d3b72a2f4c654ae1d3b0973b93de8-ddd20b997d276f3304e0011fc79971344c630b0f

Get the certificate using this key:

% openssl req -engine pkcs11 -x509 -out softcard.crt -days 365 -key "pkcs11:model=;token=apachesoftcard;pin-value=123456;object=softcardkey" -keyform ENGINE -subj "/CN=softcardkey"

The following error can appear:

engine "pkcs11" set.
Specified object not found
PKCS11_get_private_key returned NULL
cannot load Private Key from engine
139939575797568:error:80067065:pkcs11 engine:ctx_load_privkey:object not found:eng_back.c:975:
139939575797568:error:26096080:engine routines:ENGINE_load_private_key:failed loading private key:crypto/engine/eng_pkey.c:78:

If it does, make sure you expose the Softcards as described in this section, and run the command again.

Configure the Apache HTTP Server for SSL:

Copy the .crt file:

% sudo cp softcard.crt /etc/pki/tls/certs/.

Edit /etc/httpd/conf.d/ssl.conf and change the following lines to use the new .key and .crt files:

SSLCertificateFile /etc/pki/tls/certs/softcard.crt
SSLCertificateKeyFile "pkcs11:object=softcardkey;token=apachesoftcard;type=private?pin-value=123456"
SSLCryptoDevice pkcs11

Restart the Apache service:
```
% sudo service httpd restart
```

Test the connections:

% openssl s_client -crlf -connect localhost:443 -CAfile softcard.crt

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)

Set up OCS protection

Create an OCS:

% /opt/nfast/bin/createocs -m1 -s0 --persist -Q 1/1 -N apacheocs

Use "123456" as the passphrase.

Create a key:

% generatekey --cardset=apacheocs pkcs11 protect=token type=rsa size=2048 pubexp=65537 plainname=ocskey nvram=no recovery=yes

slot: Slot to read cards from? (0-3) [0] > 0
key generation parameters:
 operation    Operation to perform               generate
 application  Application                        pkcs11
 protect      Protected by                       token
 slot         Slot to read cards from            0
 recovery     Key recovery                       yes
 verify       Verify security of key             yes
 type         Key type                           rsa
 size         Key size                           2048
 pubexp       Public exponent for RSA key (hex)  65537
 plainname    Key name                           ocskey
 nvram        Blob in NVRAM (needs ACS)          no

Loading `apacheocs':
 Module 1: 0 cards of 1 read
 Module 1 slot 0: `apacheocs' #1
 Module 1 slot 2: Admin Card #1
 Module 1 slot 3: empty
 Module 1 slot 0:- passphrase supplied - reading card
Card reading complete.

Key successfully generated.
Path to key: /opt/nfast/kmdata/local/key_pkcs11_uc547fb435172da4280cc771eb3c2ad8b86ab06d0a-8d6a4394b07fc70148ff9c1f9960d279bf4a1d6b

Get the certificate using this key:

% openssl req -engine pkcs11 -x509 -out ocskey.crt -days 365 -key "pkcs11:token=apacheocs;object=ocskey;type=private?pin-value=123456" -keyform engine -subj "/CN=ocskey"

Configure the Apache HTTP Server for SSL:

Copy the .crt file:

% sudo cp ocskey.crt /etc/pki/tls/certs/.

Edit /etc/httpd/conf.d/ssl.conf and change the following lines to use the new .key and .crt files:

SSLCertificateFile /etc/pki/tls/certs/ocskey.crt
SSLCertificateKeyFile "pkcs11:object=ocskey;token=apacheocs;type=private?pin-value=123456"
SSLCryptoDevice pkcs11

Restart the Apache service:
```
% sudo service httpd restart
```

Test the connections:

% openssl s_client -crlf -connect localhost:443 -CAfile ocskey.crt

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)