mirror of
https://github.com/corda/corda.git
synced 2024-12-19 04:57:58 +00:00
Network permissioning new doc
This commit is contained in:
Patrick Kuo
Joel Dudley
parent
ffd693719a
commit
20337aaa25
@ -1,104 +1,99 @@
|
||||
Network permissioning (Doorman)
|
||||
===============================
|
||||
Network Permissioning
|
||||
=====================
|
||||
|
||||
The keystore located in ``<workspace>/certificates/sslkeystore.jks`` is required to connect to the Corda network securely.
|
||||
In development mode (when ``devMode = true``, see ":doc:`corda-configuration-file`" for more information) a pre-configured
|
||||
keystore will be used if the keystore does not exist. This is to ensure developers can get the nodes working as quickly
|
||||
as possible.
|
||||
.. contents::
|
||||
|
||||
However this is not secure for the real network. This documentation will explain the procedure of obtaining a signed
|
||||
certificate for TestNet.
|
||||
Corda networks are *permissioned*. To connect to a network, a node needs three keystores in its
|
||||
``<workspace>/certificates/`` folder:
|
||||
|
||||
Initial Registration
|
||||
--------------------
|
||||
* ``truststore.jks``, which stores trusted public keys and certificates (in our case, those of the network root CA)
|
||||
* ``nodekeystore.jks``, which stores the node’s identity keypairs and certificates
|
||||
* ``sslkeystore.jks``, which stores the node’s TLS keypairs and certificates
|
||||
|
||||
The certificate signing request will be created based on node information obtained from the node configuration.
|
||||
The following information from the node configuration file is needed to generate the request.
|
||||
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.
|
||||
|
||||
:myLegalName: Your company's legal name as an X.500 string. X.500 allows differentiation between entities with the same
|
||||
name as the legal name needs to be unique on the network. If another node has already been permissioned with this
|
||||
name then the permissioning server will automatically reject the request. The request will also be rejected if it
|
||||
violates legal name rules, see `Legal Name Constraints`_ for more information.
|
||||
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.
|
||||
|
||||
:emailAddress: e.g. "admin@company.com"
|
||||
Creating the network keypairs and certificates
|
||||
----------------------------------------------
|
||||
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:
|
||||
|
||||
:compatibilityZoneURL: Corda compatibility zone network management service root URL.
|
||||
* The certificates must follow the `X.509 standard <https://tools.ietf.org/html/rfc5280>`_
|
||||
|
||||
A new pair of private and public keys generated by the Corda node will be used to create the request.
|
||||
* We recommend X.509 v3 for forward compatibility
|
||||
|
||||
The utility will submit the request to the doorman server and poll for a result periodically to retrieve the certificates.
|
||||
Once the request has been approved and the certificates downloaded from the server, the node will create the keystore and trust store using the certificates and the generated private key.
|
||||
* The TLS certificates must follow the `TLS v1.2 standard <https://tools.ietf.org/html/rfc5246>`_
|
||||
|
||||
.. note:: You can exit the utility at any time if the approval process is taking longer than expected. The request process will resume on restart.
|
||||
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.
|
||||
|
||||
This process only is needed when the node connects to the network for the first time, or when the certificate expires.
|
||||
Creating the root CA's keystore and truststore
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Legal Name Constraints
|
||||
----------------------
|
||||
The legal name is the unique identifier in the Corda network, so constraints have been set out to prevent encoding attacks and visual spoofing.
|
||||
1. Create a new keypair
|
||||
|
||||
The legal name validator (see ``LegalNameValidator.kt``) is used to enforce rules on Corda's legal names, it is intended to be used by the network operator and Corda node during the node registration process.
|
||||
It has two functions, a function to normalize legal names, and a function to validate legal names.
|
||||
* This will be used as the root CA's keypair
|
||||
|
||||
The normalize function performs the following transformations:
|
||||
2. Create a self-signed certificate for the keypair. The basic constraints extension must be set to ``true``
|
||||
|
||||
* Remove leading and trailing whitespaces.
|
||||
* This will be used as the root CA's certificate
|
||||
|
||||
* Replace multiple whitespaces with a single space.
|
||||
3. Store the root CA's keypair and certificate in a keystore for later use
|
||||
|
||||
* Normalize the string according to `NFKC normalization form <https://en.wikipedia.org/wiki/Unicode_equivalence#Normalization>`_.
|
||||
4. Store the root CA's certificate in a Java keystore named ``truststore.jks`` using the alias ``cordarootca``
|
||||
|
||||
The validation function will validate the input string using the following rules:
|
||||
.. warning:: The root CA's private key should be protected and kept safe.
|
||||
|
||||
* No blacklisted words like "node", "server".
|
||||
Creating the intermediate CA's keystore
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* Restrict names to Latin scripts for now to avoid right-to-left issues, debugging issues when we can't pronounce names over the phone, and character confusability attacks.
|
||||
1. Create a new keypair
|
||||
|
||||
* Should start with a capital letter.
|
||||
* This will be used as the intermediate CA's keypair
|
||||
|
||||
* No commas or equals signs.
|
||||
2. Obtain a certificate for the keypair signed with the root CA key. The basic constraints extension must be set to
|
||||
``true``
|
||||
|
||||
* No dollars or quote marks, although we may relax the quote mark constraint in future to handle Irish company names.
|
||||
* This will be used as the intermediate CA's certificate
|
||||
|
||||
Starting the Registration
|
||||
-------------------------
|
||||
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
|
||||
|
||||
You will need to specify the working directory of your Corda node using ``--base-dir`` flag. This is defaulted to current directory if left blank.
|
||||
You can also specify the location of ``node.conf`` with ``--config-file`` flag if it's not in the working directory.
|
||||
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.
|
||||
|
||||
**To start the registration**::
|
||||
Creating the node CA keystores
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
java -jar corda.jar --initial-registration --base-dir <<optional>> --config-file <<optional>>
|
||||
1. On each node, create a new keypair
|
||||
|
||||
A ``certificates`` folder containing the keystore and trust store will be created in the base directory when the process is completed.
|
||||
2. Obtain a certificate for the keypair signed with the intermediate CA key. The basic constraints extension must be
|
||||
set to ``true``
|
||||
|
||||
.. warning:: The keystore is protected by the keystore password from the node configuration file. The password should kept safe to protect the private key and certificate.
|
||||
3. Store the keypair in a Java keystore named ``nodekeystore.jks`` using the alias ``cordaclientca``
|
||||
|
||||
Creating the node TLS keystores
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Protocol Design
|
||||
---------------
|
||||
.. note:: This section is intended for developers who want to implement their own doorman service.
|
||||
1. On each node, create a new keypair
|
||||
|
||||
The certificate signing protocol:
|
||||
2. Create a certificate for the keypair signed with the node CA key. The basic constraints extension must be set to
|
||||
``false``
|
||||
|
||||
* Generate a keypair, save it to disk.
|
||||
3. Store the key and certificates in a Java keystore named ``sslkeystore.jks`` using the alias ``cordaclienttls``
|
||||
|
||||
* Generate a CSR using Bouncy Castle or the java crypto APIs containing myLegalName from the config file. We should also have an admin email address in the config file and CSR so we know who to email if anything goes wrong. Sign it with the private key.
|
||||
Installing the certificates on the nodes
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
For each node:
|
||||
|
||||
* HTTPS POST the CSR to the doorman. It creates the server-side records of this request, allocates an ID for it, and then sends back an HTTP redirect to another URL that contains that request ID (which should be sufficiently large that it's not predictable or brute forceable).
|
||||
1. Copy the node's ``nodekeystore.jks`` and ``sslkeystore.jks`` keystores to the node's certificate directory
|
||||
|
||||
* Store that URL to disk.
|
||||
|
||||
* Server goes into a slow polling loop, in which every 10 minutes or so it fetches the URL it was given in the redirect. Mostly it will get 204 No Content. Eventually it will get 200 OK and download the signed certificate in binary form, which it can then stash in its local keystore file.
|
||||
|
||||
The initial registration process uses the following web api to communicate with the doorman service:
|
||||
|
||||
+----------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| Request method | Path | Description |
|
||||
+================+==============================+========================================================================================================================================================+
|
||||
| POST | /api/certificate | Create new certificate request record and stored for further approval process, server will response with a request ID if the request has been accepted.|
|
||||
+----------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| GET | /api/certificate/{requestId} | Retrieve certificates for requestId, the server will return HTTP 204 if request is not yet approved or HTTP 401 if it has been rejected. |
|
||||
+----------------+------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
|
||||
See ``NetworkRegistrationHelper`` and ``X509Utilities`` for examples of certificate signing request creation and certificate signing using Bouncy Castle.
|
||||
2. Copy the ``truststore.jks`` keystore created by the root CA to the node's certificate directory
|
||||
Loading…
Reference in New Issue
Block a user