5 \h'-\w'\\$1\ 'u'\\$1\ \c
16 .TH cookie 1 "5 June 1999" "Straylight/Edgeware" "Catacomb cryptographic library"
18 cookie \- generate and validate cryptographic cookies
25 where command is one of:
53 program generates timestamped cryptographic cookies which can be handed
54 out to clients and later validated. It provides two subcommands: one to
55 create a new cookie, and one to ensure that a particular cookie is
58 Before the command name,
60 may be given. The following global options are supported:
62 .BR "\-h, \-\-help " [ \fIcommand ...]
63 Displays help text for
65 on standard output and exits successfullly. With command names, gives
71 version number on standard output and exits successfullly.
74 Displays an unhelpfully terse usage summary on standard output and exits
77 .BI "\-k, \-\-keyring " file
80 as the keyring file rather than the default, which is the file named
82 in the current directory. See
86 for more details about keyring files.
88 The message authentication algorithm used to tag and verify cookies is
89 described by an attribute on the key, or its type. If the key has a
91 attribute, then that is taken to be the name of the MAC algorithm to
92 use; otherwise the key must have the type
95 .SH "COMMAND REFERENCE"
99 command behaves exactly as the
101 option. With no arguments, it shows an overview of
103 options; with arguments, it describes the named subcommands.
107 command prints various lists of tokens understood by
109 With no arguments, it prints all of the lists; with arguments, it prints
110 just the named lists, in order. The recognized lists can be enumerated
115 command. The lists are as follows.
118 The lists which can be enumerated by the
123 The message authentication algorithms which can be used in a key's
129 command creates a new cookie. The command understands the following
132 .BI "\-b, \-\-bits " bits
133 Specifies the size of the cryptographic token to generate. The default
134 token size is 32 bits.
136 .BI "\-e, \-\-expire " expire
137 The expiry date for the cookie. This may be the string
139 if the cookie should never expire, or any date acceptable to the
141 library function, e.g.,
143 It is an error to ask for a non-expiring cookie to be created using a
144 key which will expire.
146 .BI "\-k, \-\-key " tag
149 to authenticate the cookie; the default key is named
154 argument is supplied, then an identical argument must be supplied to the
156 command if the cookie is to be accepted as valid. The data will usually
157 be some way of identifying the cookie's recipient, e.g., an email
160 The generated cookie is written to standard output, followed by a
161 newline. Cookies are not architecture-specific.
165 command checks a cookie for validity. It accepts the following
168 .BI "\-b, \-\-bits " bits
169 Only accept a cookie with a cryptographic token exactly
173 .BI "\-m, \-\-min\-bits " bits
174 Only accept a cookie with a cryptographic token at least
176 bits long. The default is to accept any token with size 32 bits or
179 .B "\-f, \-\-forever"
180 Allow non-expiring cookies. Without this option, cookies which never
181 expire are automatically rejected by
185 Display expiry time as UTC rather than using the local time zone.
190 more quiet. Repeat for a greater effect.
192 .B "\-v, \-\-verbose"
195 more verbose. Repeat for a greater effect.
199 is the cookie to check. The cookie may have whitespace before, after
204 is specified, it must exactly match the data passed to
206 if the cookie is to be accepted.
208 Each line of text emitted by the
210 command begins with a status indicator, which is one of the following:
213 This line provides possibly useful information about the cookie.
215 lines are displayed while
217 is working, before it's made its mind up about whether to reject the
218 cookie. The remainder of the line contains the information gleaned.
221 The cookie is invalid. The remainder of the line is a human-readable
222 error message giving a reason for rejecting the cookie.
231 flags control the amount of output that
233 generates. By default, only
237 lines are generated. One
239 option shows the cookie's keyid and expiry time. Two
241 options also show the authentication token width. A
243 option suppresses all output, or cancels out a previous
246 Regardless of how much output is generated,
248 exits with return code 0 if the cookie was accepted and return code 1 if
249 validation failed for some reason.
251 Cookies are Base64-encoded binary objects. The binary data consists of:
253 A 32-bit keyid referring to the key with which the cookie was created.
255 An expiry date, expressed as a 64-bit integer in the format returned by
260 The `authentication token', which is the leftmost bits of a MAC over the
261 keyid and date and any extra data supplied to the
265 The keyid and expiry date are stored in network (big-endian) byte order.
269 Mark Wooding, <mdw@distorted.org.uk>
projects / u / mdw / catacomb / blob