@@ -96,12 +96,12 @@ separated, in the **SOPS_PGP_FP** env variable.
96
96
97
97
Note: you can use both PGP and KMS simultaneously.
98
98
99
- Then simply call ``sops `` with a file path as argument. It will handle the
99
+ Then simply call ``sops edit `` with a file path as argument. It will handle the
100
100
encryption/decryption transparently and open the cleartext file in an editor
101
101
102
102
.. code :: sh
103
103
104
- $ sops mynewtestfile.yaml
104
+ $ sops edit mynewtestfile.yaml
105
105
mynewtestfile.yaml doesn' t exist, creating it.
106
106
please wait while an encryption key is being generated and stored in a secure fashion
107
107
file written to mynewtestfile.yaml
@@ -164,7 +164,7 @@ Given that, the only command a SOPS user needs is:
164
164
165
165
.. code :: sh
166
166
167
- $ sops < file>
167
+ $ sops edit < file>
168
168
169
169
`<file> ` will be opened, decrypted, passed to a text editor (vim by default),
170
170
encrypted if modified, and saved back to its original location. All of these
@@ -179,7 +179,7 @@ the example files and pgp key provided with the repository::
179
179
$ git clone https://github.com/getsops/sops.git
180
180
$ cd sops
181
181
$ gpg --import pgp/sops_functional_tests_key.asc
182
- $ sops example.yaml
182
+ $ sops edit example.yaml
183
183
184
184
This last step will decrypt ``example.yaml `` using the test private key.
185
185
@@ -431,35 +431,33 @@ separated list.
431
431
SOPS will prompt you with the changes to be made. This interactivity can be
432
432
disabled by supplying the ` ` -y` ` flag.
433
433
434
- Command Line
435
- ************
434
+ ` ` rotate ` ` command
435
+ ******************
436
436
437
- Command line flag ` ` --add-kms` ` , ` ` --add-pgp` ` , ` ` --add-gcp-kms` ` , ` ` --add-azure-kv` ` ,
438
- ` ` --rm-kms` ` , ` ` --rm-pgp` ` , ` ` --rm-gcp-kms` ` and ` ` --rm-azure-kv` ` can be used to add
439
- and remove keys from a file.
440
- These flags use the comma separated syntax as the ` ` --kms` ` , ` ` --pgp` ` , ` ` --gcp-kms` `
441
- and ` ` --azure-kv` ` arguments when creating new files.
437
+ The ` ` rotate` ` command generates a new data encryption key and reencrypt all values
438
+ with the new key. At te same time, the command line flag ` ` --add-kms` ` , ` ` --add-pgp` ` ,
439
+ ` ` --add-gcp-kms` ` , ` ` --add-azure-kv` ` , ` ` --rm-kms` ` , ` ` --rm-pgp` ` , ` ` --rm-gcp-kms` `
440
+ and ` ` --rm-azure-kv` ` can be used to add and remove keys from a file. These flags use
441
+ the comma separated syntax as the ` ` --kms` ` , ` ` --pgp` ` , ` ` --gcp-kms` ` and ` ` --azure-kv` `
442
+ arguments when creating new files.
442
443
443
- Note that ` ` -r` ` or ` ` --rotate` ` is mandatory in this mode. Not specifying
444
- rotate will ignore the ` ` --add-*` ` options. Use ` ` updatekeys` ` if you want to
445
- add a key without rotating the data key.
444
+ Use ` ` updatekeys` ` if you want to add a key without rotating the data key.
446
445
447
446
.. code:: sh
448
447
449
448
# add a new pgp key to the file and rotate the data key
450
- $ sops -r -i --add-pgp 85D77543B3D624B63CEA9E6DBC17301B491B3F21 example.yaml
449
+ $ sops rotate -i --add-pgp 85D77543B3D624B63CEA9E6DBC17301B491B3F21 example.yaml
451
450
452
451
# remove a pgp key from the file and rotate the data key
453
- $ sops -r -i --rm-pgp 85D77543B3D624B63CEA9E6DBC17301B491B3F21 example.yaml
452
+ $ sops rotate -i --rm-pgp 85D77543B3D624B63CEA9E6DBC17301B491B3F21 example.yaml
454
453
455
454
456
455
Direct Editing
457
456
**************
458
457
459
- Alternatively, invoking ` ` sops` ` with the flag **-s** will display the master keys
458
+ Alternatively, invoking ` ` sops edit ` ` with the flag **-s** will display the master keys
460
459
while editing. This method can be used to add or remove ` ` kms` ` or ` ` pgp` ` keys under the
461
- ` ` sops` ` section. Invoking ` ` sops` ` with the **-i** flag will perform an in-place edit
462
- instead of redirecting output to ` ` stdout` ` .
460
+ ` ` sops` ` section.
463
461
464
462
For example, to add a KMS master key to a file, add the following entry while
465
463
editing:
@@ -571,7 +569,7 @@ When creating a new file, you can specify the encryption context in the
571
569
572
570
.. code:: sh
573
571
574
- $ sops --encryption-context Environment:production,Role:web-server test.dev.yaml
572
+ $ sops edit --encryption-context Environment:production,Role:web-server test.dev.yaml
575
573
576
574
The format of the Encrypt Context string is ` ` <EncryptionContext Key>:<EncryptionContext Value>,<EncryptionContext Key>:<EncryptionContext Value>,...` `
577
575
@@ -602,13 +600,16 @@ Key Rotation
602
600
~~~~~~~~~~~~
603
601
604
602
It is recommended to renew the data key on a regular basis. ` ` sops` ` supports key
605
- rotation via the ` ` -r ` ` flag . Invoking it on an existing file causes ` ` sops` ` to
606
- reencrypt the file with a new data key, which is then encrypted with the various
603
+ rotation via the ` ` rotate ` ` command . Invoking it on an existing file causes ` ` sops` `
604
+ to reencrypt the file with a new data key, which is then encrypted with the various
607
605
KMS and PGP master keys defined in the file.
608
606
607
+ Add the ` ` -i` ` option to write the rotated file back, instead of printing it to
608
+ stdout.
609
+
609
610
.. code:: sh
610
611
611
- $ sops -r example.yaml
612
+ $ sops rotate example.yaml
612
613
613
614
Using .sops.yaml conf to select KMS, PGP and age for new files
614
615
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -692,7 +693,7 @@ Creating a new file with the right keys is now as simple as
692
693
693
694
.. code:: sh
694
695
695
- $ sops <newfile>.prod.yaml
696
+ $ sops edit <newfile>.prod.yaml
696
697
697
698
Note that the configuration file is ignored when KMS or PGP parameters are
698
699
passed on the SOPS command line or in environment variables.
@@ -798,7 +799,7 @@ For example:
798
799
799
800
.. code:: sh
800
801
801
- $ sops --shamir-secret-sharing-threshold 2 example.json
802
+ $ sops edit --shamir-secret-sharing-threshold 2 example.json
802
803
803
804
Alternatively, you can configure the Shamir threshold for each creation rule in the ` ` .sops.yaml` ` config
804
805
with ` ` shamir_threshold` ` :
@@ -831,7 +832,7 @@ with ``shamir_threshold``:
831
832
- pgp:
832
833
- fingerprint5
833
834
834
- And then run ` ` sops example.json` ` .
835
+ And then run ` ` sops edit example.json` ` .
835
836
836
837
The threshold (` ` shamir_threshold` ` ) is set to 2, so this configuration will require
837
838
master keys from two of the three different key groups in order to decrypt the file.
@@ -1263,7 +1264,7 @@ The command below creates a new file with a data key encrypted by KMS and PGP.
1263
1264
1264
1265
.. code:: sh
1265
1266
1266
- $ sops --kms "arn:aws:kms:us-west-2:927034868273:key/fe86dd69-4132-404c-ab86-4269956b4500" --pgp C9CAB0AF1165060DB58D6D6B2653B624D620786D /path/to/new/file.yaml
1267
+ $ sops edit --kms "arn:aws:kms:us-west-2:927034868273:key/fe86dd69-4132-404c-ab86-4269956b4500" --pgp C9CAB0AF1165060DB58D6D6B2653B624D620786D /path/to/new/file.yaml
1267
1268
1268
1269
Encrypting an existing file
1269
1270
~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1363,26 +1364,26 @@ Set a sub-part in a document tree
1363
1364
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1364
1365
1365
1366
SOPS can set a specific part of a YAML or JSON document, by providing
1366
- the path and value in the ``-- set`` command line flag . This is useful to
1367
- set specific values, like keys, without needing an editor.
1367
+ the path and value in the ``set`` command. This is useful to set specific
1368
+ values, like keys, without needing an editor.
1368
1369
1369
1370
.. code:: sh
1370
1371
1371
- $ sops -- set ' [" app2" ][" key" ] " app2keystringvalue" ' ~/git/svc/sops/example.yaml
1372
+ $ sops set ~/git/svc/sops/example.yaml ' [" app2" ][" key" ]' ' " app2keystringvalue" '
1372
1373
1373
1374
The tree path syntax uses regular python dictionary syntax, without the
1374
1375
variable name. Set to keys by naming them, and array elements by
1375
1376
numbering them.
1376
1377
1377
1378
.. code:: sh
1378
1379
1379
- $ sops -- set ' [" an_array" ][1] " secretuser2" ' ~/git/svc/sops/example.yaml
1380
+ $ sops set ~/git/svc/sops/example.yaml ' [" an_array" ][1]' ' " secretuser2" '
1380
1381
1381
1382
The value must be formatted as json.
1382
1383
1383
1384
.. code:: sh
1384
1385
1385
- $ sops -- set ' [" an_array" ][1] {" uid1" :null," uid2" :1000," uid3" :[" bob" ]}' ~/git/svc/sops/example.yaml
1386
+ $ sops set ~/git/svc/sops/example.yaml ' [" an_array" ][1]' ' {" uid1" :null," uid2" :1000," uid3" :[" bob" ]}'
1386
1387
1387
1388
Showing diffs in cleartext in git
1388
1389
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1651,7 +1652,7 @@ when creating a new file:
1651
1652
1652
1653
.. code:: sh
1653
1654
1654
- $ sops --pgp "E60892BB9BD89A69F759A1A0A3D652173B763E8F,84050F1D61AF7C230A12217687DF65059EF093D3,85D77543B3D624B63CEA9E6DBC17301B491B3F21" mynewfile.yaml
1655
+ $ sops edit --pgp "E60892BB9BD89A69F759A1A0A3D652173B763E8F,84050F1D61AF7C230A12217687DF65059EF093D3,85D77543B3D624B63CEA9E6DBC17301B491B3F21" mynewfile.yaml
1655
1656
1656
1657
Threat Model
1657
1658
------------
0 commit comments