Create custom certificates for Tomcat installations (non-Docker)

This article is valid for Smart ID 20.11 and above and PRIME 3.12 and above.

In a production environment, the certificates used must be created by a real certificate authority (CA). By doing so, the trust is clear.

If it is not possible to use a CA, it is not recommended to use certificates with well-known private keys. 

This article gives examples of scripts that makes it easy to set up the certificates needed with a new set of private keys. Those private keys are intended for a single machine or Identity Manager installation.

The procedure consists of these steps:

• Set up a local CA
  The CA can be used for several installations on the same machine.
• Establish trust for the CA
  The CA certificate is installed in the cacerts truststore of the active Java installations. This step has to be repeated after every Java upgrade. Thus having a single CA keeps maintenance low. In order to access a Java installation on Windows, the script needs to run in Windows command line, not in WSL2.

• Create the actual P12s
  By default, the names and pass phrases are used as the dummy certificates, so you just need to copy them to WEB-INF/classes in the web applications of the Identity Manager installation.

  

  In this example we only create two P12 files: one for encryption and one for signing. It is recommended to use multiple different ones for various signing-related use-cases, but the default config in supplied Tomcat packages uses a common signing P12.

Requirements

• These scripts use OpenSSL. This can be installed on Windows and added to the PATH environment variable, or you can use a WSL2 Linux distribution with OpenSSL instead.

  

  The latest 1.x version of OpenSSL is recommended. Version 3 by default uses incompatible PKCS#12 algorithms.

  If you insist on using version 3, then you need to change any "openssl pkcs12" calls in the .bat and .sh files from certsetup.zip to include the following extra parameter(s):

  Mandatory parameter to enable the legacy provider:

  CODE

  -legacy

  Also potentially needed, in case the legacy provider library is in the wrong path (as is the case with some OpenSSL builds for Windows) is this (make sure you locate the correct path first, instead of the examples below):

  CODE

  -provider-path "C:\folder\containing\legacy.dll"

   or

  CODE

   -provider-path "/folder/containing/legacy.so" 

• Active Java installation is selected via JAVA_HOME environment variable.

Steps with installed OpenSSL for Windows

This was successfully tested with https://slproweb.com/download/Win64OpenSSL_Light-1_1_1m.msi .

1. Ensure that JAVA_HOME points to the folder of the Windows Java installation that will be used by Tomcat.
2. Download certsetup.zip.
3. Unpack it. (For example to C:\primestuff\certsetup)
4. Start a command line as administrator to execute the following:
   
   1. Navigate to the batch files (cd c:\primestuff\certsetup)
   2. createca.bat
   3. trustlocalCA.bat
   4. createP12s.bat
5. Copy sign.p12 and hybridEncKeypair.p12 to WEB-INF\classes of your web applications.

Steps using WSL2

1. Ensure that JAVA_HOME points to the folder of the Windows Java installation that will be used by Tomcat.
2. Download certsetup.zip.
3. Unpack it. (For example to C:\primestuff\certsetup)
4. Open WSL distribution to execute the following:
   
   1. Navigate to the batch files (cd /mnt/c/primestuff/certsetup → depends on distribution, example is Ubuntu) 
   2. ./createca.sh
   3. ./createP12s.sh
5. Start a command line as administrator (Establishing the trust has to be done to the Java of Windows)
   1. Navigate to the batch files (cd c:\primestuff\certsetup)
   2. trustlocalCA.bat
6. Copy sign.p12 and hybridEncKeypair.p12 to WEB-INF\classes of your web applications.

Additional information