[question] Where is the documentation?

[toraritte]

Tried to find the man pages or a more in-depth documentation (as I have only a minimal experience with cryptographic concepts and tools), but it looks like the de facto documentation is simply the repo's README. Here are some other resources I could scrounge up:

• 3rd party blog posts (my go-tos are this and this)

• the docs directory in this repo, that is only about the release process

• the getsops/docs repo created ca. 3 weeks ago, but it is empty for now

For context:
We've been using SOPS in production for more than a year now; setting it up was a trial and error affair (because of my lack of experience), but haven't had to touch since then. An issue came up (not with SOPS, but with Azure keyvault), so needed to add another method to unlock the encrypted config file. I don't even know what the right terms here to start searching for the problem: add a new encryption method to unlock the SOPS master key? The repo's README provides a lot of recipes, but doesn't explain some of the SOPS basics (and looking at its structure it looks like subsequent additions made things more cluttered).

sops --help shows the available flags, so I guess I just need to figure out how to use --add-age (because want to use AGE as an alternative method), but then I saw the main "COMMANDS" section, and would like to learn more. Such as, what does keyservice do? The closest I came to understanding it is finding sops/keyservice/keyservice.go using a Google search, but the comment there didn't help much:

Package keyservice implements a gRPC API that can be used by SOPS to encrypt and decrypt the data key using remote
master keys.

Thank you!

[felixfontein]

You found all current documentation. There isn't any more right now.

(And it doesn't help that GitHub screws up RST formatting.)

You can either use the rotate command (https://github.com/getsops/sops/blob/main/README.rst#rotate-command) to explicitly add or remove access keys from a file. (Note that the currently released version doesn't have a rorate command, you have to use the --rotate flag instead.)

Or you can update .sops.yaml to mention all the keys that should be there, and use the updatekeys command to ensure that your SOPS encrypted file uses the keys specified in .sops.yaml.

(I usually use .sops.yaml to specify which keys should be able to access which files - in a simple setup there's only one such configuration for all files - and then use updatekeys to make sure exactly these keys have access.)

[toraritte]

You found all current documentation. There isn't any more right now.

Thank you for confirming! If one would like to contribute to docs, should issues and pull requests go in the getsops/docs repo?

Thanks also for the details on how to add extra keys and best practices! (I completely missed the section you linked...)

edit: Sorry also for this issue - I also missed that the there is a discussion page for this repo.