Network Working Group A. McMillan
Internet-Draft Morphoss
Intended status: Standards Track C. Daboo
Expires: March 2, 2013 Apple Inc.
August 29, 2012
Aggregated Service Discovery
draft-daboo-aggregated-service-discovery-00
Abstract
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.
Status of This Memo
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 March 2, 2013.
Copyright Notice
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.
McMillan & Daboo Expires March 2, 2013 [Page 1]
Internet-Draft Aggregated Service Discovery August 2012
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Conventions Used in This Document . . . . . . . . . . . . . . 4
4. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
5. Aggregated Service Discovery Document Format . . . . . . . . . 5
5.1. SD:servicediscovery . . . . . . . . . . . . . . . . . . . 5
5.1.1. SD:common . . . . . . . . . . . . . . . . . . . . . . 5
5.1.1.1. SD:name . . . . . . . . . . . . . . . . . . . . . 5
5.1.1.2. SD:description . . . . . . . . . . . . . . . . . . 5
5.1.1.3. SD:image . . . . . . . . . . . . . . . . . . . . . 5
5.1.1.4. SD:contact . . . . . . . . . . . . . . . . . . . . 5
5.1.2. SD:service . . . . . . . . . . . . . . . . . . . . . . 6
5.1.2.1. SD:type . . . . . . . . . . . . . . . . . . . . . 6
5.1.2.2. SD:class . . . . . . . . . . . . . . . . . . . . . 6
5.1.2.3. SD:priority . . . . . . . . . . . . . . . . . . . 6
5.1.2.4. SD:host . . . . . . . . . . . . . . . . . . . . . 6
5.1.2.5. SD:port . . . . . . . . . . . . . . . . . . . . . 6
5.1.2.6. SD:tls . . . . . . . . . . . . . . . . . . . . . . 6
5.1.2.7. SD:auth . . . . . . . . . . . . . . . . . . . . . 7
6. Finding the Aggregated Service Discovery Information . . . . . 7
7. Internationalization Considerations . . . . . . . . . . . . . 7
8. Security Considerations . . . . . . . . . . . . . . . . . . . 8
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
9.1. Namespace Registration . . . . . . . . . . . . . . . . . . 8
9.2. Media Type . . . . . . . . . . . . . . . . . . . . . . . . 8
9.3. Well-Known URI Registration . . . . . . . . . . . . . . . 9
9.3.1. servicediscovery Well-Known URI Registration . . . . . 9
10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 10
11. Normative References . . . . . . . . . . . . . . . . . . . . . 10
Appendix A. Aggregated Service Discovery Schema . . . . . . . . . 10
Appendix B. Example . . . . . . . . . . . . . . . . . . . . . . . 12
McMillan & Daboo Expires March 2, 2013 [Page 2]
Internet-Draft Aggregated Service Discovery August 2012
1. Introduction
There are currently various systems in place for discovery and
configuration of individual protocols, but the process can often
require am 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 + 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.
2. Open Issues
1. XML vs JSON for the document format
2. Support custom service attributes without the need for formal
registration? If so, would we need a "critical" attribute to
indicate ones that must be understood?
3. Is it OK to embed certificate details for the actual services or
a root certificate?
4. Do we want to support delegation of service information to
another service discovery document? That might be useful in
cases where different services at the same domain are under the
control of different "authorities".
5. Should we define a local area network discovery mechanism? i.e.,
client connects to local network and immediately sees a set of
services it could configure for the user.
McMillan & Daboo Expires March 2, 2013 [Page 3]
Internet-Draft Aggregated Service Discovery August 2012
6. Should we specify whether clients should re-check account
information on a regular basis for updates, or should we rely on
in-protocol account redirection?
3. Conventions Used in This Document
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.
4. Overview
The following outlines the steps a client carries out to setup
multiple services for a user:
1. The client software is expected to capture a user identifier and
domain name (possibly entered in the form of an email address)
from the user, and possibly a password. e.g.,
'cyrus@example.com'.
2. The client would make an initial DNS SRV [RFC2782] query for
'_servicediscovery._tcp.example.com'. The result of the SRV
lookup will be a hostname that is then used in place of the user
supplied domain name for the next steps. If the SRV lookup is
unsuccessful, then the user supplied domain name is used for the
next steps.
3. The client then makes an HTTP GET request [RFC2616] against the
server, using TLS [RFC2818], requesting the URL 'https://{domain
name}/.well-known/servicediscovery?id={user identifier}', where
'{domain name}' is the host name determined from step #2, and
'{user identifier}' is the user supplied identifier from step #1.
The client will follow any redirects and respond to any
authentication challenges. Where the user did not provide an
appropriate authentication token in the first step the client
software will prompt for it at this point
4. The client will receive an XML document in step #3 conforming to
the format described in Section 5. The client parses this
document to extract information about the available services. At
that point it can either present a list of services to the user
so that they can decide exactly what they want setup, or it can
McMillan & Daboo Expires March 2, 2013 [Page 4]
Internet-Draft Aggregated Service Discovery August 2012
automatically setup services for all those it supports.
5. Aggregated Service Discovery Document Format
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 A. Each element is described
below.
5.1. SD:servicediscovery
The root element for the document
5.1.1. SD:common
Contains information describing the entire service, that can be used
by clients to provide information about the overall service.
5.1.1.1. SD:name
The name for the service.
5.1.1.2. SD:description
The description of the service.
5.1.1.3. SD:image
An image that can be used as an "icon" for the service. The image
data MUST be base64 encoded. The image SHOULD NOT exceed a size of
128 x 128 pixels.
5.1.1.4. SD:contact
Contact information for the service provider.
5.1.1.4.1. SD:email
An email address that can be used to contact the service provider.
McMillan & Daboo Expires March 2, 2013 [Page 5]
Internet-Draft Aggregated Service Discovery August 2012
5.1.1.4.2. SD:uri
A URI for a webpage providing information about the service provider.
5.1.2. SD:service
Provides detail for a specific service
5.1.2.1. SD:type
The service type. This MUST be an IANA registered service type. The
type will determine what additional information is present within the
enclosing SD:service element.
5.1.2.2. SD:class
The class of the service. This is used in conjunction with the SD:
priority element to group services of different types into a single
class with the assumption that only one of the services within the
class will be configured. For example, the IMAP and POP3 protocols
will have SD:type values of 'imap' and 'pop3' respectively, and they
could be given the same SD:class 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.
5.1.2.3. SD:priority
An integer value in the range 1 through 10 that is used by the
service provider to indicate a preference for one particular service
over another of the same class. Multiple services within a class 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.
5.1.2.4. SD:host
The hostname of the server providing the service.
5.1.2.5. SD:port
The network port number of the server providing the service.
5.1.2.6. SD:tls
Provides detail of transport layer security to be used with the
service.
McMillan & Daboo Expires March 2, 2013 [Page 6]
Internet-Draft Aggregated Service Discovery August 2012
5.1.2.6.1. SD:required
If present, indicates that clients MUST use transport layer security
when connecting to the server providing the service.
5.1.2.6.2. SD:certificate
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.
5.1.2.7. SD:auth
Provides detail of authentication to be used with the service.
TODO element details
6. Finding the Aggregated Service Discovery Information
A ".well-known" URI is registered by this specification:
"servicediscovery" (see Section 9). 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.
7. Internationalization Considerations
Some elements of the service discovery document can contain human
readable text that client 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.
McMillan & Daboo Expires March 2, 2013 [Page 7]
Internet-Draft Aggregated Service Discovery August 2012
8. Security Considerations
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.
9. IANA Considerations
9.1. Namespace Registration
Registration request for the aggregated service discovery namespace:
URI: urn:ietf:params:xml:ns:icalendar-2.0
Registrant Contact: IESG
XML: None. Namespace URIs do not represent an XML specification.
9.2. Media Type
This section defines the MIME media type for use with the aggregated
service discovery XML data.
Type name: application
Subtype name: servicediscovery+xml
Required parameters: none
Optional parameters: charset as defined for application/xml in
[RFC3023]; per [RFC3023], use of the charset property parameter
with the value "utf-8" is "STRONGLY RECOMMENDED"
McMillan & Daboo Expires March 2, 2013 [Page 8]
Internet-Draft Aggregated Service Discovery August 2012
Encoding considerations: Same as encoding considerations of
application/xml as specified in [RFC3023]
Security considerations: See Section 8.
Interoperability considerations: This media type provides a format
for aggregated service discovery information based on XML.
Published specification: This specification.
Applications which use this media type: Applications that configure
services.
Additional information:
Magic number(s): None
File extension(s): None
Macintosh file type code(s): None specified.
Person & email address to contact for further information: IESG
Intended usage: COMMON
Restrictions on usage: There are no restrictions on where this media
type can be used.
Author: See the "Author's Address" section of this document.
Change controller: IETF
9.3. Well-Known URI Registration
This document defines a ".well-known" URI using the registration
procedure and template from Section 5.1 of [RFC5785].
9.3.1. servicediscovery Well-Known URI Registration
URI suffix: servicediscovery
Change controller: IETF.
Specification document(s): This RFC.
McMillan & Daboo Expires March 2, 2013 [Page 9]
Internet-Draft Aggregated Service Discovery August 2012
Related information: None.
10. Acknowledgments
11. Normative References
[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.
Appendix A. Aggregated Service Discovery Schema
McMillan & Daboo Expires March 2, 2013 [Page 10]
Internet-Draft Aggregated Service Discovery August 2012
<!ELEMENT servicediscovery (common?, service*) >
<!ELEMENT common (name?, description?, image?, contact?) >
<!ELEMENT name (#PCDATA) >
<!ELEMENT description (#PCDATA) >
<!ELEMENT image (#PCDATA) >
<!ELEMENT contact (email?, uri?) >
<!ELEMENT email (#PCDATA) >
<!ELEMENT uri (#PCDATA) >
<!ELEMENT service (type, (class, priority)?,
host?, port?, tls?, auth?, ANY) >
<!ELEMENT type (#PCDATA) >
<!ELEMENT class (#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) >
McMillan & Daboo Expires March 2, 2013 [Page 11]
Internet-Draft Aggregated Service Discovery August 2012
Appendix B. Example
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">
<common>
<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>
</common>
<service>
<type>imap</type>
<class>mail-access</class>
<priority>2</priority>
<host>imap.example.com</host>
<port>143</port>
<tls>
<required />
</tls>
<auth>
<type>CRAM-MD5</type>
</auth>
</service>
<service>
<type>pop3</type>
<class>mail-access</class>
<priority>1</priority>
<host>pop.example.com</host>
<port>110</port>
<tls>
<required />
</tls>
<auth>
<type>CRAM-MD5</type>
</auth>
McMillan & Daboo Expires March 2, 2013 [Page 12]
Internet-Draft Aggregated Service Discovery August 2012
</service>
<service>
<type>submission</type>
<host>mail.example.com</host>
<port>587</port>
<tls>
<required />
</tls>
<auth>
<type>CRAM-MD5</type>
</auth>
</service>
<service>
<type>caldav</type>
<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>
</service>
<service>
<type>carddav</type>
<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>
</service>
</servicediscovery>
McMillan & Daboo Expires March 2, 2013 [Page 13]
Internet-Draft Aggregated Service Discovery August 2012
Authors' Addresses
Andrew McMillan
Morphoss Ltd
6 Karoro Place
Porirua 5024
New Zealand
EMail: andrew@morphoss.com
URI: http://www.morphoss.com/
Cyrus Daboo
Apple Inc.
1 Infinite Loop
Cupertino, CA 95014
USA
EMail: cyrus@daboo.name
URI: http://www.apple.com/
McMillan & Daboo Expires March 2, 2013 [Page 14]