diff --git a/README.rst b/README.rst index 91b49d792..480ddd51f 100644 --- a/README.rst +++ b/README.rst @@ -131,7 +131,7 @@ The resulting encrypted file looks like this: A copy of the encryption/decryption key is stored securely in each KMS and PGP block. As long as one of the KMS or PGP method is still usable, you will be able -to access you data. +to access your data. To decrypt a file in a `cat` fashion, use the `-d` flag: @@ -140,10 +140,10 @@ To decrypt a file in a `cat` fashion, use the `-d` flag: $ sops -d mynewtestfile.yaml `sops` encrypted files contain the necessary information to decrypt their content. -All a user of `sops` need is valid AWS credentials and the necessary +All a user of `sops` needs is valid AWS credentials and the necessary permissions on KMS keys. -Given that, the only command a `sops` user need is: +Given that, the only command a `sops` user needs is: .. code:: bash @@ -189,7 +189,7 @@ Assuming roles and using KMS in various AWS accounts SOPS has the ability to use KMS in multiple AWS accounts by assuming roles in each account. Being able to assume roles is a nice feature of AWS that allows -administrator to establish trust relationships between accounts, typically from +administrators to establish trust relationships between accounts, typically from the most secure account to the least secure one. In our use-case, we use roles to indicate that a user of the Master AWS account is allowed to make use of KMS master keys in development and staging AWS accounts. Using roles, a single file @@ -243,7 +243,7 @@ appending it to the ARN of the master key, separated by a **+** sign:: Key Rotation ~~~~~~~~~~~~ -It is recommend to renew the data key on a regular basis. `sops` supports key +It is recommended to renew the data key on a regular basis. `sops` supports key rotation via the `-r` flag. A simple approach is to decrypt and reencrypt all files in place with rotation enabled: @@ -260,7 +260,7 @@ Examples Creating a new file ~~~~~~~~~~~~~~~~~~~ -The command below create a new file with a data key encrypted by KMS and PGP. +The command below creates a new file with a data key encrypted by KMS and PGP. .. code:: bash @@ -336,7 +336,7 @@ Extract a sub-part of a document tree `sops` can extract a specific part of a YAML or JSON document, by provided the path in the `--extract` command line flag. This is useful to extract specific -values, like keys, without needed an extra parser. +values, like keys, without needing an extra parser. .. code:: bash @@ -351,7 +351,7 @@ values, like keys, without needed an extra parser. bKGPkMM4w5blyE1tqGN0T7sJwEx+EUOgacRNqM2ljVA= -----END RSA PRIVATE KEY----- -The tree path syntax uses a regular python dictionary syntax, without the +The tree path syntax uses regular python dictionary syntax, without the variable name. Extract keys by naming them, and array elements by numbering them. @@ -401,7 +401,7 @@ to a sops command in the git configuration file of the repository. textconv = "sops -d" With this in place, calls to `git diff` will decrypt both previous and current -version of the target file prior to displaying the diff. And it even works with +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! Implementation details @@ -413,7 +413,7 @@ YAML types limitations `sops` only supports a subset of `YAML`'s many types. Encrypting YAML files that contain strings, numbers and booleans will work fine. -Files that contain anchors will not work, because the anchors redefine that +Files that contain anchors will not work, because the anchors redefine the structure of the file at load time. `sops` uses the path to a value as additional data in the AEAD encryption, and thus dynamic paths generated by anchors break the authentication step. @@ -423,7 +423,7 @@ JSON and TEXT file types have no such feature and do not suffer this limitation. Encryption method ~~~~~~~~~~~~~~~~~ -When sops creates a file, it generates a random 256 bits data key and asks each +When sops creates a file, it generates a random 256 bit data key and asks each KMS and PGP master key to encrypt the data key. The encrypted version of the data key is stored in the `sops` metadata under `sops.kms` and `sops.pgp`. @@ -468,9 +468,9 @@ For PGP: sops then opens a text editor on the newly created file. The user adds data to the file and saves it when done. -Upon save, sops browses the entire file as of a key/value tree. Every time sops +Upon save, sops browses the entire file as a key/value tree. Every time sops encounters a leaf value (a value that does not have children), it encrypts the -value with AES256_GCM using the data key and a 256 bits random initialization +value with AES256_GCM using the data key and a 256 bit random initialization vector. Each file uses a single data key to encrypt all values of a document, but each @@ -479,15 +479,15 @@ value receives a unique initialization vector and has unique authentication data Additional data is used to guarantee the integrity of the encrypted data and of the tree structure: when encrypting the tree, key names are concatenated into a byte string that is used as AEAD additional data (aad) when encrypting -values encrypted. We expect that keys do not carry sensitive information, and +values. We expect that keys do not carry sensitive information, and keeping them in cleartext allows for better diff and overall readability. Any valid KMS or PGP master key can later decrypt the data key and access the data. Multiple master keys allow for sharing encrypted files without sharing master -keys, and provide disaster recovery solution. The recommended way to use sops -is to have two KMS master keys in different region and one PGP public key with +keys, and provide a disaster recovery solution. The recommended way to use sops +is to have two KMS master keys in different regions and one PGP public key with the private key stored offline. If, by any chance, both KMS master keys are lost, you can always recover the encrypted data using the PGP private key. @@ -544,7 +544,7 @@ Operational requirements ~~~~~~~~~~~~~~~~~~~~~~~~ When Mozilla's Services Operations team started revisiting the issue of -distributing secrets to EC2 instances, we set the goal to store these secrets +distributing secrets to EC2 instances, we set a goal to store these secrets encrypted until the very last moment, when they need to be decrypted on target systems. Not unlike many other organizations that operate sufficiently complex automation, we found this to be a hard problem with a number of prerequisites: @@ -571,7 +571,7 @@ manipulated as a tree where keys are stored in cleartext, and values are encrypted. hiera-eyaml does something similar, and over the years we learned to appreciate its benefits, namely: -* diff are meaningful. If a single value of a file is modified, only that +* diffs are meaningful. If a single value of a file is modified, only that value will show up in the diff. The diff is still limited to only showing encrypted data, but that information is already more granular that indicating that an entire file has changed. @@ -586,8 +586,8 @@ OpenPGP integration ~~~~~~~~~~~~~~~~~~~ OpenPGP gets a lot of bad press for being an outdated crypto protocol, and while -true, what really made look for alternatives is the difficulty to manage and -distribute keys to systems. With KMS, we manage permissions to an API, not keys, +true, what really made us look for alternatives is the difficulty of managing and +distributing keys to systems. With KMS, we manage permissions to an API, not keys, and that's a lot easier to do. But PGP is not dead yet, and we still rely on it heavily as a backup solution: @@ -613,13 +613,13 @@ strongest symetric encryption algorithm known today. Data keys are encrypted in either KMS, which also uses AES256_GCM, or PGP which uses either RSA or ECDSA keys. -Going from the most likely to the least likely, the threats are as follow: +Going from the most likely to the least likely, the threats are as follows: Compromised AWS credentials grant access to KMS master key ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ An attacker with access to an AWS console can grant itself access to one of -the KMS master key used to encrypt a sops data key. This threat should be +the KMS master keys used to encrypt a sops data key. This threat should be mitigated by protecting AWS accesses with strong controls, such as multi-factor authentication, and also by performing regular audits of permissions granted to AWS users.