From e0ebbcc426c37b8d468ecc67b4196add94ac4da3 Mon Sep 17 00:00:00 2001 From: Joel Dudley Date: Mon, 27 Nov 2017 14:30:55 +0000 Subject: [PATCH] Updates permissioning docs to address RGB review comments. --- docs/source/permissioning.rst | 117 +++++++++++++++++++++------------- 1 file changed, 71 insertions(+), 46 deletions(-) diff --git a/docs/source/permissioning.rst b/docs/source/permissioning.rst index 13d889cc43..dcffd0bb49 100644 --- a/docs/source/permissioning.rst +++ b/docs/source/permissioning.rst @@ -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 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 -that will be used in the creation of these keystores for each node joining the network. +However, these pre-configured keystores are not secure. 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. -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 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 `_ -Creating the node certificate authority -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -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 and intermediate network CAs +---------------------------------------------- -Creating the root CA's keystore and truststore -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Creating the root network CA's keystore and truststore +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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`` - * 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 - * 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 - ``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 +2. Obtain a certificate for the keypair signed with the root network CA key. The basic constraints extension must be 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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -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 ``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 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -For each node: +---------------------------------------- +For each node, copy the following files to the node's certificate directory (``/certificates/``): -1. Copy the node's ``nodekeystore.jks`` and ``sslkeystore.jks`` keystores to the node's certificate directory - -2. Copy the ``truststore.jks`` keystore created by the root CA to the node's certificate directory \ No newline at end of file +1. The node's ``nodekeystore.jks`` keystore +2. The node's ``sslkeystore.jks`` keystore +3. The root network CA's ``truststore.jks`` keystore