idnits 2.17.1 draft-jones-simple-web-discovery-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 3 instances of too long lines in the document, the longest one being 39 characters in excess of 72. == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 246 has weird spacing: '... suffix simpl...' -- The document date (January 11, 2011) is 4826 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) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) Summary: 5 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Jones 3 Internet-Draft Y. Goland 4 Intended status: Standards Track Microsoft 5 Expires: July 15, 2011 January 11, 2011 7 Simple Web Discovery (SWD) 8 draft-jones-simple-web-discovery-00 10 Abstract 12 Simple Web Discovery (SWD) defines a HTTPS GET based mechanism to 13 discover the location of a given type of service for a given 14 principal starting only with a domain name. 16 Requirements Language 18 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 19 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 20 document are to be interpreted as described in RFC 2119 [RFC2119]. 22 Status of this Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on July 15, 2011. 39 Copyright Notice 41 Copyright (c) 2011 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. A Simple Web Discovery Request . . . . . . . . . . . . . . . . 3 58 3. Simple Web Discovery Responses . . . . . . . . . . . . . . . . 4 59 3.1. A response containing one or more locations . . . . . . . . 4 60 3.2. Redirecting all Simple Web Discovery Requests . . . . . . . 4 61 3.3. 401 Unauthorized Response . . . . . . . . . . . . . . . . . 6 62 3.4. Other HTTP 1.1 Responses . . . . . . . . . . . . . . . . . 6 63 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 6 64 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 6 65 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7 66 6.1. Normative References . . . . . . . . . . . . . . . . . . . 7 67 6.2. Informative References . . . . . . . . . . . . . . . . . . 8 68 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 8 70 1. Introduction 72 Simple Web Discovery (SWD) defines a HTTPS GET based mechanism to 73 discover the location of a given type of service for a given 74 principal starting only with a domain name. SWD requests use the 75 x-www-form-urlencoded format to specify a URI for the principal and 76 another URI for the type of service being sought. If the request is 77 successful then the response, by default, is a JSON object containing 78 an array of URIs that point to where the principal has instances of 79 services of the requested type. 81 For example, let us say that a requester wants to discover where Joe 82 keeps his calendar. The requester could take Joe's e-mail address, 83 joe@example.com and take from it its domain to create a HTTPS GET 84 request of the following form: 86 GET /.well-known/simple-web-discovery?principal=mailto:joe@example.com&service=urn:adatum.com:calendar HTTP/1.1 87 Host: example.com 89 HTTP/1.1 200 O.K. 90 Content-Type: application/json 92 { 93 "locations":["http://calendars.proseware.com/calendars/joseph"] 94 } 96 Note: The request-URI is left un-encoded in the above example for the 97 sake of readability in the above example. 99 2. A Simple Web Discovery Request 101 Domains that support SWD requests MUST make available a SWD server 102 for their domain at the path .well-known/simple-web-discovery. The 103 syntax and semantics of ".well-known" are defined in RFC 5785 104 [RFC5785]. "simple-web-discovery" MUST point to a SWD server 105 compliant with this specification. 107 SWD servers MUST support receiving SWD requests via TLS 1.2 as 108 defined in RFC 5246 [RFC5246] and MAY support other transport layer 109 security mechanisms of equivalent security. SWD servers MUST reject 110 SWD requests sent over plain HTTP or any other transport that does 111 not provide both privacy and validation of the server's identity. 113 A SWD server is queried using a HTTPS GET request with the previously 114 specified path along with a query segment containing a x-www-form- 115 urlencoded form as defined in HTML 4.01 [W3C.REC-html401-19991224]. 116 The form MUST contain two name/value pairs that MUST appear exactly 117 once, principal and service. Both name/value pairs MUST have values 118 that are set to URIs (as defined in RFC 3986 [RFC3986] . If any of 119 the previous requirements are not met in a SWD request then the 120 request MUST be rejected with a 400 Bad Request. 122 The SWD request form MAY contain additional name/value pairs but if 123 those name/value pairs are not recognized by the SWD server then the 124 SWD server MUST ignore them for processing purposes. 126 The principal query component is a URI that identifies an entity. 127 The service query component is a URI that identifies a service type. 128 The semantics of the SWD query is "Please return the location(s) of 129 instances of the specified service type associated with the specified 130 principal". The definition of URIs used to identify principals and 131 services are outside the scope of this specification. 133 3. Simple Web Discovery Responses 135 3.1. A response containing one or more locations 137 Unless another content-type is negotiated, a 200 O.K. response to a 138 SWD request that contains the information requested MUST return 139 content of type application/json as defined in RFC 4627 [RFC4627]. 140 The JSON response MUST contain a JSON object that contains a member 141 pair whose name is the string "locations" and whose value is an array 142 of strings that are each a URI pointing to a location where the 143 desired service type belonging to the specified principal can be 144 found. There are no semantics associated with the order in which the 145 URIs are listed in the array. 147 The JSON object MAY contain other members but a receiver of the 148 object MAY ignore any member pairs whose name it does not recognize. 150 3.2. Redirecting all Simple Web Discovery Requests 152 SWD requests by definition start off by being issued to the .well- 153 known/simple-web-discovery location. But locating a SWD server at a 154 root location can prove inconvenient. To enable service level 155 redirection a SWD server MAY return a 200 O.k. to a HTTPS request 156 with a content type of application/json (or whatever other content 157 type has been negotiated) that contains a JSON object that contains a 158 member pair whose name is the string "SWD_service_redirect" whose 159 value is a JSON object with a member pair whose name is "location" 160 and whose value is a string that encodes a URI. Optionally the JSON 161 object value of "SWD_service_redirect" MAY also contain a member 162 whose name is "expires" and whose value is a JSON number that encodes 163 an integer. 165 A SWC compliant client MUST support the SWD_service_redirect 166 response. 168 The JSON objects MAY contain other members but a receiver of the 169 objects MAY ignore any pairs whose name it does not recognize. 171 The location member identifies the URI that the caller MUST redirect 172 all SWD requests for that domain to until the expires time is met. 173 SWD requests for the redirected domain MUST be constructed by taking 174 the URI returned in the location and using it as the base URI to 175 which the SWD form arguments are then added as query parameters. The 176 location URI MUST NOT include a query component. 178 GET /.well-known/simple-web-discovery?principal=mailto:joe@example.com&service=urn:adatum.com:calendar HTTP/1.1 179 Host: example.com 181 HTTP/1.1 200 O.K. 182 Content-Type: application/json 184 { 185 "SWD_service_redirect": 186 { 187 "location":"https://swd.proseware.com/swd_server", 188 "expires": 1300752001 189 } 190 } 192 GET /swd_server?principal=mailto:joe@example.com&service=urn:adatum.com:calendar HTTP/1.1 193 Host: swd.proseware.com 195 HTTP/1.1 200 O.K. 196 Content-Type: application/json 198 { 199 "locations":["http://calendars.proseware.com/calendars/joseph"] 200 } 202 Note: The request-URIs are left un-encoded in the above example for 203 the sake of readability in the above example. 205 The location URI MUST be a HTTPS URL. 207 The optional expires member identifies the point in time at which the 208 caller MUST NOT redirect its SWD requests for that domain to the 209 previously obtained location and MUST instead return to the .well- 210 known/simple-web-discovery location. The value of the expires member 211 MUST encode the number of seconds from 1970-01-01T0:0:0Z as measured 212 in UTC until the desired date/time. See RFC 3339 [RFC3339] for 213 details regarding date/times in general and UTC in particular. If 214 the expires value is in the past or if the value is more than one 215 hour in the future then the response MUST be treated as if it didn't 216 contain an expires value. 218 If the expires value is omitted or if its value is incorrect then the 219 expires value MUST be treated as having a value of exactly one hour 220 into the future. 222 If a JSON response is received that contains both a member pair with 223 the name "SWD_service_redirect" and a member pair with the name 224 "locations" as children of the object root then the 225 "SWD_service_redirect" member pair MUST be ignored. 227 3.3. 401 Unauthorized Response 229 A SWD server MAY respond to a request with a 401 Unauthorized 230 Response, as described in RFC 2616 [RFC2616], Section 10. Per the 231 RFC, the request MAY be repeated with a suitable Authorization header 232 field. Authorization information may be communicated in this manner, 233 including a JSON Web Token [JWT]. 235 3.4. Other HTTP 1.1 Responses 237 A SWD server MAY return other HTTP 1.1 responses, including 404 Not 238 Found, 400 Bad Request, and 403 Forbidden. SWD implementations MUST 239 correctly handle these responses. 241 4. IANA Considerations 243 Per RFC 5785 [RFC5785] the following registration template is 244 offered: 246 URI suffix simple-web-discovery 248 Change controller IETF 250 Specification document This RFC 252 5. Security Considerations 254 SWD responses can contain confidential information. Therefore a, 255 general approach is used to require TLS in all cases. But TLS can 256 only provide for privacy and server validation, it cannot validate 257 that the requester is authorized to see the results of a query. The 258 exact mechanism used to determine if the requester is authorized to 259 see the result of the query is outside the scope of this 260 specification. 262 Because SWD responses can contain confidential information, the 263 requestor may need authorization to receive them. Standard HTTP 264 authorization mechanisms MAY be employed to request authorized 265 access, including the use of an HTTP Authorization header field in 266 requests, which in turn, may contain a JSON Web Token [JWT], among 267 other authorization data formats. 269 The ability to redirect an entire SWD server as defined in this 270 document is an obvious attack point. This is another reason why we 271 have mandated TLS, so as to be sure that the redirect can only be 272 received over a secure connection. We have also put in the upper 273 limit of 60 minutes for a redirect so as to provide a path for 274 regaining control over queries should a successful attack be launched 275 to return false redirects. 277 The SWD_service_redirect capability may cause unanticipated failures 278 in cases where a requestor may have permissions to discover content 279 at the original SWD endpoint but not the one redirected to, or vice- 280 versa. 282 6. References 284 6.1. Normative References 286 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 287 Requirement Levels", BCP 14, RFC 2119, March 1997. 289 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 290 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 291 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 293 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 294 Internet: Timestamps", RFC 3339, July 2002. 296 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 297 Resource Identifier (URI): Generic Syntax", STD 66, 298 RFC 3986, January 2005. 300 [RFC4627] Crockford, D., "The application/json Media Type for 301 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 303 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 304 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 306 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 307 Uniform Resource Identifiers (URIs)", RFC 5785, 308 April 2010. 310 [W3C.REC-html401-19991224] 311 Hors, A., Jacobs, I., and D. Raggett, "HTML 4.01 312 Specification", World Wide Web Consortium 313 Recommendation REC-html401-19991224, December 1999, 314 . 316 6.2. Informative References 318 [JWT] Jones (editor), M., Balfanz, D., Bradley, J., Goland, Y., 319 Panzer, J., and N. Sakimura, "JSON Web Token (JWT)", 320 October 2010. 322 Authors' Addresses 324 Michael B. Jones 325 Microsoft 327 Email: mbj@microsoft.com 328 URI: http://self-issued.info/ 330 Yaron Y. Goland 331 Microsoft 333 Email: yarong@microsoft.com