ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2025-06-19 15:43:52 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Merge OS to Enterprise

Browse Source
This commit is contained in:
szymonsztuka
2018-11-27 12:53:31 +00:00
parent ca1ff6663f 759fd9b5bb
commit 50c2112a2b
55 changed files with 1100 additions and 511 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
docs/source/api-contract-constraints.rst
View File

@ -62,6 +62,58 @@ consumes notary and ledger resources, and is just in general more complex.
.. _implicit_constraint_types:
Contract/State Agreement
------------------------
Starting with Corda 4, ``ContractState``s must explicitly indicate which ``Contract`` they belong to. When a transaction is
verified, the contract bundled with each state in the transaction must be its "owning" contract, otherwise we cannot guarantee that
the transition of the ``ContractState`` will be verified against the business rules that should apply to it.
There are two mechanisms for indicating ownership. One is to annotate the ``ContractState`` with the ``BelongsToContract`` annotation,
indicating the ``Contract`` class to which it is tied:
.. sourcecode:: java
@BelongToContract(MyContract.class)
public class MyState implements ContractState {
// implementation goes here
}
.. sourcecode:: kotlin
@BelongsToContract(MyContract::class)
data class MyState(val value: Int) : ContractState {
// implementation goes here
}
The other is to define the ``ContractState`` class as an inner class of the ``Contract`` class
.. sourcecode:: java
public class MyContract implements Contract {
public static class MyState implements ContractState {
// state implementation goes here
}
// contract implementation goes here
}
.. sourcecode:: kotlin
class MyContract : Contract {
data class MyState(val value: Int) : ContractState
}
If a ``ContractState``'s owning ``Contract`` cannot be identified by either of these mechanisms, and the ``targetVersion`` of the
CorDapp is 4 or greater, then transaction verification will fail with a ``TransactionRequiredContractUnspecifiedException``. If
the owning ``Contract`` _can_ be identified, but the ``ContractState`` has been bundled with a different contract, then
transaction verification will fail with a ``TransactionContractConflictException``.
How constraints work
--------------------

8
docs/source/corda-configuration-file.rst
View File

@ -376,7 +376,7 @@ Configuring a node where the Corda Compatibility Zone's registration and Network
.. literalinclude:: example-code/src/main/resources/example-node-with-networkservices.conf
Fields Override
Fields override
---------------
JVM options or environmental variables prefixed with ``corda.`` can override ``node.conf`` fields.
Provided system properties can also set values for absent fields in ``node.conf``.
@ -387,7 +387,7 @@ This is an example of adding/overriding the keyStore password :
java -Dcorda.rpcSettings.ssl.keyStorePassword=mypassword -jar node.jar
CRL Configuration
CRL configuration
-----------------
The Corda Network provides an endpoint serving an empty certificate revocation list for the TLS-level certificates.
This is intended for deployments that do not provide a CRL infrastructure but still require a strict CRL mode checking.
@ -406,7 +406,9 @@ Together with the above configuration `tlsCertCrlIssuer` option needs to be set
This set-up ensures that the TLS-level certificates are embedded with the CRL distribution point referencing the CRL issued by R3.
In cases where a proprietary CRL infrastructure is provided those values need to be changed accordingly.
Hiding Sensitive Data
.. _corda-configuration-hiding-sensitive-data:
Hiding sensitive data
---------------------
A frequent requirement is that configuration files must not expose passwords to unauthorised readers. By leveraging environment variables, it is possible to hide passwords and other similar fields.

230
docs/source/network-bootstrapper.rst
View File

@ -15,7 +15,7 @@ In addition to the network map, all the nodes must also use the same set of netw
which guarantee interoperability between the nodes. The HTTP network map distributes the network parameters which are downloaded
automatically by the nodes. In the absence of this the network parameters must be generated locally.
For these reasons, test deployments can avail themselves of the network bootstrapper. This is a tool that scans all the
For these reasons, test deployments can avail themselves of the Network Bootstrapper. This is a tool that scans all the
node configurations from a common directory to generate the network parameters file, which is then copied to all the nodes'
directories. It also copies each node's node-info file to every other node so that they can all be visible to each other.
@ -41,7 +41,7 @@ For example running the command on a directory containing these files:
└── partyb_node.conf // Party B's node.conf file
will generate directories containing three nodes: ``notary``, ``partya`` and ``partyb``. They will each use the ``corda.jar``
that comes with the bootstrapper. If a different version of Corda is required then simply place that ``corda.jar`` file
that comes with the Network Bootstrapper. If a different version of Corda is required then simply place that ``corda.jar`` file
alongside the configuration files in the directory.
You can also have the node directories containing their "node.conf" files already laid out. The previous example would be:
@ -56,7 +56,7 @@ You can also have the node directories containing their "node.conf" files alread
└── partyb
└── node.conf
Similarly, each node directory may contain its own ``corda.jar``, which the bootstrapper will use instead.
Similarly, each node directory may contain its own ``corda.jar``, which the Bootstrapper will use instead.
Providing CorDapps to the Network Bootstrapper
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -87,7 +87,7 @@ Any CorDapps provided when bootstrapping a network will be scanned for contracts
The CorDapp JARs will be hashed and scanned for ``Contract`` classes. These contract class implementations will become part
of the whitelisted contracts in the network parameters (see ``NetworkParameters.whitelistedContractImplementations`` :doc:`network-map`).
By default the bootstrapper will whitelist all the contracts found in the unsigned CorDapp JARs (a JAR file not signed by jarSigner tool).
By default the Bootstrapper will whitelist all the contracts found in the unsigned CorDapp JARs (a JAR file not signed by jarSigner tool).
Whitelisted contracts are checked by `Zone constraints`, while contract classes from signed JARs will be checked by `Signature constraints`.
To prevent certain contracts from unsigned JARs from being whitelisted, add their fully qualified class name in the ``exclude_whitelist.txt``.
These will instead use the more restrictive ``HashAttachmentConstraint``.
@ -103,7 +103,7 @@ For example:
Modifying a bootstrapped network
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The network bootstrapper is provided as a development tool for setting up Corda networks for development and testing.
The Network Bootstrapper is provided as a development tool for setting up Corda networks for development and testing.
There is some limited functionality which can be used to make changes to a network, but for anything more complicated consider
using a :doc:`network-map` server.
@ -115,7 +115,7 @@ the nodes are being run on different machines you need to do the following:
* Run the Network Bootstrapper from the root directory
* Copy each individual node's directory back to the original machine
The network bootstrapper cannot dynamically update the network if an existing node has changed something in their node-info,
The Network Bootstrapper cannot dynamically update the network if an existing node has changed something in their node-info,
e.g. their P2P address. For this the new node-info file will need to be placed in the other nodes' ``additional-node-infos`` directory.
If the nodes are located on different machines, then a utility such as `rsync <https://en.wikipedia.org/wiki/Rsync>`_ can be used
so that the nodes can share node-infos.
@ -123,11 +123,11 @@ so that the nodes can share node-infos.
Adding a new node to the network
--------------------------------
Running the bootstrapper again on the same network will allow a new node to be added and its
Running the Bootstrapper again on the same network will allow a new node to be added and its
node-info distributed to the existing nodes.
As an example, if we have an existing bootstrapped network, with a Notary and PartyA and we want to add a PartyB, we
can use the network bootstrapper on the following network structure:
can use the Network Bootstrapper on the following network structure:
.. sourcecode:: none
@ -148,7 +148,7 @@ can use the network bootstrapper on the following network structure:
│ └── node-info-partya
└── partyb_node.conf // the node.conf for the node to be added
Then run the network bootstrapper again from the root dir:
Then run the Network Bootstrapper again from the root dir:
``java -jar network-bootstrapper-VERSION.jar --dir <nodes-root-dir>``
@ -182,19 +182,19 @@ Which will give the following:
├── node-info-partya
└── node-info-partyb
The bootstrapper will generate a directory and the ``node-info`` file for PartyB, and will also make sure a copy of each
The Bootstrapper will generate a directory and the ``node-info`` file for PartyB, and will also make sure a copy of each
nodes' ``node-info`` file is in the ``additional-node-info`` directory of every node. Any other files in the existing nodes,
such a generated keys, will be unaffected.
.. note:: The bootstrapper is provided for test deployments and can only generate information for nodes collected on
the same machine. If a network needs to be updated using the bootstrapper once deployed, the nodes will need
.. note:: The Network Bootstrapper is provided for test deployments and can only generate information for nodes collected on
the same machine. If a network needs to be updated using the Bootstrapper once deployed, the nodes will need
collecting back together.
Updating the contract whitelist for bootstrapped networks
---------------------------------------------------------
If the network already has a set of network parameters defined (i.e. the node directories all contain the same network-parameters
file) then the bootstrapper can be used to append contracts from new CorDapps to the current whitelist.
file) then the Network Bootstrapper can be used to append contracts from new CorDapps to the current whitelist.
For example, with the following pre-generated network:
.. sourcecode:: none
@ -217,7 +217,7 @@ For example, with the following pre-generated network:
│ └── cordapp-a.jar
└── cordapp-b.jar // The new cordapp to add to the existing nodes
Then run the network bootstrapper again from the root dir:
Then run the Network Bootstrapper again from the root dir:
``java -jar network-bootstrapper-VERSION.jar --dir <nodes-root-dir>``
@ -247,81 +247,183 @@ To give the following:
.. note:: The whitelist can only ever be appended to. Once added a contract implementation can never be removed.
Package namespace ownership
----------------------------
Modifying the network parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Package namespace ownership is a Corda security feature that allows a compatibility zone to give ownership of parts of the Java package namespace to registered users (e.g. CorDapp development organisations).
The exact mechanism used to claim a namespace is up to the zone operator. A typical approach would be to accept an SSL
certificate with the domain in it as proof of domain ownership, or to accept an email from that domain.
The Network Bootstrapper creates a network parameters file when bootstrapping a network, using a set of sensible defaults. However, if you would like
to override these defaults when testing, there are two ways of doing this. Options can be overridden via the command line or by supplying a configuration
file. If the same parameter is overridden both by a command line argument and in the configuration file, the command line value
will take precedence.
Overriding network parameters via command line
----------------------------------------------
The ``--minimum-platform-version``, ``--max-message-size``, ``--max-transaction-size`` and ``--event-horizon`` command line parameters can
be used to override the default network parameters. See `Command line options`_ for more information.
Overriding network parameters via a file
----------------------------------------
You can provide a network parameters overrides file using the following syntax:
``java -jar network-bootstrapper-VERSION.jar --network-parameters-overrides=<path_to_file>``
Or alternatively, by using the short form version:
``java -jar network-bootstrapper-VERSION.jar -n=<path_to_file>``
The network parameter overrides file is a HOCON file with the following fields, all of which are optional. Any field that is not provided will be
ignored. If a field is not provided and you are bootstrapping a new network, a sensible default value will be used. If a field is not provided and you
are updating an existing network, the value in the existing network parameters file will be used.
.. note:: All fields can be used with placeholders for environment variables. For example: ``${KEY_STORE_PASSWORD}`` would be replaced by the contents of environment
variable ``KEY_STORE_PASSWORD``. See: :ref:`corda-configuration-hiding-sensitive-data` .
The available configuration fields are listed below:
:minimumPlatformVersion: The minimum supported version of the Corda platform that is required for nodes in the network.
:maxMessageSize: The maximum permitted message size, in bytes. This is currently ignored but will be used in a future release.
:maxTransactionSize: The maximum permitted transaction size, in bytes.
:eventHorizon: The time after which nodes will be removed from the network map if they have not been seen during this period. This parameter uses
the ``parse`` function on the ``java.time.Duration`` class to interpret the data. See `here <https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html#parse-java.lang.CharSequence->`_
for information on valid inputs.
:packageOwnership: A list of package owners. See `Package namespace ownership`_ for more information. For each package owner, the following fields
are required:
:packageName: Java package name (e.g `com.my_company` ).
:keystore: The path of the keystore file containing the signed certificate.
:keystorePassword: The password for the given keystore (not to be confused with the key password).
:keystoreAlias: The alias for the name associated with the certificate to be associated with the package namespace.
An example configuration file:
.. parsed-literal::
minimumPlatformVersion=4
maxMessageSize=10485760
maxTransactionSize=524288000
eventHorizon="30 days"
packageOwnership=[
{
packageName="com.example"
keystore="myteststore"
keystorePassword="MyStorePassword"
keystoreAlias="MyKeyAlias"
}
]
Package namespace ownership
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Package namespace ownership is a Corda security feature that allows a compatibility zone to give ownership of parts of the Java package
namespace to registered users (e.g. a CorDapp development organisation). The exact mechanism used to claim a namespace is up to the zone
operator. A typical approach would be to accept an SSL certificate with the domain in it as proof of domain ownership, or to accept an email from that domain.
.. note:: Read more about *Package ownership* :doc:`here<design/data-model-upgrades/package-namespace-ownership>`.
A Java package namespace is case insensitive and cannot be a sub-package of an existing registered namespace.
See `Naming a Package <https://docs.oracle.com/javase/tutorial/java/package/namingpkgs.html>`_ and `Naming Conventions <https://www.oracle.com/technetwork/java/javase/documentation/codeconventions-135099.html#28840 for guidelines and conventions>`_ for guidelines on naming conventions.
Registration of a java package namespace requires creation of a signed certificate as generated by the
The registration of a Java package namespace requires the creation of a signed certificate as generated by the
`Java keytool <https://docs.oracle.com/javase/8/docs/technotes/tools/windows/keytool.html>`_.
The following four items are passed as a semi-colon separated string to the ``--register-package-owner`` command:
The packages can be registered by supplying a network parameters override config file via the command line, using the ``--network-parameters-overrides`` command.
1. Java package name (e.g `com.my_company` ).
2. Keystore file refers to the full path of the file containing the signed certificate.
3. Password refers to the key store password (not to be confused with the key password).
4. Alias refers to the name associated with a certificate containing the public key to be associated with the package namespace.
For each package to be registered, the following are required:
Let's use the `Example CorDapp <https://github.com/corda/cordapp-example>`_ to initialise a simple network, and then register and unregister a package namespace.
:packageName: Java package name (e.g `com.my_company` ).
:keystore: The path of the keystore file containing the signed certificate. If a relative path is provided, it is assumed to be relative to the
location of the configuration file.
:keystorePassword: The password for the given keystore (not to be confused with the key password).
:keystoreAlias: The alias for the name associated with the certificate to be associated with the package namespace.
Using the `Example CorDapp <https://github.com/corda/cordapp-example>`_ as an example, we will initialise a simple network and then register and unregister a package namespace.
Checkout the Example CorDapp and follow the instructions to build it `here <https://docs.corda.net/tutorial-cordapp.html#building-the-example-cordapp>`_.
.. note:: You can point to any existing bootstrapped corda network (this will have the effect of updating the associated network parameters file).
1. Create a new public key to use for signing the java package namespace we wish to register:
#. Create a new public key to use for signing the Java package namespace we wish to register:
.. code-block:: shell
$JAVA_HOME/bin/keytool -genkeypair -keystore _teststore -storepass MyStorePassword -keyalg RSA -alias MyKeyAlias -keypass MyKeyPassword -dname "O=Alice Corp, L=Madrid, C=ES"
This will generate a key store file called ``_teststore`` in the current directory.
#. Create a ``network-parameters.conf`` file in the same directory, with the following information:
.. parsed-literal::
packageOwnership=[
{
packageName="com.example"
keystore="_teststore"
keystorePassword="MyStorePassword"
keystoreAlias="MyKeyAlias"
}
]
#. Register the package namespace to be claimed by the public key generated above:
.. code-block:: shell
# Register the Java package namespace using the Network Bootstrapper
java -jar network-bootstrapper.jar --dir build/nodes --network-parameter-overrides=network-parameters.conf
#. To unregister the package namespace, edit the ``network-parameters.conf`` file to remove the package:
.. parsed-literal::
packageOwnership=[]
#. Unregister the package namespace:
.. code-block:: shell
# Unregister the Java package namespace using the Network Bootstrapper
java -jar network-bootstrapper.jar --dir build/nodes --network-parameter-overrides=network-parameters.conf
Command line options
~~~~~~~~~~~~~~~~~~~~
The Network Bootstrapper can be started with the following command line options:
.. code-block:: shell
$JAVA_HOME/bin/keytool -genkeypair -keystore _teststore -storepass MyStorePassword -keyalg RSA -alias MyKeyAlias -keypass MyKeyPassword -dname "O=Alice Corp, L=Madrid, C=ES"
This will generate a key store file called ``_teststore`` in the current directory.
2. Register the package namespace to be claimed by the public key generated above:
.. code-block:: shell
# Register the java package namespace using the bootstrapper tool
java -jar network-bootstrapper.jar --dir build/nodes --register-package-owner com.example;./_teststore;MyStorePassword;MyKeyAlias
3. Unregister the package namespace:
.. code-block:: shell
# Unregister the java package namespace using the bootstrapper tool
java -jar network-bootstrapper.jar --dir build/nodes --unregister-package-owner com.example
Command-line options
--------------------
The network bootstrapper can be started with the following command-line options:
.. code-block:: shell
bootstrapper [-hvV] [--no-copy] [--dir=<dir>] [--logging-level=<loggingLevel>]
[--minimum-platform-version=<minimumPlatformVersion>]
[--register-package-owner java-package-namespace=keystore-file:password:alias]
[--unregister-package-owner java-package-namespace]
[COMMAND]
bootstrapper [-hvV] [--no-copy] [--dir=<dir>] [--event-horizon=<eventHorizon>]
[--logging-level=<loggingLevel>]
[--max-message-size=<maxMessageSize>]
[--max-transaction-size=<maxTransactionSize>]
[--minimum-platform-version=<minimumPlatformVersion>]
[-n=<networkParametersFile>] [COMMAND]
* ``--dir=<dir>``: Root directory containing the node configuration files and CorDapp JARs that will form the test network.
It may also contain existing node directories. Defaults to the current directory.
It may also contain existing node directories. Defaults to the current directory.
* ``--no-copy``: Don't copy the CorDapp JARs into the nodes' "cordapps" directories.
* ``--verbose``, ``--log-to-console``, ``-v``: If set, prints logging to the console as well as to a file.
* ``--logging-level=<loggingLevel>``: Enable logging at this level and higher. Possible values: ERROR, WARN, INFO, DEBUG, TRACE. Default: INFO.
* ``--help``, ``-h``: Show this help message and exit.
* ``--version``, ``-V``: Print version information and exit.
* ``--minimum-platform-version``: The minimum platform version to use in the generated network-parameters.
* ``--register-package-owner``: Register a java package namespace with its owners public key.
* ``--unregister-package-owner``: Unregister a java package namespace.
* ``--minimum-platform-version``: The minimum platform version to use in the network-parameters.
* ``--max-message-size``: The maximum message size to use in the network-parameters, in bytes.
* ``--max-transaction-size``: The maximum transaction size to use in the network-parameters, in bytes.
* ``--event-horizon``: The event horizon to use in the network-parameters.
* ``--network-parameter-overrides=<networkParametersFile>``, ``-n=<networkParametersFile>`: Overrides the default network parameters with those
in the given file. See `Overriding network parameters via a file`_ for more information.
Sub-commands
^^^^^^^^^^^^
``install-shell-extensions``: Install ``bootstrapper`` alias and auto completion for bash and zsh. See :doc:`cli-application-shell-extensions` for more info.
------------
``install-shell-extensions``: Install ``bootstrapper`` alias and auto completion for bash and zsh. See :doc:`cli-application-shell-extensions` for more info.

6
docs/source/node-database.rst
View File

@ -395,6 +395,10 @@ By default, the node database has the following tables:
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| NODE_TRANSACTIONS | TX_ID, TRANSACTION_VALUE, STATE_MACHINE_RUN_ID |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| PK_HASH_TO_EXT_ID_MAP | ID, EXTERNAL_ID, PUBLIC_KEY_HASH |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| STATE_PARTY | OUTPUT_INDEX, TRANSACTION_ID, ID, PUBLIC_KEY_HASH, X500_NAME |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| VAULT_FUNGIBLE_STATES | OUTPUT_INDEX, TRANSACTION_ID, ISSUER_NAME, ISSUER_REF, OWNER_NAME, QUANTITY |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| VAULT_FUNGIBLE_STATES_PARTS | OUTPUT_INDEX, TRANSACTION_ID, PARTICIPANTS |
@ -407,6 +411,8 @@ By default, the node database has the following tables:
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| VAULT_TRANSACTION_NOTES | SEQ_NO, NOTE, TRANSACTION_ID |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| V_PKEY_HASH_EX_ID_MAP | ID, PUBLIC_KEY_HASH, TRANSACTION_ID, OUTPUT_INDEX, EXTERNAL_ID |
+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Guideline for adding support for other databases
````````````````````````````````````````````````