Generating a new SSL certificate and key on a ProtectServer 3 HSM

To integrate Apache Tomcat with a ProtectServer 3 HSM by generating a new SSL certificate, you must complete the following steps:

1. Configure Java for a ProtectServer 3 HSM

2. Generate key materials on the ProtectServer 3 HSM

3. Configure SSL for Apache Tomcat

Configuring Java for a ProtectServer 3 HSM

Tomcat uses Java JSSE for SSL/TLS support. Configure Java to add support for PKCS#11 that will be consumed by Tomcat for securing the SSL keys and certificates on the ProtectServer 3 HSM.

To configure PKCS#11 in Java

1. Log on to the Apache Tomcat server as root or as another user with administrative privileges.

2. Ensure that the JAVA_HOME and PATH variables are set.

   # export JAVA_HOME=<JDK_installation_directory>
   # export PATH=$JAVA_HOME/bin:$PATH

   Copy
   

   Note

   On Windows, set the JAVA_HOME and PATH System variables under System > Advanced system settings > Environment Variables…

3. Edit the Java Security Configuration file (java.security) located in <JDK_installation_directory>/jre/lib/security and add PKCS#11 to the java.security file.

   security.provider.1=sun.security.provider.Sun
   security.provider.2=sun.security.rsa.SunRsaSign
   security.provider.3=sun.security.ec.SunEC
   security.provider.4=com.sun.net.ssl.internal.ssl.Provider
   security.provider.5=com.sun.crypto.provider.SunJCE
   security.provider.6=sun.security.jgss.SunProvider
   security.provider.7=com.sun.security.sasl.Provider
   security.provider.8=sun.security.pkcs11.SunPKCS11 C:\\Program Files\\Java\\jdk1.8.0_251\\jre\\lib\\security\\pkcs11.cfg
   security.provider.9=org.jcp.xml.dsig.internal.dom.XMLDSigRI
   security.provider.10=sun.security.smartcardio.SunPCSC
   security.provider.11=sun.security.mscapi.SunMSCAPI

   Copy
   

   Note

   On Windows, the java.security file is located in <JDK_installation_directory>\jre\lib\security.

Generating key materials on the ProtectServer 3 HSM

When Java is configured to use PKCS#11, we can create the keys and certificate in the keystore pointing to ProtectServer 3 HSM slot.

To create keys and certificate in a ProtectServer 3 HSM

1. Generate a key pair in the keystore using the Java keytool utility. The key pair will be generated on the registered slot of the ProtectServer 3 HSM.

   keytool -genkeypair -alias <key label> -keyalg <key algorithm> -keysize <size of key> -sigalg <signing algorithm> -keystore <keystore name> -storepass <slot password> -storetype <PKCS11>

   Copy

   For example:

   keytool -genkeypair -alias ptkkey -keyalg RSA -keysize 2048 -sigalg SHA256withRSA -keystore NONE -storepass 0000 -storetype PKCS11
   
   logger: s_ctData->ft = 0x0000000016C86500
   logger: s_ctData->ft->C_Initialize = 0x00007FF98C3B1578
   What is your first and last name?
     [Unknown]:  PTK Test
   What is the name of your organizational unit?
     [Unknown]:  PTK
   What is the name of your organization?
     [Unknown]:  Thales
   What is the name of your City or Locality?
     [Unknown]:  Ottawa
   What is the name of your State or Province?
     [Unknown]:  Ontario
   What is the two-letter country code for this unit?
     [Unknown]:  CA
   Is CN=PTK Test, OU=PTK, O=Thales, L=Ottawa, ST=Ontario, C=CA correct?
     [no]:  yes

   Copy

2. Display the generated key materials.

   keytool -list -keystore NONE -storetype PKCS11

   Copy

   For example:

   keytool -list -keystore NONE -storetype PKCS11
   
   logger: s_ctData->ft = 0x0000000016B86450
   logger: s_ctData->ft->C_Initialize = 0x00007FF98C3B1578
   Enter keystore password:
   Keystore type: PKCS11
   Keystore provider: SunPKCS11-PSE
   
   Your keystore contains 1 entry
   
   ptkkey, PrivateKeyEntry,
   Certificate fingerprint (SHA1): 5B:79:92:EC:F1:1B:BA:50:AD:97:A3:98:DE:90:7D:67:C6:1B:4C:77

   Copy

Configuring SSL for Apache Tomcat

The Apache Tomcat server uses the SSL key and certificate stored in the keystore for SSL communication.

Apache Tomcat uses the server.xml file available in <Tomcat_installation_directory>/conf to define the connector setting for SSL.

Note

On Windows, server.xlm is located in <Tomcat_installation_directory>\conf.

To configure SSL for Apache Tomcat

1. Stop the server, if running. Run the shutdown.bat or shutdown.sh script provided under bin folder of <Tomcat_installation_directory>.

2. Edit server.xml by uncommenting the existing connector and updating it as shown in the snippets below or by adding the snippets shown below in their entirety without uncommenting the existing one.

   For Apache Tomcat 9

   <Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
                       sslImplementationName="org.apache.tomcat.util.net.jsse.JSSEImplementation"
              maxThreads="150" scheme="https" secure="true" SSLEnabled="true"
              clientAuth="false" sslProtocol="TLS"
              keystoreType="PKCS11" keystoreFile=<path_to_pkcs11.cfg> keyAlias=<key_alias>
              keystorePass=<keystore_password> />

   Copy

   For Apache Tomcat 10

   <Connector protocol="org.apache.coyote.http11.Http11NioProtocol"
              port="8443"
              maxThreads="150"
              scheme="https"
              secure="true"
              SSLEnabled="true">
       <SSLHostConfig>
         sslProtocol="TLS"
         clientAuth="false"
         <Certificate
            certificateKeystoreType="PKCS11"
            certificateKeystoreFile=<path_to_pkcs11.cfg>
            certificateKeyAlias =<key_alias>
            certificateKeystorePassword=<keystore_password>
            />
       </SSLHostConfig>
   </Connector>

   Copy

   Save and close server.xml.

   Ensure that the keystore settings values are correct as per your environment.

3. Start the Tomcat server using startup.bat or startup.sh provided under bin directory of <Tomcat_installation_directory>.

4. If Tomcat starts successfully, you will see the default page of Tomcat at https://<hostname or IP address>:8443/. The SSL certificate is the one that you generated and stored in PTK Keystore.

   

This completes the Apache Tomcat integration with the ProtectServer 3 HSM.

The SSL certificate private key is secured on the HSM slot and the SSL page will be accessible only if the HSM slot is accessible and available to Apache Tomcat Server.