ACME [
RFC 8555] defines a "dns" identifier type that is used to verify that a particular entity has control over a domain or specific service associated with the domain. In order to be able to issue end-user S/MIME certificates, ACME needs a new identifier type that proves ownership of an email address.
This document defines a new identifier type, "email", which corresponds to an email address. The address can be all ASCII [
RFC 5321] or internationalized [
RFC 6531]; when an internationalized email address is used, the domain part can contain both U-labels and A-labels [
RFC 5890]. This can be used with S/MIME or another similar service that requires possession of a certificate tied to an email address.
Any identifier of type "email" in a newOrder request
MUST NOT have a wildcard ("*") character in its value.
A new challenge type, "email-reply-00", is used with the "email" identifier type, which provides proof that an ACME client has control over an email address.
The process of issuing an S/MIME certificate works as follows. Note that the ACME client can be a standalone application (if the MUA is not ACME-email-aware) or can be a component of the MUA.
-
An end user initiates issuance of an S/MIME certificate for one of their email addresses. This might be done by using an email client UI, by running a command-line tool, by visiting a certificate authority web page, etc. This document doesn't prescribe a specific UI used to initiate S/MIME certificate issuance or where the ACME client is located.
-
The ACME-email-aware client component begins the certificate issuance process by sending a POST request to the server's newOrder resource, including the identifier of type "email". See Section 7.4 of RFC 8555 for more details.
-
The ACME server responds to the POST request, including an "authorizations" URL for the requested email address. The ACME client then retrieves information about the corresponding "email-reply-00" challenge, as specified in Section 7.5 of RFC 8555. The "token" field of the corresponding challenge object (from the "challenges" array) contains token-part2. token-part2 should contain at least 128 bits of entropy. The "type" field of the challenge object is "email-reply-00". The challenge object also contains the "from" field, with the email address that would be used in the From header field of the "challenge" email message (see the next step).
An example challenge object might look like this:
{
"type": "email-reply-00",
"url": "https://example.com/acme/chall/ABprV_B7yEyA4f",
"from": "acme-challenge+2i211oi1204310@example.com",
"token": "DGyRejmCefe7v4NfDGDKfA"
}
-
After responding to the authorization request, the ACME server generates another token and a "challenge" email message with the subject "ACME: <token-part1>", where <token-part1> is the base64url-encoded [RFC 4648] form of the token. The ACME server MUST generate a fresh token for each S/MIME issuance request (authorization request), and token-part1 MUST contain at least 128 bits of entropy. The "challenge" email message structure is described in more details in Section 3.1.
-
The MUA retrieves and parses the "challenge" email message. If the MUA is ACME-email-aware, it ignores any "challenge" email that is not expected, e.g., if there is no ACME certificate issuance pending. The ACME-email-aware MUA also ignores any "challenge" email that has the Subject header field that indicates that it is an email reply, e.g., a subject starting with the reply prefix "Re:".
-
The ACME client concatenates "token-part1" (received over email) and "token-part2" (received over HTTPS [RFC 2818]) to create the ACME "token" and calculates keyAuthorization (as per Section 8.1 of RFC 8555). Then, it returns the base64url-encoded SHA-256 digest [RFC 6234] of the key authorization. The MUA returns the base64url-encoded SHA-256 digest obtained from the ACME client in the body of a "response" email message. The "response" email message structure is described in more details in Section 3.2. If the MUA is ACME-email-aware, it MUST NOT respond to the same "challenge" email more than once.
-
Once the MUA sends the "response" email, the ACME client notifies the ACME server by POST to the challenge URL ("url" field).
-
The ACME client can start polling the authorization URL (using POST-as-GET requests) to see if the ACME server received and validated the "response" email message. (See Section 7.5.1 of RFC 8555 for more details.) If the "status" field of the challenge switches to "valid", then the ACME client can proceed with request finalization. The Certificate Signing Request (CSR) MUST indicate the exact same set of requested identifiers as the initial newOrder request. For an identifier of type "email", the PKCS#10 [RFC 2986] CSR MUST contain the requested email address in an extensionRequest attribute [RFC 2985] requesting a subjectAltName extension. The email address MUST also match the From header field value of the "response" email message.
-
In order to request generation of signing-only or encryption-only S/MIME certificates (as opposed to requesting generation of S/MIME certificates suitable for both), the CSR needs to include the key usage extension (see Section 4.4.2 of RFC 8550). This is described in more details in Section 3.3.
-
If a request to finalize an order is successful, the ACME server will return a 200 (OK) with an updated order object. If the certificate is issued successfully, i.e., if the order "status" is "valid", then the ACME client can download the issued S/MIME certificate from the URL specified in the "certificate" field.
A "challenge" email message
MUST have the following structure:
-
The Subject header field has the following syntax: "ACME: <token-part1>", where the prefix "ACME:" is followed by folding white space (FWS; see [RFC 5322]) and then by <token-part1>, which is the base64url-encoded first part of the ACME token that MUST be at least 128 bits long after decoding. Due to the recommended 78-octet line-length limit in [RFC 5322], the subject line can be folded, so white spaces (if any) within the <token-part1> MUST be ignored. [RFC 2231] encoding of the Subject header field MUST be supported, and, when used, only the "UTF-8" and "US-ASCII" charsets are allowed; other charsets MUST NOT be used. The US-ASCII charset SHOULD be used.
-
The From header field MUST be the same email address as specified in the "from" field of the challenge object.
-
The To header field MUST be the email address of the entity that requested the S/MIME certificate to be generated.
-
The message MAY contain a Reply-To and/or CC header field.
-
The message MUST include the Auto-Submitted header field with the value "auto-generated" [RFC 3834]. To aid in debugging (and, for some implementations, to make automated processing easier), the Auto-Submitted header field SHOULD include the "type=acme" parameter. It MAY include other optional parameters, as allowed by the syntax of the Auto-Submitted header field.
-
In order to prove authenticity of a challenge message, it MUST be signed using either DomainKeys Identified Mail (DKIM) [RFC 6376] or S/MIME [RFC 8551].
-
If DKIM signing is used, the resulting DKIM-Signature header field MUST contain the "h=" tag that includes at least the From, Sender, Reply-To, To, CC, Subject, Date, In-Reply-To, References, Message-ID, Auto-Submitted, Content-Type, and Content-Transfer-Encoding header fields. The DKIM-Signature header field's "h=" tag SHOULD also include the Resent-Date, Resent-From, Resent-To, Resent-Cc, List-Id, List-Help, List-Unsubscribe, List-Subscribe, List-Post, List-Owner, List-Archive, and List-Unsubscribe-Post header fields. The domain from the "d=" tag of the DKIM-Signature header field MUST be the same as the domain from the From header field of the "challenge" email.
-
If S/MIME signing is used, the certificate corresponding to the signer MUST have an rfc822Name subjectAltName extension with the value equal to the From header field email address of the "challenge" email.
-
The body of the challenge message is not used for automated processing, so it can be any media type. (However, there are extra requirements on S/MIME signing, if used. See below.) Typically, it is text/plain or text/html containing a human-readable explanation of the purpose of the message. If S/MIME signing is used to prove authenticity of the challenge message, then the multipart/signed or "application/pkcs7-mime; smime-type=signed-data;" media type should be used. Either way, it MUST use S/MIME header protection.
An email client compliant with this specification that detects that a particular "challenge" email fails the validation described above
MUST ignore the challenge and thus will not generate a "response" email. To aid in debugging, such failed validations
SHOULD be logged.
Here is an example of an ACME "challenge" email (note that, for simplicity, DKIM-related header fields are not included).
Auto-Submitted: auto-generated; type=acme
Date: Sat, 5 Dec 2020 10:08:55 +0100
Message-ID: <A2299BB.FF7788@example.org>
From: acme-generator@example.org
To: alexey@example.com
Subject: ACME: LgYemJLy3F1LDkiJrdIGbEzyFJyOyf6vBdyZ1TG3sME=
Content-Type: text/plain
MIME-Version: 1.0
This is an automatically generated ACME challenge for email address
"alexey@example.com". If you haven't requested an S/MIME
certificate generation for this email address, be very afraid.
If you did request it, your email client might be able to process
this request automatically, or you might have to paste the first
token part into an external program.
A valid "response" email message
MUST have the following structure:
-
The Subject header field is formed as a reply to the ACME "challenge" email (see Section 3.1). Its syntax is the same as that of the challenge message except that it may be prefixed by a US-ASCII reply prefix (typically "Re:") and FWS (see [RFC 5322]), as is normal in reply messages. When parsing the subject, ACME servers MUST decode [RFC 2231] encoding (if any), and then they can ignore any prefix before the "ACME:" label.
-
The From header field contains the email address of the user that is requesting S/MIME certificate issuance.
-
The To header field of the response contains the value from the Reply-To header field from the challenge message (if set). Otherwise, it contains the value from the From header field of the challenge message.
-
The Cc header field is ignored if present in the "response" email message.
-
The In-Reply-To header field SHOULD be set to the Message-ID header field of the challenge message according to rules in Section 3.6.4 of RFC 5322.
-
List-* header fields [RFC 4021][RFC 8058] MUST be absent (i.e., the reply can't come from a mailing list).
-
The media type of the "response" email message is either text/plain or multipart/alternative [RFC 2046], containing text/plain as one of the alternatives. (Note that the requirement to support multipart/alternative is to allow use of ACME-unaware MUAs, which can't always generate pure text/plain, e.g., if they reply to a text/html). The text/plain body part (whether or not it is inside multipart/alternative) MUST contain a block of lines starting with the line "-----BEGIN ACME RESPONSE-----", followed by one or more lines containing the base64url-encoded SHA-256 digest [RFC 6234] of the key authorization, calculated from concatenated token-part1 (received over email) and token-part2 (received over HTTPS), as outlined in the 5th bullet in Section 3. (Note that each line of text/plain is terminated by CRLF. Bare LFs or bare CRs are not allowed.) Due to historical line-length limitations in email, line endings (CRLFs) can be freely inserted in the middle of the encoded digest, so they MUST be ignored when processing it. The final line of the encoded digest is followed by a line containing:
-----END ACME RESPONSE-----
Any text before and after this block is ignored. For example, such text might explain what to do with it for ACME-unaware clients.
-
There is no need to use any Content-Transfer-Encoding other than 7bit for the text/plain body part. Use of quoted-printable or base64 in a "response" email message is not necessary and should be avoided, though it is permitted.
-
In order to prove authenticity of a response message, it MUST be DKIM [RFC 6376] signed. The resulting DKIM-Signature header field MUST contain the "h=" tag that includes at least the From, Sender, Reply-To, To, CC, Subject, Date, In-Reply-To, References, Message-ID, Content-Type, and Content-Transfer-Encoding header fields. The DKIM-Signature header field's "h=" tag SHOULD also include the Resent-Date, Resent-From, Resent-To, Resent-Cc, List-Id, List-Help, List-Unsubscribe, List-Subscribe, List-Post, List-Owner, List-Archive, and List-Unsubscribe-Post header fields. The domain from the "d=" tag of DKIM-Signature header field MUST be the same as the domain from the From header field of the "response" email.
Here is an example of an ACME "response" email (note that, for simplicity, DKIM-related header fields are not included).
Date: Sat, 5 Dec 2020 12:01:45 +0100
Message-ID: <111-22222-3333333@example.com>
In-Reply-To: <A2299BB.FF7788@example.org>
From: alexey@example.com
To: acme-generator@example.org
Subject: Re: ACME: LgYemJLy3F1LDkiJrdIGbEzyFJyOyf6vBdyZ1TG3sME=
Content-Type: text/plain
MIME-Version: 1.0
-----BEGIN ACME RESPONSE-----
LoqXcYV8q5ONbJQxbmR7SCTNo3tiAXDfowy
jxAjEuX0=
-----END ACME RESPONSE-----
ACME extensions specified in this document can be used to request signing-only or encryption-only S/MIME certificates.
In order to request signing-only S/MIME certificates, the CSR
MUST include the key usage extension with digitalSignature and/or nonRepudiation bits set and no other bits set.
In order to request encryption-only S/MIME certificates, the CSR
MUST include the key usage extension with keyEncipherment or keyAgreement bits set and no other bits set.
Presence of both of the above sets of key usage bits in the CSR, as well as absence of the key usage extension in the CSR, signals to the ACME server to issue an S/MIME certificate suitable for both signing and encryption.