draft-ietf-acme-authority-token-05.txt   draft-ietf-acme-authority-token-06.txt 
Network Working Group J. Peterson Network Working Group J. Peterson
Internet-Draft Neustar Internet-Draft Neustar
Intended status: Informational M. Barnes Intended status: Standards Track M. Barnes
Expires: September 10, 2020 Independent Expires: January 13, 2022 Independent
D. Hancock D. Hancock
C. Wendt C. Wendt
Comcast Comcast
March 9, 2020 July 12, 2021
ACME Challenges Using an Authority Token ACME Challenges Using an Authority Token
draft-ietf-acme-authority-token-05 draft-ietf-acme-authority-token-06
Abstract Abstract
Some proposed extensions to the Automated Certificate Management Some proposed extensions to the Automated Certificate Management
Environment (ACME) rely on proving eligibility for certificates Environment (ACME) rely on proving eligibility for certificates
through consulting an external authority that issues a token through consulting an external authority that issues a token
according to a particular policy. This document specifies a generic according to a particular policy. This document specifies a generic
Authority Token challenge for ACME which supports subtype claims for Authority Token challenge for ACME which supports subtype claims for
different identifiers or namespaces that can be defined separately different identifiers or namespaces that can be defined separately
for specific applications. for specific applications.
skipping to change at page 1, line 40 skipping to change at page 1, line 40
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on September 10, 2020. This Internet-Draft will expire on January 13, 2022.
Copyright Notice Copyright Notice
Copyright (c) 2020 IETF Trust and the persons identified as the Copyright (c) 2021 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Challenges for an Authority Token . . . . . . . . . . . . . . 3 3. ACME Authority Token Challenge . . . . . . . . . . . . . . . 3
3.1. Token Type Requirements . . . . . . . . . . . . . . . . . 4 3.1. Token Type Requirements . . . . . . . . . . . . . . . . . 4
3.2. Authority Token Scope . . . . . . . . . . . . . . . . . . 4 3.2. Authority Token Scope . . . . . . . . . . . . . . . . . . 4
3.3. Binding Challenges . . . . . . . . . . . . . . . . . . . 5 3.3. Binding Challenges . . . . . . . . . . . . . . . . . . . 5
4. ATC tkauth-type Registration . . . . . . . . . . . . . . . . 6 4. Authority Token Challenge tkauth-type Registration . . . . . 6
5. Acquiring a Token . . . . . . . . . . . . . . . . . . . . . . 7 5. Acquiring a Token . . . . . . . . . . . . . . . . . . . . . . 7
5.1. Basic REST Interface . . . . . . . . . . . . . . . . . . 7 5.1. Basic REST Interface . . . . . . . . . . . . . . . . . . 8
6. Using an Authority Token in a Challenge . . . . . . . . . . . 8 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9
7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 8. Security Considerations . . . . . . . . . . . . . . . . . . . 9
9. Security Considerations . . . . . . . . . . . . . . . . . . . 10 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 10
10. Normative References . . . . . . . . . . . . . . . . . . . . 10 9.1. Normative References . . . . . . . . . . . . . . . . . . 10
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12 9.2. Informative References . . . . . . . . . . . . . . . . . 11
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11
1. Introduction 1. Introduction
ACME [RFC8555] is a mechanism for automating certificate management ACME [RFC8555] is a mechanism for automating certificate management
on the Internet. It enables administrative entities to prove on the Internet. It enables administrative entities to prove
effective control over resources like domain names, and automates the effective control over resources like domain names, and automates the
process of generating and issuing certificates. process of generating and issuing certificates that attest control or
ownership of those resources.
In some cases, proving effective control over an identifier requires In some cases, proving effective control over an identifier requires
an attestation from a third party who has authority over the an attestation from a third party who has authority over the
resource, for example, an external policy administrator for a resource, for example, an external policy administrator for a
namespace other than the DNS application ACME was originally designed namespace other than the DNS application ACME was originally designed
to support. In order to automate the process of issuing certificates to support. In order to automate the process of issuing certificates
for those resources, this specification defines a generic Authority for those resources, this specification defines a generic Authority
Token challenge that ACME servers can issue in order to require Token challenge that ACME servers can issue in order to require
clients to return such a token. The challenge contains a type clients to return such a token. The challenge contains a type
indication that tells the client what sort of token it needs to indication that tells the client what sort of token it needs to
acquire. It is expected that the Authority Token challenge will be acquire. It is expected that the Authority Token challenge will be
usable for a variety of identifier types. usable for a variety of identifier types. In particular, this
document describes an architecture for Authority Tokens, defines a
the Authority Token format along with a protocol for token
acquisition, and shows how to integrate these tokens into an ACME
challenge.
For example, the system of [I-D.ietf-acme-authority-token-tnauthlist] For example, the system of [I-D.ietf-acme-authority-token-tnauthlist]
provides a mechanism that allows service providers to acquire provides a mechanism that allows service providers to acquire
certificates corresponding to a Service Provider Code (SPC) as certificates corresponding to a Service Provider Code (SPC) as
defined in [RFC8226] by consulting an external authority responsible defined in [RFC8226] by consulting an external authority responsible
for those codes. Furthermore, Communications Service Providers for those codes. Furthermore, Communications Service Providers
(CSPs) can delegate authority over numbers to their customers, and (CSPs) can delegate authority over numbers to their customers, and
those CSPs who support ACME can then help customers to acquire those CSPs who support ACME can then help customers to acquire
certificates for those numbering resources with ACME. This can certificates for those numbering resources with ACME. This can
permit number acquisition flows compatible with those shown in permit number acquisition flows compatible with those shown in
[RFC8396]. Another, similar example would a mechanism that permits [RFC8396].
CSPs to delegate authority for particular telephone numbers to
customers, as described in [I-D.ietf-acme-telephone].
2. Terminology 2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
3. Challenges for an Authority Token 3. ACME Authority Token Challenge
Proving that a device on the Internet has effective control over a Proving that a device on the Internet has effective control over a
non-Internet resource is not as straightforward as proving control non-Internet resource is not as straightforward as proving control
over an Internet resources like a DNS zone or a web page. Provided 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 that the issuer of identifiers in a namespace, or someone acting on
the issuer's behalf, can implement a service that grants Authority the issuer's behalf, can implement a service that grants Authority
Tokens to the people to whom it has issued identifiers, a generic Tokens to the people to whom it has issued identifiers, a generic
token could be used as a response to an ACME challenge. This token could be used as a response to an ACME challenge. This
specification, therefore, defines an Authority Token issued by an specification, therefore, defines an Authority Token issued by an
authority over a namespace to an ACME client for delivery to a CA in authority over a namespace to an ACME client for delivery to a CA in
skipping to change at page 3, line 46 skipping to change at page 4, line 5
This architecture assumes a trust relationship between CAs and Token This architecture assumes a trust relationship between CAs and Token
Authorities: that CAs are willing to accept the attestation of Token Authorities: that CAs are willing to accept the attestation of Token
Authorities for particular types of identifiers as sufficient proof Authorities for particular types of identifiers as sufficient proof
to issue a credential. It furthermore assumes that ACME clients have to issue a credential. It furthermore assumes that ACME clients have
a relationship with Token Authorities which permits them to a relationship with Token Authorities which permits them to
authenticate and authorize the issuance of Authority Tokens to the authenticate and authorize the issuance of Authority Tokens to the
proper entities. This ACME challenge has no applicability to proper entities. This ACME challenge has no applicability to
identifiers or authorities where those pre-associations cannot be identifiers or authorities where those pre-associations cannot be
assumed. assumed.
ACME challenges that support Authority Tokens therefore need to The ACME Authority Token Challenge type, "tkauth-01", supports
specify the type of token they require; CAs can even provide a hint different token subtypes. The token subtype is determined by a new
in their challenges to ACME clients that tells them how to find a ACME challenge field, tkauth-type. An IANA registry is used to
Token Authority who can issue tokens for a given namespace. This manage the values of tkauth-type, see Section 7. Additionally, this
challenge type thus requires a new "tkauth-type" element, and may challenge also has a new "token-authority" field to designate a
optionally supply a "token-authority" designating a location where location where a token can be acquired.
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 3.1. Token Type Requirements
The IANA will maintain a registry of tkauth-types under a policy of The IANA will maintain a registry of tkauth-types under a policy of
Specification Required. In order to register a new tkauth-type, Specification Required. In order to register a new tkauth-type,
specifications must address the following requirements. specifications must address the following requirements; in cases
where a tkauth-type admits of its own subtypes, subtypes inherit
these requirements.
While Authority Token types do not need to be specific to a While Authority Token types do not need to be specific to a
namespace, every token must carry enough information for a CA to namespace, every token must carry enough information for a CA to
determine the name that it will issue a certificate for. Some types determine the name that it will issue a certificate for. Some types
of Authority Token types might be reusable for a number of different of Authority Token types might be reusable for a number of different
namespaces; other might be specific to a particular type of name. namespaces; other might be specific to a particular type of name.
Therefore, in defining tkauth-types, future specifications must Therefore, in defining tkauth-types, future specifications must
indicate how a token conveys to the CA the name(s) that the Token indicate how a token conveys to the CA the name(s) that the Token
Authority is attesting that the ACME client controls. Authority is attesting that the ACME client controls.
While nothing precludes use cases where an ACME client is itself a While nothing precludes use cases where an ACME client is itself a
Token Authority, an ACME client will typically need a protocol to Token Authority, an ACME client will typically need a protocol to
request and retrieve an Authority Token. The Token Authority will request and retrieve an Authority Token. The Token Authority will
require certain information from an ACME client in order to ascertain require certain information from an ACME client in order to ascertain
that it is the right entity to request a certificate for a particular that it is the right entity to request a certificate for a particular
name. The protocols used to request an Authority Token MUST convey name. The protocols used to request an Authority Token MUST convey
to the Token Authority the identifier type and value from the ACME to the Token Authority the identifier type and value from or what
challenge, as well as the binding (see Section 3.3), and those MUST will be used in the ACME challenge, as well as the binding (see
be reflected in the Authority Token. A baseline mechanism for how Section 3.3), and those MUST be reflected in the Authority Token. A
the Token Authority authenticates and authorizes ACME clients to baseline mechanism for how the Token Authority authenticates and
receive Authority Tokens is given in Section 5. authorizes ACME clients to receive Authority Tokens is given in
Section 5.
Because the assignment of resources can change over time, Because the assignment of resources can change over time,
demonstrations of authority must be regularly refreshed. Definitions demonstrations of authority must be regularly refreshed. Definitions
of a tkauth-type MUST specify how they manage the freshness of of a tkauth-type MUST specify how they manage the freshness of
authority assignments. Typically, a CA will expect a regular authority assignments. Typically, a CA will expect a regular
refreshing of the token. refreshing of the token.
3.2. Authority Token Scope 3.2. Authority Token Scope
An Authority Token is used to answer a challenge from an ACME server, 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 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 the Authority Token is requested from the Token Authority after a
been received, or it could be that the AT was acquired prior to the challenge has been received, or it could be that the Authority Token
initial ACME client request. A Token Authority could grant to a was acquired prior to the initial ACME client request. A Token
client a Token that has the exact same scope as the requested Authority could grant to a client an Authority Token that has the
certificate; alternatively, an Authority Token could attest to all of exact same scope as the requested certificate; alternatively, an
the resources that the client is eligible to receive certificates Authority Token could attest to all of the resources that the client
for, which could be a superset of the scope of the requested is eligible to receive certificates for, which could be a superset of
certificate. the scope of the requested certificate.
For example, imagine a case where an Authority for DNS names knows For example, imagine a case where an Authority for DNS names knows
that a client is eligible to receive certificates for "example.com" that a client is eligible to receive certificates for "example.com"
and "example.net". The client asks an ACME server for a certificate and "example.net". The client asks an ACME server for a certificate
for "example.com", the server directs the client to acquire an for "example.com", the server directs the client to acquire an
Authority Token from the Authority. When the client sends an Authority Token from the Token Authority. When the client sends an
acquisition request (see Section 5) to the Authority, the Authority acquisition request (see Section 5) to the Token Authority, the Token
could issue a token scoped just to "example.com", or a token that Authority could issue a token scoped just to "example.com", or a
attests the client is eligible to receive certificates for both token that attests the client is eligible to receive certificates for
"example.com" or "example.net". The advantage of the latter is that both "example.com" or "example.net". The advantage of the latter is
if, at a later time (but one within the expiry of the JWT), the 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 client wanted to acquire a certificate for "example.net", it would
not have to return to the Authority, as the Token effectively pre- not have to return to the Token Authority, as the Token effectively
authorized the issuance of that certificate. pre-authorized the issuance of that certificate.
Applications of the Authority Token to different identifier types Applications of the Authority Token to different identifier types
might require different scopes, so registrations of tkauth-types might require different scopes, so registrations of tkauth-types
should be clear if and how a scope greater than that of the requested should be clear if and how a scope greater than that of the requested
certificate would be conveyed in a token. certificate would be conveyed in a token.
3.3. Binding Challenges 3.3. Binding Challenges
Applications that use the Authority Token need a way to correlate Applications that use the Authority Token need a way to correlate
tokens issued by an Authority with the proper ACME client, to prevent tokens issued by a Token Authority with the proper ACME client, to
replay or cut-and-paste attacks using a token issued for a different prevent replay or cut-and-paste attacks using a token issued for a
purpose. To mitigate this, Authority Tokens contain a binding signed different purpose. To mitigate this, Authority Tokens contain a
by an Authority; an ACME server can use the binding to determine that binding signed by a Token Authority; an ACME server can use the
a Token presented by a client was in fact granted by the Authority binding to determine that a Token presented by a client was in fact
based on a request from the client, and not from some other entity. granted by the Token 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 Creating a binding from an Authority Token to a particular ACME
the Token could be reused up until its expiry for multiple challenges account entails that the Token could be reused up until its expiry
issued by an ACME server. This might be a desirable property when for multiple challenges issued by an ACME server. This might be a
using short-lived certificates, for example, or in any cases where desirable property when using short-lived certificates, for example,
the ACME server issues challenges more frequently that an Authority or in any cases where the ACME server issues challenges more
Token can or should issue tokens, or in cases where the Authority frequently that an Authority Token can or should issue tokens, or in
Token scope (see Section 3.2) is broad, so certificates with a more cases where the Authority Token scope (see Section 3.2) is broad, so
narrow scope may periodically be issued. certificates with a more narrow scope may periodically be issued.
For some identifier types, it may be more appropriate to bind the For some identifier types, it may be more appropriate to bind the
Authority Token to a nonce specific to the challenge rather than to Authority Token to a nonce specific to the challenge rather than to
an ACME account fingerprint. Any specification of the use of the an ACME account fingerprint. Any specification of the use of the
nonce for this purpose is left to the identifier type profile for the nonce for this purpose is left to the identifier type profile for the
Authority Token. Authority Token.
4. ATC tkauth-type Registration 4. Authority Token Challenge tkauth-type Registration
This draft registers a tkauth-type of "atc", for the Authority Token This draft specifies a tkauth-type of "atc" which contains a standard
Challenge. Here the "atc" tkauth-type signifies a standard JWT token JWT token [RFC7519] using a JWS-defined signature string [RFC7515].
[RFC7519] using a JWS-defined signature string [RFC7515]. This may The "atc" tkauth-type MAY be used for any number of different ACME
be used for any number of different identifier types given in ACME identifier types in the ACME challenge.
challenges. The "atc" element (defined below) lists the identifier
type used by tokens based on ATC. The use of "atc" is restricted to A new JWT claim, "atc", is defined below and lists the identifier
JWTs, if non-JWT tokens were desired for ACME challenges, a different type used in this Authority Token. The "atc" tkauth-type is
tkauth-type should be defined for them. restricted to the JWTs; if a non-JWT token format is desired for the
ACME Authority Token Challenge, a different tkauth-type should be
specified and registered in the "ACME Authority Token Challenge
Types" registry defined in Section 8.
For this ACME Authority Token usage of JWT, the payload of the JWT For this ACME Authority Token usage of JWT, the payload of the JWT
OPTIONALLY contain an "iss" indicating the Token Authority that OPTIONALLY contain an "iss" indicating the Token Authority that
generated the token, if the "x5u" element in the header does not generated the token, if the "x5u" element in the header does not
already convey that information; typically, this will be the same already convey that information; typically, this will be the same
location that appeared in the "token-authority" field of the ACME location that appeared in the "token-authority" field of the ACME
challenge. In order to satisfy the requirement for replay prevention challenge. In order to satisfy the requirement for replay prevention
the JWT MUST contain a "jti" element, and an "exp" claim. In the JWT MUST contain a "jti" element, and an "exp" claim; the "exp"
addition to helping to manage replay, the "jti" provides a convenient claim manages token freshness. In addition to helping to manage
way to reliably track with the same "atc" Authority Token is being replay, the "jti" provides a convenient way to reliably track with
used for multiple challenges over time within its set expiry. 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 The JWT payload MUST also contain a new JWT claim, "atc", for
Authority Token Challenge, which contains three mandatory elements in Authority Token Challenge, which contains three mandatory elements in
an array: the identifier type ("tktype"), the identifier value an array: the ATC identifier type ("tktype"), the identifier value
("tkvalue"), and the binding ("fingerprint"). The identifier type ("tkvalue"), and the binding ("fingerprint"). The "tkvalue"
and value are those given in the ACME challenge and conveyed to the indicates the scope of the authority that the token, and its
Token Authority by the ACME client. Following the example of semantics are outside the scope of this document. The identifier
[I-D.ietf-acme-authority-token-tnauthlist], the "tkvalue" identifier type and value are those given in the ACME challenge and conveyed to
type could be the TNAuthList, with a "tkvalue" as defined in the Token Authority by the ACME client.
[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: 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", {
"protected": base64url({
"typ":"JWT",
"alg":"ES256", "alg":"ES256",
"x5u":"https://authority.example.org/cert"} "x5u":"https://authority.example.org/cert"
{ }),
"iss":"https://authority.example.org/authz", "payload": base64url({
"exp":1300819380, "iss":"https://authority.example.org/authz",
"jti":"id6098364921", "exp":1300819380,
"atc":{"tktype":"TnAuthList","tkvalue":"F83n2a...avn27DN3==","fingerprint": "jti":"id6098364921",
"SHA256 56:3E:CF:AE:83:CA:4D:15:B0:29:FF:1B:71:D3:BA:B9:19:81:F8:50: "atc":{"tktype":"TnAuthList","tkvalue":"F83n2a...avn27DN3==","fingerprint":
9B:DF:4A:D4:39:72:E2:B1:F0:B9:38:E3"} } "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"
}
Optionally, the "atc" element may contain a fourth element, "ca". If Optionally, the "atc" claim may contain a fourth element, "ca". If
set to "true", the "ca" element indicates that the Token Authority is set to "true", the "ca" element indicates that the Token Authority is
granting permission to issue a certification authority certificate granting permission to issue a certification authority certificate
rather than an end-entity certificate for the names in question. rather than an end-entity certificate for the names in question.
This permits subordinate delegations from the issued certificate. If This permits subordinate delegations from the issued certificate. If
the "ca" element is absent, the Token Authority is explicitly the "ca" element is absent, the Token Authority is explicitly
withholding permission. The "atc" object in the example above would withholding permission. The "atc" object in the example above would
then look like: then look like:
"atc":{"tktype":"TnAuthList","tkvalue":"F83n2a...avn27DN3==","ca":true, "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: "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"} } 9B:DF:4A:D4:39:72:E2:B1:F0:B9:38:E3"} }
Specifications of "tktype" identifier type may define additional Specifications of "tktype" identifier type may define additional
optional "atc" elements. optional "atc" elements.
5. Acquiring a Token 5. Acquiring a Token
The acquisition of a Authority Token requires a network interface, The acquisition of an Authority Token requires a network interface,
apart from potential use cases where the entity that acts as an ACME 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 client itself also acts as a Token Authority trusted by the ACME
server. Implementations compliant with this specification MUST server. Implementations compliant with this specification MUST
support an HTTPS REST interface for Authority Token acquisition as support an HTTPS REST interface for Authority Token acquisition as
described below, though other interfaces MAY be supported as well. described below, though other interfaces MAY be supported as well.
5.1. Basic REST Interface 5.1. Basic REST Interface
In order to request an Authority Token from a Token Authority, a In order to request an Authority Token from a Token Authority, a
client sends an HTTPS POST request. Different services may organize client sends an HTTPS POST request. This specification assumes that
Token Authority URIs are known to clients through preexisting
business relationships, and that credentials and related
authentication and authorization for Authority Token acquisition
encompassed in that relationship. Different services may organize
their web resources in domain-specific ways, but the resource locator their web resources in domain-specific ways, but the resource locator
should specify the account of the client, an identifier for the should specify the account of the client, an identifier for the
service provider, and finally a locator for the token. service provider, and finally a locator for the token.
POST /at/account/:id/token HTTP/1.1 POST /at/account/:id/token HTTP/1.1
Host: authority.example.com Host: authority.example.com
Content-Type: application/json Content-Type: application/json
The body of the POST request will contain the ATC element that the The body of the POST request MUST contain the Authority Token
client is requesting the Token Authority generate. Challenge element that the client is requesting the Token Authority
generate. In the way, the client proposes the scope of the Authority
{ Token it would like to receive from the Token Authority.
"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"} }
}
In common use cases, the "tkvalue" in this request is asking that the In common use cases, the "tkvalue" in this request is asking that the
Token Authority issue a token that attests the entire scope of Token Authority issue a token that attests the entire scope of
authority to which the client is entitled. The client may also authority to which the client is entitled. The client may also
request an AT with some subset of its own authority via the "tkvalue" request an Authority Token with some subset of its own authority via
element in the ATC object. The way that "tkvalue" is defined will the "tkvalue" element in the Authority Token Challenge object. The
necessarily be specific to the identifier type. For the TNAuthlist way that "tkvalue" is defined will necessarily be specific to the
identifier type, for example, an object requesting an AT could identifier type. For the TNAuthlist identifier type, for example, an
request authority for only a single telephone number in a way that is object requesting an Authority Token could request authority for only
defined in the TNAuthList specification. 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 Finally, the JSON object MAY also contain an optional boolean element
"ca" which signifies that the client is requesting that the Token "ca" which signifies that the client is requesting that the Token
Authority issue an AT with the "ca" flag set, as described in Authority issue an Authority Token with the "ca" flag set, as
Section 4. described in Section 4.
After an HTTPS-level challenge to verify the identity of the client After an HTTPS-level challenge (e.g. a 401 HTTP response code) to
and subsequently making an authorization decision, in the success verify the identity of the client and subsequently making an
case the Token Authority returns a 200 OK with a body of type authorization decision about whether the client should receive 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. "application/json" containing the Authority Token.
6. Using an Authority Token in a Challenge A full example of "atc" token acquisition using the HTTP interface,
with the "tktype" of "TNAuthList", is given in
Taking the identifier example of TNAuthList from [I-D.ietf-acme-authority-token-tnauthlist] Section 5.5.
[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, 6. Acknowledgements
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 We would like to Roman Danyliw for contributions to this problem
back to the URL given by the ACME challenge. statement and framework.
POST /acme/authz/asdf/0 HTTP/1.1 7. IANA Considerations
Host: boulder.example.com
Content-Type: application/jose+json
{ This document requests that IANA populate a new ACME Validation
"protected": base64url({ Method (again per [RFC8555]) for the label "tkauth-01", identifier
"alg": "ES256", type "atc", an ACME value of "Y", and a reference pointing to
"kid": "https://boulder.example.com/acme/reg/asdf", [RFCThis].
"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. Furthermore, this document asks IANA to populate a new claim in the
"JSON Web Token Claims" registry as defined in [RFC7519] as follows:
7. Acknowledgements Claim name: atc
We would like to thank you for your contributions to this problem Claim Description: Authority Token Challenge
statement and framework.
8. IANA Considerations Change Controller: IESG
This document requests that the IANA registers a new ACME identifier Specification document(s): [RFCThis]
type (per [RFC8555]) for the label "atc", for which the reference is
[RFCThis].
This document further requests that the IANA create a registry for This document further requests that the IANA create a new registry
"token types" as used in these challenges, following the requirements for "ACME Authority Token Challenge Types" as used in these
in Section 3.1, pre-populated with the label of "atc" per Section 4 challenges, under a policy of Specification Required and following
with a value of [RFCThis]. the requirements in Section 3.1, with two columns, Label and
Reference. The registry should be pre-populated with a Label of
"atc" per Section 4 with a Reference value of [RFCThis].
9. Security Considerations 8. Security Considerations
Per the guidance in [RFC8555], ACME transactions MUST use TLS, and Per the guidance in [RFC8555], ACME transactions MUST use TLS, and
similarly the HTTPS REST transactions used to request and acquire similarly the HTTPS REST transactions used to request and acquire
authority tokens MUST use TLS. These measures are intended to Authority Tokens MUST use TLS. These measures are intended to
prevent the capture of Authority Tokens by eavesdroppers. The prevent the capture of Authority Tokens by eavesdroppers. The
security considerations of [RFC8555] apply to the use of the security considerations of [RFC8555] apply to the use of the
mechanism in this specification. mechanism in this specification.
As described in Section 3.2, an Authority Token can either have a
scope that attests all of the resources which a client is eligible to
receive certificates for, or potentially a more limited scope that is
intended to capture only those resources for which a client will
receive a certificate from a particular certification authority. Any
certification authority that sees an Authority Token can learn
information about the resources a client can claim. In cases where
this incurs a privacy risk, Authority Token scopes should be limited
to only the resources that will be attested by the requested ACME
certificate.
In cases where a tkauth-type as defined in Section 4 admits of its
own subtypes, the security of features like binding challenges (see
Section 3.3) will depend on the subtype specification.
The capture of Authority Tokens by an adversary could enable an The capture of Authority Tokens by an adversary could enable an
attacker to acquire a certificate from a CA. Therefore, all attacker to acquire a certificate from a CA. Therefore, all
Authority Tokens MUST contain a field that identifies to the CA which Authority Tokens MUST contain a field that identifies to the CA which
ACME client requested the token from the authority; here that is the ACME client requested the token from the Token Authority; here that
fingerprint specified in Section 4). All Authority Tokens must is the fingerprint specified in Section 4). All Authority Tokens
specify an expiry (of the token itself as proof for a CA, as opposed must specify an expiry (of the token itself as proof for a CA, as
to the expiry of the name), and for some application, it may make opposed to the expiry of the name), and for some application, it may
sense of that expiry to be quite short. Any protocol used to make sense of that expiry to be quite short. Any protocol used to
retrieve Authority Tokens from an authority MUST use confidentiality retrieve Authority Tokens from a Token Authority MUST use
to prevent eavesdroppers from acquiring an Authority Token. confidentiality to prevent eavesdroppers from acquiring an Authority
Token.
10. Normative References 9. References
9.1. Normative References
[I-D.ietf-acme-authority-token-tnauthlist] [I-D.ietf-acme-authority-token-tnauthlist]
Wendt, C., Hancock, D., Barnes, M., and J. Peterson, Wendt, C., Hancock, D., Barnes, M., and J. Peterson,
"TNAuthList profile of ACME Authority Token", draft-ietf- "TNAuthList profile of ACME Authority Token", draft-ietf-
acme-authority-token-tnauthlist-05 (work in progress), acme-authority-token-tnauthlist-08 (work in progress),
November 2019. March 2021.
[I-D.ietf-acme-service-provider]
Barnes, M. and C. Wendt, "ACME Identifiers and Challenges
for VoIP Service Providers", draft-ietf-acme-service-
provider-02 (work in progress), October 2017.
[I-D.ietf-acme-star]
Sheffer, Y., Lopez, D., Dios, O., Pastor, A., and T.
Fossati, "Support for Short-Term, Automatically-Renewed
(STAR) Certificates in Automated Certificate Management
Environment (ACME)", draft-ietf-acme-star-11 (work in
progress), October 2019.
[I-D.ietf-acme-telephone]
Peterson, J. and R. Barnes, "ACME Identifiers and
Challenges for Telephone Numbers", draft-ietf-acme-
telephone-01 (work in progress), October 2017.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC7340] Peterson, J., Schulzrinne, H., and H. Tschofenig, "Secure
Telephone Identity Problem Statement and Requirements",
RFC 7340, DOI 10.17487/RFC7340, September 2014,
<https://www.rfc-editor.org/info/rfc7340>.
[RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
2015, <https://www.rfc-editor.org/info/rfc7515>. 2015, <https://www.rfc-editor.org/info/rfc7515>.
[RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
<https://www.rfc-editor.org/info/rfc7519>. <https://www.rfc-editor.org/info/rfc7519>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8224] Peterson, J., Jennings, C., Rescorla, E., and C. Wendt,
"Authenticated Identity Management in the Session
Initiation Protocol (SIP)", RFC 8224,
DOI 10.17487/RFC8224, February 2018,
<https://www.rfc-editor.org/info/rfc8224>.
[RFC8225] Wendt, C. and J. Peterson, "PASSporT: Personal Assertion
Token", RFC 8225, DOI 10.17487/RFC8225, February 2018,
<https://www.rfc-editor.org/info/rfc8225>.
[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, [RFC8396] Peterson, J. and T. McGarry, "Managing, Ordering,
Distributing, Exposing, and Registering Telephone Numbers Distributing, Exposing, and Registering Telephone Numbers
(MODERN): Problem Statement, Use Cases, and Framework", (MODERN): Problem Statement, Use Cases, and Framework",
RFC 8396, DOI 10.17487/RFC8396, July 2018, RFC 8396, DOI 10.17487/RFC8396, July 2018,
<https://www.rfc-editor.org/info/rfc8396>. <https://www.rfc-editor.org/info/rfc8396>.
[RFC8555] Barnes, R., Hoffman-Andrews, J., McCarney, D., and J. [RFC8555] Barnes, R., Hoffman-Andrews, J., McCarney, D., and J.
Kasten, "Automatic Certificate Management Environment Kasten, "Automatic Certificate Management Environment
(ACME)", RFC 8555, DOI 10.17487/RFC8555, March 2019, (ACME)", RFC 8555, DOI 10.17487/RFC8555, March 2019,
<https://www.rfc-editor.org/info/rfc8555>. <https://www.rfc-editor.org/info/rfc8555>.
9.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>.
Authors' Addresses Authors' Addresses
Jon Peterson Jon Peterson
Neustar, Inc. Neustar, Inc.
1800 Sutter St Suite 570 1800 Sutter St Suite 570
Concord, CA 94520 Concord, CA 94520
US US
Email: jon.peterson@team.neustar Email: jon.peterson@team.neustar
 End of changes. 56 change blocks. 
235 lines changed or deleted 207 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/