This example is part of the Sharing HSM tokens examples and shows how to share a token to operate it remotely over network with SSL/TLS protocol.
This example uses the ghcr.io/primosti/softhsm2 image as HSM container to use SoftHSMv2 as the HSM token.
Once the Unix Domain Socket has been shared by the p11-kit server command, this socket can be accessed remotely by
another container wrapping it in a TCP socket. All we need is a TCP listener service that will receive the remote
connection and forward the traffic to the socket.
Although, PKCS #11 implements the PIN code to protect the token against unauthorized access, this measure is not enough to protect the token over network traffic. It is necessary to protect the token access with a secure channel.
This example covers a solution to protect the shared token over a secure channel using SSL/TLS protocol. Two services and a client container were implemented to exemplify this scenario:
The following diagram illustrates how that interaction works:
| Service / Files | Description |
|---|---|
| client | A container that accesses the shared token over network. |
| /etc/pkc11/modules/p11-ssl-connect.conf | PKCS #11 module configuration file, to automatically connect to the shared token over network. This permits to some tools to access the token without any configuration. Read GnuTLS: PKCS #11 Initialization and pkcs11.conf(5) |
| /srv/bin/p11-kit-ssl-connect.sh | Script to connect to the shared token over network. |
| /srv/keys | Directory where are stored the certificates and keys for the SSL/TLS connection. This keys are shared to example purposes only. |
| hsm | The container that has access to the HSM (Hardware Security Module) and shares the token through a Unix Domain Socket. |
| /srv/data/tokens | Directory where SoftHSMv2 uses as backend to store token objects. Note: The /srv/data directory is a volume mouted to persist the token data. |
| /srv/run/sockets/token1.sock | The socket that shares the token. Note: The /srv/run/sockets directory is a volume that is shared with the proxy container. |
| proxy | The service that listens for TCP over SSL/TLS connections and forwards traffic to Unix Domain Socket. |
| /srv/bin/p11-kit-ssl-proxy.sh | Script to listen for TCP connections to forward traffic to the shared Unix Domain Socket. |
| /srv/bin/p11-kit-ssl-proxy.py | Alternative script to listen for TCP connections and forward traffic to the shared Unix Domain Socket. This script is written in Python to illustrate how to implement a proxy with custom logic. |
| /srv/run/sockets/token1.sock | The socket that shares the token. Note: The /srv/run/sockets directory is a volume that is shared with the hsm container. |
| /srv/keys | Directory where are stored the certificates and keys for the SSL/TLS connection. This keys are shared to example purposes only. |
- First, run the solution containers.
docker compose up- Then, access the
clientcontainer shell.
docker exec -it client ash- Then, from the
clientcontainer shell, operate on the token.
# You can use "p11tool" to operate with the token.
# Use "p11tool --help" to see all available options.
#
# For example, list the available tokens:
p11tool --list-tokensWarning: Sharing the token remotely can have security implications. Take security measures to protect the token from unauthorized access.
Some security measures includes:
- Use strong Security Officer (SO) PIN and User PIN to protect the token.
- Define a specific user and group for the container.
- Set the permissions of the exposed socket to be accessible only by a specific user and group.
- When sharing the token over network, use a secure connection with mutual authentication (e.g. TLS).
- Protect the access to the SoftHSMv2 storage. Read more about SoftHSMv2 storage internals.
YOU MUST ANALYZE YOUR OWN SCENARIO AND TAKE THE APPROPRIATE SECURITY MEASURES, BY YOUR OWN RISK.
Copyright © 2023 Primos TI
Licensed under the MIT License. See LICENSE in the project root for license information.