diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst index 7dcb99bdc5..674b96c428 100644 --- a/docs/source/changelog.rst +++ b/docs/source/changelog.rst @@ -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`. diff --git a/docs/source/corda-networks-index.rst b/docs/source/corda-networks-index.rst index 1ac1c2dc1c..9315a2de09 100644 --- a/docs/source/corda-networks-index.rst +++ b/docs/source/corda-networks-index.rst @@ -8,4 +8,3 @@ Corda networks permissioning network-map versioning - permissioning-certificate-spec diff --git a/docs/source/generating-a-node.rst b/docs/source/generating-a-node.rst index 19ae9ab27b..f1e1b2160a 100644 --- a/docs/source/generating-a-node.rst +++ b/docs/source/generating-a-node.rst @@ -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 `_ -* 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`` diff --git a/docs/source/release-notes.rst b/docs/source/release-notes.rst index 7b3e96fe4c..5bd286f858 100644 --- a/docs/source/release-notes.rst +++ b/docs/source/release-notes.rst @@ -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. diff --git a/docs/source/resources/certificate_structure.png b/docs/source/resources/certificate_structure.png index 6121b968da..df3f786276 100644 Binary files a/docs/source/resources/certificate_structure.png and b/docs/source/resources/certificate_structure.png differ