ns_cookie(n) 5.0.0a naviserver "NaviServer Built-In Commands"

Name

ns_cookie - HTTP cookies

Table Of Contents
Synopsis
Description
COMMANDS
OPTIONS
EXAMPLES
See Also
Keywords

Synopsis

ns_setcookie ?-discard bool? ?-domain d? ?-expires t? ?-path p? ?-replace bool? ?-scriptable bool? ?-secure bool? ?--? name data
ns_getcookie ?-all bool? ?-include_set_cookies bool? ?--? name ?default?
ns_deletecookie ?-domain d? ?-path p? ?-replace bool? ?-samesite t? ?-secure bool? ?--? name

Cookies are small pieces of data which the server sends to the user agent and the user agent sends back during subsequent requests. You can use this mechanism to save state between otherwise stateless HTTP requests.

Cookie size limits are user agent dependent. Practically, as cookies are sent with every request to the server (for which the optional domain and path match), size should be kept to a minimum.

These commands implement the original version 1 Netscape cookie protocol which is widely supported by user agents.

COMMANDS

ns_setcookie ?-discard bool? ?-domain d? ?-expires t? ?-path p? ?-replace bool? ?-scriptable bool? ?-secure bool? ?--? name data

Send data to the user agent as a cookie, using name as the identifier. The user agent will send the cookie data back to the server during subsequent requests for which the domain and path match, if it has not expired. If the provided domain is empty, it is ignored.

A cookie is identified by a signature which is made up of its name, domain, path and secure flag. A cookie named foo with path /x/y is a different cookie than one named foo with path /x/y/z. During a request for the URL /x/y/z both cookies named foo are sent.

The data will be URL-encoded to escape special characters. ns_getcookie correctly reverses the encoding.

ns_getcookie ?-all bool? ?-include_set_cookies bool? ?--? name ?default?

Get the cookie data identified by name. If no such cookie exists then default is returned. If default is not given and no such cookie exists, an error is raised. When the option ?-include_set_cookies? is set true, then this command will search as well in the cookies being currently set in the output headers.

By default, only the first cookie identified by name is returned. If two cookies with the same name are sent by the user agent, each with a different domain and/or path, which cookie data is returned depends on the user agent. When the option ?-all? is set, all cookies with the specified name are returned. This can be use to detect such situations with multiple cookies. The option ?-all? cannot be set together with the option ?-include_set_cookies?.

When using domain or path to restrict cookies, it is recommended to use a unique name for each restricted cookie.

ns_deletecookie ?-domain d? ?-path p? ?-replace bool? ?-samesite t? ?-secure bool? ?--? name

Instruct the client to delete the cookie data identified by name. The complete cookie signature including domain and path must match for the cookie to be deleted. If the provided domain is empty, it is ignored.

OPTIONS

-discard boolean

If the discard option is true then the cookie will be automatically deleted at the end of the current session (when the user agent terminates).

-domain domain

Restrict the cookie to a domain name, such as example.com. The current domain is implied if none is specified.

-expires time

The cookie will expire the given time, after which the client will no longer send the cookie back to the server. The time value can be specified in the form secs?:microsecs?, or secs.fraction, or as a number with a time unit. If time is large it is treated as the absolute time in the future when the cookie should expire. The special value -1 may be used to indicate that the cookie should never expire.

-path path

Restrict the cookie to a URL path such as /foo/bar. If no path is specified then the cookie will be back sent to the server for all requests. If a path is specified the cookie will only be sent back for requests which match the specified path, or a sub-path.

-replace boolean

If the replace option is true the cookie being set or deleted is as well deleted from the current output header set if provided there. The default value is false.

-samesite strict|lax|none

When the flag is set it prevents the browser from sending this cookie along with cross-site requests to mitigate cross site scripting attacks. Permissible values are strict, lax (default), or none (only allowed together with -secure). While the value strict prevents sending the cookie to the target site in all cross-site browsing context, the value of lax allows sending the cookie when the user clicks on regular links. For details, see https://www.owasp.org/index.php/SameSite

-scriptable boolean

If the scriptable option is false or not given the cookie is unavailable to JavaScript on the client. This can prevent cross site scripting attacks (XSS) on clients which support the HttpOnly option. Set -scriptable to true if you need to access the cookie via JavaScript.

-secure boolean

If the secure option is true then the cookie will only be sent back to the server when the client uses a secure (TLS/SSL) connection.

The expiry time is valid across browser sessions. If no expiry is specified then the cookie will expire when the browser session ends, which is usually when the user closes their browser.

EXAMPLES

Track all user agents which ever visited our site:

 proc browser_tracking_filter {} {
   if {![ns_getcookie first_visit 0]} {
     ns_setcookie -expires -1 -- first_visit [clock seconds]
   }
 }
 ns_register_filter preauth GET /* browser_tracking_filter

Keywords

cookie, server built-in, session