X-Git-Url: https://git.distorted.org.uk/u/mdw/catacomb/blobdiff_plain/2b2d07ca33cf57a82d416ee0aafa5842bf24e509..052b36d05a622a93733b735acce2de865b14627b:/key.1

diff --git a/key.1 b/key.1
index 95cba9b..2f47eff 100644
--- a/key.1
+++ b/key.1
@@ -1,4 +1,12 @@
 .\" -*-nroff-*-
+.ie t \{\
+.  ds ss \s8\u
+.  ds se \d\s0
+.\}
+.el \{\
+.  ds ss ^
+.  ds se
+.\}
 .TH key 1 "5 June 1999" Catacomb
 .SH NAME
 key \- simple key management system
@@ -13,33 +21,68 @@ where
 is one of:
 .PP
 .B add
-.RB [ \-b
+.RB [ \-lq ]
+.RB [ \-a
+.IR alg ]
+.RB [ \-b | \-B
 .IR bits ]
+.RB [ \-p
+.IR param ]
+.RB [ \-r
+.IR tag ]
+.br
+\h'8n'
 .RB [ \-e
 .IR expire ]
+.RB [ \-t
+.IR tag ]
 .RB [ \-c
 .IR comment ]
 .I type
 .IR attr ...
 .br
 .B expire
-.IR keyid ...
+.IR tag ...
 .br
 .B delete
-.IR keyid ...
+.IR tag ...
+.br
+.B tag
+.I tag
+.RI [ new-tag ]
+.br
+.B comment
+.I tag
+.RI [ comment ]
 .br
 .B setattr
-.I keyid
+.I tag
 .IR attr ...
 .br
+.B lock
+.I qtag
+.br
+.B unlock
+.I qtag
+.br
 .B list
-.RB [ \-quv ]
+.RB [ \-uqv ]
+.RB [ \-f
+.IR filter ]
+.RI [ tag ...]
+.br
+.B fingerprint
+.RB [ \-f
+.IR filter ]
+.RI [ tag ...]
 .br
 .B tidy
 .br
 .B extract
+.RB [ \-f
+.IR filter ]
 .I file
-.IR keyid ...
+.RI [ tag ...]
 .br
 .B merge
 .I file
@@ -86,21 +129,72 @@ report a failure.
 In addition to the actual key data itself, a Catacomb key has a number
 of other pieces of information attached to it:
 .TP
-.B keyid
-Every key has a 32-bit identifying number, written in hexadecimal.  The
-keyid is derived from the actual key contents (although knowledge of a
-key's keyid doesn't help one to guess the key itself).  Applications use
-keyids to refer to specific keys.  A
+.B "keyid"
+Every key has a 32-bit identifying number, written in hexadecimal.
+Keyids are not actually related to the key contents: they're generated
+randomly.  Applications use keyids to refer to specific keys; users are
+probably better off with tags and types.  A
 .I deleted
 key cannot be looked up by keyid.
 .TP
-.B type
+.B "tag"
+A key's tag is a unique string which can be used by users and
+applications to identify the key.  Tag strings may not contain spaces,
+colons or dots.  A
+.I deleted
+key cannot be looked up by tag.  Whenever a tag name is wanted, a hex
+keyid or key type string can be given instead.
+.TP
+.B "type"
 A key's type string describes what the key may be used for.  The type
 string is arbitrary, except that it may not contain whitespace
-characters.  Applications use key types to obtain an arbitrary but
-suitable key for some purpose.  An
+characters, dots or colons.  Applications use key types to obtain an
+arbitrary but suitable key for some purpose.  An
 .I expired
-key cannot be looked up by type, but may be looked up by keyid.
+key cannot be looked up by type, but may be looked up by keyid or tag.
+.TP
+.B "key encoding"
+There are a number of different ways in which keys can be represented,
+according to the uses to which the key will be put.  Most symmetric
+algorithms use
+.I binary
+keys.  Keys used with number-theoretic systems (like most common
+public-key systems) use
+.I "multiprecision integer"
+keys.  Algorithms which require several key constituents (again, like
+most public-key systems) use
+.I structured
+keys, which consist of a collection of named parts.  Finally, keys
+(including structured keys) can be encrypted.
+.TP
+.B "filter"
+Keys and key components may be selected by a filter expression, a
+sequence of flag names separated by commas.  Flags are:
+.BR binary ,
+.BR integer ,
+.B struct
+or
+.B encrypt
+(describing the key encoding);
+.BR symmetric ,
+.BR private ,
+.B public
+or
+.B shared
+(describing the category of key);
+.B burn
+and its negation
+.B \-burn
+(whether the key should be erased from memory after use); and
+.B secret
+and its negation
+.B \-secret
+(whether the key is safe to divulge).
+.TP
+.B "qualified tag"
+A key component may be identified by the key's tag (or keyid, or type).
+Subcomponents of structured keys are identified by following the tag by
+a dot and the name of the subcomponent.
 .TP
 .B "expiry time"
 Most keys expire after a certain amount of time.  Once a key has
@@ -112,19 +206,17 @@ reached.
 A key's deletion time is the latest expiry time of any of the objects
 which require that key.  For example, a key used for authenticating
 cryptographic cookies should have its deletion time set to the longest
-expiry time of any of the cookies it can authenticate.  A key is never
-deleted until it has also expired.  Once a key has expired
-.I and
-its deletion time is passed, it can no longer be referred to by
+expiry time of any of the cookies it can authenticate.  Once a key's
+deletion time is passed, it can no longer be referred to by
 applications, and will be removed from the keyring next time it's
 written to disk.
 .TP
-.B comment
+.B "comment"
 A key may be given a comment when it's created.  The comment is for the
 benefit of users, and isn't interpreted by applications at all.
 (Hopefully.)
 .TP
-.B attributes
+.B "attributes"
 A key as zero or more name/value pairs.  The names and values are
 arbitrary strings, except they may not contain null bytes.  Some
 attributes may have meaning for particular applications or key types;
@@ -136,10 +228,22 @@ The
 command creates a new key and adds it to the keyring.  The command
 accepts the following options:
 .TP
+.BI "\-a, \-\-algorithm " alg
+Selects a key generation algorithm.  The default algorithm is
+.BR binary ;
+the different algorithms are described below.
+.TP
 .BI "\-b, \-\-bits " bits
 The length of the key to generate, in bits.  The default, if this option
-is not supplied, is 128 bits.  The bit length must be nonzero, and must
-be a multiple of 8.
+is not supplied, depends on the key-generation algorithm.
+.TP
+.BI "\-B, \-\-qbits " bits
+The length of the subsidiary key or parameter, in bits.  Not all
+key-generation algorithms have a subsidiary key size.
+.TP
+.BI "\-p, \-\-parameters " tag
+Selects a key containing parameter values to copy.  Not all
+key-generation algorithms allow the use of shared parameters.
 .TP
 .BI "\-e, \-\-expire " expire
 The expiry date for the generated key.  This may be the string
@@ -159,6 +263,28 @@ The default is to allow a 2 week expiry, which isn't useful.
 .TP
 .BI "\-c, \-\-comment " comment
 Sets a comment for the key.  The default is not to attach a comment.
+.TP
+.BI "\-t, \-\-tag " tag
+Selects a tag string for the key.  The default is not to set a tag.  It
+is an error to select a tag which already exists.
+.TP
+.BI "\-r, \-\-rand-id " tag
+Selects the key to use for the random number generator.  Catacomb's
+random number generator can be
+.IR keyed ,
+so that, even if the inputs to the generator are compromised, knowledge
+of the key is also necessary to be able to predict the output.  By
+default, the latest-expiring key with type
+.B catacomb-rand
+is used, if present; if not, no key is used.
+.TP
+.BI "\-l, \-\-lock"
+Requests that the secret parts of the newly-generated key be encrypted
+using a passphrase.
+.TP
+.BI "\-q, \-\-quiet"
+Suppresses the progress indication which is usually generated while
+time-consuming key generation tasks are being performed.
 .PP
 The key's type is given by the required
 .I type
@@ -167,36 +293,236 @@ attached to the key in the same way as for the
 .B setattr
 command.
 .PP
-The
-.B key
-program only generates random bitstrings, which are suitable for most
-symmetric algorithms but not for public key cryptography.  Generating
-keys for more exotic algorithms is a feature which will be added later.
-The keys are generated using the Catacomb random number generator, using
-the
-.B rand_goodbits
-function.  The Catacomb generator is believed to be strong.
-.SS expire
+The key-generation algorithms supported are as follows:
+.TP
+.B "binary"
+Generates a plain binary key of the requested length.  If the requested
+key length is not a multiple of eight, the high-order bits of the first
+octet of the key are zeroed.  The default key length is 128 bits.
+.TP
+.B "des"
+Generates a DES key, with parity bits.  The key length must be 56, 112
+or 168; the default is 56.  The low-order bit of each octet is ignored by
+the DES algorithm; it is used to give each octet odd parity.
+.TP
+.B "rsa"
+Generates a public/private key pair for use with the RSA algorithm.
+.IP
+The key components are
+.I p
+and
+.IR q ,
+a pair of prime numbers;
+.IR n ,
+the product of
+.I p
+and
+.IR q ;
+.IR e ,
+the public exponent;
+.IR d ,
+the private exponent, chosen such that
+.IR ed \ \(==\ 1
+(mod
+.RI ( p \ \-\ 1)( q \ \-\ 1));
+and some other values useful for optimizing private-key operations:
+.IR q \*(ss\-1\*(se\ mod\  p ,
+.IR d \ mod\  p \ \-\ 1,
+and
+.IR d \ mod\  q \ \-\ 1.
+The values
+.I n
+and
+.I e
+constitute the public key; the rest must be kept secret.  The key size
+requested by the
+.B \-b
+option determines the size of the modulus
+.IR n ;
+the default is 1024 bits.
+.IP
+The key generation algorithm chooses
+.I p
+and
+.I q
+to be
+.I strong
+primes: both
+.IR p \ \-\ 1
+and
+.IR p \ +\ 1
+have large prime factors \- call them
+.I r
+and
+.I s
+respectively \- and
+.IR r \ \-\ 1
+also has a large prime factor;
+.I q
+has similar properties.
+.IP
+The modulus
+.I n
+cannot be sensibly used as a shared parameter, since knowledge of
+corrssponding public and private exponents is sufficient to be able to
+factor the modulus and recover other users' private keys.
+.TP
+.B "dh-params"
+Generates parameters for use with the Diffie-Hellman key exchange
+protocol, and many related systems, such as ElGamal encryption and
+signatures, and even DSA (although the DSA algorithm is probably better
+for this).  The parameters are a prime number
+.IR q ,
+a larger prime number
+.IR p ,
+and a generator
+.I g
+of the
+.RI order- q
+subgroup of the integers
+.RI mod\  p .
+.IP
+The key size set by the
+.B \-b
+option determines the size of the modulus
+.IR p ;
+the size of the generator order
+.I q
+is set by the
+.B \-B
+option.  The default modulus size is 1024 bits; if no size is specified
+for
+.IR q ,
+the parameters are chosen such that
+.IR p \ =\ 2 q \ +\ 1,
+and
+.I
+g
+is assigned the value 4.  This takes much longer.
+.IP
+If used with the
+.B \-p
+option, the algorithm simply copies the parameters from an existing key.
+.TP
+.B "dh"
+Generates a public/private key pair for use with offline Diffie-Hellman,
+ElGamal, DSA or similar discrete-logarithm-based systems.  It selects a
+private key
+.IR x \ <\  q ,
+and computes the public key
+.IR y \ =\  g\*(ssx\*(se \ mod\  p .
+.TP
+.B "dsa-param"
+Generates parameters for the DSA algorithm.  DSA parameters are also
+suitable for use with Diffie-Hellman and ElGamal system.
+.IP
+The main difference between DSA and Diffie-Hellman parameter generation
+is thatthe DSA parameter generation
+algorithm creates a
+.I seed
+from which the parameters are derived, and, assuming that the SHA-1 hash
+function is strong, it's not feasible to construct a seed from which
+deliberately weak parameters are derived.  The algorithm used is the one
+described in the DSA standard, FIPS\ 186, extended only to allow
+sequential search for a prime
+.I q
+and to allow arbitrary parameter sizes.  The seed is stored,
+Base64-encoded, as the value of the attribute
+.BR seed .
+.IP
+The default lengths for
+.I p
+and
+.I q
+are 768 and 160 bits respectively, since the DSA standard specifies that
+.I q
+be 160 bits, and the choice of 768 bits for
+.I p
+gives commensurate security.
+.TP
+.B "dsa"
+Generates a public/private key pair for DSA.  As for Diffie-Hellman
+keys, it selects a
+private key
+.IR x \ <\  q ,
+and computes the public key
+.IR y \ =\  g\*(ssx\*(se \ mod\  p .
+.TP
+.B "bbs"
+Generates a public/private key pair for the Blum-Blum-Shub random-number
+generator, and the Blum-Goldwasser semantically-secure public-key
+encryption system.
+.IP
+The key components are prime numbers
+.I p
+and
+.IR q ,
+both congruent to 3 (mod\ 4), and their product
+.IR n .
+The public key is simply the modulus
+.IR n ;
+the factors
+.I p
+and
+.I q
+are the private key.
+.IP
+The key-generation algorithm ensures that the two primes
+.I p
+and
+.I q
+are
+.I strong
+(see the discussion of strong primes above, in the section on RSA keys),
+and that
+.RI ( p \ \-\ 1)/2
+and
+.RI ( q \ \-\ 1)/2
+are relatively prime, giving a maximum possible period length.
+.IP
+The key size requested by the
+.B \-b
+option determines the length of the modulus
+.IR n ;
+the default length is 1024 bits.
+.SS "expire"
 Forces keys to immediately expire.  An expired key is not chosen when a
 program requests a key by its type.  The keys to expire are listed by
 their
-.IR keyid s.
-.SS delete
+.IR tag s.
+.SS "delete"
 Deletes keys immediately.  The keys to delete are listed by their
-.IR keyid s.
+.IR tag s.
 Be careful when deleting keys.  It might be a better idea
 to expire keys rather than deleting them.
-.SS setattr
+.SS "tag"
+Sets, deletes or changes the tag attached to a key.  The first tag or
+keyid names the key to be modified; the second, if present specifies the
+new tag to be set.  If no second argument is given, the existing tag, if
+any, is removed and no new tag is set.
+.SS "setattr"
 Attaches attributes to a key.  The key to which the attributes should be
 attached is given by its
-.IR keyid .
+.IR tag .
 Each attribute has the form
 .IB name = value\fR.
 An attribute can be deleted by assigning it an empty value.  Although
 the keyring file format is capable of representing an attribute with an
 empty value as distinct from a nonexistant attribute, this interface
 does not allow empty attributes to be set.
-.SS list
+.SS "comment"
+Sets, deletes or changes the comment attached to a key.  The first
+argument is a key tag or keyid which names the key to be modified; the
+second, if present, is the new comment.  If no second argument is given,
+the existing comment, if any, is removed, and no new comment is set.
+.SS "lock"
+Locks a key or key component using a passphrase.  If the key is already
+locked, the existing passphrase is requested, and a new passphrase is
+set.
+.SS "unlock"
+Unlocks a passphrase-locked key or key component.  If the key is not
+locked, an error is reported.
+.SS "list"
 Lists the keys in the keyring.  A couple of options are supported:
 .TP
 .B "\-v, \-\-verbose"
@@ -211,24 +537,48 @@ option.
 .TP
 .B "\-u, \-\-utc"
 Display key expiry times as UTC rather than using the local time zone.
+.TP
+.BI "\-f, \-\-filter " filter
+Specifies a filter.  Only keys and key components which match the filter
+are listed.
 .PP
 By default, a single line of output is generated for each, showing
 keyids, types, expiry and deletion dates, and comments.  Additional
 .RB ` \-v '
 options show more information, such as the exact time of day for expiry
-and deletion, key attributes, and a hex dump of the actual key data.
-.SS tidy
+and deletion, key attributes, and a dump of the actual key data.  If the
+verbosity level is sufficiently high, passphrases are requested to
+decrypt locked keys.  Make sure nobody is looking over your shoulder
+when you do this!
+.SS "fingerprint"
+Reports a fingerprint (secure hash) on components of requested keys.
+The following option is supported:
+.TP
+.BI "\-f, \-\-filter " filter
+Specifies a filter.  Only keys and key components which match the filter
+are fingerprinted.  The default is to only fingerprint nonsecret
+components.
+.PP
+The keys to be fingerprinted are named by their tags or keyids given as
+command line arguments.  If no key tags are given, all keys which match
+the filter are fingerprinted.
+.SS "tidy"
 Simply reads the keyring from file and writes it back again.  This has
 the effect of removing any deleted keys from the file.
-.SS extract
-Writes a selection of keys to the named
-.IR file ,
+.SS "extract"
+Writes a selection of keys to a file.  An option is supported:
+.TP
+.BI "\-f, \-\-filter " filter
+Specifies a filter.  Only keys and key components which match the filter
+are written.
+.PP
+Keys extracted are written to the file named by the first argument,
 which may be
 .RB ` \- '
 to designate standard output.  The keys to extract are listed by their
-.IR keyid s.
-The output is a valid keyring file.
-.SS merge
+tags; if no tags are given, all keys which match the filter are
+extracted.  The output is a valid keyring file.
+.SS "merge"
 Merges the keys from the named
 .IR file ,
 which may be
@@ -236,11 +586,6 @@ which may be
 to designate standard input, with the keyring.  Keys already in the
 keyring are not overwritten: you must explicitly remove them first if
 you want them to be replaced during the merge.
-.SH BUGS
-The ability to generate keys for specific algorithms ought to be added,
-for DES (setting the parity bits correctly), RSA, ElGamal and DSA, at
-the very least.  (None of these systems are actually implemented in
-Catacomb at the moment, however.)
 .SH "SEE ALSO"
 .BR keyring (5).
 .SH AUTHOR