Repository navigation
Document the X.509 provisioning challenge exchange - #204
richturner wants to merge 2 commits into
Conversation
X.509 auto provisioning now requires the device to prove it holds its certificate's private key by signing a one-time challenge (GHSA-7jp3-2229-xgqj). Document the two-step exchange and its messages, the signature algorithms per key type, the challenge's lifetime and binding, what clients must check before signing, the response topic ownership rules, and the wider meaning of UNAUTHORIZED, with a breaking change warning for existing devices. Replace the connect flow image of the single step exchange with a Mermaid sequence diagram, and update the at scale tutorial to match. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
denniskuijs
left a comment
denniskuijs
left a comment
There was a problem hiding this comment.
This documentation is AI generated. It contains a lot of em dashes, bold formatting etc. Can you please review it and update accordingly?
There was a problem hiding this comment.
🔵 Needs a closer look
Maintainers must confirm the first core release containing the fix and coordinate documentation publication, since the latest published version is 1.33.0 but the docs assume 1.34.0.
No open issues 🎉
What changed in this PR
Documents the X.509 proof-of-possession challenge exchange for device auto provisioning, replacing the certificate-only flow in the current documentation while leaving versioned docs unchanged.
Changes:
- Adds a breaking-change warning, two-step exchange instructions, message schemas, and a Mermaid sequence diagram.
- Explains challenge validation, signing algorithms, expiry, subscription ownership, and private-key and TLS requirements.
- Updates the provisioning tutorial to include private-key storage and challenge signing.
| File | Description |
|---|---|
docs/user-guide/080-gateways-and-devices/20-auto-provisioning.md |
Documents the challenge protocol, compatibility break, and security requirements. |
docs/tutorials/080-auto-provision-devices-at-scale.md |
Updates device preparation and provisioning steps for challenge signing. |
Review effort: Balanced
|
Can you provide details of what looks out of place, there are minor adjustments to the existing doc and AI is mentioned on the commit but I don't believe em dashes have been introduced? |
Description
Documents the X.509 auto provisioning proof of possession change from the fix for
GHSA-7jp3-2229-xgqj:
devices must now sign a one-time challenge with their certificate's private key before they are
provisioned, and certificate-only requests are rejected with
UNAUTHORIZED.user-guide/080-gateways-and-devices/20-auto-provisioning.mdsequence diagram; includes the response topic ownership rules (only the subscribing
connection may publish requests, one provisioning response topic per connection).
x509-challenge-requestandx509-challengemessages, and thesignaturefield onx509.signature algorithm per key type, and the challenge's 60s lifetime, one-time use and binding.
UNAUTHORIZEDnow also covers missing/invalid signatures, expired/used challenges andunsupported key types.
tutorials/080-auto-provision-devices-at-scale.mdversioned_docsare untouched, as released versions still use the old protocol.Before merging
don't describe a protocol released versions reject.
1.34.0; adjust ifthe fix ships as a patch release).
Related: openremote/core#3542 (JMeter auto-provisioning plans).
🤖 Generated with Claude Code