Skip to main content

Metadata Query Protocol
draft-young-md-query-01

The information below is for an old version of the document.
Document Type
This is an older version of an Internet-Draft whose latest revision state is "Active".
Author Ian Young
Last updated 2013-12-29
RFC stream (None)
Formats
Additional resources
Stream Stream state (No stream defined)
Consensus boilerplate Unknown
RFC Editor Note (None)
IESG IESG state I-D Exists
Telechat date (None)
Responsible AD (None)
Send notices to (None)
draft-young-md-query-01
Network Working Group                                      I. Young, Ed.
Internet-Draft                                               Independent
Intended status: Informational                         December 29, 2013
Expires: July 2, 2014

                        Metadata Query Protocol
                        draft-young-md-query-01

Abstract

   This document defines a simple protocol for retrieving metadata about
   named entities, or named collections of entities.  The goal of the
   protocol is to profile various aspects of HTTP to allow requesters to
   rely on certain, rigorously defined, behaviour.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on July 2, 2014.

Copyright Notice

   Copyright (c) 2013 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.

Young                     Expires July 2, 2014                  [Page 1]
Internet-Draft           Metadata Query Protocol           December 2013

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.1.  Notation and Conventions  . . . . . . . . . . . . . . . .   3
     1.2.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   3
   2.  Protocol Transport  . . . . . . . . . . . . . . . . . . . . .   3
     2.1.  Transport Protocol  . . . . . . . . . . . . . . . . . . .   3
     2.2.  HTTP Version  . . . . . . . . . . . . . . . . . . . . . .   3
     2.3.  HTTP Method . . . . . . . . . . . . . . . . . . . . . . .   3
     2.4.  Request Headers . . . . . . . . . . . . . . . . . . . . .   3
     2.5.  Response Headers  . . . . . . . . . . . . . . . . . . . .   4
     2.6.  Status Codes  . . . . . . . . . . . . . . . . . . . . . .   4
     2.7.  Base URL  . . . . . . . . . . . . . . . . . . . . . . . .   5
     2.8.  Content Negotiation . . . . . . . . . . . . . . . . . . .   5
   3.  Metadata Query Protocol . . . . . . . . . . . . . . . . . . .   5
     3.1.  Identifiers . . . . . . . . . . . . . . . . . . . . . . .   6
     3.2.  Protocol  . . . . . . . . . . . . . . . . . . . . . . . .   7
       3.2.1.  Request . . . . . . . . . . . . . . . . . . . . . . .   7
       3.2.2.  Response  . . . . . . . . . . . . . . . . . . . . . .   7
       3.2.3.  Example Request and Response  . . . . . . . . . . . .   7
   4.  Efficient Retrieval and Caching . . . . . . . . . . . . . . .   8
     4.1.  Conditional Retrieval . . . . . . . . . . . . . . . . . .   8
     4.2.  Content Caching . . . . . . . . . . . . . . . . . . . . .   8
     4.3.  Content Compression . . . . . . . . . . . . . . . . . . .   8
   5.  Protocol Extension Points . . . . . . . . . . . . . . . . . .   8
   6.  Security Considerations . . . . . . . . . . . . . . . . . . .   9
     6.1.  Integrity . . . . . . . . . . . . . . . . . . . . . . . .   9
     6.2.  Confidentiality . . . . . . . . . . . . . . . . . . . . .   9
     6.3.  Authentication  . . . . . . . . . . . . . . . . . . . . .   9
   7.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   9
   8.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .   9
   9.  Normative References  . . . . . . . . . . . . . . . . . . . .  10
   Appendix A.  Change Log (to be removed by RFC Editor before
                publication) . . . . . . . . . . . . . . . . . . . .  10
     A.1.  Since draft-young-md-query-00 . . . . . . . . . . . . . .  10
     A.2.  Since draft-lajoie-md-query-01  . . . . . . . . . . . . .  11

1.  Introduction

   Many clients of web-based services are capable of consuming
   descriptive metadata about a service in order to customize or
   information the client's connection parameters.  While the form of
   the metadata (e.g., JSON, XML) and content varies between services
   this document specifies a set of semantics for HTTP [RFC2616] that
   allow clients to rely on certain behavior.  The defined behavior is
   meant to make it easy for clients to perform queries, to be efficient
   for both requesters and responders, and to allow the responder to
   scale in various ways.

Young                     Expires July 2, 2014                  [Page 2]
Internet-Draft           Metadata Query Protocol           December 2013

1.1.  Notation and Conventions

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in RFC 2119 [BCP14].

   This document makes use of the Augmented BNF metalanguage defined in
   [STD68].

1.2.  Terminology

      entity - A single logical construct for which metadata may be
      asserted.  Generally this is a network accessible service.

      metadata - A machine readable description of certain entity
      characteristics.  Generally metadata provides information such as
      end point references, service contact information, etc.

2.  Protocol Transport

   The metadata query protocol seeks to fully employ the features of the
   HTTP protocol.  Additionally this specification makes mandatory some
   optional HTTP features.

2.1.  Transport Protocol

   The metadata query protocol makes use of the HTTP protocol to
   transmit requests and responses.  The underlying HTTP connection may
   make use of any appropriate transport protocol.  In particular, the
   HTTP connection MAY make use of either TCP or SSL/TLS at the
   transport layer.  See the Security Considerations section for
   guidance in choosing an appropriate transport protocol.

2.2.  HTTP Version

   Requests from clients MUST NOT use an HTTP version prior to version
   1.1.  Responders MUST reply to such requests using status code 505,
   "HTTP Version Not Supported".

   Protocol responders MUST support requests using HTTP version 1.1, and
   MAY support later versions.

2.3.  HTTP Method

   All metadata query requests MUST use the GET method.

2.4.  Request Headers

Young                     Expires July 2, 2014                  [Page 3]
Internet-Draft           Metadata Query Protocol           December 2013

   All metadata query requests MUST include the following HTTP headers:

      Accept - this header MUST contain the content-type identifying the
      type, or form, of metadata to be retrieved

   All metadata query requests SHOULD include the following HTTP
   headers:

      Accept-Charset

      Accept-Encoding

   A metadata request to the same URL, after an initial request, MUST
   include the following header per section 13.3.4 of RFC 2616
   [RFC2616]:

      If-None-Match

2.5.  Response Headers

   All successful metadata query responses (even those that return no
   results) MUST include the following headers:

      Content-Encoding - required if, and only if, content is compressed

      Content-Type

      ETag

   All metadata retrieval responses SHOULD include the following
   headers:

      Cache-Control

      Content-Length

      Last-Modified

2.6.  Status Codes

   This protocol uses the following HTTP status codes:

      200 "OK" - standard response code when returning requested
      metadata

      304 "Not Modified" - response code indicating requested metadata
      has not been updated since the last request

Young                     Expires July 2, 2014                  [Page 4]
Internet-Draft           Metadata Query Protocol           December 2013

      400 "Bad Request" - response code indicating that the requester's
      request was malformed in some fashion

      401 "Unauthorized" - response code indicating the request must be
      authenticated before requesting metadata

      404 "Not Found" - indicates that the requested metadata could not
      be found; this MUST NOT be used in order to indicate a general
      service error.

      405 "Method Not Allowed" - response code indicating that a non-GET
      method was used

      406 "Not Acceptable" - response code indicating that metadata is
      not available in the request content-type

      501 "Not Implemented" - response code indicating that a given
      extended identifier is not supported

      505 "HTTP Version Not Supported" - response code indicating that
      HTTP/1.1 was not used

2.7.  Base URL

   Requests defined in this document are performed by issuing an HTTP
   GET request to a particular URL.  The final component of the path to
   which requests are issued is defined by the requests specified within
   this document.  A base URL precedes such paths.  Such a base URL MUST
   contain at least the scheme and host name components.  It MAY also
   include a port as well as a path.  It MUST NOT include URL fragments.
   If a path is included the path required by the particular defined
   request is appended to the path in the base URL.

2.8.  Content Negotiation

   As there may be many representations for a given piece of metadata,
   agent-driven content negotiation is used to ensure the proper
   representation is delivered to the requester.  In addition to the
   required usage of the Accept header a responder SHOULD also support
   the use of the Accept-Charset header.

3.  Metadata Query Protocol

   The metadata query protocol retrieves metadata based on a single
   "tag" or "keyword" identifier.  A request may return information for
   none, one, or a collection of entities.

Young                     Expires July 2, 2014                  [Page 5]
Internet-Draft           Metadata Query Protocol           December 2013

3.1.  Identifiers

   The query protocol uses identifiers to "tag" metadata for single- and
   multi-entity metadata collections.  The assignment of such
   identifiers to a particular metadata document is the responsibility
   of the query responder.  If a metadata collection already contains a
   well known identifier it is RECOMMENDED that such a natural
   identifier is used when possible.  Any given metadata collection MAY
   have more than one identifier associated with it.

   An identifier used in the query protocol is either a basic identifier
   or an extended identifier:

   id       = basicid / extid

   Identifiers starting with anything other than "{" are basic
   identifiers:

   basicid  = notlb *idchar
   notlb    = %x00-7a / %x7c-7f ; anything other than a "{"

   An identifier starting with "{" (ASCII 0x7B) is an extended
   identifier, and MUST match the "extid" production in the following
   ABNF grammar:

   extid    = "{" extname "}" extarg
   extname  = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
   extarg   = *idchar
   idchar   = %x00-ff ; any encodable character
   ALPHA    = %x41-5a / %x61-7a
   DIGIT    = %x30-39

   The particular extension to be used is named by the "extname" value.
   This value is case sensitive; "Example" and "example" would name
   different extensions.  Each extension may define its own additional
   rules for the "extarg" component.

   A responder MUST return a 400 (bad request) status code if either of
   the following conditions hold:

   o  An identifier starting with "{" does not match the "extid"
      production.

   o  The "extarg" component fails to meet the requirements for the
      named extension.

   A responder MUST return a 501 (not implemented) status code if the
   "extname" value is not supported by the responder.

Young                     Expires July 2, 2014                  [Page 6]
Internet-Draft           Metadata Query Protocol           December 2013

3.2.  Protocol

3.2.1.  Request

   A metadata query request is performed by issuing an HTTP GET request
   to a URL constructed as the concatenation of the following
   components:

   o  The responder's base URL.

   o  A single "/" character, unless the base URL already ends in a "/".

   o  The string "entities/".

   o  A single URL-encoded identifier.

   For example, with a base URL of "http://example.org/mdq", a query for
   the identifier "foo" would be performed by an HTTP GET request to the
   following URL:

   http://example.org/mdq/entities/foo

3.2.2.  Response

   The response to a metadata query request MUST be a document that
   provides metadata for the given request identifier in the format
   described by the request's Content-Type header.

   The responder is responsible for ensuring that the metadata returned
   is valid.  If the responder can not create a valid document it MUST
   respond with a 406 status code.  An example of such an error would be
   the case where the result of the query is metadata for multiple
   entities but the request content type does not support returning
   multiple results in a single document.

3.2.3.  Example Request and Response

   GET /service/entities/http%3A%2F%2Fexample.org%2Fidp HTTP/1.1
   Host: metadata.example.org
   Accept: application/samlmetadata+xml

                      Example Metadata Query Request

Young                     Expires July 2, 2014                  [Page 7]
Internet-Draft           Metadata Query Protocol           December 2013

   HTTP/1.x 200 OK
   Content-Type: application/samlmetadata+xml
   ETag: abcdefg
   Last-Modified: Thu, 15 Apr 2010 12:45:26 GMT
   Content-Length: 1234

   <?xml version="1.0" encoding="UTF-8"?>
   <EntityDescriptor entityID="http://example.org/idp"
       xmlns="urn:oasis:names:tc:SAML:2.0:metadata">
   ....

                      Example Metadata Query Response

4.  Efficient Retrieval and Caching

4.1.  Conditional Retrieval

   Upon a successful response the responder is required to return an
   ETag header and may return a Last-Modified header as well.
   Requesters SHOULD use either or both, with the ETag being preferred,
   in any subsequent requests for the same resource.  In the event that
   a resource has not changed since the previous request, the requester
   will receive a 304 (Not Modified) status code as a response.

4.2.  Content Caching

   Responders SHOULD include cache control information with successful
   (200 status code) responses, assuming the responder knows when
   retrieved metadata is meant to expire.  The responder should also
   include cache control information with 404 Not Found responses.  This
   allows the requester to create and maintain a negative-response
   cache.  When cache controls are used only the 'max-age' directive
   SHOULD be used.

4.3.  Content Compression

   As should be apparent from the required request and response headers
   this protocol encourages the use of content compression.  This is in
   recognition that some metadata documents can be quite large or
   fetched with relatively high frequency.

   Requesters SHOULD support, and advertise support for, gzip
   compression unless such usage would put exceptional demands on
   constrained environments.  Responders MUST support gzip compression.
   Requesters and responders MAY support other compression algorithms.

5.  Protocol Extension Points

Young                     Expires July 2, 2014                  [Page 8]
Internet-Draft           Metadata Query Protocol           December 2013

   The Metadata Query Protocol is extensible using the following
   protocol extension points:

   o  The "extension identifier" syntax described in the Identifiers
      section above is intended for relatively simple extensions such as
      transformed identifiers.

   o  More complex extensions may be implemented by defining additional
      paths (other than "entities/") below the base URL.

6.  Security Considerations

6.1.  Integrity

   As metadata often contains information necessary for the secure
   operation of interacting services it is RECOMMENDED that some form of
   content integrity checking be performed.  This may include the use of
   SSL/TLS at the transport layer, digital signatures present within the
   metadata document, or any other such mechanism.

6.2.  Confidentiality

   In many cases service metadata is public information and therefore
   confidentiality is not required.  In the cases where such
   functionality is required, it is RECOMMENDED that both the requester
   and responder support SSL/TLS.  Other mechanisms, such as XML
   encryption, MAY also be supported.

6.3.  Authentication

   All responders which require client authentication to view retrieved
   information MUST support the use of HTTP basic authentication over
   SSL/TLS.  Responders SHOULD also support the use of X.509 client
   certificate authentication.

7.  IANA Considerations

   This document has no actions for IANA.

8.  Acknowledgements

   The editor would like to acknowledge the following individuals for
   their contributions to this document:

      Scott Cantor (The Ohio State University)

      Leif Johansson (SUNET)

Young                     Expires July 2, 2014                  [Page 9]
Internet-Draft           Metadata Query Protocol           December 2013

      Thomas Lenggenhager (SWITCH)

      Joe St Sauver (University of Oregon)

      Tom Scavo (Internet2)

   Special acknowledgement is due to Chad LaJoie (Covisint) for his work
   in editing previous versions of this specification.

9.  Normative References

   [BCP14]    Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC2616]  Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
              Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
              Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.

   [STD68]    Crocker, D. and P. Overell, "Augmented BNF for Syntax
              Specifications: ABNF", STD 68, RFC 5234, January 2008.

Appendix A.  Change Log (to be removed by RFC Editor before publication)

A.1.  Since draft-young-md-query-00

   Split into two documents: this one is as agnostic as possible around
   questions such as metadata format and higher level protocol use
   cases, a new layered document describes the detailed requirements for
   SAML support.

   Rewrite Section 3.2.1 to clarify construction of the request URL and
   its relationship to the base URL.

   Added Section 2.1 to clarify that the transport protocol underlying
   HTTP may be either TCP or SSL/TLS.

   Clarify position on HTTP versions (Section 2.2) which may be used to
   underly this protocol.

   Added Change Log modelled on draft-ietf-httpbis-http2.

   Added a reference to [STD68].  Use ABNF to describe request syntax.
   Replace transformed identifier concept with extended identifiers
   (this also resulted in the removal of any discussion of specific
   transformed identifier formats).  Add grammar to distinguish basic
   from extended identifiers.

Young                     Expires July 2, 2014                 [Page 10]
Internet-Draft           Metadata Query Protocol           December 2013

   Changed the required response when the result can not be validly
   expressed in the requested format from 500 to 406.

   Removed the '+' operator and all references to multiple identifiers
   in queries.  If more complex queries are required, these will be
   reintroduced at a different path under the base URL.

   Added a section describing Protocol Extension Points.

A.2.  Since draft-lajoie-md-query-01

   Adopted as base for draft-young-md-query-00.

   Updated author and list of contributors.

   Changed ipr from "pre5378Trust200902" to "trust200902", submission
   type from IETF to independent and category from experimental to
   informational.

   Added empty IANA considerations section.

   Minor typographical nits but (intentionally) no substantive content
   changes.

Author's Address

   Ian A. Young (editor)
   Independent

   EMail: ian@iay.org.uk

Young                     Expires July 2, 2014                 [Page 11]