.\" -*-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>