idnits 2.17.1 draft-jones-simple-web-discovery-04.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 (November 5, 2012) is 4189 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: May 9, 2013 November 5, 2012 7 Simple Web Discovery (SWD) 8 draft-jones-simple-web-discovery-04 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 May 9, 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 2.1. "simple-web-discovery" Subdomain . . . . . . . . . . . . . 4 54 3. Simple Web Discovery Responses . . . . . . . . . . . . . . . . 5 55 3.1. Response Containing One or More Locations . . . . . . . . . 5 56 3.2. 401 Unauthorized Response . . . . . . . . . . . . . . . . . 5 57 3.3. Other HTTP 1.1 Responses . . . . . . . . . . . . . . . . . 5 58 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 5 59 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 6 60 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 6 61 6.1. Normative References . . . . . . . . . . . . . . . . . . . 6 62 6.2. Informative References . . . . . . . . . . . . . . . . . . 7 63 Appendix A. Document History . . . . . . . . . . . . . . . . . . . 7 64 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 8 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): 83 GET /.well-known/simple-web-discovery 84 ?principal=joe@example.com 85 &service=urn:example:service:calendar HTTP/1.1 86 Host: example.com 88 HTTP/1.1 200 OK 89 Content-Type: application/json 91 { 92 "locations": ["https://calendars.example.net/calendars/joseph"] 93 } 95 Note: The request-URI is left unencoded in the above example for the 96 sake of readability. The query parameters above would actually be 97 encoded as "?principal=joe%40example.com&service=urn%3Aexample%3Aserv 98 ice%3Acalendar". 100 1.1. Notational Conventions 102 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 103 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 104 document are to be interpreted as described in Key words for use in 105 RFCs to Indicate Requirement Levels [RFC2119]. 107 2. Simple Web Discovery Request 109 Domains that support SWD requests SHOULD make an SWD server available 110 for their domain at the path "/.well-known/simple-web-discovery". 111 The syntax and semantics of "/.well-known" are defined in RFC 5785 112 [RFC5785]. "/.well-known/simple-web-discovery" MUST point to an SWD 113 server compliant with this specification. 115 SWD servers MUST support receiving SWD requests via TLS 1.2 [RFC5246] 116 and MAY support other transport layer security mechanisms of 117 equivalent security. SWD servers MUST reject SWD requests sent over 118 plain HTTP or any other transport that does not provide both privacy 119 and validation of the server's identity. 121 An SWD server is queried using an HTTPS GET request with the 122 previously specified path along with a query segment containing a 123 form encoded using the application/x-www-form-urlencoded encoding 124 algorithm as defined in HTML 4.01 [W3C.REC-html401-19991224]. The 125 form MUST contain two name/value pairs that MUST appear exactly once, 126 "principal" and "service". Both name/value pairs MUST have values 127 that are set to URIs [RFC3986]. If any of the previous requirements 128 are not met in an SWD request, then the request MUST be rejected with 129 a 400 Bad Request. 131 The SWD request form MAY contain additional name/value pairs but if 132 those name/value pairs are not recognized by the SWD server then the 133 SWD server MUST ignore them for processing purposes. 135 The "principal" query component is a URI that identifies an entity. 136 The "service" query component is a URI that identifies a service 137 type. The semantics of the SWD query is "Please return the 138 location(s) of instances of the specified service type associated 139 with the specified principal". The definition of URIs used to 140 identify principals and services are outside the scope of this 141 specification. 143 SWD servers MAY also be located on ports other than 443 (the default 144 HTTPS port), provided they use TLS on those ports. The means by 145 which an SWD client would know to use any alternative ports are out 146 of scope for this specification. 148 2.1. "simple-web-discovery" Subdomain 150 It may be difficult or impossible for some domains wanting to support 151 SWD requests to make an SWD server available for their domain at the 152 path "/.well-known/simple-web-discovery". For instance, in the case 153 of hosted domains, no web server may be running on the domain host at 154 all. 156 For that reason, SWD servers for a domain MAY be located on a 157 specific subdomain of that domain: "simple-web-discovery". For 158 example, the SWD server for the domain "example.com" MAY be located 159 at the URI "https://simple-web-discovery.example.com/.well-known/simp 160 le-web-discovery". 162 SWD clients MUST first attempt to make an SWD request to the domain's 163 "/.well-known/simple-web-discovery" endpoint, and then if that fails, 164 they MUST then attempt to make the request to the SWD endpoint at the 165 "simple-web-discovery" subdomain for the domain. 167 3. Simple Web Discovery Responses 169 3.1. Response Containing One or More Locations 171 A 200 OK response to an SWD request that contains the information 172 requested MUST return content of type application/json [RFC4627]. 173 The JSON response MUST contain a JSON object that contains a member 174 pair whose name is the string "locations" and whose value is an array 175 of strings that are each a URI pointing to a location where the 176 desired service type belonging to the specified principal can be 177 found. There are no semantics associated with the order in which the 178 URIs are listed in the array. 180 The JSON object MAY contain other members but a receiver of the 181 object MAY ignore any member pairs whose name it does not recognize. 183 3.2. 401 Unauthorized Response 185 An SWD server MAY respond to a request with a 401 Unauthorized 186 Response, as described in RFC 2616 [RFC2616], Section 10. Per the 187 RFC, the request MAY be repeated with a suitable Authorization header 188 field. Authorization information may be communicated in this manner, 189 including a JSON Web Token [JWT]. 191 3.3. Other HTTP 1.1 Responses 193 An SWD server MAY return other HTTP 1.1 responses, including 404 Not 194 Found, 400 Bad Request, and 403 Forbidden. SWD implementations MUST 195 correctly handle these responses. 197 4. IANA Considerations 199 This specification registers a well-known URI suffix value relative 200 to "/.well-known/" in the IANA Well-Known URI registry defined in RFC 201 5785 [RFC5785]: 203 URI suffix: simple-web-discovery 204 Change controller: IETF 206 Specification document: [[ this document ]] 208 5. Security Considerations 210 SWD responses can contain confidential information. Therefore a, 211 general approach is used to require TLS in all cases. But TLS can 212 only provide for privacy and server validation, it cannot validate 213 that the requester is authorized to see the results of a query. The 214 exact mechanism used to determine if the requester is authorized to 215 see the result of the query is outside the scope of this 216 specification. 218 Because SWD responses can contain confidential information, the 219 requestor may need authorization to receive them. Standard HTTP 220 authorization mechanisms MAY be employed to request authorized 221 access, including the use of an HTTP Authorization header field in 222 requests, which in turn, may contain a JSON Web Token [JWT], among 223 other authorization data formats. 225 When the SWD server for a domain is located at the 226 "simple-web-discovery" subdomain, a TLS certificate will need to be 227 present for that subdomain. 229 6. References 231 6.1. Normative References 233 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 234 Requirement Levels", BCP 14, RFC 2119, March 1997. 236 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 237 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 238 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 240 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 241 Resource Identifier (URI): Generic Syntax", STD 66, 242 RFC 3986, January 2005. 244 [RFC4627] Crockford, D., "The application/json Media Type for 245 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 247 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 248 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 250 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 251 Uniform Resource Identifiers (URIs)", RFC 5785, 252 April 2010. 254 [W3C.REC-html401-19991224] 255 Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01 256 Specification", World Wide Web Consortium 257 Recommendation REC-html401-19991224, December 1999, 258 . 260 6.2. Informative References 262 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 263 (JWT)", October 2012. 265 Appendix A. Document History 267 [[ to be removed by the RFC editor before publication as an RFC ]] 269 -04 271 o Specified that the SWD server for a domain may be located at the 272 "simple-web-discovery" subdomain of the domain and that SWD 273 clients must first try the endpoint at the domain and then the 274 endpoint at the subdomain. 276 o Removed the "SWD_service_redirect" response, since redirection can 277 be accomplished by pointing the "simple-web-discovery" subdomain 278 to a different location than the domain's host. 280 o Removed "mailto:" from examples in favor of bare e-mail address 281 syntax. 283 o Specified that SWD servers may also be run on ports other than 284 443, provided they use TLS on those ports. 286 -03 288 o Changed "requests use the x-www-form-urlencoded format" to 289 "requests use query parameters" and changed "an x-www-form- 290 urlencoded form" to "a form encoded using the application/ 291 x-www-form-urlencoded encoding algorithm", both at the suggestion 292 of Julian Reschke. 294 o Updated examples to use "urn:example:" URNs rather than 295 "urn:example.org:" URNs, also at Julian's suggestion. 297 o Applied applicable editorial improvements from JOSE specs to SWD. 299 o Updated references to related specifications. 301 -02 303 o Update examples to use example.{com,net,org} domain names. 305 o Provide encoded representation of the request-URI query parameters 306 for the first example request. 308 o Changed "200 O.K." to "200 OK". 310 o Respect line length restrictions in examples. 312 o No normative changes. 314 -01 316 o Refresh draft before expiration of -00. No normative changes. 318 -00 320 o Initial version. 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