From d4520835c98ce20fd01c5787ab8d436462f0ef6c Mon Sep 17 00:00:00 2001 From: fhoekstra <32362869+fhoekstra@users.noreply.github.com> Date: Sun, 24 May 2026 00:11:31 +0200 Subject: [PATCH 1/6] docs: Add example for dealing with compromised key The order of operations in this scenario is very specific and error-prone. It would make sense to document this right here in this project. Signed-off-by: fhoekstra <32362869+fhoekstra@users.noreply.github.com> --- content/en/docs/_index.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/content/en/docs/_index.md b/content/en/docs/_index.md index 2008b76..89d0218 100644 --- a/content/en/docs/_index.md +++ b/content/en/docs/_index.md @@ -1860,6 +1860,19 @@ You can also specify these options in the `.sops.yaml` config file. > and `--unencrypted-comment-regex` are mutually exclusive and > cannot all be used in the same file. +### Rotating secrets after a public key in a key group has been compromised + +First, remove the key from the key group in `.sops.yaml`, then run the following for each sops-encrypted file: + +``` sh +sops updatekeys secret.sops.yaml +sops rotate --in-place secret.sops.yaml +``` + +This ensures that *first* the compromised key is removed from the list of keys that has access to the per-file data key, and only *then* rotates the data key. If done in the wrong order, the data key is encrypted with a key that the compromised key still has access to. + +Only after this is done, should you start rotating the actual passwords, API keys and other secrets that are encrypted inside `secret.sops.yaml`. Otherwise, if you put in new credentials before completing this step, the compromised key would still have access to those. + ## Config file format This section describes the format of the SOPS config file. From 385f60cc6b70ea15f062ba595d8481a9b722b194 Mon Sep 17 00:00:00 2001 From: fhoekstra <32362869+fhoekstra@users.noreply.github.com> Date: Sun, 24 May 2026 09:16:44 +0200 Subject: [PATCH 2/6] Add small clarifications to key rotation example Signed-off-by: fhoekstra <32362869+fhoekstra@users.noreply.github.com> --- content/en/docs/_index.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/content/en/docs/_index.md b/content/en/docs/_index.md index 89d0218..94dcdb2 100644 --- a/content/en/docs/_index.md +++ b/content/en/docs/_index.md @@ -1860,9 +1860,9 @@ You can also specify these options in the `.sops.yaml` config file. > and `--unencrypted-comment-regex` are mutually exclusive and > cannot all be used in the same file. -### Rotating secrets after a public key in a key group has been compromised +### Rotating secrets after a key in a key group has been compromised -First, remove the key from the key group in `.sops.yaml`, then run the following for each sops-encrypted file: +First, remove the key from the key group in `.sops.yaml`, then run the following for each sops-encrypted file (only `secret.sops.yaml` in this example): ``` sh sops updatekeys secret.sops.yaml @@ -1871,6 +1871,8 @@ sops rotate --in-place secret.sops.yaml This ensures that *first* the compromised key is removed from the list of keys that has access to the per-file data key, and only *then* rotates the data key. If done in the wrong order, the data key is encrypted with a key that the compromised key still has access to. +Running `sops rotate` periodically is recommended anyways. + Only after this is done, should you start rotating the actual passwords, API keys and other secrets that are encrypted inside `secret.sops.yaml`. Otherwise, if you put in new credentials before completing this step, the compromised key would still have access to those. ## Config file format From 2ee1e80c00fe5febbc2890d19c0562dedb358c68 Mon Sep 17 00:00:00 2001 From: fhoekstra <32362869+fhoekstra@users.noreply.github.com> Date: Tue, 26 May 2026 18:44:26 +0200 Subject: [PATCH 3/6] Clarify wording on malicious access Co-authored-by: Felix Fontein Signed-off-by: fhoekstra <32362869+fhoekstra@users.noreply.github.com> --- content/en/docs/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/_index.md b/content/en/docs/_index.md index 94dcdb2..935ea5c 100644 --- a/content/en/docs/_index.md +++ b/content/en/docs/_index.md @@ -1873,7 +1873,7 @@ This ensures that *first* the compromised key is removed from the list of keys t Running `sops rotate` periodically is recommended anyways. -Only after this is done, should you start rotating the actual passwords, API keys and other secrets that are encrypted inside `secret.sops.yaml`. Otherwise, if you put in new credentials before completing this step, the compromised key would still have access to those. +Only after this is done, should you start rotating the actual passwords, API keys and other secrets that are encrypted inside `secret.sops.yaml`. Otherwise, if you put in new credentials before completing this step, the compromised key could still have access to those. ## Config file format From 1d7697eb1bed1696803abc45aba512f55719fd01 Mon Sep 17 00:00:00 2001 From: fhoekstra <32362869+fhoekstra@users.noreply.github.com> Date: Wed, 27 May 2026 07:52:25 +0200 Subject: [PATCH 4/6] [PR feedback]: Add @felixfontein's comment about when the order matters and clarify checking in of the updated file. Signed-off-by: fhoekstra <32362869+fhoekstra@users.noreply.github.com> --- content/en/docs/_index.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/content/en/docs/_index.md b/content/en/docs/_index.md index 935ea5c..148e619 100644 --- a/content/en/docs/_index.md +++ b/content/en/docs/_index.md @@ -1869,7 +1869,14 @@ sops updatekeys secret.sops.yaml sops rotate --in-place secret.sops.yaml ``` -This ensures that *first* the compromised key is removed from the list of keys that has access to the per-file data key, and only *then* rotates the data key. If done in the wrong order, the data key is encrypted with a key that the compromised key still has access to. +Commit and push the updated file. + +This ensures that *first* the compromised key is removed from the list of keys that has access to the per-file data key, and only *then* rotates the data key. If done in the wrong order, the compromised key could still have access to the data in some cases[^1]. + +[^1]: While it is generally better to schedule the operations this way, doing it the other way is only a problem in two specific situations: +- secret.sops.yaml file is checked in between the two sops calls above; +- alternatively, the compromised key is with a cloud provider (AWS, Azure, GCP, HWC, Vault) which is compromised itself, so that the call to encrypt the document key actually stores that document key. + Running `sops rotate` periodically is recommended anyways. From 33533f5e6d1200cce61d149a15427217f86bf70f Mon Sep 17 00:00:00 2001 From: fhoekstra <32362869+fhoekstra@users.noreply.github.com> Date: Wed, 27 May 2026 08:02:10 +0200 Subject: [PATCH 5/6] fix: footnote cannot be multi-line Signed-off-by: fhoekstra <32362869+fhoekstra@users.noreply.github.com> --- content/en/docs/_index.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/content/en/docs/_index.md b/content/en/docs/_index.md index 148e619..ebcf495 100644 --- a/content/en/docs/_index.md +++ b/content/en/docs/_index.md @@ -1873,10 +1873,7 @@ Commit and push the updated file. This ensures that *first* the compromised key is removed from the list of keys that has access to the per-file data key, and only *then* rotates the data key. If done in the wrong order, the compromised key could still have access to the data in some cases[^1]. -[^1]: While it is generally better to schedule the operations this way, doing it the other way is only a problem in two specific situations: -- secret.sops.yaml file is checked in between the two sops calls above; -- alternatively, the compromised key is with a cloud provider (AWS, Azure, GCP, HWC, Vault) which is compromised itself, so that the call to encrypt the document key actually stores that document key. - +[^1]: While it is generally better to schedule the operations this way, doing it the other way is only a problem in two specific situations: secret.sops.yaml file is checked in between the two sops calls above; alternatively, the compromised key is with a cloud provider (AWS, Azure, GCP, HWC, Vault) which is compromised itself, so that the call to encrypt the document key actually stores that document key. Running `sops rotate` periodically is recommended anyways. From c24040d641fb9b999932e6310052bb29ad46892c Mon Sep 17 00:00:00 2001 From: fhoekstra <32362869+fhoekstra@users.noreply.github.com> Date: Wed, 3 Jun 2026 09:25:37 +0200 Subject: [PATCH 6/6] Update content/en/docs/_index.md Co-authored-by: Felix Fontein Signed-off-by: fhoekstra <32362869+fhoekstra@users.noreply.github.com> --- content/en/docs/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/_index.md b/content/en/docs/_index.md index ebcf495..defbe7d 100644 --- a/content/en/docs/_index.md +++ b/content/en/docs/_index.md @@ -1873,7 +1873,7 @@ Commit and push the updated file. This ensures that *first* the compromised key is removed from the list of keys that has access to the per-file data key, and only *then* rotates the data key. If done in the wrong order, the compromised key could still have access to the data in some cases[^1]. -[^1]: While it is generally better to schedule the operations this way, doing it the other way is only a problem in two specific situations: secret.sops.yaml file is checked in between the two sops calls above; alternatively, the compromised key is with a cloud provider (AWS, Azure, GCP, HWC, Vault) which is compromised itself, so that the call to encrypt the document key actually stores that document key. +[^1]: While it is generally better to schedule the operations this way, doing it the other way is only a problem in two specific situations: the `secret.sops.yaml` file is checked in between the two sops calls above; alternatively, the compromised key is with a cloud provider (AWS, Azure, GCP, HWC, Vault) which is compromised itself, so that the call to encrypt the document key actually stores that document key. Running `sops rotate` periodically is recommended anyways.