diff --git a/platform/smallstep-agent.mdx b/platform/smallstep-agent.mdx index 284482fd..4ad6d9bd 100644 --- a/platform/smallstep-agent.mdx +++ b/platform/smallstep-agent.mdx @@ -1,5 +1,5 @@ --- -updated_at: June 9, 2026 +updated_at: July 27, 2026 title: Install the Smallstep Agent html_title: Install the Smallstep Agent on macOS, Windows, and Linux description: Install, configure, and deploy the Smallstep Agent on macOS, Windows, and Linux endpoints. Includes manual install, MDM integration, system requirements, and network endpoints. @@ -267,7 +267,7 @@ curl -fsSL https://packages.smallstep.com/scripts/smallstep-agent-install.sh | s 3. Install the Smallstep agent ```bash - sudo apt-get update && sudo apt-get -y install step-agent openssl-tpm2-engine + sudo apt-get update && sudo apt-get -y install step-agent ``` 4. Check that it was installed correctly @@ -333,13 +333,19 @@ If you get any errors, check the agent’s status: sudo systemctl status step-agent.service ``` -### OpenSSL and PKCS#11 support +### PKCS#11 support + +Keys managed by the Smallstep agent are bound to the device's TPM and cannot be exported. To let other software use those keys for TLS handshakes and other purposes, the agent runs a PKCS#11 server, exposed as a UNIX socket at `/run/step-agent/step-agent-pkcs11.sock`. + +PKCS#11 is the supported integration point for software like NetworkManager, `wpa_supplicant`, VPN clients, and web browsers. -The Smallstep agent stores the certificate on the filesystem alongside a TPM TSS2-formatted file, which is a reference to a TPM-bound key. As a result, any software that integrates with OpenSSL's `tpm2-openssl` provider, or with the underlying `libtpm2-tss`, can use the TPM-bound key for TLS handshakes or other purposes. +The Linux packages register the agent as a PKCS#11 module for you, by installing `/etc/pkcs11/modules/step-agent.module`. Software that discovers modules through p11-kit picks up the agent's keys with no further configuration. + + + Module registration requires Smallstep agent v0.67.4 or later. + -Because PKCS#11 is a common integration point, the Smallstep agent also provides a PKCS#11 server -for use with software like NetworkManager, `wpa_supplicant`, or web browsers. -The PKCS#11 server is exposed as a UNIX socket at `$XDG_RUNTIME_DIR/step-agent/step-agent-pkcs11.sock`. +NSS-based applications, such as Google Chrome and Firefox, don't read p11-kit module configuration. For those, register the module manually, as shown below. #### Example usage: Google Chrome @@ -352,14 +358,14 @@ To use Smallstep certificates in Chrome, run: ``` 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=unix:path=/run/step-agent/step-agent-pkcs11.sock ``` Next, start Chrome from the command line. In Chrome, you should now have access to certificates managed by Smallstep. -For regular usage, add `P11_KIT_SERVER_ADDRESS` to your environment more permanently. For example, you might add `P11_KIT_SERVER_ADDRESS=unix:path=$XDG_RUNTIME_DIR/step-agent/step-agent-pkcs11.sock` to your global `/etc/environment` file. +For regular usage, add `P11_KIT_SERVER_ADDRESS` to your environment more permanently. For example, you might add `P11_KIT_SERVER_ADDRESS=unix:path=/run/step-agent/step-agent-pkcs11.sock` to your global `/etc/environment` file. If PKCS#11 isn't working as expected, see [PKCS#11 troubleshooting](./troubleshooting-agent.mdx#pkcs11-not-working-linuxmacos). diff --git a/platform/troubleshooting-agent.mdx b/platform/troubleshooting-agent.mdx index e4688699..87cacf14 100644 --- a/platform/troubleshooting-agent.mdx +++ b/platform/troubleshooting-agent.mdx @@ -1,5 +1,5 @@ --- -updated_at: February 03, 2026 +updated_at: July 27, 2026 title: Troubleshooting Guide html_title: Smallstep Troubleshooting Guide description: Troubleshoot Smallstep Device Identity issues. Diagnose platform, MDM, and endpoint problems with step-by-step guidance. @@ -313,7 +313,7 @@ Each check validates a specific aspect of the agent's functionality. A **PASS** **Troubleshooting steps:** 1. Verify the PKCS#11 socket exists: ```bash - ls -l $XDG_RUNTIME_DIR/step-agent/step-agent-pkcs11.sock + ls -l /run/step-agent/step-agent-pkcs11.sock ``` 2. Check the environment variable: ```bash @@ -323,7 +323,7 @@ Each check validates a specific aspect of the agent's functionality. A **PASS** ```bash pkcs11-tool --module /usr/lib/x86_64-linux-gnu/pkcs11/p11-kit-client.so --list-slots ``` -4. See [PKCS#11 Support](./smallstep-agent.mdx#openssl-and-pkcs11-support) for configuration details +4. See [PKCS#11 Support](./smallstep-agent.mdx#pkcs11-support) for configuration details #### Advanced doctor options @@ -479,11 +479,11 @@ The location of `p11-kit-client.so` may vary by distribution. 1. Verify PKCS#11 socket exists and is accessible 2. Set environment variable correctly: ```bash - export P11_KIT_SERVER_ADDRESS=unix:path=$XDG_RUNTIME_DIR/step-agent/step-agent-pkcs11.sock + export P11_KIT_SERVER_ADDRESS=unix:path=/run/step-agent/step-agent-pkcs11.sock ``` 3. Install p11-kit if not present 4. Test with `pkcs11-tool --list-slots` -5. See [PKCS#11 configuration guide](./smallstep-agent.mdx#openssl-and-pkcs11-support) +5. See [PKCS#11 configuration guide](./smallstep-agent.mdx#pkcs11-support) 6. See the [p11-kit documentation](https://p11-glue.github.io/p11-glue/p11-kit/manual/) for general PKCS#11 reference #### Cannot access a resource (wi-fi, VPN, web app)