From ab4cb7abda6afa976518da34e2466519bcaec331 Mon Sep 17 00:00:00 2001 From: Tudor Malene Date: Fri, 2 Mar 2018 11:59:58 +0000 Subject: [PATCH] CORDA-1050 - docs on whitelisting CorDapps (#2671) (#2694) * CORDA-1050 docs on whitelisting CorDapps * Addressed code review notes * Addressed code review notes (cherry picked from commit 06af213) --- docs/source/network-map.rst | 3 ++ docs/source/setting-up-a-corda-network.rst | 45 ++++++++++++++++++++++ 2 files changed, 48 insertions(+) diff --git a/docs/source/network-map.rst b/docs/source/network-map.rst index 58719583dc..50bb2a6496 100644 --- a/docs/source/network-map.rst +++ b/docs/source/network-map.rst @@ -114,6 +114,9 @@ The current set of network parameters: :epoch: Version number of the network parameters. Starting from 1, this will always increment whenever any of the parameters change. +:whitelistedContractImplementations: List of whitelisted versions of contract code. + For each contract class there is a list of hashes of the approved CorDapp jar versions containing that contract. + Read more about *Zone constraints* here :doc:`api-contract-constraints` More parameters will be added in future releases to regulate things like allowed port numbers, how long a node can be offline before it is evicted from the zone, whether or not IPv6 connectivity is required for zone members, required diff --git a/docs/source/setting-up-a-corda-network.rst b/docs/source/setting-up-a-corda-network.rst index 31205b93d2..138d5db9c0 100644 --- a/docs/source/setting-up-a-corda-network.rst +++ b/docs/source/setting-up-a-corda-network.rst @@ -88,6 +88,51 @@ in the other nodes' ``additional-node-infos`` directory. A simple way to do this However, if it's known beforehand the set of nodes that will eventually the node folders can be pregenerated in the bootstrap and only started when needed. + +Whitelisting Contracts +~~~~~~~~~~~~~~~~~~~~~~ + +If you want to create a *Zone whitelist* (see :doc:`api-contract-constraints`), you can pass in a list of CorDapp jars: + +``java -jar network-bootstrapper.jar ..`` + +The CorDapp jars will be hashed and scanned for ``Contract`` classes. +By default the tool would generate a file named ``whitelist.txt`` containing an entry for each contract with the hash of the jar. + +For example: + +.. sourcecode:: none + + net.corda.finance.contracts.asset.Obligation:decd098666b9657314870e192ced0c3519c2c9d395507a238338f8d003929de8 + net.corda.finance.contracts.asset.Cash:decd098666b9657314870e192ced0c3519c2c9d395507a238338f8d003929de9 + +These will be added to the ``NetworkParameters.whitelistedContractImplementations``. See :doc:`network-map`. + +This means that by default the Network bootstrapper tool will whitelist all contracts found in all passed CorDapps. + +In case there is a ``whitelist.txt`` file in the root dir already, the tool will append the new jar hashes or contracts to it. + +The zone operator will maintain this whitelist file, and, using the tool, will append new versions of CorDapps to it. + +.. warning:: + - The zone operator must ensure that this file is *append only*. + - If the operator removes hashes from the list, all transactions pointing to that version will suddenly fail the constraint verification, and the entire chain is compromised. + - If a contract is removed from the whitelist, then all states created from that moment on will be constrained by the HashAttachmentConstraint. + + Note: In future releases, we will provider a tamper-proof way of maintaining the contract whitelist. + +For fine-grained control of constraints, in case multiple contracts live in the same jar, the tool reads from another file: +``exclude_whitelist.txt``, which contains a list of contracts that should not be whitelisted, and thus default to the very restrictive: +``HashAttachmentConstraint`` + +For example: + +.. sourcecode:: none + + net.corda.finance.contracts.asset.Cash + net.corda.finance.contracts.asset.CommercialPaper + + Starting the nodes ~~~~~~~~~~~~~~~~~~