Skip to content

docs: drop openssl-tpm2-engine in favor of PKCS#11 #538

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tashian merged 2 commits into from
Jul 29, 2026
+22 −16
Merged

docs: drop openssl-tpm2-engine in favor of PKCS#11 #538

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fd4f027
docs: drop openssl-tpm2-engine in favor of PKCS#11
joshdrake Jul 27, 2026
8d38d7a
Merge origin/main into docs/remove-openssl-tpm2-engine
joshdrake Jul 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 15 additions & 9 deletions platform/smallstep-agent.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.

<Alert severity="info">
Module registration requires Smallstep agent v0.67.4 or later.
</Alert>

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

Expand All @@ -350,7 +356,7 @@ Let’s make client certificates and keys from the agent available to Google Chr
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
export P11_KIT_SERVER_ADDRESS=unix:path=/run/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
Expand All @@ -364,7 +370,7 @@ 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).

Expand Down
14 changes: 7 additions & 7 deletions platform/troubleshooting-agent.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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

Expand Down Expand Up @@ -479,16 +479,16 @@ 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

##### 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:
If you ran `modutil -add` before exporting `P11_KIT_SERVER_ADDRESS` (see [PKCS#11 support](./smallstep-agent.mdx#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.

Expand All @@ -509,7 +509,7 @@ If you ran `modutil -add` before exporting `P11_KIT_SERVER_ADDRESS` (see [OpenSS

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
export P11_KIT_SERVER_ADDRESS=unix:path=/run/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
```
Expand Down
Loading