The rfc2109 Reference Manual

This is the rfc2109 Reference Manual, version 0.4, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Dec 15 07:36:26 2024 GMT+0.

Table of Contents


1 Systems

The main system appears first, followed by any subsystem dependency.


1.1 rfc2109

Version

0.4

Dependency

split-sequence (system).

Source

rfc2109.asd.

Child Component

rfc2109.lisp (file).


2 Files

Files are sorted by type and then listed depth-first from the systems components trees.


2.1 Lisp


2.1.1 rfc2109/rfc2109.asd

Source

rfc2109.asd.

Parent Component

rfc2109 (system).

ASDF Systems

rfc2109.

Packages

rfc2109-system.

Public Interface
Internals

load-file-with-tests (class).


2.1.2 rfc2109/rfc2109.lisp

Source

rfc2109.asd.

Parent Component

rfc2109 (system).

Packages

rfc2109.

Public Interface
Internals

3 Packages

Packages are listed by definition order.


3.1 rfc2109-system

Source

rfc2109.asd.

Use List
  • asdf/interface.
  • common-lisp.
Internals

load-file-with-tests (class).


3.2 rfc2109

This package implements RFC2109 - the original cookie specification. Use it to generate (and eventually parse) cookies in an RFC-compliant way.

Source

rfc2109.lisp.

Use List

common-lisp.

Public Interface
Internals

4 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


4.1 Public Interface


4.1.1 Ordinary functions

Package

rfc2109.

Source

rfc2109.lisp.

Target Slot

comment.

Package

rfc2109.

Source

rfc2109.lisp.

Target Slot

domain.

Package

rfc2109.

Source

rfc2109.lisp.

Target Slot

max-age.

Package

rfc2109.

Source

rfc2109.lisp.

Target Slot

name.

Package

rfc2109.

Source

rfc2109.lisp.

Package

rfc2109.

Source

rfc2109.lisp.

Target Slot

path.

Package

rfc2109.

Source

rfc2109.lisp.

Target Slot

secure.

Creates a cookie named NAME of value VALUE
The returned value is suitable for passing in (request-send-headers request :set-cookie cookie).

NAME, VALUE (strings)
Required. The name of the state information ("cookie") is NAME,
and its value is VALUE. NAMEs that begin with $ are reserved for
other uses and must not be used by applications.

Comment (a string)
Because cookies can contain private information about a
user, the Cookie attribute allows an origin server to document its
intended use of a cookie. The user can inspect the information to
decide whether to initiate or continue a session with this cookie.

Domain (a string)
The Domain attribute specifies the domain for which the
cookie is valid. An explicitly specified domain must always start
with a dot. [ed - this implementation requires an explicitly specified domain!]

Max-Age (a non-negative integer)
The Max-Age attribute defines the lifetime of the
cookie, in seconds. The delta-seconds value is a decimal non-
negative integer. After delta-seconds seconds elapse, the client
should discard the cookie. A value of zero means the cookie
should be discarded immediately.

Path (a string)
The Path attribute specifies the subset of URLs to
which this cookie applies.

NB: Mozilla (pre-Deer-Park), IE, and links all fail with RFC-compliant
PATHs. As such, it is recommended to set the cookie in the root of your
web app’s URI, and not include a path argument.

Secure (true or false)
The Secure attribute directs the user
agent to use only (unspecified) secure means to contact the origin
server whenever it sends back this cookie.

The user agent (possibly under the user’s control) may determine
what level of security it considers appropriate for "secure"
cookies. The Secure attribute should be considered security
advice from the server to the user agent, indicating that it is in
the session’s interest to protect the cookie contents.

corrects-path-p (true or false)
If this is true, PATH will be written as a quoted string, in conformance
with the standard. Otherwise, whatever string is provided to PATH is used.
This may be used to cludge compatibility with current browsers’ broken
handling of the path option.

Package

rfc2109.

Source

rfc2109.lisp.

Given a cookie struct, return an RFC-compliant cookie string

Package

rfc2109.

Source

rfc2109.lisp.

Package

rfc2109.

Source

rfc2109.lisp.

Target Slot

value.

Function: domain-match-p (host-a host-b)

Checks to see if host-a "domain-matches" host-b, per RFC2109
From the RFC:
Hosts names can be specified either as an IP address or a FQHN string. Sometimes we compare one host name with another. Host A’s name domain-matches host B’s if

* both host names are IP addresses and their host name strings match exactly; or

* both host names are FQDN strings and their host name strings match exactly; or

* A is a FQDN string and has the form NB, where N is a non-empty name string, B has the form .B’, and B’ is a FQDN string. (So, x.y.com domain-matches .y.com but not y.com.)

Note that domain-match is not a commutative operation: a.b.c.com domain-matches .c.com, but not the reverse.

Package

rfc2109.

Source

rfc2109.lisp.

Function: make-cookie (&key name value comment domain max-age path secure)
Package

rfc2109.

Source

rfc2109.lisp.

Function: parse-cookies (cookie-string)

Parses cookies in a Cookie: request header, returning a list of COOKIE structs.
The only information that is passed back for each cookie is: name, value, path, domain, so don’t go looking for comments or the like.

Note that this function does not want the Cookie: portion of the header

So if the request header looked like:
Cookie: $Version=1;
mycookie=value1;
myothercookie=value2

You’d leave off the Cookie: bit at the front.

The other parser is SAFE-PARSE-COOKIES, which is the version to use when you can.

Package

rfc2109.

Source

rfc2109.lisp.

Function: safe-parse-cookies (cookie-string &optional domain-restriction)

Parse a cookie string (see parse-cookies), but only allow domain cookies that match domain-restriction RFC 2109 specifies that, in order to avoid a cookie spoofing attack,
one should check that the domain being handed back in your cookie is
the domain you gave out.

A walkthrough of the mechanics:
- If you hand out a cookie with no domain=, then it is restricted to your host
- If you specify a domain, the cookie is "unlocked" for the domain specified

If you don’t expect to use domain cookies, it’s best to ignore all
domain cookies, as they’re not from your website. The default call to
SAFE-PARSE-COOKIES will ignore all domain cookies.

Later on, if you need domain cookies, pass the domains you’ll be using to SAFE-PARSE-COOKIES,
and those specific domains will not be dropped.

RFC text below:

8.2 Cookie Spoofing

Proper application design can avoid spoofing attacks from related
domains. Consider:

1. User agent makes request to victim.cracker.edu, gets back
cookie session_id="1234" and sets the default domain
victim.cracker.edu.

2. User agent makes request to spoof.cracker.edu, gets back
cookie session-id="1111", with Domain=".cracker.edu".

3. User agent makes request to victim.cracker.edu again, and
passes

Cookie: $Version="1";
session_id="1234";
session_id="1111"; $Domain=".cracker.edu"

The server at victim.cracker.edu should detect that the second
cookie was not one it originated by noticing that the Domain
attribute is not for itself and ignore it.

Package

rfc2109.

Source

rfc2109.lisp.


4.1.2 Standalone methods

Method: output-files :around ((op compile-op) (c load-file-with-tests))
Package

asdf/action.

Source

rfc2109.asd.

Method: perform :around (op (component load-file-with-tests))
Package

asdf/action.

Source

rfc2109.asd.

Method: print-object ((object cookie) stream)
Source

rfc2109.lisp.


4.2 Internals


4.2.1 Special variables

Special Variable: *cr*
Package

rfc2109.

Source

rfc2109.lisp.

Special Variable: *ht*
Package

rfc2109.

Source

rfc2109.lisp.

Special Variable: *lf*
Package

rfc2109.

Source

rfc2109.lisp.


4.2.2 Macros

Macro: correct (slot test &optional failure-message)

Checks to see if slot obeys test, or throws an invalid-cookie-parameter. If test is a simple function name it will be turned into (test slot)

Package

rfc2109.

Source

rfc2109.lisp.

Macro: optional (element requirement)
Package

rfc2109.

Source

rfc2109.lisp.

Macro: try-quotes (slot test &body else)

If slot doesn’t match test, try adding quotes around it - if that doesn’t work go to else

Package

rfc2109.

Source

rfc2109.lisp.


4.2.3 Ordinary functions

Function: attr? (element)

Determine if element is an attr

Package

rfc2109.

Source

rfc2109.lisp.

Function: char-el? (el)
Package

rfc2109.

Source

rfc2109.lisp.

Function: cleave-sequence (separator sequence)

Cleave SEQUENCE into two at the first and mandatory occurrance of SEPARATOR.

Package

rfc2109.

Source

rfc2109.lisp.

True if the cookie string is longer than the minimum cookie size guaranteed to be allowed by the specification

Package

rfc2109.

Source

rfc2109.lisp.

Function: copy-cookie (instance)
Package

rfc2109.

Source

rfc2109.lisp.

Function: crlf-el? (el)
Package

rfc2109.

Source

rfc2109.lisp.

Function: ctl-el? (el)
Package

rfc2109.

Source

rfc2109.lisp.

Function: ensure-pair (list delim)

Ensure that the LIST has only two elements, by joining the elements of the tail with DELIM. Gentle failure: shorter lists are just returned.
LIST should be a list of strings.

Package

rfc2109.

Source

rfc2109.lisp.

Function: lws-el? (el)
Package

rfc2109.

Source

rfc2109.lisp.

Function: octet-el? (datum)
Package

rfc2109.

Source

rfc2109.lisp.

Function: parse-cookies-v1 (cookie-string chopped)

Parses RFC2109 cookies - do not use directly

Package

rfc2109.

Source

rfc2109.lisp.

Function: parse-cookies-vnetscape (cookie-string)

Parses old netscape-style cookies

Package

rfc2109.

Source

rfc2109.lisp.

Function: print-cookie (cookie stream depth)

Prints an aesthetic representation of COOKIE to STREAM. Note that this is *not* the equivalent of COOKIE-STRING-FROM-COOKIE-STRUCT. As such, it explicity prints an invalid cookie.

Package

rfc2109.

Source

rfc2109.lisp.

Function: qdtext? (element)
Package

rfc2109.

Source

rfc2109.lisp.

Function: quote-around (string)

Adds quotes around a string

Package

rfc2109.

Source

rfc2109.lisp.

Function: quoted-string? (element)
Package

rfc2109.

Source

rfc2109.lisp.

Function: remove-escaped-quotes (string)
Package

rfc2109.

Source

rfc2109.lisp.

Function: remove-quotes-around (string)

If there are quotes, remove them

Package

rfc2109.

Source

rfc2109.lisp.

Function: split-along-lws (string)

Chops up a string along linear whitespace, returns a list

Package

rfc2109.

Source

rfc2109.lisp.

Function: split-along-quoted-lws (string)

Chops up a string along linear whitespace, but this version knows about quote marks

Package

rfc2109.

Source

rfc2109.lisp.

Function: text-el? (el)
Package

rfc2109.

Source

rfc2109.lisp.

Function: text? (element)
Package

rfc2109.

Source

rfc2109.lisp.

Function: token-el? (el)
Package

rfc2109.

Source

rfc2109.lisp.

Function: token? (element)
Package

rfc2109.

Source

rfc2109.lisp.

Function: trim-spaces (string)
Package

rfc2109.

Source

rfc2109.lisp.

Function: tspecial-el? (el)
Package

rfc2109.

Source

rfc2109.lisp.

Function: valid-domain? (domain)
Package

rfc2109.

Source

rfc2109.lisp.

Function: valid-name? (name)

Verifies that NAME is a valid name

Package

rfc2109.

Source

rfc2109.lisp.

Function: value? (element)

Determine if element is a value

Package

rfc2109.

Source

rfc2109.lisp.

Function: word? (element)

Determine if element is a word

Package

rfc2109.

Source

rfc2109.lisp.


4.2.4 Generic functions

Package

rfc2109.

Methods
Source

rfc2109.lisp.

Target Slot

cookie-string.

Generic Reader: invalid-cookie-parameter-message (condition)
Package

rfc2109.

Methods
Reader Method: invalid-cookie-parameter-message ((condition invalid-cookie-parameter))
Source

rfc2109.lisp.

Target Slot

message.

Generic Reader: invalid-cookie-parameter-parameter (condition)
Package

rfc2109.

Methods
Reader Method: invalid-cookie-parameter-parameter ((condition invalid-cookie-parameter))
Source

rfc2109.lisp.

Target Slot

parameter.

Generic Reader: invalid-cookie-parameter-value (condition)
Package

rfc2109.

Methods
Reader Method: invalid-cookie-parameter-value ((condition invalid-cookie-parameter))
Source

rfc2109.lisp.

Target Slot

value.

Generic Reader: unparseable-cookie-cookie-string (condition)
Package

rfc2109.

Methods
Reader Method: unparseable-cookie-cookie-string ((condition unparseable-cookie))
Source

rfc2109.lisp.

Target Slot

cookie-string.

Generic Reader: unparseable-cookie-message (condition)
Package

rfc2109.

Methods
Reader Method: unparseable-cookie-message ((condition unparseable-cookie))
Source

rfc2109.lisp.

Target Slot

message.

Generic Reader: unparseable-cookie-version (condition)
Package

rfc2109.

Methods
Reader Method: unparseable-cookie-version ((condition unparseable-cookie))
Source

rfc2109.lisp.

Target Slot

version.


4.2.5 Conditions

Package

rfc2109.

Source

rfc2109.lisp.

Direct superclasses

error.

Direct subclasses
Package

rfc2109.

Source

rfc2109.lisp.

Direct superclasses

cookie-warning.

Direct methods

cookie-string-exceeds-minimum-length-cookie-string.

Direct slots
Initargs

:cookie-string

Readers

cookie-string-exceeds-minimum-length-cookie-string.

Writers

This slot is read-only.

Package

rfc2109.

Source

rfc2109.lisp.

Direct superclasses

warning.

Direct subclasses

cookie-string-exceeds-minimum-length.

Condition: invalid-cookie-parameter
Package

rfc2109.

Source

rfc2109.lisp.

Direct superclasses

cookie-error.

Direct methods
Direct slots
Slot: parameter
Initargs

:parameter

Readers

invalid-cookie-parameter-parameter.

Writers

This slot is read-only.

Slot: value
Initargs

:value

Readers

invalid-cookie-parameter-value.

Writers

This slot is read-only.

Slot: message
Initform

(quote nil)

Initargs

:message

Readers

invalid-cookie-parameter-message.

Writers

This slot is read-only.

Condition: unparseable-cookie

Condition returned when all parsing attempts have failed.

Package

rfc2109.

Source

rfc2109.lisp.

Direct superclasses

cookie-error.

Direct methods
Direct slots
Slot: version
Initargs

:version

Readers

unparseable-cookie-version.

Writers

This slot is read-only.

Initargs

:cookie-string

Readers

unparseable-cookie-cookie-string.

Writers

This slot is read-only.

Slot: message
Initargs

:message

Readers

unparseable-cookie-message.

Writers

This slot is read-only.


4.2.6 Structures

Cookie struct - useful for manipulating cookie values. Please note that just because it’s a valid cookie structure doesn’t mean that it’s a valid cookie. See documentation for COOKIE-STRING for parameter information.

Package

rfc2109.

Source

rfc2109.lisp.

Direct superclasses

structure-object.

Direct methods

print-object.

Direct slots
Slot: name
Type

string

Initform

""

Readers

cookie-name.

Writers

(setf cookie-name).

Slot: value
Type

string

Initform

""

Readers

cookie-value.

Writers

(setf cookie-value).

Slot: comment
Type

(or string null)

Readers

cookie-comment.

Writers

(setf cookie-comment).

Slot: domain
Type

(or string null)

Readers

cookie-domain.

Writers

(setf cookie-domain).

Slot: max-age
Type

(or (integer 0) null)

Readers

cookie-max-age.

Writers

(setf cookie-max-age).

Slot: path
Type

(or string null)

Readers

cookie-path.

Writers

(setf cookie-path).

Slot: secure
Type

boolean

Readers

cookie-secure.

Writers

(setf cookie-secure).


4.2.7 Classes

Class: load-file-with-tests
Package

rfc2109-system.

Source

rfc2109.asd.

Direct superclasses

cl-source-file.

Direct methods

Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (  
A   C   D   E   F   G   I   L   M   O   P   Q   R   S   T   U   V   W  
Index Entry  Section

(
(setf cookie-comment): Public ordinary functions
(setf cookie-domain): Public ordinary functions
(setf cookie-max-age): Public ordinary functions
(setf cookie-name): Public ordinary functions
(setf cookie-path): Public ordinary functions
(setf cookie-secure): Public ordinary functions
(setf cookie-value): Public ordinary functions

A
attr?: Private ordinary functions

C
char-el?: Private ordinary functions
cleave-sequence: Private ordinary functions
cookie-comment: Public ordinary functions
cookie-domain: Public ordinary functions
cookie-max-age: Public ordinary functions
cookie-name: Public ordinary functions
cookie-p: Public ordinary functions
cookie-path: Public ordinary functions
cookie-secure: Public ordinary functions
cookie-string: Public ordinary functions
cookie-string-exceeds-minimum-length-cookie-string: Private generic functions
cookie-string-exceeds-minimum-length-cookie-string: Private generic functions
cookie-string-from-cookie-struct: Public ordinary functions
cookie-string-too-long?: Private ordinary functions
cookie-value: Public ordinary functions
copy-cookie: Private ordinary functions
correct: Private macros
crlf-el?: Private ordinary functions
ctl-el?: Private ordinary functions

D
domain-match-p: Public ordinary functions

E
ensure-pair: Private ordinary functions

F
Function, (setf cookie-comment): Public ordinary functions
Function, (setf cookie-domain): Public ordinary functions
Function, (setf cookie-max-age): Public ordinary functions
Function, (setf cookie-name): Public ordinary functions
Function, (setf cookie-path): Public ordinary functions
Function, (setf cookie-secure): Public ordinary functions
Function, (setf cookie-value): Public ordinary functions
Function, attr?: Private ordinary functions
Function, char-el?: Private ordinary functions
Function, cleave-sequence: Private ordinary functions
Function, cookie-comment: Public ordinary functions
Function, cookie-domain: Public ordinary functions
Function, cookie-max-age: Public ordinary functions
Function, cookie-name: Public ordinary functions
Function, cookie-p: Public ordinary functions
Function, cookie-path: Public ordinary functions
Function, cookie-secure: Public ordinary functions
Function, cookie-string: Public ordinary functions
Function, cookie-string-from-cookie-struct: Public ordinary functions
Function, cookie-string-too-long?: Private ordinary functions
Function, cookie-value: Public ordinary functions
Function, copy-cookie: Private ordinary functions
Function, crlf-el?: Private ordinary functions
Function, ctl-el?: Private ordinary functions
Function, domain-match-p: Public ordinary functions
Function, ensure-pair: Private ordinary functions
Function, lws-el?: Private ordinary functions
Function, make-cookie: Public ordinary functions
Function, octet-el?: Private ordinary functions
Function, parse-cookies: Public ordinary functions
Function, parse-cookies-v1: Private ordinary functions
Function, parse-cookies-vnetscape: Private ordinary functions
Function, print-cookie: Private ordinary functions
Function, qdtext?: Private ordinary functions
Function, quote-around: Private ordinary functions
Function, quoted-string?: Private ordinary functions
Function, remove-escaped-quotes: Private ordinary functions
Function, remove-quotes-around: Private ordinary functions
Function, safe-parse-cookies: Public ordinary functions
Function, split-along-lws: Private ordinary functions
Function, split-along-quoted-lws: Private ordinary functions
Function, text-el?: Private ordinary functions
Function, text?: Private ordinary functions
Function, token-el?: Private ordinary functions
Function, token?: Private ordinary functions
Function, trim-spaces: Private ordinary functions
Function, tspecial-el?: Private ordinary functions
Function, valid-domain?: Private ordinary functions
Function, valid-name?: Private ordinary functions
Function, value?: Private ordinary functions
Function, word?: Private ordinary functions

G
Generic Function, cookie-string-exceeds-minimum-length-cookie-string: Private generic functions
Generic Function, invalid-cookie-parameter-message: Private generic functions
Generic Function, invalid-cookie-parameter-parameter: Private generic functions
Generic Function, invalid-cookie-parameter-value: Private generic functions
Generic Function, unparseable-cookie-cookie-string: Private generic functions
Generic Function, unparseable-cookie-message: Private generic functions
Generic Function, unparseable-cookie-version: Private generic functions

I
invalid-cookie-parameter-message: Private generic functions
invalid-cookie-parameter-message: Private generic functions
invalid-cookie-parameter-parameter: Private generic functions
invalid-cookie-parameter-parameter: Private generic functions
invalid-cookie-parameter-value: Private generic functions
invalid-cookie-parameter-value: Private generic functions

L
lws-el?: Private ordinary functions

M
Macro, correct: Private macros
Macro, optional: Private macros
Macro, try-quotes: Private macros
make-cookie: Public ordinary functions
Method, cookie-string-exceeds-minimum-length-cookie-string: Private generic functions
Method, invalid-cookie-parameter-message: Private generic functions
Method, invalid-cookie-parameter-parameter: Private generic functions
Method, invalid-cookie-parameter-value: Private generic functions
Method, output-files: Public standalone methods
Method, perform: Public standalone methods
Method, print-object: Public standalone methods
Method, unparseable-cookie-cookie-string: Private generic functions
Method, unparseable-cookie-message: Private generic functions
Method, unparseable-cookie-version: Private generic functions

O
octet-el?: Private ordinary functions
optional: Private macros
output-files: Public standalone methods

P
parse-cookies: Public ordinary functions
parse-cookies-v1: Private ordinary functions
parse-cookies-vnetscape: Private ordinary functions
perform: Public standalone methods
print-cookie: Private ordinary functions
print-object: Public standalone methods

Q
qdtext?: Private ordinary functions
quote-around: Private ordinary functions
quoted-string?: Private ordinary functions

R
remove-escaped-quotes: Private ordinary functions
remove-quotes-around: Private ordinary functions

S
safe-parse-cookies: Public ordinary functions
split-along-lws: Private ordinary functions
split-along-quoted-lws: Private ordinary functions

T
text-el?: Private ordinary functions
text?: Private ordinary functions
token-el?: Private ordinary functions
token?: Private ordinary functions
trim-spaces: Private ordinary functions
try-quotes: Private macros
tspecial-el?: Private ordinary functions

U
unparseable-cookie-cookie-string: Private generic functions
unparseable-cookie-cookie-string: Private generic functions
unparseable-cookie-message: Private generic functions
unparseable-cookie-message: Private generic functions
unparseable-cookie-version: Private generic functions
unparseable-cookie-version: Private generic functions

V
valid-domain?: Private ordinary functions
valid-name?: Private ordinary functions
value?: Private ordinary functions

W
word?: Private ordinary functions