{"id":28953348,"url":"https://github.com/vegardit/docker-softhsm2-pkcs11-proxy","last_synced_at":"2025-06-23T18:05:08.942Z","repository":{"id":43059540,"uuid":"387764022","full_name":"vegardit/docker-softhsm2-pkcs11-proxy","owner":"vegardit","description":"Docker image to run a virtual HSM (Hardware Security Module) network service based on SoftHSM2 and pkcs11-proxy.","archived":false,"fork":false,"pushed_at":"2025-05-19T16:44:09.000Z","size":91,"stargazers_count":33,"open_issues_count":0,"forks_count":9,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-19T17:38:50.658Z","etag":null,"topics":["docker-image","pkcs11-proxy","pkcs11-tool","softhsm2"],"latest_commit_sha":null,"homepage":"","language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vegardit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-07-20T11:06:12.000Z","updated_at":"2025-05-19T16:44:13.000Z","dependencies_parsed_at":"2024-01-08T15:05:43.489Z","dependency_job_id":"c7c12ba8-121a-4415-b696-58d23c18283e","html_url":"https://github.com/vegardit/docker-softhsm2-pkcs11-proxy","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vegardit/docker-softhsm2-pkcs11-proxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vegardit%2Fdocker-softhsm2-pkcs11-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vegardit%2Fdocker-softhsm2-pkcs11-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vegardit%2Fdocker-softhsm2-pkcs11-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vegardit%2Fdocker-softhsm2-pkcs11-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vegardit","download_url":"https://codeload.github.com/vegardit/docker-softhsm2-pkcs11-proxy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vegardit%2Fdocker-softhsm2-pkcs11-proxy/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261528619,"owners_count":23172748,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker-image","pkcs11-proxy","pkcs11-tool","softhsm2"],"created_at":"2025-06-23T18:05:08.312Z","updated_at":"2025-06-23T18:05:08.930Z","avatar_url":"https://github.com/vegardit.png","language":"Dockerfile","readme":"# vegardit/docker-softhsm2-pkcs11-proxy \u003ca href=\"https://github.com/vegardit/docker-softhsm2-pkcs11-proxy/\" title=\"GitHub Repo\"\u003e\u003cimg height=\"30\" src=\"https://raw.githubusercontent.com/simple-icons/simple-icons/develop/icons/github.svg?sanitize=true\"\u003e\u003c/a\u003e\n\n[![Build Status](https://github.com/vegardit/docker-softhsm2-pkcs11-proxy/workflows/Build/badge.svg \"GitHub Actions\")](https://github.com/vegardit/docker-softhsm2-pkcs11-proxy/actions?query=workflow%3ABuild)\n[![License](https://img.shields.io/github/license/vegardit/docker-softhsm2-pkcs11-proxy.svg?label=license)](#license)\n[![Docker Pulls](https://img.shields.io/docker/pulls/vegardit/softhsm2-pkcs11-proxy.svg)](https://hub.docker.com/r/vegardit/softhsm2-pkcs11-proxy)\n[![Docker Stars](https://img.shields.io/docker/stars/vegardit/softhsm2-pkcs11-proxy.svg)](https://hub.docker.com/r/vegardit/softhsm2-pkcs11-proxy)\n[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.1%20adopted-ff69b4.svg)](CODE_OF_CONDUCT.md)\n\n1. [What is it?](#what-is-it)\n1. [Docker image tagging scheme](#tags)\n1. [Usage](#usage)\n1. [License](#license)\n\n\n## \u003ca name=\"what-is-it\"\u003e\u003c/a\u003eWhat is it?\n\n\u003e **SoftHSM has been developed for development purposes only. Don't use in production!**\n\nA multi-arch Docker image to run a virtual HSM (Hardware Security Module) network service based on [SoftHSM2](https://github.com/softhsm/SoftHSMv2) and\n[pkcs11-proxy](https://github.com/SUNET/pkcs11-proxy/).\n\nAutomatically rebuilt **weekly** to include the latest OS security fixes.\n\nClient applications can communicate with the HSM via TCP/TLS using libpkcs11-proxy.so and an OpenSSL TLS-PSK:\n\n![](doc/aod.png)\n\n\n## \u003ca name=\"tags\"\u003e\u003c/a\u003eDocker image tagging scheme\n\n|Tag|Description|Base Image\n|-|-|-\n|`:latest` \u003cbr\u003e `:latest-alpine` | weekly build of the latest available SoftHSM release | alpine:3\n|`:latest-debian` | weekly build of the latest available SoftHSM release | debian:stable-slim\n|`:develop` \u003cbr\u003e `:develop-alpine` | weekly build of the development branch | alpine:3\n|`:develop-debian` | weekly build of the development branch | debian:stable-slim\n|`:2.x` \u003cbr\u003e `:2.x-alpine` | weekly build of the latest minor version of the respective \u003cbr\u003e major release, e.g. `2.x` may contain release `2.6` | alpine:3\n|`:2.x-debian` | weekly build of the latest minor version of the respective \u003cbr\u003e major release, e.g. `2.x` may contain release `2.6` | debian:stable-slim\n\nSee all tags at https://hub.docker.com/r/vegardit/softhsm2-pkcs11-proxy/tags\n\n\n## \u003ca name=\"usage\"\u003e\u003c/a\u003eUsage\n\n### Service Configuration\n\nSoftHSMv2 internal storage is located at `/var/lib/softhsm/`.\n\nThe PKCS11 Daemon listens on port `2345` by default.\n\nThe docker image can be configured via the following environment variables:\n\n\n|Name                      | Comment | Default\n|-                         |-        |-\n|INIT_SH_FILE              | Path to a file that shall be automatically executed on container start. | [`/opt/init-token.sh`](image/init-token.sh)\n|TOKEN_AUTO_CREATE         | If a token shall be created on container start if it is not already existing based on the following values: `0` = no or `1` = yes | `1`\n|TOKEN_LABEL               | Name of the token to auto-create. |`Test Token`\n|TOKEN_USER_PIN            | User pin of the token to auto-create. |`1234`\n|TOKEN_USER_PIN_FILE       | Path to file containing the user pin. Value in this file takes precedence over TOKEN_USER_PIN variable. | empty\n|TOKEN_SO_PIN              | SO (Security Officer/Admin user) pin of the token to auto-create. |`5678`\n|TOKEN_SO_PIN_FILE         | Path to file containing SO pin. Value in the file takes precedence over TOKEN_SO_PIN variable. | empty\n|TOKEN_IMPORT_TEST_DATA    | Specifies if a test certificate shall be imported: `0` = no or `1` = yes | `0`\n|PKCS11_DAEMON_SOCKET      | Socket the PKCS11 daemon listens. |`tls://0.0.0.0:2345`\n|PKCS11_PROXY_TLS_PSK_FILE | File containing the PKCS11 daemon's OpenSSL TLS-PSK (pre-shared key). |`/opt/test.tls.psk`\n|SOFTHSM_STORAGE           | Specifies what backend shall be used to store the token: `file` or `db` (aka `sqlite`) | `file`\n\n\nExamples:\n\n1. Running with default test configuration:\n    ```bash\n    docker run -it -name softhsm vegardit/docker-softhsm2-pkcs11-proxy\n    ```\n\n1. Running with custom settings:\n    ```bash\n    docker run -it --rm \\\n       -name softhsm-server \\\n       # define a custom token name:\n       -e TOKEN_LABEL=\"MyToken\" \\\n       # use custom pins stored in files:\n       -e TOKEN_USER_PIN_FILE=\"/mnt/config/token_user_pin\" \\\n       -e TOKEN_SO_PIN_FILE=\"/mnt/config/token_so_pin\" \\\n       # use a custom TLS pre-shared key:\n       -e PKCS11_PROXY_TLS_PSK_FILE=\"/mnt/config/pkcs11_proxy.psk\" \\\n       # expose port 2345\n       -p 2345:2345 \\\n       # mount config and data directories:\n       -v /path/to/config:/mnt/config:ro \\\n       -v /path/to/data:/var/lib/softhsm:rw \\\n       vegardit/docker-softhsm2-pkcs11-proxy:latest\n    ```\n\n1. Same as docker-compose file:\n\n    ```yaml\n    version: '3.8'\n\n    services:\n\n      softhsm-server:\n        image: vegardit/softhsm2-pkcs11-proxy:latest\n        environment:\n          TOKEN_LABEL: MyToken # define a custom token name\n          TOKEN_USER_PIN_FILE: /mnt/config/token_user_pin # use custom pin stored in file\n          TOKEN_SO_PIN_FILE: /mnt/config/token_so_pin     # use custom pin stored in file\n          TOKEN_IMPORT_TEST_DATA: 0 # don't import test data\n          PKCS11_PROXY_TLS_PSK_FILE: /mnt/config/pkcs11_proxy.psk # use a custom TLS pre-shared key\n        ports:\n          - 2345:2345\n        volume:\n          /path/to/config:/mnt/config:ro    # mount config directory readonly\n          /path/to/data:/var/lib/softhsm:rw # mount data directory writable\n        deploy:\n          restart_policy:\n            condition: on-failure\n            delay: 5s\n    ```\n\n\n### Client Usage Example\n\nThis is a simple exercise to get you familiar with how a client container can interact remotely with the SoftHSM via the PKCS11 proxy\n\n1. Download one of the example dockerfiles [client.alpine.Dockerfile](client.alpine.Dockerfile) or [client.debian.Dockerfile](client.debian.Dockerfile).\n\n2. Build the image using:\n\n    ```bash\n    $ docker build -f /path/to/Dockerfile --tag softhsm-client .\n    ```\n\n3. Start the docker images:\n\n    ```bash\n    # create a docker network through which both containers can communicate\n    $ docker network create softhsm-net\n\n    # start the SoftHSM server in test mode:\n    $ docker run -it --rm \\\n        --net softhsm-net \\\n        --hostname softhsm-server \\\n        vegardit/softhsm2-pkcs11-proxy:latest\n\n    # in a second terminal window start the client:\n    $ docker run -it --rm \\\n        --net softhsm-net \\\n        -e PKCS11_PROXY_SOCKET=tls://softhsm-server:2345 \\\n        -e PKCS11_PROXY_TLS_PSK_FILE=/opt/test.tls.psk \\\n        softhsm-client\n    ```\n\n4. Test network communication\n\n    In the shell of the client container you can now test connectivity to the server using\n    the [pkcs11-tool](https://linux.die.net/man/1/pkcs11-tool).\n\n    ```bash\n    #\n    # first define an alias that loads the required proxy module\n    #\n    $ alias p11tool='pkcs11-tool --module /usr/local/lib/libpkcs11-proxy.so'\n\n    #\n    # show all slots\n    #\n    $ p11tool --list-slots\n      # output:\n      Available slots:\n      Slot 0 (0x3e2d07e4): SoftHSM slot ID 0x3e2d07e4\n        token label        : Test Token\n        token manufacturer : SoftHSM project\n        token model        : SoftHSM v2\n        token flags        : login required, rng, token initialized, PIN initialized, other flags=0x20\n        hardware version   : 2.6\n        firmware version   : 2.6\n        serial num         : a96de792be2d07e4\n        pin min/max        : 4/255\n      Slot 1 (0x1): SoftHSM slot ID 0x1\n        token state:   uninitialized\n\n    #\n    # generate and store a new key pair\n    #\n    $ p11tool --keypairgen --key-type RSA:2048 --label \"My Key\" --token-label \"Test Token\" --login --pin 1234\n      # output:\n      Key pair generated:\n      Private Key Object; RSA\n        label:      My Key\n        ID:         01\n        Usage:      decrypt, sign, unwrap\n      Public Key Object; RSA 2048 bits\n        label:      My Key\n        ID:         01\n        Usage:      encrypt, verify, wrap\n\n    #\n    # show all public objects in token \"Test Token\"\n    #\n    $ p11tool --list-objects --token-label \"Test Token\"\n      # output:\n      Public Key Object; RSA 2048 bits\n        label:      My Key\n        ID:         01\n        Usage:      encrypt, verify, wrap\n\n    #\n    # show all objects in token \"Test Token\"\n    #\n    $ p11tool --list-objects --token-label \"Test Token\" --login --pin 1234\n      # output:\n      Private Key Object; RSA\n        label:      My Key\n        ID:         01\n        Usage:      decrypt, sign, unwrap\n      Public Key Object; RSA 2048 bits\n        label:      My Key\n        ID:         01\n        Usage:      encrypt, verify, wrap\n\n    #################################\n    # sign some data with the new key\n    #################################\n    #\n    # 1. create a file to sign\n    $ echo \"Hello World!\" \u003e message.txt\n\n    # 2. list available algorithms to sign data\n    $ p11tool --list-mechanisms | grep -P \"RSA.*sign\"\n      # output:\n      Using slot 0 with a present token (0x5bb016b2)\n        MD5-RSA-PKCS, keySize={512,16384}, sign, verify\n        RSA-PKCS, keySize={512,16384}, encrypt, decrypt, sign, verify, wrap, unwrap\n        RSA-PKCS-PSS, keySize={512,16384}, sign, verify\n        RSA-X-509, keySize={512,16384}, encrypt, decrypt, sign, verify\n        SHA1-RSA-PKCS, keySize={512,16384}, sign, verify\n        SHA256-RSA-PKCS, keySize={512,16384}, sign, verify\n        SHA384-RSA-PKCS, keySize={512,16384}, sign, verify\n        SHA512-RSA-PKCS, keySize={512,16384}, sign, verify\n\n    # 3. sign the data with the newly created key\n    $ p11tool --sign --id 1 --mechanism SHA256-RSA-PKCS \\\n         --token-label \"Test Token\" --pin 1234 \\\n         --input-file message.txt \\\n         --output-file message.txt.sig\n      # output:\n      Using signature algorithm SHA256-RSA-PKCS\n\n    #################################\n    # verify the message signature\n    #################################\n    # 1. extract the public key\n    $ p11tool --read-object --type pubkey --label \"My Key\" --token-label \"Test Token\" \u003e mykey.pub.der\n\n    # 2. convert the public key to PEM format\n    $ openssl rsa -inform DER -outform PEM -in mykey.pub.der -pubin \u003e mykey.pub.pem\n      # output:\n      writing RSA key\n\n    # 3. verify the signature\n    $ openssl dgst -keyform PEM -verify mykey.pub.pem -sha256 -signature message.txt.sig message.txt\n      # output:\n      Verified OK\n    ```\n\n\n\n## \u003ca name=\"resources\"\u003e\u003c/a\u003eResources\n\n- SoftHSM:\n  - website: https://www.softhsm.org/\n  - sources: https://github.com/softhsm/SoftHSMv2\n  - tutorials:\n    - [SoftHSM2 first steps to create slots](https://verschlüsselt.it/softhsm2-first-steps/)\n- pkcs11-proxy:\n  - sources: https://github.com/scobiej/pkcs11-proxy/tree/osx-openssl1-1 (SUNET/pkcs11-proxy plus OpenSSL 1.1 support)\n  - sources: https://github.com/SUNET/pkcs11-proxy (fork with most changes)\n  - sources: https://github.com/kedros-as/pkcs11-proxy (most recently updated fork)\n  - sources: https://github.com/iksaif/pkcs11-proxy (original)\n- pkcs11-tool:\n  - sources: https://github.com/Mastercard/pkcs11-tools\n  - documentation: https://linux.die.net/man/1/pkcs11-tool\n  - tutorials:\n    - [Show slot and token info with OpenSC pkcs11-tool](https://verschlüsselt.it/show-slot-and-token-info-with-pkcs11-tool/)\n    - [Generate RSA, ECC and AES keys with OpenSC pkcs11-tool](https://verschlüsselt.it/generate-rsa-ecc-and-aes-keys-with-opensc-pkcs11-tool/)\n    - [Export a RSA / ECC public key with OpenSC pkcs11-tool](https://verschlüsselt.it/export-a-rsa-ecc-public-key-with-opensc-pkcs11-tool/)\n    - [Using the SmartCard-HSM with ECC and OpenSC](https://www.smartcard-hsm.com/2014/08/22/using-smartcard-hsm-with-ecc-and-opensc.html)\n    - [OpenSC test Sign, Verify, Encipher and Decipher from commandline with OpenSSL CLI ](https://gist.github.com/Jakuje/5a993d2b2d8a9cac35203599e49e6831)\n\n\n## \u003ca name=\"license\"\u003e\u003c/a\u003eLicense\n\nAll files in this repository are released under the [Apache License 2.0](LICENSE.txt).\n\nIndividual files contain the following tag instead of the full license text:\n```\nSPDX-License-Identifier: Apache-2.0\n```\n\nThis enables machine processing of license information based on the SPDX License Identifiers that are available here: https://spdx.org/licenses/.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvegardit%2Fdocker-softhsm2-pkcs11-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvegardit%2Fdocker-softhsm2-pkcs11-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvegardit%2Fdocker-softhsm2-pkcs11-proxy/lists"}