summaryrefslogtreecommitdiff
path: root/share/man/keyringer.1
blob: 19f447ffc8502351a9d5179991478c876606a4ad (plain)
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
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
.TH "KEYRINGER" "1" "Oct 25, 2013" "Keyringer User Manual" ""
.SH NAME
.PP
keyringer \- encrypted and distributed secret sharing software
.SH SYNOPSIS
.PP
keyringer <\f[I]keyring\f[]> <\f[I]action\f[]> [\f[I]options\f[]]...
.SH DESCRIPTION
.PP
Keyringer lets you manage and share secrets using GnuPG and Git in a
distributed fashion.
.PP
It has custom commands to create key\-pairs and to encrypt, decrypt and
re\-encrypt secrets.
It also supports encryption to multiple recipients and groups of
recipients, to allow a workgroup to share access to a single repository
while restricting some secrets to subsets of the group.
.PP
Secrets are encrypted using OpenPGP and added to a Git tree so that they
can be synced with remote branches later.
.SH ACTIONS
.PP
Keyringer has three types of actions:
.IP "1." 3
Repository lookup and manipulation actions, which handle repository
initialization, content tracking and navigation.
.IP "2." 3
Secret manipulation actions, which take care of encrypting, decrypting
and other read/write operations on secrets.
.IP "3." 3
Configuration actions, handling repository metadata.
.SH REPOSITORY LOOKUP AND MANIPULATION ACTIONS
.TP
.B find <\f[I]expression\f[]>
Find secrets in the repository.
.RS
.RE
.TP
.B init <\f[I]path\f[]> [\f[I]remote\f[]]
Initialize a new keyringer repository.
If a \f[I]remote\f[] URL is specified, keyringer will clone an existing
repository.
.RS
.PP
After initialization, \f[I]path\f[] will contain a folder structure for
storing secrets and metadata (user aka recipients, groups of recipients,
etc).
.PP
Also, an entry will be added to \f[C]$HOME/.keyringer/config\f[]
allowing keyringer to find the keyring by its alias.
.RE
.TP
.B destroy
Alias for \f[I]teardown\f[] action.
.RS
.RE
.TP
.B git <\f[I]action\f[]> <\f[I]options\f[]>
Git wrapper that operates from the toplevel keyring repository.
You can issue any \f[I]GIT(1)\f[] subcommand with this action to have it
applied in the keyring repository.
.RS
.RE
.TP
.B commit [\f[I]arguments\f[]]
Alias to "git commit".
.RS
.RE
.TP
.B ls <\f[I]path\f[]>
List contents from the toplevel repository \f[I]keys\f[] folder or from
relative paths if \f[I]path\f[] is specified.
Like the git wrapper, this is a wrapper around the \f[I]LS(1)\f[]
command.
.RS
.RE
.TP
.B mkdir <\f[I]path\f[]>
Create a directory inside the repository \f[I]keys\f[] folder.
.RS
.RE
.TP
.B rmdir <\f[I]path\f[]>
Remove an empty folder inside the repository \f[I]keys\f[] folder.
.RS
.RE
.TP
.B tree <\f[I]path\f[]>
List contents from the toplevel repository \f[I]keys\f[] folder or from
relative paths if \f[I]path\f[] is specified using a tree\-like format.
Like the ls wrapper, this is a wrapper around the \f[I]TREE(1)\f[]
command.
.RS
.RE
.TP
.B shell
Run keyringer on interactive mode from a built\-in command\-line prompt
where all other actions can be called and are operated from the current
selected keyring.
.RS
.PP
An additional "cd" internal command is available for directory
navigation.
.PP
All <\f[I]secret\f[]> parameters from actions invoked from the shell are
called relatively from the current selected directory.
.RE
.TP
.B teardown
Remove permanently a local copy of a repository, very dangerous if you
have just a single copy.
.RS
.RE
.TP
.B check
Run maintenance checks in a keyring.
.RS
.RE
.SH SECRET MANIPULATION ACTIONS
.PP
All secret manipulation actions operate upon a \f[I]secret\f[] which is
the pathname of an encrypted file relative to the keyring with optional
\f[C]\&.asc\f[] extension.
.PP
If the \f[C]\&.asc\f[] extension is omitted, keyringer will add it at
the end of the pathname.
.PP
No spaces are allowed in the secret name.
.PP
Secret manipulation actions do not commit changes into the secret
repository.
Instead, the user has to manually commit the changes using the git
wrapper action.
.TP
.B append <\f[I]secret\f[]>
Append contents into a secret by decrypting the secret, appending lines
read from the standard input and encrypting again.
.RS
.RE
.TP
.B append\-batch <\f[I]secret\f[]>
Append contents into a secret, batch mode.
.RS
.RE
.TP
.B decrypt <\f[I]secret\f[]>
Decrypts a secret into standard output.
.RS
.RE
.TP
.B del <\f[I]secret\f[]>
Removes a secret using Git.
After deleting a secret a git commit and push is still needed to update
remote repositories.
.RS
.PP
Please note that this command \f[B]does not remove the secret from the
Git history.\f[] To completely remove a file from a keyring, you should
also rewrite the Git history yourself.
.RE
.TP
.B rm <\f[I]secret\f[]>
Alias for \f[I]del\f[] action.
.RS
.RE
.TP
.B cp <\f[I]secret\f[]> <\f[I]dest\f[]>
Copy a secret.
.RS
.RE
.TP
.B mv <\f[I]secret\f[]> <\f[I]dest\f[]>
Rename a secret.
.RS
.RE
.TP
.B edit <\f[I]secret\f[]>
Edit a secret by temporarily decrypting it, opening the decrypted copy
into the text editor defined by the \f[I]$EDITOR\f[] environment
variable and then re\-encrypting it.
.RS
.PP
Please make sure to use an
\f[I]\f[I]E\f[]\f[I]D\f[]\f[I]I\f[]\f[I]T\f[]\f[I]O\f[]\f[I]R\f[] * \f[I]w\f[]\f[I]h\f[]\f[I]i\f[]\f[I]c\f[]\f[I]h\f[]\f[I]d\f[]\f[I]o\f[]\f[I]e\f[]\f[I]s\f[]\f[I]n\f[]\f[I]o\f[]\f[I]t\f[]\f[I]l\f[]\f[I]e\f[]\f[I]a\f[]\f[I]k\f[]\f[I]d\f[]\f[I]a\f[]\f[I]t\f[]\f[I]a\f[]\f[I]l\f[]\f[I]i\f[]\f[I]k\f[]\f[I]e\f[]\f[I]h\f[]\f[I]i\f[]\f[I]s\f[]\f[I]t\f[]\f[I]o\f[]\f[I]r\f[]\f[I]y\f[]\f[I]b\f[]\f[I]u\f[]\f[I]f\f[]\f[I]f\f[]\f[I]e\f[]\f[I]r\f[]\f[I]s\f[].\f[I]K\f[]\f[I]e\f[]\f[I]y\f[]\f[I]r\f[]\f[I]i\f[]\f[I]n\f[]\f[I]g\f[]\f[I]e\f[]\f[I]r\f[]\f[I]t\f[]\f[I]r\f[]\f[I]i\f[]\f[I]e\f[]\f[I]s\f[]\f[I]t\f[]\f[I]o\f[]\f[I]d\f[]\f[I]e\f[]\f[I]t\f[]\f[I]e\f[]\f[I]c\f[]\f[I]t\f[]\f[I]i\f[]\f[I]f\f[] * EDITOR\f[]
is set to VIM and disables the \f[I]\&.viminfo\f[] file.
.RE
.TP
.B encrypt <\f[I]secret\f[]> [\f[I]file\f[]]
Encrypts content from standard input or \f[I]file\f[] into
\f[I]secret\f[] pathname.
No spaces are supported in the \f[I]secret\f[] name.
If \f[I]file\f[] is actually a folder, keyringer will recursivelly
encrypt all it\[aq]s contents.
.RS
.RE
.TP
.B encrypt\-batch <\f[I]secret\f[]> [\f[I]file\f[]]
Encrypt content, batch mode.
Behavior is identical to \f[I]encrypt\f[] action, but less verbose.
Useful inside scripts.
.RS
.RE
.TP
.B genkeys <\f[I]ssh\f[]|\f[I]gpg\f[]|\f[I]x509\f[]|\f[I]x509\-self\f[]|\f[I]ssl\f[]|\f[I]ssl\-self\f[]> [\f[I]options\f[]]
Wrapper to generate encryption key\-pairs, useful for automated key
deployment.
.RS
.RE
.TP
.B genpair <\f[I]ssh\f[]|\f[I]gpg\f[]|\f[I]x509\f[]|\f[I]x509\-self\f[]|\f[I]ssl\f[]|\f[I]ssl\-self\f[]> [\f[I]options\f[]]
Alias for \f[I]genkeys\f[] action.
.RS
.RE
.TP
.B open <\f[I]secret\f[]>
Decrypt a secret into a temporary folder and open it using xdg\-open,
which tries to figure out the file type and then calls the associated
application.
.RS
.PP
After the application exits, keyringer encrypts the temporary decrypted
file again into the secret file and deletes the temporary file.
.RE
.TP
.B pwgen <\f[I]secret\f[]> [\f[I]size\f[]]
Generates a random passphrase and stores into \f[I]secret\f[] pathname
with optional entropy size in bytes.
Default size is 20.
.RS
.PP
Passphrases will be slightly bigger than size due to base64 conversion.
.PP
With this action you can generate and store a passphrase without need to
see it.
Combined with clip or sclip action provides an hygienic way to handle
secrets.
.RE
.TP
.B recrypt <\f[I]secret\f[]>
Re\-encrypts a secret by decrypting it and encrypting it again.
Useful when users are added into the recipient configuration.
If no \f[I]secret\f[] is given, all secrets in the repository are
re\-encrypted.
.RS
.RE
.TP
.B clip <\f[I]secret\f[]>
Copy the first line of a secret to the clipboard, following
password\-store convention.
.RS
.RE
.TP
.B xclip <\f[I]secret\f[]>
Alias to clip action.
.RS
.RE
.TP
.B sclip <\f[I]secret\f[]>
Same as clip action, but sleeps five seconds, overwrite clipboard and
exit.
If xdotool is available, it also switches to the next window using the
alt+Tab shortcut.
This action is useful to be invoked by a custom key combo in a window
manager so it becomes easy to provide keyringer managed passphrases to
other applications such as a web browser.
.RS
.RE
.SH CONFIGURATION ACTIONS
.TP
.B commands
List available actions, useful for shell completion and syntax check.
.RS
.RE
.TP
.B options <\f[I]ls\f[]|\f[I]edit\f[]|\f[I]add\f[]>
List, edit or add miscellaneous \f[I]repository\f[] options.
.RS
.PP
Repository options are settings which are saved in the repository as a
\f[I]global\f[] configuration stanza for a given keyring, shared by all
users with access to the repository.
.PP
Options are written using the \f[I]KEY=VALUE\f[] syntax.
All lines starting with the hash (#) character are interpreted as
comments.
.RE
.TP
.B preferences <\f[I]ls\f[]|\f[I]edit\f[]|\f[I]add\f[]>
List, edit or add \f[I]user\f[] preferences for a given repository.
.RS
.PP
User preferences are settings which are saved in the user\[aq]s
keyringer folder (\f[C]$HOME/.keyringer/\f[]), and not shared with the
other users.
.PP
Preferences are written using the \f[I]KEY=VALUE\f[] syntax.
All lines starting with the hash (#) character are interpreted as
comments.
.RE
.TP
.B usage
Show keyringer usage information.
.RS
.RE
.TP
.B help
Alias for usage action.
.RS
.RE
.TP
.B recipients <\f[I]ls\f[]|\f[I]edit\f[]> <\f[I]recipients\-file\f[]>
List, create or edit recipients configuration.
.RS
.PP
Recipients files are lists of OpenPGP public key fingerprints which are
used by keyringer when encrypting secrets and associated with email
aliases.
.PP
Keyringer uses a default recipients file, but specifying a custom
\f[I]recipients\-file\f[] pathname will override this default.
.PP
For instance, if a user encrypts a secret to a file in the keyring
repository\[aq]s \f[I]accounting\f[] folder, a \f[I]recipients\-file\f[]
under \f[I]accounting\f[] will be used.
Encrypting a secret into \f[I]accounting/bank\-accounts\f[] will result
in a file \f[C]$KEYRING_FOLDER/keys/accounting/bank\-accounts.asc\f[]
encrypted using the public keys listed in the config
file\f[C]$KEYRING_FOLDER/config/recipients/accounting\f[].
.PP
Each line in a recipients file has entries in the format
\[aq]john\@doe.com XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\[aq], where
\f[I]john\@doe.com\f[] is an alias for the OpenPGP public key whose
fingerprint is \f[I]XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.\f[]
.PP
All lines starting with the hash (#) character are interpreted as
comments.
.PP
Parameters to the \f[I]recipients\f[] action are:
.TP
.B \f[I]ls\f[]
List all existing recipients files.
.RS
.RE
.TP
.B \f[I]edit\f[]
Create or edit a recipients file.
.RS
.PP
Editing happens using the editor specified by the \f[C]$EDITOR\f[]
environment variable.
.PP
The required parameter \f[I]recipients\-file\f[] is interpreted relative
to the \f[C]$KEYRING_FOLDER/config/recipients/\f[] folder.
.RE
.RE
.SH FILES
.PP
$HOME/.keyringer/config : User\[aq]s main configuration file used to map
alias names to keyrings.
.PP
$HOME/.keyringer/\f[I]keyring\f[] : User preferences for the keyringer
aliased \f[I]keyring\f[] keyring.
.PP
$KEYRING_FOLDER/config/options : Custom keyring options which will be
applied for all users that use the keyringer repository.
.SH LIMITATIONS
.PP
Keyringer currently has the following limitations:
.IP "1." 3
Metadata is not encrypted, meaning that an attacker with access to a
keyringer repository can discover all public key IDs used for
encryption, and which secrets are encrypted to which keys.
This can be improved in the future by encrypting the repository
configuration with support for the \f[I]\-\-hidden\-recipient\f[] GnuPG
option and encrypted repository options.
.PP
To mitigate that, it\[aq]s possible to keep the repo just atop of an
encrypted and non\-public place.
.IP "2." 3
History is not rewritten by default when secrets are removed from a
keyringer repository.
After a secret is removed with the \f[I]del\f[] action, it will still be
available in the repository history even after a commit.
This is by design for the following reasons:
.IP \[bu] 2
It\[aq]s the default behavior of the Git content tracker.
Forcing the deletion by default could break the expected behavior and
hence limit the repository\[aq]s backup features, which can be helpful
if someone mistakenly overwrites a secret.
.IP \[bu] 2
History rewriting cannot be considered a security measure against the
unauthorized access to a secret as it doesn\[aq]t automatically update
all working copies of the repository.
.RS 2
.PP
In the case that the secret is a passphrase, the recommended measure
against such attacks is to change the passphrase, making useless the
knowledge of the previous secret.
.PP
Users wishing to edit their repository history should proceed manually
using the \f[I]git\f[] action.
.RE
.IP "3." 3
Keyringer does not protect data which were not encrypted to a keyring,
so be careful when decrypting secrets and writing them to the disk or
other storage media.
.PP
Pay special attention that keyringer outputs data to stdout, which could
be easily spotted by any agent looking directly at you computer screen.
.PP
The xclip action even copies secret data to the X11 clipboard, which can
be accessed by any application running in the user\[aq]s X11 session, so
use this feature carefully.
.SH SEE ALSO
.PP
The \f[I]README\f[] file distributed with Keyringer contains full
documentation.
.PP
The Keyringer source code and all documentation may be downloaded from
<https://keyringer.pw>.
.SH AUTHORS
Silvio Rhatto <rhatto@riseup.net>.