From d16b9d27e77fb64dbc29b0e6cc86f351f12038e2 Mon Sep 17 00:00:00 2001 From: chris-j-h <39617426+chris-j-h@users.noreply.github.com> Date: Mon, 10 Feb 2020 15:30:38 +0000 Subject: [PATCH] docs(tessera): CLI and configfile updates (#929) --- docs/FAQ.md | 8 + docs/Privacy/Tessera/Configuration/Keys.md | 187 +++++++++++++++++- .../Configuration/Sample Configuration.md | 70 ++++++- .../Tessera v0.10.3 sample settings.md | 133 +++++++++++++ ...sing CLI to override config pre-v0.10.3.md | 51 +++++ .../Using CLI to override config v0.10.3.md | 49 +++++ .../Using CLI to override config.md | 64 +----- .../Tessera/Tessera Services/Keys/Keys.md | 164 ++++++++------- .../Keys/Setting up an AWS Secrets Manager.md | 29 +++ mkdocs.yml | 1 + 10 files changed, 622 insertions(+), 134 deletions(-) create mode 100644 docs/Privacy/Tessera/Configuration/Tessera v0.10.3 sample settings.md create mode 100644 docs/Privacy/Tessera/Configuration/Using CLI to override config pre-v0.10.3.md create mode 100644 docs/Privacy/Tessera/Configuration/Using CLI to override config v0.10.3.md create mode 100644 docs/Privacy/Tessera/Tessera Services/Keys/Setting up an AWS Secrets Manager.md diff --git a/docs/FAQ.md b/docs/FAQ.md index ce4489cfa..30b0ffae3 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -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. Red color signifies that while connectivity is possible, red colored 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?" diff --git a/docs/Privacy/Tessera/Configuration/Keys.md b/docs/Privacy/Tessera/Configuration/Keys.md index 38cb0f42b..6586ab1d2 100644 --- a/docs/Privacy/Tessera/Configuration/Keys.md +++ b/docs/Privacy/Tessera/Configuration/Keys.md @@ -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", @@ -19,6 +57,12 @@ You can use existing private/public key pairs as well as use Tessera to generate "tlsKeyStorePath": "Path", "tlsTrustStorePath": "Path" }, + "keyVaultConfig": { + "keyVaultConfigType": "AWS", + "properties": { + "endpoint": "Url" + } + }, "keyData": [ { // The data for a private/public key pair @@ -74,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", @@ -110,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", @@ -122,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= @@ -166,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" @@ -189,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", @@ -219,6 +344,34 @@ 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). +### 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 tab="v0.10.3 onwards" +"keys": { + "keyVaultConfig": { + "keyVaultConfigType": "AWS", + "properties": { + "endpoint": "https://secretsmanager.us-west-2.amazonaws.com" + } + }, + "keyData": [ + { + "awsSecretsManagerPublicKeyId": "secretIdPub", + "awsSecretsManagerPrivateKeyId": "secretIdKey" + } + ] + } +``` + +This example configuration will retrieve the secrets `secretIdPub` and `secretIdKey` from the _AWS Secrets Manager_ using the endpoint `https://secretsmanager.us-west-2.amazonaws.com`. + +!!! info + A `Credential should be scoped to a valid region` error when starting means that the region specified in the `endpoint` differs from the region the AWS SDK has retrieved from its [property retrieval chain](https://docs.aws.amazon.com/sdk-for-java/v2/developer-guide/credentials.html). This can be resolved by setting the `AWS_REGION` environment variable to the same region as defined in the `endpoint`. + +!!! info + Environment variables must be set if using an _AWS Secrets Manager_, for more information see [Setting up an AWS Secrets Manager](../../Tessera%20Services/Keys/Setting%20up%20an%20AWS%20Secrets%20Manager) + ## 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. @@ -240,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=" @@ -253,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). diff --git a/docs/Privacy/Tessera/Configuration/Sample Configuration.md b/docs/Privacy/Tessera/Configuration/Sample Configuration.md index a633b763a..f3f4c0716 100644 --- a/docs/Privacy/Tessera/Configuration/Sample Configuration.md +++ b/docs/Privacy/Tessera/Configuration/Sample Configuration.md @@ -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 diff --git a/docs/Privacy/Tessera/Configuration/Tessera v0.10.3 sample settings.md b/docs/Privacy/Tessera/Configuration/Tessera v0.10.3 sample settings.md new file mode 100644 index 000000000..8ec39eb1d --- /dev/null +++ b/docs/Privacy/Tessera/Configuration/Tessera v0.10.3 sample settings.md @@ -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)" + } + } +} +``` diff --git a/docs/Privacy/Tessera/Configuration/Using CLI to override config pre-v0.10.3.md b/docs/Privacy/Tessera/Configuration/Using CLI to override config pre-v0.10.3.md new file mode 100644 index 000000000..830866ff4 --- /dev/null +++ b/docs/Privacy/Tessera/Configuration/Using CLI to override config pre-v0.10.3.md @@ -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 `), whilst the config override options are prefixed with a double hyphen (e.g. `--alwaysSendTo `). 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 ` and `--alwaysSendTo ` 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. + diff --git a/docs/Privacy/Tessera/Configuration/Using CLI to override config v0.10.3.md b/docs/Privacy/Tessera/Configuration/Using CLI to override config v0.10.3.md new file mode 100644 index 000000000..5f2231a69 --- /dev/null +++ b/docs/Privacy/Tessera/Configuration/Using CLI to override config v0.10.3.md @@ -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" + } + ] +} +``` diff --git a/docs/Privacy/Tessera/Configuration/Using CLI to override config.md b/docs/Privacy/Tessera/Configuration/Using CLI to override config.md index 3f3534d15..4fbb3bfee 100644 --- a/docs/Privacy/Tessera/Configuration/Using CLI to override config.md +++ b/docs/Privacy/Tessera/Configuration/Using CLI to override config.md @@ -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 `), whilst the config override options are prefixed with a double hyphen (e.g. `--alwaysSendTo `). Use `tessera help` to see a complete list of CLI options. +`tessera help` and `tessera 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 ` and `--alwaysSendTo ` 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 --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) | diff --git a/docs/Privacy/Tessera/Tessera Services/Keys/Keys.md b/docs/Privacy/Tessera/Tessera Services/Keys/Keys.md index d6c5694e1..f7ae81a91 100644 --- a/docs/Privacy/Tessera/Tessera Services/Keys/Keys.md +++ b/docs/Privacy/Tessera/Tessera Services/Keys/Keys.md @@ -1,76 +1,104 @@ ## 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 ``, as secrets with IDs `Pub` and `Key`: - ``` - tessera -keygen -keygenvaulttype AZURE -keygenvaulturl - ``` - - 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 -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 \ - -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 \ - -keygenvaultsecretengine -filename \ - -keygenvaultkeystore -keygenvaulttruststore \ - -keygenvaultapprole - ``` - The `-filename` option can be used to generate and store multiple key pairs at the same time: - ```bash - tessera -keygen -keygenvaulttype HASHICORP -keygenvaulturl \ - -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 ``: +``` +tessera -keygen -keygenvaulttype AZURE -keygenvaulturl +``` -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. +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 -filename id1,id2 +``` -!!! note - By default the `-keygen` commands generate [NaCl](https://nacl.cr.yp.to/) compatible keys. +!!! 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) + +!!! 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) + +### 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 \ + -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 \ + -keygenvaultsecretengine -filename \ + -keygenvaultkeystore -keygenvaulttruststore \ + -keygenvaultapprole +``` +The `-filename` option can be used to generate and store multiple key pairs at the same time: +```bash +tessera -keygen -keygenvaulttype HASHICORP -keygenvaulturl \ + -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 ``, as secrets with IDs `Pub` and `Key`: + +```bash +tessera -keygen -keygenvaulttype AWS -keygenvaulturl +``` + +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 -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. @@ -118,7 +146,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. diff --git a/docs/Privacy/Tessera/Tessera Services/Keys/Setting up an AWS Secrets Manager.md b/docs/Privacy/Tessera/Tessera Services/Keys/Setting up an AWS Secrets Manager.md new file mode 100644 index 000000000..bd434c0b2 --- /dev/null +++ b/docs/Privacy/Tessera/Tessera Services/Keys/Setting up an AWS Secrets Manager.md @@ -0,0 +1,29 @@ + +The private/public key pairs used by Tessera can be [stored](../Keys) in and [retrieved](../../../Configuration/Keys) from a key vault, preventing the need to store the keys locally. + +This page details how to set up and configure an _AWS Secrets Manager_ for use with Tessera. + +The _AWS Secrets Manager_ documentation provides much of the information needed to get started. The information in this section has been taken from the following pages of the _AWS_ documentation: + +* [AWS Secrets Manager User Guide](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) +* [AWS SDK for Java Developer Guide](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/welcome.html) + +## Creating the AWS Secrets Manager + +Once you have set up your AWS profile, you will be able to use AWS Secrets Manager. + +## Enabling Tessera to use the _AWS Secrets Manager_ +### Environment Variables + +If using an _AWS Secrets Manager_, configuration credentials can be provided in many ways as outlined in the [AWS docs - Supplying and Retrieving AWS Credentials](https://docs.aws.amazon.com/sdk-for-java/v2/developer-guide/credentials.html). + +To use environment variables set the following: + +1. `AWS_REGION`: region_to_connect_to (i.e. us-west-2) +1. `AWS_ACCESS_KEY_ID`: your_access_key_id +1. `AWS_SECRET_ACCESS_KEY`: your_secret_access_key + +The `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` for a particular user can be retrieved from the [AWS IAM Management Console](https://console.aws.amazon.com/iam). + +### Dependencies +The AWS Secrets Manager dependencies are included in the `tessera-app--app.jar`. If using the `tessera-simple--app.jar` then `aws-key-vault--all.jar` must be added to the classpath. diff --git a/mkdocs.yml b/mkdocs.yml index 9a54224ea..3ad610243 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -64,6 +64,7 @@ nav: - Key Generation: Privacy/Tessera/Tessera Services/Keys/Keys.md - Setting up Hashicorp Vault: Privacy/Tessera/Tessera Services/Keys/Setting up a Hashicorp Vault.md - Setting up Azure Key Vault: Privacy/Tessera/Tessera Services/Keys/Setting up an Azure Key Vault.md + - Setting up AWS Secrets Manager: Privacy/Tessera/Tessera Services/Keys/Setting up an AWS Secrets Manager.md - Usage: - Interfaces & API: Privacy/Tessera/Usage/Interface & API.md - Admin Usage: Privacy/Tessera/Usage/Admin Usage.md