+++ /dev/null
-.\" -*-nroff-*-
-.de hP
-.IP
-.ft B
-\h'-\w'\\$1\ 'u'\\$1\ \c
-.ft P
-..
-.ie t \{\
-. if \n(.g \{\
-. fam P
-. \}
-.\}
-.ie t .ds o \(bu
-.el .ds o o
-.
-.TH cookie 1 "5 June 1999" "Straylight/Edgeware" "Catacomb cryptographic library"
-.SH NAME
-cookie \- generate and validate cryptographic cookies
-.SH SYNOPSIS
-.B cookie
-.RB [ \-k
-.IR keyring ]
-.I command
-.PP
-where command is one of:
-.PP
-.B help
-.RI [ command ...]
-.br
-.B show
-.RI [ item ...]
-.br
-.B generate
-.RB [ \-b
-.IR bits ]
-.RB [ \-e
-.IR expire ]
-.RB [ \-k
-.IR tag ]
-.I data
-.br
-.B verify
-.RB [ \-fquv ]
-.RB [ \-b
-.IR bits ]
-.RB [ \-m
-.IR bits ]
-.I cookie
-.RI [ data ]
-.SH DESCRIPTION
-The
-.B cookie
-program generates timestamped cryptographic cookies which can be handed
-out to clients and later validated. It provides two subcommands: one to
-create a new cookie, and one to ensure that a particular cookie is
-valid.
-.SS "Global options"
-Before the command name,
-.I "global options"
-may be given. The following global options are supported:
-.TP
-.BR "\-h, \-\-help " [ \fIcommand ...]
-Displays help text for
-.B cookie
-on standard output and exits successfullly. With command names, gives
-help on each command.
-.TP
-.B "\-v, \-\-version"
-Displays
-.BR cookie 's
-version number on standard output and exits successfullly.
-.TP
-.B "\-u, \-\-usage"
-Displays an unhelpfully terse usage summary on standard output and exits
-successfully.
-.TP
-.BI "\-k, \-\-keyring " file
-Use
-.I file
-as the keyring file rather than the default, which is the file named
-.B keyring
-in the current directory. See
-.BR key (1)
-and
-.BR keyring (5)
-for more details about keyring files.
-.SH "KEY SETUP"
-The message authentication algorithm used to tag and verify cookies is
-described by an attribute on the key, or its type. If the key has a
-.B mac
-attribute, then that is taken to be the name of the MAC algorithm to
-use; otherwise the key must have the type
-.BR cookie- \c
-.IR mac .
-.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 cookie 's
-options; with arguments, it describes the named subcommands.
-.SS show
-The
-.B show
-command prints various lists of tokens understood by
-.BR cookie .
-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
-cookie 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 mac
-The message authentication algorithms which can be used in a key's
-.B mac
-attribute.
-.SS generate
-The
-.B generate
-command creates a new cookie. The command understands the following
-options:
-.TP
-.BI "\-b, \-\-bits " bits
-Specifies the size of the cryptographic token to generate. The default
-token size is 32 bits.
-.TP
-.BI "\-e, \-\-expire " expire
-The expiry date for the cookie. This may be the string
-.RB ` forever '
-if the cookie should never expire, or any date acceptable to the
-.BR getdate (3)
-library function, e.g.,
-.RB ` "+2 weeks" '.
-It is an error to ask for a non-expiring cookie to be created using a
-key which will expire.
-.TP
-.BI "\-k, \-\-key " tag
-Use the key named
-.I tag
-to authenticate the cookie; the default key is named
-.BR cookie .
-.PP
-If a
-.I data
-argument is supplied, then an identical argument must be supplied to the
-.B verify
-command if the cookie is to be accepted as valid. The data will usually
-be some way of identifying the cookie's recipient, e.g., an email
-address.
-.PP
-The generated cookie is written to standard output, followed by a
-newline. Cookies are not architecture-specific.
-.SS verify
-The
-.B verify
-command checks a cookie for validity. It accepts the following
-options:
-.TP
-.BI "\-b, \-\-bits " bits
-Only accept a cookie with a cryptographic token exactly
-.I bits
-bits long.
-.TP
-.BI "\-m, \-\-min\-bits " bits
-Only accept a cookie with a cryptographic token at least
-.I bits
-bits long. The default is to accept any token with size 32 bits or
-more.
-.TP
-.B "\-f, \-\-forever"
-Allow non-expiring cookies. Without this option, cookies which never
-expire are automatically rejected by
-.BR cookie .
-.TP
-.B "\-u, \-\-utc"
-Display expiry time as UTC rather than using the local time zone.
-.TP
-.B "\-q, \-\-quiet"
-Make
-.B cookie
-more quiet. Repeat for a greater effect.
-.TP
-.B "\-v, \-\-verbose"
-Make
-.B cookie
-more verbose. Repeat for a greater effect.
-.PP
-The argument
-.I cookie
-is the cookie to check. The cookie may have whitespace before, after
-or within it.
-.PP
-If
-.I data
-is specified, it must exactly match the data passed to
-.B generate
-if the cookie is to be accepted.
-.PP
-Each line of text emitted by the
-.B verify
-command begins with a status indicator, which is one of the following:
-.TP
-.B INFO
-This line provides possibly useful information about the cookie.
-.B INFO
-lines are displayed while
-.B cookie
-is working, before it's made its mind up about whether to reject the
-cookie. The remainder of the line contains the information gleaned.
-.TP
-.B FAIL
-The cookie is invalid. The remainder of the line is a human-readable
-error message giving a reason for rejecting the cookie.
-.TP
-.B OK
-The cookie is valid.
-.PP
-The
-.B \-q
-and
-.B \-v
-flags control the amount of output that
-.B cookie
-generates. By default, only
-.B OK
-and
-.B FAIL
-lines are generated. One
-.B \-v
-option shows the cookie's keyid and expiry time. Two
-.B \-v
-options also show the authentication token width. A
-.B \-q
-option suppresses all output, or cancels out a previous
-.BR \-v .
-.PP
-Regardless of how much output is generated,
-.B cookie
-exits with return code 0 if the cookie was accepted and return code 1 if
-validation failed for some reason.
-.SH "COOKIE FORMAT"
-Cookies are Base64-encoded binary objects. The binary data consists of:
-.hP \*o
-A 32-bit keyid referring to the key with which the cookie was created.
-.hP \*o
-An expiry date, expressed as a 64-bit integer in the format returned by
-the
-.BR time (2)
-system call.
-.hP \*o
-The `authentication token', which is the leftmost bits of a MAC over the
-keyid and date and any extra data supplied to the
-.B generate
-command
-.PP
-The keyid and expiry date are stored in network (big-endian) byte order.
-.SH "SEE ALSO"
-.BR key (1).
-.SH "AUTHOR"
-Mark Wooding, <mdw@distorted.org.uk>
projects / u / mdw / catacomb / blobdiff