From be81e9b62027a0377a8b44a27a8fe8bf4631325c Mon Sep 17 00:00:00 2001 From: Patrick Kuo Date: Thu, 24 Nov 2016 16:38:40 +0000 Subject: [PATCH 1/2] permissioning doc --- docs/source/corda-configuration-files.rst | 9 ++++ docs/source/index.rst | 3 +- docs/source/permissioning.rst | 64 +++++++++++++++++++++++ 3 files changed, 75 insertions(+), 1 deletion(-) create mode 100644 docs/source/permissioning.rst diff --git a/docs/source/corda-configuration-files.rst b/docs/source/corda-configuration-files.rst index e0fbbdf9a7..dde866278c 100644 --- a/docs/source/corda-configuration-files.rst +++ b/docs/source/corda-configuration-files.rst @@ -39,6 +39,9 @@ NetworkMapService plus Simple Notary configuration file. webAddress : "localhost:12346" extraAdvertisedServiceIds: "" useHTTPS : false + devMode = true + // Certificate signing service will be hosted by R3 in the near future. + //certificateSigningService = "https://testnet.certificate.corda.net" Configuration File Fields ------------------------- @@ -94,3 +97,9 @@ Configuration File Fields :permissions: A list of permission strings which RPC methods can use to control access If this field is absent or an empty list then RPC is effectively locked down. + +:devMode: + This flag indicate if the node is running in development mode. On startup, if the keystore ``/certificates/sslkeystore.jks`` does not exist, a developer keystore will be used if ``devMode`` is true. The node will exit if ``devMode`` is false and keystore does not exist. + +:certificateSigningService: + Certificate Signing Server address. It is used by the certificate signing request utility to obtain SSL certificate. (See :doc:`permissioning` for more information.) diff --git a/docs/source/index.rst b/docs/source/index.rst index 112b1043ab..3a789907bd 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -51,6 +51,8 @@ Read on to learn: corda-configuration-files corda-plugins node-services + node-explorer + permissioning .. toctree:: :maxdepth: 2 @@ -78,7 +80,6 @@ Read on to learn: :caption: Other network-simulator - node-explorer initial-margin-agreement .. toctree:: diff --git a/docs/source/permissioning.rst b/docs/source/permissioning.rst new file mode 100644 index 0000000000..e9fe5d487d --- /dev/null +++ b/docs/source/permissioning.rst @@ -0,0 +1,64 @@ +Network Permissioning +===================== + +The keystore located in ``/certificates/sslkeystore.jks`` is required to connect to the Corda network securely. +In development mode (when ``devMode = true``, see :doc:`corda-configuration-files` 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. + +However this is not secure for the real network. This documentation will explain the procedure of obtaining a signed certificate for TestNet. + +.. warning:: The TestNet has not been setup yet as of Milestone 6 release. You will not be able to connect to the certificate signing server. + +Certificate Signing Request Utility +----------------------------------- + +The utility creates certificate signing request based on node information obtained from the node configuration. +The following information from the node configuration file is needed to generate a certificate signing request. + +:myLegalName: Your company's legal name. e.g. "R3 CEV, LLC" + +:nearestCity: e.g. "London" + +:emailAddress: e.g. "admin@company.com" + +:certificateSigningService: Certificate signing server URL. A certificate signing 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 will be generated by the utility and 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. +Once the request has been approved and the certificates downloaded from the server, the utility will create the key store and trust store using the certificates and the generated private key. + +.. note:: You can exit the utility at anytime if the approval process is taking longer then expected. The request process will resume on restart. + +This process only needs to be done once when the node connects to the network for the first time, or when the certificate expires. + +Building the Utility +-------------------- +The utility will be created as part of the main build ``buildCordaJAR``. +You can also build the utility JAR by run the following command from the Corda project root directory. + +**Windows**:: + + gradlew.bat buildCertSigningRequestUtilityJAR + +**Other**:: + + ./gradlew buildCertSigningRequestUtilityJAR + +The utility JAR will be created in ``/build/libs/certSigningRequestUtility.jar`` + + +Running the Utility +------------------- + +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. + +**Running the Utility**:: + + java -jar certSigningRequestUtility.jar --base-dir <> --config-file <> + +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. +.. note:: Password encryption in node configuration will be supported in subsequent release. \ No newline at end of file From 55ea753c52335b5060f2b87a97c538a5e82071eb Mon Sep 17 00:00:00 2001 From: Patrick Kuo Date: Fri, 25 Nov 2016 16:35:43 +0000 Subject: [PATCH 2/2] Added dev mode to the example config --- docs/source/example-code/src/main/resources/example-node.conf | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/source/example-code/src/main/resources/example-node.conf b/docs/source/example-code/src/main/resources/example-node.conf index c52a6f3e01..dc4456e2d2 100644 --- a/docs/source/example-code/src/main/resources/example-node.conf +++ b/docs/source/example-code/src/main/resources/example-node.conf @@ -17,3 +17,6 @@ useHTTPS : false rpcUsers : [ { user=user1, password=letmein, permissions=[ StartProtocol.net.corda.protocols.CashProtocol ] } ] +devMode = true +// Certificate signing service will be hosted by R3 in the near future. +//certificateSigningService = "https://testnet.certificate.corda.net" \ No newline at end of file