mirror of
https://github.com/corda/corda.git
synced 2025-04-19 08:36:39 +00:00
Merge pull request #1303 from corda/chrisr3-os-merge
Merge up to 78b61d4a
This commit is contained in:
Chris Rankin
GitHub
commit
c9a747f759
@ -4,41 +4,44 @@ The network
|
||||
.. topic:: Summary
|
||||
|
||||
* *A Corda network is made up of nodes running Corda and CorDapps*
|
||||
* *The network is permissioned, with access controlled by a doorman*
|
||||
* *Communication between nodes is point-to-point, instead of relying on global broadcasts*
|
||||
* *Each node has a certificate mapping their network identity to a real-world legal identity*
|
||||
* *The network is permissioned, with access requiring a certificate from the network operator*
|
||||
|
||||
Network structure
|
||||
-----------------
|
||||
A Corda network is an authenticated peer-to-peer network of nodes, where each node is a JVM run-time environment
|
||||
hosting Corda services and executing applications known as *CorDapps*.
|
||||
|
||||
All communication between nodes is direct, with TLS-encrypted messages sent over AMQP/1.0. This means that data is
|
||||
shared only on a need-to-know basis; in Corda, there are **no global broadcasts**.
|
||||
|
||||
Each network has a **network map service** that publishes the IP addresses through which every node on the network can
|
||||
be reached, along with the identity certificates of those nodes and the services they provide.
|
||||
|
||||
The doorman
|
||||
-----------
|
||||
Corda networks are semi-private. Each network has a doorman service that enforces rules regarding the information
|
||||
that nodes must provide and the know-your-customer processes that they must complete before being admitted to the
|
||||
network.
|
||||
|
||||
To join the network, a node must contact the doorman and provide the required information. If the doorman is
|
||||
satisfied, the node will receive a root-authority-signed TLS certificate from the network's permissioning service.
|
||||
This certificate certifies the node's identity when communicating with other participants on the network.
|
||||
|
||||
We can visualize a network as follows:
|
||||
A Corda network is a peer-to-peer network of **nodes**. Each node runs the Corda software as well as Corda applications
|
||||
known as **CorDapps**.
|
||||
|
||||
.. image:: resources/network.png
|
||||
:scale: 25%
|
||||
:align: center
|
||||
|
||||
Network services
|
||||
----------------
|
||||
Nodes can provide several types of services:
|
||||
All communication between nodes is point-to-point and encrypted using transport-layer security. This means that data is
|
||||
shared only on a need-to-know basis. There are **no global broadcasts**.
|
||||
|
||||
* One or more pluggable **notary services**. Notaries guarantee the uniqueness, and possibility the validity, of ledger
|
||||
updates. Each notary service may be run on a single node, or across a cluster of nodes.
|
||||
* Zero or more **oracle services**. An oracle is a well-known service that signs transactions if they state a fact and
|
||||
that fact is considered to be true.
|
||||
Identity
|
||||
--------
|
||||
Each node has a single well-known identity. The node's identity is used to represent the node in transactions, such as
|
||||
when purchasing an asset.
|
||||
|
||||
.. note:: These identities are distinct from the RPC user logins that are able to connect to the node via RPC.
|
||||
|
||||
Each network has a **network map service** that maps each well-known node identity to an IP address. These IP
|
||||
addresses are used for messaging between nodes.
|
||||
|
||||
Nodes can also generate confidential identities for individual transactions. The certificate chain linking a
|
||||
confidential identity to a well-known node identity or real-world legal identity is only distributed on a need-to-know
|
||||
basis. This ensures that even if an attacker gets access to an unencrypted transaction, they cannot identify the
|
||||
transaction's participants without additional information if confidential identities are being used.
|
||||
|
||||
Admission to the network
|
||||
------------------------
|
||||
Corda networks are semi-private. To join a network, a node must obtain a certificate from the network operator. This
|
||||
certificate maps a well-known node identity to:
|
||||
|
||||
* A real-world legal identity
|
||||
* A public key
|
||||
|
||||
The network operator enforces rules regarding the information that nodes must provide and the know-your-customer
|
||||
processes they must undergo before being granted this certificate.
|
||||
@ -1,62 +0,0 @@
|
||||
Identity
|
||||
========
|
||||
|
||||
.. topic:: Summary
|
||||
|
||||
* *Identities in Corda can represent legal identities or service identities*
|
||||
* *Identities are attested to by X.509 certificate signed by the Doorman or a well known identity*
|
||||
* *Well known identities are published in the network map*
|
||||
* *Confidential identities are only shared on a need to know basis*
|
||||
|
||||
Identities in Corda can represent:
|
||||
|
||||
* The legal identity of an organisation
|
||||
* The service identity of a network service
|
||||
|
||||
These identities are distinct from the RPC users that are able to connect to the node via RPC.
|
||||
|
||||
Identity types
|
||||
--------------
|
||||
|
||||
Whereas legal identities are used to represent parties in transactions, such as the owner of a cash state, service identities
|
||||
are used for entities providing transaction-related services, such as notaries or oracles. Service identities are distinct
|
||||
from legal identities so that distributed services can exist on nodes owned by different organisations. Such distributed service identities are based on ``CompositeKeys``, which describe the valid sets of signers for a signature from the service.
|
||||
See :doc:`api-core-types` for more technical detail on composite keys.
|
||||
|
||||
Identities are either well known or confidential, depending on whether their X.509 certificate (and corresponding
|
||||
certificate path to a trusted root certificate) is published:
|
||||
|
||||
* Well known identities are the generally identifiable public key of a legal entity or service, which makes them
|
||||
ill-suited to transactions where confidentiality of participants is required. This certificate is published in the
|
||||
network map service for anyone to access.
|
||||
* Confidential identities are only published to those who are involved in transactions with the identity. The public
|
||||
key may be exposed to third parties (for example to the notary service), but distribution of the name and X.509
|
||||
certificate is limited.
|
||||
|
||||
Although there are several elements to the Corda transaction privacy model, including ensuring that transactions are
|
||||
only shared with those who need to see them, and planned use of Intel SGX, it is important to provide defense in depth against
|
||||
privacy breaches. Confidential identities are used to ensure that even if a third party gets access to an unencrypted
|
||||
transaction, they cannot identify the participants without additional information.
|
||||
|
||||
Certificates
|
||||
------------
|
||||
|
||||
Nodes must be able to verify the identity of the owner of a public key, which is achieved using X.509 certificates.
|
||||
When first run a node generates a key pair and submits a certificate signing request to the network Doorman service
|
||||
(see :doc:`permissioning`).
|
||||
The Doorman service applies appropriate identity checks then issues a certificate to the node, which is used as the
|
||||
node certificate authority (CA). From this initial CA certificate the node automatically creates and signs two further
|
||||
certificates, a TLS certificate and a signing certificate for the node's well known identity. Finally the node
|
||||
builds a node info record containing its address and well known identity, and registers it with the network map service.
|
||||
|
||||
From the signing certificate the organisation can create both well known and confidential identities. Use-cases for
|
||||
well known identities include clusters of nodes representing a single identity for redundancy purposes, or creating
|
||||
identities for organisational units.
|
||||
|
||||
It is up to organisations to decide which identities they wish to publish in the network map service, making them
|
||||
well known, and which they wish to keep as confidential identities for privacy reasons (typically to avoid exposing
|
||||
business sensitive details of transactions). In some cases nodes may also use private network map services in addition
|
||||
to the main network map service, for operational reasons. Identities registered with such network maps must be
|
||||
considered well known, and it is never appropriate to store confidential identities in a central directory without
|
||||
controls applied at the record level to ensure only those who require access to an identity can retrieve its
|
||||
certificate.
|
||||
@ -13,7 +13,6 @@ This section should be read in order:
|
||||
|
||||
key-concepts-ecosystem
|
||||
key-concepts-ledger
|
||||
key-concepts-identity
|
||||
key-concepts-states
|
||||
key-concepts-contracts
|
||||
key-concepts-transactions
|
||||
|
||||
@ -22,64 +22,10 @@ Upgrading to |release| from Open Source 3.x requires updating build file propert
|
||||
|
||||
.. sourcecode:: shell
|
||||
|
||||
<<<<<<< HEAD
|
||||
ext.corda_release_distribution = 'com.r3.corda'
|
||||
ext.corda_release_version = '3.1'
|
||||
ext.corda_gradle_plugins_version = '4.0.25'
|
||||
..
|
||||
=======
|
||||
ext.kotlin_version = '1.1.4'
|
||||
ext.quasar_version = '0.7.9'
|
||||
|
||||
Please consult the relevant release notes of the release in question. If not specified, you may assume the
|
||||
versions you are currently using are still in force.
|
||||
|
||||
We also strongly recommend cross referencing with the :doc:`changelog` to confirm changes.
|
||||
|
||||
UNRELEASED
|
||||
----------
|
||||
|
||||
<<< Fill this in >>>
|
||||
|
||||
* Database upgrade - Change the type of the ``checkpoint_value``.
|
||||
This will address the issue that the `vacuum` function is unable to clean up deleted checkpoints as they are still referenced from the ``pg_shdepend`` table.
|
||||
|
||||
For Postgres:
|
||||
|
||||
.. sourcecode:: sql
|
||||
|
||||
ALTER TABLE node_checkpoints ALTER COLUMN checkpoint_value set data type bytea;
|
||||
|
||||
For H2:
|
||||
|
||||
.. sourcecode:: sql
|
||||
|
||||
ALTER TABLE node_checkpoints ALTER COLUMN checkpoint_value set data type VARBINARY(33554432);
|
||||
|
||||
|
||||
* API change: ``net.corda.core.schemas.PersistentStateRef`` fields (``index`` and ``txId``) incorrectly marked as nullable are now non-nullable,
|
||||
:doc:`changelog` contains the explanation.
|
||||
|
||||
H2 database upgrade action:
|
||||
|
||||
For Cordapps persisting custom entities with ``PersistentStateRef`` used as non Primary Key column, the backing table needs to be updated,
|
||||
In SQL replace ``your_transaction_id``/``your_output_index`` column names with your custom names, if entity didn't used JPA ``@AttributeOverrides``
|
||||
then default names are ``transaction_id`` and ``output_index``.
|
||||
|
||||
.. sourcecode:: sql
|
||||
|
||||
SELECT count(*) FROM [YOUR_PersistentState_TABLE_NAME] WHERE your_transaction_id IS NULL OR your_output_index IS NULL;
|
||||
|
||||
In case your table already contains rows with NULL columns, and the logic doesn't distinguish between NULL and an empty string,
|
||||
all NULL column occurrences can be changed to an empty string:
|
||||
|
||||
.. sourcecode:: sql
|
||||
|
||||
UPDATE [YOUR_PersistentState_TABLE_NAME] SET your_transaction_id="" WHERE your_transaction_id IS NULL;
|
||||
UPDATE [YOUR_PersistentState_TABLE_NAME] SET your_output_index="" WHERE your_output_index IS NULL;
|
||||
|
||||
If all rows have NON NULL ``transaction_ids`` and ``output_idx`` or you have assigned empty string values, then it's safe to update the table:
|
||||
>>>>>>> 121dbec87700856679baab3995352448e8214b4e
|
||||
|
||||
and specifying an additional repository entry to point to the location of the Corda Enterprise distribution. As an example:
|
||||
|
||||
|
||||
@ -15,10 +15,6 @@ include 'confidential-identities'
|
||||
include 'finance'
|
||||
include 'finance:isolated'
|
||||
include 'core'
|
||||
include 'core-deterministic'
|
||||
include 'core-deterministic:testing'
|
||||
include 'core-deterministic:testing:common'
|
||||
include 'core-deterministic:testing:data'
|
||||
include 'docs'
|
||||
include 'node-api'
|
||||
include 'node'
|
||||
@ -81,7 +77,6 @@ include 'samples:business-network-demo'
|
||||
include 'samples:cordapp-configuration'
|
||||
include 'samples:network-verifier'
|
||||
include 'serialization'
|
||||
include 'serialization-deterministic'
|
||||
include 'cordform-common'
|
||||
include 'hsm-tool'
|
||||
include 'launcher'
|
||||
@ -89,3 +84,11 @@ include 'node:dist'
|
||||
include 'tools:notary-healthcheck:contract'
|
||||
include 'tools:notary-healthcheck:cordapp'
|
||||
include 'tools:notary-healthcheck:client'
|
||||
|
||||
if (JavaVersion.current() == JavaVersion.VERSION_1_8) {
|
||||
include 'core-deterministic'
|
||||
include 'core-deterministic:testing'
|
||||
include 'core-deterministic:testing:common'
|
||||
include 'core-deterministic:testing:data'
|
||||
include 'serialization-deterministic'
|
||||
}
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user