[u/mdw/catacomb] / cookie.1

.\" -*-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>
Commit	Line	Data
c65df279	1	.\" --nroff--
	2	.de hP
	3	.IP
	4	.ft B
	5	\h'-\w'\\$1\ 'u'\\$1\ \c
	6	.ft P
	7	..
	8	.ie t \{\
	9	. if \n(.g \{\
	10	. fam P
	11	. \}
	12	.\}
	13	.ie t .ds o \(bu
	14	.el .ds o o
	15	.
	16	.TH cookie 1 "5 June 1999" "Straylight/Edgeware" "Catacomb cryptographic library"
	17	.SH NAME
	18	cookie \- generate and validate cryptographic cookies
	19	.SH SYNOPSIS
	20	.B cookie
	21	.RB [ \-k
	22	.IR keyring ]
	23	.I command
	24	.PP
	25	where command is one of:
	26	.PP
	27	.B help
	28	.RI [ command ...]
	29	.br
	30	.B show
	31	.RI [ item ...]
	32	.br
	33	.B generate
	34	.RB [ \-b
	35	.IR bits ]
	36	.RB [ \-e
	37	.IR expire ]
	38	.RB [ \-k
	39	.IR tag ]
	40	.I data
	41	.br
	42	.B verify
	43	.RB [ \-fquv ]
	44	.RB [ \-b
	45	.IR bits ]
	46	.RB [ \-m
	47	.IR bits ]
	48	.I cookie
	49	.RI [ data ]
	50	.SH DESCRIPTION
	51	The
	52	.B cookie
	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
	56	valid.
	57	.SS "Global options"
	58	Before the command name,
	59	.I "global options"
	60	may be given. The following global options are supported:
	61	.TP
	62	.BR "\-h, \-\-help " [ \fIcommand ...]
	63	Displays help text for
	64	.B cookie
65	on standard output and exits successfullly. With command names, gives
66	help on each command.
67	.TP
68	.B "\-v, \-\-version"
69	Displays
70	.BR cookie 's
71	version number on standard output and exits successfullly.
72	.TP
73	.B "\-u, \-\-usage"
74	Displays an unhelpfully terse usage summary on standard output and exits
75	successfully.
76	.TP
77	.BI "\-k, \-\-keyring " file
78	Use
79	.I file
80	as the keyring file rather than the default, which is the file named
81	.B keyring
82	in the current directory. See
83	.BR key (1)
84	and
85	.BR keyring (5)
86	for more details about keyring files.
87	.SH "KEY SETUP"
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
90	.B mac
91	attribute, then that is taken to be the name of the MAC algorithm to
92	use; otherwise the key must have the type
93	.BR cookie- \c
94	.IR mac .
95	.SH "COMMAND REFERENCE"
96	.SS help
97	The
98	.B help
99	command behaves exactly as the
100	.B \-\-help
101	option. With no arguments, it shows an overview of
102	.BR cookie 's
103	options; with arguments, it describes the named subcommands.
104	.SS show
105	The
106	.B show
107	command prints various lists of tokens understood by
108	.BR cookie .
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
111	using the
112	.VS
113	cookie show list
114	.VE
115	command. The lists are as follows.
116	.TP
117	.B list
118	The lists which can be enumerated by the
119	.B show
120	command.
121	.TP
122	.B mac
123	The message authentication algorithms which can be used in a key's
124	.B mac
125	attribute.
126	.SS generate
127	The
128	.B generate
129	command creates a new cookie. The command understands the following
130	options:
131	.TP
132	.BI "\-b, \-\-bits " bits
133	Specifies the size of the cryptographic token to generate. The default
134	token size is 32 bits.
135	.TP
136	.BI "\-e, \-\-expire " expire
137	The expiry date for the cookie. This may be the string
138	.RB ` forever '
139	if the cookie should never expire, or any date acceptable to the
140	.BR getdate (3)
141	library function, e.g.,
142	.RB ` "+2 weeks" '.
143	It is an error to ask for a non-expiring cookie to be created using a
144	key which will expire.
145	.TP
146	.BI "\-k, \-\-key " tag
147	Use the key named
148	.I tag
149	to authenticate the cookie; the default key is named
150	.BR cookie .
151	.PP
152	If a
153	.I data
154	argument is supplied, then an identical argument must be supplied to the
155	.B verify
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
45c0fd36	158	address.
c65df279	159	.PP
	160	The generated cookie is written to standard output, followed by a
	161	newline. Cookies are not architecture-specific.
	162	.SS verify
	163	The
	164	.B verify
	165	command checks a cookie for validity. It accepts the following
	166	options:
	167	.TP
	168	.BI "\-b, \-\-bits " bits
	169	Only accept a cookie with a cryptographic token exactly
	170	.I bits
	171	bits long.
	172	.TP
	173	.BI "\-m, \-\-min\-bits " bits
	174	Only accept a cookie with a cryptographic token at least
	175	.I bits
	176	bits long. The default is to accept any token with size 32 bits or
	177	more.
	178	.TP
	179	.B "\-f, \-\-forever"
	180	Allow non-expiring cookies. Without this option, cookies which never
	181	expire are automatically rejected by
	182	.BR cookie .
	183	.TP
	184	.B "\-u, \-\-utc"
	185	Display expiry time as UTC rather than using the local time zone.
	186	.TP
	187	.B "\-q, \-\-quiet"
	188	Make
	189	.B cookie
	190	more quiet. Repeat for a greater effect.
	191	.TP
	192	.B "\-v, \-\-verbose"
	193	Make
	194	.B cookie
	195	more verbose. Repeat for a greater effect.
	196	.PP
	197	The argument
	198	.I cookie
	199	is the cookie to check. The cookie may have whitespace before, after
	200	or within it.
	201	.PP
	202	If
	203	.I data
	204	is specified, it must exactly match the data passed to
	205	.B generate
	206	if the cookie is to be accepted.
	207	.PP
	208	Each line of text emitted by the
	209	.B verify
	210	command begins with a status indicator, which is one of the following:
	211	.TP
	212	.B INFO
	213	This line provides possibly useful information about the cookie.
	214	.B INFO
	215	lines are displayed while
	216	.B cookie
	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.
	219	.TP
	220	.B FAIL
	221	The cookie is invalid. The remainder of the line is a human-readable
	222	error message giving a reason for rejecting the cookie.
223	.TP
224	.B OK
225	The cookie is valid.
226	.PP
227	The
228	.B \-q
229	and
230	.B \-v
231	flags control the amount of output that
232	.B cookie
233	generates. By default, only
234	.B OK
235	and
236	.B FAIL
237	lines are generated. One
238	.B \-v
239	option shows the cookie's keyid and expiry time. Two
240	.B \-v
241	options also show the authentication token width. A
242	.B \-q
243	option suppresses all output, or cancels out a previous
244	.BR \-v .
245	.PP
246	Regardless of how much output is generated,
247	.B cookie
248	exits with return code 0 if the cookie was accepted and return code 1 if
249	validation failed for some reason.
250	.SH "COOKIE FORMAT"
251	Cookies are Base64-encoded binary objects. The binary data consists of:
252	.hP \*o
253	A 32-bit keyid referring to the key with which the cookie was created.
254	.hP \*o
255	An expiry date, expressed as a 64-bit integer in the format returned by
256	the
257	.BR time (2)
258	system call.
259	.hP \*o
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
262	.B generate
263	command
264	.PP
265	The keyid and expiry date are stored in network (big-endian) byte order.
266	.SH "SEE ALSO"
267	.BR key (1).
268	.SH "AUTHOR"
f387fcb1	269	Mark Wooding, <mdw@distorted.org.uk>