poanetwork
/
quorum
mirror of https://github.com/poanetwork/quorum.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Update Tessera encryption & Privacy Manager docs (#972)

This commit is contained in:
chris-j-h 2020-04-18 18:24:34 +01:00 committed by GitHub
parent c9e8488785
commit f429be1dd8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 187 additions and 149 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/FAQ.md
View File

@ -10,16 +10,16 @@
1. Enabling transaction Senders to create a private transaction by marking who is privy to that transaction via the `privateFor` parameter
2. Replacing the payload of a private transaction with a hash of the encrypted payload, such that the original payload is not visible to participants who are not privy to the transaction
3. Storing encrypted private data off-chain in a separate component called the Transaction Manager (provided by [Constellation](https://github.com/jpmorganchase/constellation) or [Tessera](https://github.com/jpmorganchase/tessera)). The Transaction Manager distributes the encrypted data to other parties that are privy to the transaction and returns the decrypted payload to those parties
3. Storing encrypted private data off-chain in a separate component called the Privacy Manager (provided by [Constellation](https://github.com/jpmorganchase/constellation) or [Tessera](https://github.com/jpmorganchase/tessera)). The Privacy Manager distributes the encrypted data to other parties that are privy to the transaction and returns the decrypted payload to those parties
Please see the [Transaction Processing](../Transaction%20Processing/Transaction%20Processing) page for more info.
Please see the [Transaction and Contract Privacy](../Privacy/Overview) section for more info.
??? question "How does Quorum achieve consensus on Private Transactions?"
In standard Ethereum, all nodes process all transactions and so each node has the same state root. In Quorum, nodes process all 'public' transactions (which might include reference data or market data contracts for example) but only process the private transactions that they are party to.
Quorum nodes maintain two Patricia Merkle Tries: one for private state and one for public state. As a result, block validation includes a **state** check on the new-to-Quorum `public state root`. Block validation also includes a check of the `global Transaction hash`, which is a hash of **all** Transactions in a block - private and public. This means that each node is able to validate that it has the same set of Transactions as other nodes. Since the EVM is provably deterministic through the synchronized public state root, and that the Private Transaction inputs are known to be in sync across nodes (global Transaction Hash), private state synchronization across nodes can be implied. In addition, Quorum provides an API call, `eth_storageRoot`, that returns the private state hash for a given transaction at a given block height, that can optionally be called at the application layer to specifically perform an off-chain state validation with a counterparty.
Please see the [Quorum Consensus](../Consensus/Consensus) and [Transaction Processing](../Transaction%20Processing/Transaction%20Processing) pages for more info.
Please see the [Quorum Consensus](../Consensus/Consensus) and [Transaction and Contract Privacy Overview](../Privacy/Overview) pages for more info.
??? question "Are there any restrictions on the transaction size for private transactions (since they are encrypted)?"
The only restriction is the gas limit on the transaction. Constellation/Tessera does not have a size limit (although maybe it should be possible to set one). If anything, performing large transactions as private transactions will improve performance because most of the network only sees hash digests. In terms of performance of transferring large data blobs between geographically distributed nodes, it would be equivalent performance to PGP encrypting the file and transferring it over http/https..so very fast. If you are doing sequential transactions then of course you will have to wait for those transfers, but there is no special overhead by the payload being large if you are doing separate/concurrent transactions, subject to network bandwidth limits. Constellation/Tessera does everything in parallel.

2
docs/Getting Started/running.md
View File

@ -1,7 +1,7 @@
# Running Quorum
## Developing Smart Contracts
Quorum uses standard [Solidity](https://solidity.readthedocs.io/en/develop/) for writing Smart Contracts, and generally, these can be designed as you would design Smart Contracts for Ethereum. Smart Contracts can either be public (i.e. visible and executable by all participants on a given Quorum network) or private to one or more network participants. Note, however, that Quorum does not introduce new contract Types. Instead, similar to [Transactions](../../Transaction%20Processing/Transaction%20Processing), the concept of public and private contracts is notional only.
Quorum uses standard [Solidity](https://solidity.readthedocs.io/en/develop/) for writing Smart Contracts, and generally, these can be designed as you would design Smart Contracts for Ethereum. Smart Contracts can either be public (i.e. visible and executable by all participants on a given Quorum network) or private to one or more network participants. Note, however, that Quorum does not introduce new contract Types. Instead, similar to [Transactions](../../Privacy/Overview), the concept of public and private contracts is notional only.
### Creating Public Transactions/Contracts

46
docs/Privacy/Lifecycle-of-a-private-transaction.md Normal file
View File

@ -0,0 +1,46 @@
Below is a description of how Private Transactions are processed in Quorum:
![Quorum Tessera Privacy Flow](https://github.com/jpmorganchase/tessera/raw/master/Tessera%20Privacy%20flow.jpeg)
In this example, Party A and Party B are party to Transaction AB, whilst Party C is not.
1. Party A sends a Transaction to their Quorum Node, specifying the Transaction payload and setting `privateFor` to be the public keys for Parties A and B (Party A is optional)
1. Party A's Quorum Node passes the Transaction on to its paired Transaction Manager, requesting that it encrypt and store the Transaction payload before forwarding it on to the recipients of the transaction (i.e. Party B)
1. Party A's Transaction Manager makes a call to its associated Enclave to encrypt the payload for the given recipients
1. Party A's Enclave encrypts the private transaction payload by:
1. generating a symmetric key (which will be referred to as *tx-key* from here on) and two random nonces
1. encrypting the Transaction payload with this tx-key and one of the nonces
1. encrypting the tx-key separately for each recipient by:
1. deriving the ECDH (elliptic-curve Diffie-Hellman) shared symmetric key (*shared-key*) from the sender's (A's) private key and the recipient's (B's) public key
1. encrypting the tx-key with the shared-key and the other nonce
1. repeating this for all recipients (i.e. for *n* recipients there will be *n* unique encrypted tx-keys) (the nonce is unchanged for each recipient as the shared-key being used changes)
1. returning to the Transaction Manager: the encrypted transaction payload, all encrypted tx-keys, both nonces, and the public keys of the sender and all recipients
1. Party A's Transaction Manager stores the response from the Enclave and forwards to the private transaction recipients by:
1. calculating the SHA3-512 hash of the encrypted payload (this acts as the unique identifier/primary key in the database)
1. storing the hash, encrypted payload, all encrypted tx-keys, both nonces, and the public keys of the sender and all recipients in the database
1. sending the response from the Enclave to each recipient by:
1. sanitising the response for each recipient (i.e. removing all encrypted tx-keys except for the one intended for that recipient)
1. serialising the data
1. pushing the serialised data to the recipient (in this case Party B's Transaction Manager)
1. ensuring the push was successful (if a single recipient fails to respond or returns an error then the process will stop here - i.e. it is a requirement that all recipients have stored the encrypted payload before the transaction can be propagated at the Quorum level and written to the blockchain)
1. repeating this for all recipients
1. Party A's Transaction Manager returns the hash of the encrypted payload to the Quorum Node. Quorum replaces the `data` field of the Transaction with that hash, and changes the transaction's `v` value to `37` or `38`, thus marking the transaction as private and indicating that the transaction's `data` field represents the hash of an encrypted payload as opposed to executable EVM bytecode
1. The Transaction is then propagated to the rest of the network using the standard geth P2P Protocol
1. A block containing Transaction AB is created and distributed to each Quorum node in the network
1. In processing the block, all Quorum nodes attempt to process the Transaction. Recognising that the transaction `data` is a hash due to the `v` value of `37` or `38`, each node will make a call to its Transaction Manager to determine if it is party to the transaction (i.e. there is an entry for the given hash in its database). In this example, Party A & B's Transaction Managers will determine that they are party to the transaction whereas Party C's Transaction Manager will determine that it is not party
1. Party A & B's Transaction Managers make a call to their associated Enclaves to decrypt the payload
1. Party A & B's Enclaves decrypt the private transaction by:
1. deriving the shared-key used in the encryption:
1. as Party A was the sender of this transaction, it will derive the shared-key using its private key and the receiver's (B's) public key
1. as Party B was a recipient of this transaction it will derive the shared-key using its private key and the sender's (A's) public key
1. decrypting the tx-key with the shared-key and the encrypted data and nonce retrieved from the database
1. decrypting the private transaction payload with the tx-key and the encrytped data and nonce retrieved from the database
1. returning to the Transaction Manager: the decrypted private transaction data
1. The Transaction Manager's return their results to their Quorum nodes:
1. Party A & B's Transaction Managers return the decrypted private transaction data to their Quorum nodes which can now execute the transaction as normal, thus updating their respective Private StateDB. Quorum discards the decrypted private transaction data once used
1. Party C's Transaction Manager returns a 404 NOT FOUND to its Quorum node as it is not a recipient of the transaction. Recognising that it is not party to this private transaction, the Quorum node will skip the execution of the transaction, so that no changes to its Private StateDB are made

18
docs/Transaction Processing/Transaction Processing.md → docs/Privacy/Overview.md
View File

@ -1,8 +1,12 @@
# Transaction Processing
# Transaction and Contract Privacy
One of the key features of Quorum is that of Transaction Privacy. To that end, we introduce the notion of 'Public Transactions' and 'Private Transactions'. Note that this is a notional concept only and Quorum does not introduce new Transaction Types, but rather, the Ethereum Transaction Model has been extended to include an optional `privateFor` parameter (the population of which results in a Transaction being treated as private by Quorum) and the Transaction Type has a new `IsPrivate` method to identify such Transactions.
Quorum achieves Transaction Privacy by:
1. Enabling transaction Senders to create a private transaction by marking who is privy to that transaction via the `privateFor` parameter
2. Replacing the payload of a private transaction with a hash of the encrypted payload, such that the original payload is not visible to participants who are not privy to the transaction
3. Storing encrypted private data off-chain in a separate component called the [Privacy Manager](../Privacy-Manager). The Privacy Manager encrypts private data, distributes the encrypted data to other parties that are privy to the transaction, and returns the decrypted payload to those parties
[Constellation](../../Privacy/Constellation/Constellation) / [Tessera](../../Privacy/Tessera/Tessera) are used by Quorum to transfer private payloads to their intended recipients, performing encryption and related operations in the process.
Quorum introduces the notion of 'Public Transactions' and 'Private Transactions'. Note that this is a notional concept only and Quorum does not introduce new Transaction Types, but rather, the Ethereum Transaction Model has been extended to include an optional `privateFor` parameter (the population of which results in a Transaction being treated as private by Quorum) and the Transaction Type has a new `IsPrivate` method to identify such Transactions.
## Public Transactions
So called 'Public Transactions' are those Transactions whose payload is visible to all participants of the same Quorum network. These are [created as standard Ethereum Transactions in the usual way](https://github.com/ethereum/wiki/wiki/JavaScript-API#web3ethsendtransaction).
@ -17,15 +21,9 @@ So called 'Private Transactions' are those Transactions whose payload is only vi
When the Quorum Node encounters a Transaction with a non-null `privateFor` value, it sets the `V` value of the Transaction Signature to be either `37` or `38` (as opposed to `27` or `28` which are the values used to indicate a Transaction is 'public' as per standard Ethereum as specified in the Ethereum yellow paper).
## Processing Transactions
### Public vs Private Transaction handling
## Public vs Private Transaction Handling
Public Transactions are executed in the standard Ethereum way, and so if a Public Transaction is sent to an Account that holds Contract code, each participant will execute the same code and their underlying StateDBs will be updated accordingly.
Private Transactions, however, are not executed per standard Ethereum: prior to the sender's Quorum Node propagating the Transaction to the rest of the network, it replaces the original Transaction Payload with a hash of the encrypted Payload that it receives from Constellation/Tessera. Participants that are party to the Transaction will be able to replace the hash with the actual payload via their Constellation/Tessera instance, whilst those Participants that are not party will only see the hash.
The result is that if a Private Transaction is sent to an Account that holds Contract code, those participants who are not party to the Transaction will simply end up skipping the Transaction, and therefore not execute the Contract code. However those participants that are party to the Transaction will replace the hash with the original Payload before calling the EVM for execution, and their StateDB will be updated accordingly. In absence of making corresponding changes to the geth client, these two sets of participants would therefore end up with different StateDBs and not be able to reach consensus. So in order to support this bifurcation of contract state, Quorum stores the state of Public contracts in a Public State Trie that is globally synchronised, and it stores the state of Private contracts in a Private State Trie that is not synchronised globally. For details on how Consensus is achieved in light of this, please refer to [Quorum Consensus](../../Consensus/Consensus).
### Private Transaction Process Flow
Please refer [Private Transaction Flow](../../Privacy/Tessera/How%20Tessera%20Works) section under Tessera

21
docs/Privacy/Privacy-Manager.md Normal file
View File

@ -0,0 +1,21 @@
# Privacy Manager
A Privacy Manager is required to use private transactions in Quorum.
The Privacy Manager is a separate component that is concerned with the storing and distribution of encrypted private transaction data between recipients of a private transaction.
To enable private transactions, use the `PRIVATE_CONFIG` environment variable when starting a Quorum node to provide the node with the path to the Privacy Manager's `.ipc` socket, e.g.:
```shell
export PRIVATE_CONFIG=path/to/tm.ipc
```
The Privacy Manager has two components:
* **Transaction Manager**: See the [Homepage](../../#privacy-manager) and [Tessera's Transaction Manager page](../Tessera/Tessera%20Services/Transaction%20Manager) for more details on the responsibilities of the Transaction Manager
* **Enclave**: See [Homepage](../../#privacy-manager) and [Tessera's Enclave page](../Tessera/Tessera%20Services/Enclave) for more details on the responsibilities of the Enclave
## Implementations
* [Tessera](../Tessera/Tessera) is a production-ready implementation of Quorum's privacy manager. It is undergoing active development with new features being added regularly.
* [Constellation](../Constellation/Constellation) is the reference implementation of Quorum's privacy manager. It is still supported but no longer undergoing active development of new features.

26
docs/Privacy/Tessera/Configuration/Configuration Overview.md
View File

@ -265,13 +265,23 @@ Default configuration for this is `false` as this is BREAKABLE change to lower v
---
### Encryptor - Supporting alternative curves in Tessera
### Alternative cryptographic elliptic curves
By default Tessera uses the [NaCl(salt)](https://nacl.cr.yp.to/) library in order to encrypt private payloads (which uses a particular combination of Curve25519, Salsa20, and Poly1305 under the hood).
By default Tessera's Enclave uses the [jnacl](https://github.com/neilalexander/jnacl) implementation of the [NaCl](https://nacl.cr.yp.to/) library to encrypt/decrypt private payloads.
Alternative curves/symmetric ciphers can be used by configuring the EC Encryptor (which relies on JCA to perform a similar logic to NaCl).
NaCl provides public-key authenticated encryption by using `curve25519xsalsa20poly1305`, a combination of the:
1. **Curve25519 Diffie-Hellman key-exchange function**: based on fast arithmetic on a strong elliptic curve
2. **Salsa20 stream cipher**: encrypts a message using the shared secret
3. **Poly1305 message-authentication code**: authenticates the encrypted message using a shared secret
This is a feature introduced in Tessera v0.10.2. Providing no `encryptor` configuration results in the standard pre-v0.10.2 Tessera behaviour.
The NaCl primitives provide good security and speed and should be sufficient in most circumstances.
However, the Enclave also supports the JCA (Java Cryptography Architecture) framework. Supplying a compatible JCA provider (e.g. [SunEC provider](https://docs.oracle.com/javase/8/docs/technotes/guides/security/SunProviders.html#SunEC)) and the necessary Tessera config allows the NaCl primitives to be replaced with alternative curves and symmetric ciphers.
The same Enclave encryption process as described in [Lifecycle of a private transaction](../../../Lifecycle-of-a-private-transaction) is used regardless of whether the NaCl or JCA Encryptor are configured.
This is a feature introduced in Tessera v0.10.2. Providing no `encryptor` configuration means the default NaCl encryptor is used.
```
"encryptor": {
@ -293,9 +303,9 @@ If `type` is set to `EC`, the following `properties` fields can also be configur
Field|Default Value|Description
-------------|-------------|-----------
`ellipticCurve`|`secp256r1`|The elliptic curve to use. See [SunEC provider](https://docs.oracle.com/javase/8/docs/technotes/guides/security/SunProviders.html#SunEC) for other options. Depending on the JCE provider you are using there may be additional curves available.
`symmetricCipher`|`AES/GCM/NoPadding`|The symmetric cipher to use for encrypting data (GCM IS MANDATORY as an initialisation vector is supplied during encryption).
`nonceLength`|`24`|The nonce length (used as the initialization vector - IV - for symmetric encryption).
`sharedKeyLength`|`32`|The key length used for symmetric encryption (keep in mind the key derivation operation always produces 32 byte keys - so the encryption algorithm must support it).
<span style="white-space:nowrap">`ellipticCurve`</span>|<span style="white-space:nowrap">`secp256r1`</span>|The elliptic curve to use. See [SunEC provider](https://docs.oracle.com/javase/8/docs/technotes/guides/security/SunProviders.html#SunEC) for other options. Depending on the JCE provider you are using there may be additional curves available.
<span style="white-space:nowrap">`symmetricCipher`</span>|<span style="white-space:nowrap">`AES/GCM/NoPadding`</span>|The symmetric cipher to use for encrypting data (GCM IS MANDATORY as an initialisation vector is supplied during encryption).
<span style="white-space:nowrap">`nonceLength`</span>|`24`|The nonce length (used as the initialization vector - IV - for symmetric encryption).
<span style="white-space:nowrap">`sharedKeyLength`</span>|`32`|The key length used for symmetric encryption (keep in mind the key derivation operation always produces 32 byte keys - so the encryption algorithm must support it).
---

29
docs/Privacy/Tessera/How Tessera Works.md
View File

@ -1,29 +0,0 @@
### Private Transaction Process Flow
Below is a description of how Private Transactions are processed in Quorum:
![Quorum Tessera Privacy Flow](https://github.com/jpmorganchase/tessera/raw/master/Tessera%20Privacy%20flow.jpeg)
In this example, Party A and Party B are party to Transaction AB, whilst Party C is not.
1. Party A sends a Transaction to their Quorum Node, specifying the Transaction payload and setting `privateFor` to be the public keys for Parties A and B (Party A is optional)
1. Party A's Quorum Node passes the Transaction on to its paired Transaction Manager, requesting for it to store the Transaction payload
1. Party A's Transaction Manager makes a call to its associated Enclave to validate the sender and encrypt the payload
1. Party A's Enclave checks the private key for Party A and, once validated, performs the Transaction conversion. This entails:
1. generating a random master key (RMK) and a random Nonce
1. encrypting the Transaction payload with the nonce and RMK from step a.
1. iterating through the list of transaction recipients, in this case parties A and B, and encrypting the RMK from a. with the shared key derived from Party A's private key and the recipient's public key, along with another randomly generated nonce. Each encrypted RMK is unique for each recipient and will only be shared with the respective recipient along with encrypted payload.
1. returning the encrypted payload from step b. and all encrypted RMKs from step c. to the Transaction Manager
1. Party A's Transaction Manager calculates the SHA3-512 hash of the encrypted payload then stores the encrypted payload and encrypted RMKs against the hash in the database
1. Party A's Transaction Manager then securely transfers (via HTTPS) the encrypted payload, and RMK that has been encrypted with shared key from previous step 4.c, the nonce's to Party B's Transaction Manager. Party B's Transaction Manager responds with an Ack/Nack response. Note that if Party A does not receive a response/receives a Nack from Party B then the Transaction will not be propagated to the network. It is a prerequisite for the recipients to store the communicated payload.
1. Once the data transmission to Party B's Transaction Manager has been successful, Party A's Transaction Manager returns the hash to the Quorum Node which then replaces the Transaction's original payload with that hash, and changes the transaction's `V` value to 37 or 38, which will indicate to other nodes that this hash represents a private transaction with an associated encrypted payload as opposed to a public transaction with nonsensical bytecode.
1. The Transaction is then propagated to the rest of the network using the standard Ethereum P2P Protocol.
1. A block containing Transaction AB is created and distributed to each Party on the network.
1. In processing the block, all Parties will attempt to process the Transaction. Each Quorum node will recognise a `V` value of 37 or 38, identifying the Transaction as one whose payload requires decrypting, and make a call to their local Transaction Manager to determine if they hold the Transaction (using the hash as the index to look up).
1. Since Party C does not hold the Transaction, it will receive a `NotARecipient` message and will skip the Transaction - it will not update its Private StateDB. Party A and B will look up the hash in their local Transaction Managers and identify that they do hold the Transaction. Each will then make a call to its Enclave, passing in the Encrypted Payload, Encrypted symmetric key and Signature.
1. The Enclave validates the signature and then decrypts the symmetric key using the Party's private key that is held in The Enclave, decrypts the Transaction Payload using the now-revealed symmetric key and returns the decrypted payload to the Transaction Manager.
1. The Transaction Managers for Parties A and B then send the decrypted payload to the EVM for contract code execution. This execution will update the state in the Quorum Node's Private StateDB only. NOTE: once the code has been executed it is discarded so is never available for reading without going through the above process.

58
docs/Privacy/Tessera/Tessera Services/Enclave.md
View File

@ -1,71 +1,69 @@
## Enclave
### What is an enclave?
## What is an enclave?
An enclave is a secure processing environment that acts as a black box for processing commands and data. Enclaves come in various forms, some on hardware and others in software. In all scenarios, the purpose is to protect information that exists inside of the enclave from malicious attack.
### What does a Tessera enclave do?
## What does the Tessera Enclave do?
The Tessera enclave is designed to handle all of the encryption/decryption operations required by the Transaction Manager, as well as all forms of key management.
The Tessera Enclave is designed to handle all of the encryption/decryption operations required by the Transaction Manager, as well as all forms of key management.
This enables all sensitive operations to be handled in a single place, without any leakage into areas of program memory that don't need access. This also means that a smaller application can be run in a secure environment, where memory constraints are often more stringent, such as hardware enclaves.
The Transaction Manager, which handles peer management and database access, as well as Quorum communication does not perform **any** encryption/decryption, greatly reducing the impact an attack can have.
### What exactly does the enclave handle?
## What exactly does the Enclave handle?
The Tessera enclave **handles** the following data:
The Tessera Enclave **handles** the following data:
- public/private key access
- public keys of extra recipients (** should be moved into Transaction Manager, not sensitive)
- default identity of attached nodes
The enclaves **performs** the following actions on request:
The Enclave **performs** the following actions on request:
- fetching the default identity for attached nodes (default public key)
- providing forwarding keys for all transactions (** should be moved into Transaction Manager, not sensitive)
- returning all public keys managed by this enclave
- returning all public keys managed by this Enclave
- encrypting a payload for given sender and recipients
- encrypting raw payloads for given sender
- decrypting transactions for a given recipient (or sender)
- adding new recipients for existing payloads
### Where does the Enclave sit in the private transaction flow?
## Where does the Enclave sit in the private transaction flow?
The Enclave is the innermost actor of the sequence of events. The below diagram demonstrates where the enclave sits:
The Enclave is the innermost actor of the sequence of events. The below diagram demonstrates where the Enclave sits:
![Quorum Tessera Privacy Flow](https://github.com/jpmorganchase/tessera/raw/master/Tessera%20Privacy%20flow.jpeg)
As the diagram shows, each enclave interacts only with it's own transaction manager and no-one else.
As the diagram shows, each Enclave interacts only with it's own transaction manager and no-one else.
Tessera provides different types of Enclaves to suit different needs:
### Types of Enclave
## Types of Enclave
#### Local enclave
The local enclave is the classical option that was included in versions of Tessera prior to v0.9. This includes the enclave inside the same process and the transaction manager. This is still an option, and requires all the enclave configuration to be inside the same configuration file and the Transaction Manager configuration.
### Local Enclave
The local Enclave is the classical option that was included in versions of Tessera prior to v0.9. This includes the Enclave inside the same process and the transaction manager. This is still an option, and requires all the Enclave configuration to be inside the same configuration file and the Transaction Manager configuration.
##### How to use?
In order to use the local enclave, you simply need to not specify an Enclave server type in the configuration. don't forget to specify the enclave config in the Transaction Manager config file.
#### How to use?
In order to use the local Enclave, you simply need to not specify an Enclave server type in the configuration. don't forget to specify the Enclave config in the Transaction Manager config file.
#### HTTP Enclave
The HTTP Enclave is a remote enclave that serves RESTful endpoints over HTTP. This allows a clear separation of concerns for between the Enclave process and Transaction Manager (TM) process. The enclave must be present and running at TM startup as it will be called upon for initialisation.
### HTTP Enclave
The HTTP Enclave is a remote Enclave that serves RESTful endpoints over HTTP. This allows a clear separation of concerns for between the Enclave process and Transaction Manager (TM) process. The Enclave must be present and running at TM startup as it will be called upon for initialisation.
##### How to use?
The HTTP enclave can be started up by specifying an `ENCLAVE` server app type, with REST as the communication type. This same configuration should be put into the TM configuration so it knows where to find the remote enclave. Remember to set TLS settings as appropriate, with the TM being a client of the Enclave.
#### How to use?
The HTTP Enclave can be started up by specifying an `ENCLAVE` server app type, with REST as the communication type. This same configuration should be put into the TM configuration so it knows where to find the remote Enclave. Remember to set TLS settings as appropriate, with the TM being a client of the Enclave.
##### Advantage?
The HTTP enclave could be deployed in a completely secure environment away from local machine where TM process runs and it adds this additional layer of security for private keys which is only accessible from HTTP enclave.
#### Advantage?
The HTTP Enclave could be deployed in a completely secure environment away from local machine where TM process runs and it adds this additional layer of security for private keys which is only accessible from HTTP Enclave.
### Setting up an Enclave
## Setting up an Enclave
### Configuration
## Configuration
The configuration for the enclave is designed to the same as for the Transaction Manager.
The configuration for the Enclave is designed to the same as for the Transaction Manager.
#### Local Enclave Setup
### Local Enclave Setup
The following should be present in the TM configuration:
```json
{
@ -80,10 +78,10 @@ The following should be present in the TM configuration:
}
```
#### Remote Enclave Setup
### Remote Enclave Setup
The configuration required is minimal, and only requires the following from the main config (as an example):
In the remote enclave config:
In the remote Enclave config:
```json
{
"serverConfigs": [{
@ -114,7 +112,7 @@ and in the TM configuration:
"communicationType": "REST"
}],
```
The keys are the same as the Transaction Manager configuration, and can use all the key types including vaults. When using a vault with the enclave, be sure to include the corresponding jar on the classpath, either:
The keys are the same as the Transaction Manager configuration, and can use all the key types including vaults. When using a vault with the Enclave, be sure to include the corresponding jar on the classpath, either:
* `/path/to/azure-key-vault-0.9-SNAPSHOT-all.jar`
* `/path/to/hashicorp-key-vault-0.9-SNAPSHOT-all.jar`

84
docs/index.md
View File

@ -12,20 +12,49 @@ The primary features of Quorum, and therefore extensions over public Ethereum, a
* Network/Peer permissions management
* Higher performance
Quorum currently includes the following components:
* Quorum Node (modified Geth Client)
* Privacy Manager (Constellation/Tessera)
* Transaction Manager
* Enclave
!!! info "Background Reading"
For more information on the design rationale and background to Quorum, please read the [**Quorum Whitepaper**](https://github.com/jpmorganchase/quorum/blob/master/docs/Quorum%20Whitepaper%20v0.2.pdf), view the [Hyperledger deck](https://drive.google.com/open?id=0B8rVouOzG7cOeHo0M2ZBejZTdGs) or watch the [presentation](https://drive.google.com/open?id=0B8rVouOzG7cOcDg4UkxqdTBacm8) given to the Hyperledger Project Technical Steering Committee meeting on 22-Sept-16. Also see quick overview of sending private transactions [here](https://vimeo.com/user5833792/review/210456729/8f70cfaaa5)
## Logical Architecture Diagram
## Quorum's components
### Logical architecture diagram
![](Quorum%20Design.png)
### Quorum Node
The Quorum Node is intentionally designed to be a lightweight fork of geth in order that it can continue to take advantage of the R&D that is taking place within the ever growing Ethereum community. To that end, Quorum will be updated in-line with future geth releases.
The Quorum Node includes the following modifications to geth:
* Consensus is achieved with the Raft or Istanbul BFT consensus algorithms instead of using Proof-of-Work.
* The P2P layer has been modified to only allow connections to/from permissioned nodes.
* The block generation logic has been modified to replace the ‘global state root’ check with a new ‘global public state root’.
* The block validation logic has been modified to replace the ‘global state root’ in the block header with the ‘global public state root’
* The State Patricia trie has been split into two: a public state trie and a private state trie.
* Block validation logic has been modified to handle ‘Private Transactions’
* Transaction creation has been modified to allow for Transaction data to be replaced by encrypted hashes in order to preserve private data where required
* The pricing of Gas has been removed, although Gas itself remains
### Privacy Manager
[Constellation](Privacy/Constellation/Constellation) and [Tessera](Privacy/Tessera/Tessera) are Haskell and Java implementations of a general-purpose system for submitting information in a secure way. They are comparable to a network of MTA (Message Transfer Agents) where messages are encrypted with PGP. It is not blockchain-specific, and are potentially applicable in many other types of applications where you want individually-sealed message exchange within a network of counterparties. The Constellation and Tessera modules consist of two sub-modules:
* The Node (which is used for Quorum's default implementation of a `PrivateTransactionManager`)
* The Enclave
#### Transaction Manager
Quorum’s Transaction Manager is responsible for Transaction privacy. It stores and allows access to encrypted transaction data, exchanges encrypted payloads with other participant's Transaction Managers but does not have access to any sensitive private keys. It utilizes the Enclave for cryptographic functionality (although the Enclave can optionally be hosted by the Transaction Manager itself.)
The Transaction Manager is restful/stateless and can be load balanced easily.
For further details on how the Transaction Manager interacts with the Enclave, please refer [here](Privacy/Tessera/Tessera%20Services/Transaction%20Manager)
#### The Enclave
Distributed Ledger protocols typically leverage cryptographic techniques for transaction authenticity, participant authentication, and historical data preservation (i.e. through a chain of cryptographically hashed data.) In order to achieve a separation of concerns, as well as to provide performance improvements through parallelization of certain crypto-operations, much of the cryptographic work including symmetric key generation and data encryption/decryption is delegated to the Enclave.
The Enclave works hand in hand with the Transaction Manager to strengthen privacy by managing the encryption/decryption in an isolated way. It holds private keys and is essentially a “virtual HSM” isolated from other components.
For further details on the Enclave, please refer [here](Privacy/Tessera/Tessera%20Services/Enclave).
## Design
### Public/Private State
@ -76,40 +105,3 @@ To overcome this issue the RPC method `eth_storageRoot(address[, blockNumber]) -
It returns the storage root for the given address at an (optional) block number.
If the optional block number is not given the latest block number is used.
The storage root hash can be on or off chain compared by the parties involved.
## Component Overview
### Quorum Node
The Quorum Node is intentionally designed to be a lightweight fork of geth in order that it can continue to take advantage of the R&D that is taking place within the ever growing Ethereum community. To that end, Quorum will be updated in-line with future geth releases.
The Quorum Node includes the following modifications to geth:
* Consensus is achieved with the Raft or Istanbul BFT consensus algorithms instead of using Proof-of-Work.
* The P2P layer has been modified to only allow connections to/from permissioned nodes.
* The block generation logic has been modified to replace the ‘global state root’ check with a new ‘global public state root’.
* The block validation logic has been modified to replace the ‘global state root’ in the block header with the ‘global public state root’
* The State Patricia trie has been split into two: a public state trie and a private state trie.
* Block validation logic has been modified to handle ‘Private Transactions’
* Transaction creation has been modified to allow for Transaction data to be replaced by encrypted hashes in order to preserve private data where required
* The pricing of Gas has been removed, although Gas itself remains
### Constellation & Tessera
[Constellation](Privacy/Constellation/Constellation) and [Tessera](Privacy/Tessera/Tessera) are Haskell and Java implementations of a general-purpose system for submitting information in a secure way. They are comparable to a network of MTA (Message Transfer Agents) where messages are encrypted with PGP. It is not blockchain-specific, and are potentially applicable in many other types of applications where you want individually-sealed message exchange within a network of counterparties. The Constellation and Tessera modules consist of two sub-modules:
* The Node (which is used for Quorum's default implementation of a `PrivateTransactionManager`)
* The Enclave
#### Transaction Manager
Quorum’s Transaction Manager is responsible for Transaction privacy. It stores and allows access to encrypted transaction data, exchanges encrypted payloads with other participant's Transaction Managers but does not have access to any sensitive private keys. It utilizes the Enclave for cryptographic functionality (although the Enclave can optionally be hosted by the Transaction Manager itself.)
The Transaction Manager is restful/stateless and can be load balanced easily.
For further details on how the Transaction Manager interacts with the Enclave, please refer [here](Privacy/Tessera/Tessera%20Services/Transaction%20Manager)
#### The Enclave
Distributed Ledger protocols typically leverage cryptographic techniques for transaction authenticity, participant authentication, and historical data preservation (i.e. through a chain of cryptographically hashed data.) In order to achieve a separation of concerns, as well as to provide performance improvements through parallelization of certain crypto-operations, much of the cryptographic work including symmetric key generation and data encryption/decryption is delegated to the Enclave.
The Enclave works hand in hand with the Transaction Manager to strengthen privacy by managing the encryption/decryption in an isolated way. It holds private keys and is essentially a “virtual HSM” isolated from other components.
For further details on the Enclave, please refer [here](Privacy/Tessera/Tessera%20Services/Enclave).

46
mkdocs.yml
View File

@ -11,6 +11,7 @@ repo_name: quorum
repo_url: https://github.com/jpmorganchase/quorum
nav:
- Home: index.md
- Getting Started:
- Quickstart: Getting Started/Getting Started Overview.md
- Installing: Getting Started/Installing.md
@ -27,30 +28,12 @@ nav:
- Overview: Consensus/ibft/ibft.md
- Consensus/ibft/istanbul-rpc-api.md
- Consensus/ibft/ibft-parameters.md
- Transaction Processing: Transaction Processing/Transaction Processing.md
- Security Framework:
- Overview: Security/Framework/Overview.md
- Quorum Network:
- Consortium: Security/Framework/Quorum Network Security/Consortium.md
- Quorum Node:
- Overview: Security/Framework/Quorum Network Security/Node.md
- Permissioning:
- Network Permissioning: Security/Framework/Quorum Network Security/Nodes/Permissioning/Network Permissioning.md
- Transaction Manager: Security/Framework/Quorum Network Security/Transaction Manager.md
- Operational Considerations: Security/Framework/Quorum Network Security/Opertional Considerations.md
- Decentralized App:
- Frontend: Security/Framework/Decentralized Application/Frontend Components.md
- Smart Contracts: Security/Framework/Decentralized Application/Smart Contracts Security.md
- Permissioning:
- Overview: Permissioning/Overview.md
- Design: Permissioning/Contract Design.md
- Setup: Permissioning/setup.md
- APIs: Permissioning/Permissioning apis.md
- Usage: Permissioning/Usage.md
- Privacy:
- Transaction & Contract Privacy:
- Overview: Privacy/Overview.md
- Privacy/Privacy-Manager.md
- Privacy/Lifecycle-of-a-private-transaction.md
- Tessera:
- What is Tessera: Privacy/Tessera/Tessera.md
- How Tessera works: Privacy/Tessera/How Tessera Works.md
- Configuration:
- Overview: Privacy/Tessera/Configuration/Configuration Overview.md
- Keys Config: Privacy/Tessera/Configuration/Keys.md
@ -75,6 +58,25 @@ nav:
- How it works: Privacy/Constellation/How constellation works.md
- Sample Configuration: Privacy/Constellation/Sample Configuration.md
- Running Constellation: Privacy/Constellation/Installation & Running.md
- Permissioning:
- Overview: Permissioning/Overview.md
- Design: Permissioning/Contract Design.md
- Setup: Permissioning/setup.md
- APIs: Permissioning/Permissioning apis.md
- Usage: Permissioning/Usage.md
- Security Framework:
- Overview: Security/Framework/Overview.md
- Quorum Network:
- Consortium: Security/Framework/Quorum Network Security/Consortium.md
- Quorum Node:
- Overview: Security/Framework/Quorum Network Security/Node.md
- Permissioning:
- Network Permissioning: Security/Framework/Quorum Network Security/Nodes/Permissioning/Network Permissioning.md
- Transaction Manager: Security/Framework/Quorum Network Security/Transaction Manager.md
- Operational Considerations: Security/Framework/Quorum Network Security/Opertional Considerations.md
- Decentralized App:
- Frontend: Security/Framework/Decentralized Application/Frontend Components.md
- Smart Contracts: Security/Framework/Decentralized Application/Smart Contracts Security.md
- Pluggable Architecture:
- Overview: PluggableArchitecture/Overview.md
- Settings: PluggableArchitecture/Settings.md