ACME Challenges Using an Authority Token
draft-ietf-acme-authority-token-05

Abstract

Some proposed extensions to the Automated Certificate Management Environment (ACME) rely on proving eligibility for certificates through consulting an external authority that issues a token according to a particular policy. This document specifies a generic Authority Token challenge for ACME which supports subtype claims for different identifiers or namespaces that can be defined separately for specific applications.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on September 10, 2020.

Copyright Notice

Copyright (c) 2020 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 Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

Table of Contents

• 1. Introduction
• 2. Terminology
• 3. Challenges for an Authority Token
• 3.1. Token Type Requirements
• 3.2. Authority Token Scope
• 3.3. Binding Challenges
• 4. ATC tkauth-type Registration
• 5. Acquiring a Token
• 5.1. Basic REST Interface
• 6. Using an Authority Token in a Challenge
• 7. Acknowledgements
• 8. IANA Considerations
• 9. Security Considerations
• 10. Normative References
• Authors' Addresses

1. Introduction

ACME is a mechanism for automating certificate management on the Internet. It enables administrative entities to prove effective control over resources like domain names, and automates the process of generating and issuing certificates.

In some cases, proving effective control over an identifier requires an attestation from a third party who has authority over the resource, for example, an external policy administrator for a namespace other than the DNS application ACME was originally designed to support. In order to automate the process of issuing certificates for those resources, this specification defines a generic Authority Token challenge that ACME servers can issue in order to require clients to return such a token. The challenge contains a type indication that tells the client what sort of token it needs to acquire. It is expected that the Authority Token challenge will be usable for a variety of identifier types.

For example, the system of [I-D.ietf-acme-authority-token-tnauthlist] provides a mechanism that allows service providers to acquire certificates corresponding to a Service Provider Code (SPC) as defined in [RFC8226] by consulting an external authority responsible for those codes. Furthermore, Communications Service Providers (CSPs) can delegate authority over numbers to their customers, and those CSPs who support ACME can then help customers to acquire certificates for those numbering resources with ACME. This can permit number acquisition flows compatible with those shown in [RFC8396]. Another, similar example would a mechanism that permits CSPs to delegate authority for particular telephone numbers to customers, as described in [I-D.ietf-acme-telephone].

2. Terminology

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. Challenges for an Authority Token

Proving that a device on the Internet has effective control over a non-Internet resource is not as straightforward as proving control over an Internet resources like a DNS zone or a web page. Provided that the issuer of identifiers in a namespace, or someone acting on the issuer's behalf, can implement a service that grants Authority Tokens to the people to whom it has issued identifiers, a generic token could be used as a response to an ACME challenge. This specification, therefore, defines an Authority Token issued by an authority over a namespace to an ACME client for delivery to a CA in response to a challenge. Authority over a hierarchical namespace can also be delegated, so that delegates of a root authority can themselves act as Token Authorities for certain types of names.

This architecture assumes a trust relationship between CAs and Token Authorities: that CAs are willing to accept the attestation of Token Authorities for particular types of identifiers as sufficient proof to issue a credential. It furthermore assumes that ACME clients have a relationship with Token Authorities which permits them to 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.

ACME challenges that support Authority Tokens therefore need to specify the type of token they require; CAs can even provide a hint in their challenges to ACME clients that tells them how to find a Token Authority who can issue tokens for a given namespace. This challenge type thus requires a new "tkauth-type" element, and may optionally supply a "token-authority" designating a location where tokens can be acquired. The set of "tkauth-type" values and the semantic requirements for those tokens are tracked by an IANA registry.

3.1. Token Type Requirements

The IANA will maintain a registry of tkauth-types under a policy of Specification Required. In order to register a new tkauth-type, specifications must address the following 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 that it will issue a certificate for. Some types of Authority Token types might be reusable for a number of different namespaces; other might be specific to a particular type of name. Therefore, in defining tkauth-types, future specifications must indicate how a token conveys to the CA the name(s) that the Token Authority is attesting that 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 will require certain information from an ACME client in order to ascertain that it is the right 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 from the ACME challenge, as well as the binding (see Section 3.3), and 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, upon a request for the issuance of a certificate. It could be that the AT is requested from the Token Authority after a challenge has been received, or it could be that the AT was acquired prior to the initial ACME client request. A Token Authority could grant to a client a Token that has the exact same scope as the requested certificate; alternatively, an Authority Token could attest to all of the resources that the client is eligible to receive certificates for, which could be a superset of the scope of the requested certificate.

For example, imagine a case where an Authority for DNS names knows that 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", the server directs the client to acquire an Authority Token from the Authority. When the client sends an acquisition request (see Section 5) to the Authority, the 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 advantage of the latter is that if, at a later time (but one within the expiry of the JWT), the client wanted to acquire a certificate for "example.net", it would not have to return to the Authority, as the Token effectively pre-authorized the issuance of that certificate.

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

3.3. Binding Challenges

Applications that use the Authority Token need a way to correlate tokens issued by an Authority with the proper ACME client, to prevent replay or cut-and-paste attacks using a token issued for a different purpose. To mitigate this, Authority Tokens contain a binding signed by an Authority; an ACME server can use the binding to determine that a Token presented by a client was in fact granted by the Authority based on a request from the client, and not from some other entity.

Binding an Authority Token to a particular ACME account entails that the Token could be reused up until its expiry for multiple challenges issued by an ACME server. This might be a desirable property when using short-lived certificates, for example, or in any cases where the ACME server issues challenges more frequently that an Authority Token can or should issue tokens, or in cases where the Authority Token scope (see Section 3.2) is broad, so certificates with a more narrow scope may periodically be issued.

For some identifier types, it may be more appropriate to bind the Authority Token to a nonce specific to the challenge rather than to an ACME account fingerprint. Any specification of the use of the nonce for this purpose is left to the identifier type profile for the Authority Token.

4. ATC tkauth-type Registration

This draft registers a tkauth-type of "atc", for the Authority Token Challenge. Here the "atc" tkauth-type signifies a standard JWT token using a JWS-defined signature string. This may be used for any number of different identifier types given in ACME challenges. The "atc" element (defined below) lists the identifier type used by tokens based on ATC. The use of "atc" is restricted to JWTs, if non-JWT tokens were desired for ACME challenges, a different tkauth-type should be defined for them.

For this ACME Authority Token usage of JWT, the payload of the JWT OPTIONALLY contain an "iss" indicating the Token Authority that generated the token, if the "x5u" element in the header does not already convey that information; typically, this will be the same location that appeared in the "token-authority" field of the ACME challenge. In order to satisfy the requirement for replay prevention the JWT MUST contain a "jti" element, and an "exp" claim. In addition to helping to manage replay, the "jti" provides a convenient way to reliably track with the same "atc" Authority Token is being used for multiple challenges over time within its set expiry.

The JWT payload must also contain a new JWT claim, "atc", for Authority Token Challenge, which contains three mandatory elements in an array: the identifier type ("tktype"), the identifier value ("tkvalue"), and the binding ("fingerprint"). The identifier type and value are those given in the ACME challenge and conveyed to the Token Authority by the ACME client. Following the example of [I-D.ietf-acme-authority-token-tnauthlist], the "tkvalue" identifier type could be the TNAuthList, with a "tkvalue" as defined in [RFC8226] that the Token Authority is attesting. Practically speaking, that scope may comprise a list of Service Provider Code elements, telephone number range elements, and/or individual telephone numbers. For the purposes of the "atc" tkauth-type, the binding "fingerprint" is assumed to be a fingerprint of the ACME credential for the account used to request the certificate, but the specification of how the binding is generated is left to the identifier type profile for the Authority Token.

So for example:

    { "typ":"JWT",
     "alg":"ES256",
     "x5u":"https://authority.example.org/cert"}
    {
    "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"} }
            

   "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"} }
        

Optionally, the "atc" element may contain a fourth element, "ca". If set to "true", the "ca" element indicates that the Token Authority is granting permission to issue a certification authority certificate rather than an end-entity certificate for the names in question. This permits subordinate delegations from the issued certificate. If the "ca" element is absent, the Token Authority is explicitly withholding permission. The "atc" object in the example above would then look like:

Specifications of "tktype" identifier type may define additional optional "atc" elements.

5. Acquiring a Token

The acquisition of a Authority Token requires a network interface, apart from potential use cases where the entity that acts as an ACME client itself also acts as a Token Authority trusted by the ACME server. Implementations compliant with this specification MUST support an HTTPS REST interface for Authority Token acquisition as described below, though other interfaces MAY be supported as well.

5.1. Basic REST Interface

In order to request an Authority Token from a Token Authority, a client sends an HTTPS POST request. Different services may organize their web resources in domain-specific ways, but the resource locator should specify the account of the client, 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
                  

   {
   "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"} }
   }

                

The body of the POST request will contain the ATC element that the client is requesting the Token Authority generate.

In common use cases, the "tkvalue" in this request is asking that the Token Authority issue a token that attests the entire scope of authority to which the client is entitled. The client may also request an AT with some subset of its own authority via the "tkvalue" element in the ATC object. The way that "tkvalue" is defined will necessarily be specific to the identifier type. For the TNAuthlist identifier type, for example, an object requesting an AT could request authority for only a single telephone number in a way that is defined in the TNAuthList specification.

Finally, the JSON object may also contain a optional boolean element "ca" which signifies that the client is requesting that the Token Authority issue an AT with the "ca" flag set, as described in Section 4.

After an HTTPS-level challenge to verify the identity of the client and subsequently making an authorization decision, in the success case the Token Authority returns a 200 OK with a body of type "application/json" containing the Authority Token.

6. Using an Authority Token in a Challenge

Taking the identifier example of TNAuthList from [I-D.ietf-acme-authority-token-tnauthlist], an ACME for this tkauth-type challenge might for example look as follows:

    HTTP/1.1 200 OK
    Content-Type: application/json
    Link: <https://example.com/acme/some-directory>;rel="directory"

    {
     "status": "pending",

     "identifier": {
        "type": "TNAuthList",
        "value": "F83n2a...avn27DN3=="
      },
      "challenges": [
      {
        "type": "tkauth-01",
        "tkauth-type": "atc",
        "token-authority": "https://authority.example.org/authz",
        "url": "https://boulder.example.com/authz/asdf/0"
        "token": "IlirfxKKXAsHtmzK29Pj8A" }
      ],
    }
	  	  

Entities receiving this challenge know that they can, as a proof, acquire an ATC token from the designated Token Authority (specified in the "token-authority" field), and that this authority can provide tokens corresponding to the identifier type of "TNAuthList".

Once the ATC has been acquired by the ACME Client, it can be posted back to the URL given by the ACME challenge.

    POST /acme/authz/asdf/0 HTTP/1.1
    Host: boulder.example.com
    Content-Type: application/jose+json

     {
      "protected": base64url({
      "alg": "ES256",
      "kid": "https://boulder.example.com/acme/reg/asdf",
      "nonce": "Q_s3MWoqT05TrdkM2MTDcw",
      "url": "https://boulder.example.com/acme/authz/asdf/0"
       }),
      "payload": base64url({
      "atc": "evaGxfADs...62jcerQ"
         }),
      "signature": "5wUrDI3eAaV4wl2Rfj3aC0Pp--XB3t4YYuNgacv_D3U"
     }

		  	  

The "atc" field in this response contains the Authority Token.

7. Acknowledgements

We would like to thank you for your contributions to this problem statement and framework.

8. IANA Considerations

This document requests that the IANA registers a new ACME identifier type (per [RFC8555]) for the label "atc", for which the reference is [RFCThis].

This document further requests that the IANA create a registry for "token types" as used in these challenges, following the requirements in Section 3.1, pre-populated with the label of "atc" per Section 4 with a value of [RFCThis].

9. Security Considerations

Per the guidance in [RFC8555], ACME transactions MUST use TLS, and similarly the HTTPS REST transactions used to request and acquire authority tokens MUST use TLS. These measures are intended to prevent the capture of Authority Tokens by eavesdroppers. The security considerations of [RFC8555] apply to the use of the mechanism in this specification.

The capture of Authority Tokens by an adversary could enable an attacker to acquire a certificate from a CA. Therefore, all Authority Tokens MUST contain a field that identifies to the CA which ACME client requested the token from the authority; here that is the fingerprint specified in Section 4). All Authority Tokens must specify an expiry (of the token itself as proof for a CA, as opposed to the expiry of the name), and for some application, it may make sense of that expiry to be quite short. Any protocol used to retrieve Authority Tokens from an authority MUST use confidentiality to prevent eavesdroppers from acquiring an Authority Token.

10. Normative References

Authors' Addresses