Apache HTTP Server

Configure Luna HSM

Set up GemEngine Toolkit

Ensure that the HSM is set up, initialized, provisioned, and ready for deployment. For more information, refer to Luna HSM documentation.

Create a partition that will be later on used by Apache HTTP Server.

Create and exchange certificate between the Luna Network HSM and client system. Register client and assign partition to create an NTLS connection.

Initialize Crypto Officer and Crypto User roles for the registered partition.

Run the following command to verify that the partition has been successfully registered and configured:

/usr/safenet/lunaclient/bin/lunacm 

Upon successful execution, you should observe an output similar to the example provided below:

lunacm (64-bit) v10.4.0-417. Copyright (c) 2021 Thales Group. All rights reserved. 
Available HSMs:

Slot Id ->                           1
Label ->                             apache1
Serial Number ->                     1312109862208
Model ->                             LunaSA 7.7.1
Firmware Version ->                  7.7.1
Bootloader Version  ->               1.1.2
Configuration ->                     Luna User Partition With SO (PW) Key Export With Cloning Mode
Slot Description ->                  Net Token Slot
FM HW Status ->                      Non-FM

Slot Id ->                           2
Label ->                             apache2
Serial Number ->                     1280780175894
Model ->                             LunaSA 7.7.1
Firmware Version ->                  7.7.1
Bootloader Version  ->               1.1.2
Configuration ->                     Luna User Partition With SO (PW) Key Export With Cloning Mode
Slot Description ->                  Net Token Slot
FM HW Status ->                      Non-FM

Slot Id ->                           9
HSM Label ->                         HA
HSM Serial Number ->                 11312109862208
HSM Model ->                         LunaVirtual
HSM Firmware Version ->              7.7.1
HSM Configuration ->                 Luna Virtual HSM (PW) Key Export With Cloning Mode
HSM Status ->                        N/A - HA Group

Refer to Luna HSM documentation for detailed steps on creating NTLS connection, initializing the partitions, and assigning various user roles.

For proper configuration of a PED-based Luna HSM, it is recommended to activate partition policies 22 and 23, allowing for both activation and auto-activation.

Open the configuration file:

/etc/Chrystoki.conf

Locate the Presentation section in the file.

Update or add the following line within the Presentation section:

   Presentation = {
       OneBaseSlotId = 1;
   }

By making this change, you ensure that the Luna Client is configured to use the correct slot ID required by the LunaCA3 engine.

Open the configuration file for your Luna HSM.

Look for the [Misc] section within the configuration file.

Add or modify the following setting within the [Misc] section:

RSAKeyGenMechRemap=1

This setting instructs the Luna HSM to redirect older key generation mechanisms to the newly approved mechanism when the HSM is operating in FIPS mode.

Transfer the downloaded .zip file to your client workstation using pscp, scp, or other secure means

This integration has been certified on the RHEL platform.

Extract the .zip file into a directory on your client workstation.

Extract or untar the appropriate client package for your operating system. Do not extract to a new subdirectory; place the files in the client install directory.

tar -xvf cvclient-min.tar

Run the setenv script to create a new configuration file containing information required by the Luna Cloud HSM service.

source ./setenv

To add the configuration to an already installed UC client, use the –addcloudhsm option when running the setenv script.

Run the LunaCM utility and verify that the Cloud HSM service is listed.

If your organization requires non-FIPS algorithms for your operations, ensure that the Allow non-FIPS approved algorithms check box is checked. For more information, refer to Supported Mechanisms.

Visit the Thales Customer Support portal.

Use the appropriate Doc ID to find and download your desired version of the GemEngine toolkit:

• GemEngine v1.6: Doc ID KB0026742

• GemEngine v1.5: Doc ID KB0024584

• GemEngine v1.3: Doc ID KB0017806

• GemEngine v1.2: Doc ID KB0016309

Ensure you are logged into your Thales Customer Support account to access the downloads.

It is recommended that you familiarize yourself with the Apache HTTP Server. For more information, refer to the Apache HTTP Server Documentation.

Download and extract OpenSSL source tarball.

• Download: Obtain the OpenSSL source tarball from the OpenSSL Source.

• Extract: Use the following commands to download and extract the tarball:

wget https://www.openssl.org/source/openssl-3.0.7.tar.gz
tar xvfz openssl-3.0.7.tar.gz

Download and extract Apache (httpd) source tarball.

• Download: Obtain the Apache HTTP Server source tarball from the Apache HTTP Server Download. Move the downloaded .tar.gz file into the gemengine directory.

• Extract: Use the following commands to download and extract the tarball:

wget https://downloads.apache.org/httpd/httpd-2.4.55.tar.gz
tar xzvf httpd-2.4.55.tar.gz

Download and extract APR source tarball.

• Download: Obtain the APR (Apache Portable Runtime) source tarball from the APR Download. Move the downloaded .tar.gz file into the gemengine directory.

• Extract: Use the following commands to download and extract the tarball:

wget https://downloads.apache.org/apr/apr-1.7.0.tar.gz
tar xzvf apr-1.7.0.tar.gz

Download and extract APR-util source tarball.

• Download: Obtain the APR-util source tarball from the APR Download. Move the downloaded .tar.gz file into the gemengine directory.

• Extract: Use the following commands to download and extract the tarball:

wget https://downloads.apache.org/apr/apr-util-1.6.1.tar.gz
tar xzvf apr-util-1.6.1.tar.gz

Download and extract APR-iconv source tarball.

• Download: Obtain the APR-iconv source tarball from the APR Download. Move the downloaded .tar.gz file into the gemengine directory.

• Extract: Use the following commands to download and extract the tarball:

wget https://downloads.apache.org/apr/apr-iconv-1.2.2.tar.gz
tar xzvf apr-iconv-1.2.2.tar.gz

Ensure you have the following source paths ready:

• OpenSSL source path

• Apache source path

• APR source path

• APR-iconv source path

• APR-util source path

Navigate to the gemengine directory and run the following command to configure the build. Replace the placeholder paths with your actual source paths:

./gembuild config --openssl-source=[openssl-source path] --apache-source=[httpd-src path] --apr-source=[apr-src path] --apr-iconv-source=[iconvsrc path] --apr-util-source=[utilsrc path]  --prefix=/usr/local --config-bits=64 --fips-module=no

Run the following commands to compile and install OpenSSL:

./gembuild openssl-build
./gembuild openssl-install

Execute the following commands to compile, install, and verify the Gem dynamic engine:

./gembuild engine-build
./gembuild engine-install
/usr/local/ssl/bin/openssl engine gem -v

Expected output:

(gem) Gem engine support
enginearg, openSession, closeSession, login, logout, engineinit,
CONF_PATH, ENGINE_INIT, ENGINE2_INIT,engine2init,DisableCheckFinalize,
SO_PATH, GET_HA_STATE, SET_FINALIZE_PENDING, SKIP_C_INITIALIZE,
IntermediateProcesses

Run the following commands to compile and install the sautil command:

./gembuild sautil-build
./gembuild sautil-install

By default, this installs the sautil command to [prefix]/sautil/bin/sautil, where [prefix] is the directory specified with the --prefix option in step 1. If you want to install the sautil command in a different location, use the --sautil-prefix option. You can either redo this step with the option or specify it during the installation command: ./gembuild sautil-install --sautil-prefix=[desired-directory].

Update the PATH environment variable to include the directories for OpenSSL and sautil. For example:

export PATH=/usr/local/ssl/bin:/usr/local/sautil/bin:$PATH

Finally, compile and install Apache by running the following command:

./gembuild apache-build

In the gemengine directory, execute the following command to configure the Luna Network HSM/Luna PCI-E HSM configuration file (/etc/Chrystoki.conf) for Apache:

./Optimize.sh fork

This command will update the Luna HSM configuration file for the Apache HTTP Server to include the following settings:

Luna Network HSM
Misc = {
   PE1746Enabled = 0;
   Apache = 0;
}
GemEngine = {
   LibPath = /usr/safenet/lunaclient/lib/libCryptoki2.so;
   LibPath64 = /usr/safenet/lunaclient/lib/libCryptoki2_64.so;
   EnableDsaGenKeyPair = 1;
   EnableRsaGenKeyPair = 1;
   DisablePublicCrypto = 1;
   EnableRsaSignVerify = 1;
   EnableLoadPubKey = 1;
   EnableLoadPrivKey = 1;
   DisableCheckFinalize = 0;
   DisableEcdsa = 1;
   DisableDsa = 0;
   DisableRand = 0;
   EngineInit = 1:10:11;
}

Use the sautil utility to open a session on the Luna HSM slot by running the following command:

/usr/local/sautil/bin/sautil -v -s 1 -i 10:11 -o -q

Create a text file to store the partition crypto officer password. Use the following command, replacing [partition_password] and [path_to_my_passfile] with your actual password and desired file path:

echo [partition_password] > [path_to_my_passfile]/passfile

Open the Chrystoki.conf file located in your configuration directory. Add the following text to the GemEngine section. Replace the placeholders with the actual paths to LibCryptoki2.so and LibCryptoki2_64.so:

   GemEngine = {
      LibPath = [path_to_LibCryptoki2.so];
      LibPath64 = [path_to_LibCryptoki2_64.so];
      EnableDsaGenKeyPair = 1;
      EnableRsaGenKeyPair = 1;
      DisablePublicCrypto = 1;
      EnableRsaSignVerify = 1;
      EnableLoadPubKey = 1;
      EnableLoadPrivKey = 1;
      DisableCheckFinalize = 1;
      DisableEcdsa = 1;
      DisableDsa = 0;
      DisableRand = 0;
      EngineInit = [Partition_Label]:0:0:passfile=[path_to_my_passfile]/passfile;
      EnableLoginInit = 1;
   }

Replace [Partition_Label] with the actual label of your partition and ensure passfile points to the correct path of the file containing the CO password.

In the Misc section of the Chrystoki.conf file, add the following flag and save the changes. Make sure not to delete the default values already present in the Misc section:

   Misc = {
      FinalizeOnClose = 1;
   }

Open a terminal and go to your gemengine directory.

Run the following command to generate RSA keys for Apache:

./gembuild apache-genrsa

This command generates a self-signed certificate, which is suitable for testing environments. For production environments, it is recommended to use a CA-signed certificate.

Execute the following command to generate keys on Luna HSM and save the certificate request and key reference:

openssl req -engine gem -new -newkey rsa:2048 -nodes -sha256 -keyout server.key -out server.csr -keyform engine

The private key reference is saved in server.key on the HSM.

Save the Certificate Signing Request (CSR) in server.csr. This file needs to be submitted to a Certificate Authority (CA) for obtaining a CA-signed certificate.

Run the command below to verify the generated key pair on Luna HSM:

/bin/64/cmu list

Provide the partition password when prompted.

Submit the CSR file (server.csr) to a trusted CA, such as VeriSign or Entrust. The CA will authenticate the request and provide a signed certificate or a certificate chain.

Save the CA-signed certificate obtained from the CA (e.g., server.pem) in the system directory. Update the Apache HTTP Server configuration to reference your key (server.key) and CA-signed certificate (server.pem).

Execute the following command to generate a private key on Luna HSM and save the key reference:

openssl genrsa -engine gem -out server.key 2048

server.key serves as the reference to the Private Key generated on the HSM. Keep this file secure as you will need it later.

Generate a self-signed certificate for testing purposes with the following command:

openssl req -new -engine gem -x509 -key server.key -sha256 -out server.pem

server.pem will be the self-signed certificate in PEM format, suitable for testing purposes.

Navigate to the Apache installation directory and locate the httpd.conf file. Update the ServerName field with the hostname or IP address of the server, matching the Common Name (CN) specified in your SSL certificate.

Go to the SSL configuration directory (conf/extra, e.g., /usr/local/apache2/conf/extra). Edit the httpd-ssl.conf file and adjust the Virtual Host section as follows:

[VirtualHost Hostname_or_IP_Address:443]

Replace Hostname_or_IP_Address with your actual server hostname or IP address.

Start the Apache server using the following command:

/usr/local/apache2/bin/apachectl -k start

Open a web browser and access your HTTPS server:

https://:443

Accept the SSL certificate when prompted by the browser.

Follow the steps in the Configure GemEngine for OpenSSL on UNIX section to configure OpenSSL to use GemEngine.

Identify the directory where your SSL private key and certificate are stored.

Run the following command to extract the public key from the SSL private key:

openssl rsa -in /usr/local/apache2/conf/ssl.key/server.key -pubout -out /usr/local/apache2/conf/ssl.crt/pubkey.pem

Use the command below to convert the private key to PKCS#8 format:

openssl pkcs8 -in /usr/local/apache2/conf/ssl.key/server.key -topk8 -nocrypt -out /usr/local/apache2/conf/ssl.key/privatekey.pem

Utilize the CMU utility provided with Luna Client to import the public and private keys to the HSM.

For Public Key:

[LunaClient Installation Directory]/bin/cmu import -inputFile /usr/local/apache2/conf/ssl.crt/pubkey.pem -label apache2_public_key -pubkey=rsa

For Private Key:

[LunaClient Installation Directory]/bin/cmu importkey -PKCS8 -in /usr/local/apache2/conf/ssl.key/privatekey.pem -keyalg RSA

Ensure the keys are generated on the Luna HSM partition and note the private key handle for later use:

/bin/cmu list

Example output:

Certificate Management Utility (64-bit) v10.5.0-470. Copyright (c) 2022 SafeNet. All rights reserved.

handle=2000001  label= CMU Unwrapped RSA Private Key
handle=2000002  label= apache2_public_key

If you have multiple keys and would like to easily identify them, you can assign labels. Use the following command:

[LunaClient Installation Directory]/bin/cmu setattribute -handle=2000001 -label=apache2_priv_key

This step is optional.

Check that the private key label matches the public key label:

[LunaClient Installation Directory]/bin/cmu list -password userpin1

Example output:

Certificate Management Utility (64-bit) v10.5.0-470. Copyright (c) 2021 SafeNet. All rights reserved.

handle=2000001  label= apache2_priv_key
handle=2000002  label= apache2_public_key

Copy the sautil utility to /usr/local/bin according to your OpenSSL version:

cp [gem-engine directory]/builds/linux/rhel/64/3.0/sautil /usr/local/bin

Use the sautil utility to create a private key reference to the actual private key imported in Luna HSM:

sautil -v -s 1 -i 10:11 -a 0:RSA -f /usr/local/apache2/conf/ssl.key/HSMKey_ref_new.pem -o -p userpin1 -c

After successful completion, HSMKey_ref.pem will be generated. You need to specify HSMKey_ref.pem in the SSL settings in extras/httpd-ssl.conf file.

Delete the private key generated by OpenSSL that was used before importing the key into HSM, as well as the PKCS#8 format key generated in step 4.

rm /usr/local/apache2/conf/ssl.key/server.key
rm /usr/local/apache2/conf/ssl.key/privatekey.pem

Modify the /usr/local/apache2/conf/extra/httpd-ssl.conf file by adding or updating the following lines:

    SSLCryptoDevice gem

    [VirtualHost _default_:443]
      SSLCertificateFile /usr/local/apache2/conf/ssl.crt/server.pem
      SSLCertificateKeyFile /usr/local/apache2/conf/ssl.key/HSMKey_ref.pem
    [/VirtualHost]

Restart the Apache HTTP Server to apply the changes:

/usr/local/apache2/bin/apachectl -k restart

Open a web browser and access the Apache HTTP Server over port 443. Accept the SSL certificate when prompted:

https://[HostName or IP Address}:443

Install GemEngine Toolkit: Extract sautil-win64-openssl-x.x.xx.tar.gz and ssl-win64-openssl-x.x.xx.tar.gz from [engine-directory]\builds\win to C:\.

Update System Path: Add C:\cygwin\usr\local\sautil\bin and C:\cygwin\usr\local\ssl\bin to your system path via Control Panel -> System -> Advanced -> Environment Variables -> System Variables.

Rename OpenSSL Executable: In C:\Apache24\bin, rename openssl.exe to openssl.exe.old.

Verify OpenSSL Directory: Run openssl version -d to check the OpenSSL directory. It should be C:\cygwin\usr\local\ssl.

Copy Configuration File: Copy openssl.cnf from C:\Apache24\conf to the directory specified in the OpenSSL directory output.

Copy Engines Directory: Copy the engines directory from C:\cygwin\usr\local\ssl\lib to C:\Apache24\lib.

Add the following lines to C:\Program Files\SafeNet\LunaClient\crystoki.ini:

[GemEngine]
LibPath = {LunaClient Installation Directory]\win32\cryptoki.dll
LibPath64 = [LunaClient Installation Directory]\cryptoki.dll
EnableDsaGenKeyPair = 1
EnableRsaGenKeyPair = 1
DisablePublicCrypto = 1
EnableRsaSignVerify = 1
EnableLoadPubKey = 1
EnableLoadPrivKey = 1
DisableCheckFinalize = 1
DisableEcdsa = 1
DisableDsa = 0
DisableRand = 0
EngineInit = 0:10:11

Replace [LunaClient Installation Directory] with the actual path. Adjust 0 as the slot ID and 10:11 as the application ID in EngineInit.

Open a command prompt and run the following command to initiate a persistent session with the HSM:

sautil.exe -v -s 0 -i 10:11 -o –q

Replace 0 with the slot ID and 10:11 with the application ID. Enter the partition password when prompted.

Refer to README-GEM-CONFIG in [GemEngine_Directory]\docs for more login methods and session details.

Create a text file named passfile in [path_to_my_passfile] and store the partition password in it.

Open the crystoki.ini file and add the following configuration under the [GemEngine] section:

[GemEngine]
LibPath = [path to LibCryptoki2.so]
LibPath64 = [path to LibCryptoki2_64.so]
EnableDsaGenKeyPair = 1
EnableRsaGenKeyPair = 1
DisablePublicCrypto = 1
EnableRsaSignVerify = 1
EnableLoadPubKey = 1
EnableLoadPrivKey = 1
DisableCheckFinalize = 1
DisableEcdsa = 1
DisableDsa = 0
DisableRand = 0
EngineInit = [Partition Label]:0:0:passfile=[path_to_my_passfile]/passfile;
EnableLoginInit = 1

Replace [path to LibCryptoki2.so] and [path to LibCryptoki2_64.so] with the actual paths to the libraries. Replace [Partition Label] with the actual label of your partition. Ensure passfile=[path_to_my_passfile]/passfile points to the correct path of the passfile you created.

Ensure that [Partition Label] is replaced with the actual label of your partition, and passfile points to the actual path of the file containing the partition password.

Generate a private key by navigating to the directory where OpenSSL is installed, typically C:\Apache24\conf; and then the following command to generate a private key on the HSM:.

openssl.exe genrsa -engine gem 2048 > C:\Apache24\conf\server.key

This command generates a private key using the GemEngine and saves it as C:\Apache24\conf\server.key.

Use the following OpenSSL command to generate a self-signed certificate:

openssl.exe req -engine gem -new -x509 -days 365 -key C:\Apache24\conf\server.key -out C:\Apache24\conf\server.crt -keyform engine

This command generates a self-signed certificate (server.crt) valid for 365 days, using the private key stored in C:\Apache24\conf\server.key and leveraging the GemEngine for operations.

Uncomment the following lines in C:\Apache24\conf\httpd.conf to enable SSL modules and include SSL configuration:

LoadModule socache_shmcb_module modules/mod_socache_shmcb.so
LoadModule ssl_module modules/mod_ssl.so
Include conf/extra/httpd-ssl.conf

Add or modify the following lines in C:\Apache24\conf\extra\httpd-ssl.conf to configure SSL settings, specifying the paths to your server key and certificate:

SSLCryptoDevice gem

[VirtualHost _default_:443]
  SSLCertificateKeyFile C:/Apache24/conf/server.key
  SSLCertificateFile C:/Apache24/conf/server.crt
[/VirtualHost]

Start the Apache HTTP Server by executing the following command:

C:\Apache24\bin\httpd.exe -k start

Access the Apache HTTP Server securely over HTTPS by entering the following URL in your web browser, replacing with your server's hostname or IP address:

https://[HostName or IP Address]:443

Ensure the paths C:/Apache24/conf/server.key and C:/Apache24/conf/server.crt are correctly set to your private key and certificate files.

Follow the steps outlined in the "Configuring GemEngine for OpenSSL on Windows" section to configure OpenSSL to use the GemEngine for cryptographic operations.

Identify the directory where the SSL private key (server.key) and certificate (server.crt) are stored. This directory will be used for further operations.

Extract the public key of the SSL certificate (server.crt) using the following command:

openssl rsa -in server.key -pubout -out pubkey.pem

This command extracts the public key from server.key and saves it in pubkey.pem.

Convert the SSL private key (server.key) to PKCS#8 format using the following command:

openssl pkcs8 -in server.key -topk8 -nocrypt -out privatekey.pem

This command converts the private key to PKCS#8 format (privatekey.pem) without encryption, which is compatible with Luna HSM.

Import keys to Luna HSM using CMU utility:

For Public Key:

[LunaClient Installation Directory]\Cmu.exe import -inputFile pubkey.pem -label apache_pub_key -pubkey=rsa

For Private Key:

[LunaClient Installation Directory]\Cmu.exe importkey -PKCS8 -in privatekey.pem -keyalg RSA

Run the following command to verify that the keys are generated on the Luna HSM partition and note the private key handle for later use:

[LunaClient Installation Directory]\Cmu.exe list -password userpin1

Example output:

Certificate Management Utility (64-bit) v10.5.0-470. Copyright (c) 2022 SafeNet. All rights reserved.
handle=2000001  label=apache_pub_key
handle=2000002  label=CMU Unwrapped RSA Private Key

Generate a Private Key Reference for the actual private key imported into Luna HSM:

sautil.exe -v -s 0 -i 0:0 -a 0:RSA -f HSMKey_ref.pem -o -q -c

Provide the HSM partition CO password and key handle when prompted. After successful completion, HSMKey_ref.pem will be generated.

Specify HSMKey_ref.pem in the SSL settings in extras/httpd-ssl.conf file for Apache HTTP Server.

Remove the private key generated by OpenSSL (server.key) and the PKCS#8 format key (privatekey.pem) generated in step 4, as they are no longer needed.

Add or modify the following lines in C:\Apache24\conf\extras\httpd-ssl.conf to reflect the HSM key reference and certificate configuration:

SSLCryptoDevice gem

[VirtualHost _default_:443]
  SSLCertificateKeyFile ${SRVROOT}/conf/HSMKey_ref.pem
  SSLCertificateFile ${SRVROOT}/conf/server.crt
  # Add the following line if the certificate is signed by a root CA
  # SSLCertificateChainFile ${SRVROOT}/conf/server-ca.crt
[/VirtualHost]

Replace ${SRVROOT} with the actual Apache server root directory path.

Restart the Apache HTTP Server to apply the configuration changes:

C:\Apache24\bin\httpd.exe -k restart

Open a web browser and access the Apache HTTP Server securely over port 443:

https://[HostName or IP Address]:443

Accept the certificate when prompted.