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. |
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:
HOME = .
openssl_conf = openssl_def
[openssl_def]
engines = engine_section
[engine_section]
pkcs11 = pkcs11_section
[pkcs11_section]
engine_id = pkcs11
dynamic_path = /usr/lib64/engines-3/pkcs11.so #RHEL 9
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 = localhost
[v3_req]
subjectAltName = @alt_names
extendedKeyUsage = clientAuth, serverAuth
[alt_names]
DNS.1 = www.entrust.com
IP.1 = 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: (rdrand) Intel RDRAND engine [RAND] [ available ] (dynamic) Dynamic engine loading support [ unavailable ] SO_PATH, NO_VCHECK, ID, LIST_ADD, DIR_LOAD, DIR_ADD, LOAD (pkcs11) pkcs11 engine [RSA, rsaEncryption, id-ecPublicKey] [ available ] SO_PATH, MODULE_PATH, PIN, VERBOSE, QUIET, INIT_ARGS, FORCE_LOGIN, RE_ENUMERATE
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 theopenssl.pkcs11.cnf
configuration file. This may vary on other platforms and other operating system versions.dynamic_path = /usr/lib64/engines-3/pkcs11.so #RHEL 9
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] 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:
-
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. If using a FIPS Level 3 world file, have an OCS card connected to provide FIPS Authorization. |
Module protection
-
Edit the
/opt/nfast/cknfastrc
file:CKNFAST_FAKE_ACCELERATOR_LOGIN=1
-
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
-
To expose OCS card, 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 OCS protection:CKNFAST_LOADSHARING=1
-
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)
-