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
This article is valid for Smart ID Identity Manager 24.R1. |
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 four P12 files: one for encryption and one for signing, one for email-signing and one for the device-enc CA . It is recommended to use multiple different ones for various signing- and encryption-related use-cases, but the default config in supplied Tomcat packages uses a common signing P12 as well as an encryption P12 for both config zip and database secrets.
In this example we only create four P12 files: one for encryption and one for signing, one for email-signing and one for the device-enc CA . It is recommended to use multiple different ones for various signing- and encryption-related use-cases, but the default config in supplied Tomcat packages uses a common signing P12 as well as an encryption P12 for both config zip and database secrets.
Double-check PINs
You need to make sure that WEB-INF\classes\engineSignEncryptConfig.xml has the correct PINs that were used during bootstrapping.
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).
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:
-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):
-provider-path "C:\folder\containing\legacy.dll"
or
-provider-path "/folder/containing/legacy.so"
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:
-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):
-provider-path "C:\folder\containing\legacy.dll"
or
-provider-path "/folder/containing/legacy.so"
Active Java installation is selected via JAVA_HOME environment variable.
This was successfully tested with https://slproweb.com/download/Win64OpenSSL_Light-1_1_1m.msi .
Ensure that JAVA_HOME points to the folder of the Windows Java installation that will be used by Tomcat.
Download certsetup.zip.
Unpack it. (For example to C:\primestuff\certsetup)
Start a command line as administrator to execute the following:
Navigate to the batch files (cd c:\primestuff\certsetup)
createca.bat
trustlocalCA.bat
createP12s.bat
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.
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.
Ensure that JAVA_HOME points to the folder of the Windows Java installation that will be used by Tomcat.
Download certsetup.zip.
Unpack it. (For example to C:\primestuff\certsetup)
Open WSL distribution using OpenSSL 1.x (e.g. Ubuntu 20.04)to execute the following:
Navigate to the batch files (cd /mnt/c/primestuff/certsetup → depends on distribution, example is Ubuntu)
./createca.sh
./createP12s.sh
Start a command line as administrator (Establishing the trust has to be done to the Java of Windows)
Navigate to the batch files (cd c:\primestuff\certsetup)
trustlocalCA.bat
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.
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.