aboutsummaryrefslogtreecommitdiff
path: root/README
blob: f6be24ddfb5ed0d5e6956417a83e2e1199f348dd (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
Keyringer
=========

Keyringer lets you manage and share secrets using GPG and git in a distributed
fashion. It has custom commands to encrypt, decrypt, recrypt, create key pairs,
etc.

Requirements
------------

Keyringer needs:

  - Bash - http://tiswww.case.edu/php/chet/bash/bashtop.html
  - Git - http://git-scm.com
  - GNU Privacy Guard - http://gnupg.org
  - OpenSSL - http://www.openssl.org
  - Grep, awk, tail, cut, sed and other GNU tools

Installation
------------

Just clone

    git clone git://git.sarava.org/keyringer.git

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

Creating a keyringer repository
-------------------------------

The first step will would like to take is to setup a keyring.  Keyringer suport
management of multiple isolated keyrings.  To start a new keyring (or register
an existing one at your config file), type

    keyringer <keyring> init <path> [remote]

This will 

  1. Add an entry at $HOME/.keyringer 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. Call all
other keyring actions using this alias.

If there is an existing remote keyring 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
    keyringer <keyring> recipients ls

Encrypting a key
----------------

    keyringer <keyring> encrypt <file>

Decrypting a key (only to stdout)
---------------------------------

    keyringer <keyring> decrypt <file>

Re-encrypting a key
-------------------

    keyringer <keyring> recrypt <file>

Editing a key
-------------

To edit a key, use

    keyringer <keyring> edit <file>

Use this option with caution as it keeps temporary unencrypted data into keyringer
temp folder and at your $EDITOR temp files.

Listing keys
------------

    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

Managing puppet node keys
-------------------------

Keyringer is able to manage node keys for puppet nodes. First add the puppet
main and key folders into your keyring configuration:

    keyringer <keyring> preferences add PUPPET=/path/to/puppet/config
    keyringer <keyring> preferences add PUPPET_KEYS=/path/to/puppet/keys

Then you just need to issue the following command every time you have to create
keys for new nodes:

    keyringer <keyring> newkeys puppet

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

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

Notes: Using with GNU Privacy Guard
-----------------------------------

Exporting public keys:

    gpg --armor --export <keyid>

Exporting private keys (take care):

    gpg --armor --export-secret-keys

TODO
----

There are lots of things that can be enhanced, like:

  - Enhanced documentation.

  - Interface with ssss where the scripts automatically splits passphrases
    into ssss tokens and encrypt those to different groups of users.

  - Hidden recipient support (including recipients file).

  - Rewrite using an object-oriented programming language?

Development
-----------

Developers needed! :)