Docs: bring certificate hierarchy design doc across into the open repo.

docs/source/design/ent-1133_certificate_hierarchy/decisions/levels.md

@@ -0,0 +1,47 @@
+![Corda](https://www.corda.net/wp-content/uploads/2016/11/fg005_corda_b.png)
+
+--------------------------------------------
+Design Decision: Certificate hierarchy levels
+============================================
+
+## Background / Context
+
+The decision of how many levels to include is a key feature of the [proposed certificate hierarchy](../design.md).
+
+## Options Analysis
+
+### Option 1: 2-level hierarchy
+
+Under this option, intermediate CA certificates for key signing services (Doorman, Network Map, CRL) are generated as direct children of the root certificate.
+
+![Current](../images/option1.png)
+
+#### Advantages
+
+- Simplest option
+- Minimal change to existing structure
+
+#### Disadvantages
+
+- The Root CA certificate is used to sign both intermediate certificates and CRL. This may be considered as a drawback as the Root CA should be used only to issue other certificates.
+
+### Option 2: 3-level hierarchy
+
+Under this option, an additional 'Company CA' cert is generated from the root CA cert, which is then used to generate intermediate certificates.
+
+![Current](../images/option2.png)
+
+#### Advantages
+
+- Allows for option to remove the root CA from the network altogether and store in an offline medium - may be preferred by some stakeholders
+- Allows (theoretical) revocation and replacement of the company CA cert without needing to replace the trust root.
+
+#### Disadvantages
+
+- Greater complexity
+
+## Recommendation and justification
+
+Proceed with option 1: 2-level hierarchy.
+
+No authoritative argument from a security standpoint has been made which would justify the added complexity of option 2. Given the business impact of revoking the Company CA certificate, this must be considered an extremely unlikely event with comparable implications to the revocation of the root certificate itself; hence no practical justification for the addition of the third level is observed.

docs/source/design/ent-1133_certificate_hierarchy/decisions/tls-trust-root.md

@@ -0,0 +1,44 @@
+![Corda](https://www.corda.net/wp-content/uploads/2016/11/fg005_corda_b.png)
+
+--------------------------------------------
+Design Decision: Certificate Hierarchy
+============================================
+
+## Background / Context
+
+This document purpose is to make a decision on the certificate hierarchy. It is necessary to make this decision as it affects development of features (e.g. Certificate Revocation List).
+
+## Options Analysis
+
+There are various options in how we structure the hierarchy above the node CA.
+
+### Option 1: Single trust root
+
+Under this option, TLS certificates are issued by the node CA certificate.
+
+#### Advantages
+
+- Existing design
+
+#### Disadvantages
+
+- The Root CA certificate is used to sign both intermediate certificates and CRL. This may be considered as a drawback as the Root CA should be used only to issue other certificates.
+
+### Option 2: Separate TLS vs. identity trust roots
+
+This option splits the hierarchy by introducing a separate trust root for TLS certificates. 
+
+#### Advantages
+
+- Simplifies issuance of TLS certificates (implementation constraints beyond those of other certificates used by Corda - specifically, EdDSA keys are not yet widely supported for TLS certificates)
+- Avoids requirement to specify accurate usage restrictions on node CA certificates to issue their own TLS certificates
+
+#### Disadvantages
+
+- Additional complexity
+
+## Recommendation and justification
+
+Proceed with option 1 (Single Trust Root) for current purposes.
+
+Feasibility of option 2 in the code should be further explored in due course.

docs/source/design/ent-1133_certificate_hierarchy/design.md

@@ -0,0 +1,86 @@
+![Corda](https://www.corda.net/wp-content/uploads/2016/11/fg005_corda_b.png)
+
+# Design
+
+## Document Control
+
+| Title                | Certificate hierarchy                    |
+| -------------------- | ---------------------------------------- |
+| Date                 | 23/11/2017                               |
+| Author               | Michal Kit                               |
+| Distribution         | Shams Asari, Patrick Kuo, Jonathan Sartin, David Lee, Matthew Nesbit, Konstantinos Chalkias |
+| Corda target version | Enterprise                               |
+| JIRA reference       | [ENT-1133](https://r3-cev.atlassian.net/browse/ENT-1133) |
+
+## Approvals
+
+#### Document Sign-off
+
+| Author            |                                          |
+| ----------------- | ---------------------------------------- |
+| Reviewer(s)       | Shams Asari, Patrick Kuo, Jonathan Sartin, David Lee |
+| Final approver(s) | Mike Hearn                               |
+
+HIGH LEVEL DESIGN
+---
+
+## Overview
+
+A certificate hierarchy is proposed to enable effective key management in the context of managing Corda networks, primarily Corda Connect. This includes certificate usage for the data signing process and certificate revocation process in case of a security leak. At the same time, result should  remain compliant with standards: [OCSP](https://en.wikipedia.org/wiki/Online_Certificate_Status_Protocol), [RFC 5280](https://www.ietf.org/rfc/rfc5280.txt)
+
+## Background
+
+Corda utilises public key (asymmetric) cryptography for signing and authentication purposes, and securing communication via TLS. As a result, every entity participating in a Corda network owns one or more cryptographic key pairs {*private, public*}. Integrity and authenticity of an entity's public key is assured using digital certificates following the [X.509 standard](https://tools.ietf.org/html/rfc5280), whereby the receiver’s identity is cryptographically bonded to his or her public key.
+
+Certificate Revocation List (CRL) functionality interacts with the hierarchy of the certificates, as the revocation list for any given certificate must be signed by the certificate's issuer. Therefore if we have a single doorman CA, the sole CRL for node CA certificates would be maintained by that doorman CA, creating a bottleneck. Further, if that doorman CA is compromised and its certificate revoked by the root certificate, the entire network is invalidated as a consequence.
+
+The current solution of a single intermediate CA is therefore too simplistic.
+
+Further, the split and location of intermediate CAs has impact on where long term infrastructure is hosted, as the CRLs for certificates issued by these CAs must be hosted at the same URI for the lifecycle of the issued certificates.
+
+## Scope
+
+Goals:
+
+* Define effective certificate relationships between participants and Corda network services  (i.e. nodes, notaries, network map, doorman).
+* Enable compliance with both [OCSP](https://en.wikipedia.org/wiki/Online_Certificate_Status_Protocol) and [RFC 5280](https://www.ietf.org/rfc/rfc5280.txt) (CRL)-based revocation mechanisms
+* Mitigate relevant security risks (keys being compromised, data privacy loss etc.)
+
+Non-goals:
+
+- Define an end-state mechanism for certificate revocation
+
+## Requirements
+
+In case of a private key being compromised, or a certificate incorrectly issued, it must be possible for the issuer to revoke the appropriate certificate(s).
+
+The solution needs to scale, keeping in mind that the list of revoked certificates from any given certificate authority is likely to grow indefinitely. However for an initial deployment a temporary certificate authority may be used, and given that it will not require to issue certificates in the long term, scaling issues are less of a concern in this context.
+
+
+## Design Decisions
+
+| Heading (link to completed Decision document using template) | Recommendation               |
+| ---------------------------------------- | ---------------------------- |
+| [Hierarchy levels](./decisions/levels.md) | Option 1 - 2-level hierarchy |
+| [TLS trust root](./decisions/tls-trust-root.md) | Option 1 - Single trust root |
+
+## **Target** Solution
+
+![Target certificate structure](./images/cert_structure_v2.png)
+
+The design introduces discrete intermediate CAs below the network trust root for each logical service exposed by the doorman - specifically:
+
+1. Node CA certificate issuance
+2. Network map signing
+3. Certificate Revocation List (CRL) signing
+4. OCSP revocation signing
+
+The use of discrete certificates in this way facilitates subsequent changes to the model, including retiring and replacing certificates as needed.
+
+Each of the above certificates will specify a CRL allowing the certificate to be revoked. The root CA operator (primarily R3) will be required to maintain this CRL for the lifetime of the process.
+
+TLS certificates will remain issued under Node CA certificates (see [decision: TLS trust root](./decisions/tls-trust-root.md)). 
+
+Nodes will be able to specify CRL(s) for TLS certificates they issue; in general, they will be required to such CRLs for the lifecycle of the TLS certificates.
+
+In the initial state, a single Doorman intermediate CA will be used for issuing all node certificates. Further intermediate CAs for issuance of node CA certificates may subsequently  be added to the network, where appropriate, potentially split by geographic region or otherwise.

docs/source/index.rst

@@ -57,6 +57,7 @@ We look forward to seeing what you can do with Corda!
    :maxdepth: 2
 
    design/design-review-process.md
+   design/ent-1133_certificate_hierarchy/design.md
 
 .. toctree::
    :caption: Participate