ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2024-12-18 20:47:57 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Removes Identity page. Reworks it into the Network page. (#3687)

Browse Source 
* Removes Identity page. Reworks it into the Network page.

* Removes stray doorman reference.

* Addresses review feedback.
This commit is contained in:
Joel Dudley 2018-07-25 13:13:10 +01:00 committed by GitHub
parent 6b320026a1
commit 9571f7d905
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 31 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
docs/source/key-concepts-ecosystem.rst
View File

@ -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.

62
docs/source/key-concepts-identity.rst
View File

@ -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.

1
docs/source/key-concepts.rst
View File

@ -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