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