Merge branch 'master' of git.distorted.org.uk:~mdw/publish/public-git/catacomb

[u/mdw/catacomb] / key.1

diff --git a/key.1 b/key.1
index 2f47eff..3e7a601 100644 (file)
--- a/key.1
+++ b/key.1
@@ -1,13 +1,34 @@
 .\" -*-nroff-*-
 .ie t \{\
 .\" -*-nroff-*-
 .ie t \{\

+.  if \n(.g \{\
+.    fam P
+.  \}

 .  ds ss \s8\u
 .  ds se \d\s0
 .  ds ss \s8\u
 .  ds se \d\s0

+.  ds us \s8\d
+.  ds ue \u\s0
+.  ds *b \(*b

 .\}
 .el \{\
 .  ds ss ^
 .  ds se
 .\}
 .el \{\
 .  ds ss ^
 .  ds se

+.  ds us _
+.  ds ue
+.  ds *b \fIbeta\fP

 .\}
 .\}

-.TH key 1 "5 June 1999" Catacomb
+.de VS
+.sp 1
+.RS
+.nf
+.ft B
+..
+.de VE
+.ft R
+.fi
+.RE
+.sp 1
+..
+.TH key 1 "5 June 1999" "Straylight/Edgeware" "Catacomb cryptographic library"

 .SH NAME
 key \- simple key management system
 .SH SYNOPSIS
 .SH NAME
 key \- simple key management system
 .SH SYNOPSIS


@@ -20,24 +41,42 @@ where
 .I command
 is one of:
 .PP
 .I command
 is one of:
 .PP

+.B help
+.RI [ command ...]
+.br
+.B show
+.RI [ item ...]
+.br

 .B add
 .B add

-.RB [ \-lq ]
+.RB [ \-lqrLKS ]

 .RB [ \-a
 .IR alg ]
 .RB [ \-b | \-B
 .IR bits ]
 .RB [ \-p
 .IR param ]
 .RB [ \-a
 .IR alg ]
 .RB [ \-b | \-B
 .IR bits ]
 .RB [ \-p
 .IR param ]

-.RB [ \-r
+.RB [ \-R

 .IR tag ]
 .br
 \h'8n'
 .IR tag ]
 .br
 \h'8n'

+.RB [ \-A
+.IR seed-alg ]
+.RB [ \-s
+.IR seed ]
+.RB [ \-n
+.IR bits ]
+.br
+\h'8n'

 .RB [ \-e
 .IR expire ]
 .RB [ \-t
 .IR tag ]
 .RB [ \-c
 .IR comment ]
 .RB [ \-e
 .IR expire ]
 .RB [ \-t
 .IR tag ]
 .RB [ \-c
 .IR comment ]

+.RB [ \-C
+.IR curve ]
+.br
+\h'8n'

 .I type
 .IR attr ...
 .br
 .I type
 .IR attr ...
 .br


@@ -59,6 +98,10 @@ is one of:
 .I tag
 .IR attr ...
 .br
 .I tag
 .IR attr ...
 .br

+.B getattr
+.I tag
+.I attr
+.br

 .B lock
 .I qtag
 .br
 .B lock
 .I qtag
 .br


@@ -74,8 +117,18 @@ is one of:
 .B fingerprint
 .RB [ \-f
 .IR filter ]
 .B fingerprint
 .RB [ \-f
 .IR filter ]

+.RB [ \-a
+.IR hash ]

 .RI [ tag ...]
 .br
 .RI [ tag ...]
 .br

+.B verify
+.RB [ \-f
+.IR filter ]
+.RB [ \-a
+.IR hash ]
+.I tag
+.I fingerprint
+.br

 .B tidy
 .br
 .B extract
 .B tidy
 .br
 .B extract


@@ -97,11 +150,12 @@ Before the command name,
 .I "global options"
 may be given.  The following global options are supported:
 .TP
 .I "global options"
 may be given.  The following global options are supported:
 .TP

-.B "\-h, \-\-help"
+.BR "\-h, \-\-help " [ \fIcommand ...]

 Writes a brief summary of
 .BR key 's
 various options to standard output, and
 Writes a brief summary of
 .BR key 's
 various options to standard output, and

-returns a successful exit status.
+returns a successful exit status.  With command names, gives help on
+those commands.

 .TP
 .B "\-v, \-\-version"
 Writes the program's version number to standard output, and returns a
 .TP
 .B "\-v, \-\-version"
 Writes the program's version number to standard output, and returns a


@@ -161,24 +215,32 @@ algorithms use
 keys.  Keys used with number-theoretic systems (like most common
 public-key systems) use
 .I "multiprecision integer"
 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
+keys.  Elliptic curve systems use
+.I "curve point"
+keys, which are either a pair of integers representing field elements,
+or a `point at infinity'.  Algorithms which require several key
+constituents (again, like most public-key systems) use

 .I structured
 .I structured

-keys, which consist of a collection of named parts.  Finally, keys
-(including structured keys) can be encrypted.
+keys, which consist of a collection of named parts.  It's possible to
+store an
+.I "ASCII string"
+as a key, though this is usually done as a component of a structured
+key.  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 ,
 .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
+.BR struct ,
+.BR ec ,
+.BR string ,

 or
 .B encrypt
 (describing the key encoding);
 .BR symmetric ,
 .BR private ,
 or
 .B encrypt
 (describing the key encoding);
 .BR symmetric ,
 .BR private ,

-.B public
+.BR public ,

 or
 .B shared
 (describing the category of key);
 or
 .B shared
 (describing the category of key);


@@ -222,6 +284,62 @@ arbitrary strings, except they may not contain null bytes.  Some
 attributes may have meaning for particular applications or key types;
 others may be assigned global meanings in future.
 .SH "COMMAND REFERENCE"
 attributes may have meaning for particular applications or key types;
 others may be assigned global meanings in future.
 .SH "COMMAND REFERENCE"

+.SS help
+The
+.B help
+command behaves exactly as the
+.B \-\-help
+option.  With no arguments, it shows an overview of
+.BR key 's
+options; with arguments, it describes the named subcommands.
+.SS show
+The
+.B show
+command prints various lists of tokens understood by
+.BR key .
+With no arguments, it prints all of the lists; with arguments, it prints
+just the named lists, in order.  The recognized lists can be enumerated
+using the
+.VS
+key show list
+.VE
+command.  The lists are as follows.
+.TP
+.B list
+The lists which can be enumerated by the
+.B show
+command.
+.TP
+.B hash
+The hash functions which can be used with the
+.B fingerprint
+and
+.B verify
+commands.
+.TP
+.B ec
+The built-in elliptic curves which can be used with the
+.B add \-a ec
+command.
+.TP
+.B dh
+The built-in Diffie-Hellman groups which can be used with the
+.B add \-a dh
+command.
+.TP
+.B keygen
+The key-generation algorithms which are acceptable to the
+.B \-a
+option of the
+.B add
+command.
+.TP
+.B seed
+The pseudorandom generators which are acceptable to the
+.B \-s
+option of the
+.B add
+command.

 .SS add
 The
 .B add
 .SS add
 The
 .B add


@@ -231,7 +349,9 @@ accepts the following options:
 .BI "\-a, \-\-algorithm " alg
 Selects a key generation algorithm.  The default algorithm is
 .BR binary ;
 .BI "\-a, \-\-algorithm " alg
 Selects a key generation algorithm.  The default algorithm is
 .BR binary ;

-the different algorithms are described below.
+the different algorithms are described below.  The command
+.B key show keygen
+lists the recognized key-generation algorithms.

 .TP
 .BI "\-b, \-\-bits " bits
 The length of the key to generate, in bits.  The default, if this option
 .TP
 .BI "\-b, \-\-bits " bits
 The length of the key to generate, in bits.  The default, if this option


@@ -243,7 +363,53 @@ key-generation algorithms have a subsidiary key size.
 .TP
 .BI "\-p, \-\-parameters " tag
 Selects a key containing parameter values to copy.  Not all
 .TP
 .BI "\-p, \-\-parameters " tag
 Selects a key containing parameter values to copy.  Not all

-key-generation algorithms allow the use of shared parameters.
+key-generation algorithms allow the use of shared parameters.  A new key
+also inherits attributes from its parameter key.
+.TP
+.BI "\-A, \-\-seedalg " seed-alg
+Use the deterministic random number generator algorithm
+.I seed-alg
+to generate the key.  Use
+.I before
+the
+.B \-s
+or
+.B \-n
+options; without one of these,
+.B \-A
+has no effect.  The default algorithm is
+.BR rmd160-mgf .
+The command
+.B key show seed
+shows a list of recognized seeding algorithms.  The seeding algorithm
+used to generate a key is recorded as the key's
+.B seedalg
+attribute.
+.TP
+.BI "\-s, \-\-seed " seed
+Generate the key deterministically using the given
+.IR seed ,
+which should be a Base64-encoded binary string.  This is mainly useful
+for parameters keys (types
+.BR dsa-param
+and
+.BR dh-param ),
+to demonstrate that a set of parameters has been generated in an honest
+fashion.  The
+.B dsarand
+generation algorithm can be used to generate
+.B dsa-param
+keys as required by FIPS186.  The requested seed is recorded,
+Base64-encoded, as the new key's
+.B seed
+attribute.
+.TP
+.BI "\-n, \-\-newseed " bits
+Generate a new seed, with the given length in
+.IR bits .
+The generated seed is recorded, Base64-encoded, as the new key's
+.B seed
+attribute.

 .TP
 .BI "\-e, \-\-expire " expire
 The expiry date for the generated key.  This may be the string
 .TP
 .BI "\-e, \-\-expire " expire
 The expiry date for the generated key.  This may be the string


@@ -264,11 +430,21 @@ The default is to allow a 2 week expiry, which isn't useful.
 .BI "\-c, \-\-comment " comment
 Sets a comment for the key.  The default is not to attach a comment.
 .TP
 .BI "\-c, \-\-comment " comment
 Sets a comment for the key.  The default is not to attach a comment.
 .TP

+.BI "\-C, \-\-curve " curve-spec
+Use the elliptic curve described by
+.I curve-spec
+when generating elliptic curve parameters.
+.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 "\-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
+.BI "\-r, \-\-retag"
+If a
+.B \-t
+option is given, remove this tag from any key which already has it.
+.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 ,
 Selects the key to use for the random number generator.  Catacomb's
 random number generator can be
 .IR keyed ,


@@ -285,6 +461,21 @@ using a passphrase.
 .BI "\-q, \-\-quiet"
 Suppresses the progress indication which is usually generated while
 time-consuming key generation tasks are being performed.
 .BI "\-q, \-\-quiet"
 Suppresses the progress indication which is usually generated while
 time-consuming key generation tasks are being performed.

+.TP
+.BI "\-L, \-\-lim-lee"
+When generating Diffie-Hellman parameters, generate a Lim-Lee prime
+rather than a random (or safe) prime.  See the details on Diffie-Hellman
+key generation below.
+.TP
+.BI "\-K, \-\-kcdsa"
+When generating Diffie-Hellman parameters, generate a KCDSA-style
+Lim-Lee prime rather than a random (or safe) prime.  See the details on
+Diffie-Hellman key generation below.
+.TP
+.BI "\-S, \-\-subgroup"
+When generating Diffie-Hellman parameters with a Lim-Lee prime, choose a
+generator of a prime-order subgroup rather than a subgroup of order
+.RI ( p "- 1)/2."

 .PP
 The key's type is given by the required
 .I type
 .PP
 The key's type is given by the required
 .I type


@@ -367,42 +558,99 @@ 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
 corrssponding public and private exponents is sufficient to be able to
 factor the modulus and recover other users' private keys.
 .TP

-.B "dh-params"
+.B "dh-param"

 Generates parameters for use with the Diffie-Hellman key exchange
 protocol, and many related systems, such as ElGamal encryption and
 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 ,
+signatures, and even DSA.  (The separate DSA algorithm uses the
+generator described in FIPS186-1.)
+.IP
+The Diffie-Hellman parameters are a prime modulus
+.I p

 and a generator
 .I g
 and a generator
 .I g

-of the
-.RI order- q
-subgroup of the integers
-.RI mod\  p .
-.IP
-The key size set by the
+of a subgroup of
+.BR Z / \c
+.IB p Z
+of order
+.IR q .
+The

 .B \-b
 .B \-b

-option determines the size of the modulus
+option controls the size of the modulus

 .IR p ;
 .IR p ;

-the size of the generator order
+the default size is 1024 bits.
+.IP
+If no

 .I q
 .I q

-is set by the
+size is selected using the

 .B \-B
 .B \-B

-option.  The default modulus size is 1024 bits; if no size is specified
-for
-.IR q ,
-the parameters are chosen such that
+option and the Lim-Lee prime options are disabled, then
+.I p
+is chosen to be a `safe' prime (i.e.,

 .IR p \ =\ 2 q \ +\ 1,
 .IR p \ =\ 2 q \ +\ 1,

+with
+.I q
+prime).  Finding safe primes takes a very long time.  In this case, the
+value of
+.I g
+is fixed as 4.
+.IP
+If a size is chosen for
+.I q
+and Lim-Lee primes are not selected then the prime
+.I q
+is generated and
+.I p
+is chosen so that
+.IR p \ \-\ 1
+is a multiple of
+.IR q .
+.IP
+If the
+.B \-L
+option was given, Lim-Lee primes are selected: the parameters are chosen
+such that
+.IR p \ =\ 2\  q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...\ +\ 1,
+where the
+.IR q \*(us i\*(ue
+are primes at least as large as the setting given by the
+.B \-B
+option (or 256 bits, if no setting was given).
+.IP
+If the
+.B \-K
+option was given, KCDSA-style Lim-Lee primes are selected: the
+parameters are chosen such that
+.IR p \ =\ 2\  q\ v \ +\ 1,
+where
+.IR p,
+.I q

 and
 and

-.I
-g
-is assigned the value 4.  This takes much longer.
+.I v
+are primes.
+.IP
+If the
+.B \-S
+or
+.B \-K
+options were given, the generator
+.I g
+is chosen to generate the subgroup of order
+.IR q \*(us0\*(ue;
+otherwise,
+.I g
+will generate the group of order
+.RI ( p \ \-\ 1)/2\ =\  q \*(us0\*(ue\ q \*(us1\*(ue\ q \*(us2\*(ue\ ...

 .IP
 .IP

-If used with the
-.B \-p
-option, the algorithm simply copies the parameters from an existing key.
+Finally, the
+.B \-C
+option can be given, in which case the parameters are taken directly
+from the provided group specification, which may either be the the name
+of one of the built-in groups (say
+.B "key show dh"
+for a list) or a triple
+.RI ( p ,\  q ,\  g ).
+separated by commas.  No random generation is done in this case: the
+given parameters are simply stored.

 .TP
 .B "dh"
 Generates a public/private key pair for use with offline Diffie-Hellman,
 .TP
 .B "dh"
 Generates a public/private key pair for use with offline Diffie-Hellman,


@@ -485,6 +733,104 @@ The key size requested by the
 option determines the length of the modulus
 .IR n ;
 the default length is 1024 bits.
 option determines the length of the modulus
 .IR n ;
 the default length is 1024 bits.

+.TP
+.B "ec-param"
+Store an elliptic curve specification.  If no explicit
+.I curve-spec
+is given (the
+.RB ` \-C '
+option) then a curve is chosen whose order is about the size given by the
+.RB ` \-b '
+option (default is 256 bits).
+.IP
+A
+.I curve-spec
+can be given explicitly (in which case
+.RB ` \-b '
+is ignored).  It can either be the name of a built-in curve (say
+.B "key show ec"
+for a list of curve names) or a full specification.  The curve is
+checked for correctness and security according to the SEC1
+specification: failed checks cause a warning to be issued to standard
+error (though the program continues anyway).  The check can be
+suppressed using the
+.RB ` \-q '
+option.
+.IP
+A curve specification consists of the following elements optionally
+separated by whitespace: a
+.IR "field type" ,
+which is one of
+.BR "prime" ,
+.BR "niceprime" ,
+.BR "binpoly" ,
+.or
+.BR "binnorm" ;
+an optional
+.RB ` : ';
+the field modulus
+.IR p ;
+if the field type is
+.B binnorm
+then an optional
+.RB ` , '
+and the representation of the normal element \*(*b; an optional
+.RB ` ; ';
+a
+.IR "curve type" ,
+which is one of
+.BR "prime" ,
+.BR "primeproj" ,
+.BR "bin" ,
+and
+.BR "binproj"
+(the `proj' types currently have much better performance);
+an optional
+.RB ` : ';
+the two field-element parameters
+.I a
+and
+.IR b
+which define the elliptic curve
+.IR E ,
+separated by an optional
+.RB ` , ';
+an optional
+.RB ` ; ';
+the
+.IR x -
+and
+.IR y -coordinates
+of the generator point
+.IR G ,
+separated by an optional
+.RB ` , ';
+an optional
+.RB ` : ';
+the order
+.I r
+of the group generated by
+.IR G ;
+an optional
+.RB ` * ';
+and the
+.I cofactor
+.I h
+=
+.RI # E / r .
+.TP
+.B "ec"
+Generate a private scalar and a corresponding public point on an
+elliptic curve.  See
+.B ec-param
+above for how to specify elliptic curve parameter sets.  The scalar
+.I x
+is chosen unformly between 0 and the curve order
+.IR r ;
+the public point is then
+.I x
+\(mu
+.IR G .

 .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
 .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


@@ -499,7 +845,10 @@ to expire keys rather than deleting them.
 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
 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.
+any, is removed and no new tag is set.  It is an error to set a tag
+which already exists on another key, unless you give the
+.B \-r
+option, which removes the tag first.

 .SS "setattr"
 Attaches attributes to a key.  The key to which the attributes should be
 attached is given by its
 .SS "setattr"
 Attaches attributes to a key.  The key to which the attributes should be
 attached is given by its


@@ -510,6 +859,13 @@ 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.
 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 "getattr"
+Fetches a single attribute of a key.  The key whose attribute is to be
+read is given by its
+.IR tag .
+The attribute's value is written to standard output followed by a
+newline.  If the key or attribute is absent, a message is written to
+standard error and the program exits nonzero.

 .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
 .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


@@ -552,16 +908,42 @@ 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.
 when you do this!
 .SS "fingerprint"
 Reports a fingerprint (secure hash) on components of requested keys.

-The following option is supported:
+The following options are 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.
 .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.

+.TP
+.BI "\-a, \-\-algorithm " hash
+Names the hashing algorithm.  Run
+.B key show hash
+for a list of hashing algorithms.  The default is
+.BR rmd160 .

 .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
 .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.
+the filter are fingerprinted.  See
+.BR keyring (5)
+for a description of how key fingerprints are computed.
+.SS "verify"
+Check a key's fingerprint against a reference copy.  The following
+options are supported:
+.TP
+.BI "\-f, \-\-filter " filter
+Specifies a filter.  Only key components which match the filter are
+hashed.  The default is to only fingerprint nonsecret components.  An
+error is reported if no part of the key matches.
+.TP
+.BI "\-a, \-\-algorithm " hash
+Names the hashing algorithm.  Run
+.B key show hash
+for a list of hashing algorithms.  The default is
+.BR rmd160 .
+.PP
+The reference fingerprint is given as hex, in upper or lower case.  The
+hash may contain hyphens, colons and whitespace.  Other characters are
+not permitted.

 .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 "tidy"
 Simply reads the keyring from file and writes it back again.  This has
 the effect of removing any deleted keys from the file.


@@ -589,5 +971,5 @@ you want them to be replaced during the merge.
 .SH "SEE ALSO"
 .BR keyring (5).
 .SH AUTHOR
 .SH "SEE ALSO"
 .BR keyring (5).
 .SH AUTHOR

-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>