mirror of https://github.com/poanetwork/quorum.git
Tessera release documentation update. (#914)
This commit is contained in:
Krish1979
Samer Falah
parent
85e2257995
commit
b1f3b96ea0
|
|
@ -29,6 +29,54 @@ Tessera's database uses JDBC to connect to an external database. Any valid JDBC
|
|||
}
|
||||
```
|
||||
|
||||
#### Obfuscate database password in config file
|
||||
|
||||
Certain entries in the Tessera config file must be obfuscated in order to prevent any attempts from attackers to gain access to critical parts of the application (e.g. database). The database password can be encrypted using [Jasypt](http://www.jasypt.org) to avoid it being exposed as plain text in the configuration file.
|
||||
|
||||
To enable this feature, simply replace your plain-text database password with its encrypted value and wrap it inside an `ENC()` function.
|
||||
|
||||
```json
|
||||
"jdbc": {
|
||||
"username": "sa",
|
||||
"password": "ENC(ujMeokIQ9UFHSuBYetfRjQTpZASgaua3)",
|
||||
"url": "jdbc:h2:/qdata/c1/db1",
|
||||
"autoCreateTables": true
|
||||
}
|
||||
```
|
||||
|
||||
Being a Password-Based Encryptor, Jasypt requires a secret key (password) and a configured algorithm to encrypt/decrypt this config entry. This password can either be loaded into Tessera from file system or user input. For file system input, the location of this secret file needs to be set in Environment Variable `TESSERA_CONFIG_SECRET`
|
||||
|
||||
If the database password is not wrapped inside `ENC()`, Tessera will simply treat it as a plain-text password however this approach is not recommended for production environments.
|
||||
|
||||
!!! note
|
||||
Jasypt encryption is currently only available for the `jdbc.password` field
|
||||
|
||||
##### How to encrypt database password
|
||||
|
||||
1. Download and unzip [Jasypt](http://www.jasypt.org) and redirect to the `bin` directory
|
||||
1. Encrypt the password
|
||||
``` bash
|
||||
$ ./encrypt.sh input=dbpassword password=quorum
|
||||
|
||||
----ENVIRONMENT-----------------
|
||||
|
||||
Runtime: Oracle Corporation Java HotSpot(TM) 64-Bit Server VM 25.171-b11
|
||||
|
||||
|
||||
|
||||
----ARGUMENTS-------------------
|
||||
|
||||
input: dbpassword
|
||||
password: quorum
|
||||
|
||||
|
||||
|
||||
----OUTPUT----------------------
|
||||
|
||||
rJ70hNidkrpkTwHoVn2sGSp3h3uBWxjb
|
||||
```
|
||||
1. Place the wrapped output, `ENC(rJ70hNidkrpkTwHoVn2sGSp3h3uBWxjb)`, in the config json file
|
||||
|
||||
---
|
||||
|
||||
### Server
|
||||
|
|
@ -151,7 +199,8 @@ For the ThirdParty server type it may be relevant to configure CORS.
|
|||
}
|
||||
},
|
||||
```
|
||||
The configurale fields are:
|
||||
The configurable fields are:
|
||||
|
||||
* `allowedMethods` - the list of allowed HTTP methods. If omitted the default list containing `"GET", "POST", "PUT", "DELETE", "OPTIONS", "HEAD"` is used.
|
||||
* `allowedOrigins` - the list of domains from which to accept cross origin requests (browser enforced). Each entry in the list can contain the "*" (wildcard) character which matches any sequence of characters. Ex: "*locahost" would match "http://localhost" or "https://localhost". There is no default for this field.
|
||||
* `allowedHeaders` - the list of allowed headers. If omitted the request `Access-Control-Request-Headers` are copied into the response as `Access-Control-Allow-Headers`.
|
||||
|
|
@ -216,4 +265,37 @@ Default configuration for this is `false` as this is BREAKABLE change to lower v
|
|||
|
||||
---
|
||||
|
||||
### Encryptor - Supporting alternative curves in Tessera
|
||||
|
||||
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).
|
||||
|
||||
Alternative curves/symmetric ciphers can be used by configuring the EC Encryptor (which relies on JCA to perform a similar logic to NaCl).
|
||||
|
||||
This is a feature introduced in Tessera v0.10.2. Providing no `encryptor` configuration results in the standard pre-v0.10.2 Tessera behaviour.
|
||||
|
||||
```
|
||||
"encryptor": {
|
||||
"type":"EC",
|
||||
"properties":{
|
||||
"symmetricCipher":"AES/GCM/NoPadding",
|
||||
"ellipticCurve":"secp256r1",
|
||||
"nonceLength":"24",
|
||||
"sharedKeyLength":"32"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Field|Default Value|Description
|
||||
-------------|-------------|-----------
|
||||
`type`|`NACL`|The encryptor type. Possible values are `EC` or `NACL`.
|
||||
|
||||
If `type` is set to `EC`, the following `properties` fields can also be configured:
|
||||
|
||||
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).
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -1,3 +1,8 @@
|
|||
!!! warning "Change from Tessera v0.10.2+"
|
||||
The `keys.keyData.passwords` field is no longer supported as of Tessera v0.10.2.
|
||||
|
||||
Instead, use `keys.keyData.passwordFile` or utilise the [CLI password prompt](#providing-key-passwords-at-runtime) when starting the node.
|
||||
|
||||
Tessera uses cryptographic keys to provide transaction privacy.
|
||||
|
||||
You can use existing private/public key pairs as well as use Tessera to generate new key pairs for you. See [Generating & securing keys](../../Tessera%20Services/Keys/Keys) for more info.
|
||||
|
|
@ -214,6 +219,21 @@ Tessera requires TLS certificates and keys to be stored in `.jks` Java keystore
|
|||
!!! info
|
||||
If using a Hashicorp Vault additional environment variables must be set and a version 2 K/V secret engine must be enabled. For more information see [Setting up a Hashicorp Vault](../../Tessera%20Services/Keys/Setting%20up%20a%20Hashicorp%20Vault).
|
||||
|
||||
## Providing key passwords at runtime
|
||||
Tessera will start a CLI password prompt if it has incomplete password data for its locked keys. This prompt can be used to provide the required passwords for each key without having to provide them in the configfile itself.
|
||||
|
||||
For example:
|
||||
|
||||
```bash
|
||||
tessera -configfile path/to/config.json
|
||||
Password for key[0] missing or invalid.
|
||||
Attempt 1 of 2. Enter a password for the key
|
||||
|
||||
2019-12-09 13:48:16.159 [main] INFO c.q.t.config.keys.KeyEncryptorImpl - Decrypting private key
|
||||
2019-12-09 13:48:19.364 [main] INFO c.q.t.config.keys.KeyEncryptorImpl - Decrypted private key
|
||||
# Tessera startup continues as normal
|
||||
```
|
||||
|
||||
## Multiple Keys
|
||||
If wished, multiple key pairs can be specified for a Tessera node. In this case, any one of the public keys can be used to address a private transaction to that node. Tessera will sequentially try each key to find one that can decrypt the payload. This can be used, for example, to simplify key rotation.
|
||||
|
||||
|
|
|
|||
|
|
@ -4,7 +4,8 @@ Tessera configuration varies by version as new features are added or changed. Be
|
|||
|
||||
| Version |
|
||||
| ------------- |
|
||||
| [0.10 - latest release](../Tessera%20v0.10.0%20sample%20settings) |
|
||||
| [0.10.2 - latest release](../Tessera%20v0.10.2%20sample%20settings) |
|
||||
| [0.10](../Tessera%20v0.10.0%20sample%20settings) |
|
||||
| [0.9](../Tessera%20v0.9%20sample%20settings) |
|
||||
| [0.8](../Tessera%20v0.8%20sample%20settings) |
|
||||
| [0.7.3](../Tessera%20v0.7.3%20sample%20settings) |
|
||||
|
|
|
|||
|
|
@ -0,0 +1,153 @@
|
|||
**Changes:**
|
||||
|
||||
- The `keys.keyData.passwords` field is no longer supported. Instead, use `keys.keyData.passwordFile` or utilise the [CLI password prompt](../Keys#providing-key-passwords-at-runtime) when starting the node.
|
||||
|
||||
- Added configuration to choose alternative curves/symmetric ciphers. If no encryptor configuration is provided it will default to NaCl (see [Supporting alternative curves in Tessera](../Configuration Overview#supporting-alternative-curves-in-tessera) for more details).
|
||||
|
||||
e.g.
|
||||
```
|
||||
"encryptor": {
|
||||
"type":"EC",
|
||||
"properties":{
|
||||
"symmetricCipher":"AES/GCM/NoPadding",
|
||||
"ellipticCurve":"secp256r1",
|
||||
"nonceLength":"24",
|
||||
"sharedKeyLength":"32"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Sample:**
|
||||
|
||||
```json
|
||||
{
|
||||
"useWhiteList": "boolean",
|
||||
"jdbc": {
|
||||
"url": "String",
|
||||
"username": "String",
|
||||
"password": "String"
|
||||
},
|
||||
"serverConfigs": [
|
||||
{
|
||||
"app": "ENCLAVE",
|
||||
// Defines us using a remote enclave, leave out if using built-in enclave
|
||||
"enabled": true,
|
||||
"serverAddress": "http://localhost:9081",
|
||||
//Where to find the remote enclave
|
||||
"communicationType": "REST"
|
||||
},
|
||||
{
|
||||
"app": "ThirdParty",
|
||||
"enabled": true,
|
||||
"serverAddress": "http://localhost:9081",
|
||||
"bindingAddress": "String - url with port e.g. http://127.0.0.1:9081",
|
||||
"communicationType": "REST"
|
||||
},
|
||||
{
|
||||
"app": "Q2T",
|
||||
"enabled": true,
|
||||
"serverAddress": "unix:/tmp/tm.ipc",
|
||||
"communicationType": "REST"
|
||||
},
|
||||
{
|
||||
"app": "P2P",
|
||||
"enabled": true,
|
||||
"serverAddress": "http://localhost:9001",
|
||||
"bindingAddress": "String - url with port e.g. http://127.0.0.1:9001",
|
||||
"sslConfig": {
|
||||
"tls": "enum STRICT,OFF",
|
||||
"generateKeyStoreIfNotExisted": "boolean",
|
||||
"serverKeyStore": "Path",
|
||||
"serverTlsKeyPath": "Path",
|
||||
"serverTlsCertificatePath": "Path",
|
||||
"serverKeyStorePassword": "String",
|
||||
"serverTrustStore": "Path",
|
||||
"serverTrustCertificates": [
|
||||
"Path..."
|
||||
],
|
||||
"serverTrustStorePassword": "String",
|
||||
"serverTrustMode": "Enumeration: CA, TOFU, WHITELIST, CA_OR_TOFU, NONE",
|
||||
"clientKeyStore": "Path",
|
||||
"clientTlsKeyPath": "Path",
|
||||
"clientTlsCertificatePath": "Path",
|
||||
"clientKeyStorePassword": "String",
|
||||
"clientTrustStore": "Path",
|
||||
"clientTrustCertificates": [
|
||||
"Path..."
|
||||
],
|
||||
"clientTrustStorePassword": "String",
|
||||
"clientTrustMode": "Enumeration: CA, TOFU, WHITELIST, CA_OR_TOFU, NONE",
|
||||
"knownClientsFile": "Path",
|
||||
"knownServersFile": "Path"
|
||||
},
|
||||
"communicationType": "REST"
|
||||
}
|
||||
],
|
||||
"peer": [
|
||||
{
|
||||
"url": "url e.g. http://127.0.0.1:9000/"
|
||||
}
|
||||
],
|
||||
"keys": {
|
||||
"passwordFile": "Path",
|
||||
"azureKeyVaultConfig": {
|
||||
"url": "Azure Key Vault url"
|
||||
},
|
||||
"hashicorpKeyVaultConfig": {
|
||||
"url": "Hashicorp Vault url",
|
||||
"approlePath": "String (defaults to 'approle' if not set)",
|
||||
"tlsKeyStorePath": "Path to jks key store",
|
||||
"tlsTrustStorePath": "Path to jks trust store"
|
||||
},
|
||||
"keyData": [
|
||||
{
|
||||
"config": {
|
||||
"data": {
|
||||
"aopts": {
|
||||
"variant": "Enum : id,d or i",
|
||||
"memory": "int",
|
||||
"iterations": "int",
|
||||
"parallelism": "int"
|
||||
},
|
||||
"bytes": "String",
|
||||
"snonce": "String",
|
||||
"asalt": "String",
|
||||
"sbox": "String",
|
||||
"password": "String"
|
||||
},
|
||||
"type": "Enum: argon2sbox or unlocked. If unlocked is defined then config data is required. "
|
||||
},
|
||||
"privateKey": "String",
|
||||
"privateKeyPath": "Path",
|
||||
"azureVaultPrivateKeyId": "String",
|
||||
"azureVaultPrivateKeyVersion": "String",
|
||||
"publicKey": "String",
|
||||
"publicKeyPath": "Path",
|
||||
"azureVaultPublicKeyId": "String",
|
||||
"azureVaultPublicKeyVersion": "String",
|
||||
"hashicorpVaultSecretEngineName": "String",
|
||||
"hashicorpVaultSecretName": "String",
|
||||
"hashicorpVaultSecretVersion": "Integer (defaults to 0 (latest) if not set)",
|
||||
"hashicorpVaultPrivateKeyId": "String",
|
||||
"hashicorpVaultPublicKeyId": "String"
|
||||
}
|
||||
]
|
||||
},
|
||||
"alwaysSendTo": [
|
||||
"String..."
|
||||
],
|
||||
"unixSocketFile": "Path",
|
||||
"features": {
|
||||
"enableRemoteKeyValidation": false
|
||||
},
|
||||
"encryptor": {
|
||||
"type": "Enumeration: NACL, EC",
|
||||
"properties":{
|
||||
"symmetricCipher":"String (defaults to AES/GCM/NoPadding if type = EC)",
|
||||
"ellipticCurve": "String (defaults to secp256r1 if type = EC)",
|
||||
"nonceLength": "String (defaults to 24 if type = EC)",
|
||||
"sharedKeyLength": "String (defaults to 32 if type = EC)"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
CLI options can be used to add to, or override, configuration defined in a `configfile`.
|
||||
CLI options can be used to add to, or override, configuration defined in a `configfile` or for `keygen`.
|
||||
|
||||
Standard Tessera CLI options are prefixed with a single hyphen (e.g. `-configfile <PATH>`), whilst the config override options are prefixed with a double hyphen (e.g. `--alwaysSendTo <STRING[]...>`). Use `tessera help` to see a complete list of CLI options.
|
||||
|
||||
|
|
@ -45,3 +45,16 @@ then Tessera will be started with the following equivalent configuration:
|
|||
}
|
||||
```
|
||||
As demonstrated in this example, in certain cases multiple values can be provided by repeating the CLI option. This is supported for the `peer.url`, `alwaysSendTo`, `server.sslConfig.serverTrustCertificates` and `server.sslConfig.clientTrustCertificates` options.
|
||||
|
||||
If you want to generate a key with alternative curve other than default NaCl, use the `encryptor.type` override as follows:
|
||||
|
||||
```
|
||||
tessera -keygen --encryptor.type EC
|
||||
```
|
||||
The override could also be used to override the value in the config file
|
||||
```
|
||||
tessera -configfile <path> --encryptor.type EC
|
||||
```
|
||||
|
||||
!!! info
|
||||
Please note with the above config, the default curve properties will be used. To update properties such as using a different curve or length, etc... please use the config file - click [here](../Tessera v0.10.2 sample settings) for sample
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
## Generating keys
|
||||
|
||||
|
||||
Key generation can be used in multiple ways:
|
||||
|
||||
1. Generate a key pair and save in new files `.pub` and `.key`:
|
||||
|
|
@ -67,6 +67,11 @@ If you wish to generate an unlocked key, `/dev/null` can be used for stdin to te
|
|||
|
||||
An updated `.json` configfile is printed to the terminal (or to a file if using the `-output` CLI option). No changes are made to the `config.json` file itself.
|
||||
|
||||
!!! note
|
||||
By default the `-keygen` commands generate [NaCl](https://nacl.cr.yp.to/) compatible keys.
|
||||
|
||||
As of Tessera v0.10.2, the `--encryptor.type=EC` CLI option can be provided to generate keys of different types. See [encryptor config](../../../Configuration/Configuration Overview/#encryptor-supporting-alternative-curves-in-tessera) for more details.
|
||||
|
||||
## Securing private keys
|
||||
Generated private keys can be encrypted with a password. This is prompted for on the console during key generation. After generating password-protected keys, the password must be added to your configuration to ensure Tessera can read the keys. The password is not saved anywhere but must be added to the configuration else the key will not be able to be decrypted.
|
||||
|
||||
|
|
@ -112,3 +117,8 @@ Password update can be used in multiple ways. Running any of these commands wil
|
|||
tessera --keys.keyData.privateKeyPath <path to keyfile> --keys.keyData.config.data.aopts.algorithm <algorithm> --keys.keyData.config.data.aopts.iterations <iterations> --keys.keyData.config.data.aopts.memory <memory> --keys.keyData.config.data.aopts.parallelism <parallelism>
|
||||
```
|
||||
All options have been overriden here but only the options you wish to alter from their defaults need to be provided.
|
||||
|
||||
!!! note
|
||||
By default the `-updatepassword` commands can be used to update the password of [NaCl](https://nacl.cr.yp.to/) compatible keys.
|
||||
|
||||
As of Tessera v0.10.2, the `--encryptor.type=EC` CLI option can be provided to update keys of different types. See [encryptor config](../../../Configuration/Configuration Overview/#encryptor-supporting-alternative-curves-in-tessera) for more details.
|
||||
|
|
|
|||
Loading…
Reference in New Issue