mirror of
https://github.com/certbot/certbot.git
synced 2026-01-26 07:41:33 +03:00
267 lines
27 KiB
HTML
267 lines
27 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
|
|
<head>
|
|
<meta http-equiv="Content-type" content="text/html; charset=utf-8" />
|
|
<meta http-equiv="Content-Language" content="en-us" />
|
|
<title>/26$6</title>
|
|
</head>
|
|
<body><b>ABSTRACT</b><br
|
|
/><br
|
|
/>This protocol exists to facilitate the activation of secure TLS encryption on all Internet servers to which it is applicable, in a manner compatible with existing deployed client bases, but without the need for the expert human configuration that has limited the use of TLS to date. The protocol provides transmission and validation of certification requests, and the issuance of digital certificates, with as little human intervention as possible.<br
|
|
/><br
|
|
/><br
|
|
/><b>INTRODUCTION</b><br
|
|
/><br
|
|
/>The Trustify (aka Chococlate) protocol is used between a <b>client</b>, which is a software package on an Internet-connected host that is or will be used to operate a Web server or other TLS service, and a <b>server</b>, which is a certification service provided by a certificate authority.<br
|
|
/><br
|
|
/>The protocol is implemented as a series of Protocol Buffers messages which are serialized and transported as HTTP POST request and response bodies relative to an HTTPS URI published by the server. Currently, each client to server message is a new HTTP POST and each server reply is a new response body. Hence, the client and server alternate sending messages; asynchronous notification of changes in server state do not occur, but the client can be instructed to poll periodically while the server is working. Full specification of the Trustify message format is in the Messages section below.<br
|
|
/><br
|
|
/>The client must verify the server's own certificate when making each HTTPS connection. If the client cannot establish a secure connection to the server, the client SHOULD abort the session without any further communication.<br
|
|
/><br
|
|
/>Because avoiding misissuance of certificates is a fundamental priority, the server is able to abort sessions at any time for a wide variety of reasons, declining any further communication about an abandoned session.<br
|
|
/><br
|
|
/><b>IDENTIFYING AVAILABLE TRUSTIFY SERVERS</b><br
|
|
/><br
|
|
/>The first step for a Trustify client is to identify the currently operating and available Trustify servers that correspond to CAs issuing certificates through the protocol. Clients contain an HTTPS URL that always referrs to a fresh client list. For reliability purposes, if the URL cannot be fetched, clients may refer to a previously cached copy of the list.<br
|
|
/><br
|
|
/>The Trustify Server List will contain the following data:<br
|
|
/><br
|
|
/>[Server name string, server URL, <optional> [policy string1, policy string 2,..]]<br
|
|
/><br
|
|
/>The Server name string is a UTF-8 string containing an English readable name (possibly followed by a native name in another alphabet) of the CA. The server URL is an HTTPS endpoint that responds to the Trustify protocol as documented below. The policy strings are an optional list of parameters that may at some point express relevant comparison points between multiple CAs. The semantics of policy fields will be specified by the Trustify governance foundation.<br
|
|
/><br
|
|
/><b>SESSIONS</b><br
|
|
/><br
|
|
/>Trustify sessions are distinguished by a random session identifier which is issued by the server in its very first response to a new client connection. The session identifier must then be mentioned in all communications in either direction in order to associate requests and responses with a particular transaction. Omitting the session identifier is treated as a request to begin a new session, while messages containing an unrecognized or stale session identifier are rejected.<br
|
|
/><br
|
|
/>The session identifier is an ephemeral authenticator private to the client and server. An entity that knows the session identifier is able to make requests to the server related to the session, including erroneous requests that will cause the session to be terminated. Session identifiers from old, inactive sessions are explicitly marked invalid and no further use can be made of them.<br
|
|
/><br
|
|
/>The goal of a session is the issuance of a new digital certificate. The client must already possess a subject public key and a list of requested subject host names. The client begins the protocol with the goal of obtaining a certificate issued by the server, associating the public key with each subject name.<br
|
|
/><br
|
|
/><b>MESSAGE</b><br
|
|
/><br
|
|
/>The Trusitfy message object contains a version ID and a session ID. It also contains exactly one of the following specific message objects (except for challenge and completedchallenge):<br
|
|
/><br
|
|
/>request [type SigningRequest]: sent exactly once by the client at the beginning of a session in order to request a certificate. The contents indicate the details of the certificate that is being requested in the current session.<br
|
|
/><br
|
|
/>failure [type Failure]: sent by the client or the server to indicate a reason why the session cannot continue. All failure messages are fatal and result in the server marking the session as expired, so that no further activity may occur. (If a client sends a message related to an expired session, the server will respond with a failure message indicating that the session is expired.)<br
|
|
/><br
|
|
/>proceed [type Proceed]: sent by the server to request the client to poll again on the current session after a specified time delay. Normally used when the server believes that it is in the process of testing whether challenges have been satisfied or in the process of issuing the requested certificate.<br
|
|
/>Note: Protocol also specifies the client can send this message after a polling period.<br
|
|
/><br
|
|
/>challenge [type Challenge]: sent by the server to announce challenges for the first time or to tell the client whether the server believes that the client has successfully completed a subset of the previously issued challenges.<br
|
|
/><br
|
|
/>completedchallenge [type Challenge]: sent by the client to announce that the client believes it has successfully completed a challenge.<br
|
|
/><br
|
|
/>success [type Success]: sent by the server to issue the requested certificate.<br
|
|
/><br
|
|
/><b>SEQUENCE OF COMMUNICATIONS</b><br
|
|
/><br
|
|
/><b><i>TODO</i></b>: Document difference between challenge types that call for proceed message and challenge types that call for completedchallenge message.<br
|
|
/><br
|
|
/>Initial request<br
|
|
/>At the start of communications:<br
|
|
/><ul><li>1. The client sends a <b>request</b> message, which includes a signing request.</li
|
|
><li>2. The server issues a new session ID, which is included with all subsequent messages sent in either direction.</li
|
|
><li>3. The server validates the request. If it is known to be invalid or unacceptable for any reason, the server sends a failure message and aborts the protocol.<br/><br
|
|
/></li></ul
|
|
>Server challenge or certificate issuance<br
|
|
/>In response to the <b>request</b> message:<br
|
|
/><ul><li>4. Otherwise, in accordance with its policy, the server sends a <b>challenge</b> or <b>success</b> message. (The normal case is a <b>challenge</b> message because the server typically requires proof from the client that the client is authorized to obtain the requested certificate.)</li
|
|
><li>5. If the client receives a <b>challenge</b> message, it notes the challenges that it is expected to complete. The client then attempts to complete each specified challenge.</li
|
|
><li>6. When the client believes that it has completed a challenge, it can send a <b>completedchallenge</b> message updating the server on its progress. If the client believes that it is unable to complete a challenge, it can send a failure message admitting failure, which will result in the termination of the session.<br/><br
|
|
/></li></ul
|
|
>Server response to challenge progress<br
|
|
/>In response to the client-side <b>completedchallenge</b> or <b>proceed</b> message:<br
|
|
/><ul><li>7. If the server observes or agrees that all challenges issued in the session have been completed, it may issue the certificate and send a <b>success</b> message. This terminates the session.</li
|
|
><li>8. If the server believes that more time is required for certificate issuance or for challenge verification, it may send a <b>proceed</b> message asking the client to poll again after a specified time interval. The client should poll after this interval by sending completedchallenge (if it has new successes to claim) or proceed (if not). [Return to step 7.]</li
|
|
><li>9. If the server believes that one or more challenges have still not been completed, it may send a <b>challenge</b> message indicating the status of the challenges whose completeness has or has not been verified. [Return to step 5.]</li
|
|
><li>10. If the server believes that more challenges should be completed, it may send a new <b>challenge</b> message presenting the additional challenges. [Return to step 5.]</li
|
|
><li>11. If the server believes that too much time has elapsed or that some challenge was abandoned or has become impossible to satisfy, it can send a <b>failure</b> message. This terminates the session.<br/><br
|
|
/></li></ul
|
|
><b>VERIFICATION CHALLENGES</b><br
|
|
/><br
|
|
/>During the course of a session, the Trustify server presents the client with one or more <b>challenges</b>, which are messages specifying tasks that must be completed to verify the preconditions of issuance for the certificate(s) that the client has requested. Challenges are an abstraction layer to allow the Trustify protocol to be enhanced and expanded over time.<br
|
|
/><br
|
|
/>Several challenges may be presented at once, but further or additional challenges may be presented after previous sets, possibly as a result of information that the server obtained while verfiying the earlier challenges.<br
|
|
/><br
|
|
/>Clients may decide to meet all of the outstanding challenges at once, or may decide to send responses to the challenges one at a time. The semantic relationship between the outstanding challenges may be conjunctive (all challenges must eventually be met before issuance), disjunctive (only one or a subset of challenges must be met), or variable (the set of challenges that are required depends on the manner in which the earlier ones are completed)<br
|
|
/><br
|
|
/>As a matter of protocol synchronization, there are two subtypes of challenges: those where completion of the challenge is signalled by the client and then verified by the server (such as the DVSNI challenge described below, which requires the client to configure a TLS server in a particular way) and those where completion of the challenge is identified and verified solely by the server (such as a challenge involving a payment or other organizational validation for a high-value domain).<br
|
|
/><br
|
|
/><b>DVSNI Challenges:</b><br
|
|
/><br
|
|
/>DVSNI challenges are the fundamental method employed by the Trustify protocol to ensure that clients control the DNS names for which they are requesting certificates. It is intended to be more automatable (and in some cases, more secure) than the email receipt verification that is commonly used by DV CAs, and categorically more secure than the HTTP nonce deployment verification used by some DV CAs.<br
|
|
/><br
|
|
/>DVSNI requires the client to demonstrate significant administrative control of the domain by not only changing responses from an HTTP server, but by altering the TLS configuration of an HTTPS server to answer specially crafted SNI (Server Name Indication) requests. This shows that the client at least has adminitrative control of the DNS name's web server software, and probably has full adminstrative control of the servers that the DNS name points to.<br
|
|
/><br
|
|
/><b>DVSNI implementation specifics:</b><br
|
|
/><br
|
|
/><i> Shared parameters (chosen and sent by CA in the Challenge message):</i><br
|
|
/> ${nonce} A randomly chosen nonce hex output of digest of (random 32-bytes)<br
|
|
/> ${y} [:= E(r)] r is a random secret (32 bytes, raw binary)<br
|
|
/> ${ext} x.509 extension (format? e.g: 1.3.3.7)<br
|
|
/><br
|
|
/><i> Client setup:</i><br
|
|
/> Setup SNI for <i>${nonce}</i>.chocolate<br
|
|
/> Serve a self-signed certificate with (critical(?)) X.509 extension <i>${ext}</i>,<br
|
|
/> with value z = HMAC_r(s) || s (random s, r = D(${y}) (private key decrypt))<br
|
|
/><br
|
|
/><i> Chocolate Server (CA) verification steps:</i><br
|
|
/> Connect to domain.com, with TLS SNI ${nonce}.chocolate<br
|
|
/> Check certificate for X.509 extension ${ext}. Verify that value z is formed as expected.<br
|
|
/> <br
|
|
/> <i> Purpose:</i><br
|
|
/> Proves that whoever has access to the corresponding private key also has the ability<br
|
|
/> to serve (change configuration for) an arbitrary certificate for an arbitrary<br
|
|
/> subdomain under the desired domain name.<br
|
|
/><br
|
|
/> <i>Explanation:</i><br
|
|
/>Using ${nonce}.chocolate (instead of domain.com) allows a currently running web server to continue serving domain.com without interruption. (Note we still use the IP for domain.com when we connect to the server) It is of slight importance that the .chocolate TLD is not real; it may protect against elaborate attacks against domains like dyndns.com which would allow attackers to control nonce.dyndns.com. If such a domain were also hosted on a virtual hosting service/CDN with the same IP as the attacker, and which really did SNI, it would be important that .chocolate not be real.<br
|
|
/>We require the certificate to be modified to ensure that it is freshly generated for this purpose, and not just being served a wildcard certificate. We could do this several ways, but it is neccessary to tie this modification to control of the private key (hence the need for z) and to the current Chocolate request (hence the need for ${ext}). Otherwise, a "rogue CA" could receive a request from domain.com, forward it to a "real CA" with a different public key, and have the real domain.com carry out this challenge (which real CA would verify, and give rogue CA a signed cert for domain.com).<br
|
|
/><br
|
|
/> <i>Deviations from model:</i><br
|
|
/> SNI only allows multiplexing over the domain. Apache always has a default SNI page... even if you provide a completely wrong header. The real challenge happens with y and z.<br
|
|
/> Apache uses the first virtual server specifed on the ip/port to act as a default server if the SNI extension is specified by the client but does not match any of the virtual servers.<br
|
|
/><br
|
|
/><b>DVSNI Security Considerations:</b><br
|
|
/><br
|
|
/>Shared hosting environments with multiple DNS names pointed a single host and IP are a common situation on the modern Internet. We expect that the hosting provider managing these guest domains should take its own steps to prevent one from listening on port 443 in an unconstrained manner for the other guests' domains. If it does not, the DVSNI verification step will be unable to distinguish the owner of the domain from others who can listen on the domain's privileged ports, and, depending on what other verification steps are applicable, may issue certificates to these other parties.<br
|
|
/><br
|
|
/>Verification of control on TLS ports other than 443 (such as the TLS email serivces on ports 465, 993 and 995) in the presence of virtual hosting presents similar but possibly more serious challenges, since use of these ports on virtual private servers may be rarer, and policies about them more varied.<br
|
|
/><br
|
|
/><b>Proof-of-posession challenges:</b><br
|
|
/><br
|
|
/>The server MUST check whether there are pre-existing valid certificates for the requested DNS names by consulting Certificate Transparency logs and/or the EFF SSL Observatory. If such certificates exist, the server SHOULD NOT proceed unless it can ensure that issuance will not reduce the security of TLS services deployed with those existing certificates.<br
|
|
/><br
|
|
/>Traditional OV verification processes may be one way of achieving this, but it is recommended that a Proof of Possession challenge be offered as an alternative. This challenge type requires the client to sign a challenge nonce using the private key from one of the existing valid certificates for the DNS name in question.<br
|
|
/><br
|
|
/><br
|
|
/><b>Payment challenges:</b><br
|
|
/><br
|
|
/>In limited situations, it may be determined that traditional OV or EV processes are required for the issuance of ceriticates for high-value, high-traffic DNS names. In such cases a payment challenge may be used to facilitate the transition to the OV or EV process at the client end. The Trustify governance foundation may or may not decide to allow such challenges, but if it does they will be in limited circumstances, where the OV or EV process significant enhances the security of the domain in question, and not a common case for Trustify protocol execution.<br
|
|
/><br
|
|
/>If Payment challenges exist, they will simply contain a URL for a web page that can specify and accept the payment required.<br
|
|
/><br
|
|
/><br
|
|
/><b>FAILURE REASONS</b><br
|
|
/><br
|
|
/>Currently, the following reasons for the failure of a session are defined:<br
|
|
/><br
|
|
/><b>UnsupportedVersion</b>: the requested protocol version is not available.<br
|
|
/><b>AbandonedRequest</b>: the client has abandoned the session and is no longer requesting issuance of the certificate.<br
|
|
/><b>ServerOutage</b>: the service is temporarily unavailable.<br
|
|
/><b>ServerGone</b>: the service is permanently unavailable.<br
|
|
/><b>StaleRequest</b>: the request is expired as a result of its age, excessive delay in the client-server interaction, or because the request has previously failed for another reason.<br
|
|
/><b>BadSignature</b>: the digital signature used by the client to prove its possession of the private key corresponding to the subject public key is invalid.<br
|
|
/><b>BadCSR</b>: the certificate signing request sent by the client is invalid in some way.<br
|
|
/><b>BadRequest</b>: the subject public key, one or more subject host names, or some other aspect of the signing request is invalid.<br
|
|
/><b>NeedClientPuzzle</b>: as a denial-of-service mitigation measure, the server cannot accept the request without additional proof of work by the client.<br
|
|
/><b>CannotIssueThatName</b>: the issuance of a certificate for one or more of the subject host names is administratively prohibited.<br
|
|
/><b>ExistingCertificate</b>: a previous certificate for one or more of the subject host names is known to exist and the CA policy does not permit the automated issuance of a new one in response to the current request.<br
|
|
/><b>UnsafeKey</b>: the subject public key violates a CA policy or is known to be insecure.<br
|
|
/><b>ChallengeFailed</b>: the client's attempt to comply with a challenge was unsuccessful.<br
|
|
/><b>ChallengeTimeout</b>: the client did not appear to comply with a challenge within the required period of time.<br
|
|
/><br
|
|
/>A message of type Failure must contain one of these reasons, and may contain a URI with additional human-readable information about the reason for the failure of the request.<br
|
|
/><br
|
|
/><b>SECURITY CONSIDERATIONS</b><br
|
|
/><br
|
|
/>Because the intended application of this protocol causes valuable digital certificates to be issued automatically with no time delay and without human intervention, attackers are likely to be interested in trying to use this protocol to request certificates fraudulently. It should be possible to implement the protocol and verification steps in such a way that the system as a whole is more secure than some existing certificate authority verification processes.<br
|
|
/><br
|
|
/>Before issuing a certificate, the server needs to perform a large number of validation and policy enforcement steps which are outside the scope of this protocol. For example, the server SHOULD check that the RSA modulus of the submitted subject public key is >=2048 bits and that it is not on any weak RSA modulus blacklist. The server SHOULD check that no CAA records forbid it from issuing a certificate for this domain and that the subject domain is not a high-value domain for which automated certificate issuance should be prevented. The server SHOULD check whether there is any known existing valid certificate for the requested domain and determine under what conditions server policy permits the issuance of a new certificate with concurrent validity.<br
|
|
/><br
|
|
/>When using DVSNI validation, the server SHOULD perform the probe connection from multiple locations on the Internet to achieve geographic and network topology diversity to reduce the risk that an attacker performs a DNS or BGP attack to appear to control a particular web server.<br
|
|
/><br
|
|
/>The server SHOULD avoid passing unvalidated or unsanitized data from the client to any server code implemented in a non-bounds-checked language.<br
|
|
/><br
|
|
/>The server SHOULD use physical controls to isolate a machine capable of directly causing certificate issuance from the public Internet.<br
|
|
/><br
|
|
/>The server SHOULD attempt to detect fraudulent attempts to issue certificates.<br
|
|
/><br
|
|
/>The server SHOULD attempt to notify the owner of a site when a certificate was issued, and SHOULD memorialize the issuance publicly using a system such as Certificate Transparency.<br
|
|
/><br
|
|
/>The client SHOULD be encouraged to use best practices to increase the security of its TLS deployment using the new certificate, such as HSTS and DANE.<br
|
|
/><br
|
|
/>The server MUST securely generate random session IDs to prevent a malicious client from guessing a valid session ID. The server MUST cause sessions to terminate after a specified period of inactivity or after a fatal error, and prevent any further activity from occurring on a terminated session. After sending a single error message indicating why a session was terminated, the server SHOULD not convey any information to clients about why a particular session is nonexistent or inactive, including whether or not the specified session ever existed.<br
|
|
/><br
|
|
/>The above list of verification steps may not be exhaustive. Full policy guidelines on these questions will be maintained by the Trustify governance foundation.<br
|
|
/><br
|
|
/><b>MESSAGE DATA TYPES</b><br
|
|
/><br
|
|
/>SigningRequest:<br
|
|
/><br
|
|
/> message SigningRequest {<br
|
|
/> required int64 timestamp = 2;<br
|
|
/> required string recipient = 3;<br
|
|
/> required string csr = 4;<br
|
|
/> required bytes sig = 5;<br
|
|
/> optional string clientpuzzle = 6;<br
|
|
/> }<br
|
|
/><br
|
|
/>timestamp is the Unix timestamp when the request was made. (The server SHOULD verify that this is not significantly in the past or future relative to the time that the server received it.)<br
|
|
/><br
|
|
/>recipient is the URI of the service to which the client intended to submit the request.<br
|
|
/><br
|
|
/>csr is a PEM-encoded certificate signing request containing the subject public key and all subject names to which the request relates (using "\n" rather than "\r\n" as newline delimiter).<br
|
|
/><br
|
|
/>sig is an RSA signature over the preceding values using the private key that corresponds to the subject public key. <b><i>TODO</i></b>: describe how the signature is calculated.<br
|
|
/><br
|
|
/>clientpuzzle is a hashcash string that refers to the hostname of the server.<br
|
|
/><br
|
|
/><br
|
|
/>Failure:<br
|
|
/><br
|
|
/> message Failure {<br
|
|
/> required FailureReason cause = 1;<br
|
|
/> optional string URI = 2; /* for more human-readable information */<br
|
|
/> }<br
|
|
/><br
|
|
/>cause is the FailureReason enumerated type reason why the session or request failed or is being abandoned.<br
|
|
/><br
|
|
/>URI is an optional refernce to a URI where more human-readable information about the failure can be obtained. This can be used to clarify to the human user whether there is an action that could be taken to correct the problem.<br
|
|
/><br
|
|
/><br
|
|
/>Proceed: <br
|
|
/><br
|
|
/> message Proceed {<br
|
|
/> required int64 timestamp = 1;<br
|
|
/> optional int32 polldelay = 2;<br
|
|
/> }<br
|
|
/><br
|
|
/>timestamp is the Unix time when the message was issued. When sent by the server, polldelay is a suggested number of seconds to wait before contacting the server again.<br
|
|
/><br
|
|
/>Challenge:<br
|
|
/><br
|
|
/> message Challenge {<br
|
|
/> required ChallengeType type = 1;<br
|
|
/> optional string name = 2;<br
|
|
/> repeated bytes data = 3;<br
|
|
/> optional string URI = 4;<br
|
|
/> optional bool succeeded = 5;<br
|
|
/> }<br
|
|
/><br
|
|
/>type is the type of the challenge (as defined in the enumerated type ChallengeType).<br
|
|
/><br
|
|
/>name is the name or identifier the server assigned to this particular challenge instance.<br
|
|
/><br
|
|
/>data is an array of arbitrary byte values used by a particular challenge, whose semantics are defined by the corresponding challenge type.<br
|
|
/><br
|
|
/>URI is a URI associated with the challenge, whose semantics are defined by the corresponding challenge type.<br
|
|
/><br
|
|
/>succeeded can be used by the client or the server to indicate whether the party mentioning the challenge believes that the challenge has already been satisfied.<br
|
|
/><br
|
|
/>Success:<br
|
|
/><br
|
|
/> message Success {<br
|
|
/> required string certificate = 1;<br
|
|
/> optional string chain = 2;<br
|
|
/> }<br
|
|
/><br
|
|
/>certificate is the PEM-encoded certificate that was successfully issued.<br
|
|
/><br
|
|
/>chain is an optional PEM-encoded certificate chain that chains up from the intermediate certificate authority that issued this certificate to a root certificate authority, in order to allow a verifier to validate this certificate.<br
|
|
/><br
|
|
/></body>
|
|
</html>
|