Old title: Create custom certificates for Tomcat installations (non-Docker)

TODO: replace this page entirely with a new content explaining the new dev-/test tooling for WAR and Docker deployments, see also https://confluence.nexusgroup.com/pages/viewpage.action?pageId=211419460

Tomcat deployments

xyy

Docker deployments

xy

OBSOLETE CONTENT BELOW!

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.

• Double-check PINs
  You need to make sure that WEB-INF\classes\engineSignEncryptConfig.xml has the correct PINs that were used during bootstrapping.

Requirements

• These scripts use OpenSSL 1.x. This can be installed on Windows and added to the PATH environment variable, or you can use a WSL2 Linux distribution with OpenSSL 1.x instead (e.g. Ubuntu 20.04).

• 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, signConfig.p12, signJWS.p12, signJWT.p12, encryptConfig.p12, emailSigning.p12, deviceEncCA.p12 and hybridEncKeypair.p12 to WEB-INF\classes of your web applications.

6. Edit WEB-INF\classes\engineSignEncryptConfig.xml in your web applications and make sure it uses the pins that were set during bootstrapping for the respective files.

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 using OpenSSL 1.x (e.g. Ubuntu 20.04)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, signConfig.p12, signJWS.p12, signJWT.p12, encryptConfig.p12, emailSigning.p12, deviceEncCA.p12 and hybridEncKeypair.p12 to WEB-INF\classes of your web applications.

7. Edit WEB-INF\classes\engineSignEncryptConfig.xml in your web applications and make sure it uses the pins that were set during bootstrapping for the respective files.

Additional information