generated from Consensys/doc.ethsigner
-
Notifications
You must be signed in to change notification settings - Fork 33
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* Adding docs for qlight client * Adding docs for qlight client * Consistently use the name 'qlight' * Updated diagram. Additional documentation around qlight use. * Minor updates. * Fix formatting issues on bullet lists. * Correcting some typos. * update client auth token details * fix formatting * fix param value * fix formatting * fix formatting * Adding intro section Co-authored-by: Nicolas MASSART <[email protected]> Co-authored-by: Nicolae Leonte <[email protected]>
- Loading branch information
3 people
authored
Apr 8, 2022
1 parent
2705365
commit 6ce0645
Showing
4 changed files
with
162 additions
and
5 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,73 @@ | ||
| # GoQuorum qlight node | ||
|
|
||
| A qlight node is a lightweight replica of a full node that proxies transactions to the full node. | ||
| You can deploy a qlight node to reduce the amount of data that is shared with external parties by the full nodes. | ||
|
|
||
| The qlight node can be used to: | ||
|
|
||
| - Avoid impacting main nodes which are processing transactions with anything that could thrash the API (such as monitoring, state querying, or other intensive processes). | ||
| - Prevent security concerns where the main node is handling multiple private parties [(multi-tenancy)](multi-tenancy.md). | ||
| The qlight client deals with a private state for one party only, and only that user has access to the qlight client. | ||
|
|
||
| ## Qlight nodes and standard nodes | ||
|
|
||
| A standard GoQuorum node processes all blocks and associated transactions. | ||
| It also requires a local [private transaction manager](privacy/index.md#private-transaction-manager) to handle private data. | ||
| This can require significant resources and can make it more difficult to scale networks. | ||
| Additionally, since the node processes all transactions, privacy concerns could be raised by business partners. | ||
|
|
||
| Using a qlight node for process-intensive tasks can help lessen impact to the performance of a main node. | ||
| Qlight nodes help prevent network throttling due to third party network limits, | ||
| or multiple clients all hitting the same main node. | ||
|
|
||
| Qlight nodes differ from standard quorum nodes in the following ways: | ||
|
|
||
| - Qlight nodes depend on a server full node for receiving data and will only connect to the server node. | ||
| There is no communication with any other node. | ||
|
|
||
| - They only receive blocks from the server node, processing them locally to build up the public and private state. | ||
|
|
||
| - They do not require a transaction manager. Instead, private data is sent directly by the server node via the qlight P2P protocol. | ||
|
|
||
| - They act as a proxy for locally submitted transactions, performing minimal validation. | ||
| API calls like `SendTansaction`/`SendRawTransaction`/`StoreRaw` are forwarded to the server node for processing. | ||
|
|
||
| - They use the same RPC APIs that are required for dapps, delegating calls to the server node if needed. | ||
|
|
||
| - They do not partake in the consensus mechanism. | ||
|
|
||
| ## Client and server | ||
|
|
||
| - *qlight client* refers to the qlight node. | ||
|
|
||
| - *qlight server* refers to a full node that is configured to supply data to the qlight client. | ||
| It also handles API requests that are delegated from the qlight client. | ||
|
|
||
| ## Architecture | ||
|
|
||
|  | ||
|
|
||
| ## Communication protocol | ||
|
|
||
| The qlight client and server communicate through a peer-to-peer protocol. | ||
|
|
||
| ### Security | ||
|
|
||
| A number of security features are available for the qlight client-server connection: | ||
|
|
||
| - Native transport layer security (TLS): this can be used to encrypt communications and ensure the security of private transaction data. | ||
| - Network restriction: restricts communication to specified IP networks (CIDR masks). | ||
| - File based permissioning: allows qlight peers to be checked against a permissioned list and a disallowed list. | ||
| - Enterprise authorization protocol integration: this allows qlight clients to be authenticated using an OAuth2 server. | ||
|
|
||
| ## Private transaction manager cache | ||
|
|
||
| The qlight client does not have a local [private transaction manager](../concepts/privacy/index.md#private-transaction-manager), | ||
| but relies on the qlight server to supply private data. | ||
| This is implemented by means of a local cache which simulates a local private transaction manager. | ||
| Therefore, private transactions can be executed locally, with the private data being fetched from the private transaction manager cache. | ||
|
|
||
| ## New API methods (on qlight server) | ||
|
|
||
| - `admin.qnodeInfo`: Returns details of the qlight configuration. | ||
| - `admin.qpeers`: Returns details of the qlight clients that are connected. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,82 @@ | ||
| # Using a GoQuorum qlight node | ||
|
|
||
| A [qlight client node](../../concepts/qlight-node.md) requires a full node configured to act as a qlight server. | ||
| The server node is usually set up to support [multiple private states](../../concepts/multi-tenancy.md#multiple-private-states) | ||
| (MPS), with the qlight client set up to use a [private state identifier](../../concepts/multi-tenancy.md#private-state-identifier) | ||
| (PSI) which is managed by the server node. | ||
|
|
||
| !!! note | ||
|
|
||
| A server node is normally be set up as a multi-tenant node with Multiple Private States (MPS). | ||
| However this is not essential, for example when setting up a qlight client for the purpose of offloading processing from a full node. | ||
|
|
||
| ## Configure qlight client | ||
|
|
||
| Configure the qlight client using the following command line options: | ||
|
|
||
| - `--qlight.client`: This marks the node as a qlight client. | ||
| - `--qlight.client.psi`: This specifies the PSI which this client will support (default = "private"). | ||
| - `--qlight.client.serverNode`: The Node ID of the server node. | ||
| - `--qlight.client.serverNodeRPC`: The RPC URL of the server node. | ||
|
|
||
| If the server node has the RPC API secured using TLS, then the qlight client requires the following: | ||
|
|
||
| - `--qlight.client.rpc.tls`: Use TLS when forwarding RPC API calls. | ||
| - `--qlight.client.rpc.tls.insecureskipverify`: Skip TLS verification. | ||
| - `--qlight.client.rpc.tls.cacert`: The qlight client certificate authority. | ||
| - `--qlight.client.rpc.tls.cert`: The qlight client certificate. | ||
| - `--qlight.client.rpc.tls.key`: The qlight client certificate private key. | ||
|
|
||
| If the qlight client node is halted, on restart it resyncs with any blocks that were missed when it was not running. | ||
|
|
||
| ## Configure server node | ||
|
|
||
| Configure the qlight server using the following command line options: | ||
|
|
||
| - `--qlight.server`: This marks the node as a qlight server. | ||
| - `--qlight.server.p2p.port`: The RPC listening port. | ||
| - `--qlight.server.p2p.maxpeers`: The maximum number of qlight clients that are supported. | ||
|
|
||
| ### Network IP restriction | ||
|
|
||
| This restricts communication to specified IP networks (CIDR masks). | ||
| Specify the network mask on the qlight server using `--qlight.server.p2p.netrestrict`. | ||
|
|
||
| ### File based permissioning | ||
|
|
||
| File based permissioning allows qlight clients to be checked against a permissioned list and a disallowed list. | ||
| Enable file based permissioning on the server node using `--qlight.server.p2p.permissioning`. | ||
|
|
||
| The default files are `permissioned-nodes.json` and `disallowed-nodes.json`. | ||
| However, you can specify a file prefix using `--qlight.server.p2p.permissioning.prefix`, in which case the filename is: the prefix, followed by a hyphen, followed by the default file name. | ||
|
|
||
| ## Using the enterprise authorization protocol integration | ||
|
|
||
| This leverages the security model described under [JSON-RPC security](json-rpc-api-security.md#enterprise-authorization-protocol-integration) to only allow authenticated clients to connect to the server. | ||
|
|
||
| When using [JSON-RPC security](json-rpc-api-security.md#enterprise-authorization-protocol-integration) | ||
| you must provide an access token to communicate to the qlight server. | ||
|
|
||
| Enable auth tokens in the qlight client using `--qlight.client.token.enabled`. | ||
|
|
||
| Once enabled, specify an initial value using `--qlight.client.token.value <token>`. | ||
|
|
||
| Specify a refresh mechanism for the token using `--qlight.client.token.management`. | ||
| The valid values are: | ||
|
|
||
| - `none` - the token is not refreshed (this mechanism is for development/testing purposes only). | ||
| - `external` - the refreshed token must be updated in the running qlight client process by invoking the `qlight.setCurrentToken` RPC API. | ||
| - `client-security-plugin` (default) - the client security plugin is used to periodically refresh the access token. Please see the client-security-plugin documentation for further details. | ||
|
|
||
| ## Native transport layer security (TLS) for P2P communication | ||
|
|
||
| You can add an encryption layer on the qlight client-server communication. | ||
| Configure the encryption layer using the following options: | ||
|
|
||
| - `--qlight.tls`: Enable TLS on the P2P connection. | ||
| - `--qlight.tls.cert`: The certificate file to use. | ||
| - `--qlight.tls.key`: The key file to use. | ||
| - `--qlight.tls.clientcacerts`: The certificate authorities file to use for validating the connection (server configuration parameter). | ||
| - `--qlight.tls.cacerts`: The certificate authorities file to use for validating the connection (client configuration parameter). | ||
| - `--qlight.tls.clientauth`: The way the client is authenticated. Possible values: 0=NoClientCert(default) 1=RequestClientCert 2=RequireAnyClientCert 3=VerifyClientCertIfGiven 4=RequireAndVerifyClientCert (default: 0). | ||
| - `--qlight.tls.ciphersuites`: The cipher suites to use for the connection. |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters