$webinfo: Cookie Topics

Use these topics to set the properties of a cookie and write state information to a cookie.

Description

A cookie is set at the browser only if you explicitly set it using the $webinfo("UserContext") instruction.

For more information, see Uniface Cookies and Using Uniface Default Cookies for State Management.

CookiesIn

The $webinfo("CookiesIn") topic returns an associative list of cookies present in the request:

CookieName1 = Value1 ;CookieName2 = Value2...

UserContext

The $webinfo("UserContext") function sets a Uniface list specifying information for a single, unnamed cookie. The first element is the data of the cookie; subsequent elements specify the cookie attributes.

CookiesOut

The $webinfo("CookiesOut") function sets an associative list of multiple, named cookies to be set in the response. Each cookie has name and value, followed by an optional list of cookie attributes, which can occur in any order:

Cookie = Value {;expires=Seconds} {;domain=Domain} {;path=Path} {;secure=T | F} {httponly=T | F} {;version=CookieVersion} {;encodingversion=EncodingVersion}

Cookie Contents and Attributes
Attributes Description
Cookie = Value Name and value of the cookie; the value can also be an associative list.
expires=Seconds Number of seconds that the new user context remains valid. If a request is made after the expiration time has elapsed, no cookie will be sent with the request. If not specified, the cookie is a session cookie. A value of 0 (seconds) deletes the cookie.
domain=Domain Web server domain for which the new user context is valid
path=Path Web server path on the domain for which the new user context is valid
secure=T | F Determines whether the cookie is secure, meaning that it is only used if the server is accessed via HTTPS. It ensures that the cookie is always encrypted when transmitting from client to server, making it less vulnerable to cookie theft via eavesdropping.

If not set, Uniface sets it to true when HTTPS is used; see Secure Cookies.

httponly=T | F

Determines whether the cookie can be shared between the web server and other sources, such as JavaScript. By default, it is set to T, which ensures that the cookie can only be sent back to the web server on further HTTP(S) requests, and it cannot be accessed from JavaScript.

Note:  This behavior is browser-specific, but most new browsers handle this correctly.

Note:  This property is only applied if the WRD runs in a web server or servlet engine that supports the Java Servlet API 3.0, such as Apache Tomcat .

version=0 | 1 Version of HTTP state maintenance to which the cookie conforms:
  • 0—Netscape specification (the default)
  • 1—RFC 2109 specification
encodingversion=0 | 1 | 2 Encoding version; used only when encoding is needed:
  • 0—Use default. If encoding is needed, encoding version 2 is used.
  • 1—URL encoded. Encodes the UTF-8 byte array of the cookie value, when needed.
  • 2—Base64 encoded, when needed.

When encoding is in effect, the cookie value is modified as follows:

  • The cookie value is prefixed with ENC#1: or ENC#2: to indicate the encoding used.
  • For ENC#1:, the Uniface list separator (;) is replaced by ampersand &.

There is no limit on the length of the cookie string, but limitations are imposed by some web servers. (4 Kb is a widely accepted maximum size for cookies). This value can be set and is available in the next request.

The cookie is stored on the client browser. If a cookie does not change, it should not be present in the list.

Secure Cookies

The default value of the secure attribute depends on whether the request is sent over HTTP or HTTPS. If it is not specified, it defaults to:

  • T if the request is sent via an HTTPS secured connection (the server variable SERVER_PORT_SECURE=1 in WebServerContext).
  • F if the request is sent by an HTTP connection (the server variable SERVER_PORT_SECURE=0 in WebServerContext)

For more information, see Cookies Containing Sensitive Data.

Named Cookies

A simple example of two named cookies:

cookie1=name=John!!;birthday=19840911!;expires=3600!;version=1!; ... ;cookie2=...

Constructing a Session Cookie

The following example creates a session cookie (which expires when the session on the browser is closed). By default, the httponly property is set to true, so there is no need to include it in the properties list. (It will be ignored if the servlet engine does not support Servlet API 3.0)

variables
  string vSessionId, vRandomKey, vCookieValue, vCookie
endvariables

; Generate the session ID
vRandomKey = "hH6WuPo5UUZ5iXf9YGO1o95GsbnFhya"
vSessionId = $encode("HEX",$encode("HMAC_MD5", $uuid, vRandomKey))

; Set generated session ID in cookie
putitem/id vCookieValue, "sid", vSessionId

; Set the cookie value and attributes
putitem vCookie, -1, vCookieValue
putitem/id vCookie, "version", "1"    ; type 1 cookie

Assign the list to the COOKIESOUT topic
putitem/id $webinfo("COOKIESOUT"), "MYSESSION", vCookie

Constructing Encoded Cookies

The following ProcScript fragment builds up two named cookies, COOKIE1 with cookie version 1 and encoding version 1, and COOKIE2 with only a simple value.

variables
  string  vCookieValue, vCookie1
endvariables

putitem/id vCookieValue, "name", "John Bunyan"
putitem/id vCookieValue, "birthday", "19700416"

putitem vCookie1, -1, vCookieValue
putitem/id vCookie1, "version", "1"
putitem/id vCookie1, "encodingversion", "1"

putitem/id $webinfo("COOKIESOUT"), "COOKIE1", vCookie1
putitem/id $webinfo("COOKIESOUT"), "COOKIE2", "VALUEONLY"

Various cookie values, with encoding version set to 1, are shown in the following examples:

No encoding needed:

name=John

Cookie version 0; space replaced by hex value:

ENC#1:name=John%20Bunyan

Cookie version 1; space allowed, encoding not needed:

name=John Bunyan

Cookie version 1; GOLD ; (;) replaced by &

ENC#1:name=John Bunyan&birthday=19700416