We can configure ADSS Server Tomcat to use TLS Server Authentication held within a PKCS#11 device (e.g. a PCI-e or network HSM). Here, the following manual configurations must be made:

  1. Open the ADSS Server console and navigate to the Key Manager module.
  2. Generate a new key pair using the default TLS Server Authentication Template. Choose a PKCS#11 based crypto profile for storing the key. Ensure the crypto profile is set to import the generated certificate to the PKCS#11 device. For this, enable option “Copy certificates to device” in crypto profile.
  3. On the certificates page, create a new certificate for the TLS Server public key. You can either use the local CA or generate a PKCS#10 request using the external CA option. Certify the request with an external CA and then import the issued certificate.
  4. Go to Global Settings > System Certificates and replace the current TLS Server Authentication certificate with the one from step 3.
  5. Stop the ADSS Server Windows Services (Core, Console, and Service) or UNIX daemons.
  6. Backup the server.xml file located in [ADSS Server Home]/service/server/conf/. 
  7. Open the server.xml file in a text editor.
  8. Locate and comment out the instances of connector tags for ports 8778 and 8779 that are currently enabled. Uncomment the other instances that are disabled to activate them.
  9. In the uncommented connector tag for port 8778, find the keyAlias and enter the key alias for the TLS Server Authentication certificate as specified in the PKCS#11 vendor software. Use the provided utility to retrieve the key alias:
    • Navigate to [ADSS Server Home]/util/bin and copy this path
    • Launch the command prompt, change to the path above, and run bat
    • This displays the keyAlias for the TLS Server Authentication key
  1. Add the same keyAlias to the uncommented connector tag for port 8779
  2. For both connectors (8778 and 8779), update the keystorePass element value with the PKCS#11 device PIN, and save the server.xml file
  3. Customers have the option to use encrypted keystorePass passwords if desired, or they can opt for a non-encrypted password. For encrypted keystorePass, perform following steps:
    • Use the provided utility to encrypt password:
      • Navigate to [ADSS Server Home]/util/bin
      • Run encrypt_password.bat
      • Enter your keystorePass and it will encrypt it:


      • Use this password in server.xml for keystorePass
    • Add the following parameter in uncommented 8778 connector:


  1. For connector 8779, update the truststorePass element value with the password given in the commented 8779 connector.
  2. Repeat steps 6 to 14 for the server.xml file located at [ADSS Server Home]/console/server/conf/. Note that the TLS port in this file is 8774. Configure the keyAlias for the TLS Server authentication certificate specifically for this port. You do not need to rerun the utility since you already know the key alias from the HSM device.
  3. Navigate to <ADSS_SERVER_INSTALLATION_DIRECTORY>\jdk\conf\security and open the java.security file in a text editor. Find the property #security.provider.10=sun.security.pkcs11.SunPKCS11 <ADSS_SERVER_INSTALLATION_DIRECTORY>\conf\pkcs11.properties. Uncomment this line and replace <ADSS_SERVER_INSTALLATION_DIRECTORY> with the actual absolute path to the ADSS Server installation directory.
  4. Save the file.
  5. Start the ADSS Server Windows Services (or UNIX daemons).


See also

ADSS Server Logging

Localisation
ADSS Service Interface Error Codes
Changing ADSS Default Service URL

Configuring Tomcat for TLS Authentication Using HSM Devices