--- title: "Fortanix DSM with Docker Notary for PKCS#11" slug: "data-security-manager-with-docker-notary-for-pkcs11" updated: 2026-04-01T08:46:27Z published: 2026-03-19T09:07:56Z --- > ## Documentation Index > Fetch the complete documentation index at: https://support.fortanix.com/llms.txt > Use this file to discover all available pages before exploring further. # Fortanix DSM with Docker Notary for PKCS#11 ## 1.0 Introduction This article describes the steps to integrate the Docker Notary client with the Fortanix PKCS#11 library to use **Fortanix-Data-Security-Manager (DSM)** as a signer. The Fortanix DSM stores the root key, which is an EC key pair in the case of Notary. ## 2.0 Prerequisites Ensure the following: - The system should have an open SSL with PKCS#11-enabled engine. - The PKCS#11 tool must be installed. - Run the following command to update the PKCS#11 tool: ```bash apt update opensc ``` - Run the following command to install the PKCS#11 tool: ```bash apt install opensc ``` - Run the following command to update the PKCS#11 tool, if using yum as the package manager: ```bash yum update opensc ``` - Run the following command to install the PKCS#11 tool, if using yum as the package manager: ```bash yum install opensc ``` - Ensure that you have created an application and a group in the Fortanix DSM. *For more information, refer to the*[*User's Guide: Getting Started with Fortanix Data Security Manager – UI*](/v1/docs/users-guide-getting-started-with-fortanix-data-security-manager-ui)*.* ## 3.0 Create OpenSSL Configuration File Create an OpenSSL configuration file at `/root/.docker/certs/openssl.cnf` directory with the following content: ```bash openssl_conf = openssl_def [openssl_def] engines = engine_section [req] distinguished_name = req_distinguished_name [req_distinguished_name] #empty. [engine_section] pkcs11 = pkcs11_section [pkcs11_section] engine_id = pkcs11 dynamic_path = /usr/lib/engines/engine_pkcs11.so MODULE_PATH = /opt/fortanix/fortanix_pkcs11.so PIN = file:///etc/fortanix/pkcs11.conf init = 0 ``` ## 4.0 Create SymLink to Fortanix PKCS#11 Library Create a symlink for Fortanix PKCS#11 library to Notary at the required location. Run the following command: ```bash sudo ln -s fortanix_pkcs11.so /usr/lib/libykcs11.so sudo ln -s fortanix_pkcs11.so /usr/lib64/libykcs11.so ``` ## 5.0 Create Notary Root Key The Docker Notary root key and certificate are created using the PKCS#11 tool and library and these are stored in the Fortanix DSM. These keys are never exported out of Fortanix DSM and are used as the default root of trust for all the Docker repositories. Perform the following steps: 1. Create a PKCS#11 configuration file with the following content at the default location, `/etc/fortanix/pkcs11.conf`: ```bash api_key = "" api_endpoint = "https://" [log] system = true file = "/path/to/log/file" ``` Where, > [!NOTE] > NOTE > > You can also use `FORTANIX_PKCS11_CONFIG_PATH` environment variable to set a custom configuration path. - The value for `api_key` is the copied API key from Fortanix DSM. - The value for `api_endpoint` is the Fortanix DSM cluster endpoint. 2. Run the following command to create the root key: ```bash $ pkcs11-tool --module /opt/fortanix/fortanix_pkcs11.so --login --pin file:///etc/fortanix/pkcs11.conf -k --label "Notary Root Key" --key-type EC:prime256v1 Using slot 0 with a present token (0x0) Key pair generated: Private Key Object; EC label: test EC Key ID: 6866774f524a436c7a2f72614f6a374c394e7063376a664c4c303d Usage: sign, derive Public Key Object; EC EC_POINT 256 bits EC_POINT: 04410406ca6ddfafb9c3...f0a944bbcdbb3d746a315b08853ae1bc50416fa93c98fae68cb d0 EC_PARAMS: 06082a8648ce3d030107 label: test EC Key ID: 6866774f524a436c7a2f72614f6a374c394e7063376a664c4c303d Usage: verify ``` > [!NOTE] > NOTE > > Note down the value for Private Key Object ID in the output above. 3. Run the following command to create the self-signed certificate for the root key: ```bash $ openssl req -config /root/.docker/certs/openssl.cnf -engine pkcs11 - keyform engine -new -key 1: -nodes -days 365 -x509 -sha256 - out /root/.docker/certs/root.crt -subj "/CN=root" Import the certificate into Fortanix DSM: $ openssl x509 -inform pem -outform der -in /root/.docker/certs/root.crt - out /root/.docker/certs/root-crt.der $ pkcs11-tool --module /opt/fortanix/fortanix_pkcs11.so --login --pin file:///etc/fortanix/pkcs11.conf --write-object /root/.docker/certs/root- crt.der --type cert --id --label "Notary Root Key" ``` *For more information on the configuration file, refer to*[*Configuration File Format*](/v1/docs/clients-pkcs11-library#411-configuration-file-format)*.* > [!NOTE] > NOTE > > Ensure to enter the value for the `subject` as `CN=root` for the Notary to identify the self-signed certificate created from the root key. 4. Run the following command to upload the certificate to Fortanix DSM: ```bash $ pkcs11-tool --module /opt/fortanix/fortanix_pkcs11.so --login –pin file:///etc/fortanix/pkcs11.conf --write-object /root/.docker/certs/root-crt.der --type cert --id  --label "Notary Root Key" ``` ## 6.0 Publish Root Key and Certificate Perform the following steps to publish the root key and certificate using the Fortanix DSM user interface (UI): 1. In the DSM left navigation panel, click the **Security Objects** menu item and then search for the key or certificate that you want to publish. Ensure to note the name of the key or certificate that you are publishing. 2. On the detailed view page, click the **Public key published** toggle button to publish the key. ![](https://cdn.us.document360.io/c3bd85d2-4ad8-4d85-9f60-f1c168a3aad9/Images/Documentation/Screenshot (2657).png) **Figure 1: Public key published toggle button** *This action might require approval from the approvers, refer to the*[*User's Guide: Account Quorum Policy*](/v1/docs/users-guide-account-quorum-policy)*.* Selecting this toggle button displays the **URL of the API endpoint**. You can copy this endpoint using the copy icon. In case you want to view the older version of the key or certificate, select the check box for **List previous version** and click **Save**. 3. Run the following command to list all the security objects in the Fortanix DSM along with their `CKA_ID` value: ```bash pkcs11-tool --module ~/path/to/pkcs11/library.so --login --pin -O ``` The output of this command lists all the objects in the account, along with all published root keys and certificates. Note the `CKA_ID` value mentioned against the published keys and certificates. > [!NOTE] > NOTE > > Ensure that the `CKA_IDs` are in HEX string format only. 4. Add information about the root keys and certificates in the PKCS#11 configuration file in the following format: ```bash api_key = "..." api_endpoint = "..." [log] system = true file = "/path/to/log/file" [[pub_obj_info]] account_id = "" key_name = " pkcs11_id = "" [[pub_obj_info]] account_id = "" key_name = "" pkcs11_id = "" ``` > [!NOTE] > NOTE > > You can find the values for the following: > > - `account_id` - This value is available in the **Settings** tab → **Account Settings** page. > - `key_name` - This value is copied in *Step 2*. > - `pkcs11_id` – This value is copied while creating the root key in *Step 4*. ## 7.0 Verification Run the following command to list all the Docker Notary keys: ```bash notary key list ``` The following is the sample output of the above command: ```bash ROLE GUN KEY ID LOCATION  root e38202b6664ad57...5579707260b1b yubikey ``` > [!NOTE] > NOTE > > The location of the key is always displayed as YubiKey in the CLI, however, it is also reflected in the Fortanix DSM. After the integration operation is successfully done, you can run the Docker trust command and Notary operations using the keys stored in Fortanix DSM. ## 8.0 Sign the Image with Notary Perform the following steps to sign the image with a Notary: 1. Run the following command to export the PKCS#11 configuration file path: ```bash export FORTANIX_PKCS11_CONFIG_PATH=/home/ubuntu/pkcs11.cnf ``` 2. Run the following command to create the certificate for the repository: ```bash openssl req -engine pkcs11 -keyform engine -new -key 1: -nodes -sha256 -out -subj "/CN=” ``` > [!NOTE] > NOTE > > If you encounter any error, contact the Fortanix Support team for troubleshooting steps. 3. Run the following command to create a local key pair: ```bash openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout -out ``` 4. Run the following command to sign the Certificate Signing Request (CSR): ```bash openssl x509 -req -in -CA -CAkey -CAcreateserial -out -days 375 -sha256 ``` 5. Run the following command to initialize the repository in Notary: ```bash notary -c ~/.notary/config.json -D init -s https://notary.docker.io --publish --rootcert ``` 6. Run the following command to push the snapshot key to Notary servers: ```bash notary -s https://notary.docker.io -d ~/.docker/trust key rotate snapshot --server-managed ``` 7. Run the following commands to get the size and bash: ```bash docker manifest inspect -v | jq .Descriptor.size docker manifest inspect -v | jq .Descriptor.digest ``` 8. Run the following command to create the signing key: ```bash docker trust key generate ``` > [!NOTE] > NOTE > > This command generates a key pair. The path to the public key file is mentioned at the end of the output. Note this public key path to use in the next step for `<path to the signing key>`. 9. Run the following command to add the delegation role: ```bash notary -s https://notary.docker.io -d ~/.docker/trust delegation add -p targets/ --all-paths ``` 10. Run the following command to sign the image: ```bash notary -c ~/.notary/config.json -D addhash -p "" --sha256 -r targets/ ``` 11. Now this repository can be used when the Docker content trust is enabled. Run the following command to set the value for `DOCKER_CONTENT_TRUST` environment variable to `1`. ```bash export DOCKER_CONTENT_TRUST=1 ``` Fortanix Data Security Manager (DSM) is the world’s first cloud service secured with Intel® SGX. With Fortanix DSM, you can securely generate, store, and use cryptographic keys and certificates, as well as other secrets such as passwords, API keys, tokens, or any blob of data. Your business-critical applications and containers can integrate with Fortanix DSM using legacy cryptographic interfaces (PKCS#11, CNG, and JCE) or using the native Fortanix DSM RESTful interface. ## Related - [Authentication](/users-guide-authentication.md) - [Fortanix DSM with Oracle TDE](/fortanix-using-fortanix-data-security-manager-with-oracle-tde.md) - [Fortanix DSM for Kernel Module Signing](/using-fortanix-data-security-manager-for-kernel-module-signing-module-guide.md) - [Using Fortanix Confidential Computing Manager with PostgreSQL](/using-fortanix-confidential-computing-manager-with-postgresql.md)