draft-ietf-acme-acme-00.txt   draft-ietf-acme-acme-01.txt 
Network Working Group R. Barnes Network Working Group R. Barnes
Internet-Draft Mozilla Internet-Draft Mozilla
Intended status: Standards Track J. Hoffman-Andrews Intended status: Standards Track J. Hoffman-Andrews
Expires: March 31, 2016 EFF Expires: April 6, 2016 EFF
J. Kasten J. Kasten
University of Michigan University of Michigan
September 28, 2015 October 04, 2015
Automatic Certificate Management Environment (ACME) Automatic Certificate Management Environment (ACME)
draft-ietf-acme-acme-00 draft-ietf-acme-acme-01
Abstract Abstract
Certificates in the Web's X.509 PKI (PKIX) are used for a number of Certificates in the Web's X.509 PKI (PKIX) are used for a number of
purposes, the most significant of which is the authentication of purposes, the most significant of which is the authentication of
domain names. Thus, certificate authorities in the Web PKI are domain names. Thus, certificate authorities in the Web PKI are
trusted to verify that an applicant for a certificate legitimately trusted to verify that an applicant for a certificate legitimately
represents the domain name(s) in the certificate. Today, this represents the domain name(s) in the certificate. Today, this
verification is done through a collection of ad hoc mechanisms. This verification is done through a collection of ad hoc mechanisms. This
document describes a protocol that a certificate authority (CA) and document describes a protocol that a certificate authority (CA) and
skipping to change at page 2, line 4 skipping to change at page 2, line 4
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 http://datatracker.ietf.org/drafts/current/. Drafts is at http://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 March 31, 2016. This Internet-Draft will expire on April 6, 2016.
Copyright Notice Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the Copyright (c) 2015 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
(http://trustee.ietf.org/license-info) in effect on the date of (http://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
skipping to change at page 2, line 48 skipping to change at page 2, line 48
6.2. Directory . . . . . . . . . . . . . . . . . . . . . . . . 18 6.2. Directory . . . . . . . . . . . . . . . . . . . . . . . . 18
6.3. Registration . . . . . . . . . . . . . . . . . . . . . . 18 6.3. Registration . . . . . . . . . . . . . . . . . . . . . . 18
6.3.1. Recovery Keys . . . . . . . . . . . . . . . . . . . . 20 6.3.1. Recovery Keys . . . . . . . . . . . . . . . . . . . . 20
6.4. Account Recovery . . . . . . . . . . . . . . . . . . . . 22 6.4. Account Recovery . . . . . . . . . . . . . . . . . . . . 22
6.4.1. MAC-Based Recovery . . . . . . . . . . . . . . . . . 23 6.4.1. MAC-Based Recovery . . . . . . . . . . . . . . . . . 23
6.4.2. Contact-Based Recovery . . . . . . . . . . . . . . . 25 6.4.2. Contact-Based Recovery . . . . . . . . . . . . . . . 25
6.5. Identifier Authorization . . . . . . . . . . . . . . . . 27 6.5. Identifier Authorization . . . . . . . . . . . . . . . . 27
6.6. Certificate Issuance . . . . . . . . . . . . . . . . . . 31 6.6. Certificate Issuance . . . . . . . . . . . . . . . . . . 31
6.7. Certificate Revocation . . . . . . . . . . . . . . . . . 34 6.7. Certificate Revocation . . . . . . . . . . . . . . . . . 34
7. Identifier Validation Challenges . . . . . . . . . . . . . . 35 7. Identifier Validation Challenges . . . . . . . . . . . . . . 35
7.1. Simple HTTP . . . . . . . . . . . . . . . . . . . . . . . 37 7.1. Key Authorizations . . . . . . . . . . . . . . . . . . . 37
7.2. Domain Validation with Server Name Indication (DVSNI) . . 39 7.2. HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . 38
7.3. Proof of Possession of a Prior Key . . . . . . . . . . . 41 7.3. TLS with Server Name Indication (TLS SNI) . . . . . . . . 40
7.4. DNS . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 7.4. Proof of Possession of a Prior Key . . . . . . . . . . . 42
7.5. DNS . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 46 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 46
9. Security Considerations . . . . . . . . . . . . . . . . . . . 46 9. Security Considerations . . . . . . . . . . . . . . . . . . . 46
9.1. Threat model . . . . . . . . . . . . . . . . . . . . . . 47 9.1. Threat model . . . . . . . . . . . . . . . . . . . . . . 46
9.2. Integrity of Authorizations . . . . . . . . . . . . . . . 48 9.2. Integrity of Authorizations . . . . . . . . . . . . . . . 47
9.3. Preventing Authorization Hijacking . . . . . . . . . . . 51 9.3. Preventing Authorization Hijacking . . . . . . . . . . . 50
9.4. Denial-of-Service Considerations . . . . . . . . . . . . 52 9.4. Denial-of-Service Considerations . . . . . . . . . . . . 52
9.5. CA Policy Considerations . . . . . . . . . . . . . . . . 52 9.5. CA Policy Considerations . . . . . . . . . . . . . . . . 52
10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 53 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 53
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 54 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 53
11.1. Normative References . . . . . . . . . . . . . . . . . . 54 11.1. Normative References . . . . . . . . . . . . . . . . . . 53
11.2. Informative References . . . . . . . . . . . . . . . . . 56 11.2. Informative References . . . . . . . . . . . . . . . . . 55
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 56 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 56
1. Introduction 1. Introduction
Certificates in the Web PKI are most commonly used to authenticate Certificates in the Web PKI are most commonly used to authenticate
domain names. Thus, certificate authorities in the Web PKI are domain names. Thus, certificate authorities in the Web PKI are
trusted to verify that an applicant for a certificate legitimately trusted to verify that an applicant for a certificate legitimately
represents the domain name(s) in the certificate. represents the domain name(s) in the certificate.
Existing Web PKI certificate authorities tend to run on a set of ad Existing Web PKI certificate authorities tend to run on a set of ad
skipping to change at page 12, line 41 skipping to change at page 12, line 41
"status": "valid", "status": "valid",
"expires": "2015-03-01", "expires": "2015-03-01",
"identifier": { "identifier": {
"type": "dns", "type": "dns",
"value": "example.org" "value": "example.org"
}, },
"challenges": [ "challenges": [
{ {
"type": "simpleHttp", "type": "http-01",
"status": "valid", "status": "valid",
"validated": "2014-12-01T12:05Z", "validated": "2014-12-01T12:05Z",
"token": "IlirfxKKXAsHtmzK29Pj8A" "keyAuthorization": "SXQe-2XODaDxNR...vb29HhjjLPSggwiE"
} }
], ],
} }
5.4. Errors 5.4. Errors
Errors can be reported in ACME both at the HTTP layer and within ACME Errors can be reported in ACME both at the HTTP layer and within ACME
payloads. ACME servers can return responses with an HTTP error payloads. ACME servers can return responses with an HTTP error
response code (4XX or 5XX). For example: If the client submits a response code (4XX or 5XX). For example: If the client submits a
request using a method not allowed in this document, then the server request using a method not allowed in this document, then the server
skipping to change at page 29, line 20 skipping to change at page 29, line 20
{ {
"status": "pending", "status": "pending",
"identifier": { "identifier": {
"type": "dns", "type": "dns",
"value": "example.org" "value": "example.org"
}, },
"challenges": [ "challenges": [
{ {
"type": "simpleHttp", "type": "http-01",
"uri": "https://example.com/authz/asdf/0", "uri": "https://example.com/authz/asdf/0",
"token": "IlirfxKKXAsHtmzK29Pj8A" "token": "IlirfxKKXAsHtmzK29Pj8A"
}, },
{ {
"type": "dns", "type": "dns-01",
"uri": "https://example.com/authz/asdf/1" "uri": "https://example.com/authz/asdf/1",
"token": "DGyRejmCefe7v4NfDGDKfA" "token": "DGyRejmCefe7v4NfDGDKfA"
} }
}, },
"combinations": [ "combinations": [
[0, 2], [0, 2],
[1, 2] [1, 2]
] ]
} }
skipping to change at page 29, line 50 skipping to change at page 29, line 50
the elements of the "challenges" dictionary. (This is also the stage the elements of the "challenges" dictionary. (This is also the stage
where the client should perform any actions required by the where the client should perform any actions required by the
challenge.) challenge.)
The client sends these updates back to the server in the form of a The client sends these updates back to the server in the form of a
JSON object with the response fields required by the challenge type, JSON object with the response fields required by the challenge type,
carried in a POST request to the challenge URI (not authorization URI carried in a POST request to the challenge URI (not authorization URI
or the new-authorization URI). This allows the client to send or the new-authorization URI). This allows the client to send
information only for challenges it is responding to. information only for challenges it is responding to.
For example, if the client were to respond to the "simpleHttp" For example, if the client were to respond to the "http-01" challenge
challenge in the above authorization, it would send the following in the above authorization, it would send the following request:
request:
POST /acme/authz/asdf/0 HTTP/1.1 POST /acme/authz/asdf/0 HTTP/1.1
Host: example.com Host: example.com
{ {
"resource": "challenge", "resource": "challenge",
"type": "simpleHttp", "type": "http-01",
"tls": false "token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA"
} }
/* Signed as JWS */ /* Signed as JWS */
The server updates the authorization document by updating its The server updates the authorization document by updating its
representation of the challenge with the response fields provided by representation of the challenge with the response fields provided by
the client. The server MUST ignore any fields in the response object the client. The server MUST ignore any fields in the response object
that are not specified as response fields for this type of challenge. that are not specified as response fields for this type of challenge.
The server provides a 200 (OK) response with the updated challenge The server provides a 200 (OK) response with the updated challenge
object as its body. object as its body.
If the client's response is invalid for some reason, or does not
provide the server with appropriate information to validate the
challenge, then the server MUST return an HTTP error. On receiving
such an error, the client MUST undo any actions that have been taken
to fulfil the challenge, e.g., removing files that have been
provisioned to a web server.
Presumably, the client's responses provide the server with enough Presumably, the client's responses provide the server with enough
information to validate one or more challenges. The server is said information to validate one or more challenges. The server is said
to "finalize" the authorization when it has completed all the to "finalize" the authorization when it has completed all the
validations it is going to complete, and assigns the authorization a validations it is going to complete, and assigns the authorization a
status of "valid" or "invalid", corresponding to whether it considers status of "valid" or "invalid", corresponding to whether it considers
the account authorized for the identifier. If the final state is the account authorized for the identifier. If the final state is
"valid", the server MUST add an "expires" field to the authorization. "valid", the server MUST add an "expires" field to the authorization.
When finalizing an authorization, the server MAY remove the When finalizing an authorization, the server MAY remove the
"combinations" field (if present) or remove any challenges still "combinations" field (if present) or remove any challenges still
pending. The server SHOULD NOT remove challenges with status pending. The server SHOULD NOT remove challenges with status
skipping to change at page 31, line 21 skipping to change at page 31, line 21
"status": "valid", "status": "valid",
"expires": "2015-03-01", "expires": "2015-03-01",
"identifier": { "identifier": {
"type": "dns", "type": "dns",
"value": "example.org" "value": "example.org"
}, },
"challenges": [ "challenges": [
{ {
"type": "simpleHttp" "type": "http-01"
"status": "valid", "status": "valid",
"validated": "2014-12-01T12:05Z", "validated": "2014-12-01T12:05Z",
"token": "IlirfxKKXAsHtmzK29Pj8A" "keyAuthorization": "SXQe-2XODaDxNR...vb29HhjjLPSggwiE"
} }
] ]
} }
6.6. Certificate Issuance 6.6. Certificate Issuance
The holder of an authorized key pair for an identifier may use ACME The holder of an authorized key pair for an identifier may use ACME
to request that a certificate be issued for that identifier. The to request that a certificate be issued for that identifier. The
client makes this request by sending a POST request to the server's client makes this request by sending a POST request to the server's
new-certificate resource. The body of the POST is a JWS object whose new-certificate resource. The body of the POST is a JWS object whose
skipping to change at page 36, line 41 skipping to change at page 36, line 41
structured as a problem document [I-D.ietf-appsawg-http-problem]. structured as a problem document [I-D.ietf-appsawg-http-problem].
All additional fields are specified by the Challenge type. The All additional fields are specified by the Challenge type. The
server MUST ignore any values provided in the "uri", "status", server MUST ignore any values provided in the "uri", "status",
"validated", and "error" fields of a Response payload. If the server "validated", and "error" fields of a Response payload. If the server
sets a Challenge's "status" to "invalid", it SHOULD also include the sets a Challenge's "status" to "invalid", it SHOULD also include the
"error" field to help the client diagnose why they failed the "error" field to help the client diagnose why they failed the
challenge. challenge.
Different challenges allow the server to obtain proof of different Different challenges allow the server to obtain proof of different
aspects of control over an identifier. In some challenges, like aspects of control over an identifier. In some challenges, like HTTP
Simple HTTP and DVSNI, the client directly proves its ability to do and TLS SNI, the client directly proves its ability to do certain
certain things related to the identifier. In the Proof of Possession things related to the identifier. In the Proof of Possession
challenge, the client proves historical control of the identifier, by challenge, the client proves historical control of the identifier, by
reference to a prior authorization transaction or certificate. reference to a prior authorization transaction or certificate.
The choice of which Challenges to offer to a client under which The choice of which Challenges to offer to a client under which
circumstances is a matter of server policy. A CA may choose circumstances is a matter of server policy. A CA may choose
different sets of challenges depending on whether it has interacted different sets of challenges depending on whether it has interacted
with a domain before, and how. For example: with a domain before, and how. For example:
o New domain with no known certificates: Domain Validation (DVSNI or o New domain with no known certificates: Domain Validation (HTTP or
Simple HTTP) TLS SNI)
o Domain for which known certs exist from other CAs: DV + Proof of o Domain for which known certs exist from other CAs: DV + Proof of
Possession of previous CA-signed key Possession of previous CA-signed key
o Domain with a cert from this CA, lost account key: DV + PoP of o Domain with a cert from this CA, lost account key: DV + PoP of
ACME-certified Subject key ACME-certified Subject key
o Domain with a cert from this CA, all keys and recovery mechanisms o Domain with a cert from this CA, all keys and recovery mechanisms
lost: Out of band proof of authority for the domain lost: Out of band proof of authority for the domain
The identifier validation challenges described in this section all The identifier validation challenges described in this section all
relate to validation of domain names. If ACME is extended in the relate to validation of domain names. If ACME is extended in the
future to support other types of identifier, there will need to be future to support other types of identifier, there will need to be
new Challenge types, and they will need to specify which types of new Challenge types, and they will need to specify which types of
identifier they apply to. identifier they apply to.
7.1. Simple HTTP [[ Editor's Note: In pre-RFC versions of this specification,
challenges are labeled by type, and with the version of the draft in
which they were introduced. For example, if an HTTP challenge were
introduced in version -03 and a breaking change made in version -05,
then there would be a challenge labeled "http-03" and one labeled
"http-05" - but not one labeled "http-04", since challenge in version
-04 was compatible with one in version -04. ]]
[[ Editor's Note: Operators SHOULD NOT issue "combinations" arrays in
authorization objects that require the client to perform multiple
challenges over the same type, e.g., ["http-03", "http-05"].
Challenges within a type are testing the same capability of the
domain owner, and it may not be possible to satisfy both at once. ]]
7.1. Key Authorizations
Several of the challenges in this document makes use of a key
authorization string. A key authorization expresses a domain
holder's authorization for a specified key to satisfy a specified
challenge, by concatenating the token for the challenge with a key
fingerprint, separated by a "." character:
key-authz = token || '.' || base64(JWK_Thumbprint(accountKey))
The "JWK_Thumbprint" step indicates the computation specified in
[RFC7638], using the SHA-256 digest. As specified in the individual
challenges below, the token for a challenge is a JSON string
comprised entirely of characters in the base64 alphabet. The "||"
operator indicates concatenation of strings.
In computations involving key authorizations, such as the digest
computations required for the DNS and TLS SNI challenges, the key
authorization string MUST be represented in UTF-8 form (or,
equivalently, ASCII).
7.2. HTTP
With Simple HTTP validation, the client in an ACME transaction proves With Simple HTTP validation, the client in an ACME transaction proves
its control over a domain name by proving that it can provision its control over a domain name by proving that it can provision
resources on an HTTP server that responds for that domain name. The resources on an HTTP server that responds for that domain name. The
ACME server challenges the client to provision a file with a specific ACME server challenges the client to provision a file with a specific
JWS as its contents. JWS as its contents.
As a domain may resolve to multiple IPv4 and IPv6 addresses, the As a domain may resolve to multiple IPv4 and IPv6 addresses, the
server will connect to at least one of the hosts found in A and AAAA server will connect to at least one of the hosts found in A and AAAA
records, at its discretion. The HTTP server may be made available records, at its discretion. Because many webservers allocate a
over either HTTPS or unencrypted HTTP; the client tells the server in default HTTPS virtual host to a particular low-privilege tenant user
its response which to check. in a subtle and non-intuitive manner, the challenge must be completed
over HTTP, not HTTPS.
type (required, string): The string "simpleHttp" type (required, string): The string "http-01"
token (required, string): The value to be used in generation of token (required, string): A random value that uniquely identifies
validation JWS. This value MUST have at least 128 bits of the challenge. This value MUST have at least 128 bits of entropy,
entropy, in order to prevent an attacker from guessing it. It in order to prevent an attacker from guessing it. It MUST NOT
MUST NOT contain any characters outside the URL-safe Base64 contain any characters outside the URL-safe Base64 alphabet.
alphabet.
{ {
"type": "simpleHttp", "type": "http-01",
"token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA" "token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA",
} }
A client responds to this challenge by signing a JWS object and A client responds to this challenge by constructing a key
provisioning it as a resource on the HTTP server for the domain in authorization from the "token" value provided in the challenge and
question. The payload of the JWS MUST be a JSON dictionary the client's account key. The client then provisions the key
containing the fields "type", "token", and "tls" from the ACME authorization as a resource on the HTTP server for the domain in
challenge and response (see below), and no other fields. If the question.
"tls" field is not included in the response, then validation object
MUST have its "tls" field set to "true". The JWS MUST be signed with
the client's account key pair. This JWS is NOT REQUIRED to have a
"nonce" header parameter (as with the JWS objects that carry ACME
request objects), but MUST otherwise meet the guidelines laid out in
Section 3.
{ evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA
"type": "simpleHttp", .nP1qzpXGymHBrUEepNY9HCsQk7K8KhOypzEt62jcerQ
"token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA",
"tls": false
}
The path at which the resource is provisioned is comprised of the The path at which the resource is provisioned is comprised of the
fixed prefix ".well-known/acme-challenge/", followed by the "token" fixed prefix ".well-known/acme-challenge/", followed by the "token"
value in the challenge. value in the challenge.
.well-known/acme-challenge/evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA .well-known/acme-challenge/evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA
The client's response to this challenge indicates its agreement to
this challenge by sending the server the key authorization covering
the challenge's token and the client's account key:
The client's response to this challenge indicates whether it would keyAuthorization (required, string): The key authorization for this
prefer for the validation request to be sent over TLS: challenge. This value MUST match the token from the challenge and
the client's account key.
type (required, string): The string "simpleHttp"
tls (optional, boolean, default true): If this attribute is present
and set to "false", the server will perform its validation check
over unencrypted HTTP (on port 80) rather than over HTTPS.
Otherwise the check will be done over HTTPS, on port 443.
{ {
"type": "simpleHttp", "keyAuthorization": "evaGxfADs...62jcerQ"
"tls": false
} }
/* Signed as JWS */ /* Signed as JWS */
On receiving a response, the server MUST verify that the key
authorization in the response matches the "token" value in the
challenge and the client's account key. If they do not match, then
the server MUST return an HTTP error in response to the POST request
in which the client sent the challenge.
Given a Challenge/Response pair, the server verifies the client's Given a Challenge/Response pair, the server verifies the client's
control of the domain by verifying that the resource was provisioned control of the domain by verifying that the resource was provisioned
as expected. as expected.
1. Form a URI by populating the URI template [RFC6570] 1. Form a URI by populating the URI template [RFC6570]
"{scheme}://{domain}/.well-known/acme-challenge/{token}", where: "http://{domain}/.well-known/acme-challenge/{token}", where:
* the scheme field is set to "http" if the "tls" field in the
response is present and set to false, and "https" otherwise;
* the domain field is set to the domain name being verified; and * the domain field is set to the domain name being verified; and
* the token field is the token provided in the challenge.
* the token field is set to the token in the challenge.
2. Verify that the resulting URI is well-formed. 2. Verify that the resulting URI is well-formed.
3. Dereference the URI using an HTTP or HTTPS GET request. If using 3. Dereference the URI using an HTTP or HTTPS GET request. If using
HTTPS, the ACME server MUST ignore the certificate provided by HTTPS, the ACME server MUST ignore the certificate provided by
the HTTPS server. the HTTPS server.
4. Verify that the Content-Type header of the response is either 4. Verify that the Content-Type header of the response is either
absent, or has the value "application/jose+json". absent, or has the value "text/plain".
5. Verify that the body of the response is a valid JWS, signed with
the client's account key.
6. Verify that the payload of the JWS meets the following criteria:
* it is a valid JSON dictionary;
* it has exactly three fields;
* its "type" field is set to "simpleHttp";
* its "token" field is equal to the "token" field in the
challenge;
* its "tls" field is equal to the "tls" field in the response, 5. Verify that the body of the response is well-formed key
or "true" if the "tls" field was absent. authorization.
Comparisons of the "token" field MUST be performed in terms of 6. Verify that key authorization provided by the server matches the
Unicode code points, taking into account the encodings of the stored token for this challenge and the client's account key.
nonce and the body of the request.
If all of the above verifications succeed, then the validation is If all of the above verifications succeed, then the validation is
successful. If the request fails, or the body does not pass these successful. If the request fails, or the body does not pass these
checks, then it has failed. checks, then it has failed.
7.2. Domain Validation with Server Name Indication (DVSNI) 7.3. TLS with Server Name Indication (TLS SNI)
The Domain Validation with Server Name Indication (DVSNI) validation The TLS with Server Name Indication (TLS SNI) validation method
method proves control over a domain name by requiring the client to proves control over a domain name by requiring the client to
configure a TLS server referenced by an A/AAAA record under the configure a TLS server referenced by an A/AAAA record under the
domain name to respond to specific connection attempts utilizing the domain name to respond to specific connection attempts utilizing the
Server Name Indication extension [RFC6066]. The server verifies the Server Name Indication extension [RFC6066]. The server verifies the
client's challenge by accessing the reconfigured server and verifying client's challenge by accessing the reconfigured server and verifying
a particular challenge certificate is presented. a particular challenge certificate is presented.
type (required, string): The string "dvsni" type (required, string): The string "tls-sni-01"
token (required, string): The value to be used in generation of
validation certificate. This value MUST have at least 128 bits of
entropy, in order to prevent an attacker from guessing it. It
MUST NOT contain any characters outside the URL-safe Base64
alphabet.
{
"type": "dvsni",
"token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA"
}
In response to the challenge, the client uses its account private key
to sign a JWS over a JSON object describing the challenge. The
validation object covered by the signature MUST have the following
fields and no others:
type (required, string): The string "dvsni" token (required, string): A random value that uniquely identifies
the challenge. This value MUST have at least 128 bits of entropy,
in order to prevent an attacker from guessing it. It MUST NOT
contain any characters outside the URL-safe Base64 alphabet.
token (required, string): The token value from the server-provided n (required, number): Number of tls-sni-01 iterations
challenge object
{ {
"type": "dvsni", "type": "tls-sni-01",
"token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA" "token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA",
"n": 25
} }
The client serializes the validation object to UTF-8, then uses its A client responds to this challenge by constructing a key
account private key to sign a JWS with the serialized JSON object as authorization from the "token" value provided in the challenge and
its payload. This JWS is NOT REQUIRED to have the "nonce" header the client's account key. The client first computes the SHA-256
parameter. digest Z0 of the UTF8-encoded key authorization, and encodes Z0 in
UTF-8 lower-case hexadecimal form. The client then generates
iterated hash values Z1...Z(n-1) as follows:
The client will compute Z, the SHA-256 of the "signature" value from Z(i) = lowercase_hexadecimal(SHA256(Z(i-1))).
the JWS. The hash is calculated over the base64-encoded signature
string. Z is encoded in hexadecimal form.
The client will generate a self-signed certificate with the The client generates a self-signed certificate for each iteration of
subjectAlternativeName extension containing the dNSName Zi with a single subjectAlternativeName extension dNSName that is
"<Z[0:32]>.<Z[32:64]>.acme.invalid". The client will then configure "<Zi[0:32]>.<Zi[32:64]>.acme.invalid", where "Zi[0:32]" and
the TLS server at the domain such that when a handshake is initiated "Zi[32:64]" represent the first 32 and last 32 characters of the hex-
with the Server Name Indication extension set to encoded value, respectively (following the notation used in Python).
"<Z[0:32]>.<Z[32:64]>.acme.invalid", the generated test certificate The client then configures the TLS server at the domain such that
is presented. when a handshake is initiated with the Server Name Indication
extension set to "<Zi[0:32]>.<Zi[32:64]>.acme.invalid", the
corresponding generated certificate is presented.
The response to the DVSNI challenge provides the validation JWS to The response to the TLS SNI challenge simply acknowledges that the
the server. client is ready to fulfill this challenge.
type (required, string): The string "dvsni" keyAuthorization (required, string): The key authorization for this
validation (required, string): The JWS object computed with the challenge. This value MUST match the token from the challenge and
validation object and the account key the client's account key.
{ {
"type": "dvsni", "keyAuthorization": "evaGxfADs...62jcerQ",
"validation": {
"header": { "alg": "RS256" },
"payload": "qzu9...6bjn",
"signature": "gfj9XqFv07e1wU66hSLYkiFqYakPSjAu8TsyXRg85nM"
}
} }
/* Signed as JWS */
On receiving a response, the server MUST verify that the key
authorization in the response matches the "token" value in the
challenge and the client's account key. If they do not match, then
the server MUST return an HTTP error in response to the POST request
in which the client sent the challenge.
Given a Challenge/Response pair, the ACME server verifies the Given a Challenge/Response pair, the ACME server verifies the
client's control of the domain by verifying that the TLS server was client's control of the domain by verifying that the TLS server was
configured appropriately. configured appropriately.
1. Verify the validation JWS using the account key for which the 1. Choose a subset of the N iterations to check, according to local
challenge was issued. policy.
2. Decode the payload of the JWS as UTF-8 encoded JSON.
3. Verify that there are exactly two fields in the decoded object,
and that:
* The "type" field is set to "dvsni" 2. For each iteration, compute the Zi-value from the key
authorization in the same way as the client.
* The "token" field matches the "token" value in the challenge 3. Open a TLS connection to the domain name being validated on the
requested port, presenting the value
"<Zi[0:32]>.<Zi[32:64]>.acme.invalid" in the SNI field (where the
comparison is case-insensitive).
4. Open a TLS connection to the domain name being validated on port 4. Verify that the certificate contains a subjectAltName extension
443, presenting the value "<Z[0:32]>.<Z[32:64]>.acme.invalid" in with the dNSName of "<Z[0:32]>.<Z[32:64]>.acme.invalid", and that
the SNI field. no other dNSName entries of the form "*.acme.invalid" are present
in the subjectAltName extension.
5. Verify that the certificate contains a subjectAltName extension It is RECOMMENDED that the ACME server verify a random subset of the
with the dNSName of "<Z[0:32]>.<Z[32:64]>.acme.invalid". N iterations with an appropriate sized to ensure that an attacker who
can provision certs for a default virtual host, but not for arbitrary
simultaneous virtual hosts, cannot pass the challenge. For instance,
testing a subset of 5 of N=25 domains ensures that such an attacker
has only a one in 25/5 chance of success if they post certs Zn in
random succession. (This probability is enforced by the requirement
that each certificate have only one Zi value.)
It is RECOMMENDED that the ACME server validation TLS connections It is RECOMMENDED that the ACME server validation TLS connections
from multiple vantage points to reduce the risk of DNS hijacking from multiple vantage points to reduce the risk of DNS hijacking
attacks. attacks.
If all of the above verifications succeed, then the validation is If all of the above verifications succeed, then the validation is
successful. Otherwise, the validation fails. successful. Otherwise, the validation fails.
7.3. Proof of Possession of a Prior Key 7.4. Proof of Possession of a Prior Key
The Proof of Possession challenge verifies that a client possesses a The Proof of Possession challenge verifies that a client possesses a
private key corresponding to a server-specified public key, as private key corresponding to a server-specified public key, as
demonstrated by its ability to sign with that key. This challenge is demonstrated by its ability to sign with that key. This challenge is
meant to be used when the server knows of a public key that is meant to be used when the server knows of a public key that is
already associated with the identifier being claimed, and wishes for already associated with the identifier being claimed, and wishes for
new authorizations to be authorized by the holder of the new authorizations to be authorized by the holder of the
corresponding private key. For DNS identifiers, for example, this corresponding private key. For DNS identifiers, for example, this
can help guard against domain hijacking. can help guard against domain hijacking.
skipping to change at page 42, line 28 skipping to change at page 42, line 38
(challenge + authorizationRequest). The server provides a nonce and (challenge + authorizationRequest). The server provides a nonce and
the client signs over the nonce. The main difference is that rather the client signs over the nonce. The main difference is that rather
than signing with the private key of the key pair being authorized, than signing with the private key of the key pair being authorized,
the client signs with a private key specified by the server. The the client signs with a private key specified by the server. The
server can specify which key pair(s) are acceptable directly (by server can specify which key pair(s) are acceptable directly (by
indicating a public key), or by asking for the key corresponding to a indicating a public key), or by asking for the key corresponding to a
certificate. certificate.
The server provides the following fields as part of the challenge: The server provides the following fields as part of the challenge:
type (required, string): The string "proofOfPossession" type (required, string): The string "proofOfPossession-01"
certs (optional, array of string): An array of certificates, in certs (optional, array of string): An array of certificates, in
Base64-encoded DER format, that contain acceptable public keys. Base64-encoded DER format, that contain acceptable public keys.
{ {
"type": "proofOfPossession", "type": "proofOfPossession-01",
"certs": ["MIIF7z...bYVQLY"] "certs": ["MIIF7z...bYVQLY"]
} }
In response to this challenge, the client uses the private key In response to this challenge, the client uses the private key
corresponding to one of the acceptable public keys to sign a JWS corresponding to one of the acceptable public keys to sign a JWS
object including data related to the challenge. The validation object including data related to the challenge. The validation
object covered by the signature has the following fields: object covered by the signature has the following fields:
type (required, string): The string "proofOfPossession" type (required, string): The string "proofOfPossession"
skipping to change at page 43, line 4 skipping to change at page 43, line 11
corresponding to one of the acceptable public keys to sign a JWS corresponding to one of the acceptable public keys to sign a JWS
object including data related to the challenge. The validation object including data related to the challenge. The validation
object covered by the signature has the following fields: object covered by the signature has the following fields:
type (required, string): The string "proofOfPossession" type (required, string): The string "proofOfPossession"
identifiers (required, identifier): A list of identifiers for which identifiers (required, identifier): A list of identifiers for which
the holder of the prior key authorizes the new key the holder of the prior key authorizes the new key
accountKey (required, JWK): The client's account public key accountKey (required, JWK): The client's account public key
{ {
"type": "proofOfPossession", "type": "proofOfPossession-01",
"identifiers: [{"type": "dns", "value": "example.com"}], "identifiers: [{"type": "dns", "value": "example.com"}],
"accountKey": { "kty": "RSA", ... } "accountKey": { "kty": "RSA", ... }
} }
This JWS is NOT REQUIRED to have a "nonce" header parameter (as with This JWS is NOT REQUIRED to have a "nonce" header parameter (as with
the JWS objects that carry ACME request objects). This allows proof- the JWS objects that carry ACME request objects). This allows proof-
of-possession response objects to be computed off-line. For example, of-possession response objects to be computed off-line. For example,
as part of a domain transfer, the new domain owner might require the as part of a domain transfer, the new domain owner might require the
old domain owner to sign a proof-of-possession validation object, so old domain owner to sign a proof-of-possession validation object, so
that the new domain owner can present that in an ACME transaction that the new domain owner can present that in an ACME transaction
skipping to change at page 43, line 30 skipping to change at page 43, line 38
The client's response includes the server-provided nonce, together The client's response includes the server-provided nonce, together
with a signature over that nonce by one of the private keys requested with a signature over that nonce by one of the private keys requested
by the server. by the server.
type (required, string): The string "proofOfPossession" type (required, string): The string "proofOfPossession"
authorization (required, JWS): The validation JWS authorization (required, JWS): The validation JWS
{ {
"type": "proofOfPossession", "type": "proofOfPossession-01",
"authorization": { "authorization": {
"header": { "header": {
"alg": "RS256", "alg": "RS256",
"jwk": { "jwk": {
"kty": "RSA", "kty": "RSA",
"e": "AQAB", "e": "AQAB",
"n": "AMswMT...3aVtjE" "n": "AMswMT...3aVtjE"
} }
}, },
"payload": "SfiR1...gSAl7A", "payload": "SfiR1...gSAl7A",
skipping to change at page 44, line 24 skipping to change at page 44, line 30
* The "identifier" field contains the identifier for which * The "identifier" field contains the identifier for which
authorization is being validated authorization is being validated
* The "accountKey" field matches the account key for which the * The "accountKey" field matches the account key for which the
challenge was issued challenge was issued
If all of the above verifications succeed, then the validation is If all of the above verifications succeed, then the validation is
successful. Otherwise, the validation fails. successful. Otherwise, the validation fails.
7.4. DNS 7.5. DNS
When the identifier being validated is a domain name, the client can When the identifier being validated is a domain name, the client can
prove control of that domain by provisioning resource records under prove control of that domain by provisioning resource records under
it. The DNS challenge requires the client to provision a TXT record it. The DNS challenge requires the client to provision a TXT record
containing a designated value under a specific validation domain containing a designated value under a specific validation domain
name. name.
type (required, string): The string "dns" type (required, string): The string "dns-01"
token (required, string): The value to be used in generation of
validation record to be provisioned in DNS. This value MUST have
at least 128 bits of entropy, in order to prevent an attacker from
guessing it. It MUST NOT contain any characters outside the URL-
safe Base64 alphabet.
{
"type": "dns",
"token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA"
}
In response to this challenge, the client uses its account private
key to sign a JWS over a JSON object describing the challenge. The
validation object covered by the signature MUST have the following
fields and no others:
type (required, string): The string "dns" token (required, string): A random value that uniquely identifies
token (required, string): The token value from the server-provided the challenge. This value MUST have at least 128 bits of entropy,
challenge object in order to prevent an attacker from guessing it. It MUST NOT
contain any characters outside the URL-safe Base64 alphabet.
{ {
"type": "dns", "type": "dns-01",
"token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA" "token": "evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA"
} }
The client serializes the validation object to UTF-8, then uses its A client responds to this challenge by constructing a key
account private key to sign a JWS with the serialized JSON object as authorization from the "token" value provided in the challenge and
its payload. This JWS is NOT REQUIRED to have the "nonce" header the client's account key. The client then computes the SHA-256
parameter. digest of the key authorization.
The record provisioned to the DNS is the "signature" value from the The record provisioned to the DNS is the base64 encoding of this
JWS, i.e., the base64-encoded signature value. The client constructs digest. The client constructs the validation domain name by
the validation domain name by appending the label "_acme-challenge" prepending the label "_acme-challenge" to the domain name being
to the domain name being validated, then provisions a TXT record with validated, then provisions a TXT record with the digest value under
the signature value under that name. For example, if the domain name that name. For example, if the domain name being validated is
being validated is "example.com", then the client would provision the "example.com", then the client would provision the following DNS
following DNS record: record:
_acme-challenge.example.com. 300 IN TXT "gfj9Xq...Rg85nM" _acme-challenge.example.com. 300 IN TXT "gfj9Xq...Rg85nM"
The response to a DNS challenge provides the validation JWS to the The response to the DNS challenge simply acknowledges that the client
server. is ready to fulfill this challenge.
type (required, string): The string "dns"
validation (required, JWS): The JWS object computed with the keyAuthorization (required, string): The key authorization for this
validation object and the account key challenge. This value MUST match the token from the challenge and
the client's account key.
{ {
"type": "dns" "keyAuthorization": "evaGxfADs...62jcerQ",
"clientPublicKey": { "kty": "EC", ... },
"validation": {
"header": { "alg": "HS256" },
"payload": "qzu9...6bjn",
"signature": "gfj9XqFv07e1wU66hSLYkiFqYakPSjAu8TsyXRg85nM"
}
} }
/* Signed as JWS */
To validate a DNS challenge, the server performs the following steps: On receiving a response, the server MUST verify that the key
authorization in the response matches the "token" value in the
1. Verify the validation JWS using the account key for which this challenge and the client's account key. If they do not match, then
challenge was issued the server MUST return an HTTP error in response to the POST request
in which the client sent the challenge.
2. Decode the payload of the JWS as UTF-8 encoded JSON
3. Verify that there are exactly two fields in the decoded object,
and that:
* The "type" field is set to "dns" To validate a DNS challenge, the server performs the following steps:
* The "token" field matches the "token" value in the challenge 1. Compute the SHA-256 digest of the key authorization
4. Query for TXT records under the validation domain name 2. Query for TXT records under the validation domain name
5. Verify that the contents of one of the TXT records match the 3. Verify that the contents of one of the TXT records matches the
"signature" value in the "validation" JWS digest value
If all of the above verifications succeed, then the validation is If all of the above verifications succeed, then the validation is
successful. If no DNS record is found, or DNS record and response successful. If no DNS record is found, or DNS record and response
payload do not pass these checks, then the validation fails. payload do not pass these checks, then the validation fails.
8. IANA Considerations 8. IANA Considerations
TODO TODO
o Register .well-known path o Register .well-known path
skipping to change at page 49, line 10 skipping to change at page 48, line 41
o Because the challenges were issued in response to a message signed o Because the challenges were issued in response to a message signed
account key B, the ACME server grants authorization to account key account key B, the ACME server grants authorization to account key
B (the MitM) instead of account key A (the legitimate domain B (the MitM) instead of account key A (the legitimate domain
holder) holder)
All of the challenges above that require an out-of-band query by the All of the challenges above that require an out-of-band query by the
server have a binding to the account private key, such that the only server have a binding to the account private key, such that the only
the account private key holder can successfully respond to the the account private key holder can successfully respond to the
validation query: validation query:
o Simple HTTP: The value provided in the validation request is o HTTP: The value provided in the validation request is signed by
signed by the account private key. the account private key.
o DVSNI: The validation TLS request uses the account key pair as the o TLS SNI: The validation TLS request uses the account key pair as
server's key pair. the server's key pair.
o DNS: The MAC covers the account key, and the MAC key is derived o DNS: The MAC covers the account key, and the MAC key is derived
from an ECDH public key signed with the account private key. from an ECDH public key signed with the account private key.
o Proof of possession of a prior key: The signature by the prior key o Proof of possession of a prior key: The signature by the prior key
covers the account public key. covers the account public key.
The association of challenges to identifiers is typically done by The association of challenges to identifiers is typically done by
requiring the client to perform some action that only someone who requiring the client to perform some action that only someone who
effectively controls the identifier can perform. For the challenges effectively controls the identifier can perform. For the challenges
in this document, the actions are: in this document, the actions are:
o Simple HTTP: Provision files under .well-known on a web server for o HTTP: Provision files under .well-known on a web server for the
the domain domain
o DVSNI: Configure a TLS server for the domain o TLS SNI: Configure a TLS server for the domain
o DNS: Provision DNS resource records for the domain o DNS: Provision DNS resource records for the domain
o Proof of possession of a prior key: Sign using the private key o Proof of possession of a prior key: Sign using the private key
specified by the server specified by the server
There are several ways that these assumptions can be violated, both There are several ways that these assumptions can be violated, both
by misconfiguration and by attack. For example, on a web server that by misconfiguration and by attack. For example, on a web server that
allows non-administrative users to write to .well-known, any user can allows non-administrative users to write to .well-known, any user can
claim to own the server's hostname by responding to a Simple HTTP claim to own the server's hostname by responding to a Simple HTTP
challenge, and likewise for TLS configuration and DVSNI. challenge, and likewise for TLS configuration and TLS SNI.
The use of hosting providers is a particular risk for ACME The use of hosting providers is a particular risk for ACME
validation. If the owner of the domain has outsourced operation of validation. If the owner of the domain has outsourced operation of
DNS or web services to a hosting provider, there is nothing that can DNS or web services to a hosting provider, there is nothing that can
be done against tampering by the hosting provider. As far as the be done against tampering by the hosting provider. As far as the
outside world is concerned, the zone or web site provided by the outside world is concerned, the zone or web site provided by the
hosting provider is the real thing. hosting provider is the real thing.
More limited forms of delegation can also lead to an unintended party More limited forms of delegation can also lead to an unintended party
gaining the ability to successfully complete a validation gaining the ability to successfully complete a validation
skipping to change at page 50, line 14 skipping to change at page 49, line 46
redirects in Simple HTTP validation and a web site operator redirects in Simple HTTP validation and a web site operator
provisions a catch-all redirect rule that redirects requests for provisions a catch-all redirect rule that redirects requests for
unknown resources to different domain. Then the target of the unknown resources to different domain. Then the target of the
redirect could use that to get a certificate through Simple HTTP redirect could use that to get a certificate through Simple HTTP
validation, since the validation path will not be known to the validation, since the validation path will not be known to the
primary server. primary server.
The DNS is a common point of vulnerability for all of these The DNS is a common point of vulnerability for all of these
challenges. An entity that can provision false DNS records for a challenges. An entity that can provision false DNS records for a
domain can attack the DNS challenge directly, and can provision false domain can attack the DNS challenge directly, and can provision false
A/AAAA records to direct the ACME server to send its DVSNI or Simple A/AAAA records to direct the ACME server to send its TLS SNI or HTTP
HTTP validation query to a server of the attacker's choosing. There validation query to a server of the attacker's choosing. There are a
are a few different mitigations that ACME servers can apply: few different mitigations that ACME servers can apply:
o Checking the DNSSEC status of DNS records used in ACME validation o Checking the DNSSEC status of DNS records used in ACME validation
(for zones that are DNSSEC-enabled) (for zones that are DNSSEC-enabled)
o Querying the DNS from multiple vantage points to address local o Querying the DNS from multiple vantage points to address local
attackers attackers
o Applying mitigations against DNS off-path attackers, e.g., adding o Applying mitigations against DNS off-path attackers, e.g., adding
entropy to requests [I-D.vixie-dnsext-dns0x20] or only using TCP entropy to requests [I-D.vixie-dnsext-dns0x20] or only using TCP
skipping to change at page 56, line 13 skipping to change at page 55, line 39
2015, <http://www.rfc-editor.org/info/rfc7515>. 2015, <http://www.rfc-editor.org/info/rfc7515>.
[RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/ [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/
RFC7517, May 2015, RFC7517, May 2015,
<http://www.rfc-editor.org/info/rfc7517>. <http://www.rfc-editor.org/info/rfc7517>.
[RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, DOI [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, DOI
10.17487/RFC7518, May 2015, 10.17487/RFC7518, May 2015,
<http://www.rfc-editor.org/info/rfc7518>. <http://www.rfc-editor.org/info/rfc7518>.
[RFC7638] Jones, M. and N. Sakimura, "JSON Web Key (JWK)
Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September
2015, <http://www.rfc-editor.org/info/rfc7638>.
[SEC1] Standards for Efficient Cryptography Group, "SEC 1: [SEC1] Standards for Efficient Cryptography Group, "SEC 1:
Elliptic Curve Cryptography", May 2009, Elliptic Curve Cryptography", May 2009,
<http://www.secg.org/sec1-v2.pdf>. <http://www.secg.org/sec1-v2.pdf>.
11.2. Informative References 11.2. Informative References
[I-D.vixie-dnsext-dns0x20] [I-D.vixie-dnsext-dns0x20]
Vixie, P. and D. Dagon, "Use of Bit 0x20 in DNS Labels to Vixie, P. and D. Dagon, "Use of Bit 0x20 in DNS Labels to
Improve Transaction Identity", draft-vixie-dnsext- Improve Transaction Identity", draft-vixie-dnsext-
dns0x20-00 (work in progress), March 2008. dns0x20-00 (work in progress), March 2008.
 End of changes. 80 change blocks. 
234 lines changed or deleted 230 lines changed or added

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