ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2025-01-31 00:24:59 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

added protocol design to the permissioning doc (#448)

Browse Source
This commit is contained in:
Patrick Kuo 2017-03-28 16:27:53 +01:00 committed by GitHub
parent 3dea759587
commit a47a45037d
1 changed files with 33 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
docs/source/permissioning.rst
View File

@ -1,5 +1,5 @@
Network permissioning
=====================
Network permissioning (Doorman)
===============================
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
@ -26,12 +26,12 @@ The following information from the node configuration file is needed to generate
:emailAddress: e.g. "admin@company.com"
:certificateSigningService: Certificate signing server URL. A certificate signing server will be hosted by R3 in the near
:certificateSigningService: Doorman server URL. A doorman server will be hosted by R3 in the near
future. e.g."https://testnet.certificate.corda.net"
A new pair of private and public keys generated by the Corda node will be used to create the request.
The utility will submit the request to the network permissioning server and poll for a result periodically to retrieve the certificates.
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.
.. 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.
@ -52,3 +52,32 @@ You can also specify the location of ``node.conf`` with ``--config-file`` flag i
A ``certificates`` folder containing the keystore and trust store will be created in the base directory when the process is completed.
.. 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.
Protocol Design
---------------
.. note:: This section is intended for developers who want to implement their own doorman service.
The certificate signing protocol:
* Generate a keypair, save it to disk.
* 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.
* 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).
* 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.