• 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.

The instructions below need to be done in all Digital Access VMs running the administration and policy service.

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

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

   
   

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

   Code Block
   $ 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:
   

   Code Block
   sudo chown -R 1003:1003 utimaco

   
   

UID may be different depending on the container environment.

1. Set log path and level as shown below:
   

   Code Block
   # 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:
   

   Code Block
   # 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:
   

   Code Block
   [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. 

   Code Block
   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.

Image Removed

Image Added

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