Bootstrapping of productive systems involves use of various certificate authorities to generate keys and issue certificates used by IDM.

Most descriptors, such as EncryptedFields and ObjectHistorySigner, always require proper bootstrapping for secure operation. However, depending on the subset of IDM features to be used, certain descriptors may be configured with placeholder keys and certificates (e.g. SignEmailDescriptor, if E-Mail signing in IDM is not enabled).

Productive systems can neither rely on any default keys that were installed with some older version nor on the development and test bootstrapping tools. Certificates must instead be requested and issued by real Certification Authorities (CA), taking care that they fulfill all requirements, and then installed prior to the first start of the system.

Bootstrapping of the sign and encrypt engine must be done before the system is used for the first time.

If IDM has already been used with test certificates, these insecure certificates may have been used. If object history entries and/or secrets were created with the demo keys, then after the bootstrapping you must resign the object history (using the batch_re-sign_history tool) and/or re-encrypt the secrets (using the batch_secretfieldstore_change_encryption_key tool) as described in Change Encryption key of secret field store). The batch_re-sign_history tool is not described anywhere. Need some clarification here!

Bootstrapping procedure

Identify requirements

The first step is to go through the list of all descriptors, and create a list of the descriptors for which your IDM installation actually needs a proper key. For each descriptor in the list, look up the general requirements. For the descriptors where a placeholder is sufficient, you may as well use the certificates created with the bootstrapping tool. (← is that a good idea? then we may need to change a couple of things, maybe enable selecting which descriptors to actually bootstrap. If all were first bootstrapped and then some overwritten for a prod env, this may compromise some of our checks like not booting etc!)

With the list at hand, repeat the following steps for each descriptor you have identified:

1. read the certificate requirements of each descriptor and decide

   1. who will issue the certificates for each descriptor. You can use more than one CA. Choices include

      1. any CA, e.g. your own SmartID Certificate Manager or a public CA

      2. a trusted S/MIME CA. This is needed in case you want IDM to sign emails, otherwise clients may fail to validate the emails

      3. for some descriptors, it is sufficient to create your own keypairs and certificates with any suitable tool you like.

   2. who needs to trust the issuer. You may have to install the issuer certificate in the IDM truststore or some other system, if this is stated in the certificate requirements

   3. what key usage each certificate needs to have

   4. until when the certificate shall be valid

2. read the key requirements and decide on a type.

Request certificates

Generate keypairs and Certification Signing Requests (CSRs) and request the certificates. If you want to use a Hardware Security Module (HSM), which is highly recommended, use it for generating keypairs wherever possible. The storage entry of each descriptor details where the keypair can be stored.

Configure certificates in IDM

1. Import the certificates into your HSM and/or place any of the credentials which are stored in PKCS#12 files to the correct location:

   1. Tomcat on Windows: C:\PATH\TO\TOMCAT\webapps\idm-[admin|operator]\WEB-INF\classes\

   2. Tomcat on Linux: /path/to/tomcat/idm-[admin|operator]/WEB-INF/classes/

   3. Docker on Linux: /PATH/TO/smartid/docker/compose/certs/

2. Edit the XML configuration file(s) to reference the appropriate files:

   1. Tomcat on Windows: C:\PATH\TO\TOMCAT\webapps\idm-[admin|operator]\WEB-INF\classes\engineSignEncryptConfig.xml

   2. Tomcat on Linux: /path/to/tomcat/idm-[admin|operator]/WEB-INF/classes/engineSignEncryptConfig.xml

   3. Docker on Linux: /PATH/TO/smartid/docker/compose/identitymanager/config/signencrypt.xml
      Note: each file needs to be referenced by the path within the container, as opposed to the path on the host.
      For example: file:/certs/MYFILE.p12