idnits 2.17.1 draft-young-md-query-06.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 (January 13, 2017) is 2658 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7232 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7234 (Obsoleted by RFC 9111) ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 4844 (Obsoleted by RFC 8729) Summary: 6 errors (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group I. Young, Ed. 3 Internet-Draft Independent 4 Intended status: Informational January 13, 2017 5 Expires: July 17, 2017 7 Metadata Query Protocol 8 draft-young-md-query-06 10 Abstract 12 This document defines a simple protocol for retrieving metadata about 13 named entities, or named collections of entities. The goal of the 14 protocol is to profile various aspects of HTTP to allow requesters to 15 rely on certain, rigorously defined, behaviour. 17 This document is a product of the Research and Education Federations 18 (REFEDS) Working Group process. 20 Editorial Note (To be removed by RFC Editor before publication) 22 Discussion of this draft takes place on the MDX mailing list 23 (mdx@lists.iay.org.uk), which is accessed from [MDX.list]. 25 XML versions, latest edits and the issues list for this document are 26 available from [md-query]. 28 The changes in this draft are summarized in Appendix A.7. 30 Status of This Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at http://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on July 17, 2017. 47 Copyright Notice 49 Copyright (c) 2017 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (http://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 62 1.1. Notation and Conventions . . . . . . . . . . . . . . . . 3 63 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 64 2. Protocol Transport . . . . . . . . . . . . . . . . . . . . . 4 65 2.1. Transport Protocol . . . . . . . . . . . . . . . . . . . 4 66 2.2. HTTP Version . . . . . . . . . . . . . . . . . . . . . . 4 67 2.3. HTTP Method . . . . . . . . . . . . . . . . . . . . . . . 4 68 2.4. Request Headers . . . . . . . . . . . . . . . . . . . . . 4 69 2.5. Response Headers . . . . . . . . . . . . . . . . . . . . 5 70 2.6. Status Codes . . . . . . . . . . . . . . . . . . . . . . 5 71 2.7. Base URL . . . . . . . . . . . . . . . . . . . . . . . . 6 72 2.8. Content Negotiation . . . . . . . . . . . . . . . . . . . 6 73 3. Metadata Query Protocol . . . . . . . . . . . . . . . . . . . 6 74 3.1. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 7 75 3.2. Protocol . . . . . . . . . . . . . . . . . . . . . . . . 7 76 3.2.1. Request by Identifier . . . . . . . . . . . . . . . . 7 77 3.2.2. Request All Entities . . . . . . . . . . . . . . . . 8 78 3.2.3. Response . . . . . . . . . . . . . . . . . . . . . . 8 79 3.2.4. Example Request and Response . . . . . . . . . . . . 8 80 4. Efficient Retrieval and Caching . . . . . . . . . . . . . . . 9 81 4.1. Conditional Retrieval . . . . . . . . . . . . . . . . . . 9 82 4.2. Content Caching . . . . . . . . . . . . . . . . . . . . . 9 83 4.3. Content Compression . . . . . . . . . . . . . . . . . . . 9 84 5. Protocol Extension Points . . . . . . . . . . . . . . . . . . 10 85 6. Security Considerations . . . . . . . . . . . . . . . . . . . 10 86 6.1. Integrity . . . . . . . . . . . . . . . . . . . . . . . . 10 87 6.2. Confidentiality . . . . . . . . . . . . . . . . . . . . . 10 88 6.3. Authentication . . . . . . . . . . . . . . . . . . . . . 10 89 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 90 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10 91 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 92 9.1. Normative References . . . . . . . . . . . . . . . . . . 11 93 9.2. Informative References . . . . . . . . . . . . . . . . . 12 94 Appendix A. Change Log (to be removed by RFC Editor before 95 publication) . . . . . . . . . . . . . . . . . . . . 13 96 A.1. Since draft-lajoie-md-query-01 . . . . . . . . . . . . . 13 97 A.2. Since draft-young-md-query-00 . . . . . . . . . . . . . . 13 98 A.3. Since draft-young-md-query-01 . . . . . . . . . . . . . . 14 99 A.4. Since draft-young-md-query-02 . . . . . . . . . . . . . . 14 100 A.5. Since draft-young-md-query-03 . . . . . . . . . . . . . . 14 101 A.6. Since draft-young-md-query-04 . . . . . . . . . . . . . . 14 102 A.7. Since draft-young-md-query-05 . . . . . . . . . . . . . . 15 103 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 15 105 1. Introduction 107 Many clients of web-based services are capable of consuming 108 descriptive metadata about a service in order to customize or obtain 109 information about the client's connection parameters. While the form 110 of the metadata (e.g., JSON, XML) and content varies between services 111 this document specifies a set of semantics for HTTP ([RFC7230] et 112 seq.) that allow clients to rely on certain behavior. The defined 113 behavior is meant to make it easy for clients to perform queries, to 114 be efficient for both requesters and responders, and to allow the 115 responder to scale in various ways. 117 The Research and Education Federations group ([REFEDS]) is the voice 118 that articulates the mutual needs of research and education identity 119 federations worldwide. It aims to represent the requirements of 120 research and education in the ever-growing space of access and 121 identity management. 123 From time to time REFEDS will wish to publish a document in the 124 Internet RFC series. Such documents will be published as part of the 125 RFC Independent Submission Stream [RFC4844]; however the REFEDS 126 working group sign-off process will have been followed for these 127 documents, as described in the REFEDS Participant's Agreement 128 [REFEDS.agreement]. 130 This document is a product of the REFEDS Working Group process. 132 1.1. Notation and Conventions 134 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 135 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 136 document are to be interpreted as described in RFC 2119 [BCP14]. 138 This document makes use of the Augmented BNF metalanguage defined in 139 [STD68]. 141 1.2. Terminology 143 entity: A single logical construct for which metadata may be 144 asserted. Generally this is a network accessible service. 146 metadata: A machine readable description of certain entity 147 characteristics. Generally metadata provides information such as 148 end point references, service contact information, etc. 150 2. Protocol Transport 152 The metadata query protocol seeks to fully employ the features of the 153 HTTP protocol. Additionally this specification makes mandatory some 154 optional HTTP features. 156 2.1. Transport Protocol 158 The metadata query protocol makes use of the HTTP protocol 159 ([RFC7230]) to transmit requests and responses. The underlying HTTP 160 connection MAY make use of any appropriate transport protocol. In 161 particular, the HTTP connection MAY make use of either TCP or TLS at 162 the transport layer. See the Security Considerations section for 163 guidance in choosing an appropriate transport protocol. 165 2.2. HTTP Version 167 Requests from clients MUST NOT use an HTTP version prior to version 168 1.1. Responders MUST reply to such requests using status code 505, 169 "HTTP Version Not Supported". 171 Protocol responders MUST support requests using HTTP version 1.1, and 172 MAY support later versions. 174 2.3. HTTP Method 176 All metadata query requests MUST use the GET method. 178 2.4. Request Headers 180 All metadata query requests MUST include the following HTTP headers: 182 Accept - this header MUST contain the content-type identifying the 183 type, or form, of metadata to be retrieved. See section 5.3.2 of 184 [RFC7231]. 186 All metadata query requests SHOULD include the following HTTP 187 headers: 189 Accept-Charset, see section 5.3.3 of [RFC7231] 191 Accept-Encoding, see section 5.3.4 of [RFC7231] 193 A metadata request to the same URL, after an initial request, MUST 194 include the following header: 196 If-None-Match, see section 3.2 of [RFC7232]. 198 2.5. Response Headers 200 All successful metadata query responses (even those that return no 201 results) MUST include the following headers: 203 Content-Encoding - required if, and only if, content is 204 compressed. See section 3.1.2.2 of [RFC7231]. 206 Content-Type, see section 3.1.1.5 of [RFC7231]. 208 ETag, see section 2.3 of [RFC7232]. 210 All metadata retrieval responses SHOULD include the following 211 headers: 213 Cache-Control, see section 5.2 of [RFC7234]. 215 Content-Length, see section 3.3.2 of [RFC7230] 217 Last-Modified, see section 2.2 of [RFC7232]. 219 2.6. Status Codes 221 This protocol uses the following HTTP status codes: 223 200 "OK" - standard response code when returning requested 224 metadata 226 304 "Not Modified" - response code indicating requested metadata 227 has not been updated since the last request 229 400 "Bad Request" - response code indicating that the requester's 230 request was malformed in some fashion 232 401 "Unauthorized" - response code indicating the request must be 233 authenticated before requesting metadata 234 404 "Not Found" - indicates that the requested metadata could not 235 be found; this MUST NOT be used in order to indicate a general 236 service error. 238 405 "Method Not Allowed" - response code indicating that a non-GET 239 method was used 241 406 "Not Acceptable" - response code indicating that metadata is 242 not available in the request content-type 244 505 "HTTP Version Not Supported" - response code indicating that 245 HTTP/1.1 was not used 247 2.7. Base URL 249 Requests defined in this document are performed by issuing an HTTP 250 GET request to a particular URL ([STD66]). The final component of 251 the path to which requests are issued is defined by the requests 252 specified within this document. A base URL precedes such paths. 253 Such a base URL: 255 o MUST contain the scheme and authority components. 257 o MUST contain a path component ending with a slash ('/') character. 259 o MUST NOT include a query component. 261 o MUST NOT include a fragment identifier component. 263 2.8. Content Negotiation 265 As there may be many representations for a given piece of metadata, 266 agent-driven content negotiation is used to ensure the proper 267 representation is delivered to the requester. In addition to the 268 required usage of the Accept header a responder SHOULD also support 269 the use of the Accept-Charset header. 271 3. Metadata Query Protocol 273 The metadata query protocol retrieves metadata either for all 274 entities known to the responder or for a named collection based on a 275 single "tag" or "keyword" identifier. A request returns information 276 for none, one, or a collection of entities. 278 3.1. Identifiers 280 The query protocol uses identifiers to "tag" metadata for single- and 281 multi-entity metadata collections. The assignment of such 282 identifiers to a particular metadata document is the responsibility 283 of the query responder. If a metadata collection already contains a 284 well known identifier it is RECOMMENDED that such a natural 285 identifier is used when possible. Any given metadata collection MAY 286 have more than one identifier associated with it. 288 An identifier used in the query protocol is a non-empty sequence of 289 arbitrary 8-bit characters: 291 id = 1*idchar 292 idchar = %x00-ff ; any encodable character 294 3.2. Protocol 296 3.2.1. Request by Identifier 298 A metadata query request for all entities tagged with a particular 299 identifier is performed by issuing an HTTP GET request to a URL 300 constructed as the concatenation of the following components: 302 o The responder's base URL. 304 o The string "entities/". 306 o A single identifier, percent-encoded appropriately for use as a 307 URL path segment (see sections 2.1 and 3.3 of [STD66]). 309 For example, with a base URL of "http://example.org/mdq/", a query 310 for the identifier "foo" would be performed by an HTTP GET request to 311 the following URL: 313 http://example.org/mdq/entities/foo 315 Correct encoding of the identifier as a URL path segment is critical 316 for interoperability. In particular: 318 The character '/' MUST be percent-encoded. 320 The space character MUST be encoded as '%20' and MUST NOT be 321 encoded as '+' as would be required in a query parameter. 323 For example, with a base URL of "http://example.org/mdq/", a query 324 for the identifier ""blue/green+light blue"" would be performed by an 325 HTTP GET request to the following URL: 327 http://example.org/mdq/entities/blue%2Fgreen+light%20blue 329 3.2.2. Request All Entities 331 A metadata query request for all entities known to the responder is 332 performed by issuing an HTTP GET request to a URL constructed as the 333 concatenation of the following components: 335 o The responder's base URL. 337 o The string "entities". 339 For example, with a base URL of "http://example.org/mdq/", a query 340 for all entities would be performed by an HTTP GET request to the 341 following URL: 343 http://example.org/mdq/entities 345 3.2.3. Response 347 The response to a metadata query request MUST be a document that 348 provides metadata for the given request in the format described by 349 the request's Accept header. 351 The responder is responsible for ensuring that the metadata returned 352 is valid. If the responder can not create a valid document it MUST 353 respond with a 406 status code. An example of such an error would be 354 the case where the result of the query is metadata for multiple 355 entities but the request content type does not support returning 356 multiple results in a single document. 358 3.2.4. Example Request and Response 360 The following example demonstrates a metadata query request using a 361 base URL of "http://metadata.example.org/service/" and the identifier 362 "http://example.org/idp". 364 GET /service/entities/http:%2F%2Fexample.org%2Fidp HTTP/1.1 365 Host: metadata.example.org 366 Accept: application/samlmetadata+xml 368 Example Metadata Query Request 370 HTTP/1.x 200 OK 371 Content-Type: application/samlmetadata+xml 372 ETag: "abcdefg" 373 Last-Modified: Thu, 15 Apr 2010 12:45:26 GMT 374 Content-Length: 1234 376 377 379 .... 381 Example Metadata Query Response 383 4. Efficient Retrieval and Caching 385 4.1. Conditional Retrieval 387 Upon a successful response the responder MUST return an ETag header 388 and MAY return a Last-Modified header as well. Requesters SHOULD use 389 either or both, with the ETag being preferred, in any subsequent 390 requests for the same resource. 392 In the event that a resource has not changed since the previous 393 request, the responder SHOULD send a 304 (Not Modified) status code 394 as a response. 396 4.2. Content Caching 398 Responders SHOULD include cache control information with successful 399 (200 status code) responses, assuming the responder knows when 400 retrieved metadata is meant to expire. The responder SHOULD also 401 include cache control information with 404 Not Found responses. This 402 allows the requester to create and maintain a negative-response 403 cache. When cache controls are used only the 'max-age' directive 404 SHOULD be used. 406 4.3. Content Compression 408 As should be apparent from the required request and response headers 409 this protocol encourages the use of content compression. This is in 410 recognition that some metadata documents can be quite large or 411 fetched with relatively high frequency. 413 Requesters SHOULD support, and advertise support for, gzip 414 compression unless such usage would put exceptional demands on 415 constrained environments. Responders MUST support gzip compression. 416 Requesters and responders MAY support other compression algorithms. 418 5. Protocol Extension Points 420 The Metadata Query Protocol is extensible using the following 421 protocol extension points: 423 o Profiles of this specification may assign semantics to specific 424 identifiers, or to identifiers structured in particular ways. 426 o Profiles of this specification may define additional paths (other 427 than "entities" and "entities/") below the base URL. 429 6. Security Considerations 431 6.1. Integrity 433 As metadata often contains information necessary for the secure 434 operation of interacting services it is RECOMMENDED that some form of 435 content integrity checking be performed. This may include the use of 436 TLS at the transport layer, digital signatures present within the 437 metadata document, or any other such mechanism. 439 6.2. Confidentiality 441 In many cases service metadata is public information and therefore 442 confidentiality is not required. In the cases where such 443 functionality is required, it is RECOMMENDED that both the requester 444 and responder support TLS. Other mechanisms, such as XML encryption, 445 MAY also be supported. 447 6.3. Authentication 449 All responders which require client authentication to view retrieved 450 information MUST support the use of HTTP basic authentication 451 ([RFC7235], [RFC2617]/[I-D.basicauth]) over TLS. Responders SHOULD 452 also support the use of X.509 client certificate authentication. 454 7. IANA Considerations 456 This document has no actions for IANA. 458 8. Acknowledgements 460 The editor would like to acknowledge the following individuals for 461 their contributions to this document: 463 Scott Cantor (The Ohio State University) 465 Leif Johansson (SUNET) 466 Thomas Lenggenhager (SWITCH) 468 Joe St Sauver (University of Oregon) 470 Tom Scavo (Internet2) 472 Special acknowledgement is due to Chad LaJoie (Covisint) for his work 473 in editing previous versions of this specification. 475 9. References 477 9.1. Normative References 479 [BCP14] Bradner, S., "Key words for use in RFCs to Indicate 480 Requirement Levels", BCP 14, RFC 2119, March 1997. 482 [I-D.basicauth] 483 Reschke, J., "The 'Basic' HTTP Authentication Scheme", 484 draft-ietf-httpauth-basicauth-update-07 (work in 485 progress), February 2015. 487 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 488 Leach, P., Luotonen, A., and L. Stewart, "HTTP 489 Authentication: Basic and Digest Access Authentication", 490 RFC 2617, June 1999. 492 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 493 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 494 2014. 496 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 497 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 499 [RFC7232] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 500 (HTTP/1.1): Conditional Requests", RFC 7232, June 2014. 502 [RFC7234] Fielding, R., Nottingham, M., and J. Reschke, "Hypertext 503 Transfer Protocol (HTTP/1.1): Caching", RFC 7234, June 504 2014. 506 [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 507 (HTTP/1.1): Authentication", RFC 7235, June 2014. 509 [STD66] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 510 Resource Identifier (URI): Generic Syntax", STD 66, 511 RFC 3986, January 2005. 513 [STD68] Crocker, D. and P. Overell, "Augmented BNF for Syntax 514 Specifications: ABNF", STD 68, RFC 5234, January 2008. 516 9.2. Informative References 518 [md-query] 519 Young, I., Ed., "md-query Project", 520 . 522 [MDX.list] 523 Young, I., Ed., "MDX Mailing List", 524 . 526 [REFEDS] Research and Education Federations, "REFEDS Home Page", 527 . 529 [REFEDS.agreement] 530 Research and Education Federations, "REFEDS Participant's 531 Agreement", . 534 [RFC4844] Daigle, L. and Internet Architecture Board, "The RFC 535 Series and RFC Editor", RFC 4844, July 2007. 537 Appendix A. Change Log (to be removed by RFC Editor before publication) 539 A.1. Since draft-lajoie-md-query-01 541 Adopted as base for draft-young-md-query-00. 543 Updated author and list of contributors. 545 Changed ipr from "pre5378Trust200902" to "trust200902", submission 546 type from IETF to independent and category from experimental to 547 informational. 549 Added empty IANA considerations section. 551 Minor typographical nits but (intentionally) no substantive content 552 changes. 554 A.2. Since draft-young-md-query-00 556 Split into two documents: this one is as agnostic as possible around 557 questions such as metadata format and higher level protocol use 558 cases, a new layered document describes the detailed requirements for 559 SAML support. 561 Rewrite Section 3.2.1 to clarify construction of the request URL and 562 its relationship to the base URL. 564 Added Section 2.1 to clarify that the transport protocol underlying 565 HTTP may be either TCP or SSL/TLS. 567 Clarify position on HTTP versions (Section 2.2) which may be used to 568 underly this protocol. 570 Added Change Log modelled on draft-ietf-httpbis-http2. 572 Added a reference to [STD68]. Use ABNF to describe request syntax. 573 Replace transformed identifier concept with extended identifiers 574 (this also resulted in the removal of any discussion of specific 575 transformed identifier formats). Add grammar to distinguish basic 576 from extended identifiers. 578 Changed the required response when the result can not be validly 579 expressed in the requested format from 500 to 406. 581 Removed the '+' operator and all references to multiple identifiers 582 in queries. If more complex queries are required, these will be 583 reintroduced at a different path under the base URL. 585 Added a section describing Protocol Extension Points. 587 A.3. Since draft-young-md-query-01 589 Added REFEDS RFC stream boilerplate. 591 Tidied up some normative language. 593 A.4. Since draft-young-md-query-02 595 Introduced a normative reference to [STD66]. 597 Reworked the definition of the base URL so that a non-empty path 598 ending with '/' is required. This allows the definition of request 599 URLs to be simplified. 601 Clarified the definition of the base URL to exclude a query 602 component; corrected the terminology for the fragment identifier 603 component. 605 Added the definition for the query for all entities in Section 3.2.2. 607 Corrected an example in Section 3.2.4 to include the required double 608 quotes in the value of an ETag header. Added text to clarify the 609 base URL and identifier being used in the example. 611 Simplified the definition of identifiers, so that any non-empty 612 identifier is accepted and no semantics are defined for particular 613 structures. Extended syntaxes such as the "{sha1}" notation for 614 transformed identifiers are now left to profiles. 616 Remove incidental references to SSL. 618 Remove status code 501 ("not implemented") as it is no longer 619 referenced. 621 A.5. Since draft-young-md-query-03 623 Correct a typo in the identifier grammar. 625 A.6. Since draft-young-md-query-04 627 Updated to rely on the new definition of HTTP/1.1 in [RFC7230] et 628 seq. instead of RFC 2616. 630 Corrected Section 3.2.3 to indicate that the request contains an 631 Accept header, not a Content-Type header. 633 Added an Editorial Note to help direct readers back to the 634 discussion. 636 A.7. Since draft-young-md-query-05 638 Remove unnecessary percent-encoding of a ':' character in the example 639 in Section 3.2.4. 641 Removed use of the ambiguous term "URL-encoded" in Section 3.2.1. 642 Instead, indicate that the encoding must correspond to the rules for 643 encoding a URL path segment specifically, and call out some of the 644 more important implications arising from that. Added a new example 645 illustrating these implications. 647 Updated the description of conditional retrieval in Section 4.1 to 648 make the use of a 304 (Not Modified) status code a normative but non- 649 mandatory obligation on the responder, not simply a description of 650 what the requester will receive. 652 Author's Address 654 Ian A. Young (editor) 655 Independent 657 EMail: ian@iay.org.uk