mirror of https://github.com/poanetwork/quorum.git
Merge branch 'master' into docs/AWSSecretsManagerKeyVault
This commit is contained in:
Krish1979
GitHub
commit
9c2cba6a5b
|
|
@ -49,6 +49,14 @@
|
|||
|
||||
**Note:** While every Quorum v2 client will be able to connect to any other v2 client, the usefullness will be severely degraded. <span style="color:red;">Red color</span> signifies that while connectivity is possible, <span style="color:red;">red colored</span> versions will be unable to send public or private txns to the rest of the net due to the EIP155 changes in the signer implemented in newer versions.
|
||||
|
||||
### Tessera FAQ
|
||||
|
||||
??? question "What does enabling 'disablePeerDiscovery' mean?"
|
||||
It means the node will only communicate with the nodes defined in the configuration file. Upto version 0.10.2, the nodes still accepts transactions from undiscovered nodes. From version 0.10.3 the node blocks all communication with undiscovered nodes.
|
||||
|
||||
??? info "Upgrading to Tessera version 0.10.+ from verion 0.9.+ and below"
|
||||
Due to 'database file unable to open' issue with H2 DB upgrade from version 1.4.196 direct to version 1.4.200 as explained [here](https://github.com/h2database/h2database/issues/2263), our recommended mitigation strategy is to upgrade to version 1.4.199 first before upgrading to version 1.4.200 i.e., first upgrade to Tessera 0.10.0 before upgrading to higher versions.
|
||||
|
||||
### Raft FAQ
|
||||
|
||||
??? question "Could you have a single- or two-node cluster? More generally, could you have an even number of nodes?"
|
||||
|
|
|
|||
|
|
@ -6,7 +6,45 @@
|
|||
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.
|
||||
```json
|
||||
|
||||
```json tab="v0.10.3 onwards"
|
||||
"keys": {
|
||||
"passwordFile": "Path",
|
||||
"keyVaultConfig": [
|
||||
{
|
||||
"keyVaultType": "Enumeration: AZURE, HASHICORP, AWS",
|
||||
"properties": "Map[string]string"
|
||||
}
|
||||
],
|
||||
"keyData": [
|
||||
{
|
||||
// The data for a private/public key pair
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```json tab="v0.10.2"
|
||||
"keys": {
|
||||
"passwordFile": "Path",
|
||||
"azureKeyVaultConfig": {
|
||||
"url": "Url"
|
||||
},
|
||||
"hashicorpKeyVaultConfig": {
|
||||
"url": "Url",
|
||||
"approlePath": "String",
|
||||
"tlsKeyStorePath": "Path",
|
||||
"tlsTrustStorePath": "Path"
|
||||
},
|
||||
"keyData": [
|
||||
{
|
||||
// The data for a private/public key pair
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```json tab="v0.10.1 and earlier"
|
||||
"keys": {
|
||||
"passwords": [],
|
||||
"passwordFile": "Path",
|
||||
|
|
@ -80,7 +118,32 @@ The key pair data is provided in plain text in the configfile. The plain text p
|
|||
#### Protected
|
||||
The public key is provided in plain text. The private key must be password-protected using Argon2. The corresponding encrypted data is provided in the `config` json object.
|
||||
|
||||
```json
|
||||
```json tab="v0.10.2 onwards"
|
||||
"keys": {
|
||||
"passwordFile": "/path/to/pwds.txt",
|
||||
"keyData": [
|
||||
{
|
||||
"config": {
|
||||
"data": {
|
||||
"aopts": {
|
||||
"variant": "id",
|
||||
"memory": 1048576,
|
||||
"iterations": 10,
|
||||
"parallelism": 4,
|
||||
},
|
||||
"snonce": "x3HUNXH6LQldKtEv3q0h0hR4S12Ur9pC",
|
||||
"asalt": "7Sem2tc6fjEfW3yYUDN/kSslKEW0e1zqKnBCWbZu2Zw=",
|
||||
"sbox": "d0CmRus0rP0bdc7P7d/wnOyEW14pwFJmcLbdu2W3HmDNRWVJtoNpHrauA/Sr5Vxc"
|
||||
},
|
||||
"type": "argon2sbox"
|
||||
},
|
||||
"publicKey": "/+UuD63zItL1EbjxkKUljMgG8Z1w0AJ8pNOR4iq2yQc="
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```json tab="v0.10.1 and earlier"
|
||||
"keys": {
|
||||
"passwords": ["password"],
|
||||
"passwordFile": "/path/to/pwds.txt",
|
||||
|
|
@ -116,7 +179,20 @@ Passwords must be provided so that Tessera can decrypt and use the private keys.
|
|||
|
||||
### Filesystem key pairs
|
||||
The keys in the pair are stored in files:
|
||||
```json
|
||||
|
||||
```json tab="v0.10.2 onwards"
|
||||
"keys": {
|
||||
"passwordFile": "/path/to/pwds.txt",
|
||||
"keyData": [
|
||||
{
|
||||
"privateKeyPath": "/path/to/privateKey.key",
|
||||
"publicKeyPath": "/path/to/publicKey.pub"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```json tab="v0.10.1 and earlier"
|
||||
"keys": {
|
||||
"passwords": ["password"],
|
||||
"passwordFile": "/path/to/pwds.txt",
|
||||
|
|
@ -128,6 +204,7 @@ The keys in the pair are stored in files:
|
|||
]
|
||||
}
|
||||
```
|
||||
|
||||
The contents of the public key file must contain the public key only, e.g.:
|
||||
```
|
||||
/+UuD63zItL1EbjxkKUljMgG8Z1w0AJ8pNOR4iq2yQc=
|
||||
|
|
@ -172,7 +249,27 @@ Passwords must be provided so that Tessera can decrypt and use the private keys.
|
|||
|
||||
### Azure Key Vault key pairs
|
||||
The keys in the pair are stored as secrets in an Azure Key Vault. This requires providing the vault url and the secret IDs for both keys:
|
||||
```json
|
||||
|
||||
```json tab="v0.10.3 onwards"
|
||||
"keys": {
|
||||
"keyVaultConfig": {
|
||||
"keyVaultType": "AZURE",
|
||||
"properties": {
|
||||
"url": "https://my-vault.vault.azure.net"
|
||||
}
|
||||
},
|
||||
"keyData": [
|
||||
{
|
||||
"azureVaultPrivateKeyId": "Key",
|
||||
"azureVaultPublicKeyId": "Pub",
|
||||
"azureVaultPublicKeyVersion": "bvfw05z4cbu11ra2g94e43v9xxewqdq7",
|
||||
"azureVaultPrivateKeyVersion": "0my1ora2dciijx5jq9gv07sauzs5wjo2"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```json tab="v0.10.2 and earlier"
|
||||
"keys": {
|
||||
"azureKeyVaultConfig": {
|
||||
"url": "https://my-vault.vault.azure.net"
|
||||
|
|
@ -195,7 +292,29 @@ This example configuration will retrieve the specified versions of the secrets `
|
|||
|
||||
### Hashicorp Vault key pairs
|
||||
The keys in the pair are stored as a secret in a Hashicorp Vault. Additional configuration can also be provided if the Vault is configured to use TLS and if the AppRole auth method is being used at a different path to the default (`approle`):
|
||||
```json
|
||||
|
||||
```json tab="v0.10.3 onwards"
|
||||
"keyVaultConfig": {
|
||||
"keyVaultType": "HASHICORP",
|
||||
"properties": {
|
||||
"url": "https://localhost:8200",
|
||||
"tlsKeyStorePath": "/path/to/keystore.jks",
|
||||
"tlsTrustStorePath": "/path/to/truststore.jks",
|
||||
"approlePath": "not-default"
|
||||
}
|
||||
},
|
||||
"keyData": [
|
||||
{
|
||||
"hashicorpVaultSecretEngineName": "engine",
|
||||
"hashicorpVaultSecretName": "secret",
|
||||
"hashicorpVaultSecretVersion": 1,
|
||||
"hashicorpVaultPrivateKeyId": "privateKey",
|
||||
"hashicorpVaultPublicKeyId": "publicKey",
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
```json tab="v0.10.2 and earlier"
|
||||
"hashicorpKeyVaultConfig": {
|
||||
"url": "https://localhost:8200",
|
||||
"tlsKeyStorePath": "/path/to/keystore.jks",
|
||||
|
|
@ -227,7 +346,8 @@ Tessera requires TLS certificates and keys to be stored in `.jks` Java keystore
|
|||
|
||||
### AWS Secrets Manager key pairs
|
||||
The keys in the pair are stored as secrets in the _AWS Secrets Manager_. This requires providing the secret IDs for both keys. The endpoint is optional as the _AWS SDK_ can fallback to its inbuilt property retrieval chain (e.g. using the environment variable `AWS_REGION` or `~/.aws/config` file - see [the AWS docs](https://docs.aws.amazon.com/sdk-for-java/v2/developer-guide/credentials.html) for similar behaviour explained in the context of credentials):
|
||||
```json
|
||||
|
||||
```json tab="v0.10.3 onwards"
|
||||
"keys": {
|
||||
"keyVaultConfig": {
|
||||
"keyVaultConfigType": "AWS",
|
||||
|
|
@ -273,10 +393,28 @@ If wished, multiple key pairs can be specified for a Tessera node. In this case,
|
|||
Note that multiple key pairs can only be set up within the configuration file, not via separate filesystem key files.
|
||||
|
||||
## Viewing the keys registered for a node
|
||||
An ADMIN API endpoint `/config/keypairs` exists to allow you to view the public keys of the key pairs currently in use by your Tessera node. This requires configuring an ADMIN server in the node's configuration file, as described in [Configuration Overview](../Configuration%20Overview).
|
||||
For Tessera v0.10.2 onwards the ThirdParty API `/keys` endpoint can be used to view the public keys of the key pairs currently in use by your Tessera node.
|
||||
|
||||
For Tessera v0.10.1 and earlier, an ADMIN API endpoint `/config/keypairs` exists to allow you to view the public keys of the key pairs currently in use by your Tessera node.
|
||||
|
||||
A sample response for the request `adminhost:port/config/keypairs` is:
|
||||
```json
|
||||
|
||||
```json tab="v0.10.2 onwards"
|
||||
request: thirdpartyhost:port/keys
|
||||
{
|
||||
"keys" : [
|
||||
{
|
||||
"key" : "oNspPPgszVUFw0qmGFfWwh1uxVUXgvBxleXORHj07g8="
|
||||
},
|
||||
{
|
||||
"key" : "ABn6zhBth2qpdrJXp98IvjExV212ALl3j4U//nj4FAI="
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```json tab="v0.10.1 and earlier"
|
||||
request: adminhost:port/config/keypairs
|
||||
[
|
||||
{
|
||||
"publicKey" : "oNspPPgszVUFw0qmGFfWwh1uxVUXgvBxleXORHj07g8="
|
||||
|
|
@ -286,3 +424,5 @@ A sample response for the request `adminhost:port/config/keypairs` is:
|
|||
}
|
||||
]
|
||||
```
|
||||
|
||||
The corresponding server must be configured in the node's configuration file, as described in [Configuration Overview](../Configuration%20Overview).
|
||||
|
|
|
|||
|
|
@ -4,9 +4,77 @@ Tessera configuration varies by version as new features are added or changed. Be
|
|||
|
||||
| Version |
|
||||
| ------------- |
|
||||
| [0.10.2 - latest release](../Tessera%20v0.10.2%20sample%20settings) |
|
||||
| [0.10.3](../Tessera%20v0.10.3%20sample%20settings) |
|
||||
| [0.10.2](../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) |
|
||||
|
||||
## Changelist
|
||||
### 0.10.3
|
||||
- The `keys.azureKeyVaultConfig` and `keys.hashicorpKeyVaultConfig` fields are now deprecated. Instead, the generic `keys.keyVaultConfig` should be used. See [Keys Config](../Keys) for more info.
|
||||
|
||||
### 0.10.2
|
||||
- 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.
|
||||
```json
|
||||
{
|
||||
"encryptor": {
|
||||
"type":"EC",
|
||||
"properties":{
|
||||
"symmetricCipher":"AES/GCM/NoPadding",
|
||||
"ellipticCurve":"secp256r1",
|
||||
"nonceLength":"24",
|
||||
"sharedKeyLength":"32"
|
||||
}
|
||||
},
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
### 0.10
|
||||
- Added feature-toggle for remote key validation. Disabled by default.
|
||||
```json
|
||||
{
|
||||
"features": {
|
||||
"enableRemoteKeyValidation": false
|
||||
},
|
||||
...
|
||||
}
|
||||
```
|
||||
### 0.9
|
||||
- Collapsed server socket definitions into a single property `serverAddress`, e.g.
|
||||
```json
|
||||
{
|
||||
"serverConfigs": [
|
||||
{
|
||||
"serverSocket": {
|
||||
"type":"INET",
|
||||
"port": 9001,
|
||||
"hostName": "http://localhost"
|
||||
},
|
||||
...
|
||||
}
|
||||
],
|
||||
...
|
||||
}
|
||||
```
|
||||
becomes
|
||||
```json
|
||||
{
|
||||
"serverConfigs": [
|
||||
{
|
||||
"serverAddress": "http://localhost:9001",
|
||||
...
|
||||
}
|
||||
],
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
### 0.8
|
||||
- Added modular server configurations
|
||||
|
|
|
|||
|
|
@ -0,0 +1,133 @@
|
|||
**Changes:**
|
||||
|
||||
- The `keys.azureKeyVaultConfig` and `keys.hashicorpKeyVaultConfig` fields are now deprecated. Instead, the generic `keys.keyVaultConfig` should be used. See [Keys Config](../Keys) for more info.
|
||||
|
||||
**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",
|
||||
"keyVaultConfig": {
|
||||
"keyVaultType": "Enumeration: AZURE, HASHICORP, AWS",
|
||||
"properties": "Map[string]string"
|
||||
},
|
||||
"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)"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,51 @@
|
|||
# CLI config overrides (v0.10.2 and earlier)
|
||||
|
||||
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.
|
||||
|
||||
If a config value is included in both the `configfile` and the CLI, then the CLI value will take precedence. The exceptions to this rule are the `--peer.url <STRING>` and `--alwaysSendTo <STRING[]...>` options. Instead of overriding, these CLI options append to any peer or alwaysSendTo urls in the provided `configfile`. For example, if the following was provided in a `configfile`:
|
||||
```json
|
||||
{
|
||||
...
|
||||
"peer": [
|
||||
{
|
||||
"url": "http://localhost:9001"
|
||||
}
|
||||
],
|
||||
alwaysSendTo:[
|
||||
"giizjhZQM6peq52O7icVFxdTmTYinQSUsvyhXzgZqkE="
|
||||
],
|
||||
...
|
||||
}
|
||||
```
|
||||
and Tessera was run with the following overrides:
|
||||
```bash
|
||||
tessera -configfile path/to/file --peer.url http://localhost:9002 --peer.url http://localhost:9003 --alwaysSendTo /+UuD63zItL1EbjxkKUljMgG8Z1w0AJ8pNOR4iq2yQc= --alwaysSendTo UfNSeSGySeKg11DVNEnqrUtxYRVor4+CvluI8tVv62Y=
|
||||
```
|
||||
then Tessera will be started with the following equivalent configuration:
|
||||
```json
|
||||
{
|
||||
...
|
||||
"peer": [
|
||||
{
|
||||
"url": "http://localhost:9001"
|
||||
},
|
||||
{
|
||||
"url": "http://localhost:9002"
|
||||
},
|
||||
{
|
||||
"url": "http://localhost:9003"
|
||||
}
|
||||
],
|
||||
alwaysSendTo:[
|
||||
"giizjhZQM6peq52O7icVFxdTmTYinQSUsvyhXzgZqkE=",
|
||||
"/+UuD63zItL1EbjxkKUljMgG8Z1w0AJ8pNOR4iq2yQc="
|
||||
"UfNSeSGySeKg11DVNEnqrUtxYRVor4+CvluI8tVv62Y="
|
||||
],
|
||||
...
|
||||
}
|
||||
```
|
||||
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.
|
||||
|
||||
!!! info
|
||||
The only `encryptor` field that can be overriden is `encryptor.type`. All other `encryptor` fields can only be set in the configfile. See [encryptor config](../../../Configuration/Configuration Overview/#encryptor-supporting-alternative-curves-in-tessera) for more details.
|
||||
|
||||
|
|
@ -0,0 +1,49 @@
|
|||
# CLI config overrides
|
||||
|
||||
The `-o, --override` option is used to define overrides as key/value pairs. The key is the json path of the field to be overwritten.
|
||||
|
||||
For example, given `configfile.json`:
|
||||
```json
|
||||
{
|
||||
...,
|
||||
"jdbc" : {
|
||||
"username" : "sa",
|
||||
"password" : "",
|
||||
"url" : "jdbc:h2:/path/to/db1;MODE=Oracle;TRACE_LEVEL_SYSTEM_OUT=0",
|
||||
"autoCreateTables" : true,
|
||||
"fetchSize" : 0
|
||||
},
|
||||
"peer" : [
|
||||
{
|
||||
"url" : "http://127.0.0.1:9001"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The command:
|
||||
```bash
|
||||
tessera --configfile configfile.json -o jdbc.username=username-override --override peer[1].url=http://peer-override:9001
|
||||
```
|
||||
|
||||
will start Tessera with the following effective config:
|
||||
```json
|
||||
{
|
||||
...,
|
||||
"jdbc" : {
|
||||
"username" : "username-override",
|
||||
"password" : "",
|
||||
"url" : "jdbc:h2:/path/to/db1;MODE=Oracle;TRACE_LEVEL_SYSTEM_OUT=0",
|
||||
"autoCreateTables" : true,
|
||||
"fetchSize" : 0
|
||||
},
|
||||
"peer" : [
|
||||
{
|
||||
"url" : "http://127.0.0.1:9001"
|
||||
},
|
||||
{
|
||||
"url" : "http://peer-override:9001"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
|
@ -1,60 +1,8 @@
|
|||
CLI options can be used to add to, or override, configuration defined in a `configfile` or for `keygen`.
|
||||
CLI options can be used to add to, or override, configuration defined in a `configfile`.
|
||||
|
||||
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.
|
||||
`tessera help` and `tessera <command> help` will show the available list of commands and options.
|
||||
|
||||
If a config value is included in both the `configfile` and the CLI, then the CLI value will take precendence. The exceptions to this rule are the `--peer.url <STRING>` and `--alwaysSendTo <STRING[]...>` options. Instead of overriding, these CLI options append to any peer or alwaysSendTo urls in the provided `configfile`. For example, if the following was provided in a `configfile`:
|
||||
```
|
||||
{
|
||||
...
|
||||
"peer": [
|
||||
{
|
||||
"url": "http://localhost:9001"
|
||||
}
|
||||
],
|
||||
alwaysSendTo:[
|
||||
"giizjhZQM6peq52O7icVFxdTmTYinQSUsvyhXzgZqkE="
|
||||
],
|
||||
...
|
||||
}
|
||||
```
|
||||
and Tessera was run with the following overrides:
|
||||
```
|
||||
tessera -configfile path/to/file --peer.url http://localhost:9002 --peer.url http://localhost:9003 --alwaysSendTo /+UuD63zItL1EbjxkKUljMgG8Z1w0AJ8pNOR4iq2yQc= --alwaysSendTo UfNSeSGySeKg11DVNEnqrUtxYRVor4+CvluI8tVv62Y=
|
||||
```
|
||||
then Tessera will be started with the following equivalent configuration:
|
||||
```
|
||||
{
|
||||
...
|
||||
"peer": [
|
||||
{
|
||||
"url": "http://localhost:9001"
|
||||
},
|
||||
{
|
||||
"url": "http://localhost:9002"
|
||||
},
|
||||
{
|
||||
"url": "http://localhost:9003"
|
||||
}
|
||||
],
|
||||
alwaysSendTo:[
|
||||
"giizjhZQM6peq52O7icVFxdTmTYinQSUsvyhXzgZqkE=",
|
||||
"/+UuD63zItL1EbjxkKUljMgG8Z1w0AJ8pNOR4iq2yQc="
|
||||
"UfNSeSGySeKg11DVNEnqrUtxYRVor4+CvluI8tVv62Y="
|
||||
],
|
||||
...
|
||||
}
|
||||
```
|
||||
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
|
||||
| Version |
|
||||
| ------------- |
|
||||
| [0.10.3 onwards](../Using CLI to override config v0.10.3) |
|
||||
| [0.10.2 and earlier](../Using CLI to override config pre-v0.10.3) |
|
||||
|
|
|
|||
|
|
@ -1,90 +1,105 @@
|
|||
## Generating keys
|
||||
|
||||
Key generation can be used in multiple ways:
|
||||
### File-stored keys
|
||||
Generate a key pair and save in new files `new.pub` and `new.key` (will start an interactive prompt to provide passwords):
|
||||
```
|
||||
tessera -keygen -filename new
|
||||
```
|
||||
Multiple key pairs can be generated at the same time by providing a comma-separated list of values:
|
||||
```
|
||||
tessera -keygen -filename /path/to/key1,/path/to/key2
|
||||
```
|
||||
|
||||
1. Generate a key pair and save in new files `.pub` and `.key`:
|
||||
```
|
||||
tessera -keygen
|
||||
```
|
||||
This command will require interactive input for passwords.
|
||||
If you wish to generate an unlocked key, `/dev/null` can be used for stdin to tell the application not to expect any input (version 0.8 only):
|
||||
```
|
||||
# Version 0.8+
|
||||
tessera -keygen < /dev/null
|
||||
To generate an unlocked key, the following can be used to tell Tessera to not expect any input:
|
||||
|
||||
# Version 0.7.x or before
|
||||
printf "\n\n" | tessera -keygen
|
||||
```
|
||||
```bash tab="v0.8.x onwards"
|
||||
tessera -keygen < /dev/null
|
||||
```
|
||||
|
||||
The `-filename` option can be used to specify alternate filepaths. Multiple key pairs can be generated at the same time by providing a comma-separated list of values:
|
||||
```
|
||||
tessera -keygen -filename /path/to/key1,/path/to/key2
|
||||
```
|
||||
```bash tab="v0.7.x and earlier"
|
||||
printf "\n\n" | tessera -keygen
|
||||
```
|
||||
|
||||
1. Generate a key pair and save to an Azure Key Vault, with DNS name `<url>`, as secrets with IDs `Pub` and `Key`:
|
||||
```
|
||||
tessera -keygen -keygenvaulttype AZURE -keygenvaulturl <url>
|
||||
```
|
||||
|
||||
The `-filename` option can be used to specify alternate IDs. Multiple key pairs can be generated at the same time by providing a comma-separated list of values:
|
||||
```
|
||||
tessera -keygen -keygenvaulttype AZURE -keygenvaulturl <url> -filename id1,id2
|
||||
```
|
||||
|
||||
**Note: If saving new keys with the same ID as keys that already exist in the vault, the existing keys will be replaced by the newer version.**
|
||||
|
||||
> Environment variables must be set if using an Azure Key Vault, for more information see [Setting up an Azure key vault](../Setting%20up%20an%20Azure%20Key%20Vault)
|
||||
|
||||
1. Generate a key pair and save to a Hashicorp Vault at the secret path `secretEngine/secretName` with IDs `publicKey` and `privateKey`:
|
||||
```bash
|
||||
tessera -keygen -keygenvaulttype HASHICORP -keygenvaulturl <url> \
|
||||
-keygenvaultsecretengine secretEngine -filename secretName
|
||||
```
|
||||
Options exist for configuring TLS and AppRole authentication (by default the AppRole path is set to `approle`):
|
||||
```bash
|
||||
tessera -keygen -keygenvaulttype HASHICORP -keygenvaulturl <url> \
|
||||
-keygenvaultsecretengine <secretEngineName> -filename <secretName> \
|
||||
-keygenvaultkeystore <JKS file> -keygenvaulttruststore <JKS file> \
|
||||
-keygenvaultapprole <authpath>
|
||||
```
|
||||
The `-filename` option can be used to generate and store multiple key pairs at the same time:
|
||||
```bash
|
||||
tessera -keygen -keygenvaulttype HASHICORP -keygenvaulturl <url> \
|
||||
-keygenvaultsecretengine secretEngine -filename myNode/keypairA,myNode/keypairB
|
||||
```
|
||||
**Saving a new key pair to an existing secret will overwrite the values stored at that secret. Previous versions of secrets may be retained and be retrievable by Tessera depending on how the K/V secrets engine is configured. See [Keys](../../../Configuration/Keys) for more information on configuring Tessera for use with Vault.**
|
||||
|
||||
> Environment variables must be set if using a Hashicorp Vault, and a version 2 K/V secret engine must be enabled. For more information see [Setting up a Hashicorp Vault](../Setting%20up%20a%20Hashicorp%20Vault).
|
||||
### Azure Key Vault-stored keys
|
||||
Generate a key pair as secrets with IDs `Pub` and `Key` and save to an Azure Key Vault with DNS name `<url>`:
|
||||
```
|
||||
tessera -keygen -keygenvaulttype AZURE -keygenvaulturl <url>
|
||||
```
|
||||
|
||||
1. Generate a key pair and save to an AWS Secrets Manager, with endpoint `<url>`, as secrets with IDs `Pub` and `Key`:
|
||||
The `-filename` option can be used to specify alternate IDs. Multiple key pairs can be generated at the same time by providing a comma-separated list of values:
|
||||
```
|
||||
tessera -keygen -keygenvaulttype AZURE -keygenvaulturl <url> -filename id1,id2
|
||||
```
|
||||
|
||||
```bash
|
||||
tessera -keygen -keygenvaulttype AWS -keygenvaulturl <url>
|
||||
```
|
||||
|
||||
The `-filename` option can be used to specify alternate IDs. Multiple key pairs can be generated at the same time by providing a comma-separated list of values:
|
||||
|
||||
```bash
|
||||
tessera -keygen -keygenvaulttype AWS -keygenvaulturl <url> -filename id1,id2
|
||||
```
|
||||
|
||||
>Environment variables must be set if using an AWS Secrets Manager, for more information see [Setting up an AWS Secrets Manager](../Setting%20up%20an%20AWS%20Secrets%20Manager)
|
||||
!!! warning
|
||||
If saving new keys with the same ID as keys that already exist in the vault, the existing keys will be replaced by the newer version. When doing this, make sure to [specify the correct secret version in your Tessera configuration](../../../Configuration/Keys/#azure-key-vault-key-pairs)
|
||||
|
||||
1. Generate a key pair, save to files and then start Tessera using a provided config
|
||||
```
|
||||
tessera -keygen -configfile /path/to/config.json
|
||||
```
|
||||
```
|
||||
tessera -keygen -filename key1 -configfile /path/to/config.json
|
||||
```
|
||||
Tessera loads `config.json` as usual and includes the newly generated key data before starting.
|
||||
|
||||
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
|
||||
Environment variables must be set if using an Azure Key Vault, for more information see [Setting up an Azure key vault](../Setting%20up%20an%20Azure%20Key%20Vault)
|
||||
|
||||
!!! note
|
||||
By default the `-keygen` commands generate [NaCl](https://nacl.cr.yp.to/) compatible keys.
|
||||
### Hashicorp Vault-stored keys
|
||||
Generate a key pair and save to a Hashicorp Vault at the secret path `secretEngine/secretName` with IDs `publicKey` and `privateKey`:
|
||||
```bash
|
||||
tessera -keygen -keygenvaulttype HASHICORP -keygenvaulturl <url> \
|
||||
-keygenvaultsecretengine secretEngine -filename secretName
|
||||
```
|
||||
Options exist for configuring TLS and AppRole authentication (by default the AppRole path is set to `approle`):
|
||||
```bash
|
||||
tessera -keygen -keygenvaulttype HASHICORP -keygenvaulturl <url> \
|
||||
-keygenvaultsecretengine <secretEngineName> -filename <secretName> \
|
||||
-keygenvaultkeystore <JKS file> -keygenvaulttruststore <JKS file> \
|
||||
-keygenvaultapprole <authpath>
|
||||
```
|
||||
The `-filename` option can be used to generate and store multiple key pairs at the same time:
|
||||
```bash
|
||||
tessera -keygen -keygenvaulttype HASHICORP -keygenvaulturl <url> \
|
||||
-keygenvaultsecretengine secretEngine -filename myNode/keypairA,myNode/keypairB
|
||||
```
|
||||
|
||||
!!! warning
|
||||
Saving a new key pair to an existing secret will overwrite the values stored at that secret. Previous versions of secrets may be retained and be retrievable by Tessera depending on how the K/V secrets engine is configured. When doing this, make sure to [specify the correct secret version in your Tessera configuration](../../../Configuration/Keys/#hashicorp-vault-key-pairs)
|
||||
|
||||
!!! note
|
||||
Environment variables must be set if using a Hashicorp Vault, and a version 2 K/V secret engine must be enabled. For more information see [Setting up a Hashicorp Vault](../Setting%20up%20a%20Hashicorp%20Vault)
|
||||
|
||||
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.
|
||||
|
||||
### AWS Secrets Manager-stored keys
|
||||
Generate a key pair and save to an AWS Secrets Manager, with endpoint `<url>`, as secrets with IDs `Pub` and `Key`:
|
||||
|
||||
```bash
|
||||
tessera -keygen -keygenvaulttype AWS -keygenvaulturl <url>
|
||||
```
|
||||
|
||||
The `-filename` option can be used to specify alternate IDs. Multiple key pairs can be generated at the same time by providing a comma-separated list of values:
|
||||
|
||||
```bash
|
||||
tessera -keygen -keygenvaulttype AWS -keygenvaulturl <url> -filename id1,id2
|
||||
```
|
||||
|
||||
!!! note
|
||||
Environment variables must be set if using an AWS Secrets Manager, for more information see [Setting up an AWS Secrets Manager](../Setting%20up%20an%20AWS%20Secrets%20Manager)
|
||||
|
||||
### Updating a configfile with newly generated keys
|
||||
Any newly generated keys must be added to a Tessera `.json` configfile. Often it is easiest to do this manually.
|
||||
|
||||
However, the `tessera keygen` `-configfile` option can be used to automatically update a configfile after key generation. This is particularly useful when scripting.
|
||||
|
||||
```
|
||||
tessera -keygen -filename key1 -configfile /path/to/config.json --configout /path/to/new.json --pwdout /path/to/new.pwds
|
||||
```
|
||||
|
||||
The above command will prompt for a password and generate the `key1` pair as usual. The Tessera configuration from `/path/to/config.json` will be read, updated and saved to `/path/to/new.json`. New passwords will be appended to the existing password file as defined in `/path/to/config.json` and written to `/path/to/new.pwds`.
|
||||
|
||||
If the `--configout` and `--pwdout` options are not provided, the updated `.json` config will be printed to the terminal.
|
||||
|
||||
!!! note "Note: Differences between v0.10.3 and earlier versions"
|
||||
Before Tessera version 0.10.3 the node would start after updating the configfile.
|
||||
|
||||
In v0.10.3, this behaviour was removed to ensure clearer distinction of responsibilities between each Tessera command. The same behaviour can be achieved in v0.10.3 onwards by running:
|
||||
```
|
||||
tessera keygen ... -output /path/to/new.json
|
||||
tessera -configfile /path/to/new.json
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
|
@ -132,7 +147,7 @@ Password update can be used in multiple ways. Running any of these commands wil
|
|||
```
|
||||
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.
|
||||
## Using alternative curve key types
|
||||
By default the `-keygen` and `-updatepassword` commands generate and update [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/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