mirror of
https://github.com/corda/corda.git
synced 2025-01-29 15:43:55 +00:00
Docs: adjust the certificate hierarchy design doc to render better in sphinx.
This commit is contained in:
Mike Hearn
parent
3baf27bbc7
commit
da01312ab6
@ -1,6 +1,3 @@
|
||||
|
||||
|
||||
--------------------------------------------
|
||||
Design Decision: Certificate hierarchy levels
|
||||
============================================
|
||||
|
||||
@ -12,7 +9,8 @@ The decision of how many levels to include is a key feature of the [proposed cer
|
||||
|
||||
### 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.
|
||||
Under this option, intermediate CA certificates for key signing services (Doorman, Network Map, CRL) are generated as
|
||||
direct children of the root certificate.
|
||||
|
||||
|
||||
|
||||
@ -23,11 +21,13 @@ Under this option, intermediate CA certificates for key signing services (Doorma
|
||||
|
||||
#### 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.
|
||||
- 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.
|
||||
Under this option, an additional 'Company CA' cert is generated from the root CA cert, which is then used to generate
|
||||
intermediate certificates.
|
||||
|
||||
|
||||
|
||||
@ -44,4 +44,7 @@ Under this option, an additional 'Company CA' cert is generated from the root CA
|
||||
|
||||
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.
|
||||
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.
|
||||
@ -1,12 +1,10 @@
|
||||
|
||||
|
||||
--------------------------------------------
|
||||
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).
|
||||
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
|
||||
|
||||
|
||||
@ -1,42 +1,29 @@
|
||||
|
||||
|
||||
# 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
|
||||
---
|
||||
# Certificate hierarchies
|
||||
|
||||
## 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)
|
||||
A certificate hierarchy is proposed to enable effective key management in the context of managing Corda networks.
|
||||
This includes certificate usage for the data signing process and certificate revocation process
|
||||
in case of a key compromise. At the same time, result should remain compliant with
|
||||
[OCSP](https://en.wikipedia.org/wiki/Online_Certificate_Status_Protocol) and [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.
|
||||
Corda utilises public key 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.
|
||||
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.
|
||||
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
|
||||
|
||||
@ -48,21 +35,22 @@ Goals:
|
||||
|
||||
Non-goals:
|
||||
|
||||
- Define an end-state mechanism for certificate revocation
|
||||
* 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.
|
||||
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 |
|
||||
* [Hierarchy levels](./decisions/levels.html). Option 1 - 2-level hierarchy.
|
||||
* [TLS trust root](./decisions/tls-trust-root.html). Option 1 - Single trust root.
|
||||
|
||||
## **Target** Solution
|
||||
|
||||
@ -77,10 +65,15 @@ The design introduces discrete intermediate CAs below the network trust root for
|
||||
|
||||
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.
|
||||
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)).
|
||||
TLS certificates will remain issued under Node CA certificates (see [decision: TLS trust
|
||||
root](./decisions/tls-trust-root.html)).
|
||||
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
Loading…
x
Reference in New Issue
Block a user