Gemalto GemEngine support

To set up the Gemalto GemEngine within nevisProxy, you have to proceed in a similar way as if you would set up Apache with a Gemalto engine.

The next steps (with a sample configuration) show how to proceed. For more information, see also the Gemalto documentation Apache HTTP Server, Document Number: 007-011228-001, Rev. H.

This setup was tested with the HSM model "SafeNet Luna SA 1700 (generation 5)", the OpenSSL engine GemEngine version 1.4 for OpenSSL 1.1.1, the library "Cryptoki" version 6.3.0 and the program "sautil" version 2.0.0. Other versions of these tools should be compatible.

A similar setup was tested using the Azure Dedicated HSM service, with a Thales Luna 7 HSM model A790, the OpenSSL engine GemEngine version 1.6 for OpenSSL 3.0, sautil version 2.5.0, and the latest Cryptoki library version, from the universal Luna HSM Client 10.6.0. Integration process for the Azure Dedicated HSM may slightly differ from the example. For integration support with your GemEngine, consult your Thales/Gemalto contact.

General configuration

1. Copy the gem.so (this is the GemEngine library for OpenSSL 3.0, provided by Gemalto) to the openssl-engines directory (usually /usr/lib64/openssl/engines).

2. Adapt the /etc/Chrystoki.conf using the OptimizeApache.sh script provided by Gemalto. Something like the following sample script will be added:

   Misc = {
   Apache = 0;
   }
   GemEngine = {
   LibPath = /usr/safenet/lunaclient/lib/libCryptoki2.so;
   LibPath64 = /usr/safenet/lunaclient/lib/libCryptoki2_64.so;
   EngineInit = 0:10:11;
   DisableRand = 1;
   DisableDsa = 1;
   DisableEcdsa = 1;
   DisableCheckFinalize = 0;
   EnableRsaGenKeyPair = 1;
   EnableDsaGenKeyPair = 0;
   EnablePkeyMeths = 0;
   IntermediateProcesses = 0;
   }

• Check that DisableCheckFinalize and IntermediateProcesses are set to 0, add these lines if necessary. The other settings may vary depending on your HSM configuration.
• Check that the nevisProxy user can read the /etc/Chrystoki.conf file. See the field User in the Server tag of your navajo.xml file for its name.

3. Open a session to SafeNet Luna HSM using the sautil provided by Gemalto:

   sautil -v -s 0 -i 10:11 -o -q

Gemalto GemEngine support for frontend connections

To set up the Gemalto Engine for SSL-key verification of frontend connections, proceed as follows:

1. Generate a private key and a certificate with your HSM according to your PKI policy. These files are referred to as gemKey.pem and gemCert.pem in this section. See the section: Generation of test private keys and certificates, further below for an example of generating a test certificate.

2. Specify the following settings in the navajo.xml file:

   • In the <SSL> section:

    SSLCertificateFile="/var/opt/nevisproxy/<instance>/certs/gemCert.pem"
    SSLCertificateKeyFile="/var/opt/nevisproxy/<instance>/certs/gemKey.pem"
   • In the <Server> section:

    SSLCryptoDevice="gem"
   

3. In env.conf file you have to set:

   OPENSSL_ENGINES=/usr/lib64/openssl/engines
   export OPENSSL_ENGINES
   

4. Make sure you have an open session to SafeNet Luna HSM as described in the section: General configuration, above.

5. Restart nevisProxy after you have made the previously described changes.

Gemalto GemEngine support for backend connections

To set up the Gemalto Engine for SSL-key verification on the BackendConnectorServletor the HttpsConnectorServlet, proceed as follows:

1. Generate a private key and a certificate with your HSM according to your PKI policy. These files are referred to as gemClientKey.pem and gemClientCert.pem in this section. Refer to the section: Generation of test private keys and certificates, further below for an example of generating a test certificate.

2. Set the signed certificate and key.

   • For the BackendConnectorServlet, set the signed certificate and key as the Secure.ClientCertificateFile and Secure.ClientKeyFile :

   
   <servlet>
       <servlet-name>BackendConnectorServlet</servlet-name>
       <servlet-class>ch::nevis::nevisproxy::servlet::connector::http::BackendConnectorServlet</servlet-class>
       <init-param>
           <param-name>InetAddress</param-name>
           <param-value><backendHost>:<backendPort></param-value>
       </init-param>
       <init-param>
           <param-name>Secure.ClientCertificateFile</param-name>
           <param-value>/var/opt/nevisproxy/<instance>/certs/gemClientCert.pem</param-value>
       </init-param>
       <init-param>
           <param-name>Secure.ClientKeyFile</param-name>
           <param-value>/var/opt/nevisproxy/<instance>/certs/gemClientKey.pem</param-value>
       </init-param>
       <init-param>
           <param-name>Secure.CACertificateFile</param-name>
           <param-value><yourCaCert>.pem</param-value>
       </init-param>
   </servlet>
   
   • For the HttpsConnectorServlet, set the signed certificate and key as the SSLClientCertificateFile and SSLClientKeyFileof the HttpsConnectorServlet:

   <servlet>
       <servlet-name>HttpsConnectorServlet</servlet-name>
       <servlet-class>ch::nevis::isiweb4::servlet::connector::http::HttpsConnectorServlet</servlet-class>
       <init-param>
           <param-name>InetAddress</param-name>
           <param-value><backendHost>:<backendPort></param-value>
       </init-param>
       <init-param>
           <param-name>SSLClientCertificateFile</param-name>
           <param-value>/var/opt/nevisproxy/<instance>/certs/gemClientCert.pem</param-value>
       </init-param>
       <init-param>
           <param-name>SSLClientKeyFile</param-name>
           <param-value>/var/opt/nevisproxy/<instance>/certs/gemClientKey.pem</param-value>
       </init-param>
       <init-param>
           <param-name>SSLCACertificateFile</param-name>
           <param-value><yourCaCert>.pem</param-value>
       </init-param>
   </servlet>
   

3. Set the following bc-property in the bc.property file:

   bc.net.ssl.SSLCryptoDevice=gem

4. In the file env.conf,specify the following setting:

   OPENSSL_ENGINES=/usr/lib64/openssl/engines
   export OPENSSL_ENGINES

5. Make sure you have an open session to SafeNet Luna HSM as described in the section General Configuration further above.

6. Restart nevisProxy after you have made the previously described changes.

Possible limitations

Depending on the engine, other BackendConnectorServlets or HttpsConnectorServlets may no longer work correctly if they use certificates that are not created by the engine itself.

Generation of test private keys and certificates

This section provides examples for generating private keys and certificates for testing purposes.

Frontend connections

1. Make sure you have an open session to SafeNet Luna HSM as described in the section: General Configuration, further above.

2. Generate a private key:

   sautil -v -s 0 -i 10:11 -g 2048 -f /var/opt/nevisproxy/<instance>/certs/gemKey.pem

3. Generate a self-signed certificate:

   OPENSSL_ENGINES=/usr/lib64/openssl/engines LD_LIBRARY_PATH=/opt/nevisproxy/lib/
   /opt/nevisproxy/bin/openssl req -engine gem -new -nodes -key
   /var/opt/nevisproxy/<instance>/certs/gemKey.pem -out
   /var/opt/nevisproxy/<instance>/certs/gemCert.req -days 1000 -verify
   OPENSSL_ENGINES=/usr/lib64/openssl/engines LD_LIBRARY_PATH=/opt/nevisproxy/lib/
   /opt/nevisproxy/bin/openssl x509 -engine gem -req -days 1000 -in
   /var/opt/nevisproxy/<instance>/certs/gemCert.req -signkey
   /var/opt/nevisproxy/<instance>/certs/gemKey.pem -out
   /var/opt/nevisproxy/<instance>/certs/gemCert.pem

Backend connections

1. Make sure you have an open session to SafeNet Luna HSM as described in the section General Configuration further above.

2. Generate a private key:

   sautil -v -s 0 -i 10:11 -g 2048 -f /var/opt/nevisproxy/<instance>/certs/gemClientKey.pem

3. Sign the key with a CA that is trusted by your backend. For example:

   cd /var/opt/nevisproxy/<instance>/certs
   OPENSSL_ENGINES=/usr/lib64/openssl/engines
   /opt/nevisproxy/bin/openssl req -engine gem -new -key gemClientKey.pem -out gemClient_req.pem
   OPENSSL_ENGINES=/usr/lib64/openssl/engines
   /opt/nevisproxy/bin/openssl ca -engine gem -days 365 -keyfile <yourCaKey>.pem -cert <yourCaCert>.pem -outdir . -in gemClient_req.pem -out gemClientCert.pem

Recovery after connection failure

Sometimes, nevisProxy fails to connect to the HSM. According to Gemalto, the GemEngine only supports automatic connection recovery if you use an HSM High Availability (HA) setup with HSM version 6.2.2 and above. For more details on this setup, get in touch with Thales/Gemalto directly.

For all other cases, you need to perform the following steps to recover from a failed connection:

1. Close the existing connection to the HSM:

   sautil -v -s 0 -i 10:11 -c

2. Open a new one:

   sautil -v -s 0 -i 10:11 -o -q

3. Restart nevisProxy:

   nevisproxy <instance> restart