:warning: Biscuit is no longer maintained. Do not use Biscuit on new projects.

Biscuit

Biscuit is a simple key-value store for your infrastructure secrets.

Is Biscuit right for me?

Biscuit is most useful to teams already using AWS and IAM to manage their infrastructure. If that describes your team, then Biscuit might be useful to you if you answer "yes" to any of these questions:

• Do you live in constant fear of accidentally committing infrastructure secrets to source control?
• Do you commit private keys to your source repository?
• Do you share passwords with other developers?
• Do you want to manage secrets securely across multiple regions?

Features

• Provides a simple key/value CLI to secure storage.
• Secrets can live alongside with your code in source control.
• Operates with KMS keys across multiple regions.
• Facilitates management of AWS IAM Policies, KMS Policies, and KMS Grants across multiple regions.
• Local encryption using AES-GCM-256 or Secretbox (NaCL).
• Offline mode: Using the "testing" key manager, you can use Biscuit in test environments without changing your code and without network dependencies.

Feature Comparison

| Package | Requires a server? | Multi-region | HA | Rotation | Storage | AWS KMS | Principals | Web UI | |:----------------------------------------------------|:-------------------|:-------------|:----|:---------|:---------|:---------|:-----------|:-------| | Biscuit | No | Yes | Yes | No | File | Required | AWS Only | No | | Credstash | No | No | Yes | No | DynamoDB | Required | AWS Only | No | | Lyft Confidant | Yes | No | No | No | DynamoDB | Required | AWS Only | Yes | | Hashicorp Vault | Yes | Yes | Yes | Yes | Varied | Optional | Multiple | No |

Quick Start

Installing

Downloading

See releases for the latest release.

Building from Source

If you have Golang 1.16+ installed, you can install with:

go get -v github.com/dcoker/biscuit

Setup

# Verify that your AWS credentials are readable.
biscuit kms get-caller-identity

# Provision a KMS Key w/useful defaults in us-east-1, us-west-1, 
# and us-west-2 and create a secrets.yml file.
biscuit kms init -f secrets.yml

# Store the launch codes.
biscuit put -f secrets.yml -- launch_codes 0000

# Decrypt the launch codes.
biscuit get -f secrets.yml launch_codes

Next steps: examine secrets.yml in your favorite text editor, and run biscuit --help to learn about additional commands.

Uninstalling

Done already?

The biscuit kms init step above may have created a KMS Key and some associated policies using CloudFormation. You can remove those by running:

biscuit kms deprovision
rm secrets.yml

Note: any biscuit files you created before deprovisioning will no longer be readable.

Glossary

The secret is the plaintext value which you wish to protect.

A label is a short alphanumeric string that identifies a set of keys across multiple AWS regions. It is present in CloudFormation stack names (biscuit-label) and in KMS key aliases (alias/biscuit-label).

The key manager is responsible for the provisioning of encryption keys. The encryption keys generated by the key manager are used to encrypt the secret. An encrypted version of the encryption key -- decryptable only by KMS -- is stored as the key ciphertext.

Secret values consist of the information necessary for the key manager to provide the plaintext encryption key to decrypt a ciphertext for a named secret. Values consist of a Key ID (a string, meaningful to the key manager), an indicator of which key manager is in use (string), an algorithm (string), the key ciphertext (the encrypted key, base64), and the ciphertext (base 64). Here is an example of a value named api_key:

api_key:
- key_id: arn:aws:kms:us-west-1:123456789012:key/37793df5-ad32-4d06-b19f-bfb95cee4a35
  key_manager: kms
  algorithm: secretbox
  key_ciphertext: CiA3edlKfUWXVgiDDuzbz95S/pkM8grwRsYkjRoURv0LGhKnAQEBAQB4N3nZSn1Fl1YIgw7s28/eUv6ZDPIK8EbGJI0aFEb9CxoAAAB+MHwGCSqGSIb3DQEHBqBvMG0CAQAwaAYJKoZIhvcNAQcBMB4GCWCGSAFlAwQBLjARBAw4OEtFZrisfC3xJHACARCAO+HJpH4bWD/MF9BYjBvl5ztcezTNxo5SPeAOKJ3Z8Pff2vh1uCZhEEjxnF7t1tqTma8oeESuu2vpPiZp
  ciphertext: YsI/4Qnzpu+Vm+JP4LhnO8Y3dSoz61/vKHBXGVI1pVAUCjMhvjb9ohcdjA==

Names identify a value. When using AWS KMS, names are encoded into the encryption context and must be provided by the process that decrypts the value.

A key template is a special entry in the .yml file which tells the biscuit tool how to handle values that are added to that file. This is an example template:

_keys:
- key_id: arn:aws:kms:us-west-1:123456789012:key/37793df5-ad32-4d06-b19f-bfb95cee4a35
  key_manager: kms
  algorithm: secretbox
- key_id: arn:aws:kms:us-west-2:123456789012:key/c0045b15-9880-4b17-84da-a35760e8a16f
  key_manager: kms
  algorithm: secretbox
- key_id: arn:aws:kms:us-east-1:123456789012:key/d1c5a8e3-adfb-4f79-af0b-cde9f1a31292
  key_manager: kms
  algorithm: secretbox

IAQ

How much does this cost?

Biscuit requires one key in each region you wish to use. Most users can expect to pay ~$1/mo per region per label, and additional usage charges for heavy users. See AWS Key Management Service Pricing for pricing.

Can I use it in a single AWS region?

Yes. Use the -r flag or the BISCUIT_REGIONS environment variable to specify the region.

Example:

biscuit kms init -r us-west-2 -f secrets.yml

What do I do with the .yml file after it is created?

The .yml file is safe for committing to version control, your CI system, embedding in native binaries, copying to S3, publishing in a newspaper, etc. You can deploy these to your production servers by whatever mechanism is most appropriate for your environment, but by far the easiest way to start is to simply include it in your deployments in the same way you would a configuration file.

Once I've created a value, how do I let AWS resources decrypt it?

You can use KMS Grants, KMS Key Policies, or IAM Policies to manage access to the secrets.

KMS Grants

KMS Grants enable you to delegate access to specific KMS operations to some AWS principal. Often your AWS resources will be running with an IAM Role, and thus often the easiest thing to do is to use KMS Grants to allow your IAM Roles to decrypt the appropriate values.

Biscuit will create and retire those grants for you.

Here's how to grant role/webserver and user/gordon the ability to decrypt the launch codes:

biscuit kms grants create --grantee-principal role/webserver -f secrets.yml launch_codes
biscuit kms grants create --grantee-principal user/gordon -f secrets.yml launch_codes
biscuit kms grants list -f secrets.yml launch_codes

If you wish to allow a principal to decrypt all values encrypted under the same set of keys as the launch codes, you can pass the --all-names flag:

biscuit kms grants create -g role/webserver -f secrets.yml --all-names launch_codes

You can also retire grants when they are no longer useful:

biscuit kms grants list -f secrets.yml launch_codes
biscuit kms grants retire -f secrets.yml --grant-name biscuit-ff8102edc8 launch_codes

Biscuit manages grants using the KMS CreateGrant, ListGrants, and RetireGrant APIs.

KMS Key Policies

KMS Keys have their own policies. See Key Policies for more details. If you have just a few users, this is possibly the easiest mechanism to use to control access. You can run biscuit kms edit-key-policy to edit the policy document across all of your regions at once.

Biscuit manages Key Policies using the KMS GetKeyPolicy and SetKeyPolicy APIs.

IAM Policies

IAM Policies are attached to a myriad of AWS entities, and they can also be used to enable access to KMS operations. See Key Policies for more details.

Example: You have a server running with a static AWS access key and secret key. You can give that server the ability to decrypt all values encrypted under a set of keys by attaching a standard user policy, specifying kms:Decrypt as the Action and the full key ARNs in the Resource field.

Note: IAM Policies are global entities, whereas KMS Keys are unique per region. Thus if you have a 3-region configuration, any IAM Policies that explicitly grant access to KMS Keys will need to list all 3 region-specific key ARNs.

Biscuit does not manage IAM Policies for you.

If you wish to disallow IAM Policies from controlling access to your keys, you can do so by passing --disable-iam-policies to kms init. When IAM Policies are disabled, the only way to control access to keys is via Grants and KMS Key Policies. For more information on how this works, see the CloudFormation template in the source repository and the Key Policies doc linked above.

How do I control which AWS region is used to decrypt the value