| Network Working Group | A. McMillan |
| Internet-Draft | Morphoss |
| Intended status: Standards Track | C. Daboo |
| Expires: April 16, 2013 | Apple Inc. |
| October 15, 2012 |
Aggregated Service Discovery
draft-daboo-aggregated-service-discovery-01
This specification describes how clients can discover multiple services to configure themselves with a minimum of user-provided information, as short as possible sequence of queries and with a minimum of overhead for administrators of the services.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http:/⁠/⁠datatracker.ietf.org/⁠drafts/⁠current/⁠.
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."
This Internet-Draft will expire on April 16, 2013.
Copyright (c) 2012 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http:/⁠/⁠trustee.ietf.org/⁠license-⁠info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
There are currently various systems in place for discovery and configuration of individual protocols, but the process can often require an extensive series of requests using different protocols to discover all of the details needed to set up the various client services which an individual might use to interact with an organisation or service provider.
Consider Jason, a new employee at Example Enterprises. Jason needs to configure his e-mail program to use IMAP [RFC3501] + TLS on port 143 against mail.example.com, he needs to send mail on port 8557 via TLS+SMTP to smtp.example.com, his calendar is on port 8443 at https://caldav.example.com:8443/calendar/, and so forth. Some of these things can be discovered relatively easily, with a combination of DNS queries (including SRV lookups, certificate checking, and http requests). However, each protocol has its own requirements and settings and each has to be done separately. Whilst the client can "hide" the multiple service setup from the user, the actual implementation often requires separate code and processes to manage, making it more complex that it needs to be.
This specification defines a single protocol which will allows for discovery of a variety of services in a single call, allowing developers to simplify the coding and user interface in client software, and in particular in multi-function client software such as a combined e-mail and calendar client.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].
The namespace "urn:ietf:params:xml:ns:servicediscovery" is reserved for the XML elements defined in this specification. XML elements defined by individual implementations MUST NOT use the "urn:ietf:params:xml:ns:caldav" namespace, and instead should use a namespace that they control.
The following outlines the steps a client carries out to setup multiple services for a user:
The aggregated service discovery document is an XML document. The document contains two groups of information: overall service provider information (e.g., name, icon "badge", contact information), and a list of each service supported. Each service will contain some information common to each type of service, and then information specific to each service.
The XML DTD is defined in Appendix Appendix B. Each element is described below. An example of such an aggregated service discovery document for some common services is shown in Appendix Appendix C.
The root element for the document
Contains information describing the service provider, that can be used by clients to "group" individual services together under a common name or section when presenting details to the user.
The name for the service provider.
The description of the service provider.
An image that can be used as an "icon" for the service provider. The image data MUST be base64 encoded. The image SHOULD NOT exceed a size of 128 x 128 pixels.
Contact information for the service provider.
An email address that can be used to contact the service provider.
A URI for a webpage providing information about the service provider.
A URI for a webpage where a user can manage details of their account. e.g., a place where users can go to add additional (possibly payment required) services.
Provides detail for a specific service
The service type. This MUST be an IANA registered service type. The service type will determine what additional information is present within the enclosing SD:entry element.
Identifies the nature of the service to allow similar services to be grouped together. This is used in conjunction with the SD:priority element to group services of different types so that only one of the services within the group will be configured. For example, the IMAP [RFC3501] and POP3 [RFC1939] protocols will have SD:service values of 'imap' and 'pop3' respectively, and they could be given the same SD:application value of 'mailstore'. If the service provider prefers its users to use IMAP over POP3 (assuming the client supports IMAP), then the SD:priority value for the IMAP service would have a higher value than that for the POP3 service.
A positive, non-zero integer value that is used by the service provider to indicate a preference for one particular service over another within the same application group. Multiple services within a group may share the same priority, indicating that the service provider does not wish to express a preference. Services with a higher numbered priority are to be preferred over lower numbered ones.
The hostname of the server providing the service.
The network port number of the server providing the service.
Provides detail of transport layer security to be used with the service.
If present, indicates that clients MUST use transport layer security when connecting to the server providing the service.
TODO: not sure we should have this as opposed to relying on normal certificate verification for each service. If present, indicates details about TLS certificates that the server will present to the client during TLS negotiation. Clients can use these certificate details to "short circuit" certificate verification for the service.
Provides detail of authentication to be used with the service.
TODO element details
A ".well-known" URI is registered by this specification: "servicediscovery" (see Section 10). This URI points to a resource that the client can use to retrieve the aggregated service discovery document for the site. Clients MUST handle HTTP redirects on the ".well-known" URI. Clients MUST handle HTTP authentication on the ".well-known" URI.
When requesting the document clients MUST include a URI query parameter "id" set to the user identifier entered by the user. When responding to the request, the server MUST tailor the aggregated service discovery document for the user making the request and MUST require HTTP authentication by that user before returning the document.
The SD:application and SD:priority elements provide a way for a service provider to distinguish multiple services of the same type, as well as allow the client to select the most appropriate service when several alternatives exist.
For example, consider the case of a service provider supporting two separate email retrieval services, one the "primary" account, and the other for "internal" messaging only. It is expected that clients configure accounts for both services. Each service also offers either IMAP [RFC3501] or POP3 [RFC1939] as an email retrieval protocol. In this case the aggregated service discovery document would contain four SD:entry elements: two describing an IMAP service and two describing a POP3 service. Each entry would contain an SD:application element that groups one IMAP and one POP3 service together for each of the "primary" and "internal" account groups. Each entry would also contain an SD:priority element indicating the service providers preference for clients to use either IMAP or POP3. An example of such an aggregated service discovery document is shown in Appendix Appendix D.
When a client retrieves and processes such a document, it would first group services based on the SD:application value. For each group, it iterates over the list of entries in the group, ordered by SD:priority values, and configures an account for the first one it finds with an SD:service that it supports.
Some elements of the service discovery document can contain human readable text that clients might choose to present to a user. Clients SHOULD use the Accept-Language header behavior described in Section 14.4 of [RFC2616] to ensure the server can return a document suitable for the user's chosen language. Servers SHOULD support variations of the service discovery document based on language, returning the appropriate variation in response to client requests. When doing so the xml:lang attribute SHOULD be included on all XML elements in the document that have been localized.
When using an SRV lookup to discover a server hosting the service discovery document, a malicious attacker with access to the DNS server data, or able to get spoofed answers cached in a recursive resolver, can potentially cause clients to connect to a server hosting a bogus service discovery document with service data chosen by the attacker. In the absence of a secure DNS option, clients SHOULD check that the target FQDN returned in the SRV record matches the original service domain that was queried. If the target FQDN is not in the queried domain, clients SHOULD verify with the user that the SRV target FQDN is suitable for use before executing any connections to the host.
HTTP requests for the service-discovery document MUST be performed via TLS. Clients MUST use the procedure outlined in Section 4.3 of [RFC6125] to verify the service.
Registration request for the aggregated service discovery namespace:
This section defines the MIME media type for use with the aggregated service discovery XML data.
This document defines a ".well-known" URI using the registration procedure and template from Section 5.1 of [RFC5785].
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. |
| [RFC2616] | Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. |
| [RFC2782] | Gulbrandsen, A., Vixie, P. and L. Esibov, "A DNS RR for specifying the location of services (DNS SRV)", RFC 2782, February 2000. |
| [RFC2818] | Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. |
| [RFC3023] | Murata, M., St. Laurent, S. and D. Kohn, "XML Media Types", RFC 3023, January 2001. |
| [RFC5785] | Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known Uniform Resource Identifiers (URIs)", RFC 5785, April 2010. |
| [RFC6125] | Saint-Andre, P. and J. Hodges, "Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS)", RFC 6125, March 2011. |
| [RFC1939] | Myers, J.G. and M.T. Rose, "Post Office Protocol - Version 3", STD 53, RFC 1939, May 1996. |
| [RFC3501] | Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1", RFC 3501, March 2003. |
Changes in -01:
<!ELEMENT servicediscovery (provider?, entry*) >
<!ELEMENT provider (name?, description?, image?,
contact?, manage?) >
<!ELEMENT name (#PCDATA) >
<!ELEMENT description (#PCDATA) >
<!ELEMENT image (#PCDATA) >
<!ELEMENT contact (email?, uri?) >
<!ELEMENT email (#PCDATA) >
<!ELEMENT uri (#PCDATA) >
<!ELEMENT manage (#PCDATA) >
<!ELEMENT entry (service, (application, priority)?,
host?, port?, tls?, auth?, ANY) >
<!ELEMENT service (#PCDATA) >
<!ELEMENT application (#PCDATA) >
<!ELEMENT priority (#PCDATA) >
<!ELEMENT host (#PCDATA) >
<!ELEMENT port (#PCDATA) >
<!ELEMENT tls (required?, certificate*) >
<!ELEMENT required EMPTY >
<!ELEMENT certificate (data|id|hash) >
<!ELEMENT data (#PCDATA) >
<!ELEMENT id (#PCDATA) >
<!ELEMENT hash (#PCDATA) >
<!ELEMENT auth (type, details?) >
<!ELEMENT type (#PCDATA) >
<!ELEMENT details (userpswd|ANY) >
<!ELEMENT userpswd (userid?, password?) >
<!ELEMENT userid (#PCDATA) >
<!ELEMENT password (#PCDATA) >
<!ELEMENT principal-URL (#PCDATA) >
GET /.well-known/servicediscovery?id=cyrus@example.com HTTP/1.1
Host:example.com:443
Authorization: basic QmFzZTY0IGlzIGVhc3kgdG8gZGVjb2Rl
Content-Type: application/servicediscovery+xml
Content-Length: xxx
<?xml version="1.0" standalone="no"?>
<servicediscovery xmlns="urn:ietf:params:xml:ns:servicediscovery">
<provider>
<name>Super-duper ISP</name>
<description>
Super-duper ISP is the home for all your data.
</description>
<contact>
<email>superduper@example.com</email>
<uri>http://www.example.com</uri>
</contact>
<manage>http://www.example.com/myaccount.html</manage>
</provider>
<entry>
<service>imap</service>
<application>mail-access</application>
<priority>2</priority>
<host>imap.example.com</host>
<port>143</port>
<tls>
<required />
</tls>
<auth>
<type>CRAM-MD5</type>
</auth>
</entry>
<entry>
<service>pop3</service>
<application>mail-access</application>
<priority>1</priority>
<host>pop.example.com</host>
<port>110</port>
<tls>
<required />
</tls>
<auth>
<type>CRAM-MD5</type>
</auth>
</entry>
<entry>
<service>submission</service>
<host>mail.example.com</host>
<port>587</port>
<tls>
<required />
</tls>
<auth>
<type>CRAM-MD5</type>
</auth>
</entry>
<entry>
<service>caldav</service>
<host>calendar.example.com</host>
<port>443</port>
<tls>
<required />
</tls>
<auth>
<type>Digest</type>
</auth>
<principal-URL>https://calendar.example.com/principals/
users/cyrus</principal-URL>
</entry>
<entry>
<service>carddav</service>
<host>contacts.example.com</host>
<port>443</port>
<tls>
<required />
</tls>
<auth>
<type>Digest</type>
</auth>
<principal-URL>https://contacts.example.com/principals/
users/cyrus</principal-URL>
</entry>
</servicediscovery>
GET /.well-known/servicediscovery?id=cyrus@example.com HTTP/1.1
Host:example.com:443
Authorization: basic QmFzZTY0IGlzIGVhc3kgdG8gZGVjb2Rl
Content-Type: application/servicediscovery+xml
Content-Length: xxx
<?xml version="1.0" standalone="no"?>
<servicediscovery xmlns="urn:ietf:params:xml:ns:servicediscovery">
<provider>
<name>Mail Agrregator ISP</name>
<description>
Primary and internal email services.
</description>
<contact>
<email>emails@example.com</email>
<uri>http://www.example.com</uri>
</contact>
<manage>http://www.example.com/myaccount.html</manage>
</provider>
<entry>
<service>imap</service>
<application>primary email</application>
<priority>2</priority>
<host>imap.example.com</host>
<port>143</port>
<tls>
<required />
</tls>
<auth>
<type>CRAM-MD5</type>
</auth>
</entry>
<entry>
<service>pop3</service>
<application>primary email</application>
<priority>1</priority>
<host>pop.example.com</host>
<port>110</port>
<tls>
<required />
</tls>
<auth>
<type>CRAM-MD5</type>
</auth>
</entry>
<entry>
<service>imap</service>
<application>internal email</application>
<priority>2</priority>
<host>imap.example.com</host>
<port>143</port>
<tls>
<required />
</tls>
<auth>
<type>CRAM-MD5</type>
</auth>
</entry>
<entry>
<service>pop3</service>
<application>internal email</application>
<priority>1</priority>
<host>pop.example.com</host>
<port>110</port>
<tls>
<required />
</tls>
<auth>
<type>CRAM-MD5</type>
</auth>
</entry>
</servicediscovery>