aboutsummaryrefslogtreecommitdiff
path: root/share/man/keyringer.1.mdwn
blob: 7e79b3566fab66cbf7aa2832ad15b9098359d88e (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
% KEYRINGER(1) Keyringer User Manual
% Silvio Rhatto <rhatto@riseup.net>
% Oct 25, 2013

# NAME

keyringer - encrypted and distributed secret sharing software

# SYNOPSIS

keyringer <*keyring*> <*action*> [*options*]...

# DESCRIPTION

Keyringer lets you manage and share secrets using GnuPG and Git in a
distributed fashion.

It has custom commands to encrypt, decrypt and recrypt secrets as well as
create key pairs and supports encryption to multiple recipients and groups of
different recipients to ensure the same repository can be shared with a
workgroup but allowing to keep some secrets available just to subsets of that
group.

Secrets are encrypted using GPG and added to a git tree so later then can be
synced with remote branches.

# ACTIONS

Keyringer has three types of actions:

1. Repository lookup and manipulation actions, which handles repository initialization,
   content tracking and navigation.

2. Secret manipulation actions, which takes care of encrypting, decrypting and other
   read/write operations on secrets.

3. Configuration actions, handling repository metadata.

# REPOSITORY LOOKUP AND MANIPULATION ACTIONS

init <*path*> [*remote*]
:   Initialize a new keyringer repository. If a *remote* URL is specified, keyringer will
    clone an existing repository.

    After initialization, *path* will contain a folder structure for storing secrets
    and metadata (user aka recipients, groups of recipients, etc).

    Also, an entry on `$HOME/.keyringer/config` will be added allowing keyringer to
    find the keyring by it's alias.

git <*action*> <*options*>
:   Git wrapper that operates from the toplevel keyring repository. You can issue any
    *GIT(1)* subcommand with this action that it will be applied into the keyring repository.

ls <*path*>
:   List contents from the toplevel repository *keys* folder or from relative paths
    if *path* is specified. Like the git wrapper, this is a wrapper around the *LS(1)*
    command.

# SECRET MANIPULATION ACTIONS

All secret manipulation actions operates upon a *secret* which is the pathname
of an encrypted file relative to keyring with optional `.asc` extension.

If the `.asc` extension is ommited, keyringer will add it in the end of the
pathname.

No spaces are allowed in the secret name.

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.

append <*secret*>
:   Append contents into a secret by decrypting the secret, appending lines read
    from the standard input and encrypting again.

append-batch <*secret*>
:   Append contents into a secret, batch mode.

decrypt <*secret*>
:   Decrypts a secret into standard output.

del <*secret*>
:   Removes a secret using git. After deleting a secret a git commit and push is still
    needed to update remote repositories.

    Please note that this command **does not remove the secret from the git history.**
    To completely remove a file from a keyring, you should also rewrite the git
    history by yourself.

edit <*secret*>
:   Edit a secret by temporarily decrypting it, opening the decrypted copy into the 
    text editor defined by the *$EDITOR* environment variable and then recrypting it
    again.

encrypt [*file*] <*secret*>
:   Encrypts content from standard input or *file* into *secret* pathname. No spaces
    are supported in the *file* name.

encrypt-batch <*secret*>
:   Encrypt content, batch mode.

genpair <*ssh*|*gpg*|*ssl*|*ssl-self*> [*options*]
:   Wrapper to generete encryption keypairs, useful for automated key deployment.

open <*secret*>
:   Decrypt a secret into a temporary folder and opening it using xdg-open which
    then tries to figure out the file type and calling the associated application.

    After the application exits, keyringer encrypts the temporary decrypted file
    again into the secret file.

recrypt <*secret*>
:   Recrypts a secret by decrypting it and recrypting again. Useful when users are added
    into recipient configuration. If no *secret* is given, all secrets in the repository
    are re-encrypted.

# CONFIGURATION ACTIONS

commands
:   List available actions, useful for shell completion and syntax check.

options <*ls*|*edit*|*add*>
:   List, edit or add miscelaneous *repository* options.

    Repository options are specific configurations for the keyring which are
    saved into the repository, making it available for all users with access to the
    repository and hence is a *global* configuration stanza for a given keyring.

    Options are written using the *KEY=VALUE* syntax. All lines starting with the
    hash (#) character are interpreted as comments.

preferences <*ls*|*edit*|*add*>
:   List, edit or add *user* preferences for a given repository.

    User preferences are specific configurations for the keyring which are
    saved into the user's keyringer folder (`$HOME/.keyringer/`) hence not
    shared with the other users.

    Preferences are written using the *KEY=VALUE* syntax. All lines starting with the
    hash (#) character are interpreted as comments.

usage
:   Show keyringer usage information.

recipients <*ls*|*edit*> <*recipient-file*>
:   List, create or edit recipient configuration.

    Recipient files are lists of OpenPGP public key fingerprints which are used
    by keyringer when encrypting secrets and associated with email aliases.

    Keyringer uses a default recipient file and supports custom *recipient-files* which
    overrides the default recipient file according to it's matching pathname.

    For instance, a the *recipient-file* called *accounting* will be used
    wherever a user encrypts a secret to a file residing from the *accounting*
    folder in the keyring repository. In that case, encrypting a secret into
    *accounting/bank-accounts* will result in a file
    `$KEYRING_FOLDER/keys/accounting/bank-accounts.asc` encrypted using the
    public keys listed in `$KEYRING_FOLDER/config/recipients/accounting` config
    file.

    Each line in a recipients file has entries in the form of
    'john@doe.com XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', where *john@doe.com*
    is an alias for the GPG public key whose fingerprint is
    *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.*

    All lines starting with the hash (#) character are interpreted as comments.

    Parameters to the *recipients* action are:

      *ls*
      :   List all existing recipient files.

      *edit*
      :   Create or edit a recipient-file.

          Editing happens using the editor specified by the `$EDITOR`
          environment variable.

          The required parameter *recipient-file* is taken relativelly
          from the `$KEYRING_FOLDER/config/recipients/` folder.

# FILES

$HOME/.keyringer/config
:  User's main configuration file used to map alias names to keyrings.

$HOME/.keyringer/*keyring*
:  User preferences for the keyringer aliased *keyring* keyring.

$KEYRING_FOLDER/config/options
:  Custom keyring options which will be applied for all users that use
   the keyringer repository.

# LIMITATIONS

Keyringer currently has the following limitations:

* Metadata is not encrypted, meaning that an attacker with access to a keyringer
  repository knows all public key IDs are 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 *--hidden-recipient* GnuPG
  option.

* History is not rewritten by default when secrets are removed from a keyringer
  repository. After a secret is removed with *del* action, it will still be
  available in the repository history even after a commit. This is by design
  due to the following reasons:

  1. It's the default behavior of the Git content tracker. Forcing the
     deletion by default could break the expected behavior and hence limit
     the repository's backup features, which can be helpful is someone
     mistakenly overwrites a secret.

  2. History rewriting cannot be considered a security measure against the
     unauthorized access to a secret as it doesn't automatically update all
     working copies of the repository.

     In the case that the secret is a passphrase, the recommended measure
     against such attack is to change the passphrase, making useless the
     knowledge of the previous secret.

     Users wishing to edit their repository history should proceed manually
     using the *git* action.

# SEE ALSO

The *README* file distributed with Keyringer contains full documentation.

The Keyringer source code and all documentation may be downloaded from
<https://keyringer.pw>.