Some web service providers have a requirement that users must acknowledge some form of notice before access can be granted to an associated resource, in addition to usual access control constraints. A user attempting to access such a resource is shown a web page containing a notice (or notices) and asked to acknowledge reading it or accept its conditions, typically by performing an action indicating acceptance, and submitting an HTML form. These notices are commonly legal notices, such as copyright notices, licensing notices, restricted access notices, and terms-of-use notices. This idea can also be applied to alerting users (a warning about upcoming system maintenance, for example).

For the convenience of users, once an acknowledgement has been obtained by the system the user should not be re-prompted when the same resource is subsequently accessed. The user might be re-prompted, however, should there be configuration changes (e.g., a notice is revised) or if the acknowledgement is deemed to have expired. To achieve this, state information must be maintained such that the access control mechanism is able to determine which, if any, acknowledgements for a particular resource have already been obtained.

State information used to record an acknowledgement event is called a Notice Acknowledgement Token (NAT) in this document.

Different web service providers will have different types of web services and require solutions that differ in their details. A well-designed solution architecture will therefore need to support a spectrum of requirements. Some applications will involve saving state on the client, some will require state to be saved on the server only, and others will need a combination of both approaches.

Saving state purely on the server assumes that the server has a means of identifying a client and associating persistent state with him. Upon receiving a service request, the server knows who the client is and can retrieve the client's state, including notice acknowledgement history.

Saving state purely on the client has the advantage of requiring no maintenance of state at the server, thereby reducing its complexity. For brower-based applications, HTTP cookies will be the usual mechanism for maintaining state at the client; after being returned by the server, notice acknowledgement tokens will thereafter be automatically transmitted by the browser together with future requests. Because browsers have implementation-dependent limits on the number of cookies (total, and per-server or domain name), as well as the maximum cookie size, the principle failing of this approach is that a browser may unilaterally delete HTTP cookies, thereby "forgetting" notice acknowledgements. HTTP cookies also have the disadvantage of being tied to a specified domain name, which may limit how notice acknowledgement tokens can be shared among servers.

A combined approach shares the advantages and disadvantages of the individual approaches, but reduces memory requirement at the client. Rather than storing all of the information at the client, the client is given a much smaller data structure that is essentially just a pointer to information maintained at the server.

Our concern here is specifying the syntax and semantics of client-side state information in support of building notice acknowledgement architectures.

The following features are examples of the kinds of functionality that a web service provider might want:

We use the terms "web server", "server", and "application" interchangeably to refer to an entity that receives and processes web service requests.

We use the terms "client", "user", "user agent", and "browser" to refer to an entity that generates web service requests and transmits them to a server.

A resource that can be associated with an acknowledgement is identified by a URI (RFC 2396[2], RFC 3986[3]).

The Augmented BNF of RFC 2616[4] (Section 2.1) is used to specify syntax.

The remainder of this document specifies the NAT, a system-independent data structure for representing and sharing notice acknowledgement state information. The NAT provides a simple, extensible representation of an acknowledgement event. For environments where security and tamper-resistance are required, appropriate elements are defined; environments where this is not required need not use or implement these capabilities. The NAT can be transmitted with a request as the payload of an HTTP cookie or the value of an HTTP extension header. Cooperating web services that follow this specification will be capable of understanding each other's NATs.

A notice acknowledgement token has the following general format:

nat = nat-name "=" nat-value

Following RFC 2109[5] (Section 4.3.4), an (unordered) set of NATs is represented as

nats = nat *((";" | ",") nat)

That is, two or more NATs can be combined for transmission by separating them with a ";" or "," character.

A NAT with an invalid nat-name or nat-value is ignored.

nat-value = mime_encode(unsecure-nat) | mime_encode(secure-nat)
nat-name  = token
unsecure-nat = av-pairs
secure-nat   = hmac hmac-nat
hmac         = "HMAC=<">" hmac-value <">
hmac-nat     = ";" clear-nat ";" enc-method(av-pairs)
clear-nat    = *1("Version=<">" version <"> ";") "Secure=<">" enc-method <">

The mime_encode function represents the application of base-64 encoding to the given syntactical element (see Section 2.6[6]). This encoding prevents elements of the cookie value from conflicting with the syntax of the Cookie header or an HTTP message-header and allow binary data to be sent reliably over networks and heterogeneous platforms.

av-pairs      = av-pair *(";" av-pair)
av-pair       = attr-name "=" attr-value
attr-name     = token
attr-value    = quoted-string
quoted-string = <"> text-subset <">
text-subset   = <any TEXT except separators>
TEXT          = *<any CHAR except CTLs but including SP>
escaped-char  = "%" HEXDIGIT HEXDIGIT
HEXDIGIT      = "A" | "B" | "C" | "D" | "E" | "F"


                    | "a" | "b" | "c" | "d" | "e" | "f" | DIGIT
DIGIT         = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
HEXSTRING     = 1*(HEXDIGIT)
token          = 1*<any CHAR except CTLs or separators>
separators     = "(" | ")" | "<" | ">" | "@"


                  | "," | ";" | ":" | "\" | <">


                  | "/" | "[" | "]" | "?" | "="


                  | "{" | "}" | SP | HT
CTL            = <any US-ASCII control character


                    (octets 0 - 31) and DEL (127)>
CHAR           = <any US-ASCII character (octets 0 - 127)>

Attributes (attr-name) are case-insensitive. One or more spaces are permitted before and/or after a ";" and before and/or after a "=".

An attr-value can contain arbitrary OCTETs through the escaped-char syntax. A literal "%" character must itself be escaped as the three characters "%25" and a literal ";" character must be escaped as "%3b".

This syntax allows a NAT to appear as the value of the Cookie request header or of an HTTP extension header. It is beyond the scope of this document how NATs are passed from system to system, however.

It is recommended that NAT names (nat-name) begin with the four-character long prefix "NAT-" so that they can be readily recognized. For example, HTTP Cookie headers bearing two NATs might use any of the following cookie name syntaxes:

Cookie: NAT-METALOGIC=... ; NAT-DSS=...
Cookie: NAT-METALOGIC.COM=... ; NAT-DSS.CA=...
Cookie: NAT-METALOGIC.COM-17=...
Cookie: NAT-METALOGIC.COM-WMS-17=...

The goal in selecting a syntax is to provide a way for applications to quickly locate NATs that they generated or are interested in. Since a server may issue multiple NATs as HTTP cookies, each such cookie must have a distinct nat-name. This may be achieved by appending a sequence number, time of day, or hash value, for example.

All of the attribute names (attr-name) defined in this section are reserved. All of the attributes are optional, except HMAC and Secure, which are required only when forming a secure-nat.

An implementation may use syntactically valid, unreserved attribute names for its own purposes. Unrecognized and invalid attribute names should be ignored by servers. Attribute names are case insensitive. The relative ordering of attributes is immaterial, except as stated otherwise.

A syntactically invalid nat will be ignored. If duplicate attribute names appear in a nat, a server should treat the nat as invalid and ignore it.

A resource-uri, which is used below, is defined as follows:

resource-uri = URI | relative-uri | uri "/*" | relative-uri "/*"

Attribute Name: CreatorURI (optional)
Attribute Value: a URI

CreatorURI="https://example.com:8443"
CreatorURI="http://example.com/cgi-bin/dacs"
CreatorURI="MYFED::MYJURISDICTION"

Attribute Name: BaseURI (optional)
Attribute Value: a URI

BaseURI="https://example.com:8443"
BaseURI="http://example.com/cgi-bin/dacs"

Attribute Name: ResourceURIs (optional)
Attribute Value: resource-uri *(SP resource-uri)

Example:


  ResourceURIs="https://example.com/index.html"


  -- This identifies a single web page.
Example:


  ResourceURIs="/foo.html /bar.html /baz.html"


  -- If BaseURI="https://example.com", ResourceURIs identifies


  https://example.com/foo.html, https://example.com/bar.html, and


  https://example.com/baz.html.
Example:


  ResourceURIs="/images/*"


  -- Assuming that BaseURI="https://example.com", this specifies


  all URI that are subordinate or equivalent to the absolute URI


  https://example.com/images, such as


  https://example.com/images/dog.gif,


  https://example.com/images/lines/dotted.gif, and


  https://example.com/images.
Example:


  ResourceURIs="https://example.com/*"


  -- This identifies all URI under https://example.com.
Example:


  ResourceURIs="https://example.com/foo/%2a"


  -- This specifies exactly one URI, namely https://example.com/foo/*.
Example:


  ResourceURIs="https://example.com/foo*"


  -- This specifies exactly one URI, namely https://example.com/foo*.

Attribute Name: Version (optional)
Attribute Value: "1"

Version="1"

Attribute Name: Secure (required for secure-nat)
Attribute Value: "no" | enc-method

cipher-name *1(cipher-mode) *1(digest-name)

Attribute Name: HMAC (required for secure-nat)
Attribute Value: hmac-value

Attribute Name: State (optional)
Attribute Value: a URI | local-state-identifier

Public state:

Private state:

Attribute Name: NoticeURIs (optional)
Attribute Value: notice-uri *(SP notice-uri)
where notice-uri = a URI | relative-uri

Attribute Name: NoticeDigestMethod (optional)
Attribute Value: digest-name

Attribute Name: NoticeDigest (optional)
Attribute Value: a space-separated list of HEXSTRINGs

Attribute Name: Expires (optional)
Attribute Value: a date string

Wdy, DD-Mon-YYYY HH:MM:SS GMT

For an otherwise valid NAT to potentially be applicable to the URI of a service request, one of the NAT's resource-uri must either be the same as the service request URI or, if a resource-uri ends in "/*", match as an ancestor of the URI. The latter case is called a "wildcard match".

The URI https://example.com/cgi-bin, for example, is considered to be an ancestor or parent of the URI "https://example.com/cgi-bin/program". The former URI's path component has two elements, the latter has three elements. The one-element URI path "/" is considered to be the ancestor of all other paths.

The "*" operator, which matches zero or more elements, has special meaning only when it appears as a path element at the end of a resource-uri. For instance, the URI path "/cgi-bin/*" is considered to be the ancestor of all paths having the prefix "/cgi-bin/" and matches service requests for "/cgi-bin/printenv", "/cgi-bin/", and "/cgi-bin".

Before matching a service request URI against NATs, the URI is converted into a canonical form. Any trailing "/" characters are stripped off. As a special case, the URI path "/" is unchanged.

The server examines the resource-uri of NATs to find one having the most specific URI path that applies to the service request URI; that is, it conducts a search to find the resource-uri that has the greatest number of components in common with the service request. If no exact match is found, the search will consider increasingly general resource-uri. The resource-uri that matches the URI most closely (i.e., has the greatest number of matching components) determines the applicable NAT, if any.

If two or more resource-uri "tie" (e.g., because of duplicates), one will be chosen arbitrarily.

This section and its subsections have not been completed.

Encryption Algorithms.

Message Digest Algorithms.

HMAC - Keyed Message Authentication Code.

Encryption.

To ensure that a NAT can be safely transmitted between systems, it is encoded using Base64 Content-Transfer-Encoding, as specified by RFC 2045[9] (Section 6.8). While not providing additional security, this encoding offers some protection against casual inspection of NAT contents.

A NAT need not be transmitted as the payload of an HTTP cookie, although that will likely be the most common method. Instead, NATs can be transmitted using an HTTP entity-header extension header. The field name "NoticeAcknowledgements" is recommended:

NoticeAcknowledgements: NAT-METALOGIC=..., NAT-DSS=...

Like all entity-headers, this name is case-insensitive.

This header may not be repeated unless "," is used as the separator instead of ";". See RFC 2616[4] (Section 4.2).

When there are multiple NATs, no relative ordering is imposed. In the event that more than one NAT in a list corresponds to the same resource, the resulting behaviour is undefined and may depend on the order in which the NATs are processed.

It is up to a server whether the acknowledgement of a particular notice for one resource can automatically be applied to another resource. For example, suppose that a user acknowledges notice N1 upon requesting resource R1. Subsequently, the user requests resource R2 from the server and it happens that notice N1 also applies to R2, although this fact is not recorded in a NAT. It is implementation and context dependent in cases like this whether the server requires the user to acknowledge N1 again specifically for R2 or automatically accepts the earlier acknowledgement. Similarly, if a user's NATs collectively indicate that all notices associated with a request have been acknowledged but no single NAT asserts this for the request, the outcome is server-dependent.

Although a NAT may exist that indicates that an acknowledgement has already been obtained, a server may issue a new, more specific NAT or a NAT with a different Expires field. For example, in the example scenario described in the previous section[10], a server might replace the existing NAT for R1 with one that lists both R1 and R2.

A server may return multiple NATs, adding new ones and deleting or replacing existing ones.

The path components of two URI are compared case sensitively. The scheme and authority components are compared case insensitively.

Having received a NAT as a result of accessing a given resource, a client should not assume that a later request for the same resource will not involve notice acknowledgements. A server may arbitrarily decide that acknowledgements are needed, a notice may have been modified, a new notice may have been added, or the NAT may have expired.

A minimal server implementation would issue and recognize NATs that consist simply of a base-64 encoded ResourceURIs attribute:

"NAT-DSS=" mime_encode("ResourceURIs=" ResourceURIs)

In support of thick clients and middleware architectures, an implementation might include two useful web services:

These hypothetical services are not described further here.