/usr/share/doc/dacs-examples/man/dacs.nat.5.html

<!-- Copyright (c) 2003-2013 -->
<!-- Distributed Systems Software.  All rights reserved. -->
<!-- See the file LICENSE for redistribution information. -->
<!-- $Id: copyright-html 2625 2013-01-22 18:15:12Z brachman $ -->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>dacs.nat</title><link rel="stylesheet" type="text/css" href="css/dacsdocs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div id="refentry" class="para16">
<script language="javascript" type="text/javascript" src="css/js/fontselector.js"></script>
<table width="100%"><tr>
<td align="left">
<b>DACS.NAT(5)</b></td>
<td align="center">
<b>DACS Formats and Conventions</b></td>
<td align="right">
<b>DACS.NAT(5)</b></td>
</tr></table>
<div class="refnamediv"><h2>NAME</h2><p>dacs.nat &#8212; Notice Acknowledgement Token specification</p></div><div class="refsect1"><a name="idm10"></a><h2>DESCRIPTION</h2><p>These files are part of the <span class="command"><strong>DACS</strong></span> suite.</p><p>The <a class="ulink" href="dacs_notices.8.html" target="_top">dacs_notices(8)</a>
web service implements selected parts of this specification.
</p><div class="refsect2"><a name="idm16"></a><h3>Introduction</h3><p>This document specifies the syntax and semantics of the
Notice Acknowledgement Token (<acronym class="acronym">NAT</acronym>), which is used
by parts of <span class="command"><strong>DACS</strong></span> and may be of use to other systems.
Interoperating systems that adopt this specification will be able to
understand <acronym class="acronym">NAT</acronym>s produced by any of the systems and
will therefore be capable of avoiding unnecessary user prompting.
</p><p>A system is not required to honour or even recognize another
system's <acronym class="acronym">NAT</acronym>, but doing so may benefit users.
</p><div class="refsect3"><a name="idm24"></a><h4>Purpose</h4><p>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).
</p><p>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.
</p><p>State information used to record an acknowledgement event is called a
<span class="emphasis"><em>Notice Acknowledgement Token</em></span>
(<acronym class="acronym">NAT</acronym>) in this document.
</p></div><div class="refsect3"><a name="idm31"></a><h4>Design Elements</h4><p>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.
</p><p>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.
</p><p>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.
</p><p>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.
</p><p>Our concern here is specifying the syntax and semantics of client-side
state information in support of building notice acknowledgement architectures.
</p><p>The following features are examples of the kinds of functionality that a
web service provider might want:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
One or more notices may need to be associated with a single resource.
</p></li><li class="listitem"><p>
The same notice(s) may apply to multiple resources but those
resources may have different access control requirements.
</p></li><li class="listitem"><p>
A different notice (or notices) may apply to resources having identical
access control requirements.
</p></li><li class="listitem"><p>
If a new notice is added for a resource, a user having previously
accessed the resource and acknowledged its notice should be presented
with (only) the new notice upon his next access.
</p></li><li class="listitem"><p>
If a notice is modified for a resource, a user having previously
acknowledged the notice should be presented with the modified notice
upon his next access.
</p></li><li class="listitem"><p>
It may be necessary to periodically require users to re-acknowledge a
notice (acknowledgements may expire).
</p></li><li class="listitem"><p>
Whether any notices exist for a particular resource, and exactly which
notices must be shown, can be very simple or highly application- and
data-dependent.  A solution will therefore sometimes involve the web
service provider having to write some custom code to supply this
information.
</p></li><li class="listitem"><p>
Obtaining the appropriate notice to be presented to a user may be as
simple as retrieving the contents of a file.  But notices may
need to be generated on the fly by a program and therefore ought to be 
named by, and obtained through, URLs.
</p></li><li class="listitem"><p>
Safeguards may be required to ensure that it is difficult to
bypass the notice acknowledgement mechanism.
</p></li><li class="listitem"><p>
Safeguards may be required to ensure that information within
a notice acknowledgement token remains private.
</p></li><li class="listitem"><p>
State information must be extensible to accommodate future and
unforeseen needs.
</p></li></ul></div><p>
</p></div><div class="refsect3"><a name="idm62"></a><h4>Terminology</h4><p>
We use the terms "web server", "server", and "application" interchangeably
to refer to an entity that receives and processes web service requests.
</p><p>
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.
</p><p>
A resource that can be associated with an acknowledgement is identified by
a <acronym class="acronym">URI</acronym>
(<a class="ulink" href="http://www.rfc-editor.org/rfc/rfc2396.txt" target="_top">RFC 2396</a>,
<a class="ulink" href="http://www.rfc-editor.org/rfc/rfc3986.txt" target="_top">RFC 3986</a>).
</p></div><div class="refsect3"><a name="idm70"></a><h4>Notational Conventions</h4><p>
The Augmented BNF of
<a class="ulink" href="http://www.rfc-editor.org/rfc/rfc2616.txt" target="_top">RFC 2616</a>
(Section 2.1) is used to specify syntax.
</p></div><div class="refsect3"><a name="idm74"></a><h4>Summary</h4><p>
The remainder of this document specifies the <acronym class="acronym">NAT</acronym>,
a system-independent data
structure for representing and sharing notice acknowledgement state
information.
The <acronym class="acronym">NAT</acronym> 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 <acronym class="acronym">NAT</acronym> 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
<acronym class="acronym">NAT</acronym>s.
</p></div></div><div class="refsect2"><a name="idm81"></a><h3>The Notice Acknowlegement Token</h3><p>The format of a <acronym class="acronym">NAT</acronym> is described in this section.
<acronym class="acronym">NAT</acronym>s are constructed by a
server either strictly for its own use or with the intent of sharing state
information amongst a set of cooperating servers.
</p><p>Servers that fulfill part or all of a user's service request by making
one or more service requests to other servers ("cascaded operation") are
required to forward <acronym class="acronym">NAT</acronym>s provided to them by the user
or another server.
When used in this environment, and any environment where servers are loosely
associated, an implementation must select <acronym class="acronym">NAT</acronym>
attribute types carefully to maximize interoperability.
</p><p>A server is free to ask a client to delete a
<acronym class="acronym">NAT</acronym> (e.g., by setting
an expired cookie with the same name) or replace a
<acronym class="acronym">NAT</acronym> with a newer instance.
</p><div class="refsect3"><a name="idm92"></a><h4><acronym class="acronym">NAT</acronym> Syntax</h4><p>A notice acknowledgement token has the following general format:
</p><pre class="programlisting">
<span class="symbol">nat</span> = <span class="symbol">nat-name</span> "<code class="literal">=</code>" <span class="symbol">nat-value</span>
</pre><p>
</p><p>Following
<a class="ulink" href="http://www.rfc-editor.org/rfc/rfc2109.txt" target="_top">RFC 2109</a>
(Section 4.3.4),
an (unordered) set of <acronym class="acronym">NAT</acronym>s is represented as
</p><pre class="programlisting">
<span class="symbol">nats</span> = <span class="symbol">nat</span> *(("<code class="literal">;</code>" | "<code class="literal">,</code>") <span class="symbol">nat</span>)
</pre><p>
That is, two or more <acronym class="acronym">NAT</acronym>s can be combined for transmission
by separating
them with a "<code class="literal">;</code>" or "<code class="literal">,</code>" character.
</p><p>A <acronym class="acronym">NAT</acronym> with an invalid
<span class="symbol">nat-name</span> or <span class="symbol">nat-value</span> is ignored.
</p><p>
</p><pre class="programlisting">
<span class="symbol">nat-value</span> = <code class="literal"><code class="function">mime_encode</code></code>(<span class="symbol">unsecure-nat</span>) | <code class="literal"><code class="function">mime_encode</code></code>(<span class="symbol">secure-nat</span>)

<span class="symbol">nat-name</span>  = <span class="symbol">token</span>

<span class="symbol">unsecure-nat</span> = <span class="symbol">av-pairs</span>
<span class="symbol">secure-nat</span>   = <span class="symbol">hmac</span> <span class="symbol">hmac-nat</span>
<span class="symbol">hmac</span>         = "<code class="literal">HMAC=</code>&lt;<code class="literal">"</code>&gt;" <span class="symbol">hmac-value</span> &lt;<code class="literal">"</code>&gt;
<span class="symbol">hmac-nat</span>     = "<code class="literal">;</code>" <span class="symbol">clear-nat</span> "<code class="literal">;</code>" <span class="symbol">enc-method</span>(<span class="symbol">av-pairs)</span>
<span class="symbol">clear-nat</span>    = *1("<code class="literal">Version=</code>&lt;<code class="literal">"</code>&gt;" <span class="symbol">version</span> &lt;<code class="literal">"</code>&gt; "<code class="literal">;</code>") "<code class="literal">Secure=</code>&lt;<code class="literal">"</code>&gt;" <span class="symbol">enc-method</span> &lt;<code class="literal">"</code>&gt;
</pre><p>
</p><div class="important" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="security1"></a>Security</h3><p>The <span class="symbol">secure-nat</span> syntax,
which is optional, has been carefully designed to
be secure, incur reasonable encoding overhead, and simplify implementation.
The <span class="symbol">secure-nat</span> syntax is used to protect
integrity and provide privacy.
Integrity is guarded through a cryptographically-secure keyed message
authentication code; in addition, attributes may optionally be kept private
by encipherment.
</p><p>In the absence of precautions to maintain privacy, inspection of
<acronym class="acronym">NAT</acronym>s can reveal a portion of a user's access history.
In situations where <acronym class="acronym">NAT</acronym>s are not transmitted over
secure end-to-end connections, such as those that can be provided by SSL/TLS,
the <span class="symbol">secure-nat</span> syntax should be considered.
Definitions of encryption and message digest algorithms, and sharing and
management of encryption keys are outside the scope of this document.
</p></div><p>The <code class="function">mime_encode</code> function represents the
application of base-64 encoding to the given syntactical element
(see <a class="ulink" href="#Encoding" target="_top">Section 2.6</a>).
This encoding prevents elements of the cookie value from conflicting with
the syntax of the
<code class="literal">Cookie</code> header or an HTTP message-header and allow binary
data to be sent reliably over networks and heterogeneous platforms.
</p><p>
</p><pre class="programlisting">
<span class="symbol">av-pairs</span>      = <span class="symbol">av-pair</span> *("<code class="literal">;</code>" <span class="symbol">av-pair</span>)
<span class="symbol">av-pair</span>       = <span class="symbol">attr-name</span> "<code class="literal">=</code>" <span class="symbol">attr-value</span>
<span class="symbol">attr-name</span>     = <span class="symbol">token</span>
<span class="symbol">attr-value</span>    = <span class="symbol">quoted-string</span>
<span class="symbol">quoted-string</span> = &lt;<code class="literal">"</code>&gt; <span class="symbol">text-subset</span> &lt;<code class="literal">"</code>&gt;
<span class="symbol">text-subset</span>   = &lt;<span class="emphasis"><em>any <span class="symbol">TEXT</span> except <span class="symbol">separators</span></em></span>&gt;

<span class="symbol">TEXT</span>          = *&lt;<span class="emphasis"><em>any <span class="symbol">CHAR</span> except <span class="symbol">CTL</span>s but including <span class="symbol">SP</span></em></span>&gt;

escaped-char  = "<code class="literal">%</code>" <span class="symbol">HEXDIGIT</span> <span class="symbol">HEXDIGIT</span>
<span class="symbol">HEXDIGIT</span>      = "A" | "B" | "C" | "D" | "E" | "F"
                    | "a" | "b" | "c" | "d" | "e" | "f" | <span class="symbol">DIGIT</span>
<span class="symbol">DIGIT</span>         = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
<span class="symbol">HEXSTRING</span>     = 1*(<span class="symbol">HEXDIGIT</span>)

<span class="symbol">token</span>          = 1*&lt;<span class="emphasis"><em>any <span class="symbol">CHAR</span> except <span class="symbol">CTL</span>s or <span class="symbol">separators</span></em></span>&gt;
<span class="symbol">separators</span>     = "(" | ")" | "&lt;" | "&gt;" | "@"
                  | "," | ";" | ":" | "\" | &lt;"&gt;
                  | "/" | "[" | "]" | "?" | "="
                  | "{" | "}" | SP | HT
<span class="symbol">CTL</span>            = &lt;<span class="emphasis"><em>any US-ASCII control character
                    (octets 0 - 31) and DEL (127)</em></span>&gt;
<span class="symbol">CHAR</span>           = &lt;<span class="emphasis"><em>any US-ASCII character (octets 0 - 127)</em></span>&gt;
</pre><p>
</p><p> Attributes (<span class="symbol">attr-name</span>) are case-insensitive.
One or more spaces are permitted before and/or after a
"<code class="literal">;</code>" and before and/or after a "<code class="literal">=</code>".
</p><p>An <span class="symbol">attr-value</span> can contain arbitrary
OCTETs through the <span class="symbol">escaped-char</span> syntax.
A literal "<code class="literal">%</code>" character must itself be escaped as the three
characters "<code class="literal">%25</code>" and a literal "<code class="literal">;</code>"
character must be escaped as "<code class="literal">%3b</code>".
</p><p>This syntax allows a <acronym class="acronym">NAT</acronym> to appear as the value of
the <code class="literal">Cookie</code> request header
or of an HTTP extension header.  It is beyond the scope of this document
how <acronym class="acronym">NAT</acronym>s are passed from system to system, however.
</p></div><div class="refsect3"><a name="idm227"></a><h4><acronym class="acronym">NAT</acronym> Names</h4><p>It is recommended that <acronym class="acronym">NAT</acronym> names
(<span class="symbol">nat-name</span>) begin with the four-character
long prefix "<code class="literal">NAT-</code>" so that they can be readily recognized.
For example, HTTP <code class="literal">Cookie</code> headers bearing two
<acronym class="acronym">NAT</acronym>s might use any of the following cookie name
syntaxes:
</p><pre class="programlisting">
Cookie: NAT-METALOGIC=... ; NAT-DSS=...
Cookie: NAT-METALOGIC.COM=... ; NAT-DSS.CA=...
Cookie: NAT-METALOGIC.COM-17=...
Cookie: NAT-METALOGIC.COM-WMS-17=...
</pre><p>
</p><p>The goal in selecting a syntax is to provide a way for applications to
quickly locate <acronym class="acronym">NAT</acronym>s that they generated or are interested in.
Since a server may issue multiple <acronym class="acronym">NAT</acronym>s as HTTP cookies,
each such cookie must have a distinct <span class="symbol">nat-name</span>.
This may be achieved by appending a sequence
number, time of day, or hash value, for example.
</p></div><div class="refsect3"><a name="idm241"></a><h4><acronym class="acronym">NAT</acronym> Reserved Attributes</h4><p>All of the attribute names (<span class="symbol">attr-name</span>) defined in
this section are reserved.
All of the attributes are optional,
except <span class="symbol">HMAC</span> and <span class="symbol">Secure</span>, which are
required only when forming a <span class="symbol">secure-nat</span>.
</p><p>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.
</p><p>A syntactically invalid nat will be ignored.
If duplicate attribute names appear in a
<span class="symbol">nat</span>, a server should treat the
<span class="symbol">nat</span> as invalid and ignore it.
</p><p>
A <span class="symbol">resource-uri</span>, which is used below, is defined as follows:
</p><pre class="programlisting">
<span class="symbol">resource-uri</span> = <acronym class="acronym">URI</acronym> | <span class="symbol">relative-uri</span> | <span class="symbol">uri</span> "<code class="literal">/*</code>" | <span class="symbol">relative-uri</span> "<code class="literal">/*</code>"
</pre><p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><div class="literallayout"><p>Attribute Name: <span class="symbol">CreatorURI</span> (<span class="emphasis"><em>optional</em></span>)<br>
Attribute Value: a <acronym class="acronym">URI</acronym><br>
</p></div><p> This <acronym class="acronym">URI</acronym> identifies the server, application,
or jurisdiction that
created this <acronym class="acronym">NAT</acronym>.
If it is an absolute <acronym class="acronym">URI</acronym>, it also establishes a base
<acronym class="acronym">URI</acronym> for relative <acronym class="acronym">URI</acronym>s within this
<acronym class="acronym">NAT</acronym>.
Examples:
</p><pre class="programlisting">
CreatorURI="https://example.com:8443"
CreatorURI="http://example.com/cgi-bin/dacs"
CreatorURI="MYFED::MYJURISDICTION"
</pre><p>
</p></li><li class="listitem"><div class="literallayout"><p>Attribute Name: <span class="symbol">BaseURI</span> (<span class="emphasis"><em>optional</em></span>)<br>
Attribute Value: a <acronym class="acronym">URI</acronym><br>
</p></div><p>This absolute <acronym class="acronym">URI</acronym> establishes a base
<acronym class="acronym">URI</acronym> for relative <acronym class="acronym">URI</acronym>s within this
<acronym class="acronym">NAT</acronym>.
If <span class="symbol">CreatorURI</span> is present,
this <acronym class="acronym">URI</acronym> overrides it as the base <acronym class="acronym">URI</acronym>.
Examples:
</p><pre class="programlisting">
BaseURI="https://example.com:8443"
BaseURI="http://example.com/cgi-bin/dacs"
</pre><p>
</p></li><li class="listitem"><div class="literallayout"><p>Attribute Name: <span class="symbol">ResourceURIs</span> (<span class="emphasis"><em>optional</em></span>)<br>
Attribute Value: <span class="symbol">resource-uri</span> *(<code class="literal">SP</code> <span class="symbol">resource-uri</span>)<br>
</p></div><p>This attribute identifies one or more resources that have been
acknowledged
(that is, for which one or more acknowledgements have been received).
If <span class="symbol">resource-uri</span> is an absolute <acronym class="acronym">URI</acronym>,
it identifies the resource.
If <span class="symbol">resource-uri</span> is a <span class="symbol">relative-uri</span>
and neither the BaseURI nor the
<span class="symbol">CreatorURI</span> attribute are present,
the implied default base <acronym class="acronym">URI</acronym> is
effectively "any server".  For example, if no
<span class="symbol">BaseURI</span> and <span class="symbol">CreatorURI</span>
attributes are present, a
<span class="symbol">relative-uri</span> of "<code class="filename">/index.html</code>"
refers to a resource of that name anywhere.  This behaviour can be useful
in environments where web content and resource naming are coordinated
across servers.
</p><p>If a <span class="symbol">resource-uri</span> ends in the two characters
"<code class="literal">/*</code>", it refers to
all <acronym class="acronym">URI</acronym> that are subordinate or equivalent to the
absolute or relative <acronym class="acronym">URI</acronym>.
Either or both of the characters "<code class="literal">/*</code>" may be URL-encoded
("<code class="literal">/</code>" by "<code class="literal">%2f</code>"
and "<code class="literal">*</code>" by "<code class="literal">%2a</code>")
to prevent this interpretation.
Refer to <a class="ulink" href="#URI-matching" target="_top">Section 2.4</a>.
</p><p>It is possible for a particular resource to be known by more than one
<acronym class="acronym">URI</acronym>.  There is no requirement for two distinct
<acronym class="acronym">URI</acronym> to be recognized as
referring to the same resource, therefore each may need its own
acknowledgement.
It is left to each server to decide whether a request <acronym class="acronym">URI</acronym>
matches a <span class="symbol">resource-uri</span>.
For example, domain names may not need to match exactly,
such as when a web site is mirrored, or some general mapping might be
applied to determine whether a request <acronym class="acronym">URI</acronym> matches a
<span class="symbol">resource-uri</span>.
</p><p>
</p><pre class="programlisting">
Example:
  ResourceURIs="https://example.com/index.html"

  <span class="emphasis"><em>-- This identifies a single web page.</em></span>

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

  <span class="emphasis"><em>-- If BaseURI="https://example.com", ResourceURIs identifies
  <code class="filename">https://example.com/foo.html</code>, <code class="filename">https://example.com/bar.html</code>, and
  <code class="filename">https://example.com/baz.html</code>.</em></span>

Example:
  ResourceURIs="/images/*"

  <span class="emphasis"><em>-- Assuming that BaseURI="https://example.com", this specifies
  all <acronym class="acronym">URI</acronym> that are subordinate or equivalent to the absolute <acronym class="acronym">URI</acronym>
  <code class="filename">https://example.com/images</code>, such as
  <code class="filename">https://example.com/images/dog.gif</code>,
  <code class="filename">https://example.com/images/lines/dotted.gif</code>, and
  <code class="filename">https://example.com/images</code>.</em></span>

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

  <span class="emphasis"><em>-- This identifies all <acronym class="acronym">URI</acronym> under <code class="filename">https://example.com</code>.</em></span>

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

  <span class="emphasis"><em>-- This specifies exactly one <acronym class="acronym">URI</acronym>, namely <code class="filename">https://example.com/foo/*</code>.</em></span>

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

  <span class="emphasis"><em>-- This specifies exactly one <acronym class="acronym">URI</acronym>, namely <code class="filename">https://example.com/foo*</code>.</em></span>
</pre><p>
</p></li><li class="listitem"><div class="literallayout"><p>Attribute Name: <span class="symbol">Version</span> (<span class="emphasis"><em>optional</em></span>)<br>
Attribute Value: "1"<br>
</p></div><p>This attribute specifies the version of the specification used for
this <span class="symbol">nat-value</span>.
If present, this attribute must appear first.
If absent, the attribute defaults to:
</p><pre class="programlisting">
Version="1"
</pre><p>
The only <span class="symbol">attr-value</span> permitted by this version is
"<code class="constant">1</code>".
</p></li><li class="listitem"><div class="literallayout"><p>Attribute Name: <span class="symbol">Secure</span> (<span class="emphasis"><em>required for <span class="symbol">secure-nat</span></em></span>)<br>
Attribute Value: "<code class="literal">no</code>" | <span class="symbol">enc-method</span><br>
</p></div><p>If the value is "<code class="literal">no</code>",
the <span class="symbol">av-pairs</span> have
not been encrypted and no <span class="symbol">HMAC</span> attribute is present.
A value other than "<code class="literal">no</code>" describes the
method used to encrypt the
following text and the digest algorithm used to compute the value of the
<span class="symbol">HMAC</span> attribute.
Its syntax, borrowed from that used by
<a class="ulink" href="http://www.openssl.org" target="_top">OpenSSL</a>, is:
</p><pre class="programlisting">
<span class="symbol">cipher-name</span> *1(<span class="symbol">cipher-mode</span>) *1(<span class="symbol">digest-name</span>)
</pre><p>
Examples of <span class="symbol">enc-method</span>: aes128-cbc-sha1, aes128-cfb,
aes192-cbc, aes256-ofb, des-md5, des3, desx-sha256
</p></li><li class="listitem"><div class="literallayout"><p>Attribute Name: <span class="symbol">HMAC</span> (<span class="emphasis"><em>required for <span class="symbol">secure-nat</span></em></span>)<br>
Attribute Value: <span class="symbol">hmac-value</span><br>
</p></div><p>This is the Keyed-Hash Message Authentication Code (HMAC),
represented as a <span class="symbol">HEXSTRING</span>,
computed using the digest algorithm specified or implied
by the <span class="symbol">Secure</span> attribute's value and computed over
<span class="symbol">hmac-nat</span>.
<code class="literal">SHA-1</code>, <code class="literal">SHA-224</code>,
<code class="literal">SHA-256</code>, <code class="literal">SHA-384</code>,
and <code class="literal">SHA-512</code> are recommended for this purpose.
The HMAC is used to authenticate the <acronym class="acronym">NAT</acronym> and
protect integrity by detecting tampering.
</p></li><li class="listitem"><div class="literallayout"><p>Attribute Name: <span class="symbol">State</span> (<span class="emphasis"><em>optional</em></span>)<br>
Attribute Value: a URI | <span class="symbol">local-state-identifier</span><br>
</p></div><p>This attribute identifies server-side state information for this
<acronym class="acronym">NAT</acronym>.
Rather than building a large <acronym class="acronym">NAT</acronym>,
the creator of the <acronym class="acronym">NAT</acronym> may
construct a <acronym class="acronym">NAT</acronym> that simply points to state information.
There are two types of state information: public and private.
</p><p>
</p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><div class="literallayout"><p>Public state:</p></div><p>If the <span class="symbol">attr-value</span> is a <acronym class="acronym">URI</acronym>,
it identifies a resource that contains
additional information (<span class="emphasis"><em>TBD, but presumably it is an
XML document</em></span>).
Other cooperating servers may be able to use this <acronym class="acronym">URI</acronym>
to obtain attributes described here but not included in the
<acronym class="acronym">NAT</acronym> at the discretion of the creating server.
(<span class="emphasis"><em>TBD: this service might be used to decrypt and/or validate a
<acronym class="acronym">NAT</acronym> associated with it</em></span>)
</p></li><li class="listitem"><div class="literallayout"><p>Private state:</p></div><p>If the <span class="symbol">attr-value</span> is not a <acronym class="acronym">URI</acronym>
(e.g., it is not prefixed by a recognized
scheme), it identifies information local to the creating server (not
available to other servers).  This might be a unique database key,
for example.
</p></li></ol></div><p>
</p></li><li class="listitem"><div class="literallayout"><p>Attribute Name: <span class="symbol">NoticeURIs</span> (<span class="emphasis"><em>optional</em></span>)<br>
Attribute Value: <span class="symbol">notice-uri</span> *(<code class="literal">SP</code> <span class="symbol">notice-uri</span>)<br>
where <span class="symbol">notice-uri</span> = a URI | <span class="symbol">relative-uri</span><br>
</p></div><p>This is a space-separated list of <acronym class="acronym">URI</acronym>s,
each of which represents the text of a notice that is associated with
<span class="symbol">ResourceURIs</span> and that has been acknowledged by the user.
Each <span class="symbol">relative-uri</span> is relative to the
<span class="symbol">CreatorURI</span>, which must be provided.  To test if a
<span class="symbol">notice-uri</span> matches
the <acronym class="acronym">URI</acronym> of a notice associated with a service request,
the two <acronym class="acronym">URI</acronym> are compared for equality.
</p></li><li class="listitem"><div class="literallayout"><p>Attribute Name: <span class="symbol">NoticeDigestMethod</span> (<span class="emphasis"><em>optional</em></span>)<br>
Attribute Value: <span class="symbol">digest-name</span><br>
</p></div><p>This attribute value is the digest algorithm (see the Secure attribute)
used to compute the <span class="symbol">NoticeDigest</span> attribute value elements.
If not provided, the <span class="symbol">digest-name</span> given by the
<span class="symbol">Secure</span> attribute's value
must be available and will be used; a weaker but more efficiently
computed digest might be sufficient for this purpose, however, such
as a 32-bit <acronym class="acronym">CRC</acronym> or <code class="literal">MD5</code>.
</p></li><li class="listitem"><div class="literallayout"><p>Attribute Name: <span class="symbol">NoticeDigest</span> (<span class="emphasis"><em>optional</em></span>)<br>
Attribute Value: a space-separated list of <span class="symbol">HEXSTRING</span>s<br>
</p></div><p>This is a space-separated list of
<span class="symbol">HEXSTRING</span>s, each corresponding
to an element of <span class="symbol">NoticeURIs</span>,
that is the message digest of that <span class="symbol">NoticeURIs</span>
computed using <span class="symbol">NoticeDigestMethod</span>
(or failing that, the algorithm given
by the <span class="symbol">Secure</span> attribute's value).
There must be exactly as many elements
in this list as are in <span class="symbol">NoticeURIs</span>,
otherwise the <acronym class="acronym">NAT</acronym> is invalid.
The purpose of this attribute is to help detect if any
<span class="symbol">NoticeURIs</span> has
changed and therefore might need to be acknowledged by the user again.
</p></li><li class="listitem"><div class="literallayout"><p>Attribute Name: <span class="symbol">Expires</span> (<span class="emphasis"><em>optional</em></span>)<br>
Attribute Value: a date string<br>
</p></div><p>This is a date field, as specified in the Netscape HTTP Cookie Spec:
</p><pre class="programlisting">
Wdy, DD-Mon-YYYY HH:MM:SS GMT
</pre><p>
While clients are advised of the lifetime of an HTTP cookie at the time
it is issued, nothing compels a client to destroy the cookie at that
time.
An explicit expiry date can be enforced by a server, however,
and can be used with mechanisms other than HTTP cookies.
The <acronym class="acronym">NAT</acronym> is invalid if this field
is incorrectly formatted.
</p></li></ol></div></div><div class="refsect3"><a name="URI-matching"></a><h4><acronym class="acronym">URI</acronym> Matching</h4><p>For an otherwise valid <acronym class="acronym">NAT</acronym> to potentially
be applicable
to the <acronym class="acronym">URI</acronym> of a service request,
one of the <acronym class="acronym">NAT</acronym>'s
<span class="symbol">resource-uri</span> must either be the same as
the service request <acronym class="acronym">URI</acronym> or, if a
<span class="symbol">resource-uri</span> ends in "<code class="literal">/*</code>", match as an
ancestor of the <acronym class="acronym">URI</acronym>.
The latter case is called a "wildcard match".
</p><p>The <acronym class="acronym">URI</acronym>
<code class="filename">https://example.com/cgi-bin</code>,
for example, is considered to be an
ancestor or parent of the <acronym class="acronym">URI</acronym>
"<code class="filename">https://example.com/cgi-bin/program</code>".
The former <acronym class="acronym">URI</acronym>'s path component has two elements,
the latter has three elements.
The one-element <acronym class="acronym">URI</acronym> path "<code class="literal">/</code>"
is considered to be the ancestor of all other paths.
</p><p> The "<code class="literal">*</code>" operator,
which matches zero or more elements, has special meaning
only when it appears as a path element at the end of a
<span class="symbol">resource-uri</span>.
For instance, the <acronym class="acronym">URI</acronym> path "<code class="filename">/cgi-bin/*</code>"
is considered to be the ancestor of all paths having the prefix
"<code class="filename">/cgi-bin/</code>" and matches service requests for
"<code class="filename">/cgi-bin/printenv</code>",
"<code class="filename">/cgi-bin/</code>", and
"<code class="filename">/cgi-bin</code>".
</p><p>Before matching a service request <acronym class="acronym">URI</acronym>
against <acronym class="acronym">NAT</acronym>s,
the <acronym class="acronym">URI</acronym> is converted into a canonical form.
Any trailing "<code class="literal">/</code>" characters are stripped off.
As a special case, the <acronym class="acronym">URI</acronym> path "<code class="filename">/</code>" is unchanged.
</p><p>The server examines the <span class="symbol">resource-uri</span>
of <acronym class="acronym">NAT</acronym>s to find one having the most
specific <acronym class="acronym">URI</acronym> path that applies to the service request
<acronym class="acronym">URI</acronym>;  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 <span class="symbol">resource-uri</span>.
The <span class="symbol">resource-uri</span> that matches the <acronym class="acronym">URI</acronym>
most closely
(i.e., has the greatest number of matching components) determines the
applicable <acronym class="acronym">NAT</acronym>, if any.
</p><p>If two or more <span class="symbol">resource-uri</span> "tie"
(e.g., because of duplicates), one will be chosen arbitrarily.
</p></div><div class="refsect3"><a name="idm517"></a><h4>Cryptographic Elements</h4><p>
This section and its subsections have not been completed.
</p><p><b>Encryption Algorithms. </b>
</p><p><b>Message Digest Algorithms. </b>
</p><p><b>HMAC - Keyed Message Authentication Code. </b>
</p><p><b>Encryption. </b>
</p></div><div class="refsect3"><a name="Encoding"></a><h4>Encoding for Transport</h4><p>To ensure that a <acronym class="acronym">NAT</acronym> can be safely transmitted
between systems, it is encoded using
Base64 Content-Transfer-Encoding, as specified by
<a class="ulink" href="http://www.rfc-editor.org/rfc/rfc2045.txt" target="_top">RFC 2045</a>
(Section 6.8).
While not providing additional security, this encoding offers some protection
against casual inspection of <acronym class="acronym">NAT</acronym> contents.
</p></div></div><div class="refsect2"><a name="idm538"></a><h3>Implementation Notes</h3><p>
</p><div class="refsect3"><a name="idm541"></a><h4><acronym class="acronym">NAT</acronym> HTTP Header Syntax</h4><p>A <acronym class="acronym">NAT</acronym> need not be transmitted as the payload of an
HTTP cookie, although that will likely be the most common method.
Instead, <acronym class="acronym">NAT</acronym>s can be transmitted using an
HTTP entity-header extension header.  The field name
"<code class="literal">NoticeAcknowledgements</code>" is recommended:
</p><pre class="programlisting">
NoticeAcknowledgements: NAT-METALOGIC=..., NAT-DSS=...
</pre><p>
</p><p>Like all entity-headers, this name is case-insensitive.
</p><p>This header may not be repeated unless "<code class="literal">,</code>" is used as
the separator instead of "<code class="literal">;</code>".
See
<a class="ulink" href="http://www.rfc-editor.org/rfc/rfc2616.txt" target="_top">RFC 2616</a>
(Section 4.2).
</p></div><div class="refsect3"><a name="idm554"></a><h4>Multiple <acronym class="acronym">NAT</acronym>s</h4><p>When there are multiple <acronym class="acronym">NAT</acronym>s, no relative ordering is
imposed.
In the event that more than one <acronym class="acronym">NAT</acronym> in a list corresponds
to the same resource, the resulting behaviour is undefined and may depend on
the order in which the <acronym class="acronym">NAT</acronym>s are processed.
</p></div><div class="refsect3"><a name="resource-name-mapping"></a><h4>Resource Name Mapping</h4><p>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 <code class="literal">N1</code>
upon requesting resource <code class="literal">R1</code>.
Subsequently, the user requests resource <code class="literal">R2</code> from the server
and it happens that notice <code class="literal">N1</code> also applies to
<code class="literal">R2</code>, although this fact is not
recorded in a <acronym class="acronym">NAT</acronym>.
It is implementation and context dependent in cases
like this whether the server requires the user to
acknowledge <code class="literal">N1</code> again
specifically for <code class="literal">R2</code> or automatically accepts the
earlier acknowledgement.
Similarly, if a user's <acronym class="acronym">NAT</acronym>s collectively indicate that
all notices associated with a request have been acknowledged but no single
<acronym class="acronym">NAT</acronym> asserts this for the request, the outcome is
server-dependent.
</p></div><div class="refsect3"><a name="idm574"></a><h4><acronym class="acronym">NAT</acronym> Creation and Merging</h4><p>Although a <acronym class="acronym">NAT</acronym> may exist that indicates that an
acknowledgement has already been obtained, a server may issue a new, more
specific <acronym class="acronym">NAT</acronym> or a <acronym class="acronym">NAT</acronym> with a different
<span class="symbol">Expires</span> field.
For example, in the example scenario described in the
<a class="ulink" href="#resource-name-mapping" target="_top">previous section</a>,
a server might replace the existing <acronym class="acronym">NAT</acronym> for
<code class="literal">R1</code> with one that lists both <code class="literal">R1</code> and
<code class="literal">R2</code>.
</p><p>A server may return multiple <acronym class="acronym">NAT</acronym>s,
adding new ones and deleting or replacing existing ones.
</p></div><div class="refsect3"><a name="idm589"></a><h4>Case Sensitivity</h4><p>The path components of two <acronym class="acronym">URI</acronym> are compared
case sensitively.
The scheme and authority components are compared case insensitively.
</p></div><div class="refsect3"><a name="idm593"></a><h4>Server Autonomy</h4><p>Having received a <acronym class="acronym">NAT</acronym> 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 <acronym class="acronym">NAT</acronym> may have expired.
</p></div><div class="refsect3"><a name="idm598"></a><h4>Minimal Implementation</h4><p>A minimal server implementation would issue and recognize
<acronym class="acronym">NAT</acronym>s that consist simply of a base-64 encoded
<span class="symbol">ResourceURIs</span> attribute:
</p><pre class="programlisting">
"<code class="literal">NAT-DSS=</code>" <code class="function">mime_encode</code>("<code class="literal">ResourceURIs=</code>" <span class="symbol">ResourceURIs</span>)
</pre><p>
</p></div><div class="refsect3"><a name="idm608"></a><h4>Middleware Support</h4><p>In support of thick clients and middleware architectures,
an implementation might include two useful web services:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><acronym class="acronym">NAT</acronym> creation request</p><p>An authorized client would request that a <acronym class="acronym">NAT</acronym> be
created by the server and returned.
The request's arguments would describe the
content of the <acronym class="acronym">NAT</acronym> and possibly select a format for
the returned <acronym class="acronym">NAT</acronym>
(HTTP cookie, HTTP header, XML document, and so on)
</p></li><li class="listitem"><p><acronym class="acronym">NAT</acronym> decoding request</p><p>An authorized client, sending a <acronym class="acronym">NAT</acronym> as an
argument to this web service,
would receive an indication of whether the <acronym class="acronym">NAT</acronym> was valid
and of its contents (e.g., as an XML document).
</p></li></ul></div><p>
These hypothetical services are not described further here.
</p></div></div></div><div class="refsect1"><a name="idm625"></a><h2>SEE ALSO</h2><p>
<a class="ulink" href="dacs_notices.8.html" target="_top">dacs_notices(8)</a>
</p></div><div class="refsect1"><a name="idm629"></a><h2>AUTHOR</h2><p>Distributed Systems Software
(<a class="ulink" href="http://www.dss.ca" target="_top">www.dss.ca</a>)
and
<a class="ulink" href="http://fedroot.com/admin/about-metalogic.shtml" target="_top">Metalogic
Software Corp.</a>
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note1"></a>Note</h3><p><span class="orgname">Dss</span> and
<span class="orgname">Metalogic</span>,
the authors of this specification,
hereby permit anyone to implement this specification without fee or royalties.
</p></div></div><div class="refsect1"><a name="idm638"></a><h2>COPYING</h2><p>Copyright  2003-2012 Distributed Systems Software.
See the
<a class="ulink" href="../misc/LICENSE" target="_top"><code class="filename">LICENSE</code></a>
file that accompanies the distribution
for licensing information.
</p></div>
<!-- Generated from   $Id: dacs.nat.5.xml 2849 2015-08-24 22:58:05Z brachman $ -->
<table width="100%"><tr>
<td align="left">
<b>DACS Version 1.4.38a</b></td>
<td align="center">
<b> 2-Jun-2017</b></td>
<td align="right">
<b>DACS.NAT(5)</b></td>
</tr></table>
<hr><p>
<!-- Begin font size selector -->
<table width="100%"><tr><td align="left">
<span class="set_font"><a href="index.html" title="Table of Contents">Table of Contents</a></span></td>
<td align="center"><span class="logo"><a href="http://www.dss.ca"><img src="/css/images/dss-long-14y.png" title="Distributed Systems Software, Inc."></a></span></td>
<td width="5%" align="right">
<div class="fontsize_label" title="Font size selector">Font:</div>
</td>
<td width="10%" align="left">
<!-- NB: must set both left margin and padding to work in all browsers-->
<!-- The onFocus code eliminates annoying post-click decoration -->
<ul id="fontsizecontainer" class="size02">
 <li><a href="javascript:setFont('0');" onFocus="if(this.blur)this.blur()" title="Smallest text size [0]"><span>Z</span></a></li>
 <li><a href="javascript:setFont('1');" onFocus="if(this.blur)this.blur()" title="Medium text size [1]"><span>Z</span></a></li>
 <li><a href="JavaScript:setFont('2');" onFocus="if(this.blur)this.blur()" title="Large text size [2]"><span>Z</span></a></li>
 <li><a href="JavaScript:setFont('3');" onFocus="if(this.blur)this.blur()" title="Largest text size [3]"><span>Z</span></a></li>
</ul>
</td>
<td width="3%" align="center">
<span class="set_font"><a href="javascript:setFont('-');" onFocus="if(this.blur)this.blur()" title="Decrease current font size">&#8722;&#8722;</a></span>
</td>
<td width="3%" align="center">
<span class="set_font"><a href="javascript:setFontConfig();" onFocus="if(this.blur)this.blur()" title="Remember current font size">Set</a></span>
</td>
<td width="3%" align="center">
<span class="set_font"><a href="javascript:setFont('+');" onFocus="if(this.blur)this.blur()" title="Increase current font size">++</a></span>
</td></tr></table>
<!-- End font size selector -->
<script language="javascript" type="text/javascript">
doFontConfig();</script>
</p><small><p><b>  $Id: dacs.nat.5.xml 2849 2015-08-24 22:58:05Z brachman $</b></p></small>
</div></body></html>
dacs-examples 1.4.38a-2 / usr / share / doc / dacs-examples / man / dacs.nat.5.html
