Merge branch 'ADP-179_doc_sops' into 'master'

ADP-179 doc sops

See merge request smardigo-hetzner/communication-keys!13

README.md

@@ -1,10 +1,67 @@
-## howto create a gpg key
+# GPG Key Repo
+
+Purpose: Manage gpg keys for:
+* SOPS
+
+# Key Management
+
+## howto create and add a gpg key
 - please follow instruction on following link: https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key
 - add ONLY the _PUBLIC_ part of your gpg key!!!
 - checkin via MergeRequest/PullRequest
 
 ### import gpg keys
+```shell
 gpg --import /path/to/keys/*.gpg.pub
+```
 
 ### list imported gpg keys
+```shell
 gpg --list-keys --keyid-format=long
+```
+
+# Configure SOPS
+
+SOPS is used for encrypting secrets, e.g. credentials for various systems
+
+## Install
+
+https://github.com/getsops/sops
+
+Note:
+* MacOS: If desired, one can also use brew to install sops: `brew install sops`; although this is not officially maintained, [the formula is essentially the same as the official installation instructions](https://github.com/Homebrew/homebrew-core/blob/4496ce5131bc09e7065fa0aa8fb96366a3df6477/Formula/s/sops.rb)
+
+## Usage
+
+Decrypt and Display Secrets in Terminal:
+
+```bash
+GPG_TTY=$(tty) sops secrets.yaml
+```
+
+Note: The `GPG_TTY` is necessary to have the password prompt appear. src: https://www.varokas.com/secrets-in-code-with-mozilla-sops/
+
+Note: `secrets.yaml` is just an example; the file can have any name
+
+## Example
+
+The steps in the following example can be run locally in order to:
+* create a sample secrets file
+* encrypt the file
+* decrypt the file
+
+If these steps work, sops is configured correctly - on your machine ;-) 
+
+```bash
+#!/usr/bin/env bash
+set -ueo pipefail
+# demo: create a file with a mock secret, src: https://bash-org-archive.com/?244321
+# PREREQUISITE: valid sops config, i.e. .sops.yaml - Note: most repos already have one
+# further reading: https://github.com/getsops/sops?tab=readme-ov-file#using-sops-yaml-conf-to-select-kms-pgp-and-age-for-new-files
+yq -n '.demo.credentials.secret = "hunter2"' > secrets.yaml
+# encrypt
+sops -e -i secrets.yaml
+
+# decript, print to console
+sops -d secrets.yaml
+```