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
  * Definition: List of all users: [verify/.sops.yaml](verify/.sops.yaml)

## 1a. Onboarding: [New User]: create and add a gpg key
1. Clone this repository
1. Create a branch titled `add_pubkey_[firstname]-[lastname]`. <!-- NOTE: Validation Hack: User will not be able to mistakenly create this literal branch, as the unpermitted chars '[' will prevent the branch from being created: "Branch name cannot contain '['" as per https://git-scm.com/docs/git-check-ref-format. I.e. it's a dirty hack to get some server-side(?) validation ;-) --> <!--  - Web: e.g. The following link can be used to create a branch: [https://git.dev-at.de/smardigo-hetzner/communication-keys/-/branches/new?branch_name=add_pubkey_[firstname]-[lastname]](https://git.dev-at.de/smardigo-hetzner/communication-keys/-/branches/new?branch_name=add_pubkey_[firstname]-[lastname]) -->
    - CLI: e.g. `git branch add_pubkey_Max-Musterman`
    - Note: no strict naming convention for the branch, it's strictly a Human-in-the-Loop process
1. 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
1. add ONLY the _PUBLIC_ part of your gpg key!!! to your branch
    - file format: `<email>@netgo.de.gpg.pub`
1. git: commit the new file, push
1. open a MergeRequest
1. Hand-Off: Assign the MR to an Existing User in your Team to have your key added.
    - Hint: Look up all Existing Users in the comments at: [verify/.sops.yaml](verify/.sops.yaml)

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

Determine the groups to which access is needed, e.g. a specific repository.

If uncertain, ask a Team Member for help!

Technical Instructions - please forgive the complexity

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"

Create a symlink from the group-directory back to the keyfile
```shell
cd groups/<project_name>
ln -s ../../<path_to_key.gpg.pub>
```

Example:

Add "Max Musterman" to the group for `devnso-adp-argocd`:
```shell
# navigate to group-directory for devnos
cd groups/devnso-adp-argocd
# symlink to pubkey for New User
ln -s ../../max.musterman@netgo.de.gpg.pub
```

## 2. 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_COMMUNICATION_KEYS_REPO}/bin/update_sops.sh --list_groups
# INFO: listing groups
admin
automation
devnso-adp-argocd

# For a given group, update sops config
% ${PATH_TO_COMMUNICATION_KEYS_REPO}/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_COMMUNICATION_KEYS_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.

## 3. 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

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

To mark a key as expired:
1. move it to the `archive/` dir
2. for each group, update the project repo
3. remove the key from the group

### 1. This repo: archive
```shell
# archive key - DO NOT delete - need this for auditing
git mv ${keyname} "archive/${keyname}_$(date '+%Y-%m-%d').archive"
# remove from verification sops
./verify/usr_confirm_keycfg.sh
```

### 2. For each group / repo:

**Prerequisite**: Local copy of each repo corresponding to a group

```shell
# list all groups to which the key is registered
find groups/ -name ${keyname}

# For each group, update sops config in that repo
# Example:
% cd devnso-adp-argocd
% ${PATH_TO_COMMUNICATION_KEYS_REPO}/bin/update_sops.sh -g devnso-adp-argocd
# now git commit, push, etc
```

### 3. This repo: update groups
```shell
# remove from groups
find groups -name ${keyname} | xargs git rm
```

# 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