mirror of
https://github.com/corda/corda.git
synced 2025-02-20 09:26:41 +00:00
* Update identity docs (#2319) * Update certificate extension specification * Extend documentation on node name requirements * Moving node naming back to node generation file. Merging other permissioning information. * Update certificate structure image * Address some of the comments
This commit is contained in:
Katarzyna Streich
Katelyn Baker
parent
8e0e02eb28
commit
fda55e10ec
@ -44,7 +44,7 @@ UNRELEASED
|
||||
only ever by issued by network services and therefore issuance constraints are not relevant to end users.
|
||||
The ``TLS``, ``WELL_KNOWN_LEGAL_IDENTITY`` roles must be issued by the ``NODE_CA`` certificate issued by the
|
||||
Doorman, and ``CONFIDENTIAL_IDENTITY`` certificates must be issued from a ``WELL_KNOWN_LEGAL_IDENTITY`` certificate.
|
||||
For a detailed specification of the extension please see :doc:`permissioning-certificate-specification`.
|
||||
For a detailed specification of the extension please see :doc:`permissioning`.
|
||||
|
||||
* The network map service concept has been re-designed. More information can be found in :doc:`network-map`.
|
||||
|
||||
|
||||
@ -8,4 +8,3 @@ Corda networks
|
||||
permissioning
|
||||
network-map
|
||||
versioning
|
||||
permissioning-certificate-spec
|
||||
|
||||
@ -19,24 +19,33 @@ Each Corda node has the following structure:
|
||||
The node is configured by editing its ``node.conf`` file. You install CorDapps on the node by dropping the CorDapp JARs
|
||||
into the ``cordapps`` folder.
|
||||
|
||||
In development mode (i.e. when ``devMode = true``, see :doc:`corda-configuration-file` for more information), the ``certificates``
|
||||
directory is filled with pre-configured keystores if the required keystores do not exist. This ensures that developers
|
||||
can get the nodes working as quickly as possible. However, these pre-configured keystores are not secure. To learn more see :doc:`permissioning`.
|
||||
|
||||
Node naming
|
||||
-----------
|
||||
A node's name must be a valid X.500 distinguished name. In order to be compatible with other implementations
|
||||
(particularly TLS implementations), we constrain the allowed X.500 attribute types to a subset of the minimum supported
|
||||
set for X.509 certificates (specified in RFC 3280), plus the locality attribute:
|
||||
(particularly TLS implementations), we constrain the allowed X.500 name attribute types to a subset of the minimum
|
||||
supported set for X.509 certificates (specified in RFC 3280), plus the locality attribute:
|
||||
|
||||
* Organization (O)
|
||||
* State (ST)
|
||||
* Locality (L)
|
||||
* Country (C)
|
||||
* Organizational-unit (OU)
|
||||
* Common name (CN) (only used for service identities)
|
||||
* Common name (CN)
|
||||
|
||||
``State`` should be avoided unless required to differentiate from other ``localities`` with the same or similar names at the
|
||||
country level. For example, London (GB) would not need a ``state``, but St Ives would (there are two, one in Cornwall, one
|
||||
in Cambridgeshire). As legal entities in Corda are likely to be located in major cities, this attribute is not expected to be
|
||||
present in the majority of names, but is an option for the cases which require it.
|
||||
|
||||
The name must also obey the following constraints:
|
||||
|
||||
* The organisation, locality and country attributes are present
|
||||
* The ``organisation``, ``locality`` and ``country`` attributes are present
|
||||
|
||||
* The state, organisational-unit and common name attributes are optional
|
||||
* The ``state``, ``organisational-unit`` and ``common name`` attributes are optional
|
||||
|
||||
* The fields of the name have the following maximum character lengths:
|
||||
|
||||
@ -46,7 +55,7 @@ The name must also obey the following constraints:
|
||||
* Locality: 64
|
||||
* State: 64
|
||||
|
||||
* The country attribute is a valid ISO 3166-1 two letter code in upper-case
|
||||
* The ``country`` attribute is a valid ISO 3166-1 two letter code in upper-case
|
||||
|
||||
* All attributes must obey the following constraints:
|
||||
|
||||
@ -58,13 +67,20 @@ The name must also obey the following constraints:
|
||||
* Does not contain the null character
|
||||
* Only the latin, common and inherited unicode scripts are supported
|
||||
|
||||
* The organisation field of the name also obeys the following constraints:
|
||||
* The ``organisation`` field of the name also obeys the following constraints:
|
||||
|
||||
* No double-spacing
|
||||
|
||||
* This is to avoid right-to-left issues, debugging issues when we can't pronounce names over the phone, and
|
||||
character confusability attacks
|
||||
|
||||
External identifiers
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
Mappings to external identifiers such as company registration numbers, LEI, BIC, etc. should be stored in custom X.509
|
||||
certificate extensions. These values may change for operational reasons, without the identity they're associated with
|
||||
necessarily changing, and their inclusion in the distinguished name would cause significant logistical complications.
|
||||
The OID and format for these extensions will be described in a further specification.
|
||||
|
||||
The Cordform task
|
||||
-----------------
|
||||
Corda provides a gradle plugin called ``Cordform`` that allows you to automatically generate and configure a set of
|
||||
@ -75,9 +91,8 @@ in the `Kotlin CorDapp Template <https://github.com/corda/cordapp-template-kotli
|
||||
|
||||
task deployNodes(type: net.corda.plugins.Cordform, dependsOn: ['jar']) {
|
||||
directory "./build/nodes"
|
||||
networkMap "O=NetworkMapAndNotary,L=London,C=GB"
|
||||
node {
|
||||
name "O=NetworkMapAndNotary,L=London,C=GB"
|
||||
name "O=Notary,L=London,C=GB"
|
||||
// The notary will offer a validating notary service.
|
||||
notary = [validating : true]
|
||||
p2pPort 10002
|
||||
@ -138,16 +153,14 @@ Following the previous example ``PartyB`` node will have additional configuratio
|
||||
|
||||
Running this task will create three nodes in the ``build/nodes`` folder:
|
||||
|
||||
* A ``NetworkMapAndNotary`` node that:
|
||||
* A ``Notary`` node that:
|
||||
|
||||
* Serves as the network map
|
||||
* Offers a validating notary service
|
||||
* Will not have a webserver (since ``webPort`` is not defined)
|
||||
* Is running the ``corda-finance`` CorDapp
|
||||
|
||||
* ``PartyA`` and ``PartyB`` nodes that:
|
||||
|
||||
* Are pointing at the ``NetworkMapAndNotary`` as the network map service
|
||||
* Are not offering any services
|
||||
* Will have a webserver (since ``webPort`` is defined)
|
||||
* Are running the ``corda-finance`` CorDapp
|
||||
@ -157,8 +170,7 @@ Additionally, all three nodes will include any CorDapps defined in the project's
|
||||
CorDapps are not listed in each node's ``cordapps`` entry. This means that running the ``deployNodes`` task from the
|
||||
template CorDapp, for example, would automatically build and add the template CorDapp to each node.
|
||||
|
||||
You can extend ``deployNodes`` to generate additional nodes. The only requirement is that you must specify
|
||||
a single node to run the network map service, by putting its name in the ``networkMap`` field.
|
||||
You can extend ``deployNodes`` to generate additional nodes.
|
||||
|
||||
.. warning:: When adding nodes, make sure that there are no port clashes!
|
||||
|
||||
|
||||
@ -1,43 +0,0 @@
|
||||
Network Permissioning - Certificate Specification
|
||||
=================================================
|
||||
|
||||
Certificates used by Corda have additional constraints in their contents and hierarchical structure. In a typical
|
||||
installation node administrators should not need to be aware of these, however in some cases node certificates may
|
||||
be managed by external tools (such as an existing PKI solution deployed within an organisation), in which case it is
|
||||
important to understand these constraints.
|
||||
|
||||
There are a number of roles in Corda that certificates are used for:
|
||||
|
||||
* Doorman (Intermediate CA)
|
||||
* Well known service identity (network map and notary)
|
||||
* Node CA
|
||||
* TLS
|
||||
* Well known legal identity
|
||||
* Confidential legal identity
|
||||
|
||||
Extension
|
||||
---------
|
||||
|
||||
The Corda role that a certificate relates to is specified by custom X.509 v3 extension. This extension has OID 1.3.6.1.4.1.50530.1.1
|
||||
and is non-critical, as it is safe for implementations outside of Corda nodes to ignore the extension. The extension
|
||||
contains a single ASN.1 integer identifying the type of identity the certificate is for:
|
||||
|
||||
1. Doorman
|
||||
2. Well known service identity
|
||||
3. Node CA
|
||||
4. TLS
|
||||
5. Well known legal identity
|
||||
6. Confidential legal identity
|
||||
|
||||
Hierarchy
|
||||
---------
|
||||
|
||||
Certificate path validation is extended to enforce that the extension must be present where its issuer's certificate included the extension, and that:
|
||||
|
||||
* Doorman certificates are issued by a certificate without the extension present
|
||||
* Well known service identity certificates are issued by a certificate marked as Doorman
|
||||
* Node CA certificates are issued by a certificate marked as Doorman
|
||||
* Well known legal identity/TLS certificates are issued by a certificate marked as node CA
|
||||
* Confidential legal identity certificates are issued by a certificate marked as well known legal identity
|
||||
* Party certificates are marked as either a well known identity or a confidential identity
|
||||
* The structure of certificates above Doorman/Network map is intentionally left untouched, as they are not relevant to the identity service and therefore there is no advantage in enforcing a specific structure on those certificates. The certificate hierarchy consistency checks are required because nodes can issue their own certificates and can set their own role flags on certificates, and it's important to verify that these are set consistently with the certificate hierarchy design. As as side-effect this also acts as a secondary depth restriction on issued certificates.
|
||||
@ -1,4 +1,4 @@
|
||||
Network Permissioning
|
||||
Network permissioning
|
||||
=====================
|
||||
|
||||
.. contents::
|
||||
@ -10,23 +10,19 @@ Corda networks are *permissioned*. To connect to a network, a node needs three k
|
||||
* ``nodekeystore.jks``, which stores the node’s identity keypairs and certificates
|
||||
* ``sslkeystore.jks``, which stores the node’s TLS keypairs and certificates
|
||||
|
||||
In development mode (i.e. when ``devMode = true``, see :doc:`corda-configuration-file` for more information),
|
||||
pre-configured keystores are used if the required keystores do not exist. This ensures that developers can get the
|
||||
nodes working as quickly as possible.
|
||||
|
||||
However, these pre-configured keystores are not secure. Production deployments require a secure certificate authority.
|
||||
Production deployments require a secure certificate authority.
|
||||
Most production deployments will use an existing certificate authority or construct one using software that will be
|
||||
made available in the coming months. Until then, the documentation below can be used to create your own certificate
|
||||
authority.
|
||||
|
||||
Network structure
|
||||
-----------------
|
||||
A Corda network has three types of certificate authorities (CAs):
|
||||
Certificate hierarchy
|
||||
---------------------
|
||||
A Corda network has four types of certificate authorities (CAs):
|
||||
|
||||
* The **root network CA**
|
||||
* The **intermediate network CA**
|
||||
* The **doorman CA**
|
||||
|
||||
* The intermediate network CA is used instead of the root network CA for day-to-day
|
||||
* The doorman CA is used instead of the root network CA for day-to-day
|
||||
key signing to reduce the risk of the root network CA's private key being compromised
|
||||
|
||||
* The **node CAs**
|
||||
@ -34,6 +30,27 @@ A Corda network has three types of certificate authorities (CAs):
|
||||
* Each node serves as its own CA in issuing the child certificates that it uses to sign its identity
|
||||
keys and TLS certificates
|
||||
|
||||
* The **legal identity CAs**
|
||||
|
||||
* Node's well-known legal identity, apart from signing transactions, can also issue certificates for confidential legal identities
|
||||
|
||||
The following constraints are also imposed:
|
||||
|
||||
* Doorman certificates are issued by a network root which certificate doesn't contain the extension
|
||||
* Well-known service identity certificates are issued by an entity with a Doorman certificate
|
||||
* Node CA certificates are issued by an entity with a Doorman certificate
|
||||
* Well known legal identity/TLS certificates are issued by a certificate marked as node CA
|
||||
* Confidential legal identity certificates are issued by a certificate marked as well known legal identity
|
||||
* Party certificates are marked as either a well known identity or a confidential identity
|
||||
* The structure of certificates above Doorman/Network map is intentionally left untouched, as they are not relevant to
|
||||
the identity service and therefore there is no advantage in enforcing a specific structure on those certificates. The
|
||||
certificate hierarchy consistency checks are required because nodes can issue their own certificates and can set
|
||||
their own role flags on certificates, and it's important to verify that these are set consistently with the
|
||||
certificate hierarchy design. As as side-effect this also acts as a secondary depth restriction on issued
|
||||
certificates
|
||||
|
||||
All the certificates must be issued with the custom role extension (see below).
|
||||
|
||||
We can visualise the permissioning structure as follows:
|
||||
|
||||
.. image:: resources/certificate_structure.png
|
||||
@ -51,15 +68,36 @@ public/private keypairs and certificates. The keypairs and certificates should o
|
||||
|
||||
* The TLS certificates must follow the `TLS v1.2 standard <https://tools.ietf.org/html/rfc5246>`_
|
||||
|
||||
* The root network CA, intermediate network CA and node CA keys, as well as the node TLS
|
||||
* The root network CA, doorman CA and node CA keys, as well as the node TLS
|
||||
keys, must follow one of the following schemes:
|
||||
|
||||
* ECDSA using the NIST P-256 curve (secp256r1)
|
||||
|
||||
* RSA with 3072-bit key size
|
||||
|
||||
Creating the root and intermediate network CAs
|
||||
----------------------------------------------
|
||||
Certificate role extension
|
||||
--------------------------
|
||||
Corda certificates have a custom X.509 v3 extension that specifies the role the certificate relates to. This extension
|
||||
has the OID 1.3.6.1.4.1.50530.1.1 and is non-critical, so implementations outside of Corda nodes can safely ignore it.
|
||||
The extension contains a single ASN.1 integer identifying the identity type the certificate is for:
|
||||
|
||||
1. Doorman
|
||||
2. Network map
|
||||
3. Service identity (such as a notary or oracle)
|
||||
3. Node certificate authority (from which the TLS and well-known identity certificates are issued)
|
||||
4. Transport layer security
|
||||
5. Well-known legal identity
|
||||
6. Confidential legal identity
|
||||
|
||||
In a typical installation, node administrators needn't be aware of these. However, when node certificates are managed
|
||||
by external tools (such as an existing PKI solution deployed within an organisation), it is important to understand
|
||||
these constraints.
|
||||
|
||||
Certificate path validation is extended so that a certificate must contain the extension if the extension was present
|
||||
in the certificate of the issuer.
|
||||
|
||||
Creating the root and doorman CAs
|
||||
---------------------------------
|
||||
|
||||
Creating the root network CA's keystore and truststore
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
@ -74,31 +112,31 @@ Creating the root network CA's keystore and truststore
|
||||
|
||||
3. Create a new keystore and store the root network CA's keypair and certificate in it for later use
|
||||
|
||||
* This keystore will be used by the root network CA to sign the intermediate network CA's certificate
|
||||
* This keystore will be used by the root network CA to sign the doorman CA's certificate
|
||||
|
||||
4. Create a new Java keystore named ``truststore.jks`` and store the root network CA's certificate in it using the
|
||||
alias ``cordarootca``
|
||||
|
||||
* This keystore will be provisioned to the individual nodes later
|
||||
* This keystore must then be provisioned to the individual nodes later so they can store it in their ``certificates`` folder
|
||||
|
||||
.. warning:: The root network CA's private key should be protected and kept safe.
|
||||
|
||||
Creating the intermediate network CA's keystore
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Creating the doorman CA's keystore
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
1. Create a new keypair
|
||||
|
||||
* This will be used as the intermediate network CA's keypair
|
||||
* This will be used as the doorman CA's keypair
|
||||
|
||||
2. Obtain a certificate for the keypair signed with the root network CA key. The basic constraints extension must be
|
||||
set to ``true``
|
||||
|
||||
* This will be used as the intermediate network CA's certificate
|
||||
* This will be used as the doorman CA's certificate
|
||||
|
||||
3. Create a new keystore and store the intermediate network CA's keypair and certificate chain
|
||||
(i.e. the intermediate network CA certificate *and* the root network CA certificate) in it for later use
|
||||
3. Create a new keystore and store the doorman CA's keypair and certificate chain
|
||||
(i.e. the doorman CA certificate *and* the root network CA certificate) in it for later use
|
||||
|
||||
* This keystore will be used by the intermediate network CA to sign the nodes' identity certificates
|
||||
* This keystore will be used by the doorman CA to sign the nodes' identity certificates
|
||||
|
||||
Creating the node CA keystores and TLS keystores
|
||||
------------------------------------------------
|
||||
@ -108,7 +146,7 @@ Creating the node CA keystores
|
||||
|
||||
1. For each node, create a new keypair
|
||||
|
||||
2. Obtain a certificate for the keypair signed with the intermediate network CA key. The basic constraints extension must be
|
||||
2. Obtain a certificate for the keypair signed with the doorman CA key. The basic constraints extension must be
|
||||
set to ``true``
|
||||
|
||||
3. Create a new Java keystore named ``nodekeystore.jks`` and store the keypair in it using the alias ``cordaclientca``
|
||||
|
||||
@ -8,7 +8,7 @@ Unreleased
|
||||
* X.509 certificates now have an extension that specifies the Corda role the certificate is used for, and the role
|
||||
hierarchy is now enforced in the validation code. This only has impact on those developing integrations with external
|
||||
PKI solutions, in most cases it is managed transparently by Corda. A formal specification of the extension can be
|
||||
found at see :doc:`permissioning-certificate-specification`.
|
||||
found at :doc:`permissioning`.
|
||||
|
||||
* **Enum Class Evolution**
|
||||
With the addition of AMQP serialization Corda now supports enum constant evolution.
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 108 KiB After Width: | Height: | Size: 364 KiB |
Loading…
x
Reference in New Issue
Block a user