Skip to main content
Skip table of contents

Configure Digital Access with Utimaco HSM

This article describes how to set up Utimaco with Digital Access acting as IDP in case of SAML.

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

Step-by-step instructions

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

Folder structure

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

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


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

    CODE
    $ 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
    sudo chown -R 1003:1003 utimaco


UID may be different depending on the container environment.

Configuration

Edit configuration files
  1. Set log path and level as shown below:

    CODE
    # 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
    # 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
    [CryptoServer]
    Device = { 3001@192.168.0.2 3003@192.168.0.3 }

Configure Digital Access container
  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
      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.

Make Digital Access Admin changes
  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.

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


Troubleshooting

Troubleshoot if an error occurs

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

Example:
CODE
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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.