From 5736966f4bcd1c2df8994a89b851f77ee74526a9 Mon Sep 17 00:00:00 2001 From: Katie McLaughlin Date: Tue, 2 Oct 2018 10:58:10 +1000 Subject: [PATCH] Update RST Syntax * inline code - double ticks * bash examples - use `..code` blocks, prepend commands with `$` * correct some linking Most corrections markdown -> rst --- README.rst | 247 ++++++++++++++++++++++++++++------------------------- 1 file changed, 131 insertions(+), 116 deletions(-) diff --git a/README.rst b/README.rst index 7eecc5502..3d5f0fc87 100644 --- a/README.rst +++ b/README.rst @@ -45,10 +45,13 @@ Or whatever variation of the above fits your system and shell. To use **sops** as a library, take a look at the `decrypt package `_. -**Questions?** ping "ulfr" in `#security` on `irc.mozilla.org `_ +**Questions?** ping "ulfr" in ``#security`` on `irc.mozilla.org `_ (use a web client like `mibbit `_ ). -**What happened to Python Sops?** We rewrote Sops in Go to solve a number of deployment issues, but the Python branch still exists under `python-sops`. We will keep maintaining it for a while, and you can still `pip install sops`, but we strongly recommend you use the Go version instead. +**What happened to Python Sops?** We rewrote Sops in Go to solve a number of +deployment issues, but the Python branch still exists under ``python-sops``. We +will keep maintaining it for a while, and you can still ``pip install sops``, +but we strongly recommend you use the Go version instead. .. sectnum:: .. contents:: Table of Contents @@ -64,7 +67,7 @@ recommended to use at least two master keys in different regions. export SOPS_KMS_ARN="arn:aws:kms:us-east-1:656532927350:key/920aff2e-c5f1-4040-943a-047fa387b27e,arn:aws:kms:ap-southeast-1:656532927350:key/9006a8aa-0fa6-4c14-930e-a2dfb916de1d" -Your AWS credentials must be present in `~/.aws/credentials`. sops uses aws-sdk-go. +Your AWS credentials must be present in ``~/.aws/credentials``. sops uses aws-sdk-go. .. code:: @@ -82,7 +85,7 @@ separated, in the **SOPS_PGP_FP** env variable. Note: you can use both PGP and KMS simultaneously. -Then simply call `sops` with a file path as argument. It will handle the +Then simply call ``sops`` with a file path as argument. It will handle the encryption/decryption transparently and open the cleartext file in an editor .. code:: bash @@ -97,7 +100,7 @@ Editing will happen in whatever $EDITOR is set to, or, if it's not set, in vim. Keep in mind that sops will wait for the editor to exit, and then try to reencrypt the file. Some GUI editors (atom, sublime) spawn a child process and then exit immediately. They usually have an option to wait for the main editor window to be -closed before exiting. See [#127](https://github.com/mozilla/sops/issues/127) for +closed before exiting. See `#127 `_ for more information. The resulting encrypted file looks like this: @@ -137,17 +140,17 @@ 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 your data. -To decrypt a file in a `cat` fashion, use the `-d` flag: +To decrypt a file in a ``cat`` fashion, use the ``-d`` flag: .. code:: bash $ sops -d mynewtestfile.yaml -`sops` encrypted files contain the necessary information to decrypt their content. -All a user of `sops` needs is valid AWS credentials and the necessary +``sops`` encrypted files contain the necessary information to decrypt their content. +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 needs is: +Given that, the only command a ``sops`` user needs is: .. code:: bash @@ -168,7 +171,7 @@ the example files and pgp key provided with the repository:: $ gpg --import pgp/sops_functional_tests_key.asc $ sops example.yaml -This last step will decrypt `example.yaml` using the test private key. +This last step will decrypt ``example.yaml`` using the test private key. Encrypting using GCP KMS @@ -270,21 +273,21 @@ And decrypt it using:: Adding and removing keys ~~~~~~~~~~~~~~~~~~~~~~~~ -When creating new files, `sops` uses the PGP, KMS and GCP KMS defined in the -command line arguments `--kms`, `--pgp`, `--gcp-kms` or `--azure-kv`, or from -the environment variables `SOPS_KMS_ARN`, `SOPS_PGP_FP`, `SOPS_GCP_KMS_IDS`, -`SOPS_AZURE_KEYVAULT_URL`. That information is stored in the file under the -`sops` section, such that decrypting files does not require providing those +When creating new files, ``sops`` uses the PGP, KMS and GCP KMS defined in the +command line arguments ``--kms``, ``--pgp``, ``--gcp-kms`` or ``--azure-kv``, or from +the environment variables ``SOPS_KMS_ARN``, ``SOPS_PGP_FP``, ``SOPS_GCP_KMS_IDS``, +``SOPS_AZURE_KEYVAULT_URL``. That information is stored in the file under the +``sops`` section, such that decrypting files does not require providing those parameters again. -Master PGP and KMS keys can be added and removed from a `sops` file in one of +Master PGP and KMS keys can be added and removed from a ``sops`` file in one of two ways: by using command line flag, or by editing the file directly. -Command line flag `--add-kms`, `--add-pgp`, `--add-gcp-kms`, `--add-azure-kv`, -`--rm-kms`, `--rm-pgp`, `--rm-gcp-kms` and `--rm-azure-kv` can be used to add +Command line flag ``--add-kms``, ``--add-pgp``, ``--add-gcp-kms``, ``--add-azure-kv``, +``--rm-kms``, ``--rm-pgp``, ``--rm-gcp-kms`` and ``--rm-azure-kv`` can be used to add and remove keys from a file. -These flags use the comma separated syntax as the `--kms`, `--pgp`, `--gcp-kms` -and `--azure-kv` arguments when creating new files. +These flags use the comma separated syntax as the ``--kms``, ``--pgp``, ``--gcp-kms`` +and ``--azure-kv`` arguments when creating new files. .. code:: bash @@ -294,10 +297,10 @@ and `--azure-kv` arguments when creating new files. # remove a pgp key from the file and rotate the data key $ sops -r -i --rm-pgp 85D77543B3D624B63CEA9E6DBC17301B491B3F21 example.yaml -Alternatively, invoking `sops` with the flag **-s** will display the master keys +Alternatively, invoking ``sops`` with the flag **-s** will display the master keys while editing. This method can be used to add or remove kms or pgp keys under the -sops section. Invoking `sops` with the **-i** flag will perform an in-place edit -instead of redirecting output to `stdout`. +sops section. Invoking ``sops`` with the **-i** flag will perform an in-place edit +instead of redirecting output to ``stdout``. For example, to add a KMS master key to a file, add the following entry while editing: @@ -316,11 +319,11 @@ And, similarly, to add a PGP master key, we add its fingerprint: pgp: - fp: 85D77543B3D624B63CEA9E6DBC17301B491B3F21 -When the file is saved, `sops` will update its metadata and encrypt the data key +When the file is saved, ``sops`` will update its metadata and encrypt the data key with the freshly added master keys. The removed entries are simply deleted from the file. -When removing keys, it is recommended to rotate the data key using `-r`, +When removing keys, it is recommended to rotate the data key using ``-r``, otherwise owners of the removed key may have add access to the data key in the past. @@ -341,7 +344,7 @@ the user is allowed to assume in each account. The `IAM roles `_ documentation has full details on how this needs to be configured on AWS's side. -From the point of view of `sops`, you only need to specify the role a KMS key +From the point of view of ``sops``, you only need to specify the role a KMS key must assume alongside its ARN, as follows: .. code:: yaml @@ -374,7 +377,7 @@ policy is shown below. } } -You can specify a role in the `--kms` flag and `SOPS_KMS_ARN` variable by +You can specify a role in the ``--kms`` flag and ``SOPS_KMS_ARN`` variable by appending it to the ARN of the master key, separated by a **+** sign:: + @@ -383,21 +386,21 @@ appending it to the ARN of the master key, separated by a **+** sign:: AWS KMS Encryption Context ~~~~~~~~~~~~~~~~~~~~~~~~~~ -SOPS has the ability to use AWS KMS key policy and encryption context - +SOPS has the ability to use `AWS KMS key policy and encryption context +`_ to refine the access control of a given KMS master key. When creating a new file, you can specify encryption context in the -`--encryption-context` flag by comma separated list of key-value pairs: +``--encryption-context`` flag by comma separated list of key-value pairs: When creating a new file, you can specify encryption context in the -`--encryption-context` flag by comma separated list of key-value pairs: +``--encryption-context`` flag by comma separated list of key-value pairs: .. code:: bash $ sops --encryption-context Environment:production,Role:web-server test.dev.yaml -The format of the Encrypt Context string is `:,:,...` +The format of the Encrypt Context string is ``:,:,...`` The encryption context will be stored in the file metadata and does not need to be provided at decryption. @@ -425,8 +428,8 @@ roles that can only access a given context. An example policy is shown below: Key Rotation ~~~~~~~~~~~~ -It is recommended to renew the data key on a regular basis. `sops` supports key -rotation via the `-r` flag. Invoking it on an existing file causes sops to +It is recommended to renew the data key on a regular basis. ``sops`` supports key +rotation via the ``-r`` flag. Invoking it on an existing file causes sops to reencrypt the file with a new data key, which is then encrypted with the various KMS and PGP master keys defined in the file. @@ -437,9 +440,9 @@ KMS and PGP master keys defined in the file. Using .sops.yaml conf to select KMS/PGP for new files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -It is often tedious to specify the `--kms` `--gcp-kms` and `--pgp` parameters for creation +It is often tedious to specify the ``--kms`` ``--gcp-kms`` and ``--pgp`` parameters for creation of all new files. If your secrets are stored under a specific directory, like a -`git` repository, you can create a `.sops.yaml` configuration file at the root +``git`` repository, you can create a ``.sops.yaml`` configuration file at the root directory to define which keys are used for which filename. Let's take an example: @@ -478,7 +481,7 @@ can manage the three sets of configurations for the three types of files: pgp: '1022470DE3F0BC54BC6AB62DE05550BC07FB1A0A' When creating any file under **mysecretrepo**, whether at the root or under -a subdirectory, sops will recursively look for a `.sops.yaml` file. If one is +a subdirectory, sops will recursively look for a ``.sops.yaml`` file. If one is found, the filename of the file being created is compared with the filename regexes of the configuration file. The first regex that matches is selected, and its KMS and PGP keys are used to encrypt the file. @@ -495,11 +498,11 @@ passed on the sops command line or in environment variables. Specify a different GPG executable ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -`sops` checks for the `SOPS_GPG_EXEC` environment variable. If specified, +``sops`` checks for the ``SOPS_GPG_EXEC`` environment variable. If specified, it will attempt to use the executable set there instead of the default -of `gpg`. +of ``gpg``. -Example: place the following in your `~/.bashrc` +Example: place the following in your ``~/.bashrc`` .. code:: bash @@ -508,19 +511,19 @@ Example: place the following in your `~/.bashrc` Key groups ~~~~~~~~~~ -By default, `sops` encrypts the data key for a file with each of the master keys, +By default, ``sops`` encrypts the data key for a file with each of the master keys, 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, data keys are split into parts such that keys from -multiple groups are required to decrypt a file. `sops` uses Shamir's Secret Sharing +multiple groups are required to decrypt a file. ``sops`` uses Shamir's Secret Sharing 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 key groups in order, and in +file using multiple key groups, ``sops`` goes through key groups in order, and in each group, tries to recover the fragment of the data key using a master key from -that group. Once the fragment is recovered, `sops` moves on to the next group, +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 @@ -528,19 +531,23 @@ 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. -Management of key groups is done with the `sops groups` command. +Management of key groups is done with the ``sops groups`` command. For example, you can add a new key group with 3 PGP keys and 3 KMS keys to the -file `my_file.yaml`: +file ``my_file.yaml``: -`sops groups add --file my_file.yaml --pgp fingerprint1 --pgp fingerprint2 --pgp fingerprint3 --kms arn1 --kms arn2 --kms arn3` +.. code:: bash + + $ sops groups add --file my_file.yaml --pgp fingerprint1 --pgp fingerprint2 --pgp fingerprint3 --kms arn1 --kms arn2 --kms arn3 Or you can delete the 1st group (group number 0, as groups are zero-indexed) -from `my_file.yaml`: +from ``my_file.yaml``: -`sops groups delete --file my_file.yaml 0` +.. code:: bash -Key groups can also be specified in the `.sops.yaml` config file, + $ sops groups delete --file my_file.yaml 0 + +Key groups can also be specified in the ``.sops.yaml`` config file, like so: .. code:: yaml @@ -570,19 +577,19 @@ like so: - fingerprint5 Given this configuration, we can create a new encrypted file like we normally -would, and optionally provide the `--shamir-secret-sharing-threshold` command line -flag if we want to override the default threshold. `sops` will then split the data +would, and optionally provide the ``--shamir-secret-sharing-threshold`` command line +flag if we want to override the default threshold. ``sops`` will then split the data key into three parts (from the number of key groups) and encrypt each fragment with the master keys found in each group. For example: -.. code:: yaml +.. code:: bash - sops --shamir-secret-sharing-threshold 2 example.json + $ sops --shamir-secret-sharing-threshold 2 example.json -Alternatively, you can configure the Shamir threshold for each creation rule in the `.sops.yaml` config -with `shamir_threshold`: +Alternatively, you can configure the Shamir threshold for each creation rule in the ``.sops.yaml`` config +with ``shamir_threshold``: .. code:: yaml @@ -611,22 +618,22 @@ with `shamir_threshold`: - pgp: - fingerprint5 -And then run `sops example.json`. +And then run ``sops example.json``. -The threshold (`shamir_threshold`) is set to 2, so this configuration will require +The threshold (``shamir_threshold``) is set to 2, so this configuration will require master keys from two of the three different key groups in order to decrypt the file. You can then decrypt the file the same way as with any other SOPS file: -.. code:: yaml +.. code:: bash - sops -d example.json + $ sops -d example.json Key service ~~~~~~~~~~~ -There are situations where you might want to run `sops` on a machine that -doesn't have direct access to encryption keys such as PGP keys. The `sops` key -service allows you to forward a socket so that `sops` can access encryption +There are situations where you might want to run ``sops`` on a machine that +doesn't have direct access to encryption keys such as PGP keys. The ``sops`` key +service allows you to forward a socket so that ``sops`` can access encryption keys stored on a remote machine. This is similar to GPG Agent, but more portable. @@ -647,22 +654,26 @@ Whenever we try to encrypt or decrypt a data key, SOPS will try to do so first with the local key service (unless it's disabled), and if that fails, it will try all other remote key services until one succeeds. -You can start a key service server by running `sops keyservice`. +You can start a key service server by running ``sops keyservice``. -You can specify the key services the `sops` binary uses with `--keyservice`. +You can specify the key services the ``sops`` binary uses with ``--keyservice``. This flag can be specified more than once, so you can use multiple key services. The local key service can be disabled with -`enable-local-keyservice=false`. +``enable-local-keyservice=false``. For example, to decrypt a file using both the local key service and the key -service exposed on the unix socket located in `/tmp/sops.sock`, you can run: +service exposed on the unix socket located in ``/tmp/sops.sock``, you can run: -`sops --keyservice unix:///tmp/sops.sock -d file.yaml` +.. code:: bash + + $ sops --keyservice unix:///tmp/sops.sock -d file.yaml` And if you only want to use the key service exposed on the unix socket located -in `/tmp/sops.sock` and not the local key service, you can run: +in ``/tmp/sops.sock`` and not the local key service, you can run: -`sops --enable-local-keyservice=false --keyservice unix:///tmp/sops.sock -d file.yaml` +.. code:: bash + + $ sops --enable-local-keyservice=false --keyservice unix:///tmp/sops.sock -d file.yaml Auditing ~~~~~~~~ @@ -675,20 +686,20 @@ includes a timestamp, the username SOPS is running as, and the file that was decrypted. In order to enable auditing, you must first create the database and credentials -using the schema found in :code:`audit/schema.sql`. This schema defines the -tables that store the audit events and a role named :code:`sops` that only has +using the schema found in ``audit/schema.sql``. This schema defines the +tables that store the audit events and a role named ``sops`` that only has permission to add entries to the audit event tables. The default password for -the role :code:`sops` is :code:`sops`. You should change this password. +the role ``sops`` is ``sops``. You should change this password. Once you have created the database, you have to tell SOPS how to connect to it. Because we don't want users of SOPS to be able to control auditing, the audit configuration file location is not configurable, and must be at -:code:`/etc/sops/audit.yaml`. This file should have strict permissions such +``/etc/sops/audit.yaml``. This file should have strict permissions such that only the root user can modify it. -For example, to enable auditing to a PostgreSQL database named :code:`sops` -running on localhost, using the user :code:`sops` and the password :code:`sops`, -:code:`/etc/sops/audit.yaml` should have the following contents: +For example, to enable auditing to a PostgreSQL database named ``sops`` running +on localhost, using the user ``sops`` and the password ``sops``, +``/etc/sops/audit.yaml`` should have the following contents: .. code:: yaml @@ -697,10 +708,10 @@ running on localhost, using the user :code:`sops` and the password :code:`sops`, - connection_string: "postgres://sops:sops@localhost/sops?sslmode=verify-full" -You can find more information on the :code:`connection_string` format in the +You can find more information on the ``connection_string`` format in the `PostgreSQL docs `_. -Under the :code:`postgres` map entry in the above YAML is a list, so one can +Under the ``postgres`` map entry in the above YAML is a list, so one can provide more than one backend, and SOPS will log to all of them: .. code:: yaml @@ -717,21 +728,24 @@ Important information on types YAML and JSON type extensions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -`sops` uses the file extension to decide which encryption method to use on the file -content. `YAML` and `JSON` files are treated as trees of data, and key/values are +``sops`` uses the file extension to decide which encryption method to use on the file +content. ``YAML`` and ``JSON`` files are treated as trees of data, and key/values are extracted from the files to only encrypt the leaf values. The tree structure is also used to check the integrity of the file. Therefore, if a file is encrypted using a specific format, it need to be decrypted in the same format. The easiest way to achieve this is to conserve the original file -extension after encrypting a file. For example:: +extension after encrypting a file. For example: + +.. code:: bash $ sops -e -i myfile.json - $ sops -d myfile.json If you want to change the extension of the file once encrypted, you need to provide -sops with the `--input-type` flag upon decryption. For example:: +sops with the ``--input-type`` flag upon decryption. For example: + +.. code:: bash $ sops -e myfile.json > myfile.json.enc @@ -739,11 +753,11 @@ sops with the `--input-type` flag upon decryption. For example:: YAML anchors ~~~~~~~~~~~~ -`sops` only supports a subset of `YAML`'s many types. Encrypting YAML files that +``sops`` only supports a subset of ``YAML``'s many types. Encrypting YAML files that contain strings, numbers and booleans will work fine, but files that contain anchors will not work, because the anchors redefine the structure of the file at load time. -This file will not work in `sops`: +This file will not work in ``sops``: .. code:: yaml @@ -756,7 +770,7 @@ This file will not work in `sops`: ship-to: *id001 -`sops` uses the path to a value as additional data in the AEAD encryption, and thus +``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. JSON and TEXT file types do not support anchors and thus have no such limitation. @@ -764,8 +778,8 @@ JSON and TEXT file types do not support anchors and thus have no such limitation YAML Streams ~~~~~~~~~~~~ -`YAML` supports having more than one document in a single file. `sops` does not. For this -reason, the following file won't work in `sops`: +``YAML`` supports having more than one document in a single file. ``sops`` does not. For this +reason, the following file won't work in ``sops``: .. code:: yaml @@ -774,14 +788,15 @@ reason, the following file won't work in `sops`: --- data: bar -If you try to encrypt this file with `sops`, it will ignore all documents except the first, -effectively deleting them. `sops` does not support multi-document files, and until our YAML +If you try to encrypt this file with ``sops``, it will ignore all documents except the first, +effectively deleting them. ``sops`` does not support multi-document files, and until our YAML parser does, it is unlikely it will. Top-level arrays ~~~~~~~~~~~~~~~~ -`YAML` and `JSON` top-level arrays are not supported, because `sops` needs a top-level -`sops` key to store its metadata. +``YAML`` and ``JSON`` top-level arrays are not supported, because ``sops`` +needs a top-level ``sops`` key to store its metadata. + This file will not work in sops: .. code:: yaml @@ -791,8 +806,8 @@ This file will not work in sops: - array - elements -But this one will because because the `sops` key can be added at the same level as the -`data` key. +But this one will because because the ``sops`` key can be added at the same level as the +``data`` key. .. code:: yaml @@ -801,7 +816,7 @@ But this one will because because the `sops` key can be added at the same level - array - elements -Similarly, with `JSON` arrays, this document will not work: +Similarly, with ``JSON`` arrays, this document will not work: .. code:: json @@ -843,7 +858,7 @@ Encrypting an existing file ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Similar to the previous command, we tell sops to use one KMS and one PGP key. -The path points to an existing cleartext file, so we give sops flag `-e` to +The path points to an existing cleartext file, so we give sops flag ``-e`` to encrypt the file, and redirect the output to a destination file. .. code:: bash @@ -852,7 +867,7 @@ encrypt the file, and redirect the output to a destination file. $ export SOPS_PGP_FP="C9CAB0AF1165060DB58D6D6B2653B624D620786D" $ sops -e /path/to/existing/file.yaml > /path/to/new/encrypted/file.yaml -Decrypt the file with `-d`. +Decrypt the file with ``-d``. .. code:: bash @@ -861,7 +876,7 @@ Decrypt the file with `-d`. Encrypt or decrypt a file in place ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Rather than redirecting the output of `-e` or `-d`, sops can replace the +Rather than redirecting the output of ``-e`` or ``-d``, sops can replace the original file after encrypting or decrypting it. .. code:: bash @@ -875,10 +890,10 @@ original file after encrypting or decrypting it. Encrypting binary files ~~~~~~~~~~~~~~~~~~~~~~~ -`sops` primary use case is encrypting YAML and JSON configuration files, but it +``sops`` primary use case is encrypting YAML and JSON configuration files, but it also has the ability to manage binary files. When encrypting a binary, sops will read the data as bytes, encrypt it, store the encrypted base64 under -`tree['data']` and write the result as JSON. +``tree['data']`` and write the result as JSON. Note that the base64 encoding of encrypted data can actually make the encrypted file larger than the cleartext one. @@ -907,8 +922,8 @@ In-place encryption/decryption also works on binary files. 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 +``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 needing an extra parser. .. code:: bash @@ -936,8 +951,8 @@ them. Set a sub-part in a document tree ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -`sops` can set a specific part of a YAML or JSON document, by providing -the path and value in the `--set` command line flag. This is useful to +``sops`` can set a specific part of a YAML or JSON document, by providing +the path and value in the ``--set`` command line flag. This is useful to set specific values, like keys, without needing an editor. .. code:: bash @@ -980,14 +995,14 @@ You most likely want to store encrypted files in a version controlled 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 +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. ... code:: *.yaml diff=sopsdiffer -Here we only care about YAML files. `sopsdiffer` is an arbitrary name that we map +Here we only care about YAML files. ``sopsdiffer`` is an arbitrary name that we map to a sops command in the git configuration file of the repository. .. code:: bash @@ -998,7 +1013,7 @@ to a sops command in the git configuration file of the repository. [diff "sopsdiffer"] textconv = "sops -d" -With this in place, calls to `git diff` will decrypt both previous and current +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! @@ -1007,7 +1022,7 @@ Encrypting only parts of a file Note: this only works on YAML and JSON files, not on BINARY files. -By default, `sops` encrypts all the values of a YAML or JSON file and leaves the +By default, ``sops`` encrypts all the values of a YAML or JSON file and leaves the keys in cleartext. In some instances, you may want to exclude some values from being encrypted. This can be accomplished by adding the suffix **_unencrypted** to any key of a file. When set, all values underneath the key that set the @@ -1018,14 +1033,14 @@ checksum of the file, and thus cannot be modified outside of sops without breaking the file integrity check. The unencrypted suffix can be set to a different value using the -`--unencrypted-suffix` option. +``--unencrypted-suffix`` option. Conversely, you can opt in to only encrypt some values in a YAML or JSON file, -by adding a chosen suffix to those keys and passing it to the `--encrypted-suffix` option. +by adding a chosen suffix to those keys and passing it to the ``--encrypted-suffix`` option. -You can also specify these options in the `.sops.yaml` config file. +You can also specify these options in the ``.sops.yaml`` config file. -Note: these two options `--unencrypted-suffix` and `--encrypted-suffix` are mutually exclusive and +Note: these two options ``--unencrypted-suffix`` and ``--encrypted-suffix`` are mutually exclusive and cannot both be used in the same file. Encryption Protocol @@ -1033,7 +1048,7 @@ Encryption Protocol 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`. +key is stored in the ``sops`` metadata under ``sops.kms`` and ``sops.pgp``. For KMS: @@ -1259,7 +1274,7 @@ today, we recommend that users keep their encrypted files reasonably private. Backward compatibility ---------------------- -`sops` will remain backward compatible on the major version, meaning that all +``sops`` will remain backward compatible on the major version, meaning that all improvements brought to the 1.X and 2.X branches (current) will maintain the file format introduced in **1.0**. @@ -1267,7 +1282,7 @@ Security -------- Please report security issues to jvehent at mozilla dot com, or by using one -of the contact method available on keybase: https://keybase.io/jvehent +of the contact method available on keybase: `https://keybase.io/jvehent `_ License -------