idnits 2.17.1 draft-jones-simple-web-discovery-03.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 6, 2012) is 4313 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: 4 errors (**), 0 flaws (~~), 1 warning (==), 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: January 7, 2013 July 6, 2012 7 Simple Web Discovery (SWD) 8 draft-jones-simple-web-discovery-03 10 Abstract 12 Simple Web Discovery (SWD) defines an 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 Status of this Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on January 7, 2013. 33 Copyright Notice 35 Copyright (c) 2012 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 51 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 52 2. Simple Web Discovery Request . . . . . . . . . . . . . . . . . 3 53 3. Simple Web Discovery Responses . . . . . . . . . . . . . . . . 4 54 3.1. Response Containing One or More Locations . . . . . . . . 4 55 3.2. Redirecting All Simple Web Discovery Requests . . . . . . 5 56 3.3. 401 Unauthorized Response . . . . . . . . . . . . . . . . 7 57 3.4. Other HTTP 1.1 Responses . . . . . . . . . . . . . . . . . 7 58 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 59 5. Security Considerations . . . . . . . . . . . . . . . . . . . 7 60 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 61 6.1. Normative References . . . . . . . . . . . . . . . . . . . 8 62 6.2. Informative References . . . . . . . . . . . . . . . . . . 9 63 Appendix A. Document History . . . . . . . . . . . . . . . . . . 9 64 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10 66 1. Introduction 68 Simple Web Discovery (SWD) defines an HTTPS GET based mechanism to 69 discover the location of a given type of service for a given 70 principal starting only with a domain name. SWD requests use query 71 parameters to specify a URI for the principal and another URI for the 72 type of service being sought. If the request is successful then the 73 response, by default, is a JavaScript Object Notation (JSON) 74 [RFC4627] object containing an array of URIs that point to where the 75 principal has instances of services of the requested type. 77 For example, let us say that a requester wants to discover where Joe 78 keeps his calendar. The requester could take Joe's e-mail address, 79 "joe@example.com", and use its domain to create an HTTPS GET request 80 of the following form (with long lines broken for display purposes 81 only): 82 GET /.well-known/simple-web-discovery 83 ?principal=mailto:joe@example.com 84 &service=urn:example:service:calendar HTTP/1.1 85 Host: example.com 87 HTTP/1.1 200 OK 88 Content-Type: application/json 90 { 91 "locations": ["https://calendars.example.net/calendars/joseph"] 92 } 94 Note: The request-URI is left unencoded in the above example for the 95 sake of readability. The query parameters above would actually be 96 encoded as "?principal=mailto%3Ajoe%40example.com&service=urn%3Aexamp 97 le%3Aservice%3Acalendar". 99 1.1. Notational Conventions 101 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 102 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 103 document are to be interpreted as described in Key words for use in 104 RFCs to Indicate Requirement Levels [RFC2119]. 106 2. Simple Web Discovery Request 108 Domains that support SWD requests MUST make available a SWD server 109 for their domain at the path "/.well-known/simple-web-discovery". 110 The syntax and semantics of "/.well-known" are defined in RFC 5785 111 [RFC5785]. "simple-web-discovery" MUST point to a SWD server 112 compliant with this specification. 114 SWD servers MUST support receiving SWD requests via TLS 1.2 [RFC5246] 115 and MAY support other transport layer security mechanisms of 116 equivalent security. SWD servers MUST reject SWD requests sent over 117 plain HTTP or any other transport that does not provide both privacy 118 and validation of the server's identity. 120 A SWD server is queried using an HTTPS GET request with the 121 previously specified path along with a query segment containing a 122 form encoded using the application/x-www-form-urlencoded encoding 123 algorithm as defined in HTML 4.01 [W3C.REC-html401-19991224]. The 124 form MUST contain two name/value pairs that MUST appear exactly once, 125 "principal" and "service". Both name/value pairs MUST have values 126 that are set to URIs [RFC3986]. If any of the previous requirements 127 are not met in a SWD request, then the request MUST be rejected with 128 a 400 Bad Request. 130 The SWD request form MAY contain additional name/value pairs but if 131 those name/value pairs are not recognized by the SWD server then the 132 SWD server MUST ignore them for processing purposes. 134 The "principal" query component is a URI that identifies an entity. 135 The "service" query component is a URI that identifies a service 136 type. The semantics of the SWD query is "Please return the 137 location(s) of instances of the specified service type associated 138 with the specified principal". The definition of URIs used to 139 identify principals and services are outside the scope of this 140 specification. 142 3. Simple Web Discovery Responses 144 3.1. Response Containing One or More Locations 146 Unless another content-type is negotiated, a 200 OK response to a SWD 147 request that contains the information requested MUST return content 148 of type application/json [RFC4627]. The JSON response MUST contain a 149 JSON object that contains a member pair whose name is the string 150 "locations" and whose value is an array of strings that are each a 151 URI pointing to a location where the desired service type belonging 152 to the specified principal can be found. There are no semantics 153 associated with the order in which the URIs are listed in the array. 155 The JSON object MAY contain other members but a receiver of the 156 object MAY ignore any member pairs whose name it does not recognize. 158 3.2. Redirecting All Simple Web Discovery Requests 160 SWD requests by definition start off by being issued to the 161 "/.well-known/simple-web-discovery" location. But locating a SWD 162 server at a root location can prove inconvenient. To enable service 163 level redirection, a SWD server MAY return a 200 OK to an HTTPS 164 request with a content type of application/json (or whatever other 165 content type has been negotiated) that contains a JSON object that 166 contains a member pair whose name is the string 167 "SWD_service_redirect" whose value is a JSON object with a member 168 pair whose name is "location" and whose value is a string that 169 encodes a URI. Optionally, the JSON object value of 170 "SWD_service_redirect" MAY also contain a member whose name is 171 "expires" and whose value is a JSON number that encodes an integer. 173 A SWD compliant client MUST support the "SWD_service_redirect" 174 response. 176 The JSON objects MAY contain other members but a receiver of the 177 objects MAY ignore any pairs whose name it does not recognize. 179 The "location" member identifies the URI that the caller MUST 180 redirect all SWD requests for that domain to until the "expires" time 181 has passed. SWD requests for the redirected domain MUST be 182 constructed by taking the URI returned in the "location" and using it 183 as the base URI to which the SWD form arguments are then added as 184 query parameters. The location URI MUST NOT include a query 185 component. 187 The following is an example of redirect messages (with long lines 188 broken for display purposes only): 190 GET /.well-known/simple-web-discovery 191 ?principal=mailto:joe@example.com 192 &service=urn:example:service:calendar HTTP/1.1 193 Host: example.com 195 HTTP/1.1 200 OK 196 Content-Type: application/json 198 { 199 "SWD_service_redirect": 200 { 201 "location": "https://swd.example.com/swd_server", 202 "expires": 1300752001 203 } 204 } 206 GET /swd_server 207 ?principal=mailto:joe@example.com 208 &service=urn:example:service:calendar HTTP/1.1 209 Host: swd.example.com 211 HTTP/1.1 200 OK 212 Content-Type: application/json 214 { 215 "locations": ["https://calendars.example.net/calendars/joseph"] 216 } 218 Note: The request-URIs are left unencoded in the above example for 219 the sake of readability. 221 The "location" URI MUST be an HTTPS URL. 223 The optional "expires" member identifies the point in time at which 224 the caller MUST NOT redirect its SWD requests for that domain to the 225 previously obtained "location" and MUST instead return to the 226 "/.well-known/simple-web-discovery" location. The value of the 227 "expires" member MUST encode the number of seconds from 1970-01- 228 01T0:0:0Z as measured in UTC until the desired date/time. See RFC 229 3339 [RFC3339] for details regarding date/times in general and UTC in 230 particular. If the "expires" value is in the past or if the value is 231 more than one hour in the future then the response MUST be treated as 232 if it didn't contain an "expires" value. 234 If the "expires" value is omitted or if its value is incorrect then 235 the "expires" value MUST be treated as having a value of exactly one 236 hour into the future. 238 If a JSON response is received that contains both a member pair with 239 the name "SWD_service_redirect" and a member pair with the name 240 "locations" as children of the object root then the 241 "SWD_service_redirect" member pair MUST be ignored. 243 3.3. 401 Unauthorized Response 245 A SWD server MAY respond to a request with a 401 Unauthorized 246 Response, as described in RFC 2616 [RFC2616], Section 10. Per the 247 RFC, the request MAY be repeated with a suitable Authorization header 248 field. Authorization information may be communicated in this manner, 249 including a JSON Web Token [JWT]. 251 3.4. Other HTTP 1.1 Responses 253 A SWD server MAY return other HTTP 1.1 responses, including 404 Not 254 Found, 400 Bad Request, and 403 Forbidden. SWD implementations MUST 255 correctly handle these responses. 257 4. IANA Considerations 259 This specification registers a well-known URI suffix value relative 260 to "/.well-known/" in the IANA Well-Known URI registry defined in RFC 261 5785 [RFC5785]: 263 URI suffix: simple-web-discovery 265 Change controller: IETF 267 Specification document: [[ this document ]] 269 5. Security Considerations 271 SWD responses can contain confidential information. Therefore a, 272 general approach is used to require TLS in all cases. But TLS can 273 only provide for privacy and server validation, it cannot validate 274 that the requester is authorized to see the results of a query. The 275 exact mechanism used to determine if the requester is authorized to 276 see the result of the query is outside the scope of this 277 specification. 279 Because SWD responses can contain confidential information, the 280 requestor may need authorization to receive them. Standard HTTP 281 authorization mechanisms MAY be employed to request authorized 282 access, including the use of an HTTP Authorization header field in 283 requests, which in turn, may contain a JSON Web Token [JWT], among 284 other authorization data formats. 286 The ability to redirect an entire SWD server as defined in this 287 document is an obvious attack point. This is another reason why we 288 have mandated TLS, so as to be sure that the redirect can only be 289 received over a secure connection. We have also put in the upper 290 limit of 60 minutes for a redirect so as to provide a path for 291 regaining control over queries should a successful attack be launched 292 to return false redirects. 294 The "SWD_service_redirect" capability may cause unanticipated 295 failures in cases where a requestor may have permissions to discover 296 content at the original SWD endpoint but not the one redirected to, 297 or vice-versa. 299 6. References 301 6.1. Normative References 303 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 304 Requirement Levels", BCP 14, RFC 2119, March 1997. 306 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 307 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 308 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 310 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 311 Internet: Timestamps", RFC 3339, July 2002. 313 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 314 Resource Identifier (URI): Generic Syntax", STD 66, 315 RFC 3986, January 2005. 317 [RFC4627] Crockford, D., "The application/json Media Type for 318 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 320 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 321 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 323 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 324 Uniform Resource Identifiers (URIs)", RFC 5785, 325 April 2010. 327 [W3C.REC-html401-19991224] 328 Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01 329 Specification", World Wide Web Consortium 330 Recommendation REC-html401-19991224, December 1999, 331 . 333 6.2. Informative References 335 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 336 (JWT)", July 2012. 338 Appendix A. Document History 340 [[ to be removed by the RFC editor before publication as an RFC ]] 342 -03 344 o Changed "requests use the x-www-form-urlencoded format" to 345 "requests use query parameters" and changed "an x-www-form- 346 urlencoded form" to "a form encoded using the application/ 347 x-www-form-urlencoded encoding algorithm", both at the suggestion 348 of Julian Reschke. x-www 350 o Updated examples to use "urn:example:" URNs rather than 351 "urn:example.org:" URNs, also at Julian's suggestion. 353 o Applied applicable editorial improvements from JOSE specs to SWD. 355 o Updated references to related specifications. 357 -02 359 o Update examples to use example.{com,net,org} domain names. 361 o Provide encoded representation of the request-URI query parameters 362 for the first example request. 364 o Changed "200 O.K." to "200 OK". 366 o Respect line length restrictions in examples. 368 o No normative changes. 370 -01 372 o Refresh draft before expiration of -00. No normative changes. 374 -00 376 o Initial version. 378 Authors' Addresses 380 Michael B. Jones 381 Microsoft 383 Email: mbj@microsoft.com 384 URI: http://self-issued.info/ 386 Yaron Y. Goland 387 Microsoft 389 Email: yarong@microsoft.com