idnits 2.17.1
draft-anana-datastore-01.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
** Looks like you're using RFC 2026 boilerplate. This must be updated to
follow RFC 3978/3979, as updated by RFC 4748.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
== No 'Intended status' indicated for this document; assuming Proposed
Standard
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
** The document seems to lack separate sections for Informative/Normative
References. All references will be assumed normative when checking for
downward references.
** There are 7 instances of too long lines in the document, the longest one
being 5 characters in excess of 72.
** The document seems to lack a both a reference to RFC 2119 and the
recommended RFC 2119 boilerplate, even if it appears to use RFC 2119
keywords.
RFC 2119 keyword, line 1096: '... MUST have exactly one sub...'
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the RFC 3978 Section 5.4 Copyright Line does not
match the current year
== Line 959 has weird spacing: '...request res...'
-- The document seems to lack a disclaimer for pre-RFC5378 work, but may
have content which was first submitted before 10 November 2008. If you
have contacted all the original authors and they are all willing to grant
the BCP78 rights to the IETF Trust, then this is fine, and you can ignore
this comment. If not, you may need to add the pre-RFC5378 disclaimer.
(See the Legal Provisions document at
https://trustee.ietf.org/license-info for more information.)
-- The document date (June 25, 2002) is 7975 days in the past. Is this
intentional?
Checking references for intended status: Proposed Standard
----------------------------------------------------------------------------
(See RFCs 3967 and 4897 for information about using normative references
to lower-maturity documents in RFCs)
== Unused Reference: '13' is defined on line 1530, but no explicit
reference was found in the text
== Unused Reference: '22' is defined on line 1557, but no explicit
reference was found in the text
-- No information found for draft-anana-overview - is the name correct?
-- Possible downref: Normative reference to a draft: ref. '1'
-- No information found for draft-anana-implementation - is the name
correct?
-- Possible downref: Normative reference to a draft: ref. '2'
** Downref: Normative reference to an Informational RFC: RFC 2832 (ref. '3')
-- Possible downref: Non-RFC (?) normative reference: ref. '4'
** Obsolete normative reference: RFC 2396 (ref. '5') (Obsoleted by RFC 3986)
-- Possible downref: Non-RFC (?) normative reference: ref. '6'
-- Possible downref: Non-RFC (?) normative reference: ref. '7'
** Obsolete normative reference: RFC 2234 (ref. '8') (Obsoleted by RFC 4234)
== Outdated reference: A later version (-09) exists of
draft-eastlake-cturi-03
** Obsolete normative reference: RFC 2616 (ref. '11') (Obsoleted by RFC
7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235)
** Obsolete normative reference: RFC 2821 (ref. '12') (Obsoleted by RFC
5321)
** Obsolete normative reference: RFC 3023 (ref. '13') (Obsoleted by RFC
7303)
** Obsolete normative reference: RFC 2831 (ref. '14') (Obsoleted by RFC
6331)
** Obsolete normative reference: RFC 2472 (ref. '18') (Obsoleted by RFC
5072, RFC 5172)
** Obsolete normative reference: RFC 2279 (ref. '19') (Obsoleted by RFC
3629)
** Obsolete normative reference: RFC 2633 (ref. '21') (Obsoleted by RFC
3851)
** Obsolete normative reference: RFC 1766 (ref. '22') (Obsoleted by RFC
3066, RFC 3282)
Summary: 15 errors (**), 0 flaws (~~), 6 warnings (==), 9 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Network Working Group M. Rose
3 Internet-Draft Dover Beach Consulting, Inc.
4 Expires: December 24, 2002 June 25, 2002
6 The ANANA Datastore
7 draft-anana-datastore-01
9 Status of this Memo
11 This document is an Internet-Draft and is in full conformance with
12 all provisions of Section 10 of RFC2026.
14 Internet-Drafts are working documents of the Internet Engineering
15 Task Force (IETF), its areas, and its working groups. Note that
16 other groups may also distribute working documents as Internet-
17 Drafts.
19 Internet-Drafts are draft documents valid for a maximum of six months
20 and may be updated, replaced, or obsoleted by other documents at any
21 time. It is inappropriate to use Internet-Drafts as reference
22 material or to cite them other than as "work in progress."
24 The list of current Internet-Drafts can be accessed at http://
25 www.ietf.org/ietf/1id-abstracts.txt.
27 The list of Internet-Draft Shadow Directories can be accessed at
28 http://www.ietf.org/shadow.html.
30 This Internet-Draft will expire on December 24, 2002.
32 Copyright Notice
34 Copyright (C) The Internet Society (2002). All Rights Reserved.
36 Abstract
38 This memo defines the ANANA datastore, a policy-neutral service for
39 managing registries, namespaces, and entries.
41 Table of Contents
43 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
44 2. Datastore Model . . . . . . . . . . . . . . . . . . . . . . . 5
45 2.1 XML Database Layer . . . . . . . . . . . . . . . . . . . . . . 5
46 2.2 Policy Neutral Layer . . . . . . . . . . . . . . . . . . . . . 7
47 2.3 Policy-Defined Layer . . . . . . . . . . . . . . . . . . . . . 12
48 3. Datastore Operations . . . . . . . . . . . . . . . . . . . . . 15
49 3.1 Processing a Request . . . . . . . . . . . . . . . . . . . . . 16
50 3.2 Processing an Operation . . . . . . . . . . . . . . . . . . . 18
51 3.3 Trigger Evaluation . . . . . . . . . . . . . . . . . . . . . . 19
52 3.4 Access Control Evaluation . . . . . . . . . . . . . . . . . . 20
53 4. Datastore Access . . . . . . . . . . . . . . . . . . . . . . . 23
54 4.1 Access Protocols . . . . . . . . . . . . . . . . . . . . . . . 23
55 4.2 Managing Authentication Information . . . . . . . . . . . . . 25
56 5. DTDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
57 5.1 The Operations DTD . . . . . . . . . . . . . . . . . . . . . . 27
58 5.2 The Registry DTD . . . . . . . . . . . . . . . . . . . . . . . 28
59 5.3 The AuthInfo DTD . . . . . . . . . . . . . . . . . . . . . . . 31
60 6. URI Schemes . . . . . . . . . . . . . . . . . . . . . . . . . 32
61 6.1 The anana URI Scheme . . . . . . . . . . . . . . . . . . . . . 32
62 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34
63 7.1 Registration: The anana URI Scheme . . . . . . . . . . . . . . 34
64 7.2 Registration: The System (Well-Known) TCP port number for
65 the ANANA Datastore . . . . . . . . . . . . . . . . . . . . . 35
66 7.3 The application/anana+xml Media Type . . . . . . . . . . . . . 36
67 7.4 The ANANA Datastore Profile for BEEP . . . . . . . . . . . . . 37
68 8. Security Considerations . . . . . . . . . . . . . . . . . . . 38
69 References . . . . . . . . . . . . . . . . . . . . . . . . . . 39
70 Author's Address . . . . . . . . . . . . . . . . . . . . . . . 40
71 A. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 41
72 Full Copyright Statement . . . . . . . . . . . . . . . . . . . 42
74 1. Introduction
76 [1] introduces the concept of a policy-free registrar. To
77 paraphrase:
79 o a 'registrar' is a person, organization, or group that maintains a
80 registry of names and numbers;
82 o a 'registry' is a collection of one or more namespaces;
84 o a 'namespace' is a collection of one or more blocks;
86 o a 'block' is a collection of related entries; and,
88 o an 'entry' is a binding between one or more 'keys' (each being
89 unique within the namespace), a textual commentary, and zero or
90 more 'citations' that further describe the entry.
92 Consult [2] for an example of the provisioning strategy for a policy-
93 free registrar.
95 Typically, a registry contains a single namespace, which in turn
96 contains a single block having many entries (with each entry having
97 exactly one key). However, it may be desirable to have both multiple
98 namespaces within a registry, and multiple blocks within a namespace.
99 For example, if a registry corresponded to the parameters for a
100 particular protocol, then:
102 o that protocol might have different classes of parameters, so each
103 parameter class would have its own namespace in the registry;
104 similarly,
106 o within a particular parameter class, it may be natural to divide
107 the range of possible values into related blocks, e.g., "user-
108 defined", "system-reserved", and so on.
110 (Readers familiar with XML terminology should note that the term
111 'namespace', as used in this document, has no relationship to the
112 'XML namespace' concept.)
113 This memo describes a datastore that may be used to realize a policy-
114 free registry service. As a reminder to the reader, the problem
115 domain for the service has several notable requirements. In
116 particular, the service:
118 o supports registries that contain no more than a few million
119 records;
121 o supports registries that perform no more than a few updates each
122 minute;
124 o facilitates the separation of processes responsible for policy,
125 allocation, and distribution;
127 o facilitates automated (and mostly-automated) submissions; and,
129 o facilitates transformation of registries from highly-structured to
130 human-readable content.
132 In particular, the reader should appreciate that the problem domain
133 for this service is manifestly different than the one solved by
134 traditional registry-registrar protocols, such as RRP[3].
136 2. Datastore Model
138 ANANA registries are modeled as XML[4] documents, and logically
139 reside in a datastore with three conceptual layers:
141 layer services approach
142 ----- -------- --------
144 +-------------+
145 | | externally-defined services
146 | reporting | are accessed via URI in
147 policy-defined | | response to certain
148 layer | conformance | datastore events
149 | |
150 +-------------+
151 | |
152 | access | intra-document access
153 policy neutral | control | control and structural
154 layer | | (DTD) conformance
155 | validity |
156 +-------------+
157 | |
158 | operations | a "generic" XML document
159 XML database | | database (perhaps emulated
160 layer | well- | by an RDBMS)
161 | formedness |
162 +-------------+
164 2.1 XML Database Layer
166 This layer is responsible for:
168 o structuring information as a collection of well-formed XML
169 documents; and,
171 o providing operations to manage XML documents in the datastore.
173 2.1.1 Well-Formed XML
175 The datastore contains XML documents, each of which correspond to a
176 registry.
178 Documents are uniquely identified using the ANANA URI (Section 6.1)
179 scheme. Within a datastore, documents are named using the 'abs_path'
180 syntax defined in RFC 2396[5] (e.g., "/anana/identities"). Within a
181 document, fragments are named using an XML Path Language[6] (XPath)
182 expression (e.g., "//key[@id='anana']"). Note that since an XPath
183 expression (typically) evaluates to a 'node-set' containing zero or
184 more XML fragments, the number of fragments identified by this
185 expression depends on the contents of the corresponding document.
187 Any document residing in the datastore meets two requirements:
189 o the document is well-formed (as described in Section 2.1 of [4]);
190 and,
192 o the only entities found in the document are XML's predefined
193 entities (as defined in Section 4.6 of [4]) and numeric character
194 references (as defined in Section 4.1 of [4]).
196 The first requirement is essentially the "entry cost for doing XML".
197 The second requirement limits the implementation complexity of the
198 datastore and removes a large class of potential ambiguities when
199 searching.
201 Finally, the document named "/root", and any document whose name
202 starts with "/root/", is reserved for use by the datastore.
204 2.1.2 Datastore Operations
206 The datastore supports two sets of operations:
208 o operations on documents; and,
210 o operations on fragments within a document.
212 Two document-wide operations are defined:
214 o 'create', which creates a new document in the datastore; and,
216 o 'delete', which removes an existing document from the datastore.
218 Operations on the fragments within a document are specified using
219 either:
221 o an XPath expression, to retrieve XML fragments; or,
223 o an XML Update Language[7] (XUpdate) expression, to modify an XML
224 fragment.
226 Note that in the interests of simplicity, the XUpdate expression is
227 limited to a single modification per operation.
229 2.2 Policy Neutral Layer
231 This layer is responsible for:
233 o ensuring data consistency on XML documents that model ANANA
234 registries; and,
236 o enforcing access control policies.
238 2.2.1 Valid XML
240 The ANANA Registry DTD (Section 5.2) defines the validity constraints
241 for an XML document that models an ANANA registry. Each document has
242 the '' element at its root. Each '' element
243 contains:
245 o a 'name' attribute uniquely identifying the registry, using a URI
246 that conforms to the ANANA URI (Section 6.1) scheme;
248 o a 'title' attribute containing a descriptive name for the
249 registry;
251 o a '' element containing:
253 * one or more '' elements, each containing a pointer
254 to registrar information;
256 * optionally, a '' element containing textual
257 information about the registry; and,
259 * a '' element.
261 o zero or more '' elements, each containing information
262 about a namespace within the registry; and,
264 o an '' element containing administrative information relating
265 the XML document to the datastore, specifically:
267 * an '' element containing zero or more '' elements,
268 which defines the access control policy for the document;
270 * a '' element containing zero or more ''
271 elements, which defines the conformance policy for the
272 document; and,
274 * a '' element containing zero or more ''
275 elements, which defines the reporting policy for the document.
277 The first fundamental concept about ANANA registries is that they are
278 largely pointers to other resources, and often the resource is an XML
279 fragment within the datastore.
281 For example, here is the top-level and front part of an ANANA
282 registry:
284
287
288
291 This is the registry used by the ANANA to identify
292 itself and other registrars.
294
295
297 ...
299 In this example, note that the value of the '' element's
300 'uri' attribute points to another portion of the document in which it
301 resides.
303 Each '' element contains:
305 o an 'id' attribute that is unique within the document;
307 o a 'title' attribute containing a descriptive name for the
308 namespace;
310 o optionally, a '' element containing textual information
311 about the namespace;
313 o a '' element for the entries contained in the
314 namespace; and,
316 o zero or more '' elements.
318 Each '' element contains:
320 o an 'idPattern' attribute that indicates how the 'id' attributes of
321 the '' elements are generated;
323 o a 'type' attribute indicating whether the contents of the ''
324 elements is numeric or character-oriented;
326 o optionally, an 'xml:lang' attribute, meaningful only if the '' elements are character-oriented, indicating the localization
328 language used for the contents;
330 o a 'keyText' attribute containing a brief textual description of
331 the '' values; and,
333 o optionally, a 'commentText' attribute containing an additional
334 textual description of the '' values;
336 The value of 'type' attribute is one of:
338 o "numeric";
340 o "character"; or,
342 o "arbitrary";
344 If the 'type' attribute has the value "numeric", then the ABNF[8] of
345 the character data of each corresponding '' element is:
347 numeric = range *(" " range)
349 range = number ".." number
351 number = [prefix] 1*("0" / "1" / "2" / "3" / "4" /
352 "5" / "6" / "7" / "8" / "9")
354 prefix = "0x" | "0"
355 ;; "0x" indicates hexadecimal
356 ;; "0" indicates octal
358 If the 'type' attribute has the value "character", then the character
359 data of each corresponding each corresponding '' element
360 matches the 'Name' syntax defined in XML[4] documents.
362 If the 'type' attribute has the value "arbitrary", then no
363 restrictions are placed on the character data of each corresponding
364 '' element.
366 The second fundamental concept about ANANA registries is that 'id'
367 attributes for each entry's keys are algorithmically-generated within
368 each registry. Because the uniqueness of 'id' attributes is a
369 requirement of well-formedness, the uniqueness of registered values
370 within a registry is also datastore requirement.
372 The 'idPattern' attribute corresponds to the 'Name' syntax defined in
373 XML[4] documents, with one addition: the "%" character. When the
374 'id' attribute for a '' element is generated, the normalized
375 value corresponding to the registered value (character data) of that
376 element replaces the "%" character, where
378 o for 'numeric' values, the normalized value is the decimal
379 representation of the registered value for this key, where the
380 space character (" ") is replaced with an underscore character
381 ("_");
383 o for 'character' values, the normalized value is the lowercase
384 string corresponding to the registered value for this key --
385 otherwise,
387 o for 'arbitrary' values, the normalized value is the base64
388 encoding of the lowercase string corresponding to the registered
389 value for this key -- normalization is performed according to the
390 value of the 'xml:lang' attribute of the '' element.
392 For example, here is the middle part of an ANANA registry:
394
395 This is ANANA's registry of identities. Typically,
396 registrars are listed here. Other folks (e.g., registrants)
397 may also be listed here, or in other registries.
399
401
402
403 ANANA
404
405
407
408 IANA
409
410
412 ...
413
414
416 Each '' element contains:
418 o optionally, a '' element containing textual information
419 about the block; and,
421 o zero or more '' elements.
423 Each '' element contains:
425 o one or more '' elements, the first of which is the "primary
426 key" for the entry (any others are termed "aliases");
428 o zero or more '' elements;
430 o optionally, a '' element containing textual information
431 about the entry; and,
433 o a '' element.
435 Each '' element contains:
437 o an 'id' attribute that is unique within the document; and,
439 o the character-data corresponding to the registered value for this
440 key.
442 Each '' element contains:
444 o a 'uri' attribute providing additional information about the
445 entry;
447 o optionally, a 'contentType' attribute providing typing information
448 for the remote resource (using the convention in [9]); and,
450 o a brief textual description of the citation.
452 2.2.2 Access Control
454 There are two kinds of access control policies enforced by the
455 datastore:
457 o fragment-specific policies, which are contained within each XML
458 document; and,
460 o document-specific policies, which are contained within a special
461 XML document in the datastore.
463 In each case, the datastore consults the appropriate document's
464 '' element to determine the policy in effect.
466 The '' element contains zero or more '' elements. Each
467 '' element contains:
469 o a 'subject' attribute identifying the XML fragments to which this
470 access control entry applies;
472 o optionally, an 'actor' attribute identifying the client identities
473 to which this access control entry applies (if not present, then
474 the element refers to any client, possibly unauthenticated); and,
476 o a 'permitted' attribute identifying the operations that are
477 allowed for this particular subject/actor pairing.
479 The 'subject' attribute is specified as an XPath expression;
480 similarly, the 'actor' attribute is often given as an ANANA URI.
481 Accordingly, a single access control entry may refer to multiple
482 fragments within an XML document and/or multiple client identities.
484 For example, here is an '' element for a particular ANANA
485 registry:
487
488
490
491
493 In this example, note that while both access control entries refer to
494 the entire document, different access is granted based on the client
495 identity.
497 Ordering of access control entries is important: the first access
498 control entry with a matching subject/actor pair is used. Of course,
499 if none of the access control entries apply, then no access is
500 allowed.
502 2.3 Policy-Defined Layer
504 This layer is responsible for:
506 o ensuring registrar-specific conformance policies; and,
508 o reporting registry modifications.
510 2.3.1 Conformance
512 A registrar may place additional conformance requirements on the
513 entries in a registry. Before performing any modifications, the
514 datastore consults the document's '' element to
515 determine the policy in effect. Conformance policies are implemented
516 remotely from the datastore, and are accessed via a remote resource.
518 The '' element contains zero or more ''
519 elements. Each '' element contains:
521 o a 'subject' attribute identifying the XML fragments to which this
522 conformance entry applies; and,
524 o a '' element.
526 The 'subject' attribute is specified as an XPath expression;
527 accordingly, a single conformance entry may refer to multiple
528 fragments within an XML document.
530 For example, here is a '' element for a particular
531 ANANA registry:
533
534
535
536 validate-citations
537
538
539
541 which says that whenever an entry is modified, then an HTTP-based
542 resource is asked to examine the citations in the entry.
544 A conformance trigger reports three possible outcomes:
546 o success;
548 o deferral; or,
550 o failure.
552 On deferral or failure, any response data from the trigger is
553 returned to the client and no further action is taken by the
554 datastore. Typically, a deferral indicates that a registrar will
555 examine the entry later on (typically out-of-band), and that no other
556 action is required by the client.
558 Ordering of conformance entries is important: the first conformance
559 entry with a matching subject is used.
561 2.3.2 Reporting
563 A registrar may place additional reporting requirements on the
564 entries in a registry. After performing any modifications, the
565 datastore consults the document's '' element to determine
566 the policy in effect. Reporting policies are implemented remotely
567 from the datastore, and are accessed via a remote resource.
569 The '' element contains zero or more ''
570 elements. Each '' element contains:
572 o a 'subject' attribute identifying the XML fragments to which this
573 reporting entry applies;
575 o optionally, an 'actor' attribute identifying the client identities
576 to which this reporting entry applies (if not present, then the
577 element refers to any client, possibly unauthenticated); and,
579 o a '' element.
581 The 'subject' attribute is specified as an XPath expression;
582 similarly, the 'actor' attribute is often given as an ANANA URI.
583 Accordingly, a single reporting entry may refer to multiple fragments
584 within an XML document and/or multiple client identities.
586 The outcome of a reporting trigger may be logged, but is otherwise
587 ignored by the datastore. Ordering of reporting entries is
588 important, the first reporting entry with a matching subject/actor
589 pair is used.
591 3. Datastore Operations
593 When a client wishes to interact with the datastore, it selects an
594 access protocol (Section 4.1), optionally authenticates itself, and
595 then submits one or more requests to the datastore, which returns a
596 result or an error for each request.
598 The ANANA Operations DTD (Section 5.1) defines the format of requests
599 and results, using the '' and '' elements,
600 respectively. The '' element, defined in Section 7.1 of
601 [10], is used to convey error information.
603 The '' element contains:
605 o a 'docName' attribute identifying a document in the datastore;
606 and,
608 o either:
610 * a '', to operate on an entire document; or,
612 * a '' element, to operate on the fragments within
613 a document.
615 The '' element contains:
617 o an 'operation' attribute indicating whether the document should be
618 created or deleted; and,
620 o arbitrary XML content, which is meaningful only if the create
621 operation is requested, and is ignored otherwise.
623 The '' element contains either:
625 o a '' element, which contains an 'xpath' attribute
626 identifying the XML fragments to which this operation applies; or,
628 o a '' element, (defined in Section 2.11 of
629 [7] and having exactly one subordinate element).
631 3.1 Processing a Request
633 When the datastore receives a '' element, it performs these
634 steps:
636 1. If the 'docName' attribute of the '' element does not
637 identify an existing document in the datastore, and if the
638 '' element does not contain a '' element
639 whose 'operation' attribute has a value of "create", then an
640 '' element having code 550 is returned to the client, and
641 no further processing occurs.
643 2. If the '' element contains a '' element
644 whose 'operation' attribute has a value of "create" then:
646 1. If the 'docName' attribute of the '' element
647 identifies an existing document in the datastore, then an
648 '' element having code 555 is returned to the client,
649 and no further processing occurs.
651 2. The datastore verifies that the content of the '' element is a valid '' element (cf., Section
653 2.2.1). If not, an '' element having code 505 is
654 returned to the client, and no further processing occurs.
656 3. If the '' element contains a ''
657 element, then:
659 1. The datastore computes the "snapshot" -- the document that
660 results if the operation were to be applied.
662 2. The datastore verifies that the snapshot is valid (cf.,
663 Section 2.2.1). If not, an '' element having code
664 505 is returned to the client, and no further processing
665 occurs.
667 3. The datastore extracts the "target" -- the 'select' attribute
668 of the subordinate element of the ''
669 element.
671 4. The datastore retrieves the '' element
672 contained in the original document, and examines each
673 '' element in the order they appear looking for the
674 first conformance entry having a 'subject' attribute that,
675 when applied to the snapshot, includes the target path.
677 5. If such an entry exists, then the datastore evaluates the
678 trigger associated with the conformance entry (cf., Section
679 3.3):
681 + If the trigger reports a failure outcome, this is returned
682 to the client in an '' element, and no further
683 processing occurs.
685 + If the trigger reports a deferral outcome, an ''
686 element having code 300 is returned to the client, and no
687 further processing occurs.
689 4. The datastore retrieves the appropriate access entry for the
690 client identity and determines the required access token for the
691 operation, according to the rules given in Section 3.4. The
692 datastore examines the 'permitted' attribute of the access entry
693 and sees if it contains either the required access token or the
694 value "all". If not, an '' element having code 537 is
695 returned to the client, and no further processing occurs.
697 5. The datastore performs the operation according to the rules given
698 in Section 3.2.
700 6. If the '' element contains a ''
701 element, then:
703 1. The datastore retrieves the '' element contained
704 in the snapshot, and examines each '' element in the
705 order they appear looking for the first reporting entry
706 having a 'subject' attribute that, when applied to the
707 snapshot, includes the target path, and having an 'actor'
708 attribute that matches the client identity.
710 2. If such an entry exists, then the datastore evaluates the
711 trigger associated with the reporting entry (cf., Section
712 3.3).
714 7. A '' element is returned to the client:
716 * if the '' element contains a '' element,
717 then the ''element contains the XML fragments
718 corresponding to the XPath expression in the ''
719 element; otherwise,
721 * the contents of the '' element is empty.
723 3.2 Processing an Operation
725 3.2.1 Create a Document
727 If the '' element contains a '' element whose
728 'operation' attribute has the value "create" then:
730 1. A document is created in the datastore having a name identical to
731 the '' element's 'docName' attribute, and whose
732 contents is identical to the contents of the ''
733 element.
735 3.2.2 Delete a Document
737 If the '' element contains a '' element whose
738 'operation' attribute has the value "delete" then:
740 1. The document in the datastore identified by the value of the
741 '' element's 'docName' attribute is removed from the
742 datastore.
744 3.2.3 Fetch Document Fragments
746 If the '' element contains a '' element that
747 contains a '' element, then:
749 1. The value of the '' element's 'xpath' attribute is
750 evaluated as an XPath expression, and the resulting value is
751 returned as the contents of a '' element.
753 3.2.4 Modify a Document Fragment
755 If the '' element contains a '' element that
756 contains a '' element, then:
758 1. The contents of the '' element is evaluated as an
759 XUpdate expression.
761 3.3 Trigger Evaluation
763 Triggers implement registrar-specific policies by accessing a remote
764 resource.
766 The '' element contains:
768 o a 'uri' attribute, identifying a resource to examine; and,
770 o zero or more '' elements, each containing a name/value
771 pair presented as a parameter to the resource.
773 In addition to whatever parameters are specified in the trigger
774 element, the datastore also includes these two parameters when a
775 trigger is evaluated:
777 o a parameter called "clientIdentity" having as its value the client
778 identity associated with the client (if the client is
779 unauthenticated, then an empty string is supplied); and,
781 o a parameter called "request" containing the corresponding
782 '' element.
784 The datastore evaluates the trigger using an algorithm specific to
785 the scheme used in the trigger's URI. The algorithm must define:
787 o how parameters are passed to the resource; and,
789 o how the resource is retrieved.
791 At present, the algorithm for two schemes, 'http' and 'https', are
792 specified.
794 3.3.1 HTTP/HTTPS-based Triggers
796 A trigger specified via 'http' or 'https' is evaluated using the
797 HTTP[11] 'POST' operation containing the parameters to the trigger.
799 The datastore examines the HTTP response code when a reply is
800 returned, to determine the trigger's outcome, either:
802 o success, if the HTTP response has code 2xx;
804 o a deferral, if the HTTP response has code 300; or,
806 o failure, for any other response
808 3.4 Access Control Evaluation
810 When the datastore is asked to performed an operation, it must make
811 two determinations:
813 o the required access token for the operation; and,
815 o the appropriate access entry for the client identity.
817 The datastore determines the required access token by consulting this
818 table:
820 request pattern access token
821 ------------------------------------------- ------------
822 /request/docRequest[@operation='create'] create
824 /request/docRequest[@operation='delete'] delete
826 /request/fragRequest/fetch read
828 /request/fragRequest/xupdate:modifications
829 /xupdate:insert-before insert
831 /request/fragRequest/xupdate:modifications
832 /xupdate:insert-after insert
834 /request/fragRequest/xupdate:modifications
835 /xupdate:append write
837 /request/fragRequest/xupdate:modifications
838 /xupdate:update write
840 /request/fragRequest/xupdate:modifications
841 /xupdate:remove write
843 /request/fragRequest/xupdate:modifications
844 /xupdate:rename write
846 Determining the appropriate access control entry depends on whether
847 the operation pertains to an entire document (the ''
848 element contains a '') or the fragments within a
849 document (the '' element contains a '').
851 3.4.1 Document-specific Policies
853 If the operation pertains to an entire document, a document-specific
854 policy is consulted.
856 The datastore retrieves the '' element contained in a document
857 named "/root/access", and examines each '' element in the order
858 they appear. For each access entry:
860 o if the 'subject' attribute is identical to the 'docName' attribute
861 of the '' element; and,
863 o if the 'actor' attribute matches the client identity
865 then this '' element is the appropriate access control entry.
867 If no access control entry is appropriate, then a transient access
868 entry is returned having:
870 o the 'subject' attribute set to the value of the 'docName'
871 attribute of the '' element;
873 o the 'actor' attribute set to the client identity of the client;
874 and,
876 o the 'permitted' attribute set to "none".
878 3.4.2 Fragment-specific Policies
880 If the operation pertains to the fragments within a document, a
881 fragment-specific policy is consulted.
883 The datastore retrieves the '' element contained in the
884 document containing the fragments, and examines each '' element
885 in the order they appear. For each access entry:
887 o if the 'subject' attribute when applied to the snapshot document
888 includes:
890 * any XML fragment identified by the '' element; or,
892 * the XML fragment modified by the ''
893 element
895 o and if the 'actor' attribute matches the client identity
897 then this '' element is the appropriate access control entry.
899 If no access control entry is appropriate, then a transient access
900 entry is returned having:
902 o the 'subject' attribute set to "/";
904 o the 'actor' attribute set to the client identity of the client;
905 and,
907 o the 'permitted' attribute set to "none".
909 4. Datastore Access
911 To access the datastore, a client requires:
913 o an access protocol; and,
915 o a mechanism for managing authentication information.
917 4.1 Access Protocols
919 This memo defines two ways to access the ANANA Datastore:
921 o using BEEP[10]; and,
923 o using SMTP[12].
925 4.1.1 via BEEP
927 For interactive access to the datastore, BEEP is used.
929 The BEEP profile for the ANANA Datastore is identified as:
931 http://anana.org/beep/anana-datastore
933 in the BEEP '' element during channel creation.
935 In BEEP, when the first channel is successfully created, the
936 'serverName' attribute in the '' element identifies the
937 "virtual host" associated with the peer acting in the server role,
938 e.g.,
940
941
942
944 The 'serverName' attribute is analagous to HTTP's 'Host' request-
945 header field (cf., Section 14.23 of [11]).
947 No elements are required to be exchanged during channel creation;
948 however, the BEEP initiator may choose to piggyback a ''
949 element during channel creation. If the channel is successfully
950 created, then the BEEP listener performs the piggyback'd operation
951 and returns either a '' element or an '' element as
952 piggyback'd data. (Note well that Section 2.3.1.2 of [10] limits the
953 amount of piggyback'd data to 4K octets.)
954 All messages are exchanged as 'application/beep+xml', and only one-
955 to-one exchanges are permitted, i.e.,
957 role MSG RPY ERR
958 ==== === === ===
959 I request result error
961 where the '' and '' elements are defined in
962 Section 5.1, and the '' element is defined in Section 7.1 of
963 [10].
965 4.1.2 via SMTP
967 For batch access to the datastore, email is used.
969 The '' and '' elements (defined in Section 5.1)
970 are used to batch multiple requests and results into a single
971 message, tagged as |"application/xml|[13].
973 The '' element contains:
975 o an 'originator' attribute identifying the client making the
976 requests using an URI that conforms to the ANANA URI scheme; and,
978 o zero or more '' elements.
980 The '' element contains zero or more '' and
981 '' elements.
983 The client may choose to to use MIME-based security (cf., Section 8)
984 for the message. If so, the datastore must be pre-configured to
985 understand the mapping between the cryptographic information used by
986 the client and the corresponding client identity. If there is an
987 error in processing the MIME-based security wrappers, then a message
988 containing a '' element that contains a single ''
989 element is sent to the client, and no further processing occurs.
991 If the client does not use MIME-based security, then the datastore
992 retrieves the '' element associated with the 'originator'
993 attribute of the '' element, and looks for a ''
994 element with:
996 o a 'uri' attribute containing a "mailto:" URI; and,
998 o a 'contentType' attribute having the value
999 "ContentType:application/anana+xml?type="authInfo".
1001 If no such element exists, then a message containing a ''
1002 element that contains a single '' element having code 530 is
1003 sent to the client, and no further processing occurs. Otherwise:
1005 1. The datastore sends a message to the mailbox identified by the
1006 'uri' attribute, which contains an unpredictable token and
1007 instructions for replying.
1009 2. If a reply is received sometime later, then the original message
1010 is considered authentic and processing continues.
1012 3. Otherwise, a message containing a '' element that
1013 contains a single '' element having code 531 is sent to
1014 the client, and no further processing occurs.
1016 The duration to wait for an acceptable response is a local policy
1017 matter.
1019 Regardless of the mechanism, if the message is deemed authentic, then
1020 the datastore processes each '' element in the order in
1021 which it appears in the '' element. Upon completion, a
1022 message containing a '' element (having the same number of
1023 subordinate elements as the '' element) is sent to the
1024 client.
1026 4.2 Managing Authentication Information
1028 In order to facilitate the management of authentication information,
1029 whenever an '' element is successfully added or modified, the
1030 datastore examines each '' element in the order they
1031 appear. If the value of the element's 'contentType' attribute is
1032 "ContentType:application/anana+xml?type="authInfo", and if the
1033 element's 'uri' attribute contains an 'https' URI, then:
1035 1. The datastore accesses the URI using the 'GET' operation and a
1036 client-side certificate.
1038 2. If the request is successful and returns an XML document
1039 containing an '' element, then the contents of that
1040 element are used by the datastore for future SASL-based
1041 authentication.
1043 The '' element contains zero or more '' elements,
1044 each containing a name/value pair.
1046 This memo defines two parameter names:
1048 sharedSecret: The value of this parameter is a shared secret that may
1049 be used with SASL mechanisms such as DIGEST-MD5[14].
1051 otpInfo: The value of this parameter is an 'init-hex' response
1052 defined in [15] (where the 'current-OTP' field is ignored) that
1053 may be used with the SASL OTP mechanism[16].
1055 5. DTDs
1057 5.1 The Operations DTD
1059
1076
1077
1078
1080
1084
1085
1088
1089
1090
1093
1097
1099
1100
1103
1107
1108
1109
1112
1116
1117
1120
1122 5.2 The Registry DTD
1124
1143
1144
1145
1146
1147
1149 %rfc2629.dtd;
1151
1155
1156
1160
1164
1166
1167
1170
1171
1173
1177
1178
1182
1183
1191
1192
1193
1195
1196
1199
1200
1204
1208
1210
1212
1213
1218
1220
1221
1224
1226
1227
1231
1232
1234
1235
1238 5.3 The AuthInfo DTD
1240
1242
1243
1246 6. URI Schemes
1248 6.1 The anana URI Scheme
1250 The "anana" URI scheme uses the "generic URI" syntax defined in
1251 Section 3 of [5], specifically:
1253 o the value "anana" is used for the scheme component;
1255 o the server-based naming authority defined in Section 3.2.2 of [5]
1256 is used for the authority component; and,
1258 o the path component corresponds to an 'abs_path', as defined in RFC
1259 2396[5], followed by an optional 'fragment' suffix.
1261 The values of both the scheme and authority components are case-
1262 insensitive. If the path component is absent, then it defaults to
1263 the root document, "/".
1265 The ABNF of the "anana" URI scheme is:
1267 anana_uri = "anana" ":" "//" authority [ abs_path [ frag_id ] ]
1269 frag_id = "#" "xpath" "(" balanced_parens ")"
1271 balanced_parens = *( escaped_parens | balanced_text )
1273 escaped_parens = "^()^^" | "^^^^" | "^^(" | "^^)"
1274 ;; "^(" escapes "("
1275 ;; "^)" escapes ")"
1276 ;; "^^" escapes "^"
1278 balanced_text = ( "(" balanced_parens ")" ) | noparens_text
1280 noparens_text = *<>
1282 ;; authority, abs_path, uric are defined in RFC 2396
1284 For example,
1286 anana://anana.org/anana/identities#xpath(//key[text()="ANANA"])
1287 anana://anana.org/anana/identities
1288 anana://anana.org:1026
1289 anana://10.0.0.2/
1291 are all valid ANANA URIs.
1293 6.1.1 Resolving IP/TCP Address Information
1295 The "anana" URI scheme indicates the use of the BEEP profile for the
1296 ANANA datastore service running over TCP/IP.
1298 If the authority component contains a domain name and a port number,
1299 e.g.,
1301 anana://anana.org:1026
1303 then the DNS is queried for the A RRs corresponding to the domain
1304 name, and the port number is used directly.
1306 If the authority component contains a domain name and no port number,
1307 e.g.,
1309 anana://anana.org
1311 the SRV algorithm[17] is used with a service parameter of "anana-
1312 store" and a protocol parameter of "tcp" to determine the IP/TCP
1313 addressing information. If no appropriate SRV RRs are found (e.g.,
1314 for "_anana-store._tcp.anana.org"), then the DNS is queried for the A
1315 RRs corresponding to the domain name and the port number used is
1316 assigned by the IANA for the registration in Section 7.2.
1318 If the authority component contains an IP address, e.g.,
1320 anana://10.0.0.2:1026
1322 then the DNS is not queried, and the IP address is used directly. If
1323 a port number is present, it is used directly; otherwise, the port
1324 number used is assigned by the IANA for the registration in Section
1325 7.2.
1327 While the use of literal IPv6 addresses in URIs is discouraged, if a
1328 literal IPv6 address is used in an "anana" URI, it must conform to
1329 the syntax specified in [18].
1331 7. IANA Considerations
1333 The IANA registers "anana" as a URI scheme, as specified in Section
1334 7.1.
1336 The IANA registers "ANANA datastore" as a TCP port number, as
1337 specified in Section 7.2.
1339 The IANA registers "application/anana+xml" as a MIME media type, as
1340 specified in Section 7.3.
1342 The IANA registers the BEEP profile specified in Section 7.4, and
1343 selects an IANA-specific URI, e.g.,
1345 http://iana.org/beep/anana-datastore
1347 7.1 Registration: The anana URI Scheme
1349 URI scheme name: anana
1351 URI scheme syntax: cf., Section 6.1
1353 Character encoding considerations: cf., the "generic URI" syntax
1354 defined in Section 3 of [5]
1356 Intended usage: identifies an XML document or fragment in an ANANA
1357 datastore
1359 Applications using this scheme: cf., "Intended usage", above
1361 Interoperability considerations: n/a
1363 Security Considerations: cf., Section 8
1365 Relevant Publications: cf., this memo
1367 Contact Information: Marshall Rose
1369 Author/Change controller: the IESG
1371 7.2 Registration: The System (Well-Known) TCP port number for the ANANA
1372 Datastore
1374 Protocol Number: TCP
1376 Message Formats, Types, Opcodes, and Sequences: cf., Section 5.1
1378 Functions: cf., Section 3
1380 Use of Broadcast/Multicast: none
1382 Proposed Name: ANANA Datastore
1384 Short name: anana-store
1386 Contact Information: Marshall Rose
1388 7.3 The application/anana+xml Media Type
1390 MIME Media Type Name: Application
1392 MIME subtype name: anana+xml
1394 Required Parameters: type
1396 Optional Parameters: charset (defaults to UTF-8[19])
1398 Encoding Considerations: 8-bit
1400 Security Considerations: avoid third-party disclosure as this media
1401 type may contain authentication information
1403 Interoperability Considerations: n/a
1405 Published Specification: This media type contains an XML XML[4]
1406 document, as indicated by the 'type' parameter.
1408 Two restrictions are made. First, no entity references other than
1409 the five predefined general entities references ("&", "<",
1410 ">", "'", and """) and numeric entity references may
1411 be present. Second, neither the "XML" declaration (e.g., ) nor the "DOCTYPE" declaration (e.g., ) may be
1413 present. (Accordingly, if another character set other than UTF-8
1414 is desired, then the "charset" parameter must be present.) All
1415 other XML 1.0 instructions (e.g., CDATA blocks, processing
1416 instructions, and so on) are allowed.
1418 If the 'type' parameter has the value "authInfo", then the
1419 document corresponds to the syntax given in Section 5.3.
1421 Appliations which use this media type: the ANANA datastore
1423 Additional Information: none
1425 Intended usage: cf., Section 4.1
1427 Additional Information: none
1429 Intended usage: limited use
1431 Contact Information: Marshall Rose
1433 Author/Change controller: the IESG
1435 7.4 The ANANA Datastore Profile for BEEP
1437 Profile Identification: http://anana.org/beep/anana-datastore
1439 Messages exchanged during Channel Creation: request,result
1441 Messages starting one-to-one exchanges: request
1443 Messages in positive replies: result
1445 Messages in negative replies: error
1447 Messages in one-to-many exchanges: none
1449 Message Syntax: cf., Section 5.1
1451 Message Semantics: cf., Section 3
1453 Contact Information: Marshall Rose
1455 8. Security Considerations
1457 Although service provisioning is a policy matter, at a minimum, all
1458 implementations must provide the following tuning profiles:
1460 for authentication: http://iana.org/beep/SASL/DIGEST-MD5
1462 for confidentiality: http://iana.org/beep/TLS (using the
1463 TLS_RSA_WITH_3DES_EDE_CBC_SHA cipher)
1465 for both: http://iana.org/beep/TLS (using the
1466 TLS_RSA_WITH_3DES_EDE_CBC_SHA cipher supporting client-side
1467 certificates)
1469 Further, implementations may choose to offer MIME-based security
1470 services providing message integrity and confidentiality, such as
1471 OpenPGP[20] or S/MIME[21].
1473 Regardless, consult:
1475 o [10]'s Section 9 for a discussion of BEEP-specific security
1476 issues; and,
1478 o [12]'s Section 7 for a discussion of SMTP-specific security
1479 issues.
1481 Finally, any remote resource accessed by a trigger should ensure that
1482 traffic originating from the datastore is authentic before taking any
1483 action that changes state.
1485 References
1487 [1] Malamud, C., Malamud, R. and M. Rose, "Overview of Assigned
1488 Name and Number Allocation (ANANA)", draft-anana-overview-00
1489 (work in progress), June 2002.
1491 [2] Malamud, C., Malamud, R. and M. Rose, "Implementation of ANANA
1492 namespaces at anana.org"", draft-anana-implementation-00 (work
1493 in progress), June 2002.
1495 [3] Hollenbeck, S. and M. Srivastava, "NSI Registry Registrar
1496 Protocol (RRP) Version 1.1.0", RFC 2832, May 2000.
1498 [4] Bray, T., Paoli, J., Sperberg-McQueen, C. and E. Maler,
1499 "Extensible Markup Language (XML) 1.0 (2nd ed)", W3C REC-xml,
1500 October 2000, .
1502 [5] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform
1503 Resource Identifiers (URI): Generic Syntax", RFC 2396, August
1504 1998.
1506 [6] World Wide Web Consortium, "XML Path Language (XPath) Version
1507 1.0", W3C XPath, November 1999, .
1510 [7] Laux, A. and L. Martin, "XML Update Language: Working Draft",
1511 September 2000, .
1513 [8] Crocker, D. and P. Overell, "Augmented BNF for Syntax
1514 Specifications: ABNF", RFC 2234, November 1997.
1516 [9] Eastlake, D., "Mapping Between MIME Types, Content-Types and
1517 URIs", draft-eastlake-cturi-03 (work in progress), November
1518 2001.
1520 [10] Rose, M., "The Blocks Extensible Exchange Protocol Core", RFC
1521 3080, March 2001.
1523 [11] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L.,
1524 Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol --
1525 HTTP/1.1", RFC 2616, June 1999.
1527 [12] Klensin, J., "Simple Mail Transfer Protocol", RFC 2821, April
1528 2001.
1530 [13] Murata, M., St.Laurent, S. and D. Kohn, "XML Media Types", RFC
1531 3023, January 2001.
1533 [14] Leach, P. and C. Newman, "Using Digest Authentication as a SASL
1534 Mechanism", RFC 2831, May 2000.
1536 [15] Metz, C., "OTP Extended Responses", RFC 2243, November 1997.
1538 [16] Newman, C., "The One-Time-Password SASL Mechanism", RFC 2444,
1539 October 1998.
1541 [17] Gulbrandsen, A., Vixie, P. and L. Esibov, "A DNS RR for
1542 specifying the location of services (DNS SRV)", RFC 2782,
1543 February 2000.
1545 [18] Haskin, D. and E. Allen, "IP Version 6 over PPP", RFC 2472,
1546 December 1998.
1548 [19] Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC
1549 2279, January 1998.
1551 [20] Elkins, M., Del Torto, D., Levien, R. and T. Roessler, "MIME
1552 Security with OpenPGP", RFC 3156, August 2001.
1554 [21] Ramsdell, B., "S/MIME Version 3 Message Specification", RFC
1555 2633, June 1999.
1557 [22] Alvestrand, H., "Tags for the Identification of Languages", RFC
1558 1766, March 1995.
1560 Author's Address
1562 Marshall T. Rose
1563 Dover Beach Consulting, Inc.
1564 POB 255268
1565 Sacramento, CA 95865-5268
1566 US
1568 Phone: +1 916 483 8878
1569 EMail: mrose@dbc.mtview.ca.us
1571 Appendix A. Acknowledgments
1573 The author acknowledges the contributions of Graham Klyne and Carl
1574 Malamud. In addition, the syntax of the fragment identifier is based
1575 on the generic fragment identifier syntax proposed by Jonathan Borden
1576 and Simon St. Laurent.
1578 Full Copyright Statement
1580 Copyright (C) The Internet Society (2002). All Rights Reserved.
1582 This document and translations of it may be copied and furnished to
1583 others, and derivative works that comment on or otherwise explain it
1584 or assist in its implementation may be prepared, copied, published
1585 and distributed, in whole or in part, without restriction of any
1586 kind, provided that the above copyright notice and this paragraph are
1587 included on all such copies and derivative works. However, this
1588 document itself may not be modified in any way, such as by removing
1589 the copyright notice or references to the Internet Society or other
1590 Internet organizations, except as needed for the purpose of
1591 developing Internet standards in which case the procedures for
1592 copyrights defined in the Internet Standards process must be
1593 followed, or as required to translate it into languages other than
1594 English.
1596 The limited permissions granted above are perpetual and will not be
1597 revoked by the Internet Society or its successors or assigns.
1599 This document and the information contained herein is provided on an
1600 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
1601 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
1602 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
1603 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
1604 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
1606 Acknowledgement
1608 Funding for the RFC Editor function is currently provided by the
1609 Internet Society.