Keyringer ========= Keyringer lets you manage and share secrets using GPG and git in a distributed fashion. It has custom commands to encrypt, decrypt, recrypt, create key pairs, etc. Requirements ------------ Keyringer needs: - Ruby - Rubygems and the following gems: - git - gpgme - parseconfig Installation ------------ Just clone git clone git://git.sarava.org/keyringer.git And then leave it somewhere, optionally adding it to your $PATH environment variable. You can also package it to your preferred distro. Creating a keyringer repository ------------------------------- The first step is to setup a keyring. Keyringer supports management of multiple isolated keyrings. To start a new keyring (or register an existing one with your config file), run: keyringer init [remote] This will 1. Add an entry at $HOME/.keyringer/config aliasing 'keyring' to 'path'. 2. Initialize a git repository if needed. For example, keyringer friends init $HOME/keyrings/friends will create an alias "friends" pointing to $HOME/keyrings/friends. Call all other keyring actions using this alias. If there is an existing remote keyring git repository and you just want to checkout it, use keyringer friends init $HOME/keyrings/friends Managing recipients ------------------- Your next step is tell keyringer the GPG key ids to encrypt files to: keyringer recipients edit keyringer recipients ls Managing keys ---------------- Each key has a corresponding file in your keys subdirectory. keyringer is agnostic about how you store your secrets. You may choose to have one key file that contains one line for each secret, e.g. a single file called secrets with lines such as: emma : root : secret1 emma - /dev/hda : : secret2 Or you may also have a different key file for each secret, e.g. a file called emma.root that contains the root passphrase for the server named emma and another called emma.hda with the passphrase to decrypt /dev/hda on emma. Encrypting a key keyringer encrypt Decrypting a key (only to stdout) keyringer decrypt Re-encrypting a key keyringer recrypt Appending information to a key keyringer append Editing a key To edit a key, use keyringer edit Use this option with caution as it keeps temporary unencrypted data into keyringer temp folder and at your editor's temp files. Listing keys keyringer ls [arguments] Git wrapper ----------- Keyringer comes with a simple git wrapper to ease common management tasks: keyringer git remote add keyringer keyringer git push keyringer master keyringer git pull Managing puppet node keys ------------------------- Keyringer is able to manage node keys for puppet nodes. First add the puppet main and key folders into your keyring configuration: keyringer preferences add PUPPET=/path/to/puppet/config keyringer preferences add PUPPET_KEYS=/path/to/puppet/keys Configuration files, preferences and options -------------------------------------------- 1. Main config file: $HOME/.keyringer/config: store the location of each keyring. 2. User preferences per keyring: $HOME/.keyringer/: managed by "keyringer preferences". 3. Custom keyring options: $KEYRING_FOLDER/config/options: managed by "keyringer options". Notes ----- 1. The is any file inside the keys/ folder of your keyring directory. 2. Never decrypt a key and write it to the disk, except if you're adding it to your personall keyring. 3. Recipients are defined at file config/recipients. Please add just trustable recipients. Concepts -------- Basic idea is: - Encrypt stuff with ppl's gpg pubkeys and push the output in a git repo. - Let ppl keep it in sync with the repo and the keys are shared :) For "key" it's meant anything as the script work with stdin and output things to files, so it can be passphrases, private keys or other kind of info. It's possible to share keys using an encrypted mailing list, but the main difficulty is to track the message where the keys are. With theses scripts, the workflow is more or less like this: - You have a git repo for secret keys. - You run the "encrypt" command and paste your private key to this command (so no plaintext disk write). - The encrypt command writes an encrypted file to the repo. - You manually add it to git and push it to remote repositories. - Optionally, other ppl pulls the changes but they dont need to decrypt anything until they need to use the keys. So it's just gpg-encrypted data atop of a git repository (one can think of a kind of distributed encrypted filesystem). Git was chosen to host encrypted info mostly for two reasos: easy to distribute and its the only VCS known to make easier repository history manipulation. One possible drawback: the repo has pubkey information attached, which can be linked to real ppl (and then disclose the information about who has access to a given key), but it's possible to: - Keep the repo just atop of an encrypted and non-public place. - Or to consider an integration with gpg's --hidden-recipient option. Notes: Using with GNU Privacy Guard ----------------------------------- Exporting public keys: gpg --armor --export Exporting private keys (take care): gpg --armor --export-secret-keys TODO ---- There are lots of things that can be enhanced, like: - Enhanced documentation. - Interface with ssss where the scripts automatically splits passphrases into ssss tokens and encrypt those to different groups of users. - Hidden recipient support (including recipients file). - Rewrite using an object-oriented programming language. - Tab completion subcommand support for popular shells like bash. - Recipient check support, handling non-existing or revoked keys. - Encrypted and signed configuration files such as "recipients" and "options". - Leave key labels out of recipients file. - List available subommands.