diff options
Diffstat (limited to 'index.mdwn')
| -rw-r--r-- | index.mdwn | 218 |
1 files changed, 218 insertions, 0 deletions
diff --git a/index.mdwn b/index.mdwn new file mode 100644 index 0000000..7ed01a6 --- /dev/null +++ b/index.mdwn @@ -0,0 +1,218 @@ +[[!meta title="Keyringer: encrypted and distributed secret sharing software"]] + +Keyringer lets you manage and share secrets using GPG and git with custom +commands to encrypt, decrypt, recrypt, create key pairs, etc. + +- Project page: [https://keyringer.pw](https://keyringer.pw) +- Issue tracker: [https://keyringer.pw/trac](https://keyringer.pw/trac) +- Tor hidden service: [http://y6ntvl5bzs3c7ffa.onion](http://y6ntvl5bzs3c7ffa.onion) +- Contact: rhatto at keyringer.pw + +Installation +------------ + +Just clone + + git clone git://git.sarava.org/keyringer.git + +And then leave it somewhere, optionally adding it to your `$PATH` environment variable +or 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`. All +other keyring actions should be called 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 secrets +---------------- + +Each secret has a corresponding file in your `keys` subdirectory. + +Keyringer is agnostic about how you store your secrets. You may choose to have +one encrypted 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 encrypted 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 secret + + keyringer <keyring> encrypt <file> + +Encrypting a secret from a file + + keyringer <keyring> encrypt <plaintext-file> <file> + +Decrypting a secret (only to stdout) + + keyringer <keyring> decrypt <file> + +Re-encrypting a secret or the whole repository + + keyringer <keyring> recrypt [file] + +Appending information to a secret + + keyringer <keyring> append <file> + +Editing a secret + +To edit a secret, 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 secrets + + 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> + +Example: + + keyringer <keyring> preferences add KEYID=0123456789ABCDEF0123456789ABCDE012345678 + +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`. + Take care to 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. + +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) + |