Usage

Install


Create a Secrets Group

A Secrets Group is a collection of secrets that are managed together. When you create a Secrets Group, Strongbox will allocate a DynamoDB table, a KMS Encryption Key, and two IAM Policies: one for read-only access to the Secrets Group, and one for admin access.

The KMS key will be used for envelope encryption using the AWS Encryption SDK. DynamoDB will store all the data, most of which is encrypted. The IAM policies will limit the access to the DynamoDB table and the KMS key as appropriate for the respective access level.

You can omit --region <region> if you have specified a region in ~/.aws/config. You can specify an AWS profile using --profile <profile>, otherwise the default profile will be used. Assume role and MFA config can also be specified in ~/.aws/config.

Launch via the CLI: 

strongbox --region eu-west-1 gui

strongbox --region eu-west-1 group create team.project
SecretsGroupManager sgm = new DefaultSecretsGroupManager();
sgm.create(new SecretsGroupIdentifier(Region.EU_WEST_1, "team.project"));


Create a Secret

You can create a secret from an existing value, from a file or by generating one using KMS. When you create a secret it will be encrypted using the KMS Encryption SDK and stored in DynamoDB.

The following command will prompt you to enter the secret. You can also pipe or redirect into the same command. 

strongbox --region eu-west-1 secret create --group team.project --name MySecret --value-from-stdin

SecretsGroupManager sgm = new DefaultSecretsGroupManager();
SecretsGroup sg = sgm.get(new SecretsGroupIdentifier(Region.EU_WEST_1, "team.project"));
sg.create(new NewSecretEntry(new SecretIdentifier("MySecret"), new SecretValue("1234", SecretType.OPAQUE), State.ENABLED));


Grant Read-only Access to a Secrets Group

Read-only access is provided on a per Secrets Group basis. To help avoid misconfiguration Strongbox generates a suitable read-only policy for you. Access is granted by attaching to this policy, either using one of AWS' methods of doing so, or by using Strongbox as shown below. 

strongbox --region eu-west-1 group attach-readonly --group team.project --type role my-role
SecretsGroupManager sgm = new DefaultSecretsGroupManager();
SecretsGroupIdentifier group = new SecretsGroupIdentifier(Region.EU_WEST_1, "team.project");
Principal principal = new Principal(PrincipalType.ROLE, "my-role");
sgm.attachReadOnly(group, principal);


Fetch a Secret

Secrets are read from DynamoDB and then decrypted using the AWS Encryption SDK. In addition to the examples below there are also integrations with Spring Boot and Archaius.

Get the most recent secret 

strongbox --region eu-west-1 secret get --group team.project --name MySecret

Get a specific version of a secret 

strongbox --region eu-west-1 secret get --group team.project --name MySecret --version 1

Redirect the value to a file (works for both string and binary secrets) 

strongbox --region eu-west-1 secret get --group team.project --name MySecret > my.file

For more examples see the Wiki.

Get the Secrets Group 

SecretsGroupIdentifier group = new SecretsGroupIdentifier(Region.EU_WEST_1, "team.project");
SimpleSecretsGroup sg = new DefaultSimpleSecretsGroup(group);

Get the most recent version of a String secret 

sg.getStringSecret("MySecret");

Get a specific version of a String secret 

sg.getStringSecret("MySecret", 1);

Get a specific version of a binary secret 

sg.getBinarySecret("MySecret", 1);

Get all String secrets 

List<StringSecretEntry> all = sg.getAllStringSecrets();

For a complete example see the example repo.

For an overview of additional functionality see the Javadoc for SecretsGroup and SimpleSecretsGroup.