Network Working Group M. Rose
Internet-Draft Dover Beach Consulting, Inc.
Expires: December 20, 2002 June 21, 2002
The ANANA Datastore
draft-anana-datastore-00
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at http://
www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on December 20, 2002.
Copyright Notice
Copyright (C) The Internet Society (2002). All Rights Reserved.
Abstract
This memo defines the ANANA datastore, a policy-neutral service for
managing registries, namespaces, and entries.
This document is a work-in-progress. Do not copy, cite, or
redistribute.
Rose Expires December 20, 2002 [Page 1]
Internet-Draft The ANANA Datastore June 2002
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Datastore Model . . . . . . . . . . . . . . . . . . . . . . . 5
2.1 XML Database Layer . . . . . . . . . . . . . . . . . . . . . . 5
2.2 Policy Neutral Layer . . . . . . . . . . . . . . . . . . . . . 7
2.3 Policy-Defined Layer . . . . . . . . . . . . . . . . . . . . . 12
3. Datastore Operations . . . . . . . . . . . . . . . . . . . . . 15
3.1 Processing a Request . . . . . . . . . . . . . . . . . . . . . 16
3.2 Processing an Operation . . . . . . . . . . . . . . . . . . . 18
3.3 Trigger Evaluation . . . . . . . . . . . . . . . . . . . . . . 19
3.4 Access Control Evaluation . . . . . . . . . . . . . . . . . . 20
4. Datastore Access . . . . . . . . . . . . . . . . . . . . . . . 23
4.1 Access Protocols . . . . . . . . . . . . . . . . . . . . . . . 23
4.2 Managing Authentication Information . . . . . . . . . . . . . 25
5. DTDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.1 The Operations DTD . . . . . . . . . . . . . . . . . . . . . . 27
5.2 The Registry DTD . . . . . . . . . . . . . . . . . . . . . . . 28
5.3 The AuthInfo DTD . . . . . . . . . . . . . . . . . . . . . . . 31
6. URI Schemes . . . . . . . . . . . . . . . . . . . . . . . . . 32
6.1 The anana URI Scheme . . . . . . . . . . . . . . . . . . . . . 32
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34
7.1 Registration: The anana URI Scheme . . . . . . . . . . . . . . 34
7.2 Registration: The System (Well-Known) TCP port number for
the ANANA Datastore . . . . . . . . . . . . . . . . . . . . . 35
7.3 The application/anana+xml Media Type . . . . . . . . . . . . . 36
7.4 The ANANA Datastore Profile for BEEP . . . . . . . . . . . . . 37
8. Security Considerations . . . . . . . . . . . . . . . . . . . 38
References . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Author's Address . . . . . . . . . . . . . . . . . . . . . . . 40
A. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 41
Full Copyright Statement . . . . . . . . . . . . . . . . . . . 42
Rose Expires December 20, 2002 [Page 2]
Internet-Draft The ANANA Datastore June 2002
1. Introduction
[1] introduces the concept of a policy-free registrar. To
paraphrase:
o a 'registrar' is a person, organization, or group that maintains a
registry of names and numbers;
o a 'registry' is a collection of one or more namespaces;
o a 'namespace' is a collection of one or more blocks;
o a 'block' is a collection of related entries; and,
o an 'entry' is a binding between one or more 'keys' (each being
unique within the namespace), a textual commentary, and zero or
more 'citations' that further describe the entry.
Consult [2] for an example of the provisioning strategy for a policy-
free registrar.
Typically, a registry contains a single namespace, which in turn
contains a single block having many entries (with each entry having
exactly one key). However, it may be desirable to have both multiple
namespaces within a registry, and multiple blocks within a namespace.
For example, if a registry corresponded to the parameters for a
particular protocol, then:
o that protocol might have different classes of parameters, so each
parameter class would have its own namespace in the registry;
similarly,
o within a particular parameter class, it may be natural to divide
the range of possible values into related blocks, e.g., "user-
defined", "system-reserved", and so on.
(Readers familiar with XML terminology should note that the term
'namespace', as used in this document, has no relationship to the
'XML namespace' concept.)
Rose Expires December 20, 2002 [Page 3]
Internet-Draft The ANANA Datastore June 2002
This memo describes a datastore that may be used to realize a policy-
free registry service. As a reminder to the reader, the problem
domain for the service has several notable requirements. In
particular, the service:
o supports registries that contain no more than a few million
records;
o supports registries that perform no more than a few updates each
minute;
o facilitates the separation of processes responsible for policy,
allocation, and distribution;
o facilitates automated (and mostly-automated) submissions; and,
o facilitates transformation of registries from highly-structured to
human-readable content.
In particular, the reader should appreciate that the problem domain
for this service is manifestly different than the one solved by
traditional registry-registrar protocols, such as RRP[3].
Rose Expires December 20, 2002 [Page 4]
Internet-Draft The ANANA Datastore June 2002
2. Datastore Model
ANANA registries are modeled as XML[4] documents, and logically
reside in a datastore with three conceptual layers:
layer services approach
----- -------- --------
+-------------+
| | externally-defined services
| reporting | are accessed via URI in
policy-defined | | response to certain
layer | conformance | datastore events
| |
+-------------+
| |
| access | intra-document access
policy neutral | control | control and structural
layer | | (DTD) conformance
| validity |
+-------------+
| |
| operations | a "generic" XML document
XML database | | database (perhaps emulated
layer | well- | by an RDBMS)
| formedness |
+-------------+
2.1 XML Database Layer
This layer is responsible for:
o structuring information as a collection of well-formed XML
documents; and,
o providing operations to manage XML documents in the datastore.
2.1.1 Well-Formed XML
The datastore contains XML documents, each of which correspond to a
registry.
Documents are uniquely identified using the ANANA URI (Section 6.1)
scheme. Within a datastore, documents are named using the 'abs_path'
syntax defined in RFC 2396[5] (e.g., "/anana/identities"). Within a
document, fragments are named using an XML Path Language[6] (XPath)
Rose Expires December 20, 2002 [Page 5]
Internet-Draft The ANANA Datastore June 2002
expression (e.g., "//key[@id='anana']"). Note that since an XPath
expression (typically) evaluates to a 'node-set' containing zero or
more XML fragments, the number of fragments identified by this
expression depends on the contents of the corresponding document.
Any document residing in the datastore meets two requirements:
o the document is well-formed (as described in Section 2.1 of [4]);
and,
o the only entities found in the document are XML's predefined
entities (as defined in Section 4.6 of [4]) and numeric character
references (as defined in Section 4.1 of [4]).
The first requirement is essentially the "entry cost for doing XML".
The second requirement limits the implementation complexity of the
datastore and removes a large class of potential ambiguities when
searching.
Finally, the document named "/root", and any document whose name
starts with "/root/", is reserved for use by the datastore.
2.1.2 Datastore Operations
The datastore supports two sets of operations:
o operations on documents; and,
o operations on fragments within a document.
Two document-wide operations are defined:
o 'create', which creates a new document in the datastore; and,
o 'delete', which removes an existing document from the datastore.
Operations on the fragments within a document are specified using
either:
o an XPath expression, to retrieve XML fragments; or,
o an XML Update Language[7] (XUpdate) expression, to modify an XML
fragment.
Note that in the interests of simplicity, the XUpdate expression is
limited to a single modification per operation.
Rose Expires December 20, 2002 [Page 6]
Internet-Draft The ANANA Datastore June 2002
2.2 Policy Neutral Layer
This layer is responsible for:
o ensuring data consistency on XML documents that model ANANA
registries; and,
o enforcing access control policies.
2.2.1 Valid XML
The ANANA Registry DTD (Section 5.2) defines the validity constraints
for an XML document that models an ANANA registry. Each document has
the '' element at its root. Each '' element
contains:
o a 'name' attribute uniquely identifying the registry, using a URI
that conforms to the ANANA URI (Section 6.1) scheme;
o a 'title' attribute containing a descriptive name for the
registry;
o a '' element containing:
* one or more '' elements, each containing a pointer
to registrar information;
* optionally, a '' element containing textual
information about the registry; and,
* a '' element.
o zero or more '' elements, each containing information
about a namespace within the registry; and,
o an '' element containing administrative information relating
the XML document to the datastore, specifically:
* an '' element containing zero or more '' elements,
which defines the access control policy for the document;
* a '' element containing zero or more ''
elements, which defines the conformance policy for the
document; and,
* a '' element containing zero or more ''
elements, which defines the reporting policy for the document.
Rose Expires December 20, 2002 [Page 7]
Internet-Draft The ANANA Datastore June 2002
The first fundamental concept about ANANA registries is that they are
largely pointers to other resources, and often the resource is an XML
fragment within the datastore.
For example, here is the top-level and front part of an ANANA
registry:
This is the registry used by the ANANA to identify
itself and other registrars.
...
In this example, note that the value of the '' element's
'uri' attribute points to another portion of the document in which it
resides.
Each '' element contains:
o an 'id' attribute that is unique within the document;
o a 'title' attribute containing a descriptive name for the
namespace;
o optionally, a '' element containing textual information
about the namespace;
o a '' element for the entries contained in the
namespace; and,
o zero or more '' elements.
Each '' element contains:
o an 'idPattern' attribute that indicates how the 'id' attributes of
the '' elements are generated;
o a 'type' attribute indicating whether the contents of the ''
elements is numeric or character-oriented;
Rose Expires December 20, 2002 [Page 8]
Internet-Draft The ANANA Datastore June 2002
o optionally, an 'xml:lang' attribute, meaningful only if the '' elements are character-oriented, indicating the localization
language used for the contents;
o a 'keyText' attribute containing a brief textual description of
the '' values; and,
o optionally, a 'commentText' attribute containing an additional
textual description of the '' values;
The value of 'type' attribute is one of:
o "numeric";
o "character"; or,
o "arbitrary";
If the 'type' attribute has the value "numeric", then the ABNF[8] of
the character data of each corresponding '' element is:
numeric = range *(" " range)
range = number ".." number
number = [prefix] 1*("0" / "1" / "2" / "3" / "4" /
"5" / "6" / "7" / "8" / "9")
prefix = "0x" | "0"
;; "0x" indicates hexadecimal
;; "0" indicates octal
If the 'type' attribute has the value "character", then the character
data of each corresponding each corresponding '' element
matches the 'Name' syntax defined in XML[4] documents.
If the 'type' attribute has the value "arbitrary", then no
restrictions are placed on the character data of each corresponding
'' element.
The second fundamental concept about ANANA registries is that 'id'
attributes for each entry's keys are algorithmically-generated within
each registry. Because the uniqueness of 'id' attributes is a
requirement of well-formedness, the uniqueness of registered values
within a registry is also datastore requirement.
The 'idPattern' attribute corresponds to the 'Name' syntax defined in
XML[4] documents, with one addition: the "%" character. When the
Rose Expires December 20, 2002 [Page 9]
Internet-Draft The ANANA Datastore June 2002
'id' attribute for a '' element is generated, the normalized
value corresponding to the registered value (character data) of that
element replaces the "%" character, where
o for 'numeric' values, the normalized value is the decimal
representation of the registered value for this key, where the
space character (" ") is replaced with an underscore character
("_");
o for 'character' values, the normalized value is the lowercase
string corresponding to the registered value for this key --
otherwise,
o for 'arbitrary' values, the normalized value is the base64
encoding of the lowercase string corresponding to the registered
value for this key -- normalization is performed according to the
value of the 'xml:lang' attribute of the '' element.
For example, here is the middle part of an ANANA registry:
This is ANANA's registry of identities. Typically,
registrars are listed here. Other folks (e.g., registrants)
may also be listed here, or in other registries.
ANANA
IANA
...
Each '' element contains:
o optionally, a '' element containing textual information
about the block; and,
o zero or more '' elements.
Rose Expires December 20, 2002 [Page 10]
Internet-Draft The ANANA Datastore June 2002
Each '' element contains:
o one or more '' elements, the first of which is the "primary
key" for the entry (any others are termed "aliases");
o zero or more '' elements;
o optionally, a '' element containing textual information
about the entry; and,
o a '' element.
Each '' element contains:
o an 'id' attribute that is unique within the document; and,
o the character-data corresponding to the registered value for this
key.
Each '' element contains:
o a 'uri' attribute providing additional information about the
entry;
o optionally, a 'contentType' attribute providing typing information
for the remote resource (using the convention in [9]); and,
o a brief textual description of the citation.
2.2.2 Access Control
There are two kinds of access control policies enforced by the
datastore:
o fragment-specific policies, which are contained within each XML
document; and,
o document-specific policies, which are contained within a special
XML document in the datastore.
In each case, the datastore consults the appropriate document's
'' element to determine the policy in effect.
The '' element contains zero or more '' elements. Each
'' element contains:
o a 'subject' attribute identifying the XML fragments to which this
Rose Expires December 20, 2002 [Page 11]
Internet-Draft The ANANA Datastore June 2002
access control entry applies;
o optionally, an 'actor' attribute identifying the client identities
to which this access control entry applies (if not present, then
the element refers to any client, possibly unauthenticated); and,
o a 'permitted' attribute identifying the operations that are
allowed for this particular subject/actor pairing.
The 'subject' attribute is specified as an XPath expression;
similarly, the 'actor' attribute is often given as an ANANA URI.
Accordingly, a single access control entry may refer to multiple
fragments within an XML document and/or multiple client identities.
For example, here is an '' element for a particular ANANA
registry:
In this example, note that while both access control entries refer to
the entire document, different access is granted based on the client
identity.
Ordering of access control entries is important: the first access
control entry with a matching subject/actor pair is used. Of course,
if none of the access control entries apply, then no access is
allowed.
2.3 Policy-Defined Layer
This layer is responsible for:
o ensuring registrar-specific conformance policies; and,
o reporting registry modifications.
2.3.1 Conformance
A registrar may place additional conformance requirements on the
entries in a registry. Before performing any modifications, the
datastore consults the document's '' element to
determine the policy in effect. Conformance policies are implemented
remotely from the datastore, and are accessed via a remote resource.
Rose Expires December 20, 2002 [Page 12]
Internet-Draft The ANANA Datastore June 2002
The '' element contains zero or more ''
elements. Each '' element contains:
o a 'subject' attribute identifying the XML fragments to which this
conformance entry applies; and,
o a '' element.
The 'subject' attribute is specified as an XPath expression;
accordingly, a single conformance entry may refer to multiple
fragments within an XML document.
For example, here is a '' element for a particular
ANANA registry:
validate-citations
which says that whenever an entry is modified, then an HTTP-based
resource is asked to examine the citations in the entry.
A conformance trigger reports three possible outcomes:
o success;
o deferral; or,
o failure.
On deferral or failure, any response data from the trigger is
returned to the client and no further action is taken by the
datastore. Typically, a deferral indicates that a registrar will
examine the entry later on (typically out-of-band), and that no other
action is required by the client.
Ordering of conformance entries is important: the first conformance
entry with a matching subject is used.
Rose Expires December 20, 2002 [Page 13]
Internet-Draft The ANANA Datastore June 2002
2.3.2 Reporting
A registrar may place additional reporting requirements on the
entries in a registry. After performing any modifications, the
datastore consults the document's '' element to determine
the policy in effect. Reporting policies are implemented remotely
from the datastore, and are accessed via a remote resource.
The '' element contains zero or more ''
elements. Each '' element contains:
o a 'subject' attribute identifying the XML fragments to which this
reporting entry applies;
o optionally, an 'actor' attribute identifying the client identities
to which this reporting entry applies (if not present, then the
element refers to any client, possibly unauthenticated); and,
o a '' element.
The 'subject' attribute is specified as an XPath expression;
similarly, the 'actor' attribute is often given as an ANANA URI.
Accordingly, a single reporting entry may refer to multiple fragments
within an XML document and/or multiple client identities.
The outcome of a reporting trigger may be logged, but is otherwise
ignored by the datastore. Ordering of reporting entries is
important, the first reporting entry with a matching subject/actor
pair is used.
Rose Expires December 20, 2002 [Page 14]
Internet-Draft The ANANA Datastore June 2002
3. Datastore Operations
When a client wishes to interact with the datastore, it selects an
access protocol (Section 4.1), optionally authenticates itself, and
then submits one or more requests to the datastore, which returns a
result or an error for each request.
The ANANA Operations DTD (Section 5.1) defines the format of requests
and results, using the '' and '' elements,
respectively. The '' element, defined in Section 7.1 of
[10], is used to convey error information.
The '' element contains:
o a 'docName' attribute identifying a document in the datastore;
and,
o either:
* a '', to operate on an entire document; or,
* a '' element, to operate on the fragments within
a document.
The '' element contains:
o an 'operation' attribute indicating whether the document should be
created or deleted; and,
o arbitrary XML content, which is meaningful only if the create
operation is requested, and is ignored otherwise.
The '' element contains either:
o a '' element, which contains an 'xpath' attribute
identifying the XML fragments to which this operation applies; or,
o a '' element, (defined in Section 2.11 of
[7] and having exactly one subordinate element).
Rose Expires December 20, 2002 [Page 15]
Internet-Draft The ANANA Datastore June 2002
3.1 Processing a Request
When the datastore receives a '' element, it performs these
steps:
1. If the 'docName' attribute of the '' element does not
identify an existing document in the datastore, and if the
'' element does not contain a '' element
whose 'operation' attribute has a value of "create", then an
'' element having code 550 is returned to the client, and
no further processing occurs.
2. If the '' element contains a '' element
whose 'operation' attribute has a value of "create" then:
1. If the 'docName' attribute of the '' element
identifies an existing document in the datastore, then an
'' element having code 555 is returned to the client,
and no further processing occurs.
2. The datastore verifies that the content of the '' element is a valid '' element (cf., Section
2.2.1). If not, an '' element having code 505 is
returned to the client, and no further processing occurs.
3. If the '' element contains a ''
element, then:
1. The datastore computes the "snapshot" -- the document that
results if the operation were to be applied.
2. The datastore verifies that the snapshot is valid (cf.,
Section 2.2.1). If not, an '' element having code
505 is returned to the client, and no further processing
occurs.
3. The datastore extracts the "target" -- the 'select' attribute
of the subordinate element of the ''
element.
4. The datastore retrieves the '' element
contained in the original document, and examines each
'' element in the order they appear looking for the
first conformance entry having a 'subject' attribute that,
when applied to the snapshot, includes the target path.
5. If such an entry exists, then the datastore evaluates the
trigger associated with the conformance entry (cf., Section
Rose Expires December 20, 2002 [Page 16]
Internet-Draft The ANANA Datastore June 2002
3.3):
+ If the trigger reports a failure outcome, this is returned
to the client in an '' element, and no further
processing occurs.
+ If the trigger reports a deferral outcome, an ''
element having code 300 is returned to the client, and no
further processing occurs.
4. The datastore retrieves the appropriate access entry for the
client identity and determines the required access token for the
operation, according to the rules given in Section 3.4. The
datastore examines the 'permitted' attribute of the access entry
and sees if it contains either the required access token or the
value "all". If not, an '' element having code 537 is
returned to the client, and no further processing occurs.
5. The datastore performs the operation according to the rules given
in Section 3.2.
6. If the '' element contains a ''
element, then:
1. The datastore retrieves the '' element contained
in the snapshot, and examines each '' element in the
order they appear looking for the first reporting entry
having a 'subject' attribute that, when applied to the
snapshot, includes the target path, and having an 'actor'
attribute that matches the client identity.
2. If such an entry exists, then the datastore evaluates the
trigger associated with the reporting entry (cf., Section
3.3).
7. A '' element is returned to the client:
* if the '' element contains a '' element,
then the ''element contains the XML fragments
corresponding to the XPath expression in the ''
element; otherwise,
* the contents of the '' element is empty.
Rose Expires December 20, 2002 [Page 17]
Internet-Draft The ANANA Datastore June 2002
3.2 Processing an Operation
3.2.1 Create a Document
If the '' element contains a '' element whose
'operation' attribute has the value "create" then:
1. A document is created in the datastore having a name identical to
the '' element's 'docName' attribute, and whose
contents is identical to the contents of the ''
element.
3.2.2 Delete a Document
If the '' element contains a '' element whose
'operation' attribute has the value "delete" then:
1. The document in the datastore identified by the value of the
'' element's 'docName' attribute is removed from the
datastore.
3.2.3 Fetch Document Fragments
If the '' element contains a '' element that
contains a '' element, then:
1. The value of the '' element's 'xpath' attribute is
evaluated as an XPath expression, and the resulting value is
returned as the contents of a '' element.
3.2.4 Modify a Document Fragment
If the '' element contains a '' element that
contains a '' element, then:
1. The contents of the '' element is evaluated as an
XUpdate expression.
Rose Expires December 20, 2002 [Page 18]
Internet-Draft The ANANA Datastore June 2002
3.3 Trigger Evaluation
Triggers implement registrar-specific policies by accessing a remote
resource.
The '' element contains:
o a 'uri' attribute, identifying a resource to examine; and,
o zero or more '' elements, each containing a name/value
pair presented as a parameter to the resource.
In addition to whatever parameters are specified in the trigger
element, the datastore also includes these two parameters when a
trigger is evaluated:
o a parameter called "clientIdentity" having as its value the client
identity associated with the client (if the client is
unauthenticated, then an empty string is supplied); and,
o a parameter called "request" containing the corresponding
'' element.
The datastore evaluates the trigger using an algorithm specific to
the scheme used in the trigger's URI. The algorithm must define:
o how parameters are passed to the resource; and,
o how the resource is retrieved.
At present, the algorithm for two schemes, 'http' and 'https', are
specified.
3.3.1 HTTP/HTTPS-based Triggers
A trigger specified via 'http' or 'https' is evaluated using the
HTTP[11] 'POST' operation containing the parameters to the trigger.
The datastore examines the HTTP response code when a reply is
returned, to determine the trigger's outcome, either:
o success, if the HTTP response has code 2xx;
o a deferral, if the HTTP response has code 300; or,
o failure, for any other response
Rose Expires December 20, 2002 [Page 19]
Internet-Draft The ANANA Datastore June 2002
3.4 Access Control Evaluation
When the datastore is asked to performed an operation, it must make
two determinations:
o the required access token for the operation; and,
o the appropriate access entry for the client identity.
The datastore determines the required access token by consulting this
table:
request pattern access token
------------------------------------------- ------------
/request/docRequest[@operation='create'] create
/request/docRequest[@operation='delete'] delete
/request/fragRequest/fetch read
/request/fragRequest/xupdate:modifications
/xupdate:insert-before insert
/request/fragRequest/xupdate:modifications
/xupdate:insert-after insert
/request/fragRequest/xupdate:modifications
/xupdate:append write
/request/fragRequest/xupdate:modifications
/xupdate:update write
/request/fragRequest/xupdate:modifications
/xupdate:remove write
/request/fragRequest/xupdate:modifications
/xupdate:rename write
Determining the appropriate access control entry depends on whether
the operation pertains to an entire document (the ''
element contains a '') or the fragments within a
document (the '' element contains a '').
Rose Expires December 20, 2002 [Page 20]
Internet-Draft The ANANA Datastore June 2002
3.4.1 Document-specific Policies
If the operation pertains to an entire document, a document-specific
policy is consulted.
The datastore retrieves the '' element contained in a document
named "/root/access", and examines each '' element in the order
they appear. For each access entry:
o if the 'subject' attribute is identical to the 'docName' attribute
of the '' element; and,
o if the 'actor' attribute matches the client identity
then this '' element is the appropriate access control entry.
If no access control entry is appropriate, then a transient access
entry is returned having:
o the 'subject' attribute set to the value of the 'docName'
attribute of the '' element;
o the 'actor' attribute set to the client identity of the client;
and,
o the 'permitted' attribute set to "none".
Rose Expires December 20, 2002 [Page 21]
Internet-Draft The ANANA Datastore June 2002
3.4.2 Fragment-specific Policies
If the operation pertains to the fragments within a document, a
fragment-specific policy is consulted.
The datastore retrieves the '' element contained in the
document containing the fragments, and examines each '' element
in the order they appear. For each access entry:
o if the 'subject' attribute when applied to the snapshot document
includes:
* any XML fragment identified by the '' element; or,
* the XML fragment modified by the ''
element
o and if the 'actor' attribute matches the client identity
then this '' element is the appropriate access control entry.
If no access control entry is appropriate, then a transient access
entry is returned having:
o the 'subject' attribute set to "/";
o the 'actor' attribute set to the client identity of the client;
and,
o the 'permitted' attribute set to "none".
Rose Expires December 20, 2002 [Page 22]
Internet-Draft The ANANA Datastore June 2002
4. Datastore Access
To access the datastore, a client requires:
o an access protocol; and,
o a mechanism for managing authentication information.
4.1 Access Protocols
This memo defines two ways to access the ANANA Datastore:
o using BEEP[10]; and,
o using SMTP[12].
4.1.1 via BEEP
For interactive access to the datastore, BEEP is used.
The BEEP profile for the ANANA Datastore is identified as:
http://anana.org/beep/anana-datastore
in the BEEP '' element during channel creation.
In BEEP, when the first channel is successfully created, the
'serverName' attribute in the '' element identifies the
"virtual host" associated with the peer acting in the server role,
e.g.,
The 'serverName' attribute is analagous to HTTP's 'Host' request-
header field (cf., Section 14.23 of [11]).
No elements are required to be exchanged during channel creation;
however, the BEEP initiator may choose to piggyback a ''
element during channel creation. If the channel is successfully
created, then the BEEP listener performs the piggyback'd operation
and returns either a '' element or an '' element as
piggyback'd data. (Note well that Section 2.3.1.2 of [10] limits the
amount of piggyback'd data to 4K octets.)
Rose Expires December 20, 2002 [Page 23]
Internet-Draft The ANANA Datastore June 2002
All messages are exchanged as 'application/beep+xml', and only one-
to-one exchanges are permitted, i.e.,
role MSG RPY ERR
==== === === ===
I request result error
where the '' and '' elements are defined in
Section 5.1, and the '' element is defined in Section 7.1 of
[10].
4.1.2 via SMTP
For batch access to the datastore, email is used.
The '' and '' elements (defined in Section 5.1)
are used to batch multiple requests and results into a single
message, tagged as |"application/xml|[13].
The '' element contains:
o an 'originator' attribute identifying the client making the
requests using an URI that conforms to the ANANA URI scheme; and,
o zero or more '' elements.
The '' element contains zero or more '' and
'' elements.
The client may choose to to use MIME-based security (cf., Section 8)
for the message. If so, the datastore must be pre-configured to
understand the mapping between the cryptographic information used by
the client and the corresponding client identity. If there is an
error in processing the MIME-based security wrappers, then a message
containing a '' element that contains a single ''
element is sent to the client, and no further processing occurs.
If the client does not use MIME-based security, then the datastore
retrieves the '' element associated with the 'originator'
attribute of the '' element, and looks for a ''
element with:
o a 'uri' attribute containing a "mailto:" URI; and,
o a 'contentType' attribute having the value
"ContentType:application/anana+xml?type="authInfo".
Rose Expires December 20, 2002 [Page 24]
Internet-Draft The ANANA Datastore June 2002
If no such element exists, then a message containing a ''
element that contains a single '' element having code 530 is
sent to the client, and no further processing occurs. Otherwise:
1. The datastore sends a message to the mailbox identified by the
'uri' attribute, which contains an unpredictable token and
instructions for replying.
2. If a reply is received sometime later, then the original message
is considered authentic and processing continues.
3. Otherwise, a message containing a '' element that
contains a single '' element having code 531 is sent to
the client, and no further processing occurs.
The duration to wait for an acceptable response is a local policy
matter.
Regardless of the mechanism, if the message is deemed authentic, then
the datastore processes each '' element in the order in
which it appears in the '' element. Upon completion, a
message containing a '' element (having the same number of
subordinate elements as the '' element) is sent to the
client.
4.2 Managing Authentication Information
In order to facilitate the management of authentication information,
whenever an '' element is successfully added or modified, the
datastore examines each '' element in the order they
appear. If the value of the element's 'contentType' attribute is
"ContentType:application/anana+xml?type="authInfo", and if the
element's 'uri' attribute contains an 'https' URI, then:
1. The datastore accesses the URI using the 'GET' operation and a
client-side certificate.
2. If the request is successful and returns an XML document
containing an '' element, then the contents of that
element are used by the datastore for future SASL-based
authentication.
The '' element contains zero or more '' elements,
each containing a name/value pair.
Rose Expires December 20, 2002 [Page 25]
Internet-Draft The ANANA Datastore June 2002
This memo defines two parameter names:
sharedSecret: The value of this parameter is a shared secret that may
be used with SASL mechanisms such as DIGEST-MD5[14].
otpInfo: The value of this parameter is an 'init-hex' response
defined in [15] (where the 'current-OTP' field is ignored) that
may be used with the SASL OTP mechanism[16].
Rose Expires December 20, 2002 [Page 26]
Internet-Draft The ANANA Datastore June 2002
5. DTDs
5.1 The Operations DTD
Rose Expires December 20, 2002 [Page 27]
Internet-Draft The ANANA Datastore June 2002
5.2 The Registry DTD
Rose Expires December 20, 2002 [Page 28]
Internet-Draft The ANANA Datastore June 2002
%rfc2629.dtd;
Rose Expires December 20, 2002 [Page 29]
Internet-Draft The ANANA Datastore June 2002
Rose Expires December 20, 2002 [Page 30]
Internet-Draft The ANANA Datastore June 2002
5.3 The AuthInfo DTD
Rose Expires December 20, 2002 [Page 31]
Internet-Draft The ANANA Datastore June 2002
6. URI Schemes
6.1 The anana URI Scheme
The "anana" URI scheme uses the "generic URI" syntax defined in
Section 3 of [5], specifically:
o the value "anana" is used for the scheme component;
o the server-based naming authority defined in Section 3.2.2 of [5]
is used for the authority component; and,
o the path component corresponds to an 'abs_path', as defined in RFC
2396[5], followed by an optional 'fragment' suffix.
The values of both the scheme and authority components are case-
insensitive. If the path component is absent, then it defaults to
the root document, "/".
The ABNF of the "anana" URI scheme is:
anana_uri = "anana" ":" "//" authority [ abs_path [ frag_id ] ]
frag_id = "#" "xpath" "(" balanced_parens ")"
balanced_parens = *( escaped_parens | balanced_text )
escaped_parens = "^()^^" | "^^^^" | "^^(" | "^^)"
;; "^(" escapes "("
;; "^)" escapes ")"
;; "^^" escapes "^"
balanced_text = ( "(" balanced_parens ")" ) | noparens_text
noparens_text = *<>
;; authority, abs_path, uric are defined in RFC 2396
Rose Expires December 20, 2002 [Page 32]
Internet-Draft The ANANA Datastore June 2002
For example,
anana://anana.org/anana/identities#xpath(//key[text()="ANANA"])
anana://anana.org/anana/identities
anana://anana.org:1026
anana://10.0.0.2/
are all valid ANANA URIs.
6.1.1 Resolving IP/TCP Address Information
The "anana" URI scheme indicates the use of the BEEP profile for the
ANANA datastore service running over TCP/IP.
If the authority component contains a domain name and a port number,
e.g.,
anana://anana.org:1026
then the DNS is queried for the A RRs corresponding to the domain
name, and the port number is used directly.
If the authority component contains a domain name and no port number,
e.g.,
anana://anana.org
the SRV algorithm[17] is used with a service parameter of "anana-
store" and a protocol parameter of "tcp" to determine the IP/TCP
addressing information. If no appropriate SRV RRs are found (e.g.,
for "_anana-store._tcp.anana.org"), then the DNS is queried for the A
RRs corresponding to the domain name and the port number used is
assigned by the IANA for the registration in Section 7.2.
If the authority component contains an IP address, e.g.,
anana://10.0.0.2:1026
then the DNS is not queried, and the IP address is used directly. If
a port number is present, it is used directly; otherwise, the port
number used is assigned by the IANA for the registration in Section
7.2.
While the use of literal IPv6 addresses in URIs is discouraged, if a
literal IPv6 address is used in an "anana" URI, it must conform to
the syntax specified in [18].
Rose Expires December 20, 2002 [Page 33]
Internet-Draft The ANANA Datastore June 2002
7. IANA Considerations
The IANA registers "anana" as a URI scheme, as specified in Section
7.1.
The IANA registers "ANANA datastore" as a TCP port number, as
specified in Section 7.2.
The IANA registers "application/anana+xml" as a MIME media type, as
specified in Section 7.3.
The IANA registers the BEEP profile specified in Section 7.4, and
selects an IANA-specific URI, e.g.,
http://iana.org/beep/anana-datastore
7.1 Registration: The anana URI Scheme
URI scheme name: anana
URI scheme syntax: cf., Section 6.1
Character encoding considerations: cf., the "generic URI" syntax
defined in Section 3 of [5]
Intended usage: identifies an XML document or fragment in an ANANA
datastore
Applications using this scheme: cf., "Intended usage", above
Interoperability considerations: n/a
Security Considerations: cf., Section 8
Relevant Publications: cf., this memo
Contact Information: Marshall Rose
Author/Change controller: the IESG
Rose Expires December 20, 2002 [Page 34]
Internet-Draft The ANANA Datastore June 2002
7.2 Registration: The System (Well-Known) TCP port number for the ANANA
Datastore
Protocol Number: TCP
Message Formats, Types, Opcodes, and Sequences: cf., Section 5.1
Functions: cf., Section 3
Use of Broadcast/Multicast: none
Proposed Name: ANANA Datastore
Short name: anana-store
Contact Information: Marshall Rose
Rose Expires December 20, 2002 [Page 35]
Internet-Draft The ANANA Datastore June 2002
7.3 The application/anana+xml Media Type
MIME Media Type Name: Application
MIME subtype name: anana+xml
Required Parameters: type
Optional Parameters: charset (defaults to UTF-8[19])
Encoding Considerations: 8-bit
Security Considerations: avoid third-party disclosure as this media
type may contain authentication information
Interoperability Considerations: n/a
Published Specification: This media type contains an XML XML[4]
document, as indicated by the 'type' parameter.
Two restrictions are made. First, no entity references other than
the five predefined general entities references ("&", "<",
">", "'", and """) and numeric entity references may
be present. Second, neither the "XML" declaration (e.g., ) nor the "DOCTYPE" declaration (e.g., ) may be
present. (Accordingly, if another character set other than UTF-8
is desired, then the "charset" parameter must be present.) All
other XML 1.0 instructions (e.g., CDATA blocks, processing
instructions, and so on) are allowed.
If the 'type' parameter has the value "authInfo", then the
document corresponds to the syntax given in Section 5.3.
Appliations which use this media type: the ANANA datastore
Additional Information: none
Intended usage: cf., Section 4.1
Additional Information: none
Intended usage: limited use
Contact Information: Marshall Rose
Author/Change controller: the IESG
Rose Expires December 20, 2002 [Page 36]
Internet-Draft The ANANA Datastore June 2002
7.4 The ANANA Datastore Profile for BEEP
Profile Identification: http://anana.org/beep/anana-datastore
Messages exchanged during Channel Creation: request,result
Messages starting one-to-one exchanges: request
Messages in positive replies: result
Messages in negative replies: error
Messages in one-to-many exchanges: none
Message Syntax: cf., Section 5.1
Message Semantics: cf., Section 3
Contact Information: Marshall Rose
Rose Expires December 20, 2002 [Page 37]
Internet-Draft The ANANA Datastore June 2002
8. Security Considerations
Although service provisioning is a policy matter, at a minimum, all
implementations must provide the following tuning profiles:
for authentication: http://iana.org/beep/SASL/DIGEST-MD5
for confidentiality: http://iana.org/beep/TLS (using the
TLS_RSA_WITH_3DES_EDE_CBC_SHA cipher)
for both: http://iana.org/beep/TLS (using the
TLS_RSA_WITH_3DES_EDE_CBC_SHA cipher supporting client-side
certificates)
Further, implementations may choose to offer MIME-based security
services providing message integrity and confidentiality, such as
OpenPGP[20] or S/MIME[21].
Regardless, consult:
o [10]'s Section 9 for a discussion of BEEP-specific security
issues; and,
o [12]'s Section 7 for a discussion of SMTP-specific security
issues.
Finally, any remote resource accessed by a trigger should ensure that
traffic originating from the datastore is authentic before taking any
action that changes state.
Rose Expires December 20, 2002 [Page 38]
Internet-Draft The ANANA Datastore June 2002
References
[1] Malamud, C., Malamud, R. and M. Rose, "Overview of Assigned
Name and Number Allocation (ANANA)", draft-anana-overview-00
(work in progress), June 2002.
[2] Malamud, C., Malamud, R. and M. Rose, "Implementation of ANANA
namespaces at anana.org"", draft-anana-implementation-00 (work
in progress), June 2002.
[3] Hollenbeck, S. and M. Srivastava, "NSI Registry Registrar
Protocol (RRP) Version 1.1.0", RFC 2832, May 2000.
[4] Bray, T., Paoli, J., Sperberg-McQueen, C. and E. Maler,
"Extensible Markup Language (XML) 1.0 (2nd ed)", W3C REC-xml,
October 2000, .
[5] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform
Resource Identifiers (URI): Generic Syntax", RFC 2396, August
1998.
[6] World Wide Web Consortium, "XML Path Language (XPath) Version
1.0", W3C XPath, November 1999, .
[7] Laux, A. and L. Martin, "XML Update Language: Working Draft",
September 2000, .
[8] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 2234, November 1997.
[9] Eastlake, D., "Mapping Between MIME Types, Content-Types and
URIs", draft-eastlake-cturi-03 (work in progress), November
2001.
[10] Rose, M., "The Blocks Extensible Exchange Protocol Core", RFC
3080, March 2001.
[11] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L.,
Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol --
HTTP/1.1", RFC 2616, June 1999.
[12] Klensin, J., "Simple Mail Transfer Protocol", RFC 2821, April
2001.
[13] Murata, M., St.Laurent, S. and D. Kohn, "XML Media Types", RFC
3023, January 2001.
Rose Expires December 20, 2002 [Page 39]
Internet-Draft The ANANA Datastore June 2002
[14] Leach, P. and C. Newman, "Using Digest Authentication as a SASL
Mechanism", RFC 2831, May 2000.
[15] Metz, C., "OTP Extended Responses", RFC 2243, November 1997.
[16] Newman, C., "The One-Time-Password SASL Mechanism", RFC 2444,
October 1998.
[17] Gulbrandsen, A., Vixie, P. and L. Esibov, "A DNS RR for
specifying the location of services (DNS SRV)", RFC 2782,
February 2000.
[18] Haskin, D. and E. Allen, "IP Version 6 over PPP", RFC 2472,
December 1998.
[19] Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC
2279, January 1998.
[20] Elkins, M., Del Torto, D., Levien, R. and T. Roessler, "MIME
Security with OpenPGP", RFC 3156, August 2001.
[21] Ramsdell, B., "S/MIME Version 3 Message Specification", RFC
2633, June 1999.
[22] Alvestrand, H., "Tags for the Identification of Languages", RFC
1766, March 1995.
Author's Address
Marshall T. Rose
Dover Beach Consulting, Inc.
POB 255268
Sacramento, CA 95865-5268
US
Phone: +1 916 483 8878
EMail: mrose@dbc.mtview.ca.us
Rose Expires December 20, 2002 [Page 40]
Internet-Draft The ANANA Datastore June 2002
Appendix A. Acknowledgments
The author acknowledges the contributions of Graham Klyne and Carl
Malamud. In addition, the syntax of the fragment identifier is based
on the generic fragment identifier syntax proposed by Jonathan Borden
and Simon St. Laurent.
Rose Expires December 20, 2002 [Page 41]
Internet-Draft The ANANA Datastore June 2002
Full Copyright Statement
Copyright (C) The Internet Society (2002). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Acknowledgement
Funding for the RFC Editor function is currently provided by the
Internet Society.
Rose Expires December 20, 2002 [Page 42]