idnits 2.17.1 draft-lajoie-md-query-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 : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** There is 1 instance of too long lines in the document, the longest one being 25 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (December 31, 2010) is 4858 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 3 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. LaJoie, Ed. 3 Internet-Draft Itumi, LLC 4 Intended status: Experimental December 31, 2010 5 Expires: July 4, 2011 7 Metadata Query Protocol 8 draft-lajoie-md-query-01 10 Abstract 12 This document defines a simple protocol for retrieving metadata about 13 entities. The goal of the protocol is to profile various aspects of 14 HTTP to allow requesters to rely on certain, rigorously defined, 15 behaviour. 17 Status of this Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on July 4, 2011. 34 Copyright Notice 36 Copyright (c) 2010 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 This document may contain material from IETF Documents or IETF 50 Contributions published or made publicly available before November 51 10, 2008. The person(s) controlling the copyright in some of this 52 material may not have granted the IETF Trust the right to allow 53 modifications of such material outside the IETF Standards Process. 54 Without obtaining an adequate license from the person(s) controlling 55 the copyright in such materials, this document may not be modified 56 outside the IETF Standards Process, and derivative works of it may 57 not be created outside the IETF Standards Process, except to format 58 it for publication as an RFC or to translate it into languages other 59 than English. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 64 1.1. Notation and Convention . . . . . . . . . . . . . . . . . 3 65 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 66 2. Protocol Transport . . . . . . . . . . . . . . . . . . . . . . 4 67 2.1. HTTP Version . . . . . . . . . . . . . . . . . . . . . . . 4 68 2.2. HTTP Method . . . . . . . . . . . . . . . . . . . . . . . 4 69 2.3. Request Headers . . . . . . . . . . . . . . . . . . . . . 4 70 2.4. Response Headers . . . . . . . . . . . . . . . . . . . . . 4 71 2.5. Status Codes . . . . . . . . . . . . . . . . . . . . . . . 5 72 2.6. Base URL . . . . . . . . . . . . . . . . . . . . . . . . . 5 73 2.7. Content Negotiation . . . . . . . . . . . . . . . . . . . 6 74 3. Metadata Query Protocol . . . . . . . . . . . . . . . . . . . 7 75 3.1. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 7 76 3.1.1. Transforms . . . . . . . . . . . . . . . . . . . . . . 7 77 3.2. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . 7 78 3.2.1. Request . . . . . . . . . . . . . . . . . . . . . . . 7 79 3.2.2. Response . . . . . . . . . . . . . . . . . . . . . . . 8 80 3.2.3. Example Request and Response . . . . . . . . . . . . . 8 81 4. Efficient Retrieval and Caching . . . . . . . . . . . . . . . 9 82 4.1. Conditional Retrieval . . . . . . . . . . . . . . . . . . 9 83 4.2. Content Caching . . . . . . . . . . . . . . . . . . . . . 9 84 4.3. Content Compression . . . . . . . . . . . . . . . . . . . 9 85 5. Security Considerations . . . . . . . . . . . . . . . . . . . 10 86 5.1. Integrity . . . . . . . . . . . . . . . . . . . . . . . . 10 87 5.2. Confidentiality . . . . . . . . . . . . . . . . . . . . . 10 88 5.3. Authentication . . . . . . . . . . . . . . . . . . . . . . 10 89 6. Normative References . . . . . . . . . . . . . . . . . . . . . 11 90 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 12 91 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 13 93 1. Introduction 95 Many clients of web-based services are capable of consuming 96 descriptive metadata about a service in order to customize or 97 information the client's connection parameters. While the form of 98 the metadata (e.g.. JSON, XML) and content varies between services 99 this document attempts to specifies a set of semantics for HTTP 100 [RFC2616] that allow clients to rely on certain behavior. The 101 defined behavior is meant to make it easy for clients to perform 102 queries, to be efficient for both requesters and responders, and 103 allow the responder to scale in various ways. 105 1.1. Notation and Convention 107 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 108 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 109 document are to be interpreted as described in RFC2119 [RFC2119]. 111 1.2. Terminology 113 entity - A single logical construct for which metadata may be 114 asserted. Generally this is a network accessible service. 116 metadata - A machine readable description of certain entity 117 characteristics. Generally metadata provides information such as 118 end point references, service contact information, etc. 120 2. Protocol Transport 122 The metadata retrieval protocol seeks to fully employ the features of 123 the HTTP protocol. Additionally this specification makes mandatory 124 some optional HTTP features. 126 2.1. HTTP Version 128 Metadata retrieval protocol responders MUST use HTTP, version 1.1 129 [RFC2616] 131 2.2. HTTP Method 133 All metadata retrieval requests MUST use the GET method. 135 2.3. Request Headers 137 All metadata retrieval requests MUST include the following HTTP 138 headers: 140 Accept - this header MUST contain the content-type identifying the 141 type, or form, of metadata to be retrieved 143 All metadata retrieval requests SHOULD include the following HTTP 144 headers: 146 Accept-Charset 148 Accept-Encoding 150 A metadata request to the same URL, after an initial request, MUST 151 include the following header per section 13.3.4 of RFC2616 [RFC2616]: 153 If-None-Match 155 2.4. Response Headers 157 All successful metadata retrieval responses (even those that return 158 no results) MUST include the following headers: 160 Content-Encoding - required if, and only if, content is compressed 162 Content-Type 164 ETag 166 All metadata retrieval responses SHOULD include the following 167 headers: 169 Cache-Control 171 Content-Length 173 Last-Modified 175 2.5. Status Codes 177 This protocol uses the following HTTP status codes: 179 200 - standard response code when returning requested metadata 181 304 - response code indicating requested metadata has not been 182 updated since the last request 184 400 - response code indicating that the requester's request was 185 malformed in some fashion 187 401 - response code indicating the request must be authenticated 188 before requesting metadata 190 404 - indicates that the requested metadata could not be found; 191 this MUST NOT be used in order to indicate a general service 192 error. 194 405 - response code indicating that a non-GET method was used 196 406 - response code indicating that metadata is not available in 197 the request content-type 199 500 - standard response code when something goes wrong within the 200 responder 202 501 - response code indicating that a given identifier 203 transformation is not supported 205 505 - response code indicating that HTTP/1.1 was not used 207 2.6. Base URL 209 Requests defined in this document are performed by issuing an HTTP 210 GET request to a particular URL. The final component of the path to 211 which requests are issued is defined by the requests specified within 212 this document. A base URL precedes such paths. Such a base URL MUST 213 contain at least the scheme and host name components. It MAY also 214 include a port as well as a path. It MUST NOT include URL fragments. 215 If a path is included the path required by the particular defined 216 request is appended to the path in the base URL. 218 2.7. Content Negotiation 220 As there may be many representations for a given piece of metadata, 221 agent-driven content negotiation is used to ensure the proper 222 representation is delivered to the requester. In addition to the 223 required usage of the Accept header a response SHOULD also support 224 the use of the Accept-Charset header. 226 3. Metadata Query Protocol 228 The metadata query protocol retrieves metadata based on one or more 229 "tag" or "keyword" identifiers. A request may return information for 230 none, one, or a collection of entities. 232 3.1. Identifiers 234 The query protocol uses identifiers to "tag" metadata for single- and 235 multi-entity metadata collections. An identifier MAY contain any 236 URL-encodable character but MUST NOT start with '{' (ASCII 0x7B) as 237 this character has a special meaning in the first position (see 238 below). The assignment of such identifiers to a particular metadata 239 document is the responsibility of the query responder. If a metadata 240 collection already contains a well known identifier it is RECOMMENDED 241 that such a natural identifier is used when possible. Any given 242 metadata collection MAY have more than one identifier associated with 243 it. 245 3.1.1. Transforms 247 In some cases it may be advantageous to query for metadata using a 248 transformed identifier. For example, some protocols will transmit 249 hashed entity identifiers. This may be done to reduce the overall 250 size of the identifier, escape special characters, obfuscate the 251 identifier, etc. 253 A transformed identifier is represented by pre-pending the identifier 254 with '{' + transformation indicator + '}'. The transformation 255 indicator MUST be composed exclusively of printable ASCII characters 256 (0x21-0x7E) excluding '{' (0x7B) and '}' (0x7D). Such an identifier 257 need only make sense in the context within which it is used. 258 Responders MUST support the MD5 (transformation indicator 'md5') and 259 SHA1 (transformation indicator 'sha1') hashing algorithms as 260 identifier transformations. The responder MAY support other 261 transformation indicators. 263 For example, the identifier 264 http://example.org/service 265 transformed by means of MD5 hashing would become 266 {md5}f3678248a29ab8e8e5b1b00bee4060e0 268 3.2. Protocol 270 3.2.1. Request 272 A Metadata Query request is performed by issuing an HTTP GET request. 273 All Metadata Query requests MUST use the URL format: 275 /entities/{ID}+{ID}+... 276 The request MUST contain at least one identifier but MAY contain more 277 than one. Each identifier must be properly URL encoded. If more 278 than one identifier is used the returned metadata MUST have been 279 labelled with each identifier. That is to say a search with multiple 280 identifiers results in the intersection of the metadata that would be 281 retrieved by searching for each identifier individually. 283 3.2.2. Response 285 The response to a Metadata Query request MUST be a document that 286 provides metadata for the given request identifiers in the format 287 described by the request's Content-Type header. Note, in the event 288 that multiple identifiers were used in the request, it is the 289 responder's responsibility to ensure that the metadata returned is 290 valid. If the responder can not create a valid document it MUST 291 respond with a 500 status code. An example of such an error would be 292 the case where the result of the query is metadata for multiple 293 entities but the request content type does not support returning 294 multiple results in a single document. 296 3.2.3. Example Request and Response 298 GET /service/entities/http%3A%2F%2Fexample.org%2Fidp HTTP/1.1 299 Host: metadata.example.org 300 Accept: application/samlmetadata+xml 302 Example Metadata Query Request 304 HTTP/1.x 200 OK 305 Content-Type: application/samlmetadata+xml 306 ETag: abcdefg 307 Last-Modified: Thu, 15 Apr 2010 12:45:26 GMT 308 Content-Length: 1234 310 311 312 .... 314 Example Metadata Query Response 316 4. Efficient Retrieval and Caching 318 4.1. Conditional Retrieval 320 Upon a successful response the responder is required to return an 321 ETag header and may return a Last-Modified header as well. 322 Requesters SHOULD user either or both, with the ETag being preferred, 323 in any subsequent requests for the same resource. In the event that 324 a resource has not changed since the previous request, the requester 325 will receive a 304 (Not Modified) status code as a response. 327 4.2. Content Caching 329 Responders SHOULD include cache control information with successful 330 (200 status code) responses, assuming the responder knows when 331 retrieved metadata is meant to expire. The responder should also 332 include cache control information with 404 Not Found responses. This 333 allows the requester to create and maintain a negative-response 334 cache. When cache controls are used only the 'max-age' directive 335 SHOULD be used. 337 4.3. Content Compression 339 As should be apparent from the required request and response headers 340 this protocol encourages the use of content compression. This is in 341 recognition that some metadata documents can be quite large or 342 fetched with relatively high frequency. 344 Requesters SHOULD support, and advertise support for, gzip 345 compression unless such usage would put exceptional demands on 346 constrained environments. Responders MUST support gzip compression. 347 Requesters and responders MAY support other compression algorithms. 349 5. Security Considerations 351 5.1. Integrity 353 As metadata often contains information necessary for the secure 354 operation of interacting services it is RECOMMENDED that some form of 355 content integrity checking be performed. This may include the use of 356 SSL/TLS at the transport layer, digital signatures present within the 357 metadata document, or any other such mechanism. 359 5.2. Confidentiality 361 In many cases service metadata is public information and therefore 362 confidentiality is not required. In the cases where such 363 functionality is required, it is RECOMMENDED that both the requester 364 and responder support SSL/TLS. Other mechanisms, such as XML 365 encryption, MAY also be supported. 367 5.3. Authentication 369 All responders which require client authentication to view retrieved 370 information MUST support the use of HTTP basic authentication over 371 SSL/TLS. Responders SHOULD also support the use of X.509 client 372 certificate authentication. 374 6. Normative References 376 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 377 Requirement Levels", BCP 14, RFC 2119, March 1997. 379 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 380 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 381 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 383 Appendix A. Acknowledgements 385 The editor would like to acknowledge the following individuals for 386 their contributions to this document: 388 Scott Cantor (The Ohio State University) 390 Leif Johansson (SUNET) 392 Thomas Lenggenhager (SWITCH) 394 Ian Young (EDINA, University of Edinburgh) 396 Author's Address 398 Chad LaJoie (editor) 399 Itumi, LLC 401 Email: lajoie@itumi.biz