communication-keys/README.md

# GPG Key Repo

Purpose: Manage gpg keys for:
* SOPS

# Key Management

Roles:

* New User: new key to be added; can be a new employee being added for first time, existing employee getting access to a new repo, key rotation, etc
* Existing User: user who already has access to the appropriate project
  * E.g. look up in the [groups](/groups/) dir
  * E.g. look up in in [verify/.sops.yaml](verify/.sops.yaml)

## 1a. Onboarding: [New User]: create and add a gpg key
- create a branch titled `add_pubkey_<firstname>-<lastname>`
  - e.g. `git branch add_pubkey_test-user`
  - Note: no strict naming convention for the branch, it's strictly a Human-in-the-Loop process
- please follow steps 1-13 at the following link: https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key
  - CAVEAT: step 14 is not necessary, as it is specific to a GitHub account
- add ONLY the _PUBLIC_ part of your gpg key!!! to this repo
  - file format: `<email>@netgo.de.gpg.pub`
- git: commit the new file, push
- open a MergeRequest/PullRequest
- hand-off to an Existing User of the repo. 

## 1b. Onboarding: [Existing User|New User]: Add new user to groups

Access for each repo is tracked using the `./groups/` directory; each sub-directory represents a "group" (Note: some "groups" are also "roles", e.g. `admin`)

Most of the groups correspond directly to git repository names, aka "project name"

```bash
cd groups/<project_name>
ln -s ../../<path_to_key.gpg.pub>
```

Note: this step can be performed by anyone (either new user or existing user), but it makes the most sense for an existing user to configure the groups since this is domain-specific knowledge (i.e. new users won't typically know the grups)

## 3. Onboarding: [Existing User]: Configure sops config

Context: This repo stores the keys used to encrypt secrets in other repos; these "consumer" repos each contain a sops config `.sops.yaml` which manages access to the encrypted files (e.g. `secrets.yaml`)

For verification purposes, this repo also contains a _sample_ `.sops.yaml` to which every key in the repo is added. This allows both Existing Users to instantly verify the new key, and New Users to verify that their sops installation works correctly.

### Update Verification SOPS Config

Follow the interactive prompts:
```shell
./verify/usr_confirm_keycfg.sh
```

### Update Project SOPS Config

The following commands explain how to update the `.sops.yaml` for a repository:

#### Prerequisite
```shell
# E.g. update sops config for DevNSO
% git clone git@git.dev-at.de:cloud-solutions/nso/devnso-adp-argocd.git
% cd devnso-adp-argocd/
```

#### Commands

```shell
# List available groups
% ${PATH_TO_THIS_REPO}/bin/update_sops.sh --list_groups
# INFO: listing groups
admin
automation
devnso-adp-argocd

# For a given group, update sops config
% ~/ws/netgo/git.dev-at.de/smardigo-hetzner/communication-keys/bin/update_sops.sh -g devnso-adp-argocd
# RUN: generate SOPS config
# WARN: no secrets file passed in, make sure to call 'sops updatekeys' on secrets files

# [OPTIONAL] For a given group, update sops config AND specified secrets file
% ${PATH_TO_THIS_REPO}/bin/update_sops.sh -g devnso-adp-argocd -s ./adp-api-devs/adp-api-devs/secrets.yaml

# commit the changes to any .sops.yaml or secrets files, e.g. with 
## OPINIONATED GIT - use preferred method
% git add -p
% git commit -m "adds <firstname>.<lastname> to sops config"
% git push
```

At this point, the New User has been configured and can grant themselves access to any of the secrets files in this project.

## 4. Onboarding: [New User] 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

## 5. Offboarding: [Existing User]: Archive Expired Keys (EOL)

To mark a key as expired, move it to the `archive/` dir as follows:

```bash
mv ${keyname} "archive/${keyname}_$(date '+%Y-%m-%d').archive"
```

# Advanced

# Reference: Commands for gpg keys
## import gpg keys
```shell
gpg --import /path/to/keys/*.gpg.pub
```

## list imported gpg keys
```shell
gpg --list-keys --keyid-format=long
```

## SOPS Example - Manual

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
```

# Contributing

Tests: `./verify/test.sh`

Caveat: requires working SOPS config,pgp key, etc