Cookie Plus (cookieplus)

Description

vmod-cookieplus is an advanced Cookie VMOD for interacting with request and response Cookies. vmod-cookieplus 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.

Example VCL

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 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();
}

Functions

get

STRING get(STRING name, STRING default)

• Description

  Get the Cookie value for name.

• Return value

  The Cookie value for name. If not found, default is returned.

  • name

    The name of the Cookie. The first Cookie to match is used.

  • default

    The return value if name is not found. Optional.

get_regex

STRING get_regex(STRING regex, STRING default)

• Description

  Get the Cookie value where the name matches regex.

• Return value

  The Cookie value where the name matches regex. If not found, default is returned.

  • regex

    The regular expression used to match on the name. Only the first matching Cookie is used. This value is static and cannot change between calls.

  • default

    The return value if no matching Cookie is not found. Optional.

add

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

• Description

  Add a Cookie with name and value.

• Return value

  None

  • name

    The name of the Cookie to add.

  • value

    The value of the Cookie to add.

  • keep

    If in keep_mode and keep is true, the Cookie is always kept when writing. Defaults to true.

  • override

    If the cookie exists, override it. Defaults to true.

delete

VOID delete(STRING name, BOOL delete_keep = false)

• Description

  Delete all Cookies that match name.

• Return value

  None.

  • name

    The name of the Cookie to delete. All Cookies which match name are deleted.

  • delete_keep

    If delete_keep is true, delete kept Cookies. Defaults to false.

delete_regex

VOID delete_regex(STRING regex, BOOL delete_keep = false)

• Description

  Delete all Cookies that match regex.

• Return value

  None.

  • regex

    The regular expression used to match on the name. All Cookies which match regex are deleted. This value is static and cannot change between calls.

  • delete_keep

    If delete_keep is true, delete kept Cookies. Defaults to false.

keep

VOID keep(STRING name)

• Description

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

• Return value

  None.

  • name

    The name of the Cookie to keep. All Cookies which match name are kept.

keep_regex

VOID keep_regex(STRING regex)

• Description

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

• Return value

  None.

  • regex

    The regular expression used to match on the name. All Cookies which match regex are kept. This value is static and cannot change between calls.

remove_deleted

VOID remove_deleted(STRING name)

• Description

  vmod-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.

• Return value

  None.

  • name

    The name of the Cookie to remove from the deleted Cookie list. All Cookies which match name are deleted.

remove_deleted_regex

VOID remove_deleted_regex(STRING regex)

• Description

  vmod-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.

• Return value

  None.

  • regex

    The regular expression used to match on the name of deleted Cookies. All Cookies which match regex are deleted. This value is static and cannot change between calls.

regsub

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

• Description

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

• Return value

  None.

  • name

    The name of the Cookie to modify.

  • where

    Should the name or the value be substituted.

  • pattern

    Regex pattern to match on the name or value.

  • replace

    String to repalce the value with. This string can contain backreferences.

  • repeat

    Replace all occurances. Defaults to false.

count

INT count()

• Description

  Count the number of Cookies which will be written.

• Return value

  The number of Cookies which will be written.

write

VOID write()

• Description

  Write Cookies back out to the Cookie header.

• Return value

  None.

as_string

STRING as_string()

• Description

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

• Return value

  A Cookie header formatted string.

parse

VOID parse(STRING cookies)

• Description

  Parse Cookie values from cookies.

• Return value

  None

  • cookies

    The value to parse Cookies from.

reset

VOID reset()

• Description

  Reset the internal state for Cookies.

• Return value

  None.

setcookie_get

STRING setcookie_get(STRING name, STRING default)

• Description

  Get the Set-Cookie value for name.

• Return value

  The Set-Cookie value for name. If not found, default is returned.

  • name

    The name of the Cookie. The first Set-Cookie to match is used.

  • default

    The return value if name is not found.

setcookie_get_regex

STRING setcookie_get_regex(STRING regex, STRING default)

• Description

  Get the Set-Cookie value where the name matches regex.

• Return value

  The Set-Cookie value where the name matches regex. If not found, default is returned.

  • regex

    The regular expression used to match on the name. Only the first matching Set-Cookie is used. This value is static and cannot change between calls.

  • default

    The return value if no matching Set-Cookie is not found.

setcookie_add

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

• Description

  Add a Set-Cookie.

• Return value

  None

  • name

    The Set-Cookie name.

  • value

    The Set-Cookie value.

  • ttl

    The Cookie expiration. Defaults to 0, which is a session only Cookie. A negative ttl deletes the cookie.

  • domain

    The Cookie domain. Defaults to no domain.

  • path

    The Cookie path. Defaults to no path.

  • secure

    Is this Cookie secure (HTTPS only)? Defaults to false.

  • httponly

    Is this Cookie HTTP only (no Javascript access)? Defaults to false.

  • extra

    Extra Set-Cookie attributes which are appended to the header.

  • keep

    If in keep_mode and keep is true, the Set-Cookie is always kept when writing. Defaults to true.

  • override

    If the Set-Cookie name exists, override it. Defaults to true.

setcookie_add_deleted

VOID setcookie_add_deleted(BOOL keep = true)

• Description

  Add a Set-Cookie delete headers for Cookies that were previously deleted.

• Return value

  None

  • keep

    If in keep_mode and keep is true, these Set-Cookies are always kept when writing. Defaults to true.

setcookie_delete

VOID setcookie_delete(STRING name, BOOL delete_keep = false)

• Description

  Delete all Set-Cookies that match name.

• Return value

  None.

  • name

    The name of the Set-Cookie to delete. All Set-Cookies which match name are deleted.

  • delete_keep

    If delete_keep is true, delete kept Set-Cookies. Defaults to false.

setcookie_delete_regex

VOID setcookie_delete_regex(STRING regex, BOOL delete_keep = false)

• Description

  Delete all Set-Cookies that match regex.

• Return value

  None.

  • regex

    The regular expression used to match on the name. All Set-Cookies which match regex are deleted. This value is static and cannot change between calls.

  • delete_keep

    If delete_keep is true, delete kept Set-Cookies. Defaults to false.

setcookie_keep

VOID setcookie_keep(STRING name)

• Description

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

• Return value

  None.

  • name

    The name of the Set-Cookie to keep. All Set-Cookies which match name are kept.

setcookie_keep_regex

VOID setcookie_keep_regex(STRING regex)

• Description

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

• Return value

  None.

  • regex

    The regular expression used to match on the name. All Set-Cookies which match regex are kept. This value is static and cannot change between calls.

setcookie_regsub

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

• Description

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

• Return value

  None.

  • name

    The name of the Set-Cookie to modify.

  • where

    Should the name or the value be substituted.

  • pattern

    Regex pattern to match on the name or value.

  • replace

    String to repalce the value with. This string can contain backreferences.

  • repeat

    Replace all occurances. Defaults to false.

setcookie_count

INT setcookie_count()

• Description

  Count the number of Set-Cookies which will be written.

• Return value

  The number of Set-Cookies which will be written.

setcookie_write

VOID setcookie_write(HEADER header = (be)resp.http.Set-Cookie)

• Description

  Write Set-Cookies back out to the Set-Cookie header.

• Return value

  None.

  • header

    The response header to write the Set-Cookie values to. Defaults to Set-Cookie.

setcookie_parse

VOID setcookie_parse(HEADER header)

• Description

  Parse Set-Cookie values from header.

• Return value

  None

  • header

    The header to parse Set-Cookie values from.

setcookie_reset

VOID setcookie_reset()

• Description

  Reset the internal state for Set-Cookies.

• Return value

  None.

as_json

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

• Description

  Return Cookie name and value pairs as JSON.

• Return value

  JSON formatted string of Cookie name-value pairs.

  • print

    Construct the string of only Cookies, only Set-Cookies or both Cookies and Set-cookies.