first version of the knowledge base :)

20 - Knowledge/security/gpg-basics.md

@@ -0,0 +1,120 @@
+---
+title: GPG Basics
+description: Overview of core GnuPG concepts, key management, and common operational workflows
+tags:
+  - security
+  - gpg
+  - encryption
+category: security
+created: 2026-03-14
+updated: 2026-03-14
+---
+
+# GPG Basics
+
+## Introduction
+
+GPG, implemented by GnuPG, is used for public-key encryption, signing, and verification. It remains common for signing Git commits and tags, exchanging encrypted files, and maintaining long-term personal or team keys.
+
+## Purpose
+
+This document covers:
+
+- What GPG keys and subkeys are
+- Common encryption and signing workflows
+- Key management practices that matter operationally
+
+## Architecture Overview
+
+A practical GPG setup often includes:
+
+- Primary key: used mainly for certification and identity management
+- Subkeys: used for signing, encryption, or authentication
+- Revocation certificate: lets you invalidate a lost or compromised key
+- Public key distribution: keyserver, WKD, or direct sharing
+
+The primary key should be treated as more sensitive than everyday-use subkeys.
+
+## Core Workflows
+
+### Generate a key
+
+Interactive generation:
+
+```bash
+gpg --full-generate-key
+```
+
+List keys:
+
+```bash
+gpg --list-secret-keys --keyid-format=long
+```
+
+### Export the public key
+
+```bash
+gpg --armor --export KEYID
+```
+
+### Encrypt a file for a recipient
+
+```bash
+gpg --encrypt --recipient KEYID secrets.txt
+```
+
+### Sign a file
+
+```bash
+gpg --detach-sign --armor release.tar.gz
+```
+
+### Verify a signature
+
+```bash
+gpg --verify release.tar.gz.asc release.tar.gz
+```
+
+## Configuration Example
+
+Export a revocation certificate after key creation:
+
+```bash
+gpg --output revoke-KEYID.asc --gen-revoke KEYID
+```
+
+Store that revocation certificate offline in a secure location.
+
+## Troubleshooting Tips
+
+### Encryption works but trust warnings appear
+
+- Confirm you imported the correct public key
+- Verify fingerprints out of band before marking a key as trusted
+- Do not treat keyserver availability as proof of identity
+
+### Git signing fails
+
+- Check that Git points to the expected key ID
+- Confirm the GPG agent is running
+- Verify terminal pinentry integration on the local system
+
+### Lost laptop or corrupted keyring
+
+- Restore from secure backups
+- Revoke compromised keys if needed
+- Reissue or rotate subkeys while keeping identity documentation current
+
+## Best Practices
+
+- Keep the primary key offline when practical and use subkeys day to day
+- Generate and safely store a revocation certificate immediately
+- Verify key fingerprints through a trusted secondary channel
+- Back up secret keys securely before relying on them operationally
+- Use GPG where it fits existing tooling; do not force it into workflows that are better served by simpler modern tools
+
+## References
+
+- [GnuPG Documentation](https://www.gnupg.org/documentation/)
+- [The GNU Privacy Handbook](https://www.gnupg.org/gph/en/manual/book1.html)
+- [GnuPG manual](https://www.gnupg.org/documentation/manuals/gnupg/)