RFC 9447

Automated Certificate Management Environment (ACME) Challenges Using an Authority Token

📅 published September 2023, from ietf

RFC 9447: Automated Certificate Management Environment (ACME) Challenges Using an Authority Token 🎀

Okay bestie, let's start with the basics 💖 This is an IETF document (Internet Engineering Task Force), it's RFC 9447, and it came out in September 2023. It's on the Standards Track, which means it's the real deal 👑 The authors are J. Peterson, M. Barnes, D. Hancock, and C. Wendt, and the affiliations listed are Neustar and Somos. The ISSN is 2070-1721 🌸

Abstract 🦋

Okay so some proposed extensions to ACME need you to prove you're eligible for a certificate by asking an external authority for a token, based on a particular policy 🔥 This document specifies a generic Authority Token Challenge for ACME that supports subtype claims for different identifiers or namespaces. Those can be defined separately for specific applications 💅

Status of This Memo ✨

This is an Internet Standards Track document 👑

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.

Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc9447.

Copyright (c) 2023 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.

Table of Contents 🧚

1.  Introduction
2.  Requirements Language
3.  ACME Authority Token Challenge
  3.1.  Token Type Requirements
  3.2.  Authority Token Scope
  3.3.  Binding Challenges
4.  Authority Token Challenge tkauth-type Registration
5.  Acquiring a Token
  5.1.  Basic REST Interface
6.  IANA Considerations
  6.1.  ACME Validation Method Registration
  6.2.  JSON Web Token Claim Registration
  6.3.  Creation of ACME Authority Token Challenge Types Registry
7.  Security Considerations
8.  References
  8.1.  Normative References
  8.2.  Informative References
Acknowledgements
Authors' Addresses

1. Introduction 💜

ACME [RFC8555] is a mechanism for automating certificate management on the Internet 🫶 It lets administrative entities prove effective control over resources, like domain names, and automates issuing certificates that attest control or ownership of those resources.

Sometimes proving control over an identifier means getting an attestation from a third party who has authority over the resource. An example would be an external policy administrator for a namespace other than the DNS application that ACME was originally designed to support 🦋 So this specification defines a generic Authority Token Challenge. ACME servers can issue it to require clients to return an Authority Token that authorizes a given issuance. The challenge includes a type indication that tells the client what sort of token it needs to acquire. The Authority Token Challenge is expected to be usable for a variety of identifier types. This document describes an architecture for Authority Tokens, defines a JSON Web Token (JWT) [RFC7519] Authority Token format along with a protocol for token acquisition, and shows how to plug these tokens into an ACME challenge ✨

As a concrete example, [RFC9448] provides a mechanism that lets service providers acquire certificates corresponding to a Service Provider Code (SPC), as defined in [RFC8226], by consulting an external authority responsible for those codes 🎀 Communications Service Providers (CSPs) can also delegate authority over numbers to their customers. CSPs that support ACME can then help customers acquire certificates for those numbering resources with ACME. This can permit number acquisition flows compatible with those shown in [RFC8396] 💅

2. Requirements Language 🌸

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here 📚

3. ACME Authority Token Challenge 🔥

Proving that a device on the Internet has effective control over a non-Internet resource is not as straightforward as proving control over Internet resources, like a DNS zone or a web page 😭 Here's the idea: if the issuer of identifiers in a namespace (or someone acting on the issuer's behalf) can run a service that grants Authority Tokens to the people it has issued identifiers to, then a generic token could be used as a response to an ACME challenge. So this specification defines an Authority Token issued by an authority over a namespace to an ACME client. The client then delivers it to an ACME server in response to a challenge. Authority over a hierarchical namespace can also be delegated, so delegates of a root authority can act as Token Authorities for certain types of names too 👑

This architecture assumes a trust relationship between certification authorities (CAs) and Token Authorities. In other words, CAs are willing to accept the attestation of Token Authorities for particular types of identifiers as sufficient proof to issue a credential 🤝 It also assumes ACME clients have a relationship with Token Authorities, which lets them authenticate and authorize the issuance of Authority Tokens to the proper entities. This ACME challenge has no applicability to identifiers or authorities where those pre-associations cannot be assumed 🙈

The ACME Authority Token Challenge type, "tkauth-01", is specified here for use with the "TNAuthList" (Telephone Number Authentication List) ACME Identifier Type described in [RFC9448]. To use the "tkauth-01" Validation Method with an ACME Identifier Type other than "TNAuthList", that identifier type would need to be listed in a new registration in the ACME Validation Methods registry maintained by IANA. "tkauth-01" also supports different token subtypes 🦋 The token subtype is determined by a new ACME challenge field, tkauth-type. An IANA registry is used to manage the values of tkauth-type (see Section 6.3). This challenge type also has a new token-authority field, which designates a location where a token can be acquired 🎀

3.1. Token Type Requirements 💖

IANA will maintain a registry of tkauth-types under a policy of Specification Required. To register a new tkauth-type, specifications must address the following requirements. Where a tkauth-type admits of its own subtypes, those subtypes inherit these requirements 📝

While Authority Token types do not need to be specific to a namespace, every token must carry enough information for a CA to determine the name for which certificate issuance is authorized. Some types of Authority Token might be reusable across a number of different namespaces, while others might be specific to a particular type of name. So when defining tkauth-types, future specifications must indicate how a token conveys to the CA the name(s) that the Token Authority is attesting the ACME client controls 🔍

While nothing precludes use cases where an ACME client is itself a Token Authority, an ACME client will typically need a protocol to request and retrieve an Authority Token. The Token Authority needs certain information from an ACME client to ascertain that it is an authorized entity to request a certificate for a particular name. The protocols used to request an Authority Token MUST convey to the Token Authority the identifier type and value that will be used in the ACME challenge, as well as the binding (see Section 3.3). Those MUST be reflected in the Authority Token. A baseline mechanism for how the Token Authority authenticates and authorizes ACME clients to receive Authority Tokens is given in Section 5 🫶

Because the assignment of resources can change over time, demonstrations of authority must be regularly refreshed. Definitions of a tkauth-type MUST specify how they manage the freshness of authority assignments. Typically, a CA will expect a regular refreshing of the token ⏰

3.2. Authority Token Scope 🌈

An Authority Token is used to answer a challenge from an ACME server when a certificate issuance is requested. The Authority Token could be requested from the Token Authority after a challenge has been received, or it could have been acquired before the initial ACME client request. A Token Authority could grant an Authority Token with the exact same scope as the requested certificate to a client. Alternatively, an Authority Token could attest to all of the resources the client is eligible to receive certificates for, which could be a superset of the scope of the requested certificate 🧠

For example, imagine a Token Authority for DNS names that knows a client is eligible to receive certificates for "example.com" and "example.net". The client asks an ACME server for a certificate for "example.com", and the server directs the client to acquire an Authority Token from the Token Authority. When the client sends an acquisition request (see Section 5) to the Token Authority, the Token Authority could issue a token scoped just to "example.com", or a token that attests the client is eligible to receive certificates for both "example.com" or "example.net". The upside of the second option is that if, later on (but still within the expiry of the token), the client wanted a certificate for "example.net", it wouldn't have to go back to the Token Authority, because the token effectively pre-authorized that certificate 🦋

Applications of the Authority Token to different identifier types might require different scopes. So registrations of tkauth-types should be clear about if and how a scope greater than that of the requested certificate would be conveyed in a token 💅

Part 1 of 3 is done 🎀 Part 2 picks up with Section 3.3, so stay tuned 💕

3.3. Binding Challenges 🔗

okay bestie, so Authority Tokens need a way to stay tied to the right ACME client 🫶 Otherwise someone could steal a token meant for something else and cut-and-paste it into a totally different situation 💀 To stop that, every Authority Token carries a binding that the Token Authority signs 🔏 The ACME server can check that binding and confirm the token was actually granted to the client that asked for it, and not to some random other entity 🕵️‍♀️ It is RECOMMENDED that the ACME account fingerprint be used for this binding 💜

Now here's the tradeoff, and it's a big one 👀 If you bind a token to a particular ACME account, that token can be reused for multiple challenges all the way until it expires ⏳ This can be a really good thing when you're using short-lived certificates ✨ For example, it helps when the ACME server issues challenges more often than an Authority Token can or should issue tokens, or when the Authority Token scope (see Section 3.2) is broad, so narrower certificates get issued every now and then 🌸

For some identifier types, binding to a nonce that's specific to the challenge might make more sense than binding to an ACME account fingerprint 🧚 How the nonce or any other factors get used for this is left up to the identifier type profile for the Authority Token 🎀

Heads up, this part is lowkey the most important security bit 😭 The fingerprint in the client's JWT gets reflected in the Authority Token the Token Authority hands back, but the Token Authority doesn't have to check that fingerprint at all 🙈 So if an attacker grabbed a fingerprint and had their own account with the Token Authority, they could copy that fingerprint into their own JWT and get an Authority Token carrying it 💀 But if they tried to present that token to an ACME service, the service would notice the fingerprint doesn't match the attacker's own ACME account fingerprint and say nope 🚫 So unless an attacker can compromise a target ACME account or get similar privileges, the binding stays secure 🔐

4. Authority Token Challenge tkauth-type Registration ✨

This document defines a tkauth-type called "atc", which is a standard JWT [RFC7519] that uses a signature string defined by a JSON Web Signature (JWS) [RFC7515] 💅 The "atc" tkauth-type MAY be used for any number of different ACME Identifier Types in the ACME challenge 🌈

There's also a brand-new JWT claim called "atc" (Authority Token Challenge), and it lists the identifier type used in that Authority Token 🦋 The "atc" tkauth-type is only for JWTs 🙅‍♀️ If somebody wants a non-JWT format for the ACME Authority Token Challenge, they should specify a different tkauth-type and register it in the "ACME Authority Token Challenge Types" registry from Section 6.3 📝

For this JWT-based ACME Authority Token usage, it is OPTIONAL for the JWT payload to include an "iss", which tells you which Token Authority made the token 🧾 You only need it if the "x5u" or "x5c" element in the header doesn't already say that 🤷‍♀️ Usually that'll be the same location that showed up in the "token-authority" field of the ACME challenge, when that field is there 🌸 Now, for replay prevention, the JWT MUST contain a "jti" element and an "exp" claim 🔒 The "exp" claim handles token freshness ⏰ The "jti" does more than prevent replay, too: it's a handy way to reliably track when the same "atc" Authority Token gets used for multiple challenges over time within its lifetime 📊

The JWT payload MUST also contain the new "atc" claim (Authority Token Challenge) 🎀 That claim has three required elements in a JSON map: the ATC identifier type ("tktype"), the identifier value ("tkvalue"), and the binding ("fingerprint") 💖 The "tktype" can only be one of the values in the "ACME Identifier Types" registry, as defined by [RFC8555] 📚 The identifier type and value are the ones given in the ACME challenge and passed along to the Token Authority by the ACME client 🫶 For the "atc" tkauth-type, the "fingerprint" binding is assumed to be a fingerprint of the ACME credential for the account used to request the certificate 🔑 How that binding actually gets generated is left to the identifier type profile for the Authority Token (see Section 3.3) 🧠 The "tkvalue" shows the scope of authority. The token's semantics are outside the scope of this document, since they'll be specified by the "tkvalue" identifier in a separate specification 📜

Following the example of [RFC9448], the "tktype" identifier type could be TNAuthList (as defined in [RFC8226]), and that would be the value of the "tkvalue" element that the Token Authority is attesting 📞 In practice, that scope might include a list of Service Provider Code elements, telephone number range elements, and/or individual telephone numbers 📱 Here's an example 👇

    {
"protected": base64url({
     "typ":"JWT",
 "alg":"ES256",
 "x5u":"https://authority.example.org/cert"
    }),
"payload": base64url({
     "iss":"https://authority.example.org/authz",
 "exp":1300819380,
 "jti":"id6098364921",
 "atc":{"tktype":"TnAuthList","tkvalue":"F83n2a...avn27DN3==",
 "fingerprint":"SHA256 56:3E:CF:AE:83:CA:4D:15:B0:29:FF:1B:71:D3:
 BA:B9:19:81:F8:50:9B:DF:4A:D4:39:72:E2:B1:F0:B9:38:E3"}
    }),
 "signature": "9cbg5JO1Gf5YLjjz...SpkUfcdPai9uVYYQ"
    }

The "atc" claim can optionally have a fourth boolean element, "ca" 🌟 If it's set to "true", that means the Token Authority is giving permission to issue a certification authority certificate instead of an end-entity certificate for the names in question 👑 That also allows subordinate delegations from the issued certificate (using [RFC9115] or similar mechanisms) 🌿 If the "ca" element is absent, the Token Authority is explicitly withholding permission 🙅‍♀️ So the "atc" object in the example above would look like this:

"atc":{"tktype":"TnAuthList","tkvalue":"F83n2a...avn27DN3==",
"ca":true,"fingerprint":"SHA256 56:3E:CF:AE:83:CA:4D:15:B0:29:FF:1B:
71:D3:BA:B9:19:81:F8:50:9B:DF:4A:D4:39:72:E2:B1:F0:B9:38:E3"} }

Specifications of "tktype" identifier types may define additional optional "atc" elements 🦄

5. Acquiring a Token 🎟️

Getting an Authority Token needs a network interface, unless the entity acting as the ACME client is also a Token Authority that the ACME server trusts 💁‍♀️ Implementations compliant with this specification MUST support an HTTPS interface for Authority Token acquisition, as described below 🔐 Other interfaces MAY be supported too 💫

5.1. Basic REST Interface 🌐

To request an Authority Token from a Token Authority, the client sends an HTTPS POST request [RFC9110] 📮 This spec assumes that clients already know the Token Authority URIs through existing business relationships, and that the credentials and the authentication and authorization for Authority Token acquisition are covered by that relationship 🤝 Different services can organize their web resources in their own domain-specific ways, but the resource locator should specify the client's account, an identifier for the service provider, and finally a locator for the token 🗂️

POST /at/account/:id/token HTTP/1.1
Host: authority.example.com
Content-Type: application/json

Quick note: :id here is just a placeholder for an actual account identifier 🙈 The body of the POST request MUST contain the Authority Token Challenge element (the key "atc", a colon, and its value) that the client wants the Token Authority to generate 💌 That's how the client proposes the scope of the Authority Token it'd like to get from the Token Authority 🎯

In common use cases, the "tkvalue" in this request asks the Token Authority to issue a token that attests the entire scope of authority the client is entitled to 👑 The client can also ask for an Authority Token covering just a subset of its own authority, using the "tkvalue" element in the Authority Token Challenge object 🍰 How "tkvalue" gets defined depends on the identifier type 🧩 For the TNAuthList identifier type, for example, a request for an Authority Token can ask for authority over just a single telephone number, in the way the TNAuthList specification defines 📞

Finally, the JSON object MAY also contain an optional boolean element, "ca", which means the client is asking the Token Authority to issue an Authority Token with the "ca" flag set, as described in Section 4 🌸

After an HTTPS-level challenge (for example, a 401 HTTP response code) to verify the client's identity, and after the Token Authority makes an authorization decision about whether the client should get an Authority Token with the requested scope, then in the success case the Token Authority MUST return a 200 OK with a body of type "application/json" containing the Authority Token 🥳

A full example of "atc" token acquisition using the HTTP interface, with the "tktype" of "TNAuthList", is in Section 5.5 of [RFC9448] 📖✨

6. IANA Considerations 🗂️

6.1. ACME Validation Method Registration 💎

IANA has added a new ACME Validation Method (per [RFC8555]) to the "ACME Validation Methods" subregistry of the "Automated Certificate Management Environment (ACME) Protocol" registry group, like this 👇

  • Label: tkauth-01
  • Identifier Type: TNAuthList
  • ACME: Y
  • Reference: RFC 9447

6.2. JSON Web Token Claim Registration 🏷️

IANA has added a new claim to the "JSON Web Token Claims" registry, as defined in [RFC7519], like so 🌈

  • Claim name: atc
  • Claim Description: Authority Token Challenge
  • Change Controller: IETF
  • Specification document(s): RFC 9447

6.3. Creation of ACME Authority Token Challenge Types Registry 🆕

IANA has created a new registry for "ACME Authority Token Challenge Types", used in these challenges 🎉 It runs under a Specification Required policy and follows the requirements in Section 3.1, and it has three columns: Label, Description, and Reference 📋 The initial content of the registry is:

  • Label: atc (as defined in Section 4)
  • Description: JSON Web Token (JWT) challenge type
  • Reference: RFC 9447

7. Security Considerations 🔐

okay bestie, this is the serious part, so let's get into it 🥺

Per the guidance in [RFC8555], ACME transactions MUST use TLS, and the HTTPS REST transactions used to request and acquire Authority Tokens MUST use TLS too. The whole point is to stop eavesdroppers from snatching Authority Tokens 👀. A preexisting trust relationship between the HTTPS REST client and the Token Authority also has to exist so the two parties can actually authenticate each other 🫶. The security considerations of [RFC8555] apply to this mechanism too, and implementations should follow the best practices in [RFC8725] 💅.

As described in Section 3.2, an Authority Token can either have a scope that attests to all of the resources a client is eligible to get certificates for, or a more limited scope that only covers the resources a client will receive a certificate for from one particular certification authority 🧚. Any certification authority that sees an Authority Token can learn what resources a client can claim. That's a privacy risk in some cases, so Authority Token scopes should be limited to only the resources the requested ACME certificate will attest 🙈.

In cases where a tkauth-type, as defined in Section 4, has its own subtypes, the security of features like binding challenges (see Section 3.3) will depend on the subtype specification 🌈.

⚠️ Okay, this part is giving high-stakes drama. If an attacker captures an Authority Token, they could potentially get a certificate from a CA. So all Authority Tokens MUST contain a field that tells the CA which ACME client asked the Token Authority for the token (here, that's the fingerprint specified in Section 4). Every Authority Token must also specify an expiry, which is the token's own expiry as proof for a CA and is separate from the expiry of the name. For some applications, it may make sense for that expiry to be quite short ⏳. ACME services relying on Authority Tokens SHOULD NOT issue certificates with a longer expiry than the expiry of the Authority Token. Any protocol used to retrieve Authority Tokens from a Token Authority MUST use confidentiality so eavesdroppers can't grab an Authority Token 😭. The details of that protocol are out of scope for this specification 💀.

This document only specifies SHA256 for the fingerprint hash 🔥. However, the syntax of the fingerprint object would permit other keys if a more robust algorithm were ever needed in the future, because of concerns about algorithmic agility. Future specifications can define new keys for the fingerprint object as needed 🦋.

8. References ✨

8.1. Normative References

[RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
           Requirement Levels", BCP 14, RFC 2119,
           DOI 10.17487/RFC2119, March 1997,
           <https://www.rfc-editor.org/info/rfc2119>.

[RFC7515]  Jones, M., Bradley, J., and N. Sakimura, "JSON Web
           Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
           2015, <https://www.rfc-editor.org/info/rfc7515>.

[RFC7519]  Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
           (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
           <https://www.rfc-editor.org/info/rfc7519>.

[RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
           2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
           May 2017, <https://www.rfc-editor.org/info/rfc8174>.

[RFC8555]  Barnes, R., Hoffman-Andrews, J., McCarney, D., and J.
           Kasten, "Automatic Certificate Management Environment
           (ACME)", RFC 8555, DOI 10.17487/RFC8555, March 2019,
           <https://www.rfc-editor.org/info/rfc8555>.

[RFC8725]  Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best
           Current Practices", BCP 225, RFC 8725,
           DOI 10.17487/RFC8725, February 2020,
           <https://www.rfc-editor.org/info/rfc8725>.

[RFC9110]  Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
           Ed., "HTTP Semantics", STD 97, RFC 9110,
           DOI 10.17487/RFC9110, June 2022,
           <https://www.rfc-editor.org/info/rfc9110>.

[RFC9448]  Wendt, C., Hancock, D., Barnes, M., and J. Peterson,
           "TNAuthList Profile of Automated Certificate Management
           Environment (ACME) Authority Token", RFC 9448,
           DOI 10.17487/RFC9448, September 2023,
           <https://www.rfc-editor.org/info/rfc9448>.

8.2. Informative References

[RFC8226]  Peterson, J. and S. Turner, "Secure Telephone Identity
           Credentials: Certificates", RFC 8226,
           DOI 10.17487/RFC8226, February 2018,
           <https://www.rfc-editor.org/info/rfc8226>.

[RFC8396]  Peterson, J. and T. McGarry, "Managing, Ordering,
           Distributing, Exposing, and Registering Telephone Numbers
           (MODERN): Problem Statement, Use Cases, and Framework",
           RFC 8396, DOI 10.17487/RFC8396, July 2018,
           <https://www.rfc-editor.org/info/rfc8396>.

[RFC9115]  Sheffer, Y., López, D., Pastor Perales, A., and T.
           Fossati, "An Automatic Certificate Management Environment
           (ACME) Profile for Generating Delegated Certificates",
           RFC 9115, DOI 10.17487/RFC9115, September 2021,
           <https://www.rfc-editor.org/info/rfc9115>.

Acknowledgements 🫶

We would like to Roman Danyliw and Ben Kaduk for contributions to this problem statement and framework. 🌸

Authors' Addresses 💌

Jon Peterson
Neustar, Inc.
Email: jon.peterson@team.neustar


Mary Barnes
Neustar, Inc.
Email: mary.ietf.barnes@gmail.com


David Hancock
Somos
Email: davidhancock.ietf@gmail.com


Chris Wendt
Somos
Email: chris-ietf@chriswendt.net
📦 where this page comes from