TOC 
Network Working GroupM. Rose
Internet-DraftDover Beach Consulting, Inc.
Expires: December 24, 2002June 25, 2002

The ANANA Datastore
draft-anana-datastore-01

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 24, 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.



 TOC 

Table of Contents




 TOC 

1. Introduction

[1] introduces the concept of a policy-free registrar. To paraphrase:

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:

(Readers familiar with XML terminology should note that the term namespace, as used in this document, has no relationship to the XML namespace concept.)

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:

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].



 TOC 

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:

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 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) 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:

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:

Two document-wide operations are defined:

Operations on the fragments within a document are specified using either:

Note that in the interests of simplicity, the XUpdate expression is limited to a single modification per operation.

2.2 Policy Neutral Layer

This layer is responsible for:

2.2.1 Valid XML

The ANANA Registry DTD defines the validity constraints for an XML document that models an ANANA registry. Each document has the <registry/> element at its root. Each <registry/> element contains:

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:

<registry name='anana://anana.org/anana/identities'
          title='ANANA list of identities (people, roles)'>
    
<fore>
<registrar
    uri='anana://.../anana/identities#xpath(//key[text()="ANANA"])' />
    
<comment><t>This is the registry used by the ANANA to identify
itself and other registrars.</t></comment>
    
<date month='May' year='2002' />
</fore>

...

In this example, note that the value of the <registrar/> element's uri attribute points to another portion of the document in which it resides.

Each <namespace/> element contains:

Each <template/> element contains:

The value of type attribute is one of:

If the type attribute has the value numeric, then the ABNF[8] of the character data of each corresponding <key/> 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 <key/> 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 <key/> 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 id attribute for a <key/> element is generated, the normalized value corresponding to the registered value (character data) of that element replaces the % character, where

For example, here is the middle part of an ANANA registry:

    <namespace id='identity' title='List of Identities'>
    <comment><t>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.</t></comment>
    
    <template idPattern='id.%' type='character' keyText='Registrar' />
    
    <block>
    <entry>
    <key id='id.anana'>ANANA</key>
    <citation uri='http://www.anana.org' />
    </entry>
    
    <entry>
    <key id='id.iana'>IANA</key>
    <citation uri='http://www.iana.org' />
    </entry>
    
    ...
    </block>
    </namespace>

Each <block/> element contains:

Each <entry/> element contains:

Each <key/> element contains:

Each <citation/> element contains:

2.2.2 Access Control

There are two kinds of access control policies enforced by the datastore:

In each case, the datastore consults the appropriate document's <acl/> element to determine the policy in effect.

The <acl/> element contains zero or more <ac/> elements. Each <ac/> element contains:

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 <acl/> element for a particular ANANA registry:

<acl>
<ac subject='/' permitted='all'
    actor='anana://.../anana/identities#xpath(//key[text()="ANANA"])' />
<ac subject='/' permitted='read' />
</acl>

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:

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 <conformance/> element to determine the policy in effect. Conformance policies are implemented remotely from the datastore, and are accessed via a remote resource.

The <conformance/> element contains zero or more <conform/> elements. Each <conform/> element contains:

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 <conformance/> element for a particular ANANA registry:

    <conformance>
    <conform subject='/registry/namespace/block/entry'>
    <trigger uri='http://anana.org/cgi-bin/nph-validate.cgi'>
        <param name='mode'>validate-citations</param>
    </trigger>
    </conform>
    </conformance>

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:

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.

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 <reporting/> element to determine the policy in effect. Reporting policies are implemented remotely from the datastore, and are accessed via a remote resource.

The <reporting/> element contains zero or more <report/> elements. Each <report/> element contains:

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.



 TOC 

3. Datastore Operations

When a client wishes to interact with the datastore, it selects an access protocol, 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 defines the format of requests and results, using the <request/> and <result/> elements, respectively. The <error/> element, defined in Section 7.1 of [10], is used to convey error information.

The <request/> element contains:

The <docRequest/> element contains:

The <fragRequest/> element contains either:

3.1 Processing a Request

When the datastore receives a <request/> element, it performs these steps:

  1. If the docName attribute of the <request/> element does not identify an existing document in the datastore, and if the <request/> element does not contain a <docRequest/> element whose operation attribute has a value of create, then an <error/> element having code 550 is returned to the client, and no further processing occurs.
  2. If the <request/> element contains a <docRequest/> element whose operation attribute has a value of create then:
    1. If the docName attribute of the <request/> element identifies an existing document in the datastore, then an <error/> element having code 555 is returned to the client, and no further processing occurs.
    2. The datastore verifies that the content of the <docRequest/> element is a valid <registry/> element (cf., Valid XML). If not, an <error/> element having code 505 is returned to the client, and no further processing occurs.

  3. If the <request/> element contains a <xupdate:modifications/> 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., Valid XML). If not, an <error/> 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 <xupdate:modifications/> element.
    4. The datastore retrieves the <conformance/> element contained in the original document, and examines each <conform/> 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., Trigger Evaluation):
      • If the trigger reports a failure outcome, this is returned to the client in an <error/> element, and no further processing occurs.
      • If the trigger reports a deferral outcome, an <error/> 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 Access Control Evaluation. 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 <error/> 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 Processing an Operation.
  6. If the <request/> element contains a <xupdate:modifications/> element, then:
    1. The datastore retrieves the <reporting/> element contained in the snapshot, and examines each <report/> 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., Trigger Evaluation).

  7. A <result/> element is returned to the client:
    • if the <request/> element contains a <fetch/> element, then the <result/>element contains the XML fragments corresponding to the XPath expression in the <fetch/> element; otherwise,
    • the contents of the <result/> element is empty.

3.2 Processing an Operation

3.2.1 Create a Document

If the <request/> element contains a <docRequest/> element whose operation attribute has the value create then:

  1. A document is created in the datastore having a name identical to the <request/> element's docName attribute, and whose contents is identical to the contents of the <docRequest/> element.

3.2.2 Delete a Document

If the <request/> element contains a <docRequest/> element whose operation attribute has the value delete then:

  1. The document in the datastore identified by the value of the <request/> element's docName attribute is removed from the datastore.

3.2.3 Fetch Document Fragments

If the <request/> element contains a <fragRequest/> element that contains a <fetch/> element, then:

  1. The value of the <fetch/> element's xpath attribute is evaluated as an XPath expression, and the resulting value is returned as the contents of a <result/> element.

3.2.4 Modify a Document Fragment

If the <request/> element contains a <fragRequest/> element that contains a <xupdate:modifications/> element, then:

  1. The contents of the <fragRequest/> element is evaluated as an XUpdate expression.

3.3 Trigger Evaluation

Triggers implement registrar-specific policies by accessing a remote resource.

The <trigger/> element contains:

In addition to whatever parameters are specified in the trigger element, the datastore also includes these two parameters when a trigger is evaluated:

The datastore evaluates the trigger using an algorithm specific to the scheme used in the trigger's URI. The algorithm must define:

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:

3.4 Access Control Evaluation

When the datastore is asked to performed an operation, it must make two determinations:

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 <request/> element contains a <docRequest/>) or the fragments within a document (the <request/> element contains a <fragRequest/>).

3.4.1 Document-specific Policies

If the operation pertains to an entire document, a document-specific policy is consulted.

The datastore retrieves the <acl/> element contained in a document named /root/access, and examines each <ac/> element in the order they appear. For each access entry:

then this <ac/> element is the appropriate access control entry.

If no access control entry is appropriate, then a transient access entry is returned having:

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 <acl/> element contained in the document containing the fragments, and examines each <ac/> element in the order they appear. For each access entry:

then this <ac/> element is the appropriate access control entry.

If no access control entry is appropriate, then a transient access entry is returned having:



 TOC 

4. Datastore Access

To access the datastore, a client requires:

4.1 Access Protocols

This memo defines two ways to access the ANANA Datastore:

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 <profile/> element during channel creation.

In BEEP, when the first channel is successfully created, the serverName attribute in the <start/> element identifies the virtual host associated with the peer acting in the server role, e.g.,

    <start number='1' serverName='anana.org'>
        <profile uri='http://anana.org/beep/anana-datastore' />
    </start>

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 <request/> element during channel creation. If the channel is successfully created, then the BEEP listener performs the piggyback'd operation and returns either a <result/> element or an <error/> 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.)

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 <request/> and <result/> elements are defined in The Operations DTD, and the <error/> element is defined in Section 7.1 of [10].

4.1.2 via SMTP

For batch access to the datastore, email is used.

The <reqbatch/> and <rspbatch/> elements (defined in The Operations DTD) are used to batch multiple requests and results into a single message, tagged as application/xml[13].

The <reqbatch/> element contains:

The <rspbatch/> element contains zero or more <result/> and <error/> elements.

The client may choose to to use MIME-based security (cf., Security Considerations) 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 <rspbatch/> element that contains a single <error/> 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 <entry/> element associated with the originator attribute of the <reqbatch/> element, and looks for a <citation/> element with:

If no such element exists, then a message containing a <rspbatch/> element that contains a single <error/> 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 <rspbatch/> element that contains a single <error/> 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 <request/> element in the order in which it appears in the <reqbatch/> element. Upon completion, a message containing a <rspbatch/> element (having the same number of subordinate elements as the <reqbatch/> element) is sent to the client.

4.2 Managing Authentication Information

In order to facilitate the management of authentication information, whenever an <entry/> element is successfully added or modified, the datastore examines each <citation/> 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 <authInfo/> element, then the contents of that element are used by the datastore for future SASL-based authentication.

The <authInfo/> element contains zero or more <param/> elements, each containing a name/value pair.

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].



 TOC 

5. DTDs

5.1 The Operations DTD

<!--
  DTD data types:

        entity        syntax/reference        example
        ======        ================        =======

    uniform resource identifier
        URI           cf., RFC 2396           http://anana.org/

    XML document name
        PATH          cf., abs_path in        /anana/identities
                      RFC 2396

    XPath expression
        XPATH         cf., W3C REC XPath      //key[@id='anana']
  -->

<!ENTITY % URI        "CDATA">
<!ENTITY % PATH       "CDATA">
<!ENTITY % XPATH      "CDATA">


<!--
  Requests
  -->

<!ELEMENT request     (docRequest|fragRequest)>
<!ATTLIST request
          docName     %PATH;             #REQUIRED>

<!-- contents are meaningful only on create operations -->
<!ELEMENT docRequest  ANY> 
<!ATTLIST docRequest
          operation   (create|delete)    "create">

<!-- cf., XUpdate specification for the "xupdate:modifications" element

          Note that for simplicity, the xupdate:modifications element
          MUST have exactly one subordinate element -->
<!ELEMENT fragRequest (fetch|xupdate:modifications)>

<!ELEMENT fetch       EMPTY>
<!ATTLIST fetch
          xpath       %XPATH;            #REQUIRED>


<!--
  Results
  -->

<!-- contents are meaningful only if responding to a fetch request -->
<!ELEMENT result      ANY>
<!ATTLIST result
          count       CDATA              "0">


<!--
  email wrappers
  -->

<!ELEMENT reqbatch    (request)*>
<!ATTLIST reqbatch
          originator  %URI;               #REQUIRED>

<!ELEMENT rspbatch    (result|error)*>

5.2 The Registry DTD

<!--
  DTD data types:

        entity        syntax/reference        example
        ======        ================        =======

    uniform resource identifier
        URI           cf., RFC 2396           http://anana.org/

    URI or the empty string
        ACTOR         cf., RFC 2396           ''

    localization language
        LANG          cf., RFC 1766           en, en-US, etc.

    XPath expression
        XPATH         cf., W3C REC XPath      //key[@id='anana']
  -->

<!ENTITY % URI        "CDATA">
<!ENTITY % ACTOR      "CDATA">
<!ENTITY % LANG       "CDATA">
<!ENTITY % XPATH      "CDATA">


<!ENTITY % rfc2629.dtd PUBLIC '' 
           'http://xml.resource.org/public/rfc/xml/rfc2629.dtd'>
%rfc2629.dtd;


<!--
  The top-level
  -->

<!ELEMENT registry    (fore,namespace*,aft)>
<!ATTLIST registry
          name        %URI;              #REQUIRED
          title       CDATA              #REQUIRED>


<!--
  The front
  -->

<!ELEMENT fore        (registrar+,comment?,date)>

<!ELEMENT registrar   EMPTY> 
<!ATTLIST registrar
          uri         %URI;              #REQUIRED>

<!-- cf., RFC 2629 for the "date", "t", and "figure" elements -->
<!ELEMENT comment     (t|figure)+>


<!--
  The middle
  -->

<!ELEMENT namespace   (comment?,template,block*)>
<!ATTLIST namespace
          id          ID                 #IMPLIED
          title       CDATA              #REQUIRED>

<!ELEMENT template    EMPTY>
<!ATTLIST template    
          idPattern   CDATA              "%"
          type        (numeric|character|arbitrary)
                                         "character"
          xml:lang    %LANG;             #IMPLIED
          keyText     CDATA              #REQUIRED
          commentText CDATA              #IMPLIED>

<!ELEMENT block       (comment?,entry*)>

<!-- the first key element is considered the primary key for the entry -->
<!ELEMENT entry       (key+,citation*,comment?,date)>

<!ELEMENT key         (#PCDATA)>
<!ATTLIST key
          id          ID                 #REQUIRED>

<!ELEMENT citation    (#PCDATA)>
<!ATTLIST citation
          uri         %URI;              #REQUIRED
          contentType %URI;              #IMPLIED>


<!--
  The back
  -->

<!ELEMENT aft         (acl,conformance,reporting)>

<!ELEMENT acl         (ac*)> 

<!ELEMENT ac          EMPTY>
<!ATTLIST ac
          subject     %XPATH;            #REQUIRED 
          actor       %ACTOR;            ""
          permitted   NMTOKENS           "none">

<!ELEMENT conformance (conform*)>

<!ELEMENT conform     (trigger)>
<!ATTLIST conform
          subject     %XPATH;            #REQUIRED>

<!ELEMENT reporting   (report*)>

<!ELEMENT report      (trigger)>
<!ATTLIST report
          subject     %XPATH;            #REQUIRED 
          actor       %ACTOR;            "">

<!ELEMENT trigger     (param*)>
<!ATTLIST trigger
          resource    %URI;              #REQUIRED>
<!ELEMENT param       (#PCDATA)>
<!ATTLIST param
          name        CDATA              #REQUIRED>

5.3 The AuthInfo DTD

<!ELEMENT authInfo    (param*)>

<!ELEMENT param       (#PCDATA)>
<!ATTLIST param
          name        CDATA              #REQUIRED>


 TOC 

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:

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 = *<<any uric other than "(" and ")">>
    
    ;; authority, abs_path, uric are defined in RFC 2396

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 Registration: The System (Well-Known) TCP port number for the ANANA Datastore.

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 Registration: The System (Well-Known) TCP port number for the ANANA Datastore.

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].



 TOC 

7. IANA Considerations

The IANA registers anana as a URI scheme, as specified in Registration: The anana URI Scheme.

The IANA registers ANANA datastore as a TCP port number, as specified in Registration: The System (Well-Known) TCP port number for the ANANA Datastore.

The IANA registers application/anana+xml as a MIME media type, as specified in The application/anana+xml Media Type.

The IANA registers the BEEP profile specified in The ANANA Datastore Profile for BEEP, 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., The anana URI Scheme
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., Security Considerations
Relevant Publications:
cf., this memo
Contact Information:
Marshall Rose <mrose@dbc.mtview.ca.us>
Author/Change controller:
the IESG

7.2 Registration: The System (Well-Known) TCP port number for the ANANA Datastore

Protocol Number:
TCP
Message Formats, Types, Opcodes, and Sequences:
cf., The Operations DTD
Functions:
cf., Datastore Operations
Use of Broadcast/Multicast:
none
Proposed Name:
ANANA Datastore
Short name:
anana-store
Contact Information:
Marshall Rose <mrose@dbc.mtview.ca.us>

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 ("&amp;", "&lt;", "&gt;", "&apos;", and "&quot;") and numeric entity references may be present. Second, neither the "XML" declaration (e.g., <?xml ...>) nor the "DOCTYPE" declaration (e.g., <!DOCTYPE ...>) 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 The AuthInfo DTD.
Appliations which use this media type:
the ANANA datastore
Additional Information:
none
Intended usage:
cf., Access Protocols
Additional Information:
none
Intended usage:
limited use
Contact Information:
Marshall Rose <mrose@dbc.mtview.ca.us>
Author/Change controller:
the IESG

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., The Operations DTD
Message Semantics:
cf., Datastore Operations
Contact Information:
Marshall Rose <mrose@dbc.mtview.ca.us>



 TOC 

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:

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.



 TOC 

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.
[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.


 TOC 

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


 TOC 

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.



 TOC 

Full Copyright Statement

Acknowledgement