summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/kiki.txt459
1 files changed, 459 insertions, 0 deletions
diff --git a/doc/kiki.txt b/doc/kiki.txt
new file mode 100644
index 0000000..15ae53b
--- /dev/null
+++ b/doc/kiki.txt
@@ -0,0 +1,459 @@
1kiki - a bridge between keys
2
3 Kiki turns your OpenGPG key into a single sign-on (SSO) identity
4 for all cryptographically-authenticated services.
5
6 It also enables you to accept such identities for your own services.
7
8 Fuck Google, fuck Facebook, and fuck Verisign. [TODO: enlarge list]
9
10Synopsis:
11
12 kiki [command] [options] [[command] [options]]...
13
14 [TODO: show the most useful commands as examples.]
15
16Description:
17
18 Kiki creates a cryptographic chain of trust, _from_ a foundation of
19 the OpenPGP web of trust, _to_ all other key types.
20
21 The following key types are currently supported:
22
23 * ssh (host and client)
24 * ipsec
25 * DNSKEY (DNSSEC)
26 * x509 (TLS/SSL, client and server authentication; HTTP/SMTP)
27 * Tor hidden service (.onion)
28 * I2P hidden service (.b32.i2p)
29 * GNUNet hidden service (.gnu, .zkey)
30 * Bitcoin address (and other cryptocoins)
31 * OpenPGP subkeys (merge subkeys from multiple keyrings into one)
32
33 Kiki allows such keys to be taken from an existing system and imported
34 into an OpenPGP key so that they can be shared easily.
35
36 In the other direction, Kiki will determine the OpenPGP UID(s)
37 cryptographically chained to any public key in any format, so that
38 services with cryptographic authentication can be easily modified
39 to accept OpenPGP identities by calling Kiki. Kiki can also export
40 public keys into convenient formats, ready for use by services that do
41 not call Kiki.
42
43 In addition to supporting the traditional OpenPGP web of trust,
44 Kiki recognizes the possibility of _self-authenticating_ OpenPGP
45 signatures. These are signatures which assert ownership of UIDs which
46 are provably owned by the signer. For example, an OpenPGP key which
47 claims the UID <root@hiotuxliwisbp6mi.onion> is self-authenticating
48 if the private key corresponding to 'hiotuxliwisbp6mi' has signed the
49 UID. Such OpenPGP keys do not need to be validated by an external
50 signature. They can be validated using their own internal data, and
51 trusted immediately.
52
53Tutorial:
54
55 To get started with Kiki, yada yada, [TODO]
56
57Commands:
58
59 If no command is given, the default command is 'show-working-key'.
60
61 For options common to multiple commands, see _Options_.
62
63 import-key [options] [file]
64
65 options: --autosign --sign-key --authentic-only
66
67 Import an OpenPGP key into the default keyring, optionally signing
68 it with the default key. If no file is specified, the key is read
69 from stdin.
70
71 With --authentic-only, import the key only if it is
72 self-authenticating or can be authenticated by already-trusted keys.
73 With --autosign, import the key either way, but only sign it if it
74 is self-authenticating (as if 'autosign' were run).
75
76 For a detailed description of the requirements for
77 self-authenticated keys, see section _Self-authentication_.
78
79 import-subkey [options] [public key filename | private key filename] [...]
80
81 options: [--usage=<type>] [--set-notation <name=value>] [--no-usage] [key format]
82
83 Import keys from an external file, or from stdin, into the keyring,
84 as subkeys of the working key. The keys will be signed by the
85 master key, and cross-certification will be performed (i.e., the
86 keys will be used to sign the master key).
87
88 Without a private key, cross-certification is impossible, and a
89 confirmation will be required, which can be overridden with --yes.
90
91 The --usage option can be used to specify the 'usage@' notation,
92 which is used by Kiki and Samizdat to determine what functions the
93 key should have outside of PGP. If neither --usage nor --no-usage
94 is specified, the usage will be inferred from the filename and/or
95 key format.
96
97 When the input is a file, the internal timestamp of the subkey will
98 be set to match its mtime. The subkey timestamp is not altered if
99 the subkey already exists.
100
101 export-subkey [options] <uid | master keyprint | subkey keyprint> [output path]
102
103 options: [--public[=file]] [--private[=file]] [--usage=string] [key format]
104
105 Export the explicitly specified subkey, or the newest subkey
106 indicated by the usage option, in the explicitly specified format,
107 or the format indicated by the usage option. If no output file
108 specification is supplied, stdout is used, but this may require
109 --public or --private, depending on the key format. (Not all key
110 formats allow public and private keys to be appended in a single
111 file in a reasonable way.)
112
113 If a uid or master key is specified, then the usage option is
114 mandatory; it is required to select which subkey to export. Only
115 one of --public or --private can be specified unless both have
116 arguments.
117
118 If --public or --private is specified without arguments, then the
119 public or private key is written to the specified output path. If
120 neither is specified, then the output path is where the private key
121 will be written. In that case, the public key will be also written,
122 to a path determined by that of the private key, by a mechanism
123 specified by the key format.
124
125 When --public or --private have arguments, these are the locations
126 where the public and private keys are written. A path of '-' can be
127 specified for output to stdout.
128
129 When the output is a file, the mtime on the file will be set to
130 match OpenPGP's internal subkey timestamp.
131
132 For more information about key formats, see _Key formats_.
133
134 [TODO: generic 'authorize' command?]
135
136 ssh-authorize [options] <uid | master keyprint | subkey keyprint>
137
138 options: --user=user
139
140 Authorize ssh access for the specified user by appending the
141 appropriate key to $HOME/.ssh/authorized_keys unless it already
142 exists there.
143
144 Without --user, access to the current user account is granted.
145 Otherwise, root is required, and access to the specified user
146 account is granted.
147
148 A comment will be written indicating the UID prepended with
149 '[samizdat]'.
150
151 ssh-unauthorize [uid]
152
153 options: --user=user --authorized_keys=<file>
154
155 Without a uid argument, revoked keys, expired keys, and expired
156 subkeys, will have their corresponding ssh keys removed from
157 $HOME/.ssh/authorized_keys, or the specified file. Additionally,
158 auth lines tagged [samizdat] for keys that are missing from the
159 keyring will be removed.
160
161 With a uid argument, all subkeys of the specified UID will be
162 removed.
163
164 Without --user, access to the current user account is removed.
165 Otherwise, root is required, and access to the specified user
166 account is removed.
167
168 autosign [key] [...]
169
170 This command will operate on all keys if none are specified.
171
172 The working key is used to sign the specified keys if they can be
173 self-authenticated. This tells GnuPG to trust such keys, which it
174 would not otherwise do.
175
176 For a detailed description of the requirements for
177 self-authenticated keys, see section _Self-authentication_.
178
179 show-working-key
180
181 Show all available information about the default working key.
182
183 Equivalent to 'show --all' with no uid argument.
184
185 show [options] [uid or keyprint]
186
187 options: [--all | key format]
188
189 With '--all' or without a key format option, display a listing
190 showing all keys and UIDs associated with a given UID, indicating
191 trust-chain relationships between them.
192
193 With a key format option, output a machine-useable version of the
194 key type specified. If a UID or master keyprint is specified, then
195 the 'usage@' annotation will be used to decide which subkey to
196 display. If a subkey fingerprint is specified, then that key will
197 be output in the specified format. If multiple keys are available
198 with a matching 'usage@' annotation, the most recent key is chosen.
199
200 Untrusted or unrequested data may be output via stderr. Only
201 trusted and requested data is output via stdout.
202
203 For more information about key formats, see _Key formats_.
204
205 list <uid | master keyprint | subkey keyprint> <key format>
206
207 List all subkeys of the specified master key, or of the master key
208 of the specified subkey, tagged with the usage specified by the key
209 format.
210
211 For more information about key formats, see _Key formats_.
212
213 verify [options] [file or network resource]
214
215 options: [key format | --challenge] --uid --short-uid --keyprint --datetime
216
217 Output the verified identity of the signer of the data. If no file
218 is specified, then the data is read from stdin.
219
220 A key format can be specified to indicate the format of the data.
221 Otherwise, an attempt is made to infer the key format from the data
222 itself, in which case it must not contain extraneous information.
223 For network resources, it can always be inferred.
224
225 Supported network resources are:
226
227 ssh://server[:port]
228 https://[SNI domain@]server[:port]
229 tls://[SNI domain@]server[:port]
230 dnskey://[domain][@dns server:port]
231
232 For DNSKEY network resources, all DNSKEY responses must validate;
233 but ZSK's might be validated indirectly, through RRSIG records made
234 with validated ZSK's.
235
236 Identities are output on stdout, with one identity per line. Stderr
237 may contain additional information. Special characters in UIDs
238 (such as newline) are escaped.
239
240 By default, or with --uid, show the full UID. With --short-uid,
241 show only the email part of the UID, without brackets. With
242 --keyprint, show the keyprint of the master key.
243
244 With both --keyprint and one of --uid or --short-uid, show the
245 keyprint, followed by a space, followed by the UID in the specified
246 form.
247
248 With '--challenge', a cryptographic challenge response is verified.
249 In this case, the stdout output is not necessarily an OpenPGP UID or
250 keyprint, but is specific to the challenge type.
251
252 Kiki will exit with failure if verification fails.
253
254 For more information about key formats, see _Key formats_.
255
256 challenge [options] <challenge type> <uid>
257
258 options: --language=[lang] --short --no-instructions --shell --validity-period=[interval]
259 challenge types: --bitcoin --tor --i2p --pgp
260
261 Output to stdout a human-readable challenge which can be completed
262 only with the appropriate private key. Creating the challenge may
263 require generating a PGP signature, in which case the working key
264 will be used. The response to the challenge can be verified with
265 the 'verify --challenge' command.
266
267 With --validity-period, the challenge will expire after the
268 specified interval. The interval is specified in DNS zone file
269 format. The current system time is used to calculate an absolute
270 expiration time in the future.
271
272 Unless --no-instructions is specified, the challenge will contain
273 detailed instructions intended for unsophisticated recipients. If
274 --short is specified, the instructions will be less detailed. If
275 --shell is specified, the "instructions" take the form of a Bourne
276 shell script.
277
278 response [file]
279
280 A challenge generated from 'challenge' is read from the specified
281 file, or via stdin, and an identity-proving response is generated
282 automatically and output to stdout.
283
284 help
285
286Key formats:
287
288 [TODO: determine, and document, the precise relationship between key
289 formats and usage notations.]
290
291 --pem --ssh --wallet --dnskey --ipsec --pgp
292
293 --wallet
294
295 Bitcoin wallet input format. These cryptocoins are also supported:
296
297 [...]
298
299 --ssh
300
301 OpenSSH key format. For public keys, this is the format used in
302 authorized_keys. The "comment" section, which is output via stderr,
303 contains a UID with special characters (such as newline) escaped.
304
305Options:
306
307 These options are common to multiple commands. Options specific to
308 commands are documented with the commands.
309
310 --homedir
311 --passphrase-fd
312 --keyring
313 --no-default-keyring
314 --primary-keyring
315 --default-key
316 --trustdb-name
317 --verbose
318 --quiet
319 --no-tty
320 --yes
321 --no
322
323Environment:
324
325 HOME
326 GNUPGHOME
327 GPG_AGENT_INFO
328 PINENTRY_USER_DATA
329
330Files:
331
332 $HOME/.gnupg
333
334 $GNUPGHOME/{pub,sec}ring.gpg
335
336 /etc/ssh/ssh_host*_key
337
338 /etc/ipsec.d/private/*.pem
339
340 etc.
341
342Self-authentication:
343
344 [Explain the criteria of self-authentication in precise terms.]
345
346Author:
347
348 Kiki by Joe Crayne. This manual by Andrew Cady.
349
350Copyright:
351
352 (C) 2014 Joe Crayne. All Rights Reserved.
353
354 When released, Kiki will be released under a free software license.
355 This version is a pre-release.
356
357Reporting Bugs:
358
359 Bugs? Impossible.
360
361 "From key to shining key..."
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377kiki [OPTIONS]
378
379 kiki merges a set of keyring files into a combined database and then
380 uses the database to update the files so that they have the most complete
381 information.
382
383 The files pubring.gpg and subring.gpg in the directory specified by the
384 --homedir option are implicitly included in the keyring set.
385
386 kiki can also import or export secret subkeys by using the --keypairs option.
387
388 Subkeys that are imported with kiki are given an annotation "usage@" which
389 indicates what the key is for. This tag can be used as a SPEC to select a
390 particular key. Master keys may be specified by using fingerprints or by
391 specifying a substring of an associated UID.
392
393Flags:
394 --homedir DIR
395 Where to find the the files secring.gpg and pubring.gpg. The
396 default location is taken from the environment variable
397 GNUPGHOME.
398
399 --passphrase-fd N
400 Read passphrase from the given file descriptor.
401
402 --import Add master keys to pubring.gpg. Without this option, only UID
403 and subkey data is updated.
404
405 --import-if-authentic
406 Add signed master keys to pubring.gpg. Like --import except that
407 only keys with signatures from the working key (--show-wk) are
408 imported.
409
410 --autosign Sign all cross-certified tor-style UIDs.
411 A tor-style UID is of the form:
412 Anonymous <root@HOSTNAME.onion>
413 It is considered cross certified if there exists a cross-certified
414 'tor' subkey corresponding to the address HOSTNAME.onion.
415
416Merging:
417 --keyrings FILE FILE...
418 Provide keyring files other than the implicit secring.gpg and
419 pubring.gpg in the --homedir. This option is implicit unless
420 --keypairs or --wallets is used.
421
422 --wallets FILE FILE...
423 Provide wallet files with secret crypto-coin keys in Wallet
424 Import Format. The keys will be treated as subkeys of your
425 current working key (the one shown by --show-wk).
426
427 --keypairs KEYSPEC KEYSPEC...
428 Each KEYSPEC specifies that a key should match the content and
429 timestamp of an external PKCS #1 private RSA key file.
430
431 KEYSPEC ::= SPEC=FILE{CMD}
432
433 If neither SPEC or FILE match any keys, then the CMD will be
434 executed in order to create the FILE.
435
436Output:
437 --show-wk Show fingerprints for the working key (which will be used to
438 make signatures) and all its subkeys and UID.
439
440 --show-key SPEC
441 Show fingerprints for the specified key and all its subkeys
442 and UID.
443
444 --show-all Show fingerprints and UIDs and usage tags for all known keys.
445
446 --show-whose-key
447 Shows the fingerprint and UIDs of the key that owns the one that
448 is input on stdin in ssh-rsa format.
449
450 --show-pem SPEC
451 Outputs the PKCS #8 public key corresponding to SPEC.
452
453 --show-ssh SPEC
454 Outputs the ssh-rsa blob for the specified public key.
455
456 --show-wip SPEC
457 Outputs the secret crypto-coin key in Wallet Input Format.
458
459 --help Shows this help screen.