mirror of
https://github.com/corda/corda.git
synced 2024-12-26 08:01:09 +00:00
1723838a59
* Address minor comments on confidential identities docs * Expand on implementation details of confidential identities * Cleanup * Clarify details of the data blob in the swap identites flow * Add that certificate path is not made public for confidential identities
78 lines
4.6 KiB
ReStructuredText
78 lines
4.6 KiB
ReStructuredText
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:
|
|
|
|
* Legal identity of an organisation
|
|
* Service identity of a network service
|
|
|
|
Legal identities are used for parties in a transaction, such as the owner of a cash state. Service identities are used
|
|
for those providing transaction-related services, such as notary, or oracle. Service identities are distinct to 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.
|
|
|
|
Name
|
|
----
|
|
|
|
Identity names are X.500 distinguished names with Corda-specific constraints applied. In order to be compatible with
|
|
other implementations (particularly TLS implementations), we constrain the allowed X.500 attribute types to a subset of
|
|
the minimum supported set for X.509 certificates (specified in RFC 3280), plus the locality attribute:
|
|
|
|
* organization (O)
|
|
* state (ST)
|
|
* locality (L)
|
|
* country (C)
|
|
* organizational-unit (OU)
|
|
* common name (CN) - used only for service identities
|
|
|
|
The organisation, locality and country attributes are required, while state, organisational-unit and common name are
|
|
optional. Attributes cannot be be present more than once in the name. The "country" code is strictly restricted to valid
|
|
ISO 3166-1 two letter codes.
|
|
|
|
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.
|
|
|
|
.. TODO: Revisit once design & use cases of private maps is further fleshed out |