pub/, progs/: Implement Bernstein's X25519 key-exchange algorithm.
[catacomb] / progs / key.1
... / ...
CommitLineData
1.\" -*-nroff-*-
2.ie t \{\
3. if \n(.g \{\
4. fam P
5. \}
6. ds ss \s8\u
7. ds se \d\s0
8. ds us \s8\d
9. ds ue \u\s0
10. ds *b \(*b
11.\}
12.el \{\
13. ds ss ^
14. ds se
15. ds us _
16. ds ue
17. ds *b \fIbeta\fP
18.\}
19.de VS
20.sp 1
21.RS
22.nf
23.ft B
24..
25.de VE
26.ft R
27.fi
28.RE
29.sp 1
30..
31.TH key 1 "5 June 1999" "Straylight/Edgeware" "Catacomb cryptographic library"
32.SH NAME
33key \- simple key management system
34.SH SYNOPSIS
35.B key
36.RB [ \-k
37.IR keyring ]
38.I command
39.PP
40where
41.I command
42is one of:
43.PP
44.B help
45.RI [ command ...]
46.br
47.B show
48.RI [ item ...]
49.br
50.B add
51.RB [ \-lqrLKS ]
52.RB [ \-a
53.IR alg ]
54.RB [ \-b | \-B
55.IR bits ]
56.RB [ \-p
57.IR param ]
58.RB [ \-R
59.IR tag ]
60.br
61\h'8n'
62.RB [ \-A
63.IR seed-alg ]
64.RB [ \-s
65.IR seed ]
66.RB [ \-n
67.IR bits ]
68.br
69\h'8n'
70.RB [ \-e
71.IR expire ]
72.RB [ \-t
73.IR tag ]
74.RB [ \-c
75.IR comment ]
76.RB [ \-C
77.IR curve ]
78.br
79\h'8n'
80.I type
81.IR attr ...
82.br
83.B expire
84.IR tag ...
85.br
86.B delete
87.IR tag ...
88.br
89.B tag
90.I tag
91.RI [ new-tag ]
92.br
93.B comment
94.I tag
95.RI [ comment ]
96.br
97.B setattr
98.I tag
99.IR attr ...
100.br
101.B getattr
102.I tag
103.I attr
104.br
105.B lock
106.I qtag
107.br
108.B unlock
109.I qtag
110.br
111.B list
112.RB [ \-uqv ]
113.RB [ \-f
114.IR filter ]
115.RI [ tag ...]
116.br
117.B fingerprint
118.RB [ \-f
119.IR filter ]
120.RB [ \-p
121.IR style ]
122.RB [ \-a
123.IR hash ]
124.RI [ tag ...]
125.br
126.B verify
127.RB [ \-f
128.IR filter ]
129.RB [ \-p
130.IR style ]
131.RB [ \-a
132.IR hash ]
133.I tag
134.I fingerprint
135.br
136.B tidy
137.br
138.B extract
139.RB [ \-f
140.IR filter ]
141.I file
142.RI [ tag ...]
143.br
144.B merge
145.I file
146.SH DESCRIPTION
147The
148.B key
149command performs useful operations on Catacomb keyring files. It
150provides a number of subcommands, by which the various operations may be
151carried out.
152.SS "Global options"
153Before the command name,
154.I "global options"
155may be given. The following global options are supported:
156.TP
157.BR "\-h, \-\-help " [ \fIcommand ...]
158Writes a brief summary of
159.BR key 's
160various options to standard output, and
161returns a successful exit status. With command names, gives help on
162those commands.
163.TP
164.B "\-v, \-\-version"
165Writes the program's version number to standard output, and returns a
166successful exit status.
167.TP
168.B "\-u, \-\-usage"
169Writes a very terse command line summary to standard output, and returns
170a successful exit status.
171.TP
172.BI "\-k, \-\-keyring " file
173Names the keyring file which
174.B key
175is to process. The default keyring, used if this option doesn't specify
176one, is the file named
177.B keyring
178in the current directory. The keyring must be stored in a regular file:
179pipes, sockets, devices etc. are not allowed.
180The
181.B key
182program attempts to lock the keyring before accessing it, using
183.BR fcntl (2)
184locking. It will however time out after a short while (10 seconds) and
185report a failure.
186.SS Concepts
187In addition to the actual key data itself, a Catacomb key has a number
188of other pieces of information attached to it:
189.TP
190.B "keyid"
191Every key has a 32-bit identifying number, written in hexadecimal.
192Keyids are not actually related to the key contents: they're generated
193randomly. Applications use keyids to refer to specific keys; users are
194probably better off with tags and types. A
195.I deleted
196key cannot be looked up by keyid.
197.TP
198.B "tag"
199A key's tag is a unique string which can be used by users and
200applications to identify the key. Tag strings may not contain spaces,
201colons or dots. A
202.I deleted
203key cannot be looked up by tag. Whenever a tag name is wanted, a hex
204keyid or key type string can be given instead.
205.TP
206.B "type"
207A key's type string describes what the key may be used for. The type
208string is arbitrary, except that it may not contain whitespace
209characters, dots or colons. Applications use key types to obtain an
210arbitrary but suitable key for some purpose. An
211.I expired
212key cannot be looked up by type, but may be looked up by keyid or tag.
213.TP
214.B "key encoding"
215There are a number of different ways in which keys can be represented,
216according to the uses to which the key will be put. Most symmetric
217algorithms use
218.I binary
219keys. Keys used with number-theoretic systems (like most common
220public-key systems) use
221.I "multiprecision integer"
222keys. Elliptic curve systems use
223.I "curve point"
224keys, which are either a pair of integers representing field elements,
225or a `point at infinity'. Algorithms which require several key
226constituents (again, like most public-key systems) use
227.I structured
228keys, which consist of a collection of named parts. It's possible to
229store an
230.I "ASCII string"
231as a key, though this is usually done as a component of a structured
232key. Finally, keys (including structured keys) can be encrypted.
233.TP
234.B "filter"
235Keys and key components may be selected by a filter expression, a
236sequence of flag names separated by commas. Flags are:
237.BR binary ,
238.BR integer ,
239.BR struct ,
240.BR ec ,
241.BR string ,
242or
243.B encrypt
244(describing the key encoding);
245.BR symmetric ,
246.BR private ,
247.BR public ,
248or
249.B shared
250(describing the category of key);
251.B burn
252and its negation
253.B \-burn
254(whether the key should be erased from memory after use); and
255.B secret
256and its negation
257.B \-secret
258(whether the key is safe to divulge).
259.TP
260.B "qualified tag"
261A key component may be identified by the key's tag (or keyid, or type).
262Subcomponents of structured keys are identified by following the tag by
263a dot and the name of the subcomponent.
264.TP
265.B "expiry time"
266Most keys expire after a certain amount of time. Once a key has
267expired, it will no longer be chosen as a result of a lookup by key
268type. However, it is not deleted until its deletion time is also
269reached.
270.TP
271.B "deletion time"
272A key's deletion time is the latest expiry time of any of the objects
273which require that key. For example, a key used for authenticating
274cryptographic cookies should have its deletion time set to the longest
275expiry time of any of the cookies it can authenticate. Once a key's
276deletion time is passed, it can no longer be referred to by
277applications, and will be removed from the keyring next time it's
278written to disk.
279.TP
280.B "comment"
281A key may be given a comment when it's created. The comment is for the
282benefit of users, and isn't interpreted by applications at all.
283(Hopefully.)
284.TP
285.B "attributes"
286A key has zero or more name/value pairs. The names and values are
287arbitrary strings, except that they may not contain null bytes. Some
288attributes may have meaning for particular applications or key types;
289others may be assigned global meanings in future.
290.SH "COMMAND REFERENCE"
291.SS help
292The
293.B help
294command behaves exactly as the
295.B \-\-help
296option. With no arguments, it shows an overview of
297.BR key 's
298options; with arguments, it describes the named subcommands.
299.SS show
300The
301.B show
302command prints various lists of tokens understood by
303.BR key .
304With no arguments, it prints all of the lists; with arguments, it prints
305just the named lists, in order. The recognized lists can be enumerated
306using the
307.VS
308key show list
309.VE
310command. The lists are as follows.
311.TP
312.B list
313The lists which can be enumerated by the
314.B show
315command.
316.TP
317.B hash
318The hash functions which can be used with the
319.B fingerprint
320and
321.B verify
322commands.
323.TP
324.B ec
325The built-in elliptic curves which can be used with the
326.B add \-a ec
327command.
328.TP
329.B dh
330The built-in Diffie\(enHellman groups which can be used with the
331.B add \-a dh
332command.
333.TP
334.B keygen
335The key-generation algorithms which are acceptable to the
336.B \-a
337option of the
338.B add
339command.
340.TP
341.B seed
342The pseudorandom generators which are acceptable to the
343.B \-s
344option of the
345.B add
346command.
347.TP
348.B fpres
349Fingerprint presentation styles, as used by the
350.B fingerprint
351and
352.B verify
353commands.
354.SS add
355The
356.B add
357command creates a new key and adds it to the keyring. The command
358accepts the following options:
359.TP
360.BI "\-a, \-\-algorithm " alg
361Selects a key generation algorithm. The default algorithm is
362.BR binary ;
363the different algorithms are described below. The command
364.B key show keygen
365lists the recognized key-generation algorithms.
366.TP
367.BI "\-b, \-\-bits " bits
368The length of the key to generate, in bits. The default, if this option
369is not supplied, depends on the key-generation algorithm.
370.TP
371.BI "\-B, \-\-qbits " bits
372The length of the subsidiary key or parameter, in bits. Not all
373key-generation algorithms have a subsidiary key size.
374.TP
375.BI "\-p, \-\-parameters " tag
376Selects a key containing parameter values to copy.
377A new key also inherits attributes from its parameter key.
378.TP
379.BI "\-A, \-\-seedalg " seed-alg
380Use the deterministic random number generator algorithm
381.I seed-alg
382to generate the key. Use
383.I before
384the
385.B \-s
386or
387.B \-n
388options; without one of these,
389.B \-A
390has no effect. The default algorithm is
391.BR rmd160-mgf .
392The command
393.B key show seed
394shows a list of recognized seeding algorithms. The seeding algorithm
395used to generate a key is recorded as the key's
396.B seedalg
397attribute.
398.TP
399.BI "\-s, \-\-seed " seed
400Generate the key deterministically using the given
401.IR seed ,
402which should be a Base64-encoded binary string. This is mainly useful
403for parameters keys (types
404.BR dsa-param
405and
406.BR dh-param ),
407to demonstrate that a set of parameters has been generated in an honest
408fashion. The
409.B dsarand
410generation algorithm can be used to generate
411.B dsa-param
412keys as required by FIPS186. The requested seed is recorded,
413Base64-encoded, as the new key's
414.B seed
415attribute.
416.TP
417.BI "\-n, \-\-newseed " bits
418Generate a new seed, with the given length in
419.IR bits .
420The generated seed is recorded, Base64-encoded, as the new key's
421.B seed
422attribute.
423.TP
424.BI "\-e, \-\-expire " expire
425The expiry date for the generated key. This may be the string
426.RB ` forever '
427if the key should never expire automatically, or any date acceptable to
428the
429.BR getdate (3)
430library function. Briefly,
431.B getdate
432understands absolute dates such as
433.RB ` 1999-08-02 '
434or
435.RB ` "August 2nd, 1999" ',
436and (perhaps more usefully) relative dates such as
437.RB ` "+2 weeks" '.
438The default is to allow a 2 week expiry, which isn't useful.
439.TP
440.BI "\-c, \-\-comment " comment
441Sets a comment for the key. The default is not to attach a comment.
442.TP
443.BI "\-C, \-\-curve " curve-spec
444Use the elliptic curve described by
445.I curve-spec
446when generating elliptic curve parameters.
447.TP
448.BI "\-t, \-\-tag " tag
449Selects a tag string for the key. The default is not to set a tag. It
450is an error to select a tag which already exists.
451.TP
452.BI "\-r, \-\-retag"
453If a
454.B \-t
455option is given, remove this tag from any key which already has it.
456.TP
457.BI "\-R, \-\-rand-id " tag
458Selects the key to use for the random number generator. Catacomb's
459random number generator can be
460.IR keyed ,
461so that, even if the inputs to the generator are compromised, knowledge
462of the key is also necessary to be able to predict the output. By
463default, the latest-expiring key with type
464.B catacomb-rand
465is used, if present; if not, no key is used.
466.TP
467.BI "\-l, \-\-lock"
468Requests that the secret parts of the newly-generated key be encrypted
469using a passphrase.
470.TP
471.BI "\-q, \-\-quiet"
472Suppresses the progress indication which is usually generated while
473time-consuming key generation tasks are being performed.
474.TP
475.BI "\-L, \-\-lim-lee"
476When generating Diffie\(enHellman parameters, generate a Lim\(enLee
477prime rather than a random (or safe) prime. See the details on
478Diffie\(enHellman key generation below.
479.TP
480.BI "\-K, \-\-kcdsa"
481When generating Diffie\(enHellman parameters, generate a KCDSA-style
482Lim\(enLee prime rather than a random (or safe) prime. See the details
483on Diffie\(enHellman key generation below.
484.TP
485.BI "\-S, \-\-subgroup"
486When generating Diffie\(enHellman parameters with a Lim\(enLee prime,
487choose a generator of a prime-order subgroup rather than a subgroup of
488order
489.RI ( p "\ \-\ 1)/2."
490.PP
491The key's type is given by the required
492.I type
493argument. Following the type are zero or more attributes, which are
494attached to the key in the same way as for the
495.B setattr
496command.
497.PP
498The key-generation algorithms supported are as follows:
499.TP
500.B "binary"
501Generates a plain binary key of the requested length. If the requested
502key length is not a multiple of eight, the high-order bits of the first
503octet of the key are zeroed. The default key length is 128 bits.
504.TP
505.B "des"
506Generates a DES key, with parity bits. The key length must be 56, 112
507or 168; the default is 56. The low-order bit of each octet is ignored by
508the DES algorithm; it is used to give each octet odd parity.
509.TP
510.B "rsa"
511Generates a public/private key pair for use with the RSA algorithm.
512.IP
513The key components are
514.I p
515and
516.IR q ,
517a pair of prime numbers;
518.IR n ,
519the product of
520.I p
521and
522.IR q ;
523.IR e ,
524the public exponent;
525.IR d ,
526the private exponent, chosen such that
527.IR ed \~\(==\~1
528(mod
529.RI lcm( p "\~\-\~1, " q \~\-\~1));
530and some other values useful for optimizing private-key operations:
531.IR q "\*(ss\-1\*(se mod " p ,
532.IR d "\~mod " p \~\-\~1,
533and
534.IR d "\~mod " q \~\-\~1.
535The values
536.I n
537and
538.I e
539constitute the public key; the rest must be kept secret. The key size
540requested by the
541.B \-b
542option determines the size of the modulus
543.IR n ;
544the default is 1024 bits.
545.IP
546The key generation algorithm chooses
547.I p
548and
549.I q
550to be
551.I strong
552primes: both
553.IR p \~\-\~1
554and
555.IR p \~+\~1
556have large prime factors \(en call them
557.I r
558and
559.I s
560respectively \(en and
561.IR r \~\-\~1
562also has a large prime factor;
563.I q
564has similar properties.
565.IP
566The modulus
567.I n
568cannot be sensibly used as a shared parameter, since knowledge of
569corrssponding public and private exponents is sufficient to be able to
570factor the modulus and recover other users' private keys.
571.TP
572.B "dh-param"
573Generates parameters for use with the Diffie\(enHellman key exchange
574protocol, and many related systems, such as ElGamal encryption and
575signatures, and even DSA. (The separate DSA algorithm uses the
576generator described in FIPS186-1.)
577.IP
578The Diffie\(enHellman parameters are a prime modulus
579.I p
580and a generator
581.I g
582of a subgroup of
583.BR Z / \c
584.IB p Z
585of order
586.IR q .
587The
588.B \-b
589option controls the size of the modulus
590.IR p ;
591the default size is 1024 bits.
592.IP
593If no
594.I q
595size is selected using the
596.B \-B
597option and the Lim\(enLee prime options are disabled, then
598.I p
599is chosen to be a `safe' prime (i.e.,
600.IR p "\~= 2" q \~+\~1,
601with
602.I q
603prime). Finding safe primes takes a very long time. In this case, the
604value of
605.I g
606is fixed as 4.
607.IP
608If a size is chosen for
609.I q
610and Lim\(enLee primes are not selected then the prime
611.I q
612is generated and
613.I p
614is chosen so that
615.IR p \~\-\~1
616is a multiple of
617.IR q .
618.IP
619If the
620.B \-L
621option was given, Lim\(enLee primes are selected: the parameters are
622chosen such that
623.IR p "\~= 2\~" q \*(us0\*(ue
624.IR q \*(us1\*(ue
625.IR q \*(us2\*(ue\~...\~+\~1,
626where the
627.IR q \*(us i \*(ue
628are primes at least as large as the setting given by the
629.B \-B
630option (or 256 bits, if no setting was given).
631.IP
632If the
633.B \-K
634option was given, KCDSA-style Lim\(enLee primes are selected: the
635parameters are chosen such that
636.IR p "\~= 2" qv \~+\~1,
637where
638.IR p,
639.I q
640and
641.I v
642are primes.
643.IP
644If the
645.B \-S
646or
647.B \-K
648options were given, the generator
649.I g
650is chosen to generate the subgroup of order
651.IR q \*(us0\*(ue;
652otherwise,
653.I g
654will generate the group of order
655.RI ( p "\~\-\~1)/2\~= " q "\*(us0\*(ue " q \*(us1\*(ue
656.IR q \*(us2\*(ue\~...
657.IP
658Finally, the
659.B \-C
660option can be given, in which case the parameters are taken directly
661from the provided group specification, which may either be the the name
662of one of the built-in groups (say
663.B "key show dh"
664for a list) or a triple
665.RI ( p ,\~ q ,\~ g ).
666separated by commas. No random generation is done in this case: the
667given parameters are simply stored.
668.TP
669.B "dh"
670Generates a public/private key pair for use with offline Diffie\(enHellman,
671ElGamal, DSA or similar discrete-logarithm-based systems. It selects a
672private key
673.IR x \~<\~ q ,
674and computes the public key
675.IR y "\~= " g \*(ss x "\*(se mod\~" p .
676.TP
677.B "dsa-param"
678Generates parameters for the DSA algorithm. DSA parameters are also
679suitable for use with Diffie\(enHellman and ElGamal system.
680.IP
681The main difference between DSA and Diffie\(enHellman parameter generation
682is thatthe DSA parameter generation
683algorithm creates a
684.I seed
685from which the parameters are derived, and, assuming that the SHA-1 hash
686function is strong, it's not feasible to construct a seed from which
687deliberately weak parameters are derived. The algorithm used is the one
688described in the DSA standard, FIPS\ 186, extended only to allow
689sequential search for a prime
690.I q
691and to allow arbitrary parameter sizes. The seed is stored,
692Base64-encoded, as the value of the attribute
693.BR seed .
694.IP
695The default lengths for
696.I p
697and
698.I q
699are 768 and 160 bits respectively, since the DSA standard specifies that
700.I q
701be 160 bits, and the choice of 768 bits for
702.I p
703gives commensurate security.
704.TP
705.B "dsa"
706Generates a public/private key pair for DSA. As for Diffie\(enHellman
707keys, it selects a
708private key
709.IR x \~<\~ q ,
710and computes the public key
711.IR y "\~= " g \*(ss x "\*(se mod\~" p .
712.TP
713.B "bbs"
714Generates a public/private key pair for the Blum-Blum-Shub random-number
715generator, and the Blum-Goldwasser semantically-secure public-key
716encryption system.
717.IP
718The key components are prime numbers
719.I p
720and
721.IR q ,
722both congruent to 3 (mod\~4), and their product
723.IR n .
724The public key is simply the modulus
725.IR n ;
726the factors
727.I p
728and
729.I q
730are the private key.
731.IP
732The key-generation algorithm ensures that the two primes
733.I p
734and
735.I q
736are
737.I strong
738(see the discussion of strong primes above, in the section on RSA keys),
739and that
740.RI ( p \~\-\~1)/2
741and
742.RI ( q \~\-\~1)/2
743are relatively prime, giving a maximum possible period length.
744.IP
745The key size requested by the
746.B \-b
747option determines the length of the modulus
748.IR n ;
749the default length is 1024 bits.
750.TP
751.B "ec-param"
752Store an elliptic curve specification. If no explicit
753.I curve-spec
754is given (the
755.RB ` \-C '
756option) then a curve is chosen whose order is about the size given by the
757.RB ` \-b '
758option (default is 256 bits).
759.IP
760A
761.I curve-spec
762can be given explicitly (in which case
763.RB ` \-b '
764is ignored). It can either be the name of a built-in curve (say
765.B "key show ec"
766for a list of curve names) or a full specification. The curve is
767checked for correctness and security according to the SEC1
768specification: failed checks cause a warning to be issued to standard
769error (though the program continues anyway). The check can be
770suppressed using the
771.RB ` \-q '
772option.
773.IP
774A curve specification consists of the following elements optionally
775separated by whitespace: a
776.IR "field type" ,
777which is one of
778.BR "prime" ,
779.BR "niceprime" ,
780.BR "binpoly" ,
781.or
782.BR "binnorm" ;
783an optional
784.RB ` : ';
785the field modulus
786.IR p ;
787if the field type is
788.B binnorm
789then an optional
790.RB ` , '
791and the representation of the normal element \*(*b; an optional
792.RB ` ; ';
793a
794.IR "curve type" ,
795which is one of
796.BR "prime" ,
797.BR "primeproj" ,
798.BR "bin" ,
799and
800.BR "binproj"
801(the `proj' types currently have much better performance);
802an optional
803.RB ` : ';
804the two field-element parameters
805.I a
806and
807.IR b
808which define the elliptic curve
809.IR E ,
810separated by an optional
811.RB ` , ';
812an optional
813.RB ` ; ';
814the
815.IR x -
816and
817.IR y -coordinates
818of the generator point
819.IR G ,
820separated by an optional
821.RB ` , ';
822an optional
823.RB ` : ';
824the order
825.I r
826of the group generated by
827.IR G ;
828an optional
829.RB ` * ';
830and the
831.I cofactor
832.I h
833=
834.RI # E / r .
835.TP
836.B "ec"
837Generate a private scalar and a corresponding public point on an
838elliptic curve. See
839.B ec-param
840above for how to specify elliptic curve parameter sets. The scalar
841.I x
842is chosen unformly between 0 and the curve order
843.IR r ;
844the public point is then
845.I x
846\(mu
847.IR G .
848.TP
849.B x25519
850Generate a private scalar and a corresponding public point on the
851(Montgomery-form) Curve25519 elliptic curve.
852The scalar is simply a random 256-bit string;
853the public key is the
854.IR x -coordinate
855of the corresponding point.
856.TP
857.B empty
858Generate an empty key, with trivial contents.
859This is useful as a `parameters' key,
860carrying attributes to be applied to other keys
861if they don't require more detailed parameters.
862.SS "expire"
863Forces keys to immediately expire. An expired key is not chosen when a
864program requests a key by its type. The keys to expire are listed by
865their
866.IR tag s.
867.SS "delete"
868Deletes keys immediately. The keys to delete are listed by their
869.IR tag s.
870Be careful when deleting keys. It might be a better idea
871to expire keys rather than deleting them.
872.SS "tag"
873Sets, deletes or changes the tag attached to a key. The first tag or
874keyid names the key to be modified; the second, if present specifies the
875new tag to be set. If no second argument is given, the existing tag, if
876any, is removed and no new tag is set. It is an error to set a tag
877which already exists on another key, unless you give the
878.B \-r
879option, which removes the tag first.
880.SS "setattr"
881Attaches attributes to a key. The key to which the attributes should be
882attached is given by its
883.IR tag .
884Each attribute has the form
885.IB name = value\fR.
886An attribute can be deleted by assigning it an empty value. Although
887the keyring file format is capable of representing an attribute with an
888empty value as distinct from a nonexistant attribute, this interface
889does not allow empty attributes to be set.
890.SS "getattr"
891Fetches a single attribute of a key. The key whose attribute is to be
892read is given by its
893.IR tag .
894The attribute's value is written to standard output followed by a
895newline. If the key or attribute is absent, a message is written to
896standard error and the program exits nonzero.
897.SS "comment"
898Sets, deletes or changes the comment attached to a key. The first
899argument is a key tag or keyid which names the key to be modified; the
900second, if present, is the new comment. If no second argument is given,
901the existing comment, if any, is removed, and no new comment is set.
902.SS "lock"
903Locks a key or key component using a passphrase. If the key is already
904locked, the existing passphrase is requested, and a new passphrase is
905set.
906.SS "unlock"
907Unlocks a passphrase-locked key or key component. If the key is not
908locked, an error is reported.
909.SS "list"
910Lists the keys in the keyring. A couple of options are supported:
911.TP
912.B "\-v, \-\-verbose"
913Increases the amount of information displayed for each key. Repeat for
914a greater effect.
915.TP
916.B "\-q, \-\-quiet"
917Decreases the amount of information displayed for each key. Each use
918cancels a
919.RB ` \-v '
920option.
921.TP
922.B "\-u, \-\-utc"
923Display key expiry times as UTC rather than using the local time zone.
924.TP
925.BI "\-f, \-\-filter " filter
926Specifies a filter. Only keys and key components which match the filter
927are listed.
928.PP
929By default, a single line of output is generated for each, showing
930keyids, types, expiry and deletion dates, and comments. Additional
931.RB ` \-v '
932options show more information, such as the exact time of day for expiry
933and deletion, key attributes, and a dump of the actual key data. If the
934verbosity level is sufficiently high, passphrases are requested to
935decrypt locked keys. Make sure nobody is looking over your shoulder
936when you do this!
937.SS "fingerprint"
938Reports a fingerprint (secure hash) on components of requested keys.
939The following options are supported:
940.TP
941.BI "\-f, \-\-filter " filter
942Specifies a filter. Only keys and key components which match the filter
943are fingerprinted. The default is to only fingerprint nonsecret
944components.
945.TP
946.BI "\-p, \-\-presentation " style
947Write fingerprints in the given
948.IR style .
949See below for a list of presentation styles.
950.TP
951.BI "\-a, \-\-algorithm " hash
952Names the hashing algorithm. Run
953.B key show hash
954for a list of hashing algorithms. The default is
955.BR rmd160 .
956.PP
957The keys to be fingerprinted are named by their tags or keyids given as
958command line arguments. If no key tags are given, all keys which match
959the filter are fingerprinted. See
960.BR keyring (5)
961for a description of how key fingerprints are computed.
962.PP
963The fingerprint may be shown in the following styles.
964.TP
965.B hex
966Lowercase hexadecimal, with groups of eight digits separated by hyphens
967(`\-'). This is the default presentation style. (On input, colons are
968also permitted as separators.)
969.TP
970.B base32
971Lowercase Base32 encoding, without `=' padding, with groups of six
972digits separated by colons (`:'). (On input, padding characters are
973ignored.)
974.SS "verify"
975Check a key's fingerprint against a reference copy. The following
976options are supported:
977.TP
978.BI "\-f, \-\-filter " filter
979Specifies a filter. Only key components which match the filter are
980hashed. The default is to only fingerprint nonsecret components. An
981error is reported if no part of the key matches.
982.TP
983.BI "\-p, \-\-presentation " style
984Expect the
985.I fingerprint
986to be in the given presentation
987.IR style .
988These match the styles produced by the
989.B fingerprint
990command described above.
991.TP
992.BI "\-a, \-\-algorithm " hash
993Names the hashing algorithm. Run
994.B key show hash
995for a list of hashing algorithms. The default is
996.BR rmd160 .
997.PP
998The fingerprint should be provided in the form printed by the
999.B fingerprint
1000command, using the same presentation
1001.IR style .
1002A little flexibility is permitted: separators may be placed anywhere (or
1003not at all) and are ignored; whitespace is permitted and ignored; and
1004case is ignored in presentation styles which don't make use of both
1005upper- and lower-case characters.
1006.SS "tidy"
1007Simply reads the keyring from file and writes it back again. This has
1008the effect of removing any deleted keys from the file.
1009.SS "extract"
1010Writes a selection of keys to a file. An option is supported:
1011.TP
1012.BI "\-f, \-\-filter " filter
1013Specifies a filter. Only keys and key components which match the filter
1014are written.
1015.PP
1016Keys extracted are written to the file named by the first argument,
1017which may be
1018.RB ` \- '
1019to designate standard output. The keys to extract are listed by their
1020tags; if no tags are given, all keys which match the filter are
1021extracted. The output is a valid keyring file.
1022.SS "merge"
1023Merges the keys from the named
1024.IR file ,
1025which may be
1026.RB ` \- '
1027to designate standard input, with the keyring. Keys already in the
1028keyring are not overwritten: you must explicitly remove them first if
1029you want them to be replaced during the merge.
1030.SH "SEE ALSO"
1031.BR keyring (5).
1032.SH AUTHOR
1033Mark Wooding, <mdw@distorted.org.uk>