idnits 2.17.1 draft-jones-simple-web-discovery-01.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 248 has weird spacing: '... suffix simpl...' -- The document date (July 11, 2011) is 4673 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: January 12, 2012 July 11, 2011 7 Simple Web Discovery (SWD) 8 draft-jones-simple-web-discovery-01 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 January 12, 2012. 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. Simple Web Discovery Request . . . . . . . . . . . . . . . . . 3 58 3. Simple Web Discovery Responses . . . . . . . . . . . . . . . . 4 59 3.1. 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 Appendix A. Document History . . . . . . . . . . . . . . . . . . . 8 69 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 8 71 1. Introduction 73 Simple Web Discovery (SWD) defines a HTTPS GET based mechanism to 74 discover the location of a given type of service for a given 75 principal starting only with a domain name. SWD requests use the 76 x-www-form-urlencoded format to specify a URI for the principal and 77 another URI for the type of service being sought. If the request is 78 successful then the response, by default, is a JSON object containing 79 an array of URIs that point to where the principal has instances of 80 services of the requested type. 82 For example, let us say that a requester wants to discover where Joe 83 keeps his calendar. The requester could take Joe's e-mail address, 84 joe@example.com and take from it its domain to create a HTTPS GET 85 request of the following form: 87 GET /.well-known/simple-web-discovery?principal=mailto:joe@example.com&service=urn:adatum.com:calendar HTTP/1.1 88 Host: example.com 90 HTTP/1.1 200 O.K. 91 Content-Type: application/json 93 { 94 "locations": ["http://calendars.proseware.com/calendars/joseph"] 95 } 97 Note: The request-URI is left un-encoded in the above example for the 98 sake of readability in the above example. 100 2. Simple Web Discovery Request 102 Domains that support SWD requests MUST make available a SWD server 103 for their domain at the path .well-known/simple-web-discovery. The 104 syntax and semantics of ".well-known" are defined in RFC 5785 105 [RFC5785]. "simple-web-discovery" MUST point to a SWD server 106 compliant with this specification. 108 SWD servers MUST support receiving SWD requests via TLS 1.2 as 109 defined in RFC 5246 [RFC5246] and MAY support other transport layer 110 security mechanisms of equivalent security. SWD servers MUST reject 111 SWD requests sent over plain HTTP or any other transport that does 112 not provide both privacy and validation of the server's identity. 114 A SWD server is queried using a HTTPS GET request with the previously 115 specified path along with a query segment containing a x-www-form- 116 urlencoded form as defined in HTML 4.01 [W3C.REC-html401-19991224]. 117 The form MUST contain two name/value pairs that MUST appear exactly 118 once, "principal" and "service". Both name/value pairs MUST have 119 values that are set to URIs (as defined in RFC 3986 [RFC3986]). If 120 any of the previous requirements are not met in a SWD request, then 121 the request MUST be rejected with a 400 Bad Request. 123 The SWD request form MAY contain additional name/value pairs but if 124 those name/value pairs are not recognized by the SWD server then the 125 SWD server MUST ignore them for processing purposes. 127 The "principal" query component is a URI that identifies an entity. 128 The "service" query component is a URI that identifies a service 129 type. The semantics of the SWD query is "Please return the 130 location(s) of instances of the specified service type associated 131 with the specified principal". The definition of URIs used to 132 identify principals and services are outside the scope of this 133 specification. 135 3. Simple Web Discovery Responses 137 3.1. Response Containing One or More Locations 139 Unless another content-type is negotiated, a 200 O.K. response to a 140 SWD request that contains the information requested MUST return 141 content of type application/json as defined in RFC 4627 [RFC4627]. 142 The JSON response MUST contain a JSON object that contains a member 143 pair whose name is the string "locations" and whose value is an array 144 of strings that are each a URI pointing to a location where the 145 desired service type belonging to the specified principal can be 146 found. There are no semantics associated with the order in which the 147 URIs are listed in the array. 149 The JSON object MAY contain other members but a receiver of the 150 object MAY ignore any member pairs whose name it does not recognize. 152 3.2. Redirecting All Simple Web Discovery Requests 154 SWD requests by definition start off by being issued to the .well- 155 known/simple-web-discovery location. But locating a SWD server at a 156 root location can prove inconvenient. To enable service level 157 redirection a SWD server MAY return a 200 O.k. to an HTTPS request 158 with a content type of application/json (or whatever other content 159 type has been negotiated) that contains a JSON object that contains a 160 member pair whose name is the string "SWD_service_redirect" whose 161 value is a JSON object with a member pair whose name is "location" 162 and whose value is a string that encodes a URI. Optionally the JSON 163 object value of "SWD_service_redirect" MAY also contain a member 164 whose name is "expires" and whose value is a JSON number that encodes 165 an integer. 167 A SWD compliant client MUST support the "SWD_service_redirect" 168 response. 170 The JSON objects MAY contain other members but a receiver of the 171 objects MAY ignore any pairs whose name it does not recognize. 173 The "location" member identifies the URI that the caller MUST 174 redirect all SWD requests for that domain to until the "expires" time 175 is met. SWD requests for the redirected domain MUST be constructed 176 by taking the URI returned in the "location" and using it as the base 177 URI to which the SWD form arguments are then added as query 178 parameters. The location URI MUST NOT include a query component. 180 GET /.well-known/simple-web-discovery?principal=mailto:joe@example.com&service=urn:adatum.com:calendar HTTP/1.1 181 Host: example.com 183 HTTP/1.1 200 O.K. 184 Content-Type: application/json 186 { 187 "SWD_service_redirect": 188 { 189 "location": "https://swd.proseware.com/swd_server", 190 "expires": 1300752001 191 } 192 } 194 GET /swd_server?principal=mailto:joe@example.com&service=urn:adatum.com:calendar HTTP/1.1 195 Host: swd.proseware.com 197 HTTP/1.1 200 O.K. 198 Content-Type: application/json 200 { 201 "locations": ["http://calendars.proseware.com/calendars/joseph"] 202 } 204 Note: The request-URIs are left un-encoded in the above example for 205 the sake of readability in the above example. 207 The "location" URI MUST be an HTTPS URL. 209 The optional "expires" member identifies the point in time at which 210 the caller MUST NOT redirect its SWD requests for that domain to the 211 previously obtained "location" and MUST instead return to the .well- 212 known/simple-web-discovery location. The value of the "expires" 213 member MUST encode the number of seconds from 1970-01-01T0:0:0Z as 214 measured in UTC until the desired date/time. See RFC 3339 [RFC3339] 215 for details regarding date/times in general and UTC in particular. 216 If the "expires" value is in the past or if the value is more than 217 one hour in the future then the response MUST be treated as if it 218 didn't contain an "expires" value. 220 If the "expires" value is omitted or if its value is incorrect then 221 the "expires" value MUST be treated as having a value of exactly one 222 hour into the future. 224 If a JSON response is received that contains both a member pair with 225 the name "SWD_service_redirect" and a member pair with the name 226 "locations" as children of the object root then the 227 "SWD_service_redirect" member pair MUST be ignored. 229 3.3. 401 Unauthorized Response 231 A SWD server MAY respond to a request with a 401 Unauthorized 232 Response, as described in RFC 2616 [RFC2616], Section 10. Per the 233 RFC, the request MAY be repeated with a suitable Authorization header 234 field. Authorization information may be communicated in this manner, 235 including a JSON Web Token [JWT]. 237 3.4. Other HTTP 1.1 Responses 239 A SWD server MAY return other HTTP 1.1 responses, including 404 Not 240 Found, 400 Bad Request, and 403 Forbidden. SWD implementations MUST 241 correctly handle these responses. 243 4. IANA Considerations 245 Per RFC 5785 [RFC5785], the following registration template is 246 offered: 248 URI suffix simple-web-discovery 250 Change controller IETF 252 Specification document This RFC 254 5. Security Considerations 256 SWD responses can contain confidential information. Therefore a, 257 general approach is used to require TLS in all cases. But TLS can 258 only provide for privacy and server validation, it cannot validate 259 that the requester is authorized to see the results of a query. The 260 exact mechanism used to determine if the requester is authorized to 261 see the result of the query is outside the scope of this 262 specification. 264 Because SWD responses can contain confidential information, the 265 requestor may need authorization to receive them. Standard HTTP 266 authorization mechanisms MAY be employed to request authorized 267 access, including the use of an HTTP Authorization header field in 268 requests, which in turn, may contain a JSON Web Token [JWT], among 269 other authorization data formats. 271 The ability to redirect an entire SWD server as defined in this 272 document is an obvious attack point. This is another reason why we 273 have mandated TLS, so as to be sure that the redirect can only be 274 received over a secure connection. We have also put in the upper 275 limit of 60 minutes for a redirect so as to provide a path for 276 regaining control over queries should a successful attack be launched 277 to return false redirects. 279 The "SWD_service_redirect" capability may cause unanticipated 280 failures in cases where a requestor may have permissions to discover 281 content at the original SWD endpoint but not the one redirected to, 282 or vice-versa. 284 6. References 286 6.1. Normative References 288 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 289 Requirement Levels", BCP 14, RFC 2119, March 1997. 291 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 292 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 293 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 295 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 296 Internet: Timestamps", RFC 3339, July 2002. 298 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 299 Resource Identifier (URI): Generic Syntax", STD 66, 300 RFC 3986, January 2005. 302 [RFC4627] Crockford, D., "The application/json Media Type for 303 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 305 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 306 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 308 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 309 Uniform Resource Identifiers (URIs)", RFC 5785, 310 April 2010. 312 [W3C.REC-html401-19991224] 313 Jacobs, I., Hors, A., and D. Raggett, "HTML 4.01 314 Specification", World Wide Web Consortium 315 Recommendation REC-html401-19991224, December 1999, 316 . 318 6.2. Informative References 320 [JWT] Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, 321 J., Sakimura, N., and P. Tarjan, "JSON Web Token (JWT)", 322 July 2011. 324 Appendix A. Document History 326 -01 328 o Refresh draft before expiration of -00. No normative changes. 330 -00 332 o Initial version. 334 Authors' Addresses 336 Michael B. Jones 337 Microsoft 339 Email: mbj@microsoft.com 340 URI: http://self-issued.info/ 342 Yaron Y. Goland 343 Microsoft 345 Email: yarong@microsoft.com