From f6bc48614903ba42f01e7c96dd240385515c21c3 Mon Sep 17 00:00:00 2001 From: Josh Drake Date: Tue, 21 Jul 2026 09:28:09 -0500 Subject: [PATCH] docs: fix modutil/P11_KIT_SERVER_ADDRESS ordering in PKCS#11 guide The "OpenSSL and PKCS#11 support" example ran `modutil -add` before exporting P11_KIT_SERVER_ADDRESS. That fails: modutil loads and initializes the module as it adds it, and p11-kit-client.so cannot initialize unless P11_KIT_SERVER_ADDRESS already points at the running agent's PKCS#11 socket. - smallstep-agent.mdx: export the env var before running modutil, and add a warning callout explaining the ordering requirement. - troubleshooting-agent.mdx: add a "Recovering from a failed modutil add" subsection (list/delete the broken module with modutil/certutil, then re-add in the correct order). - vale vocab: accept `certutil`. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01VBgyxA5TPfE3hZMyoL1T5r --- .../config/vocabularies/Smallstep/accept.txt | 1 + platform/smallstep-agent.mdx | 11 +++++-- platform/troubleshooting-agent.mdx | 33 +++++++++++++++++++ 3 files changed, 42 insertions(+), 3 deletions(-) diff --git a/.vale/styles/config/vocabularies/Smallstep/accept.txt b/.vale/styles/config/vocabularies/Smallstep/accept.txt index 8cf77302..f1466aaa 100644 --- a/.vale/styles/config/vocabularies/Smallstep/accept.txt +++ b/.vale/styles/config/vocabularies/Smallstep/accept.txt @@ -388,6 +388,7 @@ catalogued certkeys certmagic certspotter +certutil cfcc chown chxwEdmr diff --git a/platform/smallstep-agent.mdx b/platform/smallstep-agent.mdx index 7e7ef9fc..5e35abe6 100644 --- a/platform/smallstep-agent.mdx +++ b/platform/smallstep-agent.mdx @@ -347,14 +347,19 @@ For this example, we’re using Ubuntu 24.04. The location of `p11-kit-client.so Let’s make client certificates and keys from the agent available to Google Chrome via PKCS#11 tokens. We will use `modutil` and an NSS database. Google Chrome defaults to storing an NSS database in `~/.pki/nssdb`, so we can leverage that. -To use Smallstep certificates in Chrome, run: +To use Smallstep certificates in Chrome, first point the p11-kit client library at the agent's running PKCS#11 socket, then register it with `modutil`: + +```bash +export P11_KIT_SERVER_ADDRESS=unix:path=$XDG_RUNTIME_DIR/step-agent/step-agent-pkcs11.sock -``` modutil -dbdir ~/.pki/nssdb -add step-agent \ -libfile /usr/lib/x86_64-linux-gnu/pkcs11/p11-kit-client.so -export P11_KIT_SERVER_ADDRESS=unix:path=$XDG_RUNTIME_DIR/step-agent/step-agent-pkcs11.sock ``` + +Export `P11_KIT_SERVER_ADDRESS` and point it at the running agent's socket **before** you run `modutil`. `modutil` loads and initializes the module as it adds it, so running it first fails with a load error and can leave a broken module registered in the NSS database. If you hit this, see [Recovering from a failed `modutil` add](./troubleshooting-agent.mdx#recovering-from-a-failed-modutil-add). + + Next, start Chrome from the command line. In Chrome, you should now have access to certificates managed by Smallstep. diff --git a/platform/troubleshooting-agent.mdx b/platform/troubleshooting-agent.mdx index e4688699..6c3db595 100644 --- a/platform/troubleshooting-agent.mdx +++ b/platform/troubleshooting-agent.mdx @@ -486,6 +486,39 @@ The location of `p11-kit-client.so` may vary by distribution. 5. See [PKCS#11 configuration guide](./smallstep-agent.mdx#openssl-and-pkcs11-support) 6. See the [p11-kit documentation](https://p11-glue.github.io/p11-glue/p11-kit/manual/) for general PKCS#11 reference +##### Recovering from a failed `modutil` add + +If you ran `modutil -add` before exporting `P11_KIT_SERVER_ADDRESS` (see [OpenSSL and PKCS#11 support](./smallstep-agent.mdx#openssl-and-pkcs11-support)), the add can fail or register a broken module, because `modutil` loads `p11-kit-client.so` as it adds it and the client library cannot initialize without a reachable agent socket. To recover: + +1. Close any application using the NSS database (for example, Google Chrome). `modutil` cannot modify a database that is in use. + +2. List the modules currently registered to confirm the state: + ```bash + modutil -dbdir ~/.pki/nssdb -list + ``` + You can also list modules with `certutil`: + ```bash + certutil -d ~/.pki/nssdb -U + ``` + +3. Remove the broken `step-agent` module: + ```bash + modutil -dbdir ~/.pki/nssdb -delete step-agent + ``` + Add `-force` to skip the interactive confirmation prompt. If the add failed outright and nothing was registered, this reports that the module can't be found, which is harmless; skip to the next step. + +4. Export `P11_KIT_SERVER_ADDRESS`, then re-add the module in the correct order: + ```bash + export P11_KIT_SERVER_ADDRESS=unix:path=$XDG_RUNTIME_DIR/step-agent/step-agent-pkcs11.sock + modutil -dbdir ~/.pki/nssdb -add step-agent \ + -libfile /usr/lib/x86_64-linux-gnu/pkcs11/p11-kit-client.so + ``` + +5. Confirm the module now lists its slots and tokens: + ```bash + modutil -dbdir ~/.pki/nssdb -list step-agent + ``` + #### Cannot access a resource (wi-fi, VPN, web app) **Symptoms:**