iay / md-query Goto Github PK

The word "query" in the title, while accurate, leads some people to believe that an implementation needs to support arbitrarily complex query semantics, with the associated resource implications. Our starting point has always been that queries in that sense are out of scope, but the document itself does not appropriately set expectations.

The older xml2rfc v2 markup format I am using is deprecated. Although it is still accepted by the I-D submission system, it's described as "(You may submit an older xml2rfc version 2 file if you must.)" which I think implies that I should convert.

Note that the 2.9.x version of xml2rfc I am using is provided through MacPorts and does not support the new format so I will need to migrate to the separate installation.

Makes sense to do this after the -18 revision is done.

We refer to two specific transformations (MD5 and SHA-1) without normative references to the associated specifications.

We originally intended that the /entities endpoint (without any '/' followed by an identifier) should return an "all entities" aggregate. That seems to have been lost along the way, although as I understand it Leif's implementation already does this.

So, add this back in to the formal specification.

The current draft says that requesters MUST use HTTP/1.1 or later, which is fair enough: this permits a server to not implement HTTP/1.0 support.

However, the draft also puts a MUST requirement on the server to respond with a 505 status if HTTP/1.0 is used. That's not the same thing and it's not clear why that requirement is there as it seems like an implementation detail.

I'm not aware of any current implementations implementing this requirement correctly.

We should reconsider the MUST 505 requirement. Removing that requirement would not invalidate any implementations currently implementing it properly, but it would simplify the job of writing new clients.

Another aspect we should consider is how hard it is to implement this requirement in the usual server environments (Apache, Tomcat, Jetty, etc.).

"4.1. Conditional Retrieval" reads:

Upon a successful response the responder MUST 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.

RFC2616 says in 13.3.4:

If an entity tag has been provided by the origin server, MUST
use that entity tag in any cache-conditional request (using If-
Match or If-None-Match).

Ie. it is mandatory to use the ETag if provided and "2.5. Response Headers" mandates it's
provision.

So 4.1 should read:

"Upon a successful response the responder MUST return an ETag header and MAY return a Last-Modified header as well. Requesters SHOULD use the ETag or both, in any subsequent requests for the same resource."

The mime type for saml-metadata is the same both for an entitydescriptor and an entitiesdescriptor. I'm not sure how big a problem this is but section 3.2.2 (response) seems to indicate that you should use content negotiation to indicate if you want exactly one entity.

I read the HTTP RFC as specifying that ETag values must be quoted. The example in md-query has this:

ETag: abcdefg

This should be:

ETag: "abcdefg"

The RFC7230–7235 references in the current document should be replaced by references to the current specs, which are in RFC9110–9112.

Although we have a prohibition against document fragments in the base URL, we don't include anything similar for the query string although we didn't intend it to be allowed. This should be clarified.

The text says that all responses SHOULD include the Cache-Control header, but our example does not.

The documents are still missing the REFEDS boilerplate text.

Should review the text against:

• BCP 56
• RFC 3205
• https://tools.ietf.org/html/draft-ietf-httpbis-bcp56bis-03

This is a placeholder for resolving this thread: http://lists.iay.org.uk/pipermail/mdx-iay.org.uk/2011-May/000141.html

The example request and response in section 3.2.3 are presented without context. It would be clearer to include at least a statement that this was a query with a given base URL and identifier.

The text currently sais "If the responder can not create a valid document it MUST respond with a 500 status code." To me it feels more sensible to use 400 (Bad Request) for that error to distinguish it from any other server-related problem, crash etc.

It would be nice

To add a non-normative OAS spec to describe the protocol endpoint.

Not all MDX-endpoints will be able to serve all metadata formats. Already there is talk in the discojuice project (for instance) about using MDX as a way to query for JSON-based derivatives from SAML metadata.

It would be useful to be able to ask an MDX server about certain basic capabilities it supports, for instance (not having completely thought any of these through):

• mime types
• well known entity attributes
• trust anchors

The spec as currently drafted relies on STD66's notion of percent-encoding IDs. That encoding scheme has some deliberate ambiguity in terms of what specific string should result from encoding.

For example, although some characters (e.g. \) MUST be percent-encoded, any character MAY be percent-encoded. This means that an MDQ responder MUST regard the following as equivalent:

foo:bar
foo%3Abar

The A to F characters in the encoding MAY also appear as a to f without changing the semantics. STD66 says that encoders "should" (note, not even SHOULD) use upper case, but the result is that an MDQ responder MUST regard the following as equivalent:

foo%2fbar
foo%2Fbar

This is easy for an "active" MDQ responder implementation to deal with. It's harder for people who are trying to implement MDQ by just putting a set of carefully named files behind a standard web server.

In practice, most encoders appear to use upper case. It's not guaranteed, though, and this may cause compatibility issues. It's probably worth at least highlighting this behaviour in the MDQ base spec. I don't think it's worth profiling STD66 within MDQ such that upper case is required (and over-encoding is forbidden) but that might be a discussion to have.

The spec has taken long enough to develop that the underlying definition of HTTP/1.1 has been modernised. We should probably refer to the new RFC set, see RFC2616 is Dead.