< draft-young-md-query-15.txt   draft-young-md-query-16.txt >
Network Working Group I. Young, Ed. Network Working Group I.A. Young, Ed.
Internet-Draft Independent Internet-Draft Independent
Intended status: Informational July 8, 2021 Intended status: Informational 10 January 2022
Expires: January 9, 2022 Expires: 14 July 2022
Metadata Query Protocol Metadata Query Protocol
draft-young-md-query-15 draft-young-md-query-16
Abstract Abstract
This document defines a simple protocol for retrieving metadata about This document defines a simple protocol for retrieving metadata about
named entities, or named collections of entities. The goal of the named entities, or named collections of entities. The goal of the
protocol is to profile various aspects of HTTP to allow requesters to protocol is to profile various aspects of HTTP to allow requesters to
rely on certain, rigorously defined, behaviour. rely on certain, rigorously defined, behaviour.
This document is a product of the Research and Education Federations This document is a product of the Research and Education Federations
(REFEDS) Working Group process. (REFEDS) Working Group process.
Editorial Note (To be removed by RFC Editor before publication) Editorial Note (To be removed by RFC Editor before publication)
Discussion of this draft takes place on the MDX mailing list Discussion of this draft takes place on the MDX mailing list
(mdx@lists.iay.org.uk), which is accessed from [MDX.list]. (mdx@lists.iay.org.uk), which is accessed from [MDX.list].
XML versions, latest edits and the issues list for this document are XML versions, latest edits and the issues list for this document are
available from [md-query]. available from [md-query].
The changes in this draft are summarized in Appendix A.16. The changes in this draft are summarized in Appendix A.17.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 9, 2022. This Internet-Draft will expire on 14 July 2022.
Copyright Notice Copyright Notice
Copyright (c) 2021 IETF Trust and the persons identified as the Copyright (c) 2022 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents (https://trustee.ietf.org/
(https://trustee.ietf.org/license-info) in effect on the date of license-info) in effect on the date of publication of this document.
publication of this document. Please review these documents Please review these documents carefully, as they describe your rights
carefully, as they describe your rights and restrictions with respect and restrictions with respect to this document.
to this document.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Notation and Conventions . . . . . . . . . . . . . . . . 4 1.1. Notation and Conventions . . . . . . . . . . . . . . . . 4
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4
2. Protocol Transport . . . . . . . . . . . . . . . . . . . . . 4 2. Protocol Transport . . . . . . . . . . . . . . . . . . . . . 4
2.1. Transport Protocol . . . . . . . . . . . . . . . . . . . 4 2.1. Transport Protocol . . . . . . . . . . . . . . . . . . . 4
2.2. HTTP Version . . . . . . . . . . . . . . . . . . . . . . 4 2.2. HTTP Version . . . . . . . . . . . . . . . . . . . . . . 4
2.3. HTTP Method . . . . . . . . . . . . . . . . . . . . . . . 5 2.3. HTTP Method . . . . . . . . . . . . . . . . . . . . . . . 4
2.4. Request Headers . . . . . . . . . . . . . . . . . . . . . 5 2.4. Request Headers . . . . . . . . . . . . . . . . . . . . . 5
2.5. Response Headers . . . . . . . . . . . . . . . . . . . . 5 2.5. Response Headers . . . . . . . . . . . . . . . . . . . . 5
2.6. Status Codes . . . . . . . . . . . . . . . . . . . . . . 6 2.6. Status Codes . . . . . . . . . . . . . . . . . . . . . . 5
2.7. Base URL . . . . . . . . . . . . . . . . . . . . . . . . 6 2.7. Base URL . . . . . . . . . . . . . . . . . . . . . . . . 6
2.8. Content Negotiation . . . . . . . . . . . . . . . . . . . 7 2.8. Content Negotiation . . . . . . . . . . . . . . . . . . . 6
3. Metadata Query Protocol . . . . . . . . . . . . . . . . . . . 7 3. Metadata Query Protocol . . . . . . . . . . . . . . . . . . . 7
3.1. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 7 3.1. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 7
3.2. Protocol . . . . . . . . . . . . . . . . . . . . . . . . 7 3.2. Protocol . . . . . . . . . . . . . . . . . . . . . . . . 7
3.2.1. Request by Identifier . . . . . . . . . . . . . . . . 7 3.2.1. Request by Identifier . . . . . . . . . . . . . . . . 7
3.2.2. Request All Entities . . . . . . . . . . . . . . . . 8 3.2.2. Request All Entities . . . . . . . . . . . . . . . . 8
3.2.3. Response . . . . . . . . . . . . . . . . . . . . . . 8 3.2.3. Response . . . . . . . . . . . . . . . . . . . . . . 8
3.2.4. Example Request and Response . . . . . . . . . . . . 9 3.2.4. Example Request and Response . . . . . . . . . . . . 8
4. Efficient Retrieval and Caching . . . . . . . . . . . . . . . 9 4. Efficient Retrieval and Caching . . . . . . . . . . . . . . . 9
4.1. Conditional Retrieval . . . . . . . . . . . . . . . . . . 9 4.1. Conditional Retrieval . . . . . . . . . . . . . . . . . . 9
4.2. Content Caching . . . . . . . . . . . . . . . . . . . . . 9 4.2. Content Caching . . . . . . . . . . . . . . . . . . . . . 9
4.3. Content Compression . . . . . . . . . . . . . . . . . . . 10 4.3. Content Compression . . . . . . . . . . . . . . . . . . . 9
5. Protocol Extension Points . . . . . . . . . . . . . . . . . . 10 5. Protocol Extension Points . . . . . . . . . . . . . . . . . . 10
6. Security Considerations . . . . . . . . . . . . . . . . . . . 10 6. Security Considerations . . . . . . . . . . . . . . . . . . . 10
6.1. Integrity . . . . . . . . . . . . . . . . . . . . . . . . 10 6.1. Integrity . . . . . . . . . . . . . . . . . . . . . . . . 10
6.2. Confidentiality . . . . . . . . . . . . . . . . . . . . . 10 6.2. Confidentiality . . . . . . . . . . . . . . . . . . . . . 10
6.3. Authentication . . . . . . . . . . . . . . . . . . . . . 10 6.3. Authentication . . . . . . . . . . . . . . . . . . . . . 10
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 11
9.1. Normative References . . . . . . . . . . . . . . . . . . 11 9.1. Normative References . . . . . . . . . . . . . . . . . . 11
9.2. Informative References . . . . . . . . . . . . . . . . . 12 9.2. Informative References . . . . . . . . . . . . . . . . . 12
Appendix A. Change Log (to be removed by RFC Editor before Appendix A. Change Log (to be removed by RFC Editor before
publication) . . . . . . . . . . . . . . . . . . . . 14 publication) . . . . . . . . . . . . . . . . . . . . . . 13
A.1. Since draft-lajoie-md-query-01 . . . . . . . . . . . . . 14
A.2. Since draft-young-md-query-00 . . . . . . . . . . . . . . 14 A.1. Since draft-lajoie-md-query-01 . . . . . . . . . . . . . 13
A.3. Since draft-young-md-query-01 . . . . . . . . . . . . . . 15 A.2. Since draft-young-md-query-00 . . . . . . . . . . . . . . 13
A.4. Since draft-young-md-query-02 . . . . . . . . . . . . . . 15 A.3. Since draft-young-md-query-01 . . . . . . . . . . . . . . 14
A.5. Since draft-young-md-query-03 . . . . . . . . . . . . . . 15 A.4. Since draft-young-md-query-02 . . . . . . . . . . . . . . 14
A.6. Since draft-young-md-query-04 . . . . . . . . . . . . . . 15 A.5. Since draft-young-md-query-03 . . . . . . . . . . . . . . 14
A.7. Since draft-young-md-query-05 . . . . . . . . . . . . . . 16 A.6. Since draft-young-md-query-04 . . . . . . . . . . . . . . 14
A.8. Since draft-young-md-query-06 . . . . . . . . . . . . . . 16 A.7. Since draft-young-md-query-05 . . . . . . . . . . . . . . 15
A.9. Since draft-young-md-query-07 . . . . . . . . . . . . . . 16 A.8. Since draft-young-md-query-06 . . . . . . . . . . . . . . 15
A.10. Since draft-young-md-query-08 . . . . . . . . . . . . . . 16 A.9. Since draft-young-md-query-07 . . . . . . . . . . . . . . 15
A.11. Since draft-young-md-query-09 . . . . . . . . . . . . . . 16 A.10. Since draft-young-md-query-08 . . . . . . . . . . . . . . 15
A.12. Since draft-young-md-query-10 . . . . . . . . . . . . . . 16 A.11. Since draft-young-md-query-09 . . . . . . . . . . . . . . 15
A.13. Since draft-young-md-query-11 . . . . . . . . . . . . . . 16 A.12. Since draft-young-md-query-10 . . . . . . . . . . . . . . 15
A.14. Since draft-young-md-query-12 . . . . . . . . . . . . . . 17 A.13. Since draft-young-md-query-11 . . . . . . . . . . . . . . 15
A.15. Since draft-young-md-query-13 . . . . . . . . . . . . . . 17 A.14. Since draft-young-md-query-12 . . . . . . . . . . . . . . 16
A.16. Since draft-young-md-query-14 . . . . . . . . . . . . . . 17 A.15. Since draft-young-md-query-13 . . . . . . . . . . . . . . 16
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 17 A.16. Since draft-young-md-query-14 . . . . . . . . . . . . . . 16
A.17. Since draft-young-md-query-15 . . . . . . . . . . . . . . 16
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 16
1. Introduction 1. Introduction
Many clients of web-based services are capable of consuming Many clients of web-based services are capable of consuming
descriptive metadata about a service in order to customize or obtain descriptive metadata about a service in order to customize or obtain
information about the client's connection parameters. While the form information about the client's connection parameters. While the form
of the metadata (e.g., JSON, XML) and content varies between services of the metadata (e.g., JSON, XML) and content varies between services
this document specifies a set of semantics for HTTP ([RFC7230] et this document specifies a set of semantics for HTTP ([RFC7230] et
seq.) that allow clients to rely on certain behavior. The defined seq.) that allow clients to rely on certain behavior. The defined
behavior is meant to make it easy for clients to perform queries, to behavior is meant to make it easy for clients to perform queries, to
skipping to change at page 6, line 42 skipping to change at page 6, line 34
HTTP/1.1 was not used HTTP/1.1 was not used
2.7. Base URL 2.7. Base URL
Requests defined in this document are performed by issuing an HTTP Requests defined in this document are performed by issuing an HTTP
GET request to a particular URL ([STD66]). The final component of GET request to a particular URL ([STD66]). The final component of
the path to which requests are issued is defined by the requests the path to which requests are issued is defined by the requests
specified within this document. A base URL precedes such paths. specified within this document. A base URL precedes such paths.
Such a base URL: Such a base URL:
o MUST contain the scheme and authority components. * MUST contain the scheme and authority components.
o MUST contain a path component ending with a slash ('/') character. * MUST contain a path component ending with a slash ('/') character.
o MUST NOT include a query component. * MUST NOT include a query component.
o MUST NOT include a fragment identifier component. * MUST NOT include a fragment identifier component.
2.8. Content Negotiation 2.8. Content Negotiation
As there may be many representations for a given piece of metadata, As there may be many representations for a given piece of metadata,
agent-driven content negotiation is used to ensure the proper agent-driven content negotiation is used to ensure the proper
representation is delivered to the requester. In addition to the representation is delivered to the requester. In addition to the
required usage of the Accept header a responder SHOULD also support required usage of the Accept header a responder SHOULD also support
the use of the Accept-Charset header. the use of the Accept-Charset header.
3. Metadata Query Protocol 3. Metadata Query Protocol
skipping to change at page 7, line 44 skipping to change at page 7, line 36
idchar = %x00-ff ; any encodable character idchar = %x00-ff ; any encodable character
3.2. Protocol 3.2. Protocol
3.2.1. Request by Identifier 3.2.1. Request by Identifier
A metadata query request for all entities tagged with a particular A metadata query request for all entities tagged with a particular
identifier is performed by issuing an HTTP GET request to a URL identifier is performed by issuing an HTTP GET request to a URL
constructed as the concatenation of the following components: constructed as the concatenation of the following components:
o The responder's base URL. * The responder's base URL.
o The string "entities/". * The string "entities/".
o A single identifier, percent-encoded appropriately for use as a * A single identifier, percent-encoded appropriately for use as a
URL path segment (see sections 2.1 and 3.3 of [STD66]). URL path segment (see sections 2.1 and 3.3 of [STD66]).
For example, with a base URL of "http://example.org/mdq/", a query For example, with a base URL of http://example.org/mdq/, a query for
for the identifier "foo" would be performed by an HTTP GET request to the identifier foo would be performed by an HTTP GET request to the
the following URL: following URL:
http://example.org/mdq/entities/foo http://example.org/mdq/entities/foo
Correct encoding of the identifier as a URL path segment is critical Correct encoding of the identifier as a URL path segment is critical
for interoperability. In particular: for interoperability. In particular:
The character '/' MUST be percent-encoded. The character '/' MUST be percent-encoded.
The space character MUST be encoded as '%20' and MUST NOT be The space character MUST be encoded as '%20' and MUST NOT be
encoded as '+' as would be required in a query parameter. encoded as '+' as would be required in a query parameter.
For example, with a base URL of "http://example.org/mdq/", a query For example, with a base URL of http://example.org/mdq/, a query for
for the identifier ""blue/green+light blue"" would be performed by an the identifier "blue/green+light blue" would be performed by an HTTP
HTTP GET request to the following URL: GET request to the following URL:
http://example.org/mdq/entities/blue%2Fgreen+light%20blue http://example.org/mdq/entities/blue%2Fgreen+light%20blue
3.2.2. Request All Entities 3.2.2. Request All Entities
A metadata query request for all entities known to the responder is A metadata query request for all entities known to the responder is
performed by issuing an HTTP GET request to a URL constructed as the performed by issuing an HTTP GET request to a URL constructed as the
concatenation of the following components: concatenation of the following components:
o The responder's base URL. * The responder's base URL.
o The string "entities". * The string "entities".
For example, with a base URL of "http://example.org/mdq/", a query For example, with a base URL of http://example.org/mdq/, a query for
for all entities would be performed by an HTTP GET request to the all entities would be performed by an HTTP GET request to the
following URL: following URL:
http://example.org/mdq/entities http://example.org/mdq/entities
3.2.3. Response 3.2.3. Response
The response to a metadata query request MUST be a document that The response to a metadata query request MUST be a document that
provides metadata for the given request in the format described by provides metadata for the given request in the format described by
the request's Accept header. the request's Accept header.
The responder is responsible for ensuring that the metadata returned The responder is responsible for ensuring that the metadata returned
is valid. If the responder can not create a valid document it MUST 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 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 the case where the result of the query is metadata for multiple
entities but the request content type does not support returning entities but the request content type does not support returning
multiple results in a single document. multiple results in a single document.
3.2.4. Example Request and Response 3.2.4. Example Request and Response
The following example demonstrates a metadata query request using a The following example demonstrates a metadata query request using a
base URL of "http://metadata.example.org/service/" and the identifier base URL of http://metadata.example.org/service/ and the identifier
"http://example.org/idp". http://example.org/idp.
GET /service/entities/http:%2F%2Fexample.org%2Fidp HTTP/1.1 GET /service/entities/http:%2F%2Fexample.org%2Fidp HTTP/1.1
Host: metadata.example.org Host: metadata.example.org
Accept: application/samlmetadata+xml Accept: application/samlmetadata+xml
Figure 1: Example Metadata Query Request
Example Metadata Query Request
HTTP/1.x 200 OK HTTP/1.x 200 OK
Content-Type: application/samlmetadata+xml Content-Type: application/samlmetadata+xml
ETag: "abcdefg" ETag: "abcdefg"
Last-Modified: Thu, 15 Apr 2010 12:45:26 GMT Last-Modified: Thu, 15 Apr 2010 12:45:26 GMT
Content-Length: 1234 Content-Length: 1234
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<EntityDescriptor entityID="http://example.org/idp" <EntityDescriptor entityID="http://example.org/idp"
xmlns="urn:oasis:names:tc:SAML:2.0:metadata"> xmlns="urn:oasis:names:tc:SAML:2.0:metadata">
.... ....
Example Metadata Query Response Figure 2: Example Metadata Query Response
4. Efficient Retrieval and Caching 4. Efficient Retrieval and Caching
4.1. Conditional Retrieval 4.1. Conditional Retrieval
Upon a successful response the responder MUST return an ETag header Upon a successful response the responder MUST return an ETag header
and MAY return a Last-Modified header as well. Requesters SHOULD use and MAY return a Last-Modified header as well. Requesters SHOULD use
either or both, with the ETag being preferred, in any subsequent either or both, with the ETag being preferred, in any subsequent
requests for the same resource. requests for the same resource.
skipping to change at page 10, line 22 skipping to change at page 10, line 15
Requesters SHOULD support, and advertise support for, gzip Requesters SHOULD support, and advertise support for, gzip
compression unless such usage would put exceptional demands on compression unless such usage would put exceptional demands on
constrained environments. Responders MUST support gzip compression. constrained environments. Responders MUST support gzip compression.
Requesters and responders MAY support other compression algorithms. Requesters and responders MAY support other compression algorithms.
5. Protocol Extension Points 5. Protocol Extension Points
The Metadata Query Protocol is extensible using the following The Metadata Query Protocol is extensible using the following
protocol extension points: protocol extension points:
o Profiles of this specification may assign semantics to specific * Profiles of this specification may assign semantics to specific
identifiers, or to identifiers structured in particular ways. identifiers, or to identifiers structured in particular ways.
o Profiles of this specification may define additional paths (other * Profiles of this specification may define additional paths (other
than "entities" and "entities/") below the base URL. than entities and entities/) below the base URL.
6. Security Considerations 6. Security Considerations
6.1. Integrity 6.1. Integrity
As metadata often contains information necessary for the secure As metadata often contains information necessary for the secure
operation of interacting services it is RECOMMENDED that some form of operation of interacting services it is RECOMMENDED that some form of
content integrity checking be performed. This may include the use of content integrity checking be performed. This may include the use of
TLS at the transport layer, digital signatures present within the TLS at the transport layer, digital signatures present within the
metadata document, or any other such mechanism. metadata document, or any other such mechanism.
skipping to change at page 12, line 35 skipping to change at page 12, line 30
RFC 3986, DOI 10.17487/RFC3986, January 2005, RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>. <https://www.rfc-editor.org/info/rfc3986>.
[STD68] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax [STD68] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, Specifications: ABNF", STD 68, RFC 5234,
DOI 10.17487/RFC5234, January 2008, DOI 10.17487/RFC5234, January 2008,
<https://www.rfc-editor.org/info/rfc5234>. <https://www.rfc-editor.org/info/rfc5234>.
9.2. Informative References 9.2. Informative References
[md-query] [md-query] Young, I.A., Ed., "md-query Project",
Young, I., Ed., "md-query Project",
<https://github.com/iay/md-query>. <https://github.com/iay/md-query>.
[MDX.list] [MDX.list] Young, I.A., Ed., "MDX Mailing List",
Young, I., Ed., "MDX Mailing List",
<http://lists.iay.org.uk/listinfo.cgi/mdx-iay.org.uk>. <http://lists.iay.org.uk/listinfo.cgi/mdx-iay.org.uk>.
[REFEDS] Research and Education Federations, "REFEDS Home Page", [REFEDS] Research and Education Federations, "REFEDS Home Page",
<http://www.refeds.org/>. <http://www.refeds.org/>.
[REFEDS.agreement] [REFEDS.agreement]
Research and Education Federations, "REFEDS Participant's Research and Education Federations, "REFEDS Participant's
Agreement", Agreement",
<https://refeds.org/about/about_agreement.html>. <https://refeds.org/about/about_agreement.html>.
skipping to change at page 15, line 33 skipping to change at page 14, line 33
component. component.
Added the definition for the query for all entities in Section 3.2.2. Added the definition for the query for all entities in Section 3.2.2.
Corrected an example in Section 3.2.4 to include the required double Corrected an example in Section 3.2.4 to include the required double
quotes in the value of an ETag header. Added text to clarify the quotes in the value of an ETag header. Added text to clarify the
base URL and identifier being used in the example. base URL and identifier being used in the example.
Simplified the definition of identifiers, so that any non-empty Simplified the definition of identifiers, so that any non-empty
identifier is accepted and no semantics are defined for particular identifier is accepted and no semantics are defined for particular
structures. Extended syntaxes such as the "{sha1}" notation for structures. Extended syntaxes such as the {sha1} notation for
transformed identifiers are now left to profiles. transformed identifiers are now left to profiles.
Remove incidental references to SSL. Remove incidental references to SSL.
Remove status code 501 ("not implemented") as it is no longer Remove status code 501 ("not implemented") as it is no longer
referenced. referenced.
A.5. Since draft-young-md-query-03 A.5. Since draft-young-md-query-03
Correct a typo in the identifier grammar. Correct a typo in the identifier grammar.
skipping to change at page 17, line 17 skipping to change at page 16, line 17
No substantive changes. No substantive changes.
A.15. Since draft-young-md-query-13 A.15. Since draft-young-md-query-13
No substantive changes. No substantive changes.
A.16. Since draft-young-md-query-14 A.16. Since draft-young-md-query-14
No substantive changes. No substantive changes.
A.17. Since draft-young-md-query-15
No substantive changes.
Author's Address Author's Address
Ian A. Young (editor) Ian A. Young (editor)
Independent Independent
EMail: ian@iay.org.uk Email: ian@iay.org.uk
 End of changes. 36 change blocks. 
66 lines changed or deleted 68 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/