···
- IP addresses require exact match only
- Path matching requires exact match or prefix with "/" separator
48
-
@see <https://datatracker.ietf.org/doc/html/rfc6265> RFC 6265 - HTTP State Management Mechanism *)
48
+
@see <https://datatracker.ietf.org/doc/html/rfc6265> RFC 6265 - HTTP State Management Mechanism
50
+
{2 Standards and References}
52
+
This library implements and references the following IETF specifications:
55
+
{- {{:https://datatracker.ietf.org/doc/html/rfc6265}RFC 6265} -
56
+
HTTP State Management Mechanism (April 2011) - Primary specification}
57
+
{- {{:https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis}RFC 6265bis} -
58
+
Cookies: HTTP State Management Mechanism (Draft) - SameSite attribute and modern updates}
59
+
{- {{:https://datatracker.ietf.org/doc/html/rfc1034#section-3.5}RFC 1034 Section 3.5} -
60
+
Domain Names - Preferred Name Syntax for domain validation}
61
+
{- {{:https://datatracker.ietf.org/doc/html/rfc2616#section-2.2}RFC 2616 Section 2.2} -
62
+
HTTP/1.1 - Token syntax definition}
63
+
{- {{:https://datatracker.ietf.org/doc/html/rfc1123#section-5.2.14}RFC 1123 Section 5.2.14} -
64
+
Internet Host Requirements - Date format (rfc1123-date)}}
66
+
Additional standards:
68
+
{- {{:https://publicsuffix.org/}Mozilla Public Suffix List} - Registry
69
+
of public suffixes for cookie domain validation per RFC 6265 Section 5.3 Step 5}} *)
···
Validation functions for cookie names, values, and attributes per
{{:https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1} RFC 6265 Section 4.1.1}.
290
+
These functions implement the syntactic requirements from RFC 6265 to ensure
291
+
cookies conform to the specification before being sent in HTTP headers.
292
+
All validation failures return detailed error messages citing the specific
293
+
RFC requirement that was violated.
295
+
{2 Validation Philosophy}
297
+
Per RFC 6265 Section 4, there is an important distinction between:
298
+
- {b Server requirements} (Section 4.1): Strict syntax for generating Set-Cookie headers
299
+
- {b User agent requirements} (Section 5): Lenient parsing for receiving Set-Cookie headers
301
+
These validation functions enforce the {b server requirements}, ensuring that
302
+
cookies generated by this library conform to RFC 6265 syntax. When parsing
303
+
cookies from HTTP headers, the library may be more lenient to maximize
304
+
interoperability with non-compliant servers.
306
+
{2 Character Set Requirements}
308
+
RFC 6265 restricts cookies to US-ASCII characters with specific exclusions:
309
+
- Cookie names: RFC 2616 tokens (no CTLs, no separators)
310
+
- Cookie values: cookie-octet characters (0x21, 0x23-0x2B, 0x2D-0x3A, 0x3C-0x5B, 0x5D-0x7E)
311
+
- Domain values: RFC 1034 domain name syntax or IP addresses
312
+
- Path values: Any character except CTLs and semicolon
These functions return [Ok value] on success or [Error msg] with a detailed
explanation of why validation failed.
···
Cookie names must be valid RFC 2616 tokens: one or more characters
excluding control characters and separators.
326
+
Per {{:https://datatracker.ietf.org/doc/html/rfc2616#section-2.2}RFC 2616 Section 2.2},
327
+
a token is defined as: one or more characters excluding control characters
328
+
and the following 19 separator characters: parentheses, angle brackets, at-sign,
329
+
comma, semicolon, colon, backslash, double-quote, forward slash, square brackets,
330
+
question mark, equals, curly braces, space, and horizontal tab.
332
+
This means tokens consist of visible ASCII characters (33-126) excluding
333
+
control characters (0-31, 127) and the separator characters listed above.
@param name The cookie name to validate
@return [Ok name] if valid, [Error message] with explanation if invalid
283
-
@see <https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1> RFC 6265 Section 4.1.1 *)
338
+
@see <https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1> RFC 6265 Section 4.1.1
339
+
@see <https://datatracker.ietf.org/doc/html/rfc2616#section-2.2> RFC 2616 Section 2.2 - Basic Rules *)
val cookie_value : string -> (string, string) result
(** Validate a cookie value per RFC 6265.
···
double quotes. Invalid characters include: control characters, space,
double quote (except as wrapper), comma, semicolon, and backslash.
348
+
Per {{:https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1}RFC 6265 Section 4.1.1},
349
+
cookie-value may be:
350
+
- Zero or more cookie-octet characters, or
351
+
- Double-quoted string containing cookie-octet characters
353
+
Where cookie-octet excludes: CTLs (0x00-0x1F, 0x7F), space (0x20),
354
+
double-quote (0x22), comma (0x2C), semicolon (0x3B), and backslash (0x5C).
356
+
Valid cookie-octet characters: 0x21, 0x23-0x2B, 0x2D-0x3A, 0x3C-0x5B, 0x5D-0x7E
@param value The cookie value to validate
@return [Ok value] if valid, [Error message] with explanation if invalid
···
- A valid domain name per RFC 1034 Section 3.5
371
+
Per {{:https://datatracker.ietf.org/doc/html/rfc1034#section-3.5}RFC 1034 Section 3.5},
372
+
preferred domain name syntax requires:
373
+
- Labels separated by dots
374
+
- Labels must start with a letter
375
+
- Labels must end with a letter or digit
376
+
- Labels may contain letters, digits, and hyphens
377
+
- Labels are case-insensitive
378
+
- Total length limited to 255 octets
380
+
Leading dots are stripped per RFC 6265 Section 5.2.3 before validation.
@param domain The domain value to validate (leading dot is stripped first)
@return [Ok domain] if valid, [Error message] with explanation if invalid
anil.recoil.org