diff options
Diffstat (limited to 'index.mdwn')
| -rw-r--r--[l---------] | index.mdwn | 224 |
1 files changed, 223 insertions, 1 deletions
diff --git a/index.mdwn b/index.mdwn index 100b938..0f77dc2 120000..100644 --- a/index.mdwn +++ b/index.mdwn @@ -1 +1,223 @@ -README
\ No newline at end of file +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. + +Homepage: https://keyringer.sarava.org + +Requirements +------------ + +Keyringer needs: + + - Bash - http://tiswww.case.edu/php/chet/bash/bashtop.html + - Git - http://git-scm.com + - GNU Privacy Guard - http://gnupg.org + - Grep, awk, tail, cut, sed and other GNU tools + +Optional dependencies if you want to manage ssl keys: + + - OpenSSL - http://www.openssl.org + +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 <keyring> init <path> [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 <repository-url> + +Managing recipients +------------------- + +Your next step is tell keyringer the GPG key ids to encrypt files to: + + keyringer <keyring> recipients edit [recipient-name] + keyringer <keyring> recipients ls + +Keyringer support multiple recipients in a per-folder style. Try it by +creating a sample keyringer + + keyringer <keyring> recipients edit closest-friends + +Fill it with your friends key IDs. Now encrypt a secret just for then: + + keyringer <keyring> encrypt closest-friends/secret + +In other words, if keyringer finds a recipient file matching a given path, +it will use it instead of the global recipients file. + +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 <keyring> encrypt <file> + +Decrypting a key (only to stdout) + + keyringer <keyring> decrypt <file> + +Re-encrypting a key or the whole repository + + keyringer <keyring> recrypt [file] + +Appending information to a key + + keyringer <keyring> append <file> + +Editing a key + +To edit a key, use + + keyringer <keyring> edit <file> + +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 <keyring> ls [arguments] + +Git wrapper +----------- + +Keyringer comes with a simple git wrapper to ease common management tasks: + + keyringer <keyring> git remote add keyringer <url> + keyringer <keyring> git push keyringer master + keyringer <keyring> git pull + +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/<keyring>: managed by + "keyringer <keyring> preferences". + + 3. Custom keyring options: $KEYRING_FOLDER/config/options: managed by + "keyringer <keyring> options". + +Using a non-default OpenPGP key +------------------------------- + +If you want to use a different key other than your default for a given +keyringer, use + + keyringer <keyring> preferences add KEYID=FINGERPRINT + +Notes +----- + + 1. The <file> 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 <keyid> + +Exporting private keys (take care): + + gpg --armor --export-secret-keys + |