ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2025-04-07 11:27:01 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Address feedback on confidential identities docs (#1701)

Browse Source 
* 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
This commit is contained in:
Ross Nicoll 2017-09-28 15:20:29 +01:00 committed by josecoll
parent 183cc15808
commit 1723838a59
2 changed files with 33 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
docs/source/api-identity.rst
View File

@ -38,10 +38,10 @@ scenario the certificate path proves its issuance by the Doorman service.
Confidential Identities
-----------------------
Confidential identities are key pairs where the corresponding X.509 certificate is not made public, so that parties who
Confidential identities are key pairs where the corresponding X.509 certificate (and path) are not made public, so that parties who
are not involved in the transaction cannot identify its participants. They are owned by a well known identity, which
must sign the X.509 certificate. Before constructing a new transaction the involved parties must generate and send new
confidential identities to each other, a process which managed using ``SwapIdentitiesFlow`` (discussed below). The
confidential identities to each other, a process which is managed using ``SwapIdentitiesFlow`` (discussed below). The
public keys of these confidential identities are then used when generating output states and commands for the transaction.
Where using outputs from a previous transaction in a new transaction, counterparties may need to know who the involved
@ -72,18 +72,20 @@ You can see an example of it being used in ``TwoPartyDealFlow.kt``:
The swap identities flow goes through the following key steps:
1. Generate a nonce value.
1. Generate a nonce value to form a challenge to the other nodes.
2. Send nonce value to all counterparties, and receive their nonce values.
3. Generate a new confidential identity from our well known identity.
4. Create a data blob containing the new confidential identity, plus the hash of the nonce values.
5. Sign the resulting data blob with the confidential identity's public key.
6. Send the confidential identity, data blob signature to all counterparties, while receiving theirs.
4. Create a data blob containing the new confidential identity (public key, name and X.509 certificate path),
and the hash of the nonce values.
5. Sign the resulting data blob with the confidential identity's private key.
6. Send the confidential identity and data blob signature to all counterparties, while receiving theirs.
7. Verify the signatures to ensure that identities were generated by the involved set of parties.
8. Verify the confidential identities are owned by the expected well known identities.
9. Store the confidential identities and return them to the calling flow.
This ensures not only that the confidential identity certificates are signed by the correct well known identity, but
also that the confidential identity private key is held by the counterparty.
This ensures not only that the confidential identity X.509 certificates are signed by the correct well known identities,
but also that the confidential identity private key is held by the counterparty, and that a party cannot claim ownership
another party's confidential identities belong to its well known identity.
Identity synchronization flow
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -101,8 +103,27 @@ entities (counterparties) to require to know which well known identities those c
The identity synchronization flow goes through the following key steps:
1. Extract participant identities from all input and output states and remove any well known identities.
1. Extract participant identities from all input and output states and remove any well known identities. Required signers
on commands are currently ignored as they are presumed to be included in the participants on states, or to be well
known identities of services (such as an oracle service).
2. For each counterparty node, send a list of the public keys of the confidential identities, and receive back a list
of those the counterparty needs the certificate path for.
3. Verify the requested list of identities contains only confidential identities in the offered list, and abort otherwise.
4. Send the requested confidential identities as ``PartyAndCertificate`` instances to the counterparty.
.. note:: ``IdentitySyncFlow`` works on a push basis. The initiating node can only send confidential identities it has
the X.509 certificates for, and the remote nodes can only request confidential identities being offered (are
referenced in the transaction passed to the initiating flow). There is no standard flow for nodes to collect
confidential identities before assembling a transaction, and this is left for individual flows to manage if required.
``IdentitySyncFlow`` will serve all confidential identities in the provided transaction, irrespective of well known
identity. This is important for more complex transaction cases with 3+ parties, for example:
* Alice is building the transaction, and provides some input state *x* owned by a confidential identity of Alice
* Bob provides some input state *y* owned by a confidential identity of Bob
* Charlie provides some input state *z* owned by a confidential identity of Charlie
Alice may know all of the confidential identities ahead of time, but Bob not know about Charlie's and vice-versa.
The assembled transaction therefore has three input states *x*, *y* and *z*, for which only Alice possesses certificates
for all confidential identities. ``IdentitySyncFlow`` must send not just Alice's confidential identity but also any other
identities in the transaction to the Bob and Charlie.

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

@ -26,7 +26,7 @@ certificate path to a trusted root certificate) is published:
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
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
@ -56,7 +56,8 @@ 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.
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