Cookie Plus (cookieplus)

Description

The cookieplus vmod allows you to get, add, delete, and keep Cookie and Set-Cookie values. It also allows you to remove unused client side Cookies.

All functions will by default parse Cookies from the req.http.Cookie and Set-Cookies from resp.http.Set-Cookie, unless otherwise specified. Backend context is supported.

All functions keep an internal state of Cookies and Set-Cookies until written out using write() or setcookie_write().

Set-Cookie operations all have a setcookie prefix and can only be used where a resp or beresp object exists.

Examples

Cookie Filtering

Only allow application specific Cookies.

vcl 4.0;

import cookieplus;

sub vcl_recv
{
  // Keep these Cookies
  cookieplus.keep("JSESSIONID");
  cookieplus.keep_regex("^BNES_SSESS");
  cookieplus.keep_regex("^SSESS[a-zA-Z0-9]+$");
  cookieplus.keep_regex("^SESS[a-zA-Z0-9]+$");

  // Any Cookie that is not kept will be removed
  cookieplus.write();
}

Conditional Cookie Filtering

Conditionally allow application specific Cookies.

vcl 4.0;

import cookieplus;

sub vcl_recv
{
  // Mark all Cookies for removal
  cookieplus.keep("");

  // Only allow these Cookies if the URL allows for it
  if (req.url ~ "^/admin") {
    cookieplus.keep("JSESSIONID");
    cookieplus.keep_regex("^BNES_SSESS");
    cookieplus.keep_regex("^SSESS[a-zA-Z0-9]+$");
    cookieplus.keep_regex("^SESS[a-zA-Z0-9]+$");
  }

  // Any Cookie that is not kept will be removed
  cookieplus.write();
}

VCL Cookies

Add a VCL cookie.

vcl 4.0;

import cookieplus;
import std;

sub vcl_deliver
{
  // Get the vcpsess Cookie value
  set req.http.X-vcpsess = cookieplus.get("vcpsess", "");

  if (req.http.X-vcpsess == "") {
    // Create a new random vcpsess value
    set req.http.X-vcpsess = std.random(1, 10000000) + "." + std.random(1, 10000000);

    // Create a vcpsess Set-Cookie, valid for 30 days
    cookieplus.setcookie_add("vcpsess", req.http.X-vcpsess, 30d, req.http.Host, "/");

    // Write the Set-Cookie to the response
    cookieplus.setcookie_write();
  }

  // req.http.X-vcpsess now contains the vcpsess cookie value
}

Set-Cookie Filtering

Only allow application specific Set-Cookie values from the backend.

vcl 4.0;

import cookieplus;

sub vcl_backend_response
{
  // Mark all Set-Cookies for removal
  cookieplus.setcookie_keep("");

  // Only allow these Set-Cookies if the URL allows for it
  if (bereq.url ~ "^/admin") {
    cookieplus.setcookie_keep("JSESSIONID");
    cookieplus.setcookie_keep_regex("^BNES_SSESS");
    cookieplus.setcookie_keep_regex("^SSESS[a-zA-Z0-9]+$");
    cookieplus.setcookie_keep_regex("^SESS[a-zA-Z0-9]+$");
  }

  // Any Set-Cookie that is not kept will be removed
  cookieplus.setcookie_write();
}

Client Cookie Removal

Conditionally allow application specific Cookies and remove all other Cookies from the client.

vcl 4.0;

import cookieplus;

sub vcl_recv
{
  // Mark all Cookies for removal
  cookieplus.keep("");

  // Only allow these Cookies if the URL allows for it
  if (req.url ~ "^/admin") {
    cookieplus.keep("JSESSIONID");
    cookieplus.keep_regex("^BNES_SSESS");
    cookieplus.keep_regex("^SSESS[a-zA-Z0-9]+$");
    cookieplus.keep_regex("^SESS[a-zA-Z0-9]+$");
  }

  // Any Cookie that is not kept will be removed
  cookieplus.write();
}

sub vcl_backend_response
{
  // Mark all Set-Cookies for removal
  cookieplus.setcookie_keep("");

  // Only allow these Set-Cookies if the URL allows for it
  if (bereq.url ~ "^/admin") {
    cookieplus.setcookie_keep("JSESSIONID");
    cookieplus.setcookie_keep_regex("^BNES_SSESS");
    cookieplus.setcookie_keep_regex("^SSESS[a-zA-Z0-9]+$");
    cookieplus.setcookie_keep_regex("^SESS[a-zA-Z0-9]+$");
  }

  // Any Set-Cookie that is not kept will be removed
  cookieplus.setcookie_write();
}

sub vcl_deliver
{
  // Do not attempt to delete these Cookies from the client
  // as they may have been conditionally removed, but we want
  // to keep them.
  cookieplus.remove_deleted("JSESSIONID");
  cookieplus.remove_deleted_regex("^BNES_SSESS");
  cookieplus.remove_deleted_regex("^SSESS[a-zA-Z0-9]+$");
  cookieplus.remove_deleted_regex("^SESS[a-zA-Z0-9]+$");

  // Do not delete Google Analytic Cookies
  cookieplus.remove_deleted("_ga");
  cookieplus.remove_deleted("_git");
  cookieplus.remove_deleted("_gat");
  cookieplus.remove_deleted_regex("^__ut..$");

  // Delete all other Cookies that were sent in the request
  cookieplus.setcookie_add_deleted();
  cookieplus.setcookie_write();
}

API

get

STRING get(STRING name, STRING default = 0, ENUM {FIRST, LAST} occurrence = FIRST)

Get the first Cookie value for name, If not found, default is returned.

Arguments:

• name accepts type STRING

• default accepts type STRING with a default value of 0 optional

• occurrence is an ENUM that accepts values of FIRST, and LAST with a default value of FIRST optional

Type: Function

Returns: String

get_regex

STRING get_regex(STRING regex, STRING default = 0)

Get the first Cookie value which matches regex. The regex is matched on the name only. If not found, default is returned.

Arguments:

• regex accepts type STRING

• default accepts type STRING with a default value of 0 optional

Type: Function

Returns: String

add

VOID add(STRING name, STRING value, BOOL keep = 1, BOOL override = 1)

Add a Cookie with name and value. If in keep_mode and keep is true, cookie value is kept when writing.

Arguments:

• name accepts type STRING

• value accepts type STRING

• keep accepts type BOOL with a default value of 1 optional

• override accepts type BOOL with a default value of 1 optional

Type: Function

Returns: None

delete

VOID delete(STRING name, BOOL delete_keep = 0)

Delete all cookies that match name. If delete_keep is true, delete kept cookies.

Arguments:

• name accepts type STRING

• delete_keep accepts type BOOL with a default value of 0 optional

Type: Function

Returns: None

delete_regex

VOID delete_regex(STRING regex, BOOL delete_keep = 0)

Delete all cookies that match regex. The regex is matched on the name only. If delete_keep is true, delete kept cookies.

Arguments:

• regex accepts type STRING

• delete_keep accepts type BOOL with a default value of 0 optional

Type: Function

Returns: None

keep

VOID keep(STRING name)

Keep cookies which match name. This enables keep_mode. When writing, only cookies which have been kept are written.

Arguments:

• name accepts type STRING

Type: Function

Returns: None

keep_regex

VOID keep_regex(STRING regex)

Keep cookies which match regex. This enables keep_mode. When writing, only cookies which have been kept are written.

Arguments:

• regex accepts type STRING

Type: Function

Returns: None

remove_deleted

VOID remove_deleted(STRING name)

CookiePlus keeps track of what Cookies have been deleted. This is so you can delete them from the client using setcookie_add_deleted(). This function removes a Cookie from the deleted list, so it cannot be removed from the client.

Arguments:

• name accepts type STRING

Type: Function

Returns: None

remove_deleted_regex

VOID remove_deleted_regex(STRING regex)

CookiePlus keeps track of what Cookies have been deleted. This is so you can delete them from the client using setcookie_add_deleted(). This function removes Cookies which match regex from the deleted list, so they cannot be removed from the client.

Arguments:

• regex accepts type STRING

Type: Function

Returns: None

remove_duplicate

VOID remove_duplicate(STRING name, ENUM {FIRST, LAST} keep = FIRST)

Removes all duplicates of a given name. Can keep either the first or last occurrence.

Arguments:

• name accepts type STRING

• keep is an ENUM that accepts values of FIRST, and LAST with a default value of FIRST optional

Type: Function

Returns: None

remove_all_duplicates

VOID remove_all_duplicates(ENUM {FIRST, LAST} keep = FIRST)

Removes all duplicate cookies. Can retain either the first or last occurrence.

Arguments:

• keep is an ENUM that accepts values of FIRST, and LAST with a default value of FIRST optional

Type: Function

Returns: None

count

INT count()

The number of cookies which will be written.

Arguments: None

Type: Function

Returns: Int

write

VOID write()

Write cookies back out to the ‘Cookie’ header.

Arguments: None

Type: Function

Returns: None

as_string

STRING as_string()

Return Cookie header string. Can be used to write cookies to a different header.

Arguments: None

Type: Function

Returns: String

parse

VOID parse(STRING cookies)

Parse cookies from cookies string. Any internal state is reset.

Arguments:

• cookies accepts type STRING

Type: Function

Returns: None

reset

VOID reset()

Reset the internal state.

Arguments: None

Type: Function

Returns: None

regsub

VOID regsub(STRING name, ENUM {NAME, VALUE} where, STRING pattern, STRING replace, BOOL repeat = 0)

Cookies that match the regular expression name can have their name or value substituted based off the regular expression pattern with replace.

Arguments:

• name accepts type STRING

• pattern accepts type STRING

• replace accepts type STRING

• repeat accepts type BOOL with a default value of 0 optional

• where is an ENUM that accepts values of NAME, and VALUE

Type: Function

Returns: None

setcookie_get

STRING setcookie_get(STRING name, STRING default = 0)

Get the first Set-Cookie value for name. If not found, default is returned.

Arguments:

• name accepts type STRING

• default accepts type STRING with a default value of 0 optional

Type: Function

Returns: String

setcookie_get_regex

STRING setcookie_get_regex(STRING regex, STRING default = 0)

Get the first Set-Cookie value for regex. The regex is matched on the name only. If not found, default is returned.

Arguments:

• regex accepts type STRING

• default accepts type STRING with a default value of 0 optional

Type: Function

Returns: String

setcookie_add

VOID setcookie_add(STRING name, STRING value, DURATION ttl = 0, STRING domain = "", STRING path = "", BOOL secure = 0, BOOL httponly = 0, STRING extra = "", BOOL keep = 1, BOOL override = 1)

Add a Set-Cookie.

Arguments:

• name accepts type STRING

• value accepts type STRING

• ttl accepts type DURATION with a default value of 0 optional

• domain accepts type STRING with a default value of empty. optional

• path accepts type STRING with a default value of empty. optional

• secure accepts type BOOL with a default value of 0 optional

• httponly accepts type BOOL with a default value of 0 optional

• extra accepts type STRING with a default value of empty. optional

• keep accepts type BOOL with a default value of 1 optional

• override accepts type BOOL with a default value of 1 optional

Type: Function

Returns: None

setcookie_add_deleted

VOID setcookie_add_deleted(BOOL keep = 1)

Add a Set-Cookie for each deleted cookie.

Arguments:

• keep accepts type BOOL with a default value of 1 optional

Type: Function

Returns: None

setcookie_delete

VOID setcookie_delete(STRING name, BOOL delete_keep = 0)

Delete all Set-Cookie headers that match name.

Arguments:

• name accepts type STRING

• delete_keep accepts type BOOL with a default value of 0 optional

Type: Function

Returns: None

setcookie_delete_regex

VOID setcookie_delete_regex(STRING regex, BOOL delete_keep = 0)

Delete all Set-Cookie headers that match regex. The regex is matched on the name only.

Arguments:

• regex accepts type STRING

• delete_keep accepts type BOOL with a default value of 0 optional

Type: Function

Returns: None

setcookie_keep

VOID setcookie_keep(STRING name)

Keep Set-Cookies which match name. This enables keep_mode. When writing, only Set-Cookies which have been kept are written.

Arguments:

• name accepts type STRING

Type: Function

Returns: None

setcookie_keep_regex

VOID setcookie_keep_regex(STRING regex)

Keep Set-Cookies which match regex. This enables keep_mode. When writing, only Set-Cookies which have been kept are written.

Arguments:

• regex accepts type STRING

Type: Function

Returns: None

setcookie_count

INT setcookie_count()

The number of Set-Cookies which will be written.

Arguments: None

Type: Function

Returns: Int

setcookie_write

VOID setcookie_write(HEADER header = 0)

Write Set-Cookies back out to the ‘Set-Cookie’ header. Override with header.

Arguments:

• header accepts type HEADER with a default value of 0 optional

Type: Function

Returns: None

setcookie_parse

VOID setcookie_parse(HEADER header)

Parse Set-Cookie(s) from header.

Arguments:

• header accepts type HEADER

Type: Function

Returns: None

setcookie_reset

VOID setcookie_reset()

Reset the internal Set-Cookie state.

Arguments: None

Type: Function

Returns: None

setcookie_regsub

VOID setcookie_regsub(STRING name, ENUM {NAME, VALUE, ATTRIBUTES} where, STRING pattern, STRING replace, BOOL repeat = 0)

Set-Cookies that match the regular expression name can have their name, value or attributes substituted based off the regular expression pattern with replace.

Arguments:

• name accepts type STRING

• pattern accepts type STRING

• replace accepts type STRING

• repeat accepts type BOOL with a default value of 0 optional

• where is an ENUM that accepts values of NAME, VALUE, and ATTRIBUTES

Type: Function

Returns: None

as_json

STRING as_json(STRING prefix = 0, ENUM {COOKIE, SETCOOKIE, BOTH} print = BOTH)

Return Cookie name and value pairs as JSON.

Arguments:

• prefix accepts type STRING with a default value of 0 optional

• print is an ENUM that accepts values of COOKIE, SETCOOKIE, and BOTH with a default value of BOTH optional

Type: Function

Returns: String

Availability

The cookieplus VMOD is available in Varnish Enterprise version 6.0.0r0 and later.