Subject: [httpapi] Benjamin Kaduk's Discuss on draft-ietf-httpapi-linkset-08: (with DISCUSS and COMMENT)

From: Benjamin Kaduk via Datatracker <[email-masked]>
Date: Wed, 02 Mar 2022 11:48:49 -0800

Benjamin Kaduk has entered the following ballot position for
draft-ietf-httpapi-linkset-08: Discuss

When responding, please keep the subject line intact and reply to all
email addresses included in the To and CC lines. (Feel free to cut this
introductory paragraph, however.)

Please refer to https://www.ietf.org/about/groups/iesg/statements/handling-ballot-positions/ 
for more information about how to handle DISCUSS and COMMENT positions.

The document, along with other ballot positions, can be found here:
https://datatracker.ietf.org/doc/draft-ietf-httpapi-linkset/

----------------------------------------------------------------------
DISCUSS:
----------------------------------------------------------------------

Since the downrefs that were omitted from the IETF Last Call announcement
are to documents published on the ISE stream, I would like to ensure that
the IESG specifically discusses that fact, as we determine whether or not
an additional IETF LC (corrected to indicate the downrefs) is needed.
If we knew that the referenced mechanisms already had IETF consensus, I
would be much less concerned about having the IESG approve the downrefs
without further community consultation.

I'd also like to have the authors double-check the Content-Length in the
HTTP response in Figure 10 (Section 7.2); my (admittedly hacky)
methodology produces a length of 1246 in contrast to the listed length of
1349.

----------------------------------------------------------------------
COMMENT:
----------------------------------------------------------------------

Thanks to Donald Eastlake for the secdir review.
It would be good to see a response to his comments (especially as they
relate to artwork line folding).

The ability to (more easily) provide third-party links seems to be the
main security-relevant consideration for this document, which raises
issues of trust that require serious consideration by applications
consuming such linksets.  I have some more thoughts in the
section-by-section comments.

I made a pull request on github with some editorial suggestions:
https://github.com/ietf-wg-httpapi/linkset/pull/64 .
There is perhaps a non-editorial change in the description of the
"hreflang" JSON representation, though I would argue that in essence it
is editorial since it just brings that definition in line with its sibling
elements' definitions.

Section 4.1

   When converting an "application/linkset" document to a field value
   for the HTTP "Link" header, newline characters SHOULD be removed in
   order to comply with Section 5.5 of [I-D.ietf-httpbis-semantics].

Removed, or replaced by SP?

Section 4.2

   The "application/linkset+json" serialization allows for OPTIONAL
   support of a JSON-LD [W3C.REC-json-ld-20140116] serialization.  This
   can be achieved by adding an appropriate context to the "application/
   linkset+json" serialization using the approach described in
   [W3C.REC-json-ld-20140116].  [...]

Perhaps we want a section reference to [W3C.REC-json-ld-20140116] here, or
to mention specifically the 'http://www.w3.org/ns/json-ld#context' link
relation, to be unambiguous about what behavior we are referencing.

Section 4.2.4.1

   *  "hreflang": The optional and repeatable "hreflang" target
      attribute MUST be represented by an array (even if there only is

Does "repeatable" refer to the abstract notion of hreflang attribute (as
might have been specified in RFC 8288 when it says "multiple hreflang
attributes on a single link-value"), or specifically to the encoding of
the attribute in the JSON representation?  I note that RFC 8259 clearly
states that the behavior of software is unpredictable in the face of
non-unique names in a single object (§4 of RFC 8259), and would be very
surprised if we were proposing to have multiple instances of the
"hreflang" member in a given link target object.  So, I mostly assume that
the "repeatable" part is just indicating that the value is an array, so
that multiple different values can be reflected, and not that the JSON
object member with name "hreflang" is repeatable in the JSON object.

   *  "title": The optional and not repeatable "title" target attribute
      MUST be represented by a "title" member in the link target object,
      and its value MUST be a string that follows the same model as in
      the [RFC8288] syntax.

RFC 8288 says that this string is "in the language indicated by the
Content-Language header field (if present)".  Do we inherit those
semantics as applies to the Content-Language header field on the HTTP
message that conveys the link set as its payload?  Can we make any
provision for cases where linkset documents are reused outside the context
of an HTTP interaction?

Section 4.2.4.2

   *  The character encoding information as prescribed by [RFC8187] is
      not preserved; instead, the content of the internationalized
      attribute is represented in the character encoding used for the
      JSON set of links.

I would be very interested to hear why this is believed to be appropriate
and correct behavior; RFC 8187 was only published 5 years ago and it's
fairly surprising for the field to have shifted so dramatically in so
little time.

Section 4.2.5

   The Web linking model ([RFC8288]) provides for the use of extension
   target attributes as discussed in Section 4.2.4.3.  No other form of
   extensions SHOULD be used.  [...]

This usage of the normative keyword is a somewhat awkward construction,
with the intended sense being a negated directive but the keyword being
the positive keyword.  Perhaps it's worth rephrasing to use "NOT
RECOMMENDED"?

                               This limitation of the JSON format allows
   to unambiguously round trip between links provided in the HTTP "Link"
   header field, sets of links serialized according to the "application/
   linkset" format, and sets of links serialized according to the
   "application/linkset+json" format.

I'm not actually convinced that we can unambiguously roundtrip through all
constructions that make use of the RFC 8187 character-encoding-escaping
mechanism with a JSON encoding that forces "native" encoding (of the
containing document) on all internationalized attributes.  In particular,
I think that the reencoding process would in practice have to pick a
particular normalization form, and originals that were encoded in a
different normalization form would not roundtrip faithfully.

Section 5

The ability to claim that multiple profiles are in use concurrently seems
to set us up for a situation where two profiles have conflicting
requirements and are both listed in the "profile" parameter of a given
message.  Should we say anything about how to handle such a situation as a
message recipient?

   The value of the "profile" parameter MUST be a non-empty list of
   space-separated URIs, each of which identifies specific constraints
   or conventions that apply to the link set document.  Profile URIs MAY
   be registered in the IANA Profile URI Registry in the manner
   specified by [RFC7284].

It's a little unusual to see a stasndards-track document use a registry
established by an ISE document, but I guess there's no point duplicating
it if it gets the job done...

Section 6

   A user agent that follows a "linkset" link MUST be aware that the set
   of links provided by the resource that is the target of the link can
   contain links in which the resource that is the context of the link
   does not participate; it MAY decide to ignore those links.

"MUST be aware" is a pretty hard requirement to enforce -- is software
really even "aware"? :)
Perhaps flipping things around a bit, to a declarative statement that the
set of links can include unrelated stuff and the user agent MUST process
both context and target of each link in the link set independently, and
MAY ignore ones deemed irrelevant, would help.  (E.g., "There is no
requirement that the set of links provided by the resource that is the
target of the link contains only links relating to the resource that is
the context of the link.  User agents MUST process each link in the link
set independently, including processing of link context and link target,
and MAY ignore links from the link set in which the context of the link
(to the link set) does not participate.")

Section 7.4.1

   Figure 14 shows the server's response to the request of Figure 13,
   including a "linkset" link with a "profile" attribute that has the
   Profile URI <https://www.gs1.org/voc/?show=linktypes> as its value.
   Dereferencing that URI yields a profile document that lists all the
   link relation types that a client can expect when requesting the link
   set made discoverable by the "linkset" link.  [...]

I am not sure if this is actually a great example to use.
I followed the profile URI to look at what link relation types that the
profile expects to use, and they all start with "gs1:" as rendered on the
page by my browser.  Since link relation types (per RFC 8288) are either
registered types or URIs to indicate extension types, that seems to
indicate that all these "gs1:activityIdeas", "gs1:allergenInfo", etc.,
would need to be URIs, and thus that "gs1:" would be the URI scheme for
them.  But "gs1" does not seem to be listed as a URI scheme at
https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml which
leaves me wondering if the example in this document is in some sense
"incomplete".  Perhaps the intent is that GS1 is actually using "https"
scheme URIs like https://gs1.org/voc/activityIdeas for the relation types
(as the "gs1:activityIdeas" text on the profile page is a hyperlink that
points to that resource), but there's very little to actually give that
indication to me as a reader.

Section 7.4.3

   Note that the response Figure 16 from the link set resource is
   equivalent to the response shown in Figure 17, which leverages the
   "profile" link relation type defined in [RFC6906].

In general there's a disincentive to provide multiple equivalent ways to
do the same thing, as it tends to require endpoints to implement all
alternatives in order to ensure interoperability.  What's the motivation
for offering both a dedicated link relation type and the media type
parameter for the linkset media types, versus just one or the other?

Section 9

I might consider noting that this specification is strict about certain
JSON elements always being encoded as arrays even when there is only a
single item, which simplifies parsers and provides some modest reduction
in risk as relates to implementation bugs.  It's not a terribly important
consideration, though.

   The security considerations of Web Linking [RFC8288] apply, as long
   as they are not specifically discussing the risks of exposing
   information in HTTP header fields.

The paragraph about '''Link header fields that use the "anchor" parameter
to associate a link's context with another resource cannot be trusted
since they are effectively assertions by a third party that could be
incorrect or malicious [...]''' from 8288 seems particularly relevant and
might be worth highlighting specifically.  (I do see the final bullet
point of this section, that is related.)

   and may not be sufficiently protected.  Ideally, none of the URIs
   exposed in links should be supposed to be "hidden"; instead, if these
   URIs are supposed to be limited to certain users, then technical
   measures should be put in place so that accidentally exposing them
   does not cause any harm.

Here we say "if these URIs are supposed to be limited", but do we mean
"the resources identified by these URIs"?

   *  The Web Linking model always has an "implicit context", which is
      the resource of the HTTP interaction.  This original context can
      be lost or can change when self-contained link representations are
      moved.  Changing the context can change the interpretation of
      links when they have no explicit anchor, or when they use relative
      URIs.  [...]

I feel like it would be appropriate to highlight that changing the context
is likely to change the semantics indicated by the link (and thus break
the intended meaning), such that the default/safe behavior needs to be to
ignore such links unless there is a reliable source of link context
external to the document itself.

   *  The model introduced in this specification supports "3rd party
      links", where one party can provide links that have another
      party's resource as an anchor.  Depending on the link semantics
      and the application context, it is important to verify that there
      is sufficient trust in that 3rd party to allow it to provide these
      links.  [...]

In the vein of my earlier comment, I think it would be helpful to supply
some additional background/context on the topic, maybe in this part of the
text, or maybe elsewhere.  I'm thinking something like:

% There is no fundamental notion of "authority" for a third party to
% provide links about resources other than itself.  In the original
% [RFC8288] Web Linking model, links are provided with an implicit
% context that is the resource providing a link (though an explicit
% context can sometimes be provided instead).  In that model, a resource
% is inherently the authority for its own links, and a certain amount of
% trust can be placed in the provided links.  There is no such inherent
% trust when third-party links are used, and so in order for third-party
% links (as specified in this document) to be trustworthy, an external
% source of trust is needed.  This might be achieved in an out-of-band
% manner, with a given client configured to trust a particular entity to
% provide links about a certain class of resources, or by various implicit
% means.  For example, if a resource provides a link of relation type
% "linkset", that might be seen as a delegation of authority for providing
% trustworty link information to the target of the "linkset" link (subject
% to the caveats in Section 7.1 of [RFC3986] about the lack of reliability
% and consistency of a resource identified by a URI), at least for links
% that relate to the original resource, and [RFC8288] proposes that some
% applications might be willing to treat "share the same authority [URI
% component]" as an indication that a link relating a different resource
% might be trustworthy.  The notion of "trust" in a link is a complicated
% subject, and there is no single approach for it that applies universally
% to all applications.

Section 10

Since RFC 6690 is mentioned only to make a contrast to the mechanisms
defined in this document, it seems better classified as an informative
reference.

Section 11

I agree with Roman that [W3C.REC-json-ld-20140116] is more properly
classified as a normative reference.

Appendix A

(I don't know much about JSON-LD or Dublin Core Terms, so my review of
this part was pretty superficial.)

NITS

Section 4.2.2

   *  Each link context object MAY contain an "anchor" member with a
      value that represents the link context.  If present, this value
      MUST be a URI reference and SHOULD NOT be a relative reference as
      per Section 4.1 of [RFC3986].

It's easy to parse this statement as saying that RFC 3986 is providing
support for the "SHOULD NOT" requirement, whereas we're really just using
it as the reference for "relative reference".  Maybe s/per/defined in/, or
just "relative reference (Section 4.1 of [RFC3986])"?
(The phrasing/construct in question appears later on as well, though I'll
just remark on it once, here.)

---

From: Herbert Van de Sompel <[email-masked]>
Date: Tue, 8 Mar 2022 12:09:16 +0100

hi Benjamin,

Your Discuss items were addressed. Your comments were addressed either by
edits to the I-D or by feedback provided below under "Response". New I-D
version at
https://github.com/ietf-wg-httpapi/linkset/blob/master/draft-ietf-httpapi-linkset-09.xml

Greetings

Herbert

===============

Section 4.1

Response: Both are fine. Language adjusted.

===

Response: What RFC8288 has to say about this remains valid for every single
link in a linkset, i.e. when visiting the target of a specific link. It's
not clear how Content-Language provided when interacting with a linkset
could possibly apply to the respective "title" attributes for all links in
a linkset. That would be as if the Content-Language for an HTML page would
apply to each linked resource in that page.

===

Section 4.2.4.2

Response: RFC8187 is about character encoding and language for HTTP header
field parameters, not about character encoding in JSON documents. Using
character encoding conventions for JSON seems appropriate for a JSON
serialization of linksets.

related comment:

Response: Francesca asked an expert review re internationalization; we
assume that will provide guidance.

===

Section 5

Response: The approach follows established practice, see e.g. the "profile"
attribute for json-ld at
https://www.w3.org/TR/json-ld11/#iana-considerations

====

Section 7.4.1

Response: Clarified in the description of Figure 14 where the actual link
relations URIs are.

===

Section 7.4.3

Response: We expect the "profile" attribute for the linkset media types to
be a preferred implementation choice because it can be used both when
making a linkset discoverable (Figure 14) and when interacting with it
(Figure 16). Use of the "profile" link relation type is shown in Figure 16
for completeness. It can, however only be used when interacting with the
linkset resource.

===

Section 9

Response: Addressed by adding reference to (Section 7 of) RFC3986 as
recommended by Roman Danyliw

================

On Wed, Mar 2, 2022 at 8:48 PM Benjamin Kaduk via Datatracker <
[email-masked]> wrote:

> Please refer to
> https://www.ietf.org/about/groups/iesg/statements/handling-ballot-positions/
> --
> httpapi mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/httpapi
>

-- 
==================
Herbert Van de Sompel
https://hvdsomp.info
https://orcid.org/0000-0002-0715-6126

---

From: Benjamin Kaduk <[email-masked]>
Date: Mon, 14 Mar 2022 17:49:06 -0700

Hi Herbert,

Thanks for the explanations and link to the current editor's copy.
In general, things look good; just a few more notes inline...

> https://github.com/ietf-wg-httpapi/linkset/blob/master/draft-ietf-httpapi-linkset-09.xml

I agree it would be weird to try to apply the processing in this way; I'm
just pointing out that my interpretation of the "words on the page"
combined between this document and RFC 8288 for me to attempt to apply that
processing.  I hope that implementors do the right thing, but it it often
prudent to provide specific guidance when there is known risk of
misinterpretation.

> assume that will provide guidance.

I'm happy to defer to the internationalization experts, being only an
amateur (at best) myself.

> https://www.w3.org/TR/json-ld11/#iana-considerations

Forgive my bluntness, but it's possible for "established practice" to still
have risk of problems.  There have been a number of major security
vulnerabilities over the years that stem from a researcher discovering that
the "established practice" has weaknesses, after all.
That said, I am not going to insist on any change here.

> Response: Clarified in the description of Figure 14 where the actual link

Thank you!

> recommended by Roman Danyliw

I would have liked to see more added to this document, but I can accept
your choice.

In combination with the ongoing last-call, the changes in the editor's copy
address my DISCUSS concerns, so I will go change my ballot position to No
Objection now.

Thanks again,

Ben

---

From: Herbert Van de Sompel <[email-masked]>
Date: Wed, 23 Mar 2022 16:09:19 +0100

hi Benjamin,

The remaining issues were addressed as described below.

Greetings

Herbert

> prudent to provide specific guidance when there is known risk of
Addressed in commit
https://github.com/ietf-wg-httpapi/linkset/commit/09d35e9cff6105ddc1ff7711a6f09294798f52b3
.
Made clear that title language is not inherited from Content-Language (and
why) and recommended using "title*" instead of "title" because "title*"
allows to explicitly provide title language as part of the attribute value.
In order not to have to repeat this (and another aspect related to use of
link sets outside the context of an HTTP interaction) in both sections 4.1.
and 4.2, the info is provided in the opening of section 4. This required
moving some existing language from 4.1 and 4.2 to the intro of 4.

> That said, I am not going to insist on any change here.
Addressed in commit
https://github.com/ietf-wg-httpapi/linkset/commit/834e24005e6e4dbccb292707fdc0ce58ee9b3724
.
Added language to indicate that care must be taken not to have conflicting
profiles when  providing multiple Profile URIs.

====================================================