Modify for standalone distribution. The library's getting far too large

[u/mdw/catacomb] / key.1

.\" -*-nroff-*-
.TH key 1 "5 June 1999" Catacomb
.SH NAME
key \- simple key management system
.SH SYNOPSIS
.B key
.RB [ \-k
.IR keyring ]
.I command
.PP
where
.I command
is one of:
.PP
.B add
.RB [ \-b
.IR bits ]
.RB [ \-e
.IR expire ]
.RB [ \-c
.IR comment ]
.I type
.IR attr ...
.br
.B expire
.IR keyid ...
.br
.B delete
.IR keyid ...
.br
.B setattr
.I keyid
.IR attr ...
.br
.B list
.RB [ \-qv ]
.br
.B tidy
.br
.B extract
.I file
.IR keyid ...
.br
.B merge
.I file
.SH DESCRIPTION
The
.B key
command performs useful operations on Catacomb keyring files.  It
provides a number of subcommands, by which the various operations may be
carried out.
.SS "Global options"
Before the command name,
.I "global options"
may be given.  The following global options are supported:
.TP
.B "\-h, \-\-help"
Writes a brief summary of
.BR key 's
various options to standard output, and
returns a successful exit status.
.TP
.B "\-v, \-\-version"
Writes the program's version number to standard output, and returns a
successful exit status.
.TP
.B "\-u, \-\-usage"
Writes a very terse command line summary to standard output, and returns
a successful exit status.
.TP
.BI "\-k, \-\-keyring=" file
Names the keyring file which
.B key
is to process.  The default keyring, used if this option doesn't specify
one, is the file named
.B keyring
in the current directory.  The keyring must be stored in a regular file:
pipes, sockets, devices etc. are not allowed.
The
.B key
program attempts to lock the keyring before accessing it, using
.BR fcntl (2)
locking.  It will however time out after a short while (10 seconds) and
report a failure.
.SS Concepts
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
.I deleted
key cannot be looked up by keyid.
.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
.I expired
key cannot be looked up by type, but may be looked up by keyid.
.TP
.B "expiry time"
Most keys expire after a certain amount of time.  Once a key has
expired, it will no longer be chosen as a result of a lookup by key
type.  However, it is not deleted until its deletion time is also
reached.
.TP
.B "deletion time"
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
applications, and will be removed from the keyring next time it's
written to disk.
.TP
.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
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;
others may be assigned global meanings in future.
.SH "COMMAND REFERENCE"
.SS add
The
.B add
command creates a new key and adds it to the keyring.  The command
accepts the following options:
.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.
.TP
.BI "\-e, \-\-expire=" expire
The expiry date for the generated key.  This may be the string
.RB ` forever '
if the key should never expire automatically, or any date acceptable to
the
.BR getdate (3)
library function.  Briefly,
.B getdate
understands absolute dates such as
.RB ` 1999-08-02 '
or
.RB ` "August 2nd, 1999" ',
and (perhaps more usefully) relative dates such as
.RB ` "+2 weeks" '.
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.
.PP
The key's type is given by the required
.I type
argument.  Following the type are zero or more attributes, which are
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
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
Deletes keys immediately.  The keys to delete are listed by their
.IR keyid s.
Be careful when deleting keys.  It might be a better idea
to expire keys rather than deleting them.
.SS setattr
Attaches attributes to a key.  The key to which the attributes should be
attached is given by its
.IR keyid .
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
Lists the keys in the keyring.  A couple of options are supported:
.TP
.B "\-v, \-\-verbose"
Increases the amount of information displayed for each key.  Repeat for
a greater effect.
.TP
.B "\-q, \-\-quiet"
Decreases the amount of information displayed for each key.  Each use
cancels a
.RB ` \-v '
option.
.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
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 ,
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
Merges the keys from the named
.IR file ,
which may be
.RB ` \- '
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
Mark Wooding, <mdw@nsict.org>