diff --git a/attic/doc/trustify-protocol.html b/attic/doc/trustify-protocol.html index 3466f37ab..302e343c2 100644 --- a/attic/doc/trustify-protocol.html +++ b/attic/doc/trustify-protocol.html @@ -12,7 +12,7 @@ />
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 Trustify (aka Chocolate) 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.


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


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.
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 verifying 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).
As  a matter of protocol synchronization, there are two subtypes of  challenges: those where completion of the challenge is signaled 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 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 administrative control of the DNS name's web server  software, and probably has full administrative control of the servers that the DNS name points to.

DVSNI implementation specifics:


    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).
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 necessary 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.
     Apache uses the first virtual server specified 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:


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:
Proof-of-possession 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.


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.
In  limited situations, it may be determined that traditional OV or EV processes are required for the issuance of certificates 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.


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.
URI is an optional reference 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: