1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
|
[[!meta title="Keyringer: encrypted and distributed secret sharing software"]]
Keyringer lets you manage and share secrets using GnuPG and Git with custom
commands to encrypt, decrypt, recrypt, create key pairs, etc.
- Project page: [https://keyringer.pw](https://keyringer.pw)
- Manpage: [keyringer.1](share/man/keyringer.1)
- License: [GPLv3+](LICENSE)
- Issue tracker: [https://keyringer.pw/trac](https://keyringer.pw/trac)
- Tor hidden service: [http://y6ntvl5bzs3c7ffa.onion](http://y6ntvl5bzs3c7ffa.onion)
- Releases: [https://keyringer.pw/releases](releases)
- Contact: rhatto at riseup.net
Index
-----
[[!toc levels=4]]
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.
If you're using Debian `jessie` or `unstable`, just run
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
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 OpenPGP 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 recipient file:
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.
You can even create recipient files with your friends' key IDs but without
yours: then you shall be able to encrypt secrets for them that even you cannot
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.
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 <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]
Each `<secret>` is stored as a file inside the `keys/` folder of your keyring
directory.
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
Concepts
--------
Basic idea is:
- Encrypt screts using multiple users's OpenPGP public keys and commit the output in a git repository.
- Let users keep it in sync with the repository and the secrets are shared :)
Secrets can be any regular file as the script work with stdin and output things to
files, so it can be passphrases, private keys or other kind of information.
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 is written to disk).
- The encrypt command writes an encrypted file to the repo.
- You manually add it to git and push it to remote repositories.
- Optionally, other users pulls the changes but they dont need to
decrypt anything until they need to use the keys.
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.
One possible drawback: the repo has pubkey information attached, which can be
linked to real people (and then disclose the information about who has access to a
given key).
To mitigate that, 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.
Never decrypt a key and write it to the disk, except if you're adding it to
your personall keyring.
Check [this page](https://wiki.koumbit.net/PasswordManagementService/SoftwareComparison)
a comparison on different password management tools.
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)
Development guidelines
----------------------
See [development](development).
|
