Extensions to Automatic Certificate Management Environment for End-User S/MIME CertificatesIsode Ltd14 Castle MewsHampton, MiddlesexTW12 2NPUnited Kingdomalexey.melnikov@isode.comACMES/MIME
This document specifies identifiers and challenges required to enable
the Automated Certificate Management Environment (ACME) to issue
certificates for use by email users
that want to use S/MIME.
Status of This Memo
This document is not an Internet Standards Track specification; it is
published for informational purposes.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Not all documents
approved by the IESG are candidates for any level of Internet
Standard; see Section 2 of RFC 7841.
Information about the current status of this document, any
errata, and how to provide feedback on it may be obtained at
.
Copyright Notice
Copyright (c) 2021 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
() in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with
respect to this document. Code Components extracted from this
document must include Simplified BSD License text as described in
Section 4.e of the Trust Legal Provisions and are provided without
warranty as described in the Simplified BSD License.
Table of Contents
. Introduction
. Conventions Used in This Document
. Use of ACME for Issuing End-User S/MIME Certificates
. ACME "Challenge" Email
. ACME "Response" Email
. Generating Encryption-Only or Signing-Only S/MIME Certificates
. Internationalization Considerations
. IANA Considerations
. ACME Identifier Type
. ACME Challenge Type
. Security Considerations
. References
. Normative References
. Informative References
Acknowledgements
Author's Address
Introduction
ACME is a mechanism for automating certificate
management on the Internet. It enables administrative entities to
prove effective control over resources like domain names, and it
automates the process of generating and issuing certificates.
This document describes an extension to ACME for use by S/MIME.
defines extensions for issuing end-user S/MIME certificates.
This document aims to support both:
A Mail User Agent (MUA) that has a built-in ACME client that is aware
of the extension described in this document. (We will call such MUAs "ACME-email-aware".)
Such an MUA can present a nice user interface to the user and automate certificate issuance.
An MUA that is not ACME aware, with a separate ACME client implemented in a command-line tool or as a part of a website. While S/MIME certificate issuance is not going to
be as painless as in the case of the ACME-email-aware MUA, the extra burden on a user is
going to be minimal.
Conventions Used in This Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED",
"MAY", and "OPTIONAL" in this document are to be interpreted as
described in BCP 14
when, and only when, they appear in all capitals, as shown here.
Use of ACME for Issuing End-User S/MIME Certificates
ACME 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 or internationalized ;
when an internationalized email address is used, the domain part can contain both U-labels and A-labels .
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 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 .
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 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 .
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 ) to create the ACME "token" and calculates
keyAuthorization (as per ).
Then, it returns the base64url-encoded SHA-256 digest 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 .
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 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
CSR MUST contain the requested email address in an extensionRequest
attribute 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 ).
This is described in more details in .
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.
ACME "Challenge" Email
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 )
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 , the subject line can be folded, so white spaces (if any) within
the <token-part1> MUST be ignored. 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" .
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)
or S/MIME .
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).
ACME "Response" Email
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 ).
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 ), as is normal in reply messages. When
parsing the subject, ACME servers MUST decode 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 .
List-* header fields 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 , 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
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 .
(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
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).
Generating Encryption-Only or Signing-Only S/MIME Certificates
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.
Internationalization Considerations updated/clarified use of DKIM with internationalized email addresses .
Please consult in regards to any changes that need to be implemented.
Use of non-ASCII characters in left-hand sides of internationalized email addresses requires putting
internationalized email addresses in X.509 certificates .
IANA ConsiderationsACME Identifier Type
IANA has registered a new identifier type in the "ACME Identifier
Types" registry defined in with Label "email" and a Reference to this document,
, and . The new identifier type corresponds to an (all
ASCII) email address or
internationalized email addresses .
ACME Challenge Type
IANA has registered a new entry in the "ACME Validation Methods" registry
defined in .
This entry is as follows:
Label
Identifier Type
ACME
Reference
email-reply-00
email
Y
RFC 8823
Security Considerations
Please see the Security Considerations section of for general security
considerations related to the use of ACME. This challenge/response
protocol demonstrates that an entity that controls the private key
(corresponding to the public key in the certificate) also controls the
named email account. The ACME server is confirming that the requested
email address belongs to the entity that requested the certificate,
but this makes no claim to address correctness or fitness for purpose.
If such claims are needed, they must be obtained by some other
mechanism.
The security of the "email-reply-00" challenge type depends on the security of the email system.
A third party that can read and reply to user's email messages (by possessing a user's password
or a secret derived from it that can give read and reply access, such as "password equivalent" information,
or by being given permissions to act on a user's behalf using email delegation features common
in some email systems) can request S/MIME certificates using the protocol specified in this document
and is indistinguishable from the email account owner.
This has several possible implications:
An entity that compromised an email account would be able to request S/MIME certificates
using the protocol specified in this document, and such entity couldn't be distinguished from
the legitimate email account owner (unless some external sources of information are consulted).
For email addresses with legitimate shared access/control by
multiple users, any such user would be able to request S/MIME
certificates using the protocol specified in this document; such
requests can't be attributed to a specific user without consulting
external systems (such as IMAP/SMTP access logs).
The protocol specified in this document is not suitable for use with email addresses
associated with mailing lists . While it is not always
possible to guarantee that a particular S/MIME certificate request is not from a mailing list
address, prohibition on inclusion of List-* header fields helps certificate issuers
to handle most common cases.
An email system in its turn depends on DNS. A third party that can manipulate DNS MX records
for a domain might be able to redirect an email and can get (at least temporary) read and reply access to it.
Similar considerations apply to DKIM TXT records in DNS.
Use of DNSSEC by email system administrators is recommended to avoid making it easy to spoof
DNS records affecting an email system. However, use of DNSSEC is not ubiquitous at the time of
publishing of this document, so it is not required here.
Also, many existing systems that rely on verification of ownership of an email address --
for example, 2-factor authentication systems used by banks or traditional certificate issuance
systems -- send email messages to email addresses, expecting the owner to click on the link supplied
in them (or to reply to a message), without requiring use of DNSSEC. So the risk of not requiring
DNSSEC is presumed acceptable in this document.
An ACME email challenge message can be forged by an attacker.
As per requirements on an ACME-email-aware MUA specified in ,
the MUA will not respond to requests it is not expecting.
Even if the attacker causes the erroneous "response" email to go to
an attacker-controlled email address, very little information is leaked --
the SHA-256 hash of the key authorization would be leaked, not the key
authorization itself, so no parts of the token or the account key
thumbprint are leaked.
An attacker that can read the "response" email has only one chance to guess the
token-part2. Even if the attacker can guess it right, it still needs to know
the ACME account key to be able to make use of the intercepted SHA-256 hash of
the key authorization.
Also see the Security Considerations section of for details on how DKIM depends
on the DNS and the respective vulnerabilities this dependence has.
ReferencesNormative ReferencesMultipurpose Internet Mail Extensions (MIME) Part Two: Media TypesThis second document defines the general structure of the MIME media typing system and defines an initial set of media types. [STANDARDS-TRACK]Key words for use in RFCs to Indicate Requirement LevelsIn many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.MIME Parameter Value and Encoded Word Extensions: Character Sets, Languages, and ContinuationsThis memo defines extensions to the RFC 2045 media type and RFC 2183 disposition parameter value mechanisms. This memo also defines an extension to the encoded words defined in RFC 2047 to allow the specification of the language to be used for display as well as the character set. [STANDARDS-TRACK]HTTP Over TLSThis memo describes how to use Transport Layer Security (TLS) to secure Hypertext Transfer Protocol (HTTP) connections over the Internet. This memo provides information for the Internet community.PKCS #9: Selected Object Classes and Attribute Types Version 2.0This memo represents a republication of PKCS #9 v2.0 from RSA Laboratories' Public-Key Cryptography Standards (PKCS) series, and change control is retained within the PKCS process. The body of this document, except for the security considerations section, is taken directly from that specification. This memo provides information for the Internet community.PKCS #10: Certification Request Syntax Specification Version 1.7This memo represents a republication of PKCS #10 v1.7 from RSA Laboratories' Public-Key Cryptography Standards (PKCS) series, and change control is retained within the PKCS process. The body of this document, except for the security considerations section, is taken directly from the PKCS #9 v2.0 or the PKCS #10 v1.7 document. This memo provides information for the Internet community.Recommendations for Automatic Responses to Electronic MailThis memo makes recommendations for software that automatically responds to incoming electronic mail messages, including "out of the office" or "vacation" response generators, mail filtering software, email-based information services, and other automatic responders. The purpose of these recommendations is to discourage undesirable behavior which is caused or aggravated by such software, to encourage uniform behavior (where appropriate) among automatic mail responders, and to clear up some sources of confusion among implementors of automatic email responders. [STANDARDS-TRACK]The Base16, Base32, and Base64 Data EncodingsThis document describes the commonly used base 64, base 32, and base 16 encoding schemes. It also discusses the use of line-feeds in encoded data, use of padding in encoded data, use of non-alphabet characters in encoded data, use of different encoding alphabets, and canonical encodings. [STANDARDS-TRACK]Simple Mail Transfer ProtocolThis document is a specification of the basic protocol for Internet electronic mail transport. It consolidates, updates, and clarifies several previous documents, making all or parts of most of them obsolete. It covers the SMTP extension mechanisms and best practices for the contemporary Internet, but does not provide details about particular extensions. Although SMTP was designed as a mail transport and delivery protocol, this specification also contains information that is important to its use as a "mail submission" protocol for "split-UA" (User Agent) mail reading systems and mobile environments. [STANDARDS-TRACK]Internet Message FormatThis document specifies the Internet Message Format (IMF), a syntax for text messages that are sent between computer users, within the framework of "electronic mail" messages. This specification is a revision of Request For Comments (RFC) 2822, which itself superseded Request For Comments (RFC) 822, "Standard for the Format of ARPA Internet Text Messages", updating it to reflect current practice and incorporating incremental changes that were specified in other RFCs. [STANDARDS-TRACK]Internationalized Domain Names for Applications (IDNA): Definitions and Document FrameworkThis document is one of a collection that, together, describe the protocol and usage context for a revision of Internationalized Domain Names for Applications (IDNA), superseding the earlier version. It describes the document collection and provides definitions and other material that are common to the set. [STANDARDS-TRACK]US Secure Hash Algorithms (SHA and SHA-based HMAC and HKDF)Federal Information Processing Standard, FIPSDomainKeys Identified Mail (DKIM) SignaturesDomainKeys Identified Mail (DKIM) permits a person, role, or organization that owns the signing domain to claim some responsibility for a message by associating the domain with the message. This can be an author's organization, an operational relay, or one of their agents. DKIM separates the question of the identity of the Signer of the message from the purported author of the message. Assertion of responsibility is validated through a cryptographic signature and by querying the Signer's domain directly to retrieve the appropriate public key. Message transit from author to recipient is through relays that typically make no substantive change to the message content and thus preserve the DKIM signature.This memo obsoletes RFC 4871 and RFC 5672. [STANDARDS-TRACK]SMTP Extension for Internationalized EmailThis document specifies an SMTP extension for transport and delivery of email messages with internationalized email addresses or header information. [STANDARDS-TRACK]Ambiguity of Uppercase vs Lowercase in RFC 2119 Key WordsRFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.Internationalized Email Addresses in X.509 CertificatesThis document defines a new name form for inclusion in the otherName field of an X.509 Subject Alternative Name and Issuer Alternative Name extension that allows a certificate subject to be associated with an internationalized email address.This document updates RFC 5280.Secure/Multipurpose Internet Mail Extensions (S/MIME) Version 4.0 Certificate HandlingThis document specifies conventions for X.509 certificate usage by Secure/Multipurpose Internet Mail Extensions (S/MIME) v4.0 agents. S/MIME provides a method to send and receive secure MIME messages, and certificates are an integral part of S/MIME agent processing. S/MIME agents validate certificates as described in RFC 5280 ("Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile"). S/MIME agents must meet the certificate-processing requirements in this document as well as those in RFC 5280. This document obsoletes RFC 5750.Secure/Multipurpose Internet Mail Extensions (S/MIME) Version 4.0 Message SpecificationThis document defines Secure/Multipurpose Internet Mail Extensions (S/MIME) version 4.0. S/MIME provides a consistent way to send and receive secure MIME data. Digital signatures provide authentication, message integrity, and non-repudiation with proof of origin. Encryption provides data confidentiality. Compression can be used to reduce data size. This document obsoletes RFC 5751.Automatic Certificate Management Environment (ACME)Public Key Infrastructure using X.509 (PKIX) certificates are used for a number of purposes, the most significant of which is the authentication of domain names. Thus, certification authorities (CAs) in the Web PKI are trusted to verify that an applicant for a certificate legitimately represents the domain name(s) in the certificate. As of this writing, this verification is done through a collection of ad hoc mechanisms. This document describes a protocol that a CA and an applicant can use to automate the process of verification and certificate issuance. The protocol also provides facilities for other certificate management functions, such as certificate revocation.Email Authentication for Internationalized MailSender Policy Framework (SPF) (RFC 7208), DomainKeys Identified Mail (DKIM) (RFC 6376), and Domain-based Message Authentication, Reporting, and Conformance (DMARC) (RFC 7489) enable a domain owner to publish email authentication and policy information in the DNS. In internationalized email, domain names can occur both as U-labels and A-labels. This specification updates the SPF, DKIM, and DMARC specifications to clarify which form of internationalized domain names to use in those specifications.Informative ReferencesRegistration of Mail and MIME Header FieldsThis document defines the initial IANA registration for permanent mail and MIME message header fields, per RFC 3864. [STANDARDS-TRACK]Signaling One-Click Functionality for List Email HeadersThis document describes a method for signaling a one-click function for the List-Unsubscribe email header field. The need for this arises out of the actuality that mail software sometimes fetches URLs in mail header fields, and thereby accidentally triggers unsubscriptions in the case of the List-Unsubscribe header field.AcknowledgementsThank you to , ,
, ,
, ,
, ,
, , and
for their suggestions, comments, and corrections of this document.Author's AddressIsode Ltd14 Castle MewsHampton, MiddlesexTW12 2NPUnited Kingdomalexey.melnikov@isode.com