diff --git a/.github/mdl.config.json b/.github/mdl.config.json index 5ee12708..001dc72c 100644 --- a/.github/mdl.config.json +++ b/.github/mdl.config.json @@ -68,6 +68,9 @@ }, { "pattern": "^https://.*cr.yp.to" + }, + { + "pattern": "^https://datatracker.ietf.org" } ], "replacementPatterns": [ diff --git a/certificate-manager/acme/README.mdx b/certificate-manager/acme/README.mdx index 9117b786..be28d74d 100644 --- a/certificate-manager/acme/README.mdx +++ b/certificate-manager/acme/README.mdx @@ -22,6 +22,12 @@ including enterprise use cases. - [When to use ACME](./when-to-use-acme.mdx) describes scenarios for which ACME is a great fit. It also includes some scenarios for which ACME isn't a good solution. - [How to use ACME](./how-to-use-acme.mdx) describes how you can use the Smallstep platform to deploy ACME in your internal network. + +
+ ACME vs. ACME device attestation. Standard ACME issues certificates to servers and workloads, proving control of a domain or IP address through the http-01, dns-01, or tls-alpn-01 challenges. ACME device attestation (ACME DA) extends the same protocol to issue hardware-bound certificates for device identity, using the device-attest-01 challenge to verify a device's built-in security module. Reach for ACME DA when you're identifying devices rather than servers. +
+ + Deploying and maintaining a PKI with ACME support on your internal network becomes a breeze using [Certificate Manager](https://smallstep.com/certificate-manager/). Follow our [getting started](./how-to-use-acme.mdx#get-started) guide to start issuing certificates on your internal network using ACME. [Contact support](mailto:support@smallstep.com) in case you need help with deploying ACME in your enterprise. diff --git a/certificate-manager/acme/how-to-use-acme.mdx b/certificate-manager/acme/how-to-use-acme.mdx index 59d76cec..72447c19 100644 --- a/certificate-manager/acme/how-to-use-acme.mdx +++ b/certificate-manager/acme/how-to-use-acme.mdx @@ -130,5 +130,6 @@ Follow these three simple steps and start issuing certificates: * [Read the blog](https://smallstep.com/blog/private-acme-server/) that announced Smallstep ACME support. * Learn more about [Registration Authorities](../../registration-authorities/acme-for-certificate-manager.mdx) and how to use them to provide ACME on your internal network or how to integrate with Google Certificate Authority Service. * Start using ACME for Kubernetes certificates, learn how in [this tutorial](../../tutorials/kubernetes-acme-ca.mdx). +* Issue hardware-bound certificates for device identity with [ACME device attestation](https://smallstep.com/platform/acme-device-attestation/), using the `device-attest-01` challenge. diff --git a/certificate-manager/acme/when-to-use-acme.mdx b/certificate-manager/acme/when-to-use-acme.mdx index c47a0469..42444f62 100644 --- a/certificate-manager/acme/when-to-use-acme.mdx +++ b/certificate-manager/acme/when-to-use-acme.mdx @@ -43,6 +43,9 @@ The below listing is an overview of exemplary scenarios in which the ACME protoc - Kubernetes, with [cert-manager](https://cert-manager.io/) and the [ACME issuer](https://cert-manager.io/docs/configuration/acme/) enabled. For this to work, challenges for the identifiers need to be solvable by `cert-manager`. An example detailing this use case is available here: [Integrate Kubernetes cert-manager with an internal ACME CA](../../tutorials/kubernetes-acme-ca.mdx). +- An environment that needs strong, hardware-bound device identity. + [ACME device attestation (ACME DA)](https://smallstep.com/platform/acme-device-attestation/)—a standard Smallstep developed with Google at the IETF—extends ACME with the `device-attest-01` challenge, letting a device prove its identity using a built-in hardware security module such as a TPM or Secure Enclave. + It's natively supported on macOS, iOS, Windows, Android, and Linux, and is the modern replacement for SCEP. ### When not to use ACME @@ -56,9 +59,7 @@ These are summarized below: * Some cases that involve a technical issue or compliance requirement may still be supported when deploying an instance of the CA in Registration Authority (RA) mode. Our [RA documentation page](../../step-ca/registration-authority-ra-mode.mdx) describes this configuration in more detail. Or [contact us](mailto:support@smallstep.com) to see if we can support your use case. - * A [draft RFC for an ACME extension](https://datatracker.ietf.org/doc/draft-bweeks-acme-device-attest/) is in the making, describing how the ACME protocol can be used with challenges "solved" by a secure hardware component, like a Trusted Platform Module (TPM) or Secure Enclave (SE). - This protocol extension, optionally combined with ACME External Account Binding, could obviate the need for a separate channel for solving challenges. - At Smallstep we're closely monitoring progress of the RFC and may support this functionality in the future. + * For device identity, a hardware security module can prove control instead. See [ACME device attestation](https://smallstep.com/platform/acme-device-attestation/), described above under [Scenarios](#scenarios). - When a certificate requires email addresses to be signed, email signing certificates, for example. An informational extension to the ACME RFC adds [support for S/MIME](https://datatracker.ietf.org/doc/rfc8823/) certificates. The Smallstep platform doesn't currently support the extension, but we might do so in the future. diff --git a/certificate-manager/acme/why-use-acme.mdx b/certificate-manager/acme/why-use-acme.mdx index f2d6314c..a65585e9 100644 --- a/certificate-manager/acme/why-use-acme.mdx +++ b/certificate-manager/acme/why-use-acme.mdx @@ -25,6 +25,7 @@ Examples of older standards include Certificate Management over CMS (CMC, [RFC 5 These standards were originally designed for certificate management in internal networks and can be found in many deployments and new deployments using these protocols still happen. Some issues with these standards include the fact that they're getting older, them offering too many configuration options, and not being specified strictly enough. These result in the older standards being harder to implement and to be less aligned with current operational practices. +For device identity specifically, [ACME device attestation](https://smallstep.com/platform/acme-device-attestation/)—an ACME extension Smallstep developed with Google at the IETF—is the modern replacement for SCEP, binding certificates to a device's hardware through the `device-attest-01` challenge. ### Automated diff --git a/step-ca/acme-basics.mdx b/step-ca/acme-basics.mdx index d7fbdc8b..12ab56fb 100644 --- a/step-ca/acme-basics.mdx +++ b/step-ca/acme-basics.mdx @@ -120,10 +120,12 @@ This is a popular challenge type in cases where an ingress controller fronts cli ### The device attestation challenge (device-attest-01) The device attestation challenge (`device-attest-01`) is designed to issue client certificates bound to a device identifier. +Where the other challenge types prove control of a domain or IP address to secure a *server*, `device-attest-01` proves a *device's* hardware identity—the basis of ACME device attestation (ACME DA). It allows clients with an attached security module (TPM, Secure Enclave, YubiKey, etc) to request a certificate bound to the security module's permanent hardware identifier. It can also be used to attest the hardware protection of a private key in the security module. Further reading: +* [ACME Device Attestation](https://smallstep.com/platform/acme-device-attestation/)—Smallstep's platform for issuing hardware-bound device certificates with ACME DA, natively supported on macOS, iOS, Windows, Android, and Linux. * [Managed Device Attestation: ACME as the Bottom Turtle in Mobile Device Management](https://smallstep.com/blog/managed-device-attestation/) * [ACME Device Attestation Explained](https://smallstep.com/blog/acme-managed-device-attestation-explained/) focuses Device Attestation for MDM certificate enrollment on Apple devices.