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
423
424
425
426
427
428
429
|
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>Class: KeyRing</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta http-equiv="Content-Script-Type" content="text/javascript" />
<link rel="stylesheet" href=".././rdoc-style.css" type="text/css" media="screen" />
<script type="text/javascript">
// <![CDATA[
function popupCode( url ) {
window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
}
function toggleCode( id ) {
if ( document.getElementById )
elem = document.getElementById( id );
else if ( document.all )
elem = eval( "document.all." + id );
else
return false;
elemStyle = elem.style;
if ( elemStyle.display != "block" ) {
elemStyle.display = "block"
} else {
elemStyle.display = "none"
}
return true;
}
// Make codeblocks hidden by default
document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
// ]]>
</script>
</head>
<body>
<div id="classHeader">
<table class="header-table">
<tr class="top-aligned-row">
<td><strong>Class</strong></td>
<td class="class-name-in-header">KeyRing</td>
</tr>
<tr class="top-aligned-row">
<td><strong>In:</strong></td>
<td>
<a href="../files/keyring_rb.html">
keyring.rb
</a>
<br />
</td>
</tr>
<tr class="top-aligned-row">
<td><strong>Parent:</strong></td>
<td>
Object
</td>
</tr>
</table>
</div>
<!-- banner header -->
<div id="bodyContent">
<div id="contextContent">
<div id="description">
<h1>keyring - manage encrypted storage for authentication information</h1>
<p>
The keyring library stores authentication information such as username and
passwords in a keyring directory in encrypted form.
</p>
<p>
The keyring directory is ~/.keyring by default.
</p>
<p>
gpg is used for the encryption.
</p>
<p>
You needs your public and secret key for the encryption. (Use "gpg
—gen-key" if you don‘t have one yet.)
</p>
<h2>How to specify your authentication information in the keyring.</h2>
<p>
The keyring library uses ASCII armored gpg encrypted file to store
passwords and related data.
</p>
<p>
Comment field is used to select the file.
</p>
<p>
~/.keyring/foobar.asc :
</p>
<pre>
-----BEGIN PGP MESSAGE-----
Version: GnuPG v1.4.5 (GNU/Linux)
Comment: non-encrypted-prefix-of-the-strings
... encrypted-sequence-of-strings ...
-----END PGP MESSAGE-----
</pre>
<h3>Example 1. TypeKey</h3>
<p>
The following example stores a username and password for TypeKey. <<a
href="http://www.sixapart.jp/typekey">www.sixapart.jp/typekey</a>/>
</p>
<pre>
% mkdir ~/.keyring
% cd ~/.keyring
% echo TypeKey typekey-username typekey-password |
gpg --comment TypeKey -e -a --default-recipient-self > typekey.asc
</pre>
<p>
It creates a file ~/.keyring/typekey.asc as follows.
</p>
<pre>
-----BEGIN PGP MESSAGE-----
Version: GnuPG v1.4.5 (GNU/Linux)
Comment: TypeKey
... "TypeKey typekey-username typekey-password\n" in encrypted form ...
-----END PGP MESSAGE-----
</pre>
<p>
Now, <a
href="KeyRing.html#M000010">KeyRing.with_authinfo</a>("TypeKey")
{|username, password| … } can be used to retrieve the
typekey-username and typekey-password. It use gpg to decrypt the file. So
gpg may ask you a passphrase of your key.
</p>
<h3>Example 2. HTTP Basic Authentication</h3>
<pre>
% echo http://www.example.org basic "realm" username password |
gpg --comment 'http://www.example.org basic "realm" username' -e -a --default-recipient-self > example-org.asc
</pre>
<p>
It creates a file ~/.keyring/example-org.asc as follows.
</p>
<pre>
-----BEGIN PGP MESSAGE-----
Version: GnuPG v1.4.5 (GNU/Linux)
Comment: http://www.example.org basic "realm" username
... "http://www.example.org basic "realm" username password\n" in encrypted form ...
-----END PGP MESSAGE-----
</pre>
<p>
Now, <a href="KeyRing.html#M000010">KeyRing.with_authinfo</a> can be used
to lookup username and password.
</p>
<pre>
KeyRing.with_authinfo("http://www.example.org", "basic", "realm", "username") {|password| ... }
</pre>
<p>
It is possible to lookup username AND password as follows.
</p>
<pre>
KeyRing.with_authinfo("http://www.example.org", "basic", "realm") {|username, password| ... }
</pre>
<p>
It is also possible to lookup realm and authentication scheme.
</p>
<pre>
KeyRing.with_authinfo("http://www.example.org", "basic") {|realm, username, password| ... }
KeyRing.with_authinfo("http://www.example.org") {|auth_scheme, realm, username, password| ... }
</pre>
<h2>Keyring Directory Layout and File Format</h2>
<p>
The keyring directory is ~/.keyring.
</p>
<p>
~/.keyring may have any number of authentication information file. The file
must be named with ".asc" suffix.
</p>
<p>
The keyring library searches ~/.keyring/*.asc for authentication
information. The filename is not important.
</p>
<p>
The authentication information file should be ASCII armored gpg encrypted
file as follows.
</p>
<p>
~/.keyring/foobar.asc :
</p>
<pre>
-----BEGIN PGP MESSAGE-----
Version: GnuPG v1.4.5 (GNU/Linux)
Comment: non-encrypted-prefix
... encrypted-sequence-of-strings ...
-----END PGP MESSAGE-----
</pre>
<p>
The file should contain Comment field and encrypted contents.
</p>
<p>
The encrypted contents should be sequence of strings separated by white
spaces. (The syntax of the strings is described later.)
</p>
<pre>
Example: A B C D
</pre>
<p>
The Comment field should contain prefix of the sequence of strings.
</p>
<pre>
Example: A B C
Example: A B
Example: A
</pre>
<p>
Each string in the Comment field can be a hexadecimal SHA256 hash prepended
with "sha256:" prefix.
</p>
<pre>
Example: sha256:559aead08264d5795d3909718cdd05abd49572e84fe55590eef31a88a08fdffd B
Example: A sha256:df7e70e5021544f4834bbee64a9e3789febc4be81470df629cad6ddb03320a5c
Example: sha256:559aead08264d5795d3909718cdd05abd49572e84fe55590eef31a88a08fdffd sha256:df7e70e5021544f4834bbee64a9e3789febc4be81470df629cad6ddb03320a5c
</pre>
<p>
A string contained in the Comment field and encrypted contents must be one
of following forms.
</p>
<ul>
<li>A string not containing a white space and beginning with a digit or
alphabet. /[0-9A-Za-z][!-~]*/
</li>
<li>A string quoted by double quotes "…". The string content
may contain printable ASCII character including space and escape sequences
\, \" and \xHH. /"((?:[
!#-\[\]-~]|\["\]|\x[0-9a-fA-F][0-9a-fA-F])*)"/
</li>
<li>A white space is one of space, tab, newline, carriage return, form feed.
/\s/
</li>
</ul>
<h2>Convention of Authentication Information</h2>
<p>
Although the keyring library itself doesn‘t define the semantics of
the sequence of strings, it is useful to standardize the usage of the
strings.
</p>
<p>
So the keyring library provides convenience methods to make protection
domains for TypeKey and HTTP Authentication. They returns a protection
domain appropriate for an argument of <a
href="KeyRing.html#M000010">KeyRing.with_authinfo</a>.
</p>
<ul>
<li><a href="KeyRing.html#M000011">KeyRing.typekey_protection_domain</a>
<p>
For TypeKey authentication, protection domain is ["TypeKey"]. The
authentication information, username and password, can be stored as
follows.
</p>
<pre>
% echo TypeKey typekey-username typekey-password |
gpg --comment TypeKey -e -a --default-recipient-self > typekey.asc
</pre>
</li>
<li><a href="KeyRing.html#M000012">KeyRing.http_protection_domain</a>(uri,
scheme, realm)
<p>
For HTTP authentication, protection domain is [canonical-root-URL, scheme,
realm]. In Basic authentication, "basic" is used for the scheme.
</p>
<p>
The Basic authentication information, username and password, can be stored
as follows.
</p>
<pre>
% echo 'canonical-root-url basic "realm" username password' |
gpg --comment 'canonical-root-URL basic "realm"' -e -a --default-recipient-self > service.asc
</pre>
</li>
</ul>
<h3>Method</h3>
<ul>
<li><a href="KeyRing.html#M000010">KeyRing.with_authinfo(protection_domain)</a>
{|authentication_informaion| … }
</li>
<li><a href="KeyRing.html#M000011">KeyRing.typekey_protection_domain</a>
</li>
<li><a href="KeyRing.html#M000012">KeyRing.http_protection_domain</a>(uri,
scheme, realm)
</li>
</ul>
</div>
</div>
<div id="method-list">
<h3 class="section-bar">Methods</h3>
<div class="name-list">
<a href="#M000012">http_protection_domain</a>
<a href="#M000011">typekey_protection_domain</a>
<a href="#M000010">with_authinfo</a>
</div>
</div>
</div>
<!-- if includes -->
<div id="section">
<div id="class-list">
<h3 class="section-bar">Classes and Modules</h3>
Class <a href="KeyRing/AuthInfoNotFound.html" class="link">KeyRing::AuthInfoNotFound</a><br />
</div>
<!-- if method_list -->
<div id="methods">
<h3 class="section-bar">Public Class methods</h3>
<div id="method-M000012" class="method-detail">
<a name="M000012"></a>
<div class="method-heading">
<a href="KeyRing.src/M000012.html" target="Code" class="method-signature"
onclick="popupCode('KeyRing.src/M000012.html');return false;">
<span class="method-name">http_protection_domain</span><span class="method-args">(uri, scheme, realm)</span>
</a>
</div>
<div class="method-description">
<p>
<a href="KeyRing.html#M000012">KeyRing.http_protection_domain</a> returns
[canonical-root-URL-of-given-uri, scheme, realm]
</p>
</div>
</div>
<div id="method-M000011" class="method-detail">
<a name="M000011"></a>
<div class="method-heading">
<a href="KeyRing.src/M000011.html" target="Code" class="method-signature"
onclick="popupCode('KeyRing.src/M000011.html');return false;">
<span class="method-name">typekey_protection_domain</span><span class="method-args">()</span>
</a>
</div>
<div class="method-description">
<p>
<a href="KeyRing.html#M000011">KeyRing.typekey_protection_domain</a>
returns ["TypeKey"].
</p>
</div>
</div>
<div id="method-M000010" class="method-detail">
<a name="M000010"></a>
<div class="method-heading">
<a href="KeyRing.src/M000010.html" target="Code" class="method-signature"
onclick="popupCode('KeyRing.src/M000010.html');return false;">
<span class="method-name">with_authinfo</span><span class="method-args">(protection_domain) {|authentication_information| ...}</span>
</a>
</div>
<div class="method-description">
<p>
<a href="KeyRing.html#M000010">KeyRing.with_authinfo</a> takes one or more
strings as the argument. protection_domain can be a string or an array of
strings.
</p>
<p>
protection_domain is compared to the Comment fields in ~/.keyring/*.asc. If
a matched Comment field is found, the corresponding file is decrypted to
obtain the authentication information represented as a sequence of strings
using gpg.
</p>
<p>
<a href="KeyRing.html#M000010">KeyRing.with_authinfo</a> yields the
sequence of strings excluded with beginning words given with
protection_domain.
</p>
</div>
</div>
</div>
</div>
<div id="validator-badges">
<p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
</div>
</body>
</html>
|
