From 2ccd06317fdf83af368e8238f580e319368cafe0 Mon Sep 17 00:00:00 2001 From: Adrian Utrilla Date: Thu, 18 Jul 2019 19:35:07 +0200 Subject: [PATCH] docs: document git differ, key groups, and key rotation --- docs/_sidebar.md | 4 -- docs/usage/git_differ.md | 24 +++++++++++ docs/usage/key_groups.md | 81 ++++++++++++++++++++++++++++++++++++++ docs/usage/key_rotation.md | 11 ++++++ 4 files changed, 116 insertions(+), 4 deletions(-) create mode 100644 docs/usage/git_differ.md create mode 100644 docs/usage/key_groups.md create mode 100644 docs/usage/key_rotation.md diff --git a/docs/_sidebar.md b/docs/_sidebar.md index b0647efa0..1a32ec836 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -26,10 +26,6 @@ * [.env](storage_formats/dotenv.md) * [INI](storage_formats/ini.md) * [Arbitrary (binary) files](storage_formats/binary.md) -* Publication targets - * [AWS S3](publication_targets/s3.md) - * [Google Cloud Storage](publication_targets/gcs.md) - * [Hashicorp Vault](publication_targets/vault.md) * Internals * [Encryption protocol](internals/encryption_protocol.md) * [Comparison with other tools](comparison_with_other_tools.md) diff --git a/docs/usage/git_differ.md b/docs/usage/git_differ.md new file mode 100644 index 000000000..d941e8324 --- /dev/null +++ b/docs/usage/git_differ.md @@ -0,0 +1,24 @@ +# `sops` as a git differ + +You most likely want to store your encrypted files in a version control +repository. `sops` can be used with git to decrypt files when showing diffs +between versions. This is very handy for reviewing changes or visualizing +history. + +To configure sops to decrypt files during diff, create a `.gitattributes` file +at the root of your repository that contains a filter and a command: + +``` +*.yaml diff=sopsdiffer +``` + +Here we only care about YAML files. ``sopsdiffer`` is an arbitrary name that we +then map to a `sops` command in the git configuration file of the repository. + +```bash +$ git config diff.sopsdiffer.textconv "sops -d" +``` + +With this in place, calls to ``git diff`` will decrypt both previous and +current versions of the target file prior to displaying the diff. And it even +works with git client interfaces, because they call git diff under the hood! diff --git a/docs/usage/key_groups.md b/docs/usage/key_groups.md new file mode 100644 index 000000000..292a340fc --- /dev/null +++ b/docs/usage/key_groups.md @@ -0,0 +1,81 @@ +# Key groups + +By default, `sops` encrypts its [data key](internals/encryption_protocol.md) +with each of the [master keys](encryption_providers/README.md), such that if +any of the master keys is available, the file can be decrypted. However, it is +sometimes desirable to require access to multiple master keys in order to +decrypt files. This can be achieved with key groups. + +When using key groups in sops, the data key is split into fragments such that +master keys from multiple groups are required to decrypt a file. `sops` uses +[Shamir's Secret Sharing](TODO) to split the data key such that each key group +has a fragment, each key in the key group can decrypt that fragment, and a +configurable number of fragments (threshold) are needed to decrypt and piece +together the complete data key. When decrypting a file using multiple key +groups, `sops` goes through the key groups in order, and for each group, tries +to recover its corresponding fragment of the data key using a master key from +that group. Once the fragment is recovered, `sops` moves on to the next group, +until enough fragments have been recovered to obtain the complete data key. + +By default, the threshold is set to the number of key groups. For example, if +you have three key groups configured in your SOPS file and you don't override +the default threshold, then one master key from each of the three groups will +be required to decrypt the file. + +## The `sops groups` subcommand + +Management of key groups is performed through the `sops groups` subcommand. + +### Adding a key group to a file + +You can add groups to a file through the `sops groups add` command. For example, to add a new key group to an existing file with 3 PGP keys and 3 AWS KMS keys, one could do as follows: + +```bash +$ sops groups add --file my_file.enc --pgp fingerprint1 --pgp fingerprint2 --pgp fingerprint3 --kms arn1 --kms arn2 --kms arn3 +``` + +### Deleting key groups from a file + +Similarly, key groups can be deleted from encrypted files by their index with +the `sops groups delete` command. For example, to delete the first key group +(group number 0, as groups are zero-indexed) in a file: + +```bash +$ sops groups delete --file my_file.enc 0 +``` + +?> Currently, you can see the order of the key groups in a file by inspecting +the encrypted file directly without using `sops` (i.e., with `cat`, `less` or +your favorite editor) + +## `.sops.yaml` + +The [`.sops.yaml` configuration file](sops_yaml_config_file.md) also contains options related to +key groups, and as such it can be used as an alternative to the `sops groups` +subcommand. + +When creating a new file using the rules on `.sops.yaml`, the Shamir threshold +can also be specified through the `--shamir-secret-sharing-threshold` flag. + +## The `sops updatekeys` subcommand + +In some cases, it might be more convenient to use rules like those in +`.sops.yaml` to manage key groups. However, these only apply to new files. The +`sops updatekeys` subcommand updates the key groups in existing files based on +the matching rules in the `.sops.yaml` configuration file. Essentially, this +updates the key groups in the file such that they end up as if the file was +newly created. + +```bash +$ sops updatekeys example.yaml +2019/07/18 16:03:43 Syncing keys for file example.yaml +The following changes will be made to the file's groups: +Group 1 + 1022470DE3F0BC54BC6AB62DE05550BC07FB1A0A +--- 85D77543B3D624B63CEA9E6DBC17301B491B3F21 +Is this okay? (y/n):y +2019/07/18 16:03:53 File example.yaml synced with new keys +``` + +This can be more convenient than the `sops groups` subcommand when, for +example, we want to delete a single key from a key group. diff --git a/docs/usage/key_rotation.md b/docs/usage/key_rotation.md new file mode 100644 index 000000000..362fc6046 --- /dev/null +++ b/docs/usage/key_rotation.md @@ -0,0 +1,11 @@ +# Key rotation + +It is considered group practice to rotate cryptographic keys every once in a +while. `sops` supports rotation of its data key: + +```bash +$ sops --rotate my_file.enc +``` + +!> Rotating the data key requires encryption access to all master keys used in +a file