Network Working Group M. Rose Internet-Draft Invisible Worlds, Inc. Expires: November 28, 2001 G. Klyne Baltimore Technologies D. Crocker Brandenburg Consulting May 30, 2001 The APEX Access Service draft-ietf-apex-access-02 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 November 28, 2001. Copyright Notice Copyright (C) The Internet Society (2001). All Rights Reserved. Abstract This memo describes the APEX access service, addressed as the well- known endpoint "apex=access". The access service is used to control use of both the APEX "relaying mesh" and other APEX services. Rose, et. al. Expires November 28, 2001 [Page 1] Internet-Draft The APEX Access Service May 2001 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Management of Access Information . . . . . . . . . . . . . . . 4 2.1 Retrieval of Access Information . . . . . . . . . . . . . . . 5 2.2 Update of Access Information . . . . . . . . . . . . . . . . . 6 3. Format of Access Entries . . . . . . . . . . . . . . . . . . . 8 4. The Access Service . . . . . . . . . . . . . . . . . . . . . . 11 4.1 Use of XML and MIME . . . . . . . . . . . . . . . . . . . . . 12 4.2 The Get Operation . . . . . . . . . . . . . . . . . . . . . . 13 4.3 The Set Operation . . . . . . . . . . . . . . . . . . . . . . 14 4.4 The Reply Operation . . . . . . . . . . . . . . . . . . . . . 16 5. Registration: The Access Service . . . . . . . . . . . . . . . 17 6. The Access Service DTD . . . . . . . . . . . . . . . . . . . . 18 7. Security Considerations . . . . . . . . . . . . . . . . . . . 21 References . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 22 A. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 23 B. Changes from draft-ietf-apex-access-01 . . . . . . . . . . . . 24 C. Changes from draft-ietf-apex-access-00 . . . . . . . . . . . . 25 Full Copyright Statement . . . . . . . . . . . . . . . . . . . 26 Rose, et. al. Expires November 28, 2001 [Page 2] Internet-Draft The APEX Access Service May 2001 1. Introduction This memo describes a access service that is built upon the APEX [1] "relaying mesh". The APEX access service is used to control use of both the relaying mesh and other APEX services. APEX, at its core, provides a best-effort datagram service. Within an administrative domain, all relays must be able to handle messages for any endpoint within that domain. APEX services are logically defined as endpoints but given their ubiquitous semantics they do not necessarily need to be associated with a single physical endpoint. As such, they may be provisioned co-resident with each relay within an administrative domain, even though they are logically provided on top of the relaying mesh, i.e., +----------+ +----------+ +----------+ +---------+ | APEX | | APEX | | APEX | | | | access | | presence | | report | | ... | | service | | service | | service | | | +----------+ +----------+ +----------+ +---------+ | | | | | | | | +----------------------------------------------------------------+ | | | APEX core | | | +----------------------------------------------------------------+ That is, applications communicate with an APEX service by exchanging data with a "well-known endpoint" (WKE). APEX applications communicate with the access service by exchanging data with the well-known endpoint "apex=access" in the corresponding administrative domain, e.g., "apex=access@example.com" is the endpoint associated with the access service in the "example.com" administrative domain. Note that within a single administrative domain, the relaying mesh makes use of the APEX access service in order to determine if an originator is allowed to transmit data to a recipient (c.f., Step 5.3 of Section 4.4.4.1 of [1]). Rose, et. al. Expires November 28, 2001 [Page 3] Internet-Draft The APEX Access Service May 2001 2. Management of Access Information Management of access information falls into two categories: o applications may retrieve the access entry associated with an endpoint; and, o applications may modify the access entry associated with an endpoint. Each is now described in turn. Rose, et. al. Expires November 28, 2001 [Page 4] Internet-Draft The APEX Access Service May 2001 2.1 Retrieval of Access Information When an application wants to retrieve the access entry associated with an endpoint, it sends a "get" element to the service, e.g., +-------+ +-------+ | | -- data -------> | | | appl. | | relay | | | <--------- ok -- | | +-------+ +-------+ C: S: The service immediately responds with a set operation containing the access entry and the same transaction-identifier, e.g., +-------+ +-------+ | | <------- data -- | | | relay | |access | | | -- ok ---------> | svc. | +-------+ +-------+ C: S: Rose, et. al. Expires November 28, 2001 [Page 5] Internet-Draft The APEX Access Service May 2001 2.2 Update of Access Information When an application wants to modify the access entry associated with an endpoint, it sends a "set" element to the service, e.g., +-------+ +-------+ | | -- data -------> | | | appl. | | relay | | | <--------- ok -- | | +-------+ +-------+ C: ... S: The service immediately responds with a reply operation containing the same transaction-identifier, e.g., +-------+ +-------+ | | <------- data -- | | | relay | |access | | | -- ok ---------> | svc. | +-------+ +-------+ C: S: Note that Step 5 of Section 4.3 requires that the "lastUpdate" attribute of an access entry be supplied in order to update that entry; accordingly, applications must successfully retrieve an access entry prior to trying to update that entry. Rose, et. al. Expires November 28, 2001 [Page 6] Internet-Draft The APEX Access Service May 2001 The service also immediately sends a set operation to the endpoint associated with the access entry, e.g., +-------+ +-------+ | | <------- data -- | | | relay | |access | | | -- ok ---------> | svc. | +-------+ +-------+ C: ... S: Note that Step 6.2 of Section 4.3 requires that the access service update the "lastUpdate" attribute of an access entry when it is updated. Rose, et. al. Expires November 28, 2001 [Page 7] Internet-Draft The APEX Access Service May 2001 3. Format of Access Entries Each administrative domain is responsible for maintaining an "access entry" for each of its endpoints and every subaddress (regardless of whether those endpoints are currently attached to the relaying mesh). Section 6 defines the syntax for access entries. Each access entry has an "owner" attribute, a "lastUpdate" attribute, and contains one or more "entry" elements: o the "owner" attribute specifies the address (endpoint or subaddress) associated with the access entry; o the "lastUpdate" attribute specifies the date and time that the service last updated the access entry; and, o each "entry" element specifies, with respect to the owner address, an actor and zero or more allowed actions for that actor. Within an entry, actions are specified as service/operation pairs, (e.g., "presence:publish" refers to the "publish" operation of the "presence" service). To refer to all services and/or all operations, the reserved value "all" is used (e.g., "all:data", "presence:all", and so on). Note that the service specified as "core" is reserved for use by the relaying mesh, e.g., the "core:data" action is consulted by the relaying mesh (c.f., Step 3.3 of Section 4.4.3.1 of [1]). An actor is an APEX endpoint and is specified using the "entity" syntax specified in Section 2.2 of [1]. However, both the "local" and "domain" parts may contain limited wildcarding: o The "local" part is either: * a literal string (e.g., "fred"); or, * the value "apex=*", specifying all APEX services; or, * the value "*", specifying any endpoint other than an APEX service. o The "domain" part is either: * a FQDN (e.g., "example.com"); or, * the value "*", specifying all administrative domains. Rose, et. al. Expires November 28, 2001 [Page 8] Internet-Draft The APEX Access Service May 2001 Regardless of the "entry" elements present in an access entry, four additional elements are always considered to exist at the end of the access entry: where "local@domain" specifies the endpoint associated with the access entry. Ordering of "entry" elements within an access element is significant: a process examining an access element selects the first "entry" element that matches the actor in question. For example, consider this access entry: Briefly: o For endpoints within the "example.com" administrative domain: * "fred", "wilma", and all APEX services, are allowed access to all operations for all APEX services; * "mr.slate" is allowed access only to send data through the relaying mesh; and, * any other endpoint is allowed access to send data and invoke the "subscribe" and "watch" operations of the APEX presence service. o For any endpoint outside the "example.com" administrative domain, the endpoint is allowed access to send data, regardless of whether it is an APEX service. Note that although the four additional elements are always present, the ordering semantics cause the final element to be unused. Rose, et. al. Expires November 28, 2001 [Page 9] Internet-Draft The APEX Access Service May 2001 As a second example, consider this access entry: This access entry, for a subaddress of "fred@example.com", allows only "barney/appl=wb@example.com" to send data through the relaying mesh. The ordering semantics have no impact on the four additional elements -- each is used. Rose, et. al. Expires November 28, 2001 [Page 10] Internet-Draft The APEX Access Service May 2001 4. The Access Service Section 5 contains the APEX service registration for the access service: o Within an administrative domain, the service is addressed using the well-known endpoint of "apex=access". o Section 6 defines the syntax of the operations exchanged with the service. o A consumer of the service initiates communications by sending data containing either the get or set operation. o The service replies to these operations, and does not initiate communications. An implementation of the service must maintain information about access entries in persistent storage. Consult Section 6.1.1 of [1] for a discussion on the properties of long-lived transaction-identifiers. Rose, et. al. Expires November 28, 2001 [Page 11] Internet-Draft The APEX Access Service May 2001 4.1 Use of XML and MIME Section 4.1 of [1] describes how arbitrary MIME content is exchanged as a BEEP [2] payload. For example, to transmit: where "..." refers to: then the corresponding BEEP message might look like this: C: MSG 1 2 . 42 1234 C: Content-Type: multipart/related; boundary="boundary"; C: start="<1@example.com>"; C: type="application/beep+xml" C: C: --boundary C: Content-Type: application/beep+xml C: Content-ID: <1@example.com> C: C: C: C: C: C: --boundary C: Content-Type: application/beep+xml C: Content-ID: <2@example.com> C: C: C: --boundary-- C: END or this: C: MSG 1 1 . 42 267 C: Content-Type: application/beep+xml C: C: C: C: C: C: C: C: C: END Rose, et. al. Expires November 28, 2001 [Page 12] Internet-Draft The APEX Access Service May 2001 4.2 The Get Operation When an application wants to retrieve the access entry associated with an address, it sends a "get" element to the service. The "get" element has an "owner" attribute, a "transID" attribute, and no content: o the "owner" attribute specifies the address associated with the access entry; and, o the "transID" attribute specifies the transaction-identifier associated with this operation. When the service receives a "get" element, we refer to the "owner" attribute of that element as the "subject", and the service performs these steps: 1. If the subject is outside of this administrative domain, a "reply" element having code 553 is sent to the originator. 2. If the subject does not refer to a valid endpoint, a "reply" element having code 550 is sent to the originator. 3. If the subject's access entry does not contain a "access:get" token for the originator, a "reply" element having code 537 is sent to the originator. 4. Otherwise, a "set" element, corresponding to the subject's access entry, is sent to the originator. Regardless of whether a "set" or "reply" element is sent to the originator, the "transID" attribute is identical to the value found in the "get" element sent by the originator. Rose, et. al. Expires November 28, 2001 [Page 13] Internet-Draft The APEX Access Service May 2001 4.3 The Set Operation When an application wants to modify the access entry associated with an address, it sends a "set" element to the service. The "set" element has an "owner" attribute, a "transID" attribute, a "timeStamp" attribute, and contains an "access" element: o the "owner" attribute specifies the address to be associated with the access entry; o the "transID" attribute specifies the transaction-identifier associated with this operation; o the "timeStamp" attribute specifies the application's notion of the current date and time; and, o the "access" element contains the desired access entry for the address. Rose, et. al. Expires November 28, 2001 [Page 14] Internet-Draft The APEX Access Service May 2001 When the service receives a "set" element, we refer to the "owner" attribute of that element as the "subject", and the service performs these steps: 1. If the "owner" attribute of the "set" element doesn't match the "owner" attribute of the "access" element contained in the "set" element, a "reply" element having code 503 is sent to the originator. 2. If the subject is outside of this administrative domain, a "reply" element having code 553 is sent to the originator. 3. If the subject does not refer to a valid endpoint, a "reply" element having code 550 is sent to the originator. 4. If the subject's access entry does not contain a "access:set" token for the originator, a "reply" element having code 537 is sent to the originator. 5. If the "lastUpdate" attribute of the "set" element is not semantically identical to the "lastUpdate" attribute of the subject's access entry, a "reply" element having code 555 is sent to the originator. (This allows a basic mechanism for atomic updates.) 6. Otherwise: 1. The subject's access entry is updated from the "set" element. 2. The "lastUpdate" attribute of the access entry is set to the service's notion of the current date time. 3. A "reply" element having code 250 is sent to the originator. 4. A "set" element, corresponding to the subject's access entry, is sent to the endpoint corresonding to the subject. When sending the "reply" element, the "transID" attribute is identical to the value found in the "set" element sent by the originator. Rose, et. al. Expires November 28, 2001 [Page 15] Internet-Draft The APEX Access Service May 2001 4.4 The Reply Operation While processing operations, the service may respond with a "reply" element. Consult Sections 10.2 and 6.1.2 of [1], respectively, for the syntax and semantics of the reply operation. Rose, et. al. Expires November 28, 2001 [Page 16] Internet-Draft The APEX Access Service May 2001 5. Registration: The Access Service Well-Known Endpoint: apex=access Syntax of Messages Exchanged: c.f., Section 6 Sequence of Messages Exchanged: c.f., Section 4 Access Control Tokens: access:get, access:set Contact Information: c.f., the "Authors' Addresses" section of this memo Rose, et. al. Expires November 28, 2001 [Page 17] Internet-Draft The APEX Access Service May 2001 6. The Access Service DTD %APEXCORE; Rose, et. al. Expires November 28, 2001 [Page 18] Internet-Draft The APEX Access Service May 2001 Rose, et. al. Expires November 28, 2001 [Page 19] Internet-Draft The APEX Access Service May 2001 Rose, et. al. Expires November 28, 2001 [Page 20] Internet-Draft The APEX Access Service May 2001 7. Security Considerations Consult [1]'s Section 11 for a discussion of security issues. Rose, et. al. Expires November 28, 2001 [Page 21] Internet-Draft The APEX Access Service May 2001 References [1] Rose, M., Klyne, G. and D. Crocker, "The Application Exchange Core", draft-ietf-apex-core-02 (work in progress), May 2001. [2] Rose, M., "The Blocks Extensible Exchange Protocol Core", RFC 3080, March 2001. Authors' Addresses Marshall T. Rose Invisible Worlds, Inc. 131 Stony Circle Suite 500 Santa Rosa, CA 95401 US Phone: +1 707 578 2350 EMail: mrose@invisible.net URI: http://invisible.net/ Graham Klyne Baltimore Technologies 1310 Waterside Arlington Business Park Theale, Reading RG7 4SA UK Phone: +44 118 903 8000 EMail: gk@acm.org David H. Crocker Brandenburg Consulting 675 Spruce Drive Sunnyvale, CA 94086 US Phone: +1 408 246 8253 EMail: dcrocker@brandenburg.com URI: http://www.brandenburg.com/ Rose, et. al. Expires November 28, 2001 [Page 22] Internet-Draft The APEX Access Service May 2001 Appendix A. Acknowledgements The authors gratefully acknowledge the contributions of: Neil Cook, Darren New, Chris Newman, and Scott Pead. Rose, et. al. Expires November 28, 2001 [Page 23] Internet-Draft The APEX Access Service May 2001 Appendix B. Changes from draft-ietf-apex-access-01 o It is made more clear that each subaddress has its own access entry. o A successful set operation results in the new access entry being sent to the endpoint associated with the entry. o A small number of typos were corrected. Rose, et. al. Expires November 28, 2001 [Page 24] Internet-Draft The APEX Access Service May 2001 Appendix C. Changes from draft-ietf-apex-access-00 o Change "addr-spec" syntax from RFC 822 to APEX's custom ABNF. Rose, et. al. Expires November 28, 2001 [Page 25] Internet-Draft The APEX Access Service May 2001 Full Copyright Statement Copyright (C) The Internet Society (2001). 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, et. al. Expires November 28, 2001 [Page 26]