corda/docs/source/key-concepts-identity.rst

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