Network Working Group C. LaJoie, Ed.
Internet-Draft Itumi, LLC
Intended status: Experimental June 30, 2010
Expires: January 1, 2011
Metadata Query Protocol
draft-lajoie-md-query-00
Abstract
This document defines a simple protocol for retrieving metadata about
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 January 1, 2011.
Copyright Notice
Copyright (c) 2010 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. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
LaJoie Expires January 1, 2011 [Page 1]
Internet-Draft Metadata Query Protocol June 2010
This document may contain material from IETF Documents or IETF
Contributions published or made publicly available before November
10, 2008. The person(s) controlling the copyright in some of this
material may not have granted the IETF Trust the right to allow
modifications of such material outside the IETF Standards Process.
Without obtaining an adequate license from the person(s) controlling
the copyright in such materials, this document may not be modified
outside the IETF Standards Process, and derivative works of it may
not be created outside the IETF Standards Process, except to format
it for publication as an RFC or to translate it into languages other
than English.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Notation and Convention . . . . . . . . . . . . . . . . . 3
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
2. Protocol Transport . . . . . . . . . . . . . . . . . . . . . . 4
2.1. HTTP Version . . . . . . . . . . . . . . . . . . . . . . . 4
2.2. HTTP Method . . . . . . . . . . . . . . . . . . . . . . . 4
2.3. Request Headers . . . . . . . . . . . . . . . . . . . . . 4
2.4. Response Headers . . . . . . . . . . . . . . . . . . . . . 4
2.5. Status Codes . . . . . . . . . . . . . . . . . . . . . . . 5
2.6. Base URL . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.7. Content Negotiation . . . . . . . . . . . . . . . . . . . 6
3. Metadata Query Protocol . . . . . . . . . . . . . . . . . . . 7
3.1. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 7
3.1.1. Transforms . . . . . . . . . . . . . . . . . . . . . . 7
3.2. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.2.1. Request . . . . . . . . . . . . . . . . . . . . . . . 7
3.2.2. Response . . . . . . . . . . . . . . . . . . . . . . . 8
3.2.3. Example Request and Response . . . . . . . . . . . . . 8
4. Efficient Retrieval and Caching . . . . . . . . . . . . . . . 9
4.1. Conditional Retrieval . . . . . . . . . . . . . . . . . . 9
4.2. Content Caching . . . . . . . . . . . . . . . . . . . . . 9
4.3. Content Compression . . . . . . . . . . . . . . . . . . . 9
5. Security Considerations . . . . . . . . . . . . . . . . . . . 10
5.1. Integrity . . . . . . . . . . . . . . . . . . . . . . . . 10
5.2. Confidentiality . . . . . . . . . . . . . . . . . . . . . 10
5.3. Authentication . . . . . . . . . . . . . . . . . . . . . . 10
6. Normative References . . . . . . . . . . . . . . . . . . . . . 11
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 12
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 13
LaJoie Expires January 1, 2011 [Page 2]
Internet-Draft Metadata Query Protocol June 2010
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 attempts to 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
allow the responder to scale in various ways.
1.1. Notation and Convention
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 RFC2119 [RFC2119].
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.
LaJoie Expires January 1, 2011 [Page 3]
Internet-Draft Metadata Query Protocol June 2010
2. Protocol Transport
The metadata retrieval protocol seeks to fully employ the features of
the HTTP protocol. Additionally this specification makes mandatory
some optional HTTP features.
2.1. HTTP Version
Metadata retrieval protocol responders MUST use HTTP, version 1.1
[RFC2616]
2.2. HTTP Method
All metadata retrieval request MUST use the GET method.
2.3. Request Headers
All metadata retrieval 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 retrieval requests SHOULD include the following HTTP
headers:
Accept-Charset
Accept-Encoding
If-Modified-Since
If-None-Match
2.4. Response Headers
All metadata retrieval responses MUST include the following headers:
Content-Encoding - required if, and only if, content is compressed
Content-Type
ETag - required if, and only if, the request status code is 200
All metadata retrieval responses SHOULD include the following
headers:
LaJoie Expires January 1, 2011 [Page 4]
Internet-Draft Metadata Query Protocol June 2010
Cache-Control
Content-Length
Last-Modified
2.5. Status Codes
This protocol uses the following HTTP status codes:
200 - standard response code when returning requested metadata
304 - response code indicating requested metadata has not been
updated since the last request
400 - response code indicating that the requester's request was
malformed in some fashion
401 - response code indicating the request must be authenticated
before requesting metadata
404 - indicates that the requested metadata could not be found;
this MUST NOT be used in order to indicate a general service
error.
405 - response code indicating that a non-GET method was used
406 - response code indicating that metadata is not available in
the request content-type
500 - standard response code when something goes wrong within the
responder
501 - response code indicating that a given identifier
transformation is not supported
505 - response code indicating that HTTP/1.1 was not used
2.6. 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.
LaJoie Expires January 1, 2011 [Page 5]
Internet-Draft Metadata Query Protocol June 2010
2.7. 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 response SHOULD also support
the use of the Accept-Charset header.
LaJoie Expires January 1, 2011 [Page 6]
Internet-Draft Metadata Query Protocol June 2010
3. Metadata Query Protocol
The metadata query protocol retrieves metadata based on one or more
"tag" or "keyword" identifiers. A request may return information for
none, one, or a collection of entities.
3.1. Identifiers
The query protocol uses identifiers to "tag" metadata for single- and
multi-entity metadata collections. An identifier MAY contain any
URL-encodable character but MUST NOT start with '{' (ASCII 0x7B) as
this character has a special meaning in the first position (see
below). 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.
3.1.1. Transforms
In some cases it may be advantageous to query for metadata using a
transformed identifier. For example, some protocols will transmit
hashed entity identifiers. This may be done to reduce the overall
size of the identifier, escape special characters, obfuscate the
identifier, etc.
A transformed identifier is represented by pre-pending the identifier
with '{' + transformation indicator + '}'. The transformation
indicator MUST be composed exclusively of printable ASCII characters
(0x21-0x7E) excluding '{' (0x7B) and '}' (0x7D). Such an identifier
need only make sense in the context within which it is used.
Responders MUST support the MD5 (transformation indicator 'md5') and
SHA1 (transformation indicator 'sha1') hashing algorithms as
identifier transformations. The responder MAY support other
transformation indicators.
For example, the identifier
http://example.org/service
transformed by means of MD5 hashing would become
{md5}f3678248a29ab8e8e5b1b00bee4060e0
3.2. Protocol
3.2.1. Request
A Metadata Query request is performed by issuing an HTTP GET request.
All Metadata Query requests MUST use the URL format:
LaJoie Expires January 1, 2011 [Page 7]
Internet-Draft Metadata Query Protocol June 2010
<base_url>/entities/{ID}+{ID}+...
The request MUST contain at least one identifier but MAY contain more
than one. Each identifier must be properly URL encoded. If more
than one identifier is used the returned metadata MUST have been
labelled with each identifier. That is to say a search with multiple
identifiers results in the intersection of the metadata that would be
retrieved by searching for each identifier individually.
3.2.2. Response
The response to a Metadata Query request MUST be a document that
provides metadata for the given request identifiers in the format
described by the request's Content-Type header. Note, in the event
that multiple identifiers were used in the request, it is the
responder's responsibility to ensure that the metadata returned is
valid. If the responder can not create a valid document it MUST
respond with a 500 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
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
<EntityDescriptor entityID="http://example.org/idp">
....
Example Metadata Query Response
LaJoie Expires January 1, 2011 [Page 8]
Internet-Draft Metadata Query Protocol June 2010
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 user 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 302 (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.
LaJoie Expires January 1, 2011 [Page 9]
Internet-Draft Metadata Query Protocol June 2010
5. Security Considerations
5.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.
5.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.
5.3. Authentication
All responders which require client authentication to view retrieved
information MUST support the use of HTTP basic authentication over
SSL/TLS. Responses SHOULD also support the use of X.509 client
certificate authentication.
LaJoie Expires January 1, 2011 [Page 10]
Internet-Draft Metadata Query Protocol June 2010
6. Normative References
[RFC2119] 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.
LaJoie Expires January 1, 2011 [Page 11]
Internet-Draft Metadata Query Protocol June 2010
Appendix A. Acknowledgements
The editor would like to acknowledge the following individuals for
their contributions to this document:
Scott Cantor (The Ohio State University)
Leif Johansson (TODO)
Thomas Lenggenhager (SWITCH)
Ian Young (EDINA, University of Edinburgh)
LaJoie Expires January 1, 2011 [Page 12]
Internet-Draft Metadata Query Protocol June 2010
Author's Address
Chad LaJoie (editor)
Itumi, LLC
Email: lajoie@itumi.biz
LaJoie Expires January 1, 2011 [Page 13]