forked from square/keywhiz
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.html
328 lines (278 loc) · 16.2 KB
/
index.html
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
<!DOCTYPE html>
<!-- TODO: add this to square.github.io/repos.json, invoke generator.py -->
<html lang="en">
<head>
<meta charset="utf-8">
<title>Keywhiz</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="A file-based secret management and distribution system">
<link href="static/bootstrap-combined.min.css" rel="stylesheet">
<link href="static/app.css" rel="stylesheet">
<link href="static/app-theme.css" rel="stylesheet">
<link href="https://fonts.googleapis.com/css?family=Roboto:400,300italic,100,100italic,300" rel="stylesheet" type="text/css">
<!--[if lt IE 9]><script src="static/html5shiv.min.js"></script><![endif]-->
</head>
<body data-target=".content-nav">
<header>
<div class="container">
<div class="row">
<div class="span5">
<h1>Keywhiz</h1>
</div>
<div class="span7">
<menu>
<ul>
<li><a href="#download" class="menu download">Download <span class="version-tag">Latest</span></a></li>
<li><a href="https://github.com/square/keywhiz" data-title="View GitHub Project" class="menu github"><img src="static/icon-github.png" alt="GitHub"/></a></li>
<li><a href="https://square.github.io/" data-title="Square Open Source Portal" class="menu square"><img src="static/icon-square.png" alt="Square"/></a></li>
</ul>
</menu>
</div>
</div>
</div>
</header>
<section id="subtitle">
<div class="container">
<div class="row">
<div class="span12">
<h2>A system for distributing and managing secrets</h2>
</div>
</div>
</div>
</section>
<section id="body">
<div class="container">
<div class="row">
<div class="span9">
<h3 id="overview">Keywhiz</h3>
<p>Keywhiz is a <strong>system for managing and distributing secrets</strong>. It can
fit well with a service oriented architecture (SOA).
<a href="presentation.html">Here is an overview in presentation format</a></p>
<p>Every organization has services or systems that require secrets. Secrets like:</p>
<ul>
<li>TLS certificates/keys</li>
<li>GPG keys</li>
<li>API tokens</li>
<li>database credentials</li>
</ul>
<p>Common practices include putting secrets in config files next to code or copying
files to servers out-of-band. The former is likely to be leaked and the latter
difficult to track.</p>
<p>Keywhiz makes managing secrets easier and more secure. Keywhiz servers in a cluster
centrally store secrets encrypted in a database. Clients use mutually authenticated
TLS (mTLS) to retrieve secrets they have access to. Authenticated users administer
Keywhiz via CLI. To enable workflows, Keywhiz has automation APIs over mTLS.</p>
<p><em>Keywhiz is reliable and used in production, however some upcoming changes may
break API backward compatibility. See our <a href="#roadmap">roadmap</a>.</em></p>
<h3 id="components">System components</h3>
<h4>Keywhiz Server</h4>
<p>Keywhiz Server provides <a href="apidocs">JSON APIs</a> for accessing and
managing secrets. It is written in Java and based on
<a href="http://dropwizard.io/">Dropwizard</a>.</p>
<h4>KeywhizFs</h4>
<p><a href="https://github.com/square/keywhiz-fs">KeywhizFs</a> is a
<a href="http://fuse.sourceforge.net/">FUSE</a>-based file system, providing secrets
as if they are files in a directory. Transparently, secrets are retrieved from a
Keywhiz Server using mTLS with a client certificate.<p>
<p>Presenting secrets as files makes Keywhiz compatible with nearly all software.
Outside of Keywhiz administration, consumers of secrets only have to know how to
read a file.</p>
<p>KeywhizFs stores all secrets in memory only and never persisted to disk. If KeywhizFs
is unmounted or the server loses power, all secrets will be safely removed from that
server.</p>
<p>To mitigate a Keywhiz Server outage, KeywhizFs maintains a local cache of previously
accessed secrets. Unless the server is rebooted or KeywhizFs unmounted, applications
can happily continue accessing secrets previously accessed.</p>
<h4>Keywhiz CLI</h4>
<p>Keywhiz CLI is a Java program for Keywhiz administration. Clients, secrets, and
groups can be queried, added, removed, or associated with each other.
<a href="#model">Users</a> can authenticate and use the CLI.</p>
<h4>Public Key Infrastructure</h4>
<p>Keywhiz makes heavy use of mTLS and X509 certificates. It can even help distribute
and rotate them for other services! There is the assumption of a PKI system though.
If one does not exist or a PKI is wanted for development consider
<a href="https://github.com/square/certstrap">certstrap</a> for a simple, initial
PKI.</p>
<h3 id="model">Data model</h3>
<p>The data model is composed of clients, secrets, groups, and users.</p>
<p><strong>Clients</strong> are identified by a client certificate. A database entry can
enable/disable access or escalate automation privileges.</p>
<p><strong>Secrets</strong> have a globally unique name and can contain any binary
content. For example, <code>helloworldsrv-database.yml</code>. Secrets are
immutable, but multiple ordered versions can exist at once. Arbitrary key-value
metadata can be added for extensibility.</p>
<p><strong>Groups</strong> are the glue binding clients and secrets. Clients are
assigned membership into groups (e.g. for the service-on-host, service, etc.).
Secrets are also assigned to groups. If a client and secret share any group, the
client will have access to the secret. Groups are not hierarchical and cannot be in
other groups.</p>
<p><strong>Users</strong> are authenticated Keywhiz administrators. Authentication is
customizable with LDAP and bcrypt-hashed passwords currently supported. After
initial authentication subsequent requests require an encrypted cookie from Keywhiz
Server.</p>
<h3 id="setup">Setup</h3>
<p>Source code for the Server and CLI is available in
<a href="https://github.com/square/keywhiz">square/keywhiz</a>. KeywhizFs source is
in <a href="https://github.com/square/keywhiz-fs">square/keywhiz-fs</a>. To checkout
the Keywhiz source code:</p>
<pre class="prettyprint">$ git clone https://github.com/square/keywhiz.git && cd keywhiz</pre>
<h4>Starting the Server</h4>
<p>Keywhiz can store data in MySQL or H2. H2 is the simplest database
for development purpose and all the data is stored in
<code>/tmp/h2_data/keywhizdb_development</code>. For production
systems you should use MySQL.</p>
<p>From the base of the keywhiz repository, build the server:</p>
<pre class="prettyprint">$ mvn package -am -pl server -P h2</pre>
<p>Run any migrations:</p>
<pre class="prettyprint">$ java -jar server/target/keywhiz-server-*-SNAPSHOT-shaded.jar preview-migrate server/src/main/resources/keywhiz-development.yaml
$ java -jar server/target/keywhiz-server-*-SNAPSHOT-shaded.jar migrate server/src/main/resources/keywhiz-development.yaml</pre>
<p>Add an administrative user:</p>
<pre class="prettyprint">$ java -jar server/target/keywhiz-server-*-SNAPSHOT-shaded.jar add-user server/src/main/resources/keywhiz-development.yaml</pre>
<p>Start the server:</p>
<pre class="prettyprint">$ java -jar server/target/keywhiz-server-*-SNAPSHOT-shaded.jar server server/src/main/resources/keywhiz-development.yaml</pre>
<h4>Building the CLI</h4>
<p>From the base of the keywhiz repository:</p>
<pre class="prettyprint">$ mvn package -am -pl cli</pre>
<p>Run the CLI and get a usage statement:</p>
<pre class="prettyprint">$ ./cli/target/keywhiz-cli-*-SNAPSHOT-shaded.jar</pre>
<p>In development, you can use <code>--devTrustStore</code>, e.g.:</p>
<pre class="prettyprint">$ ./cli/target/keywhiz-cli-*-SNAPSHOT-shaded.jar --devTrustStore --user keywhizAdmin list groups</pre>
<p>You may want to alias this command for convenience:</p>
<pre class="prettyprint">$ alias keywhiz.cli="/path/to/keywhiz-cli-*-SNAPSHOT-shaded.jar"</pre>
<h4>Mounting KeywhizFs</h4>
<p>Refer to the KeywhizFs <a href="https://github.com/square/keywhiz-fs/blob/master/README.md">README</a>.</p>
<h3 id="examples">Examples</h3>
<p>More examples are available in the
<a href="https://github.com/square/keywhiz/wiki">Wiki</a>, but here are a few.</p>
<p>In development, you can use <code>--devTrustStore</code> and these examples
assume that you want to use the default <code>keywhizAdmin</code> user.</p>
<p>In production, you will want to create your own users and make sure
that your certificates are properly signed and trusted.</p>
<h4>Adding a Secret</h4>
<h5>Using Keywhiz CLI</h5>
<pre class="prettyprint">$ keywhiz.cli --devTrustStore --user keywhizAdmin login
$ keywhiz.cli add secret --name mySecretName < mySecretFile</pre>
<h5>Using Keywhiz automation API</h5>
<p>
The automation API requires a client certificate and
<code>automationAllowed=true</code> in the clients DB table. For
development purpose, you can use the pre-generated <code>client.p12</code>
keystore:
</p>
<pre class="prettyprint">$ cat request.json
{
"name":"example.keytab",
"description":"example kerberos keytab",
"content":"a2V5dGFiIGNvbnRlbnQ=",
"metadata":{"owner":"root","group":"root","mode":"0400"}
}
$ curl --cert ./server/src/test/resources/clients/client.p12:ponies -H "Content-Type:application/json" -d @request.json https://localhost:4444/automation/secrets/</pre>
<h4>Assigning a Secret to a Group</h4>
<h5>Using Keywhiz CLI</h5>
<pre class="prettyprint">$ keywhiz.cli --devTrustStore --user keywhizAdmin assign secret --name example.keytab --group kerberos</pre>
<h5>Using Keywhiz automation API</h5>
<pre class="prettyprint">$ curl --cert ./server/src/test/resources/clients/client.p12:ponies -X PUT "https://localhost:4444/automation/secrets/$SECRET_ID/groups/$GROUP_ID"</pre>
<h3 id="download">Download</h3>
<p><a href="https://search.maven.org/#search|ga|1|g:com.squareup.keywhiz" class="dl version-href">↓ <span class="version-tag">Latest</span> JARs</a></p>
<p>Source code for Keywhiz and this website is
<a href="https://github.com/square/keywhiz">available on GitHub</a>.</p>
<h3 id="roadmap">Roadmap</h3>
<h4>Upcoming features</h4>
<ul>
<li>Replace KeywhizFS to remove FUSE reliance</li>
<li>Redesigned, more coherent APIs</li>
<li>Database integrity checks</li>
</ul>
<h3 id="contributing">Contributing</h3>
<p>If you would like to contribute code to Keywhiz you can do so through GitHub by
forking the repository and sending a pull request.</p>
<p>When submitting code, please make every effort to follow existing conventions
and style in order to keep the code as readable as possible. Please also make
sure your code compiles and passes tests by running <code>mvn clean verify</code>.
<p>Before your code can be accepted into the project you must also sign the
<a href="https://spreadsheets.google.com/spreadsheet/viewform?formkey=dDViT2xzUHAwRkI3X3k5Z0lQM091OGc6MQ&ndplr=1">Individual Contributor License Agreement (CLA)</a>.
<h3 id="license">License</h3>
<pre>Copyright 2015 Square, Inc.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.</pre>
</div>
<div class="span3">
<div class="content-nav" data-spy="affix" data-offset-top="80">
<ul class="nav nav-tabs nav-stacked primary">
<li><a href="#overview">Overview</a></li>
<li><a href="#components">Components</a></li>
<li><a href="#model">Data model</a></li>
<li><a href="#setup">Setup</a></li>
<li><a href="#examples">Examples</a></li>
<li><a href="#download">Download</a></li>
<li><a href="#roadmap">Roadmap</a></li>
<li><a href="#contributing">Contributing</a></li>
<li><a href="#license">License</a></li>
</ul>
<ul class="nav nav-pills nav-stacked secondary">
<li><a href="https://github.com/square/keywhiz/wiki">Wiki</a></li>
<li><a href="apidocs">API</a></li>
<li><a href="javadocs">Javadocs</a></li>
<li><a href="https://groups.google.com/forum/#!forum/keywhiz-users">Google Group</a></li>
</ul>
</div>
</div>
</div>
<div class="row">
<div class="span12 logo">
<a href="https://squareup.com"><img src="static/logo-square.png" alt="Square, Inc."/></a>
</div>
</div>
</div>
</section>
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
<script src="static/bootstrap.min.js"></script>
<script src="static/jquery.smooth-scroll.min.js"></script>
<script src="static/jquery-maven-artifact.min.js"></script>
<script src="static/prettify.js"></script>
<script type="text/javascript">
$(function() {
// Syntax highlight code blocks.
prettyPrint();
// Spy on scroll position for real-time updating of current section.
$('body').scrollspy();
// Use smooth-scroll for internal links.
$('a').smoothScroll();
// Enable tooltips on the header nav image items.
$('.menu').tooltip({
placement: 'bottom',
trigger: 'hover',
container: 'body',
delay: {
show: 500,
hide: 0
}
});
// Look up the latest version of the library.
$.fn.artifactVersion({
'groupId': 'com.squareup.keywhiz',
'artifactId': 'keywhiz'
}, function(version, url) {
$('.version').text(version);
$('.version-tag').text('v' + version);
$('.version-href').attr('href', url);
});
});
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-40704740-2']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
</body>
</html>