draft-jones-simple-web-discovery-03.txt   draft-jones-simple-web-discovery-04.txt 
Network Working Group M. Jones Network Working Group M. Jones
Internet-Draft Y. Goland Internet-Draft Y. Goland
Intended status: Standards Track Microsoft Intended status: Standards Track Microsoft
Expires: January 7, 2013 July 6, 2012 Expires: May 9, 2013 November 5, 2012
Simple Web Discovery (SWD) Simple Web Discovery (SWD)
draft-jones-simple-web-discovery-03 draft-jones-simple-web-discovery-04
Abstract Abstract
Simple Web Discovery (SWD) defines an HTTPS GET based mechanism to Simple Web Discovery (SWD) defines an HTTPS GET based mechanism to
discover the location of a given type of service for a given discover the location of a given type of service for a given
principal starting only with a domain name. principal starting only with a domain name.
Status of this Memo Status of this Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
skipping to change at page 1, line 32 skipping to change at page 1, line 32
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 7, 2013. This Internet-Draft will expire on May 9, 2013.
Copyright Notice Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified as the Copyright (c) 2012 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3
2. Simple Web Discovery Request . . . . . . . . . . . . . . . . . 3 2. Simple Web Discovery Request . . . . . . . . . . . . . . . . . 3
3. Simple Web Discovery Responses . . . . . . . . . . . . . . . . 4 2.1. "simple-web-discovery" Subdomain . . . . . . . . . . . . . 4
3.1. Response Containing One or More Locations . . . . . . . . 4 3. Simple Web Discovery Responses . . . . . . . . . . . . . . . . 5
3.2. Redirecting All Simple Web Discovery Requests . . . . . . 5 3.1. Response Containing One or More Locations . . . . . . . . . 5
3.3. 401 Unauthorized Response . . . . . . . . . . . . . . . . 7 3.2. 401 Unauthorized Response . . . . . . . . . . . . . . . . . 5
3.4. Other HTTP 1.1 Responses . . . . . . . . . . . . . . . . . 7 3.3. Other HTTP 1.1 Responses . . . . . . . . . . . . . . . . . 5
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 5
5. Security Considerations . . . . . . . . . . . . . . . . . . . 7 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 6
6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 6
6.1. Normative References . . . . . . . . . . . . . . . . . . . 8 6.1. Normative References . . . . . . . . . . . . . . . . . . . 6
6.2. Informative References . . . . . . . . . . . . . . . . . . 9 6.2. Informative References . . . . . . . . . . . . . . . . . . 7
Appendix A. Document History . . . . . . . . . . . . . . . . . . 9 Appendix A. Document History . . . . . . . . . . . . . . . . . . . 7
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 8
1. Introduction 1. Introduction
Simple Web Discovery (SWD) defines an HTTPS GET based mechanism to Simple Web Discovery (SWD) defines an HTTPS GET based mechanism to
discover the location of a given type of service for a given discover the location of a given type of service for a given
principal starting only with a domain name. SWD requests use query principal starting only with a domain name. SWD requests use query
parameters to specify a URI for the principal and another URI for the parameters to specify a URI for the principal and another URI for the
type of service being sought. If the request is successful then the type of service being sought. If the request is successful then the
response, by default, is a JavaScript Object Notation (JSON) response, by default, is a JavaScript Object Notation (JSON)
[RFC4627] object containing an array of URIs that point to where the [RFC4627] object containing an array of URIs that point to where the
principal has instances of services of the requested type. principal has instances of services of the requested type.
For example, let us say that a requester wants to discover where Joe For example, let us say that a requester wants to discover where Joe
keeps his calendar. The requester could take Joe's e-mail address, keeps his calendar. The requester could take Joe's e-mail address,
"joe@example.com", and use its domain to create an HTTPS GET request "joe@example.com", and use its domain to create an HTTPS GET request
of the following form (with long lines broken for display purposes of the following form (with long lines broken for display purposes
only): only):
GET /.well-known/simple-web-discovery
?principal=mailto:joe@example.com GET /.well-known/simple-web-discovery
?principal=joe@example.com
&service=urn:example:service:calendar HTTP/1.1 &service=urn:example:service:calendar HTTP/1.1
Host: example.com Host: example.com
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
{ {
"locations": ["https://calendars.example.net/calendars/joseph"] "locations": ["https://calendars.example.net/calendars/joseph"]
} }
Note: The request-URI is left unencoded in the above example for the Note: The request-URI is left unencoded in the above example for the
sake of readability. The query parameters above would actually be sake of readability. The query parameters above would actually be
encoded as "?principal=mailto%3Ajoe%40example.com&service=urn%3Aexamp encoded as "?principal=joe%40example.com&service=urn%3Aexample%3Aserv
le%3Aservice%3Acalendar". ice%3Acalendar".
1.1. Notational Conventions 1.1. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in Key words for use in document are to be interpreted as described in Key words for use in
RFCs to Indicate Requirement Levels [RFC2119]. RFCs to Indicate Requirement Levels [RFC2119].
2. Simple Web Discovery Request 2. Simple Web Discovery Request
Domains that support SWD requests MUST make available a SWD server Domains that support SWD requests SHOULD make an SWD server available
for their domain at the path "/.well-known/simple-web-discovery". for their domain at the path "/.well-known/simple-web-discovery".
The syntax and semantics of "/.well-known" are defined in RFC 5785 The syntax and semantics of "/.well-known" are defined in RFC 5785
[RFC5785]. "simple-web-discovery" MUST point to a SWD server [RFC5785]. "/.well-known/simple-web-discovery" MUST point to an SWD
compliant with this specification. server compliant with this specification.
SWD servers MUST support receiving SWD requests via TLS 1.2 [RFC5246] SWD servers MUST support receiving SWD requests via TLS 1.2 [RFC5246]
and MAY support other transport layer security mechanisms of and MAY support other transport layer security mechanisms of
equivalent security. SWD servers MUST reject SWD requests sent over equivalent security. SWD servers MUST reject SWD requests sent over
plain HTTP or any other transport that does not provide both privacy plain HTTP or any other transport that does not provide both privacy
and validation of the server's identity. and validation of the server's identity.
A SWD server is queried using an HTTPS GET request with the An SWD server is queried using an HTTPS GET request with the
previously specified path along with a query segment containing a previously specified path along with a query segment containing a
form encoded using the application/x-www-form-urlencoded encoding form encoded using the application/x-www-form-urlencoded encoding
algorithm as defined in HTML 4.01 [W3C.REC-html401-19991224]. The algorithm as defined in HTML 4.01 [W3C.REC-html401-19991224]. The
form MUST contain two name/value pairs that MUST appear exactly once, form MUST contain two name/value pairs that MUST appear exactly once,
"principal" and "service". Both name/value pairs MUST have values "principal" and "service". Both name/value pairs MUST have values
that are set to URIs [RFC3986]. If any of the previous requirements that are set to URIs [RFC3986]. If any of the previous requirements
are not met in a SWD request, then the request MUST be rejected with are not met in an SWD request, then the request MUST be rejected with
a 400 Bad Request. a 400 Bad Request.
The SWD request form MAY contain additional name/value pairs but if The SWD request form MAY contain additional name/value pairs but if
those name/value pairs are not recognized by the SWD server then the those name/value pairs are not recognized by the SWD server then the
SWD server MUST ignore them for processing purposes. SWD server MUST ignore them for processing purposes.
The "principal" query component is a URI that identifies an entity. The "principal" query component is a URI that identifies an entity.
The "service" query component is a URI that identifies a service The "service" query component is a URI that identifies a service
type. The semantics of the SWD query is "Please return the type. The semantics of the SWD query is "Please return the
location(s) of instances of the specified service type associated location(s) of instances of the specified service type associated
with the specified principal". The definition of URIs used to with the specified principal". The definition of URIs used to
identify principals and services are outside the scope of this identify principals and services are outside the scope of this
specification. specification.
3. Simple Web Discovery Responses SWD servers MAY also be located on ports other than 443 (the default
HTTPS port), provided they use TLS on those ports. The means by
3.1. Response Containing One or More Locations which an SWD client would know to use any alternative ports are out
of scope for this specification.
Unless another content-type is negotiated, a 200 OK response to a SWD
request that contains the information requested MUST return content
of type application/json [RFC4627]. The JSON response MUST contain a
JSON object that contains a member pair whose name is the string
"locations" and whose value is an array of strings that are each a
URI pointing to a location where the desired service type belonging
to the specified principal can be found. There are no semantics
associated with the order in which the URIs are listed in the array.
The JSON object MAY contain other members but a receiver of the
object MAY ignore any member pairs whose name it does not recognize.
3.2. Redirecting All Simple Web Discovery Requests
SWD requests by definition start off by being issued to the
"/.well-known/simple-web-discovery" location. But locating a SWD
server at a root location can prove inconvenient. To enable service
level redirection, a SWD server MAY return a 200 OK to an HTTPS
request with a content type of application/json (or whatever other
content type has been negotiated) that contains a JSON object that
contains a member pair whose name is the string
"SWD_service_redirect" whose value is a JSON object with a member
pair whose name is "location" and whose value is a string that
encodes a URI. Optionally, the JSON object value of
"SWD_service_redirect" MAY also contain a member whose name is
"expires" and whose value is a JSON number that encodes an integer.
A SWD compliant client MUST support the "SWD_service_redirect"
response.
The JSON objects MAY contain other members but a receiver of the
objects MAY ignore any pairs whose name it does not recognize.
The "location" member identifies the URI that the caller MUST
redirect all SWD requests for that domain to until the "expires" time
has passed. SWD requests for the redirected domain MUST be
constructed by taking the URI returned in the "location" and using it
as the base URI to which the SWD form arguments are then added as
query parameters. The location URI MUST NOT include a query
component.
The following is an example of redirect messages (with long lines
broken for display purposes only):
GET /.well-known/simple-web-discovery
?principal=mailto:joe@example.com
&service=urn:example:service:calendar HTTP/1.1
Host: example.com
HTTP/1.1 200 OK
Content-Type: application/json
{
"SWD_service_redirect":
{
"location": "https://swd.example.com/swd_server",
"expires": 1300752001
}
}
GET /swd_server 2.1. "simple-web-discovery" Subdomain
?principal=mailto:joe@example.com
&service=urn:example:service:calendar HTTP/1.1
Host: swd.example.com
HTTP/1.1 200 OK It may be difficult or impossible for some domains wanting to support
Content-Type: application/json SWD requests to make an SWD server available for their domain at the
path "/.well-known/simple-web-discovery". For instance, in the case
of hosted domains, no web server may be running on the domain host at
all.
{ For that reason, SWD servers for a domain MAY be located on a
"locations": ["https://calendars.example.net/calendars/joseph"] specific subdomain of that domain: "simple-web-discovery". For
} example, the SWD server for the domain "example.com" MAY be located
at the URI "https://simple-web-discovery.example.com/.well-known/simp
le-web-discovery".
Note: The request-URIs are left unencoded in the above example for SWD clients MUST first attempt to make an SWD request to the domain's
the sake of readability. "/.well-known/simple-web-discovery" endpoint, and then if that fails,
they MUST then attempt to make the request to the SWD endpoint at the
"simple-web-discovery" subdomain for the domain.
The "location" URI MUST be an HTTPS URL. 3. Simple Web Discovery Responses
The optional "expires" member identifies the point in time at which 3.1. Response Containing One or More Locations
the caller MUST NOT redirect its SWD requests for that domain to the
previously obtained "location" and MUST instead return to the
"/.well-known/simple-web-discovery" location. The value of the
"expires" member MUST encode the number of seconds from 1970-01-
01T0:0:0Z as measured in UTC until the desired date/time. See RFC
3339 [RFC3339] for details regarding date/times in general and UTC in
particular. If the "expires" value is in the past or if the value is
more than one hour in the future then the response MUST be treated as
if it didn't contain an "expires" value.
If the "expires" value is omitted or if its value is incorrect then A 200 OK response to an SWD request that contains the information
the "expires" value MUST be treated as having a value of exactly one requested MUST return content of type application/json [RFC4627].
hour into the future. The JSON response MUST contain a JSON object that contains a member
pair whose name is the string "locations" and whose value is an array
of strings that are each a URI pointing to a location where the
desired service type belonging to the specified principal can be
found. There are no semantics associated with the order in which the
URIs are listed in the array.
If a JSON response is received that contains both a member pair with The JSON object MAY contain other members but a receiver of the
the name "SWD_service_redirect" and a member pair with the name object MAY ignore any member pairs whose name it does not recognize.
"locations" as children of the object root then the
"SWD_service_redirect" member pair MUST be ignored.
3.3. 401 Unauthorized Response 3.2. 401 Unauthorized Response
A SWD server MAY respond to a request with a 401 Unauthorized An SWD server MAY respond to a request with a 401 Unauthorized
Response, as described in RFC 2616 [RFC2616], Section 10. Per the Response, as described in RFC 2616 [RFC2616], Section 10. Per the
RFC, the request MAY be repeated with a suitable Authorization header RFC, the request MAY be repeated with a suitable Authorization header
field. Authorization information may be communicated in this manner, field. Authorization information may be communicated in this manner,
including a JSON Web Token [JWT]. including a JSON Web Token [JWT].
3.4. Other HTTP 1.1 Responses 3.3. Other HTTP 1.1 Responses
A SWD server MAY return other HTTP 1.1 responses, including 404 Not An SWD server MAY return other HTTP 1.1 responses, including 404 Not
Found, 400 Bad Request, and 403 Forbidden. SWD implementations MUST Found, 400 Bad Request, and 403 Forbidden. SWD implementations MUST
correctly handle these responses. correctly handle these responses.
4. IANA Considerations 4. IANA Considerations
This specification registers a well-known URI suffix value relative This specification registers a well-known URI suffix value relative
to "/.well-known/" in the IANA Well-Known URI registry defined in RFC to "/.well-known/" in the IANA Well-Known URI registry defined in RFC
5785 [RFC5785]: 5785 [RFC5785]:
URI suffix: simple-web-discovery URI suffix: simple-web-discovery
skipping to change at page 8, line 6 skipping to change at page 6, line 25
see the result of the query is outside the scope of this see the result of the query is outside the scope of this
specification. specification.
Because SWD responses can contain confidential information, the Because SWD responses can contain confidential information, the
requestor may need authorization to receive them. Standard HTTP requestor may need authorization to receive them. Standard HTTP
authorization mechanisms MAY be employed to request authorized authorization mechanisms MAY be employed to request authorized
access, including the use of an HTTP Authorization header field in access, including the use of an HTTP Authorization header field in
requests, which in turn, may contain a JSON Web Token [JWT], among requests, which in turn, may contain a JSON Web Token [JWT], among
other authorization data formats. other authorization data formats.
The ability to redirect an entire SWD server as defined in this When the SWD server for a domain is located at the
document is an obvious attack point. This is another reason why we "simple-web-discovery" subdomain, a TLS certificate will need to be
have mandated TLS, so as to be sure that the redirect can only be present for that subdomain.
received over a secure connection. We have also put in the upper
limit of 60 minutes for a redirect so as to provide a path for
regaining control over queries should a successful attack be launched
to return false redirects.
The "SWD_service_redirect" capability may cause unanticipated
failures in cases where a requestor may have permissions to discover
content at the original SWD endpoint but not the one redirected to,
or vice-versa.
6. References 6. References
6.1. Normative References 6.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the
Internet: Timestamps", RFC 3339, July 2002.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005. RFC 3986, January 2005.
[RFC4627] Crockford, D., "The application/json Media Type for [RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006. JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, August 2008. (TLS) Protocol Version 1.2", RFC 5246, August 2008.
skipping to change at page 9, line 9 skipping to change at page 7, line 18
[W3C.REC-html401-19991224] [W3C.REC-html401-19991224]
Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01 Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01
Specification", World Wide Web Consortium Specification", World Wide Web Consortium
Recommendation REC-html401-19991224, December 1999, Recommendation REC-html401-19991224, December 1999,
<http://www.w3.org/TR/1999/REC-html401-19991224>. <http://www.w3.org/TR/1999/REC-html401-19991224>.
6.2. Informative References 6.2. Informative References
[JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", July 2012. (JWT)", October 2012.
Appendix A. Document History Appendix A. Document History
[[ to be removed by the RFC editor before publication as an RFC ]] [[ to be removed by the RFC editor before publication as an RFC ]]
-04
o Specified that the SWD server for a domain may be located at the
"simple-web-discovery" subdomain of the domain and that SWD
clients must first try the endpoint at the domain and then the
endpoint at the subdomain.
o Removed the "SWD_service_redirect" response, since redirection can
be accomplished by pointing the "simple-web-discovery" subdomain
to a different location than the domain's host.
o Removed "mailto:" from examples in favor of bare e-mail address
syntax.
o Specified that SWD servers may also be run on ports other than
443, provided they use TLS on those ports.
-03 -03
o Changed "requests use the x-www-form-urlencoded format" to o Changed "requests use the x-www-form-urlencoded format" to
"requests use query parameters" and changed "an x-www-form- "requests use query parameters" and changed "an x-www-form-
urlencoded form" to "a form encoded using the application/ urlencoded form" to "a form encoded using the application/
x-www-form-urlencoded encoding algorithm", both at the suggestion x-www-form-urlencoded encoding algorithm", both at the suggestion
of Julian Reschke. x-www of Julian Reschke.
o Updated examples to use "urn:example:" URNs rather than o Updated examples to use "urn:example:" URNs rather than
"urn:example.org:" URNs, also at Julian's suggestion. "urn:example.org:" URNs, also at Julian's suggestion.
o Applied applicable editorial improvements from JOSE specs to SWD. o Applied applicable editorial improvements from JOSE specs to SWD.
o Updated references to related specifications. o Updated references to related specifications.
-02 -02
 End of changes. 31 change blocks. 
146 lines changed or deleted 91 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/