Documentation for Tessera AWS Secrets Manager implementation

docs/Privacy/Tessera/Configuration/Keys.md

@@ -19,6 +19,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
@@ -219,6 +225,33 @@ 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
+"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.  
 

docs/Privacy/Tessera/Tessera Services/Keys/Keys.md

@@ -56,6 +56,20 @@ If you wish to generate an unlocked key, `/dev/null` can be used for stdin to te
 
     > 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).
 
+1. 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
+    ```
+
+    >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)
+
 1. Generate a key pair, save to files and then start Tessera using a provided config
     ```
     tessera -keygen -configfile /path/to/config.json

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-<version>-app.jar`.  If using the `tessera-simple-<version>-app.jar` then `aws-key-vault-<version>-all.jar` must be added to the classpath.

mkdocs.yml

@@ -61,6 +61,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