From 2ad063217f3c6e531d4384d3b149f4265bd3c835 Mon Sep 17 00:00:00 2001 From: EKR Date: Wed, 5 Feb 2014 13:39:26 -0800 Subject: [PATCH] First import of ACIP draft --- acip/draft-rescorla-acip.txt | 1008 ++++++++++++++++++++++++++++++++++ acip/draft-rescorla-acip.xml | 869 +++++++++++++++++++++++++++++ 2 files changed, 1877 insertions(+) create mode 100644 acip/draft-rescorla-acip.txt create mode 100644 acip/draft-rescorla-acip.xml diff --git a/acip/draft-rescorla-acip.txt b/acip/draft-rescorla-acip.txt new file mode 100644 index 000000000..575efb615 --- /dev/null +++ b/acip/draft-rescorla-acip.txt @@ -0,0 +1,1008 @@ + + + +Network Working Group E. Rescorla +Internet-Draft Mozilla +Intended status: Standards Track December 11, 2013 +Expires: June 14, 2014 + + + Automatic Certificate Issuance Protocol (ACIP) + draft-rescorla-stir-fallback-00 + +Abstract + + [TODO] + +Status of this Memo + + This Internet-Draft is submitted in full conformance with the + provisions of BCP 78 and BCP 79. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF). Note that other groups may also distribute + working documents as Internet-Drafts. The list of current Internet- + Drafts is at http://datatracker.ietf.org/drafts/current/. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress." + + This Internet-Draft will expire on June 14, 2014. + +Copyright Notice + + Copyright (c) 2013 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 + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + This document may contain material from IETF Documents or IETF + Contributions published or made publicly available before November + 10, 2008. The person(s) controlling the copyright in some of this + + + +Rescorla Expires June 14, 2014 [Page 1] + +Internet-Draft ACIP December 2013 + + + material may not have granted the IETF Trust the right to allow + modifications of such material outside the IETF Standards Process. + Without obtaining an adequate license from the person(s) controlling + the copyright in such materials, this document may not be modified + outside the IETF Standards Process, and derivative works of it may + not be created outside the IETF Standards Process, except to format + it for publication as an RFC or to translate it into languages other + than English. + + +Table of Contents + + 1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 3. Deployment Model and Operator Experience . . . . . . . . . . . 3 + 3.1. Other Use Cases . . . . . . . . . . . . . . . . . . . . . 4 + 4. System Architecture Overview . . . . . . . . . . . . . . . . . 4 + 4.1. Initial Issuance . . . . . . . . . . . . . . . . . . . . . 5 + 4.2. Certificate Refresh . . . . . . . . . . . . . . . . . . . 6 + 5. Protocol Description . . . . . . . . . . . . . . . . . . . . . 6 + 5.1. CA Policies . . . . . . . . . . . . . . . . . . . . . . . 6 + 5.2. Protocol Messages . . . . . . . . . . . . . . . . . . . . 8 + 5.2.1. Issuance Requests . . . . . . . . . . . . . . . . . . 9 + 5.2.2. HTTPS with SNI . . . . . . . . . . . . . . . . . . . . 11 + 5.2.3. DNS . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 5.2.4. DANE . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 5.3. Certificate Issuance . . . . . . . . . . . . . . . . . . . 11 + 5.4. Requesting Revocation . . . . . . . . . . . . . . . . . . 12 + 5.5. Validation Methods . . . . . . . . . . . . . . . . . . . . 13 + 5.5.1. Simple HTTPS . . . . . . . . . . . . . . . . . . . . . 13 + 5.5.2. Digital Signature . . . . . . . . . . . . . . . . . . 14 + 5.5.3. Secret Token . . . . . . . . . . . . . . . . . . . . . 14 + 5.6. Errors . . . . . . . . . . . . . . . . . . . . . . . . . . 14 + 5.7. Status Publication . . . . . . . . . . . . . . . . . . . . 15 + 5.8. HTTPS Binding . . . . . . . . . . . . . . . . . . . . . . 16 + 6. Security Considerations . . . . . . . . . . . . . . . . . . . 17 + 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 + 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 17 + 9. Normative References . . . . . . . . . . . . . . . . . . . . . 17 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 18 + + + + + + + + + + + +Rescorla Expires June 14, 2014 [Page 2] + +Internet-Draft ACIP December 2013 + + +1. Terminology + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [RFC2119]. + + +2. Introduction + + Existing Web PKI certificate authorities tend to run on a set of ad + hoc protocols for certificate issuance and identity verification. A + typical user experience is something like: + + o Generate a PKCS#10 [RFC2314] Certificate Signing Request (CSR). + o Cut-and-paste the CSR into a CA web page. + o Prove ownership of the domain by one of the following methods: + * Put a CA-provided challenge at a specific place on the web + server + * Put a CA-challenge at a DNS location corresponding to the + target domain. + * Receive CA challenge at an (allegedly) administrator controlled + e-mail address corresponding to the domain and then respond to + it on the CA's web page. + o Download the issued certificate and install it on their Web + Server. + + With the exception of the CSR itself and the certificates that are + issued, these are all completely ad hoc procedures and are + accomplished by getting the user to follow instructions from the CA + rather than by published protocols. In many cases, the instructions + are difficult to follow and cause significant confusion. Even in the + best case, the lack of published, standardized mechanisms presents an + obstacle to the wide deployment of certificate-using systems. + + This document describes a framework for automating the issuance and + domain validation procedure, thus enabling the construction of + certificate-holding entities which can obtain certificates without + user interaction. It is hoped that this will radically increase the + level of deployment of certificate-using systems and specifically of + HTTPS. + + +3. Deployment Model and Operator Experience + + It's easiest to understand ACIP in the context of certificates for + Web sites (HTTPS [RFC2818]). In that case, the server is intended to + speak for one or more domains and the process of certificate issuance + is intended to verify that the server actually speaks for the domain. + + + +Rescorla Expires June 14, 2014 [Page 3] + +Internet-Draft ACIP December 2013 + + + In the case of "Domain Validation" (DV) certificates, the server + validation process merely verifies that the requester has effective + control of the domain but does not really attempt to verify their + real-world identity. (This is as opposed to "Extended Validation" + (EV) certificates where the process is intended to also verify the + real-world identity of the requester.) + + When an operator deploys a current HTTPS server, it generally prompts + him to generate a self-signed certificate. When an operator deploys + an ACIP-compatible server, the experience would be something like + this: + + o The server prompts the operator for the intended domain name(s) + that the server is to stand for. + o The server presents the operator with a list of CAs which it could + get a certificate from. The server might prompt the operator for + payment information at this point. + o Once the operator has selected a CA, tells the operator that he + will have a certificate shortly. + o In the background, the server contacts the CA, sends a CSR, and + engages in the validation procedure. + o Once the CA is satisfied, the certificate is issued and the server + automatically downloads and installs it, potentially notifying the + operator via e-mail, SMS, etc. + o The server periodically contacts the CA to get updated + certificates, stapled OCSP responses, or whatever else would be + required to keep the server functional and its credentials up-to- + date. + + The overall idea is that it's nearly as easy to deploy with a valid + certificate as a self-signed certificate and that once the operator + has done so, the process is self-sustaining with minimal manual + intervention. + +3.1. Other Use Cases + + While ACIP is explicitly designed for HTTPS server certificates, it + is in general usable in any situation where the certificate subject + is automatically verifiable. In principle, then, it could be used + with personal addresses (XMPP or e-mail) if there is some + straightforward way of responding to the validation procedure, e.g., + by having the client automatically detect and respond to validation + answerback queries. + + +4. System Architecture Overview + + We assume that that an ACIP-compatible agent which wishes to get a + + + +Rescorla Expires June 14, 2014 [Page 4] + +Internet-Draft ACIP December 2013 + + + certificate (currently, the "Certificate Holder" (CH)) starts with a + list of ACIP-compliant CAs represented as URLs. From there, the + protocol proceeds as shown below. Note that we have taken some + liberties with messages from the CA to the CH: everything is done + over HTTPS, so messages from the CA likely require either polling by + the CH or that the CH have some accessible endpoint for the CA to + talk to. + +4.1. Initial Issuance + + CH CA + + Policy + <-------- Validation Methods + + Desired identity + CSR + Validation Method --------> + + <-------- Challenge + + Response --------> + + <-------- Certificate + + Initially, the CH contacts the CA and retrieves the CA's + capabilities. This likely includes information like the validation + types (e-mail, DNS, Web, etc.) that the CA supports, whether it + charges, the types of keys it will issue for, how often the + certificates need to be reissued, etc. The CH might contact multiple + CAs to find one with the best policies before it actually requests a + certificate. + + Once the CH (or more likely the operator) has selected a CA, the CH + generates a key pair and contacts the CA with signing request. He + will also indicate (probably separately), the identity he wants the + certificate issued for and which validation method he wants the CA to + use. He might also provide a URL which the CA can use to indicate + that the certificate is ready. + + Depending on the validation method, the CA will then supply a + challenge to the CH. This might happen immediately, as in the case + of HTTPS validation (section XXX) or might happen later, as in the + case of e-mail validation (section YYY). The CH responds to the + challenge, e.g., by putting it somewhere in /.well-known on their + server. + + Once the CA has validated the CH's identity, it issues the + + + +Rescorla Expires June 14, 2014 [Page 5] + +Internet-Draft ACIP December 2013 + + + certificate. The CH might either poll the CA for readiness or the CH + can provide a URL for the CA to contact when the certificate is + ready. In either case, once the CH has the certificate, it installs + it. + +4.2. Certificate Refresh + + CH CA + + Retrieve Certificate --------> + + <-------- Certificate + + Because certificates eventually expire, there must be some for the CH + to get a new certificate. This need not involve a new authentication + transaction--and if short-lived certificates are used, then it + generally will not--but does require getting new bits to the CH. In + general, the CA will just generate new certificates periodically and + publish them at some deterministic URL that the CH can retrieve them + at. Where a new authentication transaction is required, we just + repeat the flow of Section 4.1 + + +5. Protocol Description + + This section describes the relevant protocol elements. For + explanatory reasons, we have chosen to describe these as if they were + JSON structures. Eventually we may decide on some more fixed binary + encoding, but it's easier to explain with JSON and we may eventually + just use JSON in any cse. + +5.1. CA Policies + + Every ACIP-compliant CA will post a policy document in some public + location. This document MUST be hosted over HTTPS [RFC2818] so that + it can be validated. The URL is assumed to be known to the CH. + + The policy document contains the following values: + + + issuance_validation_methods (mandatory): + A list of validation methods for issuance that the CA supports. + + revocation_validation_methods (mandatory): + + + + + + + +Rescorla Expires June 14, 2014 [Page 6] + +Internet-Draft ACIP December 2013 + + + A list of validation methods for revocation that the CA supports. + + signature_algorithms (mandatory): + A list of signature algorithms that the CA supports. [TODO: + which registry] + + key_types (mandatory): + A list of the key types that the CA allows the CH to have, + structured as an algorithm and an (optional min/max} [TODO: which + registry. + + status_mechanisms (mandatory) + A list of the status mechanisms that the CA supports (OCSP, etc.) + + signing_certificate (optional): + The base64 [REF] encoding of the certificate which will be used to + authorize the CH's key. If the CA has multiple certificates + signed by some intermediate, it will include the intermediate. + The idea here is to provide some idea of what the final + certificate will look like. + + min_lifetime (optional): + The minimum lifetime of certificates issued by the CA in seconds + so that the CH knows how often it is likely to have to refresh. + + An example policy document might look like the one below. + + + + + + + + + + + + + + + + + + + + + + + + + +Rescorla Expires June 14, 2014 [Page 7] + +Internet-Draft ACIP December 2013 + + + { + "issuance_issuance_validation_methods" : + ["https", "https-sni"], + "revocation_validation_methods" : + ["https", "shared-secret"], + "signature_algorithms" : [ "RSA", "ECDSA"], + "key_types" : [ + { + "algorithm" : "RSA", + "min" : 2048, + "max" : 4096 + }, + { + "algorithm" : "ECDSA", + "min" : 192, + "max" : 512 + }, + "min_lifetime" : 604800, + "status_mechanisms" : ["OCSP", + "short-lived", + "OCSP-stapled"], + ] + } + + Note that one important consideration is that it be possible for add + new policy values. Since these are just information to the CH, if + they are unknown they can be ignored, but may of course cause + issuance failure. [TODO: Add some support for payment.] [TODO: + Add other types.] + +5.2. Protocol Messages + + All ACIP protocol messages other than the policy document are carried + in a generic wrapper. + + + type (mandatory): + The message type, either "error" or one of the messages described + below. + + message (mandatory): + The message itself. In the JSON encoding here, just the JSON + structure shown below. + + An example message is shown below. + + + + + + +Rescorla Expires June 14, 2014 [Page 8] + +Internet-Draft ACIP December 2013 + + + { + "type": "issuance_request", + "message": + { + "validation_method" : "https", + "identities" : [ + { + "type" : "dnsNAme", + "www1.example.com" + }, + { + "type" : "dnsNAme", + "www2.example.com" + } + ], + "csr" : "", + "notification_endpoint" : + "http://status.example.com/acip-notification" + } + } + +5.2.1. Issuance Requests + + The issuance request (message type "issuance_request") is relatively + simple: + + + validation_method (mandatory): + The validation method the CH has selected. + + identities (mandatory): + A list of the identities that the CH wants issuance for. Each + identity is a pair of PKIX type and a string indicating the + identity and may also contain a "validation_info" value for the + selected validation method. + + csr (mandatory): + The PKCS#10 CSR. + + notification_endpoint (optional): + A URL that the CA can contact with status notifications" + + An example issuance request is shown below: + + + + + + + + +Rescorla Expires June 14, 2014 [Page 9] + +Internet-Draft ACIP December 2013 + + + { + "validation_method" : "https", + "identities" : [ + { + "type" : "dnsNAme", + "www1.example.com" + }, + { + "type" : "dnsNAme", + "www2.example.com" + } + ], + "csr" : "", + "notification_endpoint" : + "http://status.example.com/acip-notification" + } + + The CA responds to a successful issuance request with a message + indicating acknowledgement (type "issuance_response"), and containing + the following contents. + + + challenges (optional) + If the selected validation method requires a challenge, then the + CA shall include the challenge data in the challenges value. The + data is a list of values containing an identity field from the + request. More than one challenge may be provided for a given + identity, which means that the CH must comply with all of them. + [TODO: Do we want to allow multiple simultaneous types of + challenge? If so, we may need to tweak the negotiation to make + the client offer and then add a type in this field. + + status_url (mandatory) + A URL which the CH can contact to find the status of the request. + This MUST contain a large enough random component to avoid + guessing (minumum 80 bits of entropy). + + certificate_url (mandatory) + A URL where the eventual certificate will live. At any point this + MUST contain the most recent certificate, thus enabling short- + lived certificates. This need not be secret. + + An example issuance response is shown below: + + + + + + + + +Rescorla Expires June 14, 2014 [Page 10] + +Internet-Draft ACIP December 2013 + + + { + "challenges" : [ + { + "identity" : { + "type" : "dnsNAme", + "www1.example.com" + }, + "value" : { + "path" : "", + "value" : "", + }, + }, + { + "identity" : { + "type" : "dnsNAme", + "www2.example.com" + }, + "value" : { + "path" : "", + "value" : "", + } + } + ], + "status_url":"https://ca.example.com/status/", + "certificate_url:"https://ca.example.com/cert/1234" + +5.2.2. HTTPS with SNI + + [TODO] + +5.2.3. DNS + +5.2.4. DANE + +5.3. Certificate Issuance + + Once the certificate is issued, the CA places it at the location + indicated by the "certificate_url" it previously provided in its + request to the issuance response. A HTTP GET to that location + produces a JSON structure of the following form. + + + certificate chain (mandatory): + A list of certificates in the order specified by TLS [RFC5246] + (i.e., with each certificate certifying the next one and the end- + entity certificate as the last one.). The CA SHOULD include the + intermediate certificates that it believes a relying party would + use,but ultimately it is the CH's job to sort this out. + + + +Rescorla Expires June 14, 2014 [Page 11] + +Internet-Draft ACIP December 2013 + + + + next_issuance (mandatory): + The time that the CA expects to automatically issue a replacement + for the certificate, to be used for the CH to determine when to + refresh. + +5.4. Requesting Revocation + + [TODO(ekr@rtfm.com): Should we refactor this and issuance to have + the common elements in one place.] Under some circumstances, ACIP- + issued certificates may need to be revoked. While conventional + mechanisms (OCSP, CRLs, etc.) can be used for disseminating status + information, an automatic mechanism is needed for informing the CA + that the certificate should be revoked. As with certificate + issuance, ACIP provides a generic framework for this request, which + then must be validated by one or more of several validation + mechanisms. + + The general form of the revocation request is: + + + validation_method (mandatory): + The revocation validation method the CH has selected. + + certificates (mandatory): + A list of the certificates to revoke. Each entry in the list has + a "certificate" field and may also have a "validation_info" field + if required by the validation method. If multiple certificates + have been provided, they MUST all have the same identities. + + For example: + + { + "validation_method" : "shared_secret", + "certificates" : [ + "certificate" : "", + "validation_info" : "" + ] + } + + The CA responds to a revocation request either with an error or with + an indication of what the CH needs to do in order to have the + certificate revoked (type "revocation_response"), containing the + following items: + + + + + + + +Rescorla Expires June 14, 2014 [Page 12] + +Internet-Draft ACIP December 2013 + + + + challenges (optional) + If the selected validation method requires a challenge, then the + CA shall include the challenge data in the challenges value. The + data is a list of values containing an identity field from the + request. More than one challenge may be provided for a given + identity, which means that the CH must comply with all of them. + + status_url (mandatory) + A URL which the CH can contact to find the status of the request. + This MUST contain a large enough random component to avoid + guessing (minumum 80 bits of entropy). + +5.5. Validation Methods + + This section describes mechanisms for validating requests (both + issuance and revocation). In practice, some of these may only be + useful for validating issuance or revocation (noted below where + known) but because there is significant overlap, and this is somewhat + subject to CA policy, we simply describe validation requests. + +5.5.1. Simple HTTPS + + The "Simple HTTPS" validation method consists simply of verifying + that the operator of the server has authority to insert a given data + value at a specific location in the /.well-known directory of the + target Web server, specifically under "/.well-known/acip-verify". + [TODO: Registration needed for this?]. The challenge information is + a JSON [TODO: What if the server for some reason has an existing + cert? SNI is a clumsy discrimination mechanism here...] dictionary + with two values: + + + path (mandatory): + The location in /.well-known/acip-verify to write the challenge + value. + + value (mandatory): + The value to write. + + expected_certificate (mandatory): + The certificate which MUST be used by the CH server to + authenticate the connection. + + For instance: + + + + + + +Rescorla Expires June 14, 2014 [Page 13] + +Internet-Draft ACIP December 2013 + + + { + "path" : "abcdef", + "value" : "12345", + "expected_key" : "" + } + + In this example, the CH MUST write the string "12345" to the file + /well-known/acip-verify/12345. + + The CH server MUST use the a certificate which matches the + "expected_key" provided by the client. If the server has no such + certificate, it MUST signal an error to the operator. In general, + the expected_key will be chosen to match one of two values: + + o The key in the CSR. + o Some previous key that the operator knows the CH previously used. + + [TODO: Do we want to force both of these? if so we will need to + discriminate via SNI. We could also require that the challenge be + signed for POP...] + +5.5.2. Digital Signature + + The digital signature validation request involves the CH signing a + message requesting a service from a CA. This message MAY involve a + challenge from the CA, but need not (for instance, a signed request + for revocation need not involve a challenge, as the requester clearly + had control of the key at some point and therefore a request for + revocation seems in order. + + [TODO: RLB, please provide the JWT text here.] + +5.5.3. Secret Token + + In some cases, the CA and the CH may wish to establish a shared + secret which can be used non-cryptographically to authenticate the CH + to the CA. The most obvious example is that the CA may want to issue + the CH a "revocation token" which it can use to authenticate + revocation requests. This value could be comparatively low entropy + if it is used solely to revoke the certificate. + +5.6. Errors + + Any request from the CH to the CA can potentially generate an error + (message type = "error"). The error message contents are: + + + + + + +Rescorla Expires June 14, 2014 [Page 14] + +Internet-Draft ACIP December 2013 + + + + error_code (mandatory): + An IANA-defined error code. + + error_reason (optional): + A free-form text string providing further information. The + error_reason field SHOULD be populated. + + For example: + + { + "error_code" : "invalid_key", + "error_reason" : "RSA key less than 2048 bits provided." + } + + + The following error codes are defined. + + + invalid_key: + The provided key was invalid for some reason. + + invalid_csr: + The provided CSR was invalid for some reason other than the key, + e.g., because the signature is broken. + + invalid_validation_method: + The authentication method specified is unknown or unacceptable. + + invalid_identity: + The requested identity is invalid for some reason, e.g., because + it is improperly formatted. + + other_error: + There is some other error not covered by the above. The + "error_reason" field MUST be populated for this error, as it is + the only way for the CH to get information about what happened. + +5.7. Status Publication + + CAs are encouraged to provide a status URL so that CHs can determine + the status of a given request. A GET to the status URL returns a + status document consisting of: + + + + + + + + +Rescorla Expires June 14, 2014 [Page 15] + +Internet-Draft ACIP December 2013 + + + + request_status (mandatory): + One of the following values: + * "pending": the request is pending. + * "complete": the request has successfully completed. + * "failed": the request has failed + + error (optional): + If the request failed, the CA SHOULD supply the error information + that would have been published in an error. + + log (optional): + A free-text field consisting of logging information that might be + helpful to the CH. + +5.8. HTTPS Binding + + While the protocol defined in this document could in principle be + carried over any transport, this document defines a single transport + over HTTPS [RFC2818]. + + An CA has a single URL which it uses as its main ACIP endpoint. As + discussed in Section 4, the CH knows this URL via some out-of-band + mechanism. The CA responds to both GET and POST requests at this URL + as described below. All messages have the type "application/json" + [REF]. + + The response to any GET request is the policy document Section 5.1. + The GET request SHOULD not contain any HTTP parameters or body and in + any case these MUST be ignored. + + The CH issues instructions to the CA using HTTP POST. The body of + the POST message contains an ACIP message as specified in + Section 5.2. Again, there SHOULD be no query arguments. If the + message is not well-formed, than an HTTP 400 "bad request" error + SHOULD be generated. If the message is well-formed, then the CA + SHOULD attempt to process it and return any errors in the response + body with an HTTP 200 success code, rather than as an HTTP error. + + In addition to the above, the CA is expected to maintain a number of + informational URLs for a given certificate or certificate request + (e.g., "status_url" and "certificate_url") however these are + orthogonal to the protocol used for interacting with the CA (since + the client just does GETs to them) and therefore could in principle + be used even if some other protocol were used to interact with the + CA. + + + + + +Rescorla Expires June 14, 2014 [Page 16] + +Internet-Draft ACIP December 2013 + + +6. Security Considerations + + o CAs should bind the challenge to the key to prevent referrals... + + +7. IANA Considerations + + IANA [SHALL create/has created] an ACIP Validation Protocol + specification registry. The values are ASCII strings [REF: 8859-1?] + and the registry is initially populated with values as below. The + registration policy is Specification Required [RFC5226]. + + +-------------------+---------------+ + | Code Point | Description | + +-------------------+---------------+ + | simple-https | Section 5.5.1 | + | https-sni | Section 5.2.2 | + | digital-signature | Section 5.5.2 | + | secret-token | Section 5.5.3 | + +-------------------+---------------+ + + IANA [SHALL create/has created] an ACIP Error registry. The values + are ASCII strings [REF: 8859-1?] and the registry is initially + populated with values from Section 5.6. The registration policy is + Standards Action [RFC5226]. The + + +8. Acknowledgements + + +9. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2314] Kaliski, B., "PKCS #10: Certification Request Syntax + Version 1.5", RFC 2314, March 1998. + + [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. + + [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an + IANA Considerations Section in RFCs", BCP 26, RFC 5226, + May 2008. + + [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security + (TLS) Protocol Version 1.2", RFC 5246, August 2008. + + + + + +Rescorla Expires June 14, 2014 [Page 17] + +Internet-Draft ACIP December 2013 + + +Author's Address + + Eric Rescorla + Mozilla + 2064 Edgewood Drive + Palo Alto, CA 94303 + USA + + Phone: +1 650 678 2350 + Email: ekr@rtfm.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Rescorla Expires June 14, 2014 [Page 18] + diff --git a/acip/draft-rescorla-acip.xml b/acip/draft-rescorla-acip.xml new file mode 100644 index 000000000..c678ce2bb --- /dev/null +++ b/acip/draft-rescorla-acip.xml @@ -0,0 +1,869 @@ + + + + + + +]> + + + + + + + + + + + + + Automatic Certificate Issuance Protocol (ACIP) + + + Mozilla + +
+ + 2064 Edgewood Drive + + Palo Alto + + CA + + 94303 + + USA + + + +1 650 678 2350 + + ekr@rtfm.com + + +
+ + + + + SEC + + + + [TODO] + + + + + + +
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119. +
+ +
+ + Existing Web PKI certificate authorities tend to run on + a set of ad hoc protocols for certificate issuance and + identity verification. A typical user experience is something + like: + + + + Generate a PKCS#10 Certificate Signing Request (CSR). + Cut-and-paste the CSR into a CA web page. + Prove ownership of the domain by one of the following methods: + + Put a CA-provided challenge at a specific place on the web server + + Put a CA-challenge at a DNS location corresponding to the target domain. + + Receive CA challenge at an (allegedly) administrator controlled e-mail address corresponding to the domain and then respond to it on the CA's web page. + + + Download the issued certificate and install it on their Web Server. + + + + With the exception of the CSR itself and the certificates that are + issued, these are all completely ad hoc procedures and are accomplished + by getting the user to follow instructions from the CA rather than by + published protocols. In many cases, the instructions are difficult to + follow and cause significant confusion. Even in the best case, the + lack of published, standardized mechanisms presents an obstacle to + the wide deployment of certificate-using systems. + + + This document describes a framework for automating the issuance + and domain validation procedure, thus enabling the construction of + certificate-holding entities which can obtain certificates without + user interaction. It is hoped that this will radically increase + the level of deployment of certificate-using systems and specifically + of HTTPS. + +
+
+ + It's easiest to understand ACIP in the context of certificates + for Web sites (HTTPS ). In that case, the + server is intended to speak for one or more domains and the process of + certificate issuance is intended to verify that the server actually + speaks for the domain. In the case of "Domain Validation" (DV) certificates, + the server validation process merely verifies that the requester + has effective control of the domain but does not really attempt to + verify their real-world identity. (This is as opposed to "Extended + Validation" (EV) certificates where the process is intended to also verify + the real-world identity of the requester.) + + + When an operator deploys a current HTTPS server, it generally prompts + him to generate a self-signed certificate. + When an operator deploys an ACIP-compatible server, the experience would + be something like this: + + + + The server prompts the operator for the intended domain name(s) that the + server is to stand for. + The server presents the operator with a list of CAs which it + could get a certificate from. The server might prompt the operator + for payment information at this point. + Once the operator has selected a CA, tells the operator that he will have a certificate shortly. + In the background, the server contacts the CA, sends a CSR, and + engages in the validation procedure. + Once the CA is satisfied, the certificate is issued and the + server automatically downloads and installs it, potentially notifying + the operator via e-mail, SMS, etc. + The server periodically contacts the CA to get updated certificates, + stapled OCSP responses, or whatever else would be required to keep + the server functional and its credentials up-to-date. + + + + The overall idea is that it's nearly as easy to deploy with a valid + certificate as a self-signed certificate and that once the operator + has done so, the process is self-sustaining with minimal manual + intervention. + +
+ + While ACIP is explicitly designed for HTTPS server certificates, + it is in general usable in any situation where the certificate + subject is automatically verifiable. In principle, then, it + could be used with personal addresses (XMPP or e-mail) if there + is some straightforward way of responding to the validation + procedure, e.g., by having the client automatically + detect and respond to validation answerback queries. + +
+
+
+ + We assume that that an ACIP-compatible agent which wishes + to get a certificate (currently, the "Certificate Holder" (CH)) + starts with a list of ACIP-compliant CAs represented as URLs. + From there, the protocol proceeds as shown below. Note + that we have taken some liberties with messages from the + CA to the CH: everything is done over HTTPS, so messages + from the CA likely require either polling by the CH or + that the CH have some accessible endpoint for the CA to + talk to. + +
+
+ + + <-------- Challenge + + Response --------> + + <-------- Certificate + ]]> +
+ + Initially, the CH contacts the CA and retrieves the CA's + capabilities. This likely includes information like + the validation types (e-mail, DNS, Web, etc.) that the + CA supports, whether it charges, the types of keys it will + issue for, how often the certificates + need to be reissued, etc. The CH might contact multiple + CAs to find one with the best policies before it actually + requests a certificate. + + + Once the CH (or more likely the operator) has selected a CA, + the CH generates a key pair and contacts the CA with + signing request. He will also indicate (probably separately), + the identity he wants the certificate issued for and which + validation method he wants the CA to use. He might + also provide a URL which the CA can use to indicate that + the certificate is ready. + + + Depending on the validation method, the CA will then supply + a challenge to the CH. This might happen immediately, as + in the case of HTTPS validation (section XXX) or might + happen later, as in the case of e-mail validation (section YYY). + The CH responds to the challenge, e.g., by putting it somewhere + in /.well-known on their server. + + + Once the CA has validated the CH's identity, it issues the + certificate. The CH might either poll the CA for readiness + or the CH can provide a URL for the CA to contact when + the certificate is ready. In either case, once the CH + has the certificate, it installs it. + +
+
+
+ + + <-------- Certificate + ]]> +
+ + Because certificates eventually expire, there must be some + for the CH to get a new certificate. This need not involve + a new authentication transaction--and if short-lived + certificates are used, then it generally will not--but + does require getting new bits to the CH. + In general, the CA will just generate new certificates + periodically and publish them at some deterministic + URL that the CH can retrieve them at. Where a new + authentication transaction is required, we just repeat + the flow of + +
+
+ +
+ + This section describes the relevant protocol elements. + For explanatory reasons, we have chosen to describe + these as if they were JSON structures. Eventually + we may decide on some more fixed binary encoding, + but it's easier to explain with JSON and we may + eventually just use JSON in any cse. + + +
+ + Every ACIP-compliant CA will post a policy document in + some public location. This document MUST be hosted over + HTTPS so that it can be validated. + The URL is assumed to be known to the CH. + + + The policy document contains the following values: + + + + + A list of validation methods for issuance that the CA supports. + + + A list of validation methods for revocation that the CA supports. + + + A list of signature algorithms that the CA supports. [TODO: which registry] + + A list of the key types that the CA allows the CH to have, structured + as an algorithm and an (optional min/max} [TODO: which registry. + + + A list of the status mechanisms that the CA supports (OCSP, etc.) + + + The base64 [REF] encoding of the certificate which will + be used to authorize the CH's key. If the CA has multiple + certificates signed by some intermediate, it will include + the intermediate. The idea here is to provide some idea + of what the final certificate will look like. + + + The minimum lifetime of certificates issued by the CA in seconds + so that the CH knows how often it is likely to have to refresh. + + + + + An example policy document might look like the one below. + +
+ +
+ + Note that one important consideration is that it be possible for + add new policy values. Since these are just information to the + CH, if they are unknown they can be ignored, but may of course + cause issuance failure. [TODO: Add some support for payment.] + [TODO: Add other types.] + +
+ +
+ + All ACIP protocol messages other than the policy document are + carried in a generic wrapper. + + + + + The message type, either "error" or one of the messages + described below. + + + The message itself. In the JSON encoding here, just the + JSON structure shown below. + + + + An example message is shown below. + +
+ ", + "notification_endpoint" : + "http://status.example.com/acip-notification" + } + } + ]]> +
+
+ + The issuance request (message type "issuance_request") is relatively simple: + + + + + The validation method the CH has selected. + + + A list of the identities that the CH wants issuance for. + Each identity is a pair of PKIX type and a string indicating + the identity and may also contain a "validation_info" + value for the selected validation method. + + + The PKCS#10 CSR. + + + A URL that the CA can contact with status notifications" + + + + An example issuance request is shown below: + +
+ ", + "notification_endpoint" : + "http://status.example.com/acip-notification" + } + ]]> +
+ + + The CA responds to a successful issuance request with a message + indicating acknowledgement (type "issuance_response"), + and containing the following contents. + + + + + If the selected validation method requires a challenge, then + the CA shall include the challenge data in the challenges + value. The data is a list of values containing an identity + field from the request. More than one challenge may be + provided for a given identity, which means that the CH + must comply with all of them. [TODO: Do we want to allow + multiple simultaneous types of challenge? If so, we may + need to tweak the negotiation to make the client offer + and then add a type in this field. + + + A URL which the CH can contact to find the status of the + request. This MUST contain a large enough random component + to avoid guessing (minumum 80 bits of entropy). + + + A URL where the eventual certificate will live. At any + point this MUST contain the most recent certificate, thus + enabling short-lived certificates. This need not be secret. + + + + An example issuance response is shown below: + +
+ ", + "value" : "", + }, + }, + { + "identity" : { + "type" : "dnsNAme", + "www2.example.com" + }, + "value" : { + "path" : "", + "value" : "", + } + } + ], + "status_url":"https://ca.example.com/status/", + "certificate_url:"https://ca.example.com/cert/1234" + ]]> +
+ +
+
+ [TODO] +
+ +
+
+
+ +
+ + Once the certificate is issued, the CA places it at the + location indicated by the "certificate_url" it previously + provided in its request to the issuance response. A + HTTP GET to that location produces a JSON structure + of the following form. + + + + + A list of certificates in the order specified by + TLS + (i.e., with each certificate certifying the next one and the + end-entity certificate as the last one.). The + CA SHOULD include the intermediate certificates + that it believes a relying party would use,but + ultimately it is the CH's job to sort this out. + + + The time that the CA expects to automatically + issue a replacement for the certificate, to be used + for the CH to determine when to refresh. + + +
+ +
+ + [TODO(ekr@rtfm.com): Should we refactor this and issuance to + have the common elements in one place.] + Under some circumstances, ACIP-issued certificates may need to + be revoked. While conventional mechanisms (OCSP, CRLs, etc.) + can be used for disseminating status information, an automatic + mechanism is needed for informing the CA that the certificate + should be revoked. As with certificate issuance, ACIP provides + a generic framework for this request, which then must be validated + by one or more of several validation mechanisms. + + + The general form of the revocation request is: + + + + + The revocation validation method the CH has selected. + + + A list of the certificates to revoke. + Each entry in the list has a "certificate" field and + may also have a "validation_info" field if required + by the validation method. + If multiple certificates + have been provided, they MUST all have the same identities. + + + + + For example: + +
+ ", + "validation_info" : "" + ] + } + ]]> +
+ + The CA responds to a revocation request either with an error + or with an indication of what the CH needs to do in order to + have the certificate revoked (type "revocation_response"), + containing the following items: + + + + + If the selected validation method requires a challenge, then + the CA shall include the challenge data in the challenges + value. The data is a list of values containing an identity + field from the request. More than one challenge may be + provided for a given identity, which means that the CH + must comply with all of them. + + + A URL which the CH can contact to find the status of the + request. This MUST contain a large enough random component + to avoid guessing (minumum 80 bits of entropy). + + +
+ +
+ + This section describes mechanisms for validating requests (both + issuance and revocation). In practice, some of these may only + be useful for validating issuance or revocation (noted below + where known) but because there is significant overlap, + and this is somewhat subject to CA policy, we simply describe + validation requests. + +
+ + The "Simple HTTPS" validation method consists simply of verifying + that the operator of the server has authority to insert a given + data value at a specific location in the /.well-known directory + of the target Web server, specifically under "/.well-known/acip-verify". + [TODO: Registration needed for this?]. The challenge information is a JSON + [TODO: What if the server for some reason has an existing cert? + SNI is a clumsy discrimination mechanism here...] + dictionary with two values: + + + + + The location in /.well-known/acip-verify to write the challenge value. + + + The value to write. + + + The certificate which MUST be used by the CH server to authenticate the connection. + + + + For instance: + +
+ " + } + ]]> +
+ + In this example, the CH MUST write the string "12345" to the file + /well-known/acip-verify/12345. + + + The CH server MUST use the a certificate which matches the + "expected_key" provided by the client. If the server has + no such certificate, it MUST signal an error to the operator. + In general, the expected_key will be chosen to match one of two + values: + + + + The key in the CSR. + Some previous key that the operator knows the CH previously used. + + + + [TODO: Do we want to force both of these? if so we will need to discriminate + via SNI. We could also require that the challenge be signed for POP...] + +
+
+ + The digital signature validation request involves the CH + signing a message requesting a service from a CA. This + message MAY involve a challenge from the CA, but need not + (for instance, a signed request for revocation need not + involve a challenge, as the requester clearly had + control of the key at some point and therefore a request + for revocation seems in order. + + + [TODO: RLB, please provide the JWT text here.] + +
+
+ + In some cases, the CA and the CH may wish to establish a + shared secret which can be used non-cryptographically to + authenticate the CH to the CA. The most obvious example is + that the CA may want to issue the CH a "revocation token" + which it can use to authenticate revocation requests. + This value could be comparatively low entropy if it is + used solely to revoke the certificate. + +
+
+
+ + Any request from the CH to the CA can potentially generate an error + (message type = "error"). The error message contents are: + + + + + An IANA-defined error code. + + + A free-form text string providing further information. The + error_reason field SHOULD be populated. + + + + For example: + + +
+ + +
+ + + The following error codes are defined. + + + + + The provided key was invalid for some reason. + + + The provided CSR was invalid for some reason other than the key, + e.g., because the signature is broken. + + + The authentication method specified is unknown or unacceptable. + + + + The requested identity is invalid for some reason, e.g., because + it is improperly formatted. + + + There is some other error not covered by the above. The + "error_reason" field MUST be populated for this error, as + it is the only way for the CH to get information about what + happened. + + +
+
+ + CAs are encouraged to provide a status URL so that CHs can determine + the status of a given request. A GET to the status URL returns a + status document consisting of: + + + + + One of the following values: + + + "pending": the request is pending. + "complete": the request has successfully completed. + "failed": the request has failed + + + + + If the request failed, the CA SHOULD supply the error information + that would have been published in an error. + + + A free-text field consisting of logging information that might be + helpful to the CH. + + +
+
+ + While the protocol defined in this document could in principle be + carried over any transport, this document defines a single transport + over HTTPS . + + + An CA has a single URL which it uses as its main + ACIP endpoint. As discussed in , + the CH knows this URL via some out-of-band mechanism. The + CA responds to both GET and POST requests at this URL + as described below. All messages have the type "application/json" [REF]. + + + The response to any GET request is the policy document . The GET request SHOULD not contain any HTTP parameters or body and + in any case these MUST be ignored. + + + The CH issues instructions to the CA using HTTP POST. The + body of the POST message contains an ACIP message as + specified in . Again, there + SHOULD be no query arguments. If the message is not well-formed, + than an HTTP 400 "bad request" error SHOULD be generated. If the + message is well-formed, then the CA SHOULD attempt to process + it and return any errors in the response body with an HTTP 200 + success code, rather than as an HTTP error. + + + In addition to the above, the CA is expected to maintain a number + of informational URLs for a given certificate or certificate request + (e.g., "status_url" and "certificate_url") however these are + orthogonal to the protocol used for interacting with the CA + (since the client just does GETs to them) and therefore could + in principle be used even if some other protocol were used + to interact with the CA. + +
+
+
+ + + CAs should bind the challenge to the key to prevent referrals... + + +
+ +
+ + IANA [SHALL create/has created] an ACIP Validation Protocol specification + registry. The values are ASCII strings [REF: 8859-1?] and the registry + is initially populated with values as below. The registration policy + is Specification Required . + + + Code Point + Description + simple-https + + https-sni + + digital-signature + + secret-token + + + + + IANA [SHALL create/has created] an ACIP Error registry. + The values are ASCII strings [REF: 8859-1?] and the registry + is initially populated with values from . + The registration policy + is Standards Action . The + +
+ +
+
+ + + + &RFC2119; + &RFC2314; + &RFC2818; + &RFC5226; + &RFC5246; + + + + +