github.com/hyperion-hyn/go-ethereum@v2.4.0+incompatible/docs/Privacy/Tessera/Configuration/Keys.md (about)

     1  Tessera uses cryptographic keys to provide transaction privacy.  
     2  
     3  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.
     4  ```json
     5  "keys": {
     6      "passwords": [],
     7      "passwordFile": "Path",
     8      "azureKeyVaultConfig": {
     9          "url": "Url"
    10      },
    11      "hashicorpKeyVaultConfig": {
    12          "url": "Url",
    13          "approlePath": "String",
    14          "tlsKeyStorePath": "Path",
    15          "tlsTrustStorePath": "Path" 
    16      },
    17      "keyData": [
    18          {
    19              // The data for a private/public key pair
    20          }
    21      ]
    22  }
    23  ```
    24  
    25  ## KeyData
    26  Key pairs can be provided in several ways:
    27  
    28  ### Direct key pairs
    29  
    30  !!! warning
    31      Direct key pairs and unprotected inline key pairs are convenient but are the least secure configuration options available as the private key is exposed in the configuration file. The other options available are more secure and recommended for production environments.
    32  
    33  The key pair data is provided in plain text in the configfile.
    34  
    35  ```json
    36  "keys": {
    37      "keyData": [
    38          {
    39          "privateKey": "yAWAJjwPqUtNVlqGjSrBmr1/iIkghuOh1803Yzx9jLM=",
    40          "publicKey": "/+UuD63zItL1EbjxkKUljMgG8Z1w0AJ8pNOR4iq2yQc="
    41          }
    42      ]
    43  }
    44  ```  
    45  
    46  ### Inline key pairs
    47  #### Unprotected
    48  
    49  !!! warning
    50      Direct key pairs and unprotected inline key pairs are convenient but are the least secure configuration options available as the private key is exposed in the configuration file. The other options available are more secure and recommended for production environments.
    51      
    52  The key pair data is provided in plain text in the configfile.  The plain text private key is provided in a `config` json object:
    53  ```json
    54  "keys": {
    55      "keyData": [
    56          {
    57              "config": {
    58                  "data": {
    59                      "bytes": "yAWAJjwPqUtNVlqGjSrBmr1/iIkghuOh1803Yzx9jLM="
    60                  },
    61                  "type": "unlocked"
    62              },
    63              "publicKey": "/+UuD63zItL1EbjxkKUljMgG8Z1w0AJ8pNOR4iq2yQc="
    64          }
    65      ]
    66  }     
    67  ```
    68  
    69  #### Protected
    70  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.
    71  
    72  ```json
    73  "keys": {
    74      "passwords": ["password"],
    75      "passwordFile": "/path/to/pwds.txt",
    76      "keyData": [
    77          {
    78              "config": {
    79                  "data": {
    80                      "aopts": {
    81                          "variant": "id",
    82                          "memory": 1048576,
    83                          "iterations": 10,
    84                          "parallelism": 4,
    85                      },
    86                      "snonce": "x3HUNXH6LQldKtEv3q0h0hR4S12Ur9pC",
    87                      "asalt": "7Sem2tc6fjEfW3yYUDN/kSslKEW0e1zqKnBCWbZu2Zw=",
    88                      "sbox": "d0CmRus0rP0bdc7P7d/wnOyEW14pwFJmcLbdu2W3HmDNRWVJtoNpHrauA/Sr5Vxc"
    89                  },
    90                  "type": "argon2sbox"
    91              },
    92              "publicKey": "/+UuD63zItL1EbjxkKUljMgG8Z1w0AJ8pNOR4iq2yQc="
    93          }
    94      ]
    95  }
    96  ```
    97  
    98  Passwords must be provided so that Tessera can decrypt and use the private keys.  Passwords can be provided in multiple ways:
    99  
   100  |        | Description                                                                                                                                                                  |
   101  |--------|--------------|
   102  | File   | `"passwordFile": "/path/to/pwds.txt"`<br/>Must contain only one password per line.  Empty lines should be used for unlocked keys.  Passwords must be provided in the order that key pairs are defined in the config. |
   103  | Direct | `"passwords": ["pwd1", "pwd2", ...]`<br/>Empty strings should be used for unlocked keys.  Passwords must be provided in the order that key pairs are defined in the config.  Not recommended for production use.     |
   104  | CLI    | Tessera will prompt on the CLI for the passwords of any encrypted keys that have not had passwords provided in the config.  This process only needs to be performed once, when starting the node.              |
   105  
   106  ### Filesystem key pairs   
   107  The keys in the pair are stored in files:
   108  ```json
   109  "keys": {
   110      "passwords": ["password"],
   111      "passwordFile": "/path/to/pwds.txt",
   112      "keyData": [
   113          {
   114              "privateKeyPath": "/path/to/privateKey.key",
   115              "publicKeyPath": "/path/to/publicKey.pub"
   116          }
   117      ]
   118  }
   119  ```
   120  The contents of the public key file must contain the public key only, e.g.: 
   121  ```
   122  /+UuD63zItL1EbjxkKUljMgG8Z1w0AJ8pNOR4iq2yQc=
   123  ```
   124  
   125  The contents of the private key file must contain the private key in the Inline key pair format, e.g.:
   126  ```json
   127  {
   128      "type" : "unlocked",
   129      "data" : {
   130          "bytes" : "DK0HDgMWJKtZVaP31mPhk6TJNACfVzz7VZv2PsQZeKM="
   131      }
   132  }
   133  ```
   134  
   135  or
   136  
   137  ```json
   138  {
   139      "data": {
   140          "aopts": {
   141              "variant": "id",
   142              "memory": 1048576,
   143              "iterations": 10,
   144              "parallelism": 4,
   145          },
   146          "snonce": "x3HUNXH6LQldKtEv3q0h0hR4S12Ur9pC",
   147          "asalt": "7Sem2tc6fjEfW3yYUDN/kSslKEW0e1zqKnBCWbZu2Zw=",
   148          "sbox": "d0CmRus0rP0bdc7P7d/wnOyEW14pwFJmcLbdu2W3HmDNRWVJtoNpHrauA/Sr5Vxc"
   149      },
   150      "type": "argon2sbox"
   151  }
   152  ```
   153  
   154  Passwords must be provided so that Tessera can decrypt and use the private keys.  Passwords can be provided in multiple ways:
   155  
   156  |        | Description                                                                                                                                                                  |
   157  |--------|--------------|
   158  | File   | `"passwordFile": "/path/to/pwds.txt"`<br/>Must contain only one password per line.  Empty lines should be used for unlocked keys.  Passwords must be provided in the order that key pairs are defined in the config. |
   159  | Direct | `"passwords": ["pwd1", "pwd2", ...]`<br/>Empty strings should be used for unlocked keys.  Passwords must be provided in the order that key pairs are defined in the config.  Not recommended for production use.     |
   160  | CLI    | Tessera will prompt on the CLI for the passwords of any encrypted keys that have not had passwords provided in the config.  This process only needs to be performed once, when starting the node.              |
   161  
   162  ### Azure Key Vault key pairs
   163  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:
   164  ```json
   165  "keys": {
   166      "azureKeyVaultConfig": {
   167          "url": "https://my-vault.vault.azure.net"
   168      },
   169      "keyData": [
   170          {
   171              "azureVaultPrivateKeyId": "Key",
   172              "azureVaultPublicKeyId": "Pub",
   173              "azureVaultPublicKeyVersion": "bvfw05z4cbu11ra2g94e43v9xxewqdq7",
   174              "azureVaultPrivateKeyVersion": "0my1ora2dciijx5jq9gv07sauzs5wjo2"
   175          }
   176      ]
   177  }
   178  ```
   179  
   180  This example configuration will retrieve the specified versions of the secrets `Key` and `Pub` from the key vault with DNS name `https://my-vault.vault.azure.net`.    If no version is specified then the latest version of the secret is retrieved.
   181  
   182  !!! info
   183      Environment variables must be set if using an Azure Key Vault, for more information see [Setting up an Azure Key Vault](../../Tessera%20Services/Keys/Setting%20up%20an%20Azure%20Key%20Vault)
   184  
   185  ### Hashicorp Vault key pairs
   186  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`):
   187  ```json
   188  "hashicorpKeyVaultConfig": {
   189      "url": "https://localhost:8200",
   190      "tlsKeyStorePath": "/path/to/keystore.jks",
   191      "tlsTrustStorePath": "/path/to/truststore.jks",
   192      "approlePath": "not-default",
   193  },
   194  "keyData": [
   195      {
   196          "hashicorpVaultSecretEngineName": "engine",
   197          "hashicorpVaultSecretName": "secret",
   198          "hashicorpVaultSecretVersion": 1,
   199          "hashicorpVaultPrivateKeyId": "privateKey",
   200          "hashicorpVaultPublicKeyId": "publicKey",
   201      }
   202  ]
   203  ```
   204  
   205  This example configuration will retrieve version 1 of the secret `engine/secret` from Vault and its corresponding values for `privateKey` and `publicKey`.  
   206  
   207  If no `hashicorpVaultSecretVersion` is provided then the latest version for the secret will be retrieved by default.
   208  
   209  Tessera requires TLS certificates and keys to be stored in `.jks` Java keystore format.  If the `.jks` files are password protected then the following environment variables must be set: 
   210  
   211  * `HASHICORP_CLIENT_KEYSTORE_PWD`
   212  * `HASHICORP_CLIENT_TRUSTSTORE_PWD` 
   213  
   214  !!! info
   215      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).
   216  
   217  ## Multiple Keys
   218  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.
   219  
   220  Note that multiple key pairs can only be set up within the configuration file, not via separate filesystem key files.
   221  
   222  ## Viewing the keys registered for a node
   223  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).
   224  
   225  A sample response for the request `adminhost:port/config/keypairs` is:
   226  ```json
   227  [
   228     {
   229        "publicKey" : "oNspPPgszVUFw0qmGFfWwh1uxVUXgvBxleXORHj07g8="
   230     },
   231     {
   232        "publicKey" : "ABn6zhBth2qpdrJXp98IvjExV212ALl3j4U//nj4FAI="
   233     }
   234  ]
   235  ```