X-Git-Url: https://git.distorted.org.uk/u/mdw/catacomb/blobdiff_plain/ba6e6b64033b1f9de49feccb5c9cd438354481f7..0f00dc4c8eb47e67bc0f148c2dd109f73a451e0a:/progs/cookie.1 diff --git a/progs/cookie.1 b/progs/cookie.1 new file mode 100644 index 0000000..7bdef80 --- /dev/null +++ b/progs/cookie.1 @@ -0,0 +1,269 @@ +.\" -*-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,