diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/kiki.txt | 459 |
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 @@ | |||
1 | kiki - 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 | |||
10 | Synopsis: | ||
11 | |||
12 | kiki [command] [options] [[command] [options]]... | ||
13 | |||
14 | [TODO: show the most useful commands as examples.] | ||
15 | |||
16 | Description: | ||
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 | |||
53 | Tutorial: | ||
54 | |||
55 | To get started with Kiki, yada yada, [TODO] | ||
56 | |||
57 | Commands: | ||
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 | |||
286 | Key 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 | |||
305 | Options: | ||
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 | |||
323 | Environment: | ||
324 | |||
325 | HOME | ||
326 | GNUPGHOME | ||
327 | GPG_AGENT_INFO | ||
328 | PINENTRY_USER_DATA | ||
329 | |||
330 | Files: | ||
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 | |||
342 | Self-authentication: | ||
343 | |||
344 | [Explain the criteria of self-authentication in precise terms.] | ||
345 | |||
346 | Author: | ||
347 | |||
348 | Kiki by Joe Crayne. This manual by Andrew Cady. | ||
349 | |||
350 | Copyright: | ||
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 | |||
357 | Reporting 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 | |||
377 | kiki [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 | |||
393 | Flags: | ||
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 | |||
416 | Merging: | ||
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 | |||
436 | Output: | ||
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. | ||