Keyringer: encrypted and distributed secret sharing software

NB: We've just forked this project to add a key feature for us: recipients management per folder, otherwise you can't have subfolders with different recipients.

Keyringer lets you manage and share secrets using GnuPG and Git with custom commands to encrypt, decrypt, recrypt, create key pairs, etc.

This is from the original website:

• Project page: https://keyringer.pw
• Manpage: keyringer.1
• License: GPLv3+
• Issue tracker: https://keyringer.pw/trac
• Tor hidden service: http://4qt45wbulqipigwa.onion
• Releases: https://keyringer.pw/releases
• Contact: rhatto at riseup.net

Installation

Just clone:

git clone https://github.com/quarkslab/keyringer

And then leave it somewhere, optionally adding it to your $PATH environment variable or package it to your preferred distro.

If you're using Debian jessie or newer, just run (be careful, it's not compatible with the new features):

apt-get install keyringer

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

creates an alias "friends" pointing to $HOME/keyrings/friends. All other keyring actions for this keyring should be called using this alias. An advantage is you don't need to be into the keyring to perform operations on it.

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 secrets

Each secret has a corresponding encrypted file inside keys subdirectory from the keyring folder. Keyringer has plenty of actions to operate in these secrets:

keyringer <keyring> commands

Encrypting a secret from stdin:

keyringer <keyring> encrypt <secret>

Encrypting a secret from a file:

keyringer <keyring> encrypt <secret> <plaintext-file>

Decrypting a secret (only to stdout):

keyringer <keyring> decrypt <secret>

Re-encrypting a secret or the whole repository:

keyringer <keyring> recrypt [secret]

Appending information to a secret:

keyringer <keyring> append <secret>

Editing a secret:

keyringer <keyring> edit <secret>

Use this option with caution as it keeps temporary unencrypted data into a temporary folder.

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, options and recipients

Basic keyringer operation depends in a set of configuration files:

1. Main config file: $HOME/.keyringer/config: store the location of each keyring.

2. User preferences per keyring: $HOME/.keyringer/<keyring>: managed by "keyringer preferences". Preferences aren't shared among users, so each user can have it's own set of preferences.

3. Custom keyring options: $KEYRING_FOLDER/config/options: managed by "keyringer options". Options are shared among all keyring users.

4. Recipients: $KEYRING_FOLDER/config/recipients/: controls the list of OpenPGP public key fingerprints that should be used when encrypting content. Multiple recipients are supported, so secrets can be encrypted to different sets of OpenPGP pubkeys in the same keyring.

Other configuration parameters used by keyringer and it's actions are stored at $KEYRING_FOLDER/config/.

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

Managing recipients

Global default

Keyringer uses the default recipient stored at $KEYRING_FOLDER/config/recipients/default as the standard list of OpenPGP public key fingerprints to which secrets should be encrypted.

When you have first initialized your keyring, keyringer might have asked you to populate the default recipient list or you cloned a keyring repository which already has the default recipient.

Recipients for a specific secret

Additionally, keyringer supports multiple recipient files which can have a different set of OpenPGP public key fingerprints used for encryption.

Recipients are matched against secrets according to their paths. If it exists a recipient called accounting/balance (located at $KEYRING_FOLDER/config/recipients/accounting/balance.r), the following secret will be encrypted using it's OpenPGP public key fingerprints:

keyringer <keyring> encrypt accounting/balance

In other words, the accounting/balance recipient is used because there is an exact match between the secret name and the recipient name.

So it's the case that recipients listed in the default recipient but not in the accounting/balance recipients won't be able to decrypt this secret.

Default recipients per folder

If you don't want to specify recipients for each secret, you can define default recipient for a specific folder, just as the default recipient (see above) works for the top folder.

For example, if it exists a recipient called accounting/default, the following secret will be encrypted using it's OpenPGP public key fingerprints:

keyringer <keyring> encrypt accounting/invoices

In other words, the accounting/default recipient is used because there no exact match between the secret name and any recipient but there is a default recipient for the concerned folder.

In there is no default recipient for the concerned folder, keyringer will look up on the folder above, and again and again until it hits the default recipient file at the top.

Manage recipients

you want more recipients, next step is tell keyringer the OpenPGP key IDs to encrypt files to:

keyringer <keyring> recipients edit [recipient-name]
keyringer <keyring> recipients ls

Remember that keyringer support multiple recipients in a per-folder style. Try it by creating a default recipient within a folder:

keyringer <keyring> recipients edit closest-friends/default

Fill it with your friends key IDs. Now encrypt a secret just for them:

keyringer <keyring> encrypt closest-friends/secret

In other words, if keyringer finds a recipient matching a given path, it will use it instead of the global recipient. And default recipient within the closest folder is chosen again the global recipient.

You can even create recipient with your friends' key IDs but without yours: then you shall be able to encrypt secrets for them that even you can not access. Try to find an use case for that ;)

Each recipient list is defined in a file placed at config/recipients in your keyring repository. Take care to add just trustable recipients.

Recipients against recipient files

You may have notice that the recipient file for a specific secret ends with the ".r" extension, and that default recipient files are just "default" files. It's a builtin feature to allow you manage a tree view for your secrets, and to allow you to create secrets called "default". You don't have to care about that, except if you want to manage directly the recipient files, which is not recommended. See the Manage recipients section just above to manage recipients instead of recipient files.

Design

Keyringer's basic concepts are as follows:

• Each secret is encrypted using multiple users's OpenPGP public keys and committed in a git repository we call a "keyring".

• A "recipient" is a list of OpenPGP keys associated with a path in the keyring, so each keyring can have multiple recipient definitions so secret compartmentalization is builtin. All encryption should respect recipient definition.

• Users can keep their keyring copies in sync using any git remote and push/pull strategy they like, so key sharing gets easy.

• A secret is not limited to passphrases or text: keyringer supports any file encryption, so managing private keys, spreadsheets and media files are handled without distinction.

• Secret is stored with OpenPGP ASCII-armoured output, so one doesn't need any special program besides GnuPG to actually decrypt information.

• 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.

  Creating a logical structure to store your secrets is up to you :)

Workflow

Keyringer can be used as a personal or shared password/secret manager:

• Each keyring is a full git repository used to store encrypted secrets using ASCII-armoured OpenPGP.

• Actions like encrypt allows you to paste your secrets directly to GnuPG so no plaintext is written to disk.

• By commiting, pushing and pulling each keyring repository, you can easily share secrets with other people and systems and they don't need to decrypt this information until they need.

In summary, keyringer data store is basically 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.

Limitations

• See the manpage for details.

• Check this page a comparison on different password management tools.

Requirements

Keyringer needs:

• Bash
• Git
• GNU Privacy Guard
• Grep, awk, tail, cut, sed and other GNU tools

Optional dependencies if you want to manage ssl keys:

• OpenSSL

Development guidelines

Please PR.