• Utimaco HSM is already installed, configured and reachable from the host running the Digital Access containers.

• Since Digital Access does not yet support generation of a key-pair in the HSM via Digital Access Admin UI, a key-pair must already be generated and imported to the HSM.

1. In the Digital Access docker host, create a folder called “utimaco” with sub-folders as shown below:
   

   $ tree -d utimaco
   utimaco/
   ├── etc
   ├── lib
   └── log

2. Copy the required utimaco files: .so, .cfg, .pks files as shown below:
   

   $ tree utimaco
   utimaco
   ├── etc
   │   ├── cs_pkcs11_R3.cfg
   │   └── P11.pks
   ├── lib
   │   └── libcs_pkcs11_R3.so
   └── log

   Note : For older Utimaco Simulator versions, the .cfg, .so files could differ from R3.

3. Make sure the folder structure has the following owner and permissions:
   

   sudo chown -R 1003:1003 utimaco

UID may be different depending on the container environment.

1. Set log path and level as shown below:
   

   # For Unix:
   Logpath = /opt/utimaco/log
   
   # Loglevel (0 = NONE; 1 = ERROR; 2 = WARNING; 3 = INFO; 4 = TRACE)
   Logging = 0

2. Set the path to .pks (Specifies the path to the external key storage if keysExternal is set to true) as shown below:
   

   # For Unix:
   KeyStorageConfig = /opt/utimaco/etc/P11.pks

   Note :  Set this depending on your Utimaco version configuration

3. Set IP(s) of remote devices as shown below:
   

   [CryptoServer]
   Device = { 3001@192.168.0.2 3003@192.168.0.3 }

1. In the docker compose for admin service, mount the “utimaco” folder created in the first step in section "Create folder structure" above, and define the respective CS_PKCS11_R3_CFG environment variable. Utimaco reads this to locate its configuration file. 

     da-admin:
       (removed for brevity)
       environment:
         (removed for brevity)
         - CS_PKCS11_R3_CFG=/opt/utimaco/etc/cs_pkcs11_R3.cfg
       volumes:
         (removed for brevity)  
         - <utimaco-folder-path-on-host>:/opt/utimaco:z

   The same changes also need to be done in docker-compose files of all policy services.

2. If Utimaco logging required, adapt the above configuration to ensure that each Digital Access node logs to its own log file.
3. If Digital Access Admin and Digital Access policy is running on same host, make ENV CS_PKCS11_R3_CFG unique for each Digital Access container and specify a unique log location in Utimaco.cfg.

1. Select Manage System > Certificates > Add Server Certificate.
2. In the Add Server Certificate dialog, enable “Using Hardware Security Module”, and click Next to set HSM settings.
3. Export the certificate (or retrieve it externally), upload it in the Add Server Certificate dialog and save.
   Now the Server Certificate can be used in SAML IDP to enable signing of SAML responses using the HSM.

For older Utimaco Simulator versions, the pkcs11 could differ from R3.

If “Test Connection to HSM” check in Digital Access Admin UI fails, look for the error message in the admin system log.

2023-07-17 17:25:24 WARNING "Test connection to HSM failed, java.io.IOException: 50 (0x32) CKR_DEVICE_REMOVED, getTokenInfo"

The example error above indicates a problem connecting with the device.

Recommendations:

• Check admin service message log for errors.
• Enable debug to get logs of complete stack-trace to the message log.
• The system log of the Digital Access Policy Service will, on startup, contain information that is useful to conclude if HSM usage is operational.