Before proceeding with the integration, ensure that you have installed an Apache Web Server and OpenSSL on your Linux and that the CryptoServer is available on the network. The following assumptions for the naming of installation directories, file names or network locations are provided for further description:
-
CryptoServer: Available on the network at IP address 0.2.2, on TCP port 3001.
-
PKCS#11 R3 configuration file:
/etc/utimaco/cs_pkcs11_R3.cfg -
PKCS#11 library:
/usr/lib/libcs_pkcs11_R3.so -
Environment variable:
CS_PKCS11_R3_CFG=/etc/utimaco/cs_pkcs11_R3.cfg
Check that the environment variable for PKCS#11 was permanently added to the system and that the configuration file for PKCS#11 is present at the location given by the CS_PKCS11_R3_CFG variable:
|
|
Check that you can browse the content of the configuration file (cs_pkcs11_R3.cfg). Verify that the setting for Device in the section [CryptoServer] in the configuration file points to the current location of the CryptoServer in the network. One way to test this is to establish a connection with telnet at the IP address and the port specified for the device e.g.
|
|
A connection should be established with CryptoServer and after supplying some characters followed by Enter, the server should terminate the connection.
Note the settings Logpath and Logging (log level). At the specified location, a log with the PKCS#11 operations called cs_pkcs11_R3.log is created. The log is useful for debugging and testing the PKCS#11 operations.
The script that starts Apache erases all environment variables, so for the Apache, the CS_PKCS11_R3_CFG environment variable has to be set again. To set this variable for Apache, add in the file envvars this line:
|
|
The location of the envvars file is in the root directory of the Apache Web Server. The path to root directory for the Apache can be set at runtime with the -d option or in the configuration file. The default location for root directory can be found when apache is launched with -V option under HTTPD_ROOT.
For Ubuntu , the envvars location is: /etc/apache2/envvars
Depending on the version of the Apache Web Server, there are two main scenarios that can be implemented to have the private key stored securely inside the HSM:
-
The Apache Web Server version is at least 2.4.42, or the system administrator can upgrade Apache to a version beyond 2.4.42. In this case, the Apache Web Server works with the HSM out of the box. What needs to be done in this case is to install an engine for OpenSSL supporting PKCS#11 and configure OpenSSL to work with that engine. After that, the private key used by the Apache Web Server for https has to be moved (imported) inside the HSM. The last step is to configure the Apache Web Server to use the private key stored inside the HSM.
-
The Apache Web Server version is earlier than 2.4.42 and the Apache Web Server cannot be upgraded to a later version for various reasons. In this case, a special PKCS#11 engine for OPENSSL needs to be used. This engine has the capability to use the private key from HSM for cryptographic operation needed by https protocol. For this to work, the private key is imported into the HSM and then a special reference key file will be created. This file looks like a normal private key, with a PEM extension, but does not contain the actual key, instead it contains a reference to the private key inside the HSM.
In both scenarios after importing the private key inside the HSM, the private key should be deleted from the filesystem. This ensures that hacker are not able to steal the private key, even if they get root access to the server.