Add external PKI provider documentation #482
Conversation
|
Visit the preview URL for this PR (updated for commit 117cf28): https://golioth-docs-dev--pr482-pki-providers-fvkbbyae.web.app (expires Thu, 15 Jan 2026 18:43:22 GMT) 🔥 via Firebase Hosting GitHub Action 🌎 Sign: f53b02bdc98ce6f5593931ec4c339aa96bac84df |
beriberikix
left a comment
beriberikix
left a comment
There was a problem hiding this comment.
Small comments, excited for this!
| To verify the certificate the device presented, Golioth goes through a list of | ||
| known CAs for your project. If the device's certificate was signed by one of the | ||
| known CAs, Golioth can trust the information within it, and the device can | ||
| start sending and receiving data. |
There was a problem hiding this comment.
Nit. could be a good place to mention ZTP and link to the subsection below.
| If you do not have a PKI provider service set up, but still want to leverage | ||
| certificate authentication in your development process, you can also [establish | ||
| local PKI](./2-local-pki.md) with [`openssl`](https://github.com/openssl/openssl). |
There was a problem hiding this comment.
and CFSSL? Or are we removing examples of it?
| the certificate. The sole purpose of this identifier is to associate the | ||
| physical device with a device on the Golioth platform. While a device's | ||
| certificate ID may match other device attributes, such as the device name, it | ||
| does not specifically connotate any other meaning. Using a dedicated identifier |
There was a problem hiding this comment.
any other meaning on the Golioth platform?
hasheddan
left a comment
hasheddan
left a comment
There was a problem hiding this comment.
Thanks @trond-snekvik! A few notes on structure but looking good!
| @@ -0,0 +1,131 @@ | |||
| --- | |||
| title: "Setting up a local PKI" | |||
There was a problem hiding this comment.
| title: "Setting up a local PKI" | |
| title: "Offline PKI" |
nitpick: can we structure this guide as an "Offline" provider option, then just call out that we are demonstrating an offline scenario that doesn't leverage an HSM and doesn't securely manage keys (i.e. the way we are doing it is not suitable for production, but offline PKI in general is).
There was a problem hiding this comment.
Took a stab at this. I don't want to document our intended UX change of moving offline PKI into a pseudo-pki provider before the change is made in the console, but I think this is an okay middle ground.
| Golioth supports two mechanisms for registering CAs: Direct connections to | ||
| external PKI providers, and manually uploading CA certificates. By establishing a | ||
| direct connection to an external PKI provider, Golioth automatically keeps an up | ||
| to date list of CAs, and is able to forward certificate signing requests on | ||
| behalf of your devices, allowing devices to perform certificate rotation through | ||
| Golioth's infrastructure. |
There was a problem hiding this comment.
Similar to change of framing to "Offline" provider, can we adjust this section to, rather than describing as two different mechanisms, just describe as PKI Providers, each of which may support different capabilities. Then the two supported providers are AWS Private CA and Offline, the latter of which does not support certificate rotation. I think this will set us up well as we introduce new providers, and restructure the existing manual upload functionality as an offline provider.
trond-snekvik
force-pushed
the
pki-providers
branch
from
ccc343a to
99d16e0
Compare
hasheddan
left a comment
hasheddan
left a comment
There was a problem hiding this comment.
Thanks @trond-snekvik! One minor suggested change but otherwise LGTM!
|
|
||
| When one of your devices connects to Golioth, it'll prove its identity by | ||
| presenting a signed certificate. The device certificate contains the device's | ||
| public key, as well as its project and device ID. Device certificates are issued |
There was a problem hiding this comment.
| public key, as well as its project and device ID. Device certificates are issued | |
| public key, as well as its project and certificate ID. Device certificates are issued |
trond-snekvik
force-pushed
the
pki-providers
branch
from
99d16e0 to
6072783
Compare
Splits the PKI documentation out into multiple pages, adding documentation for how to set up AWS as an external PKI provider. The local PKI guide is also split into a separate page, which gets linked to from the main PKI page, alongside a link to the AWS page. Signed-off-by: Trond Snekvik <[email protected]>
trond-snekvik
force-pushed
the
pki-providers
branch
from
6072783 to
117cf28
Compare
Splits the PKI documentation out into multiple pages, adding documentation for how to set up AWS as an external PKI provider.
The local PKI guide is also split into a separate page, which gets linked to from the main PKI page, alongside a link to the AWS page.