diff --git a/acip/draft-rescorla-acip.txt b/acip/draft-rescorla-acip.txt deleted file mode 100644 index 575efb615..000000000 --- a/acip/draft-rescorla-acip.txt +++ /dev/null @@ -1,1008 +0,0 @@ - - - -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 deleted file mode 100644 index c678ce2bb..000000000 --- a/acip/draft-rescorla-acip.xml +++ /dev/null @@ -1,869 +0,0 @@ - - - - - - -]> - - - - - - - - - - - - - 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; - - - - -