From fddb19fe4afdacd4ce8370384aa5627c0a17725e Mon Sep 17 00:00:00 2001 From: Peter Eckersley Date: Sun, 11 Aug 2013 17:47:48 +0200 Subject: [PATCH] Import draft Trustify protocol docs from Etherpad --- doc/trustify-protocol.html | 266 +++++++++++++++++++++++++++++++++++++ 1 file changed, 266 insertions(+) create mode 100644 doc/trustify-protocol.html diff --git a/doc/trustify-protocol.html b/doc/trustify-protocol.html new file mode 100644 index 000000000..3466f37ab --- /dev/null +++ b/doc/trustify-protocol.html @@ -0,0 +1,266 @@ + + + + + +/26$6 + +ABSTRACT

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.


INTRODUCTION

The Trustify (aka Chococlate) protocol is used between a client, 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 server, which is a certification service provided by a certificate authority.

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.

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.

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.

IDENTIFYING AVAILABLE TRUSTIFY SERVERS

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.

The Trustify Server List will contain the following data:

[Server name string, server URL, <optional> [policy string1, policy string 2,..]]

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.

SESSIONS

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.

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.

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.

MESSAGE

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):

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.

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.)

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.
Note: Protocol also specifies the client can send this message after a polling period.

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.

completedchallenge [type Challenge]: sent by the client to announce that the client believes it has successfully completed a challenge.

success [type Success]: sent by the server to issue the requested certificate.

SEQUENCE OF COMMUNICATIONS

TODO: Document difference between challenge types that call for proceed message and challenge types that call for completedchallenge message.

Initial request
At the start of communications:
Server challenge or certificate issuance
In response to the request message:
Server response to challenge progress
In response to the client-side completedchallenge or proceed message:
VERIFICATION CHALLENGES

During the course of a session, the Trustify server presents the client with one or more challenges,  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.

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.

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)

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).

DVSNI Challenges:

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.

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.

DVSNI implementation specifics:

    Shared parameters (chosen and sent by CA in the Challenge message):
        ${nonce}            A randomly chosen nonce hex output of digest of (random 32-bytes)
        ${y} [:= E(r)]       r is a random secret (32 bytes, raw binary)
        ${ext}                x.509 extension (format? e.g: 1.3.3.7)

    Client setup:
        Setup SNI for ${nonce}.chocolate
        Serve a self-signed certificate with (critical(?)) X.509 extension ${ext},
            with value z = HMAC_r(s) || s (random s, r = D(${y}) (private key decrypt))

    Chocolate Server (CA) verification steps:
        Connect to domain.com, with TLS SNI ${nonce}.chocolate
        Check certificate for X.509 extension ${ext}. Verify that value z is formed as expected.
        
            Purpose:
        Proves that whoever has access to the corresponding private key also has the ability
            to serve (change configuration for) an arbitrary certificate for an arbitrary
            subdomain under the desired domain name.

    Explanation:
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.
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).

    Deviations from model:
     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.
     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.

DVSNI Security Considerations:

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.

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.

Proof-of-posession challenges:

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.

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.


Payment challenges:

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.

If Payment challenges exist, they will simply contain a URL for a web page that can specify and accept the payment required.


FAILURE REASONS

Currently, the following reasons for the failure of a session are defined:

UnsupportedVersion: the requested protocol version is not available.
AbandonedRequest: the client has abandoned the session and is no longer requesting issuance of the certificate.
ServerOutage: the service is temporarily unavailable.
ServerGone: the service is permanently unavailable.
StaleRequest: 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.
BadSignature: the digital signature used by the client to prove its possession of the private key corresponding to the subject public key is invalid.
BadCSR: the certificate signing request sent by the client is invalid in some way.
BadRequest: the subject public key, one or more subject host names, or some other aspect of the signing request is invalid.
NeedClientPuzzle: as a denial-of-service mitigation measure, the server cannot accept the request without additional proof of work by the client.
CannotIssueThatName: the issuance of a certificate for one or more of the subject host names is administratively prohibited.
ExistingCertificate: 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.
UnsafeKey: the subject public key violates a CA policy or is known to be insecure.
ChallengeFailed: the client's attempt to comply with a challenge was unsuccessful.
ChallengeTimeout: the client did not appear to comply with a challenge within the required period of time.

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.

SECURITY CONSIDERATIONS

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.

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.

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.

The server SHOULD avoid passing unvalidated or unsanitized data from the client to any server code implemented in a non-bounds-checked language.

The server SHOULD use physical controls to isolate a machine capable of directly causing certificate issuance from the public Internet.

The server SHOULD attempt to detect fraudulent attempts to issue certificates.

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.

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.

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.

The above list of verification steps may not be exhaustive.  Full policy guidelines on these questions will be maintained by the Trustify governance foundation.

MESSAGE DATA TYPES

SigningRequest:

    message SigningRequest {
         required int64 timestamp = 2;
         required string recipient = 3;
         required string csr = 4;
         required bytes sig = 5;
         optional string clientpuzzle = 6;
    }

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.)

recipient is the URI of the service to which the client intended to submit the request.

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).

sig is an RSA signature over the preceding values using the private key that corresponds to the subject public key.  TODO: describe how the signature is calculated.

clientpuzzle is a hashcash string that refers to the hostname of the server.


Failure:

    message Failure {
         required FailureReason cause = 1;
         optional string URI = 2;  /* for more human-readable information */
    }

cause is the FailureReason enumerated type reason why the session or request failed or is being abandoned.

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.


Proceed: 

    message Proceed {
         required int64 timestamp = 1;
             optional int32 polldelay = 2;
        }

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.

Challenge:

    message Challenge {
         required ChallengeType type = 1;
         optional string name = 2;
         repeated bytes data = 3;
         optional string URI = 4;
         optional bool succeeded = 5;
    }

type is the type of the challenge (as defined in the enumerated type ChallengeType).

name is the name or identifier the server assigned to this particular challenge instance.

data is an array of arbitrary byte values used by a particular challenge, whose semantics are defined by the corresponding challenge type.

URI is a URI associated with the challenge, whose semantics are defined by the corresponding challenge type.

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.

Success:

    message Success {
         required string certificate = 1;
             optional string chain = 2;
    }

certificate is the PEM-encoded certificate that was successfully issued.

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.

+