ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2024-12-20 13:33:12 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Updates permissioning docs to address RGB review comments.

Browse Source
This commit is contained in:
Joel Dudley 2017-11-27 14:30:55 +00:00 committed by GitHub
parent 247c57766c
commit e0ebbcc426
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 71 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

117
docs/source/permissioning.rst
View File

@ -14,11 +14,28 @@ In development mode (i.e. when ``devMode = true``, see :doc:`corda-configuration
pre-configured keystores are used if the required keystores do not exist. This ensures that developers can get the 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. nodes working as quickly as possible.
However, these pre-configured keystores are not secure. For a real network, you need to create a certificate authority However, these pre-configured keystores are not secure. Production deployments require a secure certificate authority.
that will be used in the creation of these keystores for each node joining the network. 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.
Creating the network keypairs and certificates Network structure
---------------------------------------------- -----------------
A Corda network has three types of certificate authorities (CAs):
* The **root network CA**
* The **intermediate network CA**
* The intermediate network 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**
* Each node serves as its own CA in issuing the child certificates that it uses to sign its identity
keys, anonymous keys and TLS certificates
Keypair and certificate formats
-------------------------------
You can use any standard key tools or Corda's ``X509Utilities`` (which uses Bouncy Castle) to create the required You can use any standard key tools or Corda's ``X509Utilities`` (which uses Bouncy Castle) to create the required
public/private keypairs and certificates. The keypairs and certificates should obey the following restrictions: public/private keypairs and certificates. The keypairs and certificates should obey the following restrictions:
@ -28,72 +45,80 @@ 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 TLS certificates must follow the `TLS v1.2 standard <https://tools.ietf.org/html/rfc5246>`_
Creating the node certificate authority Creating the root and intermediate network CAs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ----------------------------------------------
The node certificate authority is used to sign the node identity certificates. An intermediate CA is used instead of
the root CA for day-to-day key signing to reduce the risk of the root CA's private key being compromised.
Creating the root CA's keystore and truststore Creating the root network CA's keystore and truststore
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1. Create a new keypair 1. Create a new keypair
* This will be used as the root CA's keypair * This will be used as the root network CA's keypair
2. Create a self-signed certificate for the keypair. The basic constraints extension must be set to ``true`` 2. Create a self-signed certificate for the keypair. The basic constraints extension must be set to ``true``
* This will be used as the root CA's certificate * This will be used as the root network CA's certificate
3. Store the root CA's keypair and certificate in a keystore for later use 3. Create a new keystore and store the root network CA's keypair and certificate in it for later use
4. Store the root CA's certificate in a Java keystore named ``truststore.jks`` using the alias ``cordarootca`` * This keystore will be used by the root network CA to sign the intermediate network CA's certificate
.. warning:: The root CA's private key should be protected and kept safe. 4. Create a new Java keystore named ``truststore.jks`` and store the root network CA's certificate in it using the
alias ``cordarootca``
Creating the intermediate CA's keystore * This keystore will be provisioned to the individual nodes later
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. warning:: The root network CA's private key should be protected and kept safe.
Creating the intermediate network CA's keystore
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1. Create a new keypair 1. Create a new keypair
* This will be used as the intermediate CA's keypair * This will be used as the intermediate network CA's keypair
2. Obtain a certificate for the keypair signed with the root CA key. The basic constraints extension must be set to 2. Obtain a certificate for the keypair signed with the root network CA key. The basic constraints extension must be
``true``
* This will be used as the intermediate CA's certificate
3. Store the intermediate CA's keypair and certificate chain (i.e. the intermediate CA certificate *and* the root CA
certificate) in a keystore for later use
Creating the node CA keystores and TLS keystores
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Each node serves as its own "node CA" in issuing the child certificates that it uses to sign its identity keys,
anonymous keys and TLS certificates.
Creating the node CA keystores
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. On each node, create a new keypair
2. Obtain a certificate for the keypair signed with the intermediate CA key. The basic constraints extension must be
set to ``true`` set to ``true``
3. Store the keypair in a Java keystore named ``nodekeystore.jks`` using the alias ``cordaclientca`` * This will be used as the intermediate network 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
* This keystore will be used by the intermediate network CA to sign the nodes' identity certificates
Creating the node CA keystores and TLS keystores
------------------------------------------------
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
set to ``true``
3. Create a new Java keystore named ``nodekeystore.jks`` and store the keypair in it using the alias ``cordaclientca``
* The node will store this keystore locally to sign its identity keys and anonymous keys
Creating the node TLS keystores Creating the node TLS keystores
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1. On each node, create a new keypair 1. For each node, create a new keypair
2. Create a certificate for the keypair signed with the node CA key. The basic constraints extension must be set to 2. Create a certificate for the keypair signed with the node CA key. The basic constraints extension must be set to
``false`` ``false``
3. Store the key and certificates in a Java keystore named ``sslkeystore.jks`` using the alias ``cordaclienttls`` 3. Create a new Java keystore named ``sslkeystore.jks`` and store the key and certificates in it using the alias
``cordaclienttls``
* The node will store this keystore locally to sign its TLS certificates
Installing the certificates on the nodes Installing the certificates on the nodes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ----------------------------------------
For each node: For each node, copy the following files to the node's certificate directory (``<workspace>/certificates/``):
1. Copy the node's ``nodekeystore.jks`` and ``sslkeystore.jks`` keystores to the node's certificate directory 1. The node's ``nodekeystore.jks`` keystore
2. The node's ``sslkeystore.jks`` keystore
2. Copy the ``truststore.jks`` keystore created by the root CA to the node's certificate directory 3. The root network CA's ``truststore.jks`` keystore