_who_ "hosts" something. In link-format serialization, it is expressed in the "anchor" <del> attribute.  It defaults to that document's URI. </del>  A link target URI: It defines the destination of the relation (e.g. _what_ is hosted), and is the topic of all target (as described in I-D.bormann-t2trg-rel-impl): Note that depending on the particular server's architecture, such a <del> link could be anchored at the RD server's root, at the discovery site (as in this example) or at individual RD components.  The latter is to be expected when different applications are run on the same server. </del>  5. address and scheme. For media types to which limitedlinkformat applies (i.e. documents in <del> application/link-format), the RD only needs to accept representations in Limited Link Format as described there.  Its behavior with representations outside that subset is implementation defined. </del>  The registration request interface is specified as follows: which the registration request is received. Endpoints that register with a base that contains a path <del> component cannot meaningfully use RFC6690 Link Format due to its prevalence of the Origin concept in relative reference resolution.  Those applications should use different representations of links to which limitedlinkformat is not applicable (e.g.  I-D.hartke-t2trg-coral). </del>  Additional registration attributes (optional).  The endpoint can pass any parameter registered at iana-registry to the lifetime (lt)=500 <del> Base URI (base)=coap://local-proxy-old.example.com:5683 </del>  payload of Resource lookup results in links that are semantically equivalent to the links submitted to the RD by the registrant.  The links and link parameters returned by the lookup are equal to the originally <del> submitted ones, except that the target and anchor references are fully resolved. </del>  <del> Links that did not have an anchor attribute are therefore returned with the base URI of the registration as the anchor.  Links of which href or anchor was submitted as a (full) URI are returned with these attributes unmodified. </del>  The above rules allow the client to interpret the response as links without any further knowledge of the storage conventions of the RD. otherwise. Links to endpoints SHOULD be presented in path-absolute form or, if <del> required, as (full) URIs.  (This avoids the RFC6690 ambiguities.) </del>  Base addresses that contain link-local addresses MUST NOT include zone identifiers, and such registrations MUST NOT be shown unless the 12.  changes from -25 to -26 Security policies:

This is fixing as set out in URL Still marked as a draft as the outstanding changes are still: [ ] Adjusting the examples (along with all the other pending example fixes) [ ] Adjusting the appendix texts [ ] Read through it once more because that doesn't happen in the first pass.
This PR now executes the steps set out in URL and should resolve all of NAME example items -- most of it is about not having to repeat the anchor again all the time.
thanks, this looks good.
Looking in the master branch .md doc: some examples use a coap:// URI (not secure) that use the port 5684, which is normally reserved for coaps:// (secure). Better use other port numbers for these examples, e.g. ones in the dynamic range, or currently unallocated ones?
I think for the next I-D I'll be doing examples in, I'll just write a script that sets up the examples in an implementation and sniffs out the examples content. Thanks for spotting yet another case of example inconsistency. (Those should be using coaps as that's what the base URI is updated to).
Link Format doesn't require the quote characters (") for an attribute value for rt and if attributes, in case just a single value is encoded. So e.g. from an example in the draft could be: I presume above would be a typical encoding by the RD, going for the most efficient one. (As a side note: leaving out the quote characters only works for non-URI values, see URL . But that's the case here.)
In Appendix B.2: It looks like /t is an alternative for /sensors/temp , but there's no resource /sensors/temp. For clarify maybe replace to Also in the text below it; replace all "/sensors/temp" by "/temp" then.
(Sorry for not making a pull request of this - Github doesn't allow me to, it seems.) Existing master branch text: ~ Proposed update: ~ (Note: 'rt' are unquoted here following shortest RFC6690 allowed encoding of 'rt'. Other attributes may be unquoted also per RFC 6690 but I wasn't sure what is best here.)
In many examples, the "anchor" attribute is included if the target URI of the link is an absolute URI. For example like below: Here the anchor is not needed because the origin of the target URI already specifies the context/anchor; per RFC 6690 URL rule (b) . For constrained devices and networks it is very important to minimize the payload sizes where possible, so I think the RD SHOULD in this case return the most efficient form possible by leaving out the anchor parameter per link where this is unnecessary to include. New proposed text of above example: And similar changes to be made for other examples. Also I'd like to note that including the anchor additionally with the same information seems strange, given that the "hosts" relation type was defined as it is to get rid of the anchor in most cases - serving the needs of constrained systems.
Result of the last interim's discussion was that yes we can go ahead with this (after checking through the implementations list again and making the adequate changes to the text). I'm holding off the other "examples" fixes (, , , ) for then to keep the diffs more readable.
For my reference, what needs checking is the list at URL against the current understanding.
Fixed in eb62d317c4d9a650002bcee8c8fcc619134b7c4c Hello CoRE group, I'm looking for and evaluating implementations of the RFC6690 discovery process to help making decisions on the document formats usable for the Resource Directory. So far, I'm aware of RIOT, URL, Copper4Cr, leshan, wakaama, ncoap, californium, CoAP.NET, and the coap Ruby gem. I've also looked at other SDO's use of 6690: OMA LWM2M appears not to use anchor at all[8]. OCF are the first I found who actually build a link from resolving the href relative to the anchor (which is one of the RFC6690 peculiarities I'm trying to find users of), but use a serialization that is neither RFC6690 nor links-json exactly (judging from [9]). Please send me any links you have on consumers of link-format data, producers of link-format data that actually output anchor values, or other SDOs that rely on the precise resolution rules of RFC6690. Thanks in advance Christian Notes from looking through the known ones: RIOT: Tested by advertising an RD with instead of (which are equivalent in 6690); then it fails to register. Copper4Cr: not tested, but the absence of 'anchor' in [1] and its callers indicates it won't represent links correctly when anchor is set (and does not ignore them if it can't handle them either). leshan: like Copper, see [2], plus tokenizes wrongly. wakaama: like Copper, see [3] ncoap: similar to Copper, see [4], though to be fair, it exposes the URI via a getUriReference indicating the caller would need to know how to resolve it. I found no caller whom I could check for whether it's using it right. californium: similar situation, see [5]. The href gets passed out as a WebLink, whose getURI method only considers the href. CoAP.NET: I don't grade copied homework, please look at californium's sheets coap Ruby gem: same situation at [7], href is passed out as uri via accessor while anchor is passed along in atteribute if present. I had looks at contiki, libcoap, lobaro, txThings -- but none of them appears to implement link-format parsing in the library. [1]: URL [2]: URL [3]: URL [4]: URL [5]: URL [6]: URL [7]: URL [8]: URL [9]: URL To use raw power is to make yourself infinitely vulnerable to greater powers. -- Bene Gesserit axiom
Hello Reviewers, CoRE and IESG members, thanks for your input to the Resource Directory document, and your patience while it was being processed. Before the individual point to point responses can go out, this mail is to address the general status, and answer a few points that were brought up by different reviewers (it will be referred back to in the point to point responses). In summary, the points raised in the reviews led to the changes of the recently uploaded [-26], and where no changes were made, the reasoning behind the choices in the document is outlined below or in the following mails. (Either way, short of aggregated nits paragraphs, all points are responded to in the following mails). A few larger issues evolved from the review comments being discussed in the interim meetings, so please expect a -27 at a later point (after IETF109) with the changes mentioned below. Kind regards Christian [-26]: URL Preface References into the issue tracker are primarily intended for bookkeeping and to give you access to the altered text if you're curious -- but for general review purposes, the responses are self-contained. Anticipated changes We have opted to submit a new version that should clear out all the other comments, so that the remaining work can be focused and swift: Replay and Freshness (OPEN-REPLAY-FRESHNESS) The comment on DTLS replay made us reevaluate the security properties of operations on the registration resource. While these are successively harder going from DTLS without replay protection to DTLS with replay protection and hardest with OSCORE, the text as it is is still vulnerable to an attacker stopping a reoccurring registration, or undoing alterations in registration attributes. Mitigation from a concurrent document (the Echo mechanism of I-D.ietf-core-echo-request-tag in event freshness mode) is planned, but the text is not complete yet. Necessity of the value in all responses The requirements around Limited Link Format and the necessity to express all looked up links in fully resolved form have stemmed from different ways RFC6690 has been read, both in the IETF community and by implementers. A comment from Esko Dijk has shown a clear error in one of the readings. That reading is single-handedly responsible for most of the overhead in the wire format (savings can go up to 50%), which is of high importance to the CoRE field. Due to that, it is the WG's and authors' intention to remove the reading from the set of interpretations that led to the rules set forth. The change will not render any existing RD server implementation incompatible (older RDs would merely be needlessly verbose), and the known implementations of Link-Format parsers can easily be updated. The updates to the document could not be completed in time with the rest of the changes, because a) it requires revisiting the known implementations for confirmation and b) will affect almost every example that contains lookup results. Server authorization (OPEN-SERVER) The two areas of "how is the RD discovery secured" and "what do applications based on the RD need to consider" jointly opened up new questions about server authorization and the linkage between a client's intention and the server's promises that may easily not conclusde in timeframe reasonable for RD. While steps have been taken to address the issue both on the RD discovery and the applications side (URL), the ongoing discussions in the working group may turn up with a less cumbersome phrasing for these parts. There's a few small open issues Esko brought up on the issue tracker that could not be addressed in time; most of them are about enhancing the examples, which best happens after the anchor cleanup anyway. Repeated topics A few common topics came up in multiple reviews, and are addressed in the following section; the individual responses can be found in follow-up mails, and refer to the common topics as necesary. GENERIC-FFxxDB "Where do the ff35:30:2001:... addresses come from?" response: There's a coverage gap between RFC3849 (defining example unicast addresses) and RFC3306 (defining unicast-prefix-based multicast addresses). For lack of an agreed-on example multicast address, the used ones were created by applying the unicast-prefix derivation process to the example address. The results (ff35:30:2001:db8::1) should be intuitively recognizable both as a multicast address and as an example address. The generated address did, however, fail to follow the guidance of RFC 3307 and set the first bit of the Group ID. Consequently, the addresses were changed from ff35:30:2001:db8::x to ff35:30:2001:db8::8000:x, which should finally be a legal choice of a group address for anyone operating the 2001:db8:: site. (The changes can be viewed at URL). GENERIC-6MAN "Whas this discussed with 6MAN?" response: Not yet; a request for feedback was sent out recently. (Mail at URL). GENERIC-WHOPICKSMODEL "How does the client know which security policies the RD supports?" response: The client can only expect any level of trustworthiness if there is a claim to that in the RD's credentials. Typically, though, that claim will not be encoded there, but implied. For example, when configuring an application that relies authenticated endpoint names, then telling the application to use the RD authenticated via PKI as URL should only be done if the configurator is sure that URL will do the required checks on endpoint names. Some clarification has been added in URL GENERIC-SUBJECT "Section 7.1 says: '... can be transported in the subject.' -- where precisely?" response: That text was only meant to illustrate to the reader what such a policy could contain, not to set one (which would require more precision). It has been made more explicit that this is merely setting the task for the policies. As an example, some more precision is given by referring to SubjectAltName dNSName entries. Changes in URL (If you have read up to this point, please continue reading the follow-up mails addressing the individual reviewer's points.)

_who_ "hosts" something. In link-format serialization, it is expressed in the "anchor"  <ins> attribute and defaults to the Origin of the target (practically: the target with its path and later components removed) </ins> A link target URI: It defines the destination of the relation (e.g. _what_ is hosted), and is the topic of all target (as described in I-D.bormann-t2trg-rel-impl): Note that depending on the particular server's architecture, such a  <ins> link could be anchored at the RD server's root (as in this example), or at individual RD components.  The latter is to be expected when different applications are run on the same server. </ins> 5. address and scheme. For media types to which limitedlinkformat applies (i.e. documents in  <ins> application/link-format), request bodies MUST be expressed in Limited Link Format. </ins> The registration request interface is specified as follows: which the registration request is received. Endpoints that register with a base that contains a path  <ins> component cannot efficiently express their registrations in Limited Link Format (limitedlinkformat).  Those applications should use different representations of links to which limitedlinkformat is not applicable (e.g.  I-D.hartke-t2trg- coral). </ins> Additional registration attributes (optional).  The endpoint can pass any parameter registered at iana-registry to the lifetime (lt)=500  <ins> Base URI (base)=coap://local-proxy-old.example.com </ins> payload of Resource lookup results in links that are semantically equivalent to the links submitted to the RD by the registrant.  The links and link parameters returned by the lookup are equal to the originally  <ins> submitted ones, except that the target reference is fully resolved, and that the anchor reference is fully resolved if it is present in the lookup result at all. </ins>  <ins> Links that did not have an anchor attribute in the registration are returned without an anchor attribute.  Links of which href or anchor was submitted as a (full) URI are returned with the respective attribute unmodified. </ins> The above rules allow the client to interpret the response as links without any further knowledge of the storage conventions of the RD. otherwise. Links to endpoints SHOULD be presented in path-absolute form or, if  <ins> required, as (full) URIs.  (This ensures that the output conforms to Limited Link Format as described in limitedlinkformat.) </ins> Base addresses that contain link-local addresses MUST NOT include zone identifiers, and such registrations MUST NOT be shown unless the 12. <ins> changes from -26 to -27 Relaxation of the serialization rules for link-format The interpretation of RFC6690 used in resolution-rules was shown to be faulty.  Along with a correction, the common implementations of link-format were surveyed again and it was found that the only one that employed the faulty interpretation can still safely be upgraded.  These were removed from the set considered for Limited Link Format, making the set of valid Limited Link Format documents larger. As a consequence, the prescribed serialization of RD output can be roughly halved in bytes. There might be additional usage patterns that are possible with the new set of constraints, but there is insufficient implementation and deployment experience with them to warrant a change changes on that front at this point.  The specification can later be extended compatibly to allow these cases and drop the requirement of Limited Link Format. </ins> changes from -25 to -26 Security policies:


In the context of an RD, a sector is a logical grouping of <del> endpoints. The abbreviation "d=" is used for the sector in query parameters for compatibility with deployed implementations. </del>  Endpoint (EP) is a term used to describe a web server or client in The target of a link is the destination address (URI) of the link. It is sometimes identified with "href=", or displayed as "<target>".  Relative targets need resolving with respect to the <del> Base URI (section 5.2 of RFC3986). This use of the term Target is consistent with RFC8288's use of the term. </del>  The context of a link is the source address (URI) of the link, and describes which resource is linked to the target.  A link's context is made explicit in serialized links as the "anchor=" <del> attribute. This use of the term Context is consistent with RFC8288's use of the term. </del>  A resource in the RD containing registration resources.

I had hoped we could come up with something that preserves HTML's semantics of both dd pertaining to the single dt, but this solves the ugly plain text newlines and is probably the best that can be done without larger changes in the RFC toolchain. Thanks, merged.
The nits of URL COMMENT can't currently be addressed easily; looking for help at URL which currently blocks this. Thank you for the work put into this document. As you can noticed, I have cleared my 2 DISCUSS points (kept below for archive) thank you also for replying to my comments over email. BTW, I appreciated the use of ASCII art to represent an entity-relationship diagram ! I hope that this helps to improve the document, -- Section 4.1 -- It will be trivial to fix, in IPv6 address configuration (SLAAC vs. DHCP) is orthogonal to DHCP 'other-information'. E.g., even if address is configured via SLAAC, DHCPv6 other-information can be used to configure the Recursive DNS Server (or possibly the RD). -- Section 4.1.1 -- Another trivial DISCUSS to fix: in which message is this RDAO sent ? I guess unicast Router Advertisement but this MUST be specified. In general, I wonder how much interactions and exchanges of ideas have happened in the long history of this document with the DNSSD (DNS Service Discovery) Working Group that has very similar constraints (sleeping nodes) and same objectives. -- Section 2 -- To be honest: I am not too much an APP person; therefore, I was surprised to see "source address (URI)" used to identify the "anchor="... I do not mind too much the use of "destination address (URI)" as it is really a destination but the anchor does not appear to me as a "source address". Is it common terminology ? If so, then ignore my COMMENT, else I suggest to change to "destination URI" and simply "anchor" ? -- Section 3.3 -- Should the lifetime be specified in seconds at first use in the text? -- Section 3.6 -- Is the use of "M2M" still current? I would suggest to use the word "IoT" esp when 6LBR (assuming it is 6LO Border Router) is cited later. Please expand and add reference for 6LBR. Using 'modern' technologies (cfr LP-WAN WG) could also add justification to section 3.5. -- Section 4.1 -- About "coap://[MCD1]/.well-known/core?rt=core.rd*", what is the value of MCD1 ? The IANA section discuss about it but it may help the reader to give a hint before (or simply use TBDx that is common in I-D). Any reason to use "address" rather than "group" in "When answering a multicast request directed at a link-local address" ? Later "to use one of their own routable addresses for registration." but there can be multiple configured prefixes... Which one should the RD select ? Should this be specified ? As a co-author of RFC 8801, I would have appreciated to read PvD option mentionned to discover the RD. Any reason why PvD Option cannot be used ? -- Section 4.1.1 -- I suggest to swap the reserved and lifetime fields in order to be able to use a lifetime in units of seconds (to be consistent with other NDP options). -- Section 5 -- May be I missed it, but, can an end-point register multiple base URI ? E.g., multiple IPv6 addresses. -- Section 9.2 -- For information, value 38 is already assigned to RFC 8781. -- Section 2 -- The extra new lines when defining "Sector" are slighly confusing. Same applies to "Target" and "Context". This is cosmetic only.

In the context of an RD, a sector is a logical grouping of  <ins> endpoints.  The abbreviation "d=" is used for the sector in query parameters for compatibility with deployed implementations. </ins> Endpoint (EP) is a term used to describe a web server or client in The target of a link is the destination address (URI) of the link. It is sometimes identified with "href=", or displayed as "<target>".  Relative targets need resolving with respect to the  <ins> Base URI (section 5.2 of RFC3986).  This use of the term Target is consistent with RFC8288's use of the term. </ins> The context of a link is the source address (URI) of the link, and describes which resource is linked to the target.  A link's context is made explicit in serialized links as the "anchor="  <ins> attribute.  This use of the term Context is consistent with RFC8288's use of the term. </ins> A resource in the RD containing registration resources.


The location of the LWM2M Server and RD base URI path is provided by the LWM2M Bootstrap process, so no dynamic discovery of the RD is used.  LWM2M Servers and endpoints are not required to implement the <del> ./well-known/core resource. </del>  10.2.1.

This pull request contains edits to resolve my comments earlier; these here address the uncontroversial points .
As we support the alternative serializations from draft-ietf-core-links-json, I'd like to add at least the numbers in the RD lookup examples.
Use TBD64 etc., as discussed in the call.
There has been confusion about the semantics of an absent in the presence of transient ports ( first paragraphs, 5.3 HTTP example). Proposed solution: more explicit wording about con= being practically required when transient ports are used.
The wording has already been strengthened in -10; can be closed when the examples are adapted.
Closing comment was missing on 132d5c3145e6f8b3ebe568f560e922fc70b2085d; keeping the issue open until Carsten's comments in URL are resolved. Hello Peter, among those, I just happened to note that instead of (say) being advertised as URL (which would then have triggered string-appending "/ep" to it), the individual records are now advertised. Much appreciated; this makes implementation of resource trees smoother! (Actually I found an inconsistency of my implementation of -09, and looking it up, it was fixed in this version I had not read before). It does add one easily fixed quirx, however: In the lookup URI template, there's now /{+rd-looup-base}/{lookup-type}. Is that distinction still needed? The base can't be discovered now any more, so I'd say this now should be | URI Template: /{+type-lookup}{?d,...} | | type-lookup := RD lookup location (mandatory). Discovered for a given | type in .well-known/core by its resource type, where it SHOULD be | listed. The recommended value for this variable is: | "/rd-lookup/{type}". Mandatory to be present for types "ep" and | "res", optional for "d" and "gp". (Or maybe you they can stay "base URIs", but be many; that's only terminology then). I've gone through the rest of the document; "is used to discover the base URI for RD Lookup operations" would need to speak of "URIs". Sounds good now. The term "Simple directory discovery" was dropped from the descriptions but survived in 5.3.3; it should probably say "simple registration" there. Other notes (some on nitpicking level, but if we're at WGLC level I suppose that's OK): 5.2 mentions '"URL" is used to discover the base URI for RD group operations'. Shouldn't this be "URL"? (Unsure as not yet really familiar with all the groupcom things). 5.2 lists HTTP support but no HTTP response codes 5.2 first request/response example: needless quotes about a ct 5.3 example: The HTTP requester will probably want to set a con= too unless it actually sends the HTTP request from its port 80. 'The domain lookup returns every lookup domain with a base RD resource value (e.g. "/rd") encapsulated within angle brackets.' (and similarly the following group paragraph): This sounds contradictory to the example given later (which returns '<>;d="domain1"'), where nothing is encapsulated in the angle brackets. 9.3 "con" entry: Since the latest changes this should include "path" too. 10.1.2: In the requests from the CT, the domain parameter is given per-resource in the payload. Isn't that exclusively used as a query parameter in registration? Later in the group setup POST, the semicolons after the <> are missing in the payload, and the colon in 'coap//' in the con parameter, which has abundant quotation marks. 10.2: "./well-known/core" -> "/." I haven't updated my implementation yet, but don't see any trouble on that road. Looks good to me, all things considered. Best regards Christian To use raw power is to make yourself infinitely vulnerable to greater powers. -- Bene Gesserit axiom
Hi Christian, Thank for the feedback; see below. Christian Amsüss schreef op 2017-03-16 17:43: Good to read. URIs it will be; rd-lookup-base is also used later; and is an understandable concept. agreed. not yet. No opinion. see what the co-authors think. Correct; correct, again. good suggestions Yep, have to solve that one way or the other. mistakes come and go, in spite of github change it, thanks for looking at it. thanks again. there is also another instance; also here mistakes come and go. Many thanks, peter
Hi Christian Okay, I was clearly using these libraries incorrectly (create a client context - with a transient port - to register and a server context to handle queries). I now have my code working correctly using only the server context. I know it's implied, but could it be made more explicit in the spec as In the absence of this parameter the scheme of the protocol, source IP address and source port of the register request are assumed. The request should not be sent from a transient port, the registering agent is expected to be an endpoint for that scheme, IP and port. I'm thinking of someone just querying /.w-k/c, without a filter. They will see all /rd/xxxx resources, even if they don't know their type. Yes, the endpoint registering the resource is expected to use this when updating or removing the registration. Maybe I'm reading more into the spec than I should, but I'm thinking that no-one else apart from the original registering endpoint should be able to modify/delete the resources. Eventually that comes down to security but using obscurity through non-visibility helps achieve this. Cheers Jan Dr Jan Newmarch

The location of the LWM2M Server and RD base URI path is provided by the LWM2M Bootstrap process, so no dynamic discovery of the RD is used.  LWM2M Servers and endpoints are not required to implement the  <ins> /.well-known/core resource. </ins> 10.2.1.


Lifetime (optional).  Lifetime of the registration in seconds. Range of 60-4294967295.  If no lifetime is included in the initial registration, a default value of 86400 (24 hours) <del> SHOULD be assumed.  If the lt parameter is not included in a registration refresh or update operation, the most recently supplied value SHALL be re-used. </del>  Context (optional).  This parameter sets the scheme, address, port and path at which this server is available in the form

The mechanism is useful in updates, but at the registration interface they do not make sense. Closes: URL
According URL and below Therefore I'm not sure, if the explanation for the about the reuse of the most recently supplied value, just doesn't apply here (and may be moved to a more proper place), because this section is only about new or replacing registrations, or, if refresh or update registrations also apply to this section, somehow "extends" the behaviour of "replacing the registration parameters and links" (and may be therefore explicitly mentioned as exception in the "replacing the registration parameters and links, except the lifetime, where the below extra rule SHOULD be applied"). FMPOV, I don't see the use case, where a device sends a registration and the rd should use a previous lifetime without notice the device about that. The device would consider the default value, but, if the actual value would be smaller, the device will get unaware unregistered. An example for "supersede" case would therefore be also a good idea, to clarify, what is intended.
Hi Achim, I agree, we should remove the text about refresh from the description of new registrations, and it wil remove the confusion. Thanks! Michael
I agree: if a device re-registers by POSTing to the RD (rather than to its registration resource), it can often be the case that it has lost knowledge of its previous registration, so carrying defaults over from that would lead to misunderstandings. No other variables in the same section are affected by this issue. Pull-request with updated wording is pending; will merge it if no objections are brought up.
Thanks!
There is text in section 3.1 “Principles” of the RD draft that says… …snip…”it follows that no information should be stored in the resource directory that cannot be discovered from querying the described device's /.well-known/core resource directly.” This seems counter to the text in section 1 “Introduction”, which says… …snip…”These problems can be solved by employing an entity called a Resource Directory (RD), which hosts descriptions of resources held on other servers, allowing lookups to be performed for those resources.” Could the text in 3.1 be re-stated differently?
I'm note sure see the conflict; is it the "hosts", which could be read as being authority on and could be replaced with "mirrors"? Or is it more about the query interfaces that are not present on the original devices?
NAME could you elaborate on that? I do not understand the conflict.
To be honest I am not sure what the issue was. I think that in a first read it gave the impression that the RD was the host of the resources instead of mirroring them. I'll close it.

Lifetime (optional).  Lifetime of the registration in seconds. Range of 60-4294967295.  If no lifetime is included in the initial registration, a default value of 86400 (24 hours)  <ins> SHOULD be assumed. </ins> Context (optional).  This parameter sets the scheme, address, port and path at which this server is available in the form


The following example shows a client performing an endpoint type lookup: <del> The following example shows a client performing a domain lookup: </del> The following example shows a client performing a group lookup for all groups:

These changes were talked about previously in Prague and allow preservation of link relationships. A new example based on the relevant RFC6690 example shows different relevant cases (with present in the registration) in the lookup interface. The latest suggestions of bringing the endpoint interface in line with that are not included yet.
RFC5988 (web linking) describes that a statement of in the context of A means that "A has a hosted resource at B, which has the attribute C=D" (with the implied "hosts" relationship from RFC6690). The repeated entries of the pattern currently drafted for the domain lookup interface (and the analogous group lookups) are bear no such meaning, and all provide statements about the same resource. In a way, they could be collapsed into (or ). Given it then talks about the currently used resource-directory (that is ), isn't that a more straightforward to express the desired information anyway?
See issue I think we need to include the group resource location, which is returned when a group is created, in the angle brackets or "href". I also believe we shod not specify a "domain" lookup because we decided to specify domain as an attribute of a registration. There is no domain table to do lookups on...

The following example shows a client performing an endpoint type lookup:  The following example shows a client performing a group lookup for all groups:


associated domain of the registration. <del> When registering links to a Resource Directory, the Context refers to the scheme, address, port, and base path for all the links registered on behalf of an endpoint, of the general form scheme://host:port/path/ where the client may explicitly set the scheme and host, and may supply the port and path as optional parameters.  When the context of a registration is explicitly set, the URI resolution rules in RFC3986 MUST be applied. </del>  Commissioning Tool (CT) is a device that assists during the a set of links belonging to the host <del> The names of the attributes of the links correspond with the link- format attributes that can be set.  A link has the following attributes: </del>  <del> Unique rt (resource type) </del>  <del> Unique href (URI this link points to) </del>  <del> One or more ct (content-types for transport format) </del>  <del> Optional anchor (URI this link points from; default is the scheme/ authority of the /.well-known/core) </del>  <del> and associated rel (relation) Optional one if (interface description reference) </del>  The model shown in fig-ER-RD models the contents of the resource directory which contains in addition to /.well-known/core: copied from the value of the "hosts" relation and overwritten by the value of the con query parameter.  3.4. Over the last few years, mobile operators around the world have initial registration, a default value of 86400 (24 hours) SHOULD be assumed. <del> Context (optional).  This parameter sets the scheme, address, port and path at which this server is available in the form scheme://host:port/path.  In the absence of this parameter the </del>  scheme of the protocol, source address and source port of the register request are assumed.  This parameter is mandatory when the directory is filled by a third party such as an <del> commissioning tool.  When con is used, scheme and host are mandatory and port and path parameters are optional.  If the endpoint uses an ephemeral port to register with, it MUST include the con: parameter in the registration to provide a valid network path.  If the endpoint which is located behind a NAT gateway is registering with a Resource Directory which is on the network service side of the NAT gateway, the endpoint MUST use a persistent port for the outgoing registration in order to provide the NAT gateway with a valid network address for replies and incoming requests. </del>  application/link-format The endpoint MUST include the endpoint name and MAY include the registration parameters d, lt, and et, in the POST request as per <del> registration.  The scheme://authority value of the registration is taken from the requesting server's URI. </del>  The endpoints MUST be deleted after the expiration of their lifetime. Additional operations cannot be executed because no registration previous last lifetime set on a previous update or the original registration (falling back to 86400) SHOULD be used. <del> Context (optional).  This parameter sets the scheme, address and port at which this server is available in the form scheme://host:port/path.  In the absence of this parameter the scheme of the protocol, source address and source port of the register request are assumed.  This parameter is mandatory when the directory is filled by a third party such as an commissioning tool.  When con is used, scheme and host are mandatory and port and path parameters are optional. </del>  application/link-format (mandatory) endpoints and a resource lookup MUST return a list of links to resources. <del> RD Lookup does not expose registration resources directly, but returns link content from registration resource entries which satisfy RD Lookup queries. </del>  The lookup type is selected by a URI endpoint, which is indicated by a Resource Type as per lookup-types below: <del> Each endpoint and resource lookup result returns respectively the scheme (IP address and port) followed by the path part of the URI of every endpoint and resource inside angle brackets ("<>") and followed by the other parameters. The target of these links SHOULD be the actual location of the endpoint or resource, but MAY be an intermediate proxy e.g. in the case of an HTTP lookup interface for CoAP endpoints. In case that a group does not implement any multicast address, the group lookup returns every group lookup with a group base resource value encapsulated within angle brackets (e.g. "/rd/look-up"). Otherwise, the group lookup returns the multicast address of the group inside angle brackets. </del>  Using the Accept Option, the requester can control whether this list is returned in CoRE Link Format ("application/link-format", default) Endpoint name (optional).  Used for endpoint, group and resource lookups. <del> Domain (optional).  Used for domain, group, endpoint and resource lookups. </del>  gp := Group name (optional).  Used for endpoint, group and resource lookups.

This is the documenting text to the changes worked out first on the examples in . It does not (yet) contain explaining overall text, but updates the various smaller mentions of the parameter to fit together. It does change the semantics of using on a registration update, but I believe that the previous wording was not what the original authors had intended. (Previously, an endpoint registering over TCP would need to explicitly repeat its con on every update).

associated domain of the registration.  <ins> A Context is a base URL that gives scheme and (typically) authority information about an Endpoint.  The Context of an Endpoint is provided at registration time, and is used by the Resource Directory to resolve relative references inside the registration into absolute URIs. </ins> Commissioning Tool (CT) is a device that assists during the a set of links belonging to the host  <ins> The host is free to choose links it deems appropriate to be exposed in its ".well-known/core".  Typically, the links describe resources that are served by the host, but the set can also contain links to resources on other servers (see examples in [RFC6690] page 14).  The set does not necessarily contain links to all resources served by the host. </ins>  <ins> A link has the following attributes: </ins>  <ins> One or more link relations (expressed as space-separated values in the "rel" attribute, defaulting to "hosts").  They describe a relations between the link context and the link target. </ins>  <ins> A link context URI ("anchor").  The link context defines the source of the relation, and serves as the Base URI for resolving the target.  It can be relative, in which case it gets resolved against the Base URI of the ".well-known/core" document it was obtained from . It can be absent, in which the Base URI of the document is used as the context. </ins>  <ins> A link target URI ("href", expressed between the angular brackets in link-format).  The link target defines the destination of the relation, and is the topic of all other target attributes.  If it is a relative URI, it gets resolved against the link context URI. </ins>  <ins> Other target attributes (eg. resource type (rt), interface (if), cor content-type (ct)).  These provide additional information about the target URI. </ins> The model shown in fig-ER-RD models the contents of the resource directory which contains in addition to /.well-known/core: copied from the value of the "hosts" relation and overwritten by the value of the con query parameter. <ins> Links are modelled as they are in fig-ER-WKC.  As they do not have their ".well-known/core" document associated with them any more which would originally provide its Base URI, the "con" attribute of the registration fills that gap and is used as a Base URI. </ins> 3.4. Over the last few years, mobile operators around the world have initial registration, a default value of 86400 (24 hours) SHOULD be assumed.  <ins> Context (optional).  This parameter sets the Default Base URI under which the request's body are be interpreted.  The URI scheme provided MUST allow a path component, but the path component of the Context parameter MUST be empty.  The parameter is therefore of the shape "scheme://authority" for HTTP and CoAP URIs.  In the absence of this parameter the </ins> scheme of the protocol, source address and source port of the register request are assumed.  This parameter is mandatory when the directory is filled by a third party such as an  <ins> commissioning tool.  If the endpoint uses an ephemeral port to register with, it MUST include the con parameter in the registration to provide a valid network path.  If the endpoint which is located behind a NAT gateway is registering with a Resource Directory which is on the network service side of the NAT gateway, the endpoint MUST use a persistent port for the outgoing registration in order to provide the NAT gateway with a valid network address for replies and incoming requests. </ins> application/link-format The endpoint MUST include the endpoint name and MAY include the registration parameters d, lt, and et, in the POST request as per  <ins> registration.  The context of the registration is taken from the requesting server's URI. </ins> The endpoints MUST be deleted after the expiration of their lifetime. Additional operations cannot be executed because no registration previous last lifetime set on a previous update or the original registration (falling back to 86400) SHOULD be used.  <ins> Context (optional).  This parameter updates the context established in the original registration to a new value.  If the parameter is set in an update, it is stored by the RD as the new Base URI under which to interpret the links of the registration, following the same restrictions as in the registration.  If the parameter is not set and was set explicitly before, the previous context value is kept unmodified.  If the parameter is not set and was not set explicitly before either, the source address and source port of the update request are stored as the context. </ins> application/link-format (mandatory) endpoints and a resource lookup MUST return a list of links to resources.  <ins> While Endpoint Lookup does expose the registration resources, the RD does not need to make them accessible to clients.  Clients SHOULD NOT attempt to dereference or manipulate them. </ins> The lookup type is selected by a URI endpoint, which is indicated by a Resource Type as per lookup-types below:  <ins> Resource lookup results in links that are semantically equivalent to the links submitted to the RD if they were accessed on the endpoint itself.  The links and link parameters returned are equal to the submitted ones except for anchor, which gets resolved according to the endpoint's context.  That allows the client to interpret the response as links without any further knowledge of what the RD does. The Resource Directory MAY replace the contexts with a configured intermediate proxy, e.g. in the case of an HTTP lookup interface for CoAP endpoints. Endpoint and group lookups result in links to the selected registration and group resources.  Endpoint registration resources are annotated with their endpoint names (ep), domains (d, if present) and context (con).  Group resources are annotated with their group names (gp), domain (d, if present) and multicast address (con, if present). </ins> Using the Accept Option, the requester can control whether this list is returned in CoRE Link Format ("application/link-format", default) Endpoint name (optional).  Used for endpoint, group and resource lookups.  <ins> Domain (optional).  Used for group, endpoint and resource lookups. </ins> gp := Group name (optional).  Used for endpoint, group and resource lookups.


the cardinality of the relations.  The relations between the values of the attributes are explained in the interface sections.  The model shown in fig-ER-WKC models the contents of /.well-known/ core which contains: A link has the following attributes: <del> One or more link relations (expressed as space-separated values in the "rel" attribute, defaulting to "hosts").  They describe a </del>  relations between the link context and the link target. A link context URI ("anchor").  The link context defines the source of the relation, and serves as the Base URI for resolving <del> the target.  It can be relative, in which case it gets resolved against the Base URI of the ".well-known/core" document it was obtained from . It can be absent, in which the Base URI of the document is used as the context. </del>  A link target URI ("href", expressed between the angular brackets in link-format).  The link target defines the destination of the <del> relation, and is the topic of all other target attributes.  If it is a relative URI, it gets resolved against the link context URI. </del>  Other target attributes (eg. resource type (rt), interface (if), cor content-type (ct)).  These provide additional information copied from the value of the "hosts" relation and overwritten by the value of the con query parameter. <del> Links are modelled as they are in fig-ER-WKC.  As they do not have their ".well-known/core" document associated with them any more which would originally provide its Base URI, the "con" attribute of the registration fills that gap and is used as a Base URI. </del>  3.4.

This is the first step to closing [54], doing the changes to the model itself. Won't close the issue by itself probably, as some other portions might mention the model. This does not try to address any of the open issues. [54]: URL
s taget/target/

the cardinality of the relations.  The relations between the values of the attributes are explained in the interface sections. <ins> Some of the attribute values are URIs.  Those values are always full URIs and never relative references in the data model.  They can, however, be expressed as relative references in serializations, and often are. </ins> The model shown in fig-ER-WKC models the contents of /.well-known/ core which contains: A link has the following attributes:  <ins> Zero or more link relations (expressed as space-separated values in the "rel" attribute, defaulting to "hosts").  They describe a </ins> relations between the link context and the link target. A link context URI ("anchor").  The link context defines the source of the relation, and serves as the Base URI for resolving  <ins> the target.  In the serialization, it can be relative, in which case it gets resolved against the Base URI of the ".well-known/ core" document it was obtained from . It can be absent, in which the Base URI of the document is used as the context. </ins> A link target URI ("href", expressed between the angular brackets in link-format).  The link target defines the destination of the  <ins> relation, and is the topic of all other target attributes.  In the serialization, if it is a relative URI, it gets resolved against the link context URI. </ins> Other target attributes (eg. resource type (rt), interface (if), cor content-type (ct)).  These provide additional information copied from the value of the "hosts" relation and overwritten by the value of the con query parameter.  <ins> Links are modelled as they are in fig-ER-WKC. </ins> 3.4.


The endpoint then finds one or more addresses of the directory server as described in simple_finding. <del> An endpoint can send (a selection of) hosted resources to a directory server for publication as described in simple_publishing. </del>  The directory server integrates the information it received this way into its resource directory.  It MAY make the information available

Some minor text changes (commented per commit) I think are resonable and will merge soon unless someone speaks up against them.

The endpoint then finds one or more addresses of the directory server as described in simple_finding.  <ins> An endpoint finally asks the directory server to probe it for resources and publish them as described in simple_publishing. </ins> The directory server integrates the information it received this way into its resource directory.  It MAY make the information available


Endpoint type (optional).  Used for group, endpoint and resource lookups. <del> Link attribute parameters (optional).  Any link target attribute as defined in Section 4.1 of RFC6690, used for resource lookups. </del>  application/link-format (optional)

I think that rt is not an attribute of a registration; the first commit reflects that. (The second is more bycatch from that). Possibly we can simplify the whole section; as everything in the result is links, we're only applying the same link filtering that 6690 already specifies (plus pagination).
Absolutely right. After all commits by Christian, I will look at these examples again together with discovery text and other details. cabo schreef op 2017-10-19 16:57:

Endpoint type (optional).  Used for group, endpoint and resource lookups.  <ins> Link parameters (optional).  Any link parameter as defined in Section 4.1 of RFC6690, including href, used for resource lookups. </ins> application/link-format (optional)


An empty payload is considered a malformed request.  The registration request interface is specified as follows: EP -> RD (possibly updated) lifetime of the registration, independent of whether a "lt" parameter was given.  The update registration request interface is specified as follows: EP -> RD Resource lookup results in links that are semantically equivalent to the links submitted to the RD if they were accessed on the endpoint itself.  The links and link parameters returned are equal to the <del> submitted ones except for anchor, which gets resolved according to the endpoint's context.  That allows the client to interpret the response as links without any further knowledge of what the RD does. The Resource Directory MAY replace the contexts with a configured intermediate proxy, e.g. in the case of an HTTP lookup interface for CoAP endpoints. </del>  Endpoint and group lookups result in links to the selected registration resource and group resources.  Endpoint registration

The first commit tries to get across the difference between the relative references in the serialization and the URIs in the model more clearly. The second commit adds paragraphs to the descriptions of various operations about how and by whom URIs are resolved in those steps.

An empty payload is considered a malformed request. <ins> The posted link-format document can (and typically does) contain relative references both in its link targets and in its anchors, or contain empty anchors.  The server needs to resolve these references in order to faithfully represent them in lookups.  The Base URI against which they are resolved is the context of the registration, which is provided either explicitly in the "con" parameter or constructed implicitly from the requester's network address.  When resolving relative target references, the server first resolves the context of that link (the in the "anchor" attribute), and then interprets the target as a reference relative to that context (see resolution-rules). </ins> The registration request interface is specified as follows: EP -> RD (possibly updated) lifetime of the registration, independent of whether a "lt" parameter was given. <ins> If the context of the registration is changed in an update explicitly or implicitly, relative references submitted in the original registration or later updates are resolved anew against the new context (like in the original registration). </ins> The update registration request interface is specified as follows: EP -> RD Resource lookup results in links that are semantically equivalent to the links submitted to the RD if they were accessed on the endpoint itself.  The links and link parameters returned are equal to the  <ins> submitted ones except for anchor, which was resolved by the server against the endpoint's context. Links that did not have an anchor attribute are therefore returned with the (explicitly or implicitly set) context URI of the registration as the anchor.  Links whose anchor was submitted as an absolute URI are returned as they were registered.  The hrefs of links can always be served as they were submitted; the server MAY return relative references in absolute form in to resource lookups, but that results in needlessly verbose responses. That allows the client to interpret the response as links without any further knowledge of what the RD does.  The Resource Directory MAY replace the contexts with a configured intermediate proxy, e.g. in the case of an HTTP lookup interface for CoAP endpoints. </ins> Endpoint and group lookups result in links to the selected registration resource and group resources.  Endpoint registration


similar to example-discovery. A Resource Directory may optionally support HTTP.  Here is an example <del> of the same registration operation above, when done using HTTP. </del>  5.3.1. with the example resource look-up locations discovered in example- discovery:  The following example shows a client performing an endpoint type lookup:

See individual commit messages
As we support the alternative serializations from draft-ietf-core-links-json, I'd like to add at least the numbers in the RD lookup examples.
Use TBD64 etc., as discussed in the call.

similar to example-discovery. A Resource Directory may optionally support HTTP.  Here is an example  <ins> of almost the same registration operation above, when done using HTTP and the JSON Link Format. </ins> 5.3.1. with the example resource look-up locations discovered in example- discovery: <ins> The same lookup using the CBOR Link Format media type: </ins> The following example shows a client performing an endpoint type lookup:


value: /rd/4521.  The initial registration by the client set the following values:  lifetime (lt)=500 context (con)=coap://local-proxy-old.example.com:5683 <del> The initial state of the Registration Resource, /rd/4521, is: </del>  The following example shows an EP changing the context to "coaps://new.example.com:5684":

As agreed on in the 2017-10-26 meeting; this is better done right with PATCH.
I think removing the add links is more rigorous than proposed during the meeting but it is clearer text; I agree
why should the example be less controversial; it leaves the implementation hanging on this point
I don't see any reason to keep this section as pointed out during the last telco. When it is removed some examples i Registration update must be changed. The request GET /rd/4521 should change to GET /rd-lookup/ep?href=rd/4521
Apologies, that will not return the links of the endpoint The request GET /rd/4521 should change to GET /rd-lookup/res?ep=/rd/4521 or GET /rd-lookup/res?ep=node1 I am afraid we need to stay with ep name, difficult to use /rd/4521 as ep identifier.
The equivalent requests would be GET /rd-lookup/res?ep=node1 and GET /rd-lookup/res?href=/rd/4521 (where the link has neither the ep=node1 nor the href=/rd/4521 link parameter, but its registration does).
I think that we don't need the GET as long as there are no PATCHes (and I recently saw we don't even define PUT for the registration resource). The discussion has shown that this is one of the points where our understanding of resolved and unresolved addresses is tested: Can we have a resource whose content is "unresolved link-format" to operate on? Or do we need to resolve the links even in there, and any PATCH format would need to work semantically from a shared understanding of both the RD and the client? NAME you wanted to meditate on that; have you found deeper truth, or a path there?
This weird indeed: In my understanding this means return all link resource paths with ep name node1 and GET /rd-lookup/res?href=skins/larry/rd/4521 means return all link resource paths with href is skins/larry/rd/4521 and will be empty chrysn schreef op 2017-10-30 13:03:
returns resources that either have as their own link href, or are contained in an endpoint or group with that href. This was introduced in because we do not have (due to the extensibility of the link attributes and the lack of a definitive registry) a partition on attribute names that clearly states that one attribute can only be on a group, another only on an endpoint and a third only on a resource. Thus, we need to expect matches from either level -- and once we already have to do this, we can just as well do it with href because it's treated like any other attribute. IMO the alternatives to this would be either having registries set up to partition the names so every query parameter is clearly an endpoint, group or resource attribute (probably not going to happen with resource attributes, as requested and denied in RFC5988bis), or we'd need a more complex lookup language than RFC6690-style search -- something like so we could be explicit there. (See also URL )
Ok, you go faster than my shadow. As long as the text covers the example, and the intention is clear. I will need to read the finished text again. chrysn schreef op 2017-10-30 16:29:
(Moving some comments here from EMail to keep track:) [Peter] I thought we agreed to remove section 5.4.3, [Christian] I had that taken down as "we should think about it some more"; I do expect that interfact to only become useful when we have a way to patch it.
Given the current direction of lookup with construction of absolute URI, we can leave section 5.4.3 in

value: /rd/4521.  The initial registration by the client set the following values: <ins> endpoint name (ep)=endpoint1 </ins> lifetime (lt)=500 context (con)=coap://local-proxy-old.example.com:5683  <ins> The initial state of the Resource Directory is reflected in the following request: </ins> The following example shows an EP changing the context to "coaps://new.example.com:5684":


registration resource.  The registration resource location thus returned is for the purpose of updating the lifetime of the registration and for maintaining the content of the registered <del> links, including updating and deleting links. </del>  4.00 "Bad Request" or 400 "Bad Request".  Malformed request. <del> 4.09 "Conflict" or 409 "Conflict".  Attempt to create a registration resource with ep and d value pair which is already present in an earlier created registration resource. </del> 5.03 "Service Unavailable" or 503 "Service Unavailable".  Service could not perform the operation.

The description of the Registration interface describes it as idempotent, I think it should be idempotent on CoAP and not only on application level -- the same request results in the same response with no further state change. As to what happens when the re-registration arrives with a different set of links, there we have options; I went for "replaces the registration" here, but a 4.09 in that case would be just as valid an option. NAME that topic came up with the removal of the plurality removal at URL Do you agree with the basic proposition of "an unmodified request should be 2.04", and do you think replacing is the right way, or 4.09 if the links don't match?
Replacement is OK, given the removal of "addition of inks" with a POST. Conflicts are indeed impossible then.

registration resource.  The registration resource location thus returned is for the purpose of updating the lifetime of the registration and for maintaining the content of the registered  <ins> links, including updating and deleting links.  A registration with an already registered ep and d value pair responds with the same success code and Location as the original registration; the set of links registered with the endpoint is replaced with the links from the payload. </ins> 4.00 "Bad Request" or 400 "Bad Request".  Malformed request.  5.03 "Service Unavailable" or 503 "Service Unavailable".  Service could not perform the operation.


detected and used according to their own specifications and can be used with the lookup interface as with any other resource.  The lookup interface is specified as follows: Client -> RD

Unless takes a very surprising turn, I suggest reverting this: /rd-lookup/res (assuming it was discovered) always exists 2.03 is the wrong code this prescribes things already following from general observation Not reverting it yet awaiting the closure of .
chrysn schreef op 2018-01-31 12:26: Peter

detected and used according to their own specifications and can be used with the lookup interface as with any other resource. <ins> When resource observation is used, the following convention MUST be followed: When /rd-lookup/res does not exist, the response code 4.04 (Not Found) is returned and the request is not registered. When rd-lookup/res exists, the request is registered in the list of subjects and observers. When none of the links matches the filter, an empty payload with response code 2.03 (Valid) is returned. In all other cases, the set of matching links is returned in the payload with response code 2.05 (Content). Every time, the set of matching links changes, or the content of a matching link changes, the RD sends a notification with the matching link set. </ins> The lookup interface is specified as follows: Client -> RD


application/link-format+cbor and application/link-format+json, respectively, as they are defined in I-D.ietf-core-links-json. ] <del> At the same location where URI discovery happens, a user who wants to debug interoperability issues can ask for additional information that might be available about the server using generic resource discovery techniques.  That information would typically be stored in an implementation information link (as described in I-D.bormann-t2trg- rel-impl): </del>  Note that depending on the particular server's architecture, such a link could be anchored at the server's root, at the discovery site

This adds an example of how impl-info can be used to obtain implemetation software and version information. Closes: URL
But why would you want to do the latter, if not for the former or for some privacy-intrusive application? (Well, OK, netcraft style surveys. But these are not the motivation for documenting this, either.) Grüße, Carsten
The text in the RD spec suggests that debugging is needed and that debugging is possible thanks to the rel-impl relation. That is a bit strong: I can debug without the rel-impl relation. cabo schreef op 2018-01-31 17:27:
I was referring to generic use of .well-known/core as opposed to the formally limited interface ( described in the URI Discovery section. The pull request will be updated to address both concerns; thanks for the review.
Closed after immediate comments were addressed; it appears we're deep enough into the discussion of impl-info details that the direction is good.
There is a lot of confusing info in the first 4 lines. Debugging is not the problem, getting information about the implementation is. What are generic resource discovery techniques? We do have one specification called RD., and /.well-known/core The example is terse; Nice to know what the link means or is supposed to provide Thanks for the text; it helps to focus.

application/link-format+cbor and application/link-format+json, respectively, as they are defined in I-D.ietf-core-links-json. ]  <ins> A user can introspect the server for implementation information to ease debugging by using the URI discovery address as described in RFC6690 Section 4.  Information about the used software would typically be stored in an implementation information link (as described in I-D.bormann-t2trg-rel-impl): </ins> Note that depending on the particular server's architecture, such a link could be anchored at the server's root, at the discovery site


1. This document describes the technical mechanisms used by censorship <del> regimes around the world to block or degrade internet traffic.  To that end, we describe three elements of Internet censorship: aggregation, identification, and prevention.  Aggregation is the process by which censors determine what they should block, i.e. they decide to block a list of pornographic websites.  Identification is the process by which censors determine whether content is blocked, i.e. the censor blocks all webpages containing "sex" in the title. Prevention is the process by which the censor intercedes in communication and prevents access to censored materials. </del>  2. 4.3. <del> DNS Cache Poisoning refers to a mechanism where a censor interferes with the response sent by a DNS resolver to the requesting device by </del>  injecting an alternative IP address into the response message on the <del> return path.  Cache poisoning occurs after the requested site's name servers resolve the request and attempt to forward the IP back to the requesting device; on the return route the resolved IP is recursively cached by each DNS server that initially forwarded the request. During this caching process if an undesirable keyword is recognized, the resolved IP is poisoned and an alternative IP is returned.  These alternative IPs usually direct to a nonsense domain or a warning page ViewDNS-2011.  Alternatively, Iranian censorship appears to prevent the communication en-route, preventing a response from ever being sent Aryan-2012. Trade-offs: DNS Cache Poisoning is one of the rarer forms of prevention due to a number of shortcomings.  DNS Cache Poisoning requires the censor to force a user to traverse a controlled DNS resolver for the mechanism to be effective, it is easily circumvented by a technical savvy user that opts to use alternative DNS resolvers, such as the 8.8.8.8/8.8.4.4 public DNS resolvers provided by Google. DNS Cache Poisoning also implies returning an incorrect IP to those attempting to resolve a domain name, but the site is still technically unblocked if the user has another method to acquire the IP address of the desired site.  Blocking overflow has also been a </del>  problem, as occasionally users outside of the censors region will be <del> directed through a DNS server controlled by a censor, causing the request to fail.  The ease of circumvention paired with the large risk of overblocking and blocking overflow make DNS Cache Poisoning a partial, difficult, and less than ideal censorship mechanism. Empirical Evidence: DNS Cache Poisoning, when properly implemented, is easy to identify based on the shortcomings identified above. Turkey relied on DNS Cache Poisoning for its country-wide block of websites such Twitter and Youtube for almost week in March of 2014 but the ease of circumvention resulted in an increase in the popularity of Twitter until Turkish ISPs implementing an IP blacklist to achieve the governmental mandate Zmijewki-2014.  To drive proverbial "nail in the coffin" Turkish ISPs started hijacking all requests to Google and Level 3's international DNS resolvers Zmijewki-2014.  DNS Cache Poisoning, when incorrectly implemented, has as has resulted in some of the largest "censorship disasters". In January 2014 China started directing all requests passing through the Great Fire Wall to a single domain, dongtaiwang.com, due to an improperly configured DNS Cache Poisoning attempt; this incident is thought to be the largest internet-service outage in history Anon- SIGCOMM12.  Countries such as China, Iran, Turkey, and the United States have discussed blocking entire TLDs as well, but only Iran has acted by blocking all Israeli (.il) domains Albert-2011. </del>  4.4. 6.2. As Domain Names are resolved recursively, if a TLD deregisters a <del> domain all other DNS resolvers will be unable to properly forward and </del>  cache the site.  Domain name registration is only really a risk where undesirable content is hosted on TLD controlled by the censoring <del> country, such as .ch or .ru Anderson-2011. </del>  6.3.

Stephane Bortzmeyer provided great feedback on DNS aspects of this document, itemized in issues and . These commits should address those comments.
From Stephane: "Later in the document, there is again sloppy wording about the DNS. "As Domain Names are resolved recursively, if a TLD deregisters a domain all other DNS resolvers..." Which "other resolvers"? The TLD name servers are not resolvers. Also, the example "such as .ch or .ru" is poorly choosen since I am not aware of any case of censorship by the swiss TLD ("reference needed", as they say in Wikipedia). Better to use .com as an example (operation "In our sites" by the ICE)."
From Stephane: ""occasionally users outside of the censors region will be directed through a DNS server controlled by a censor, causing the request to fail" If you refer to the root-servers-in-China / Chile case, the requests never went "through a DNS server controlled by a censor". In China, this DNS mangling is done by network equipment, and does not require a DNS server."
From Stephane: "In the same section "the site is still technically unblocked if the user has another method to acquire the IP address of the desired site" is false for HTTP (unless the Web site is the only one listening at this IP address: otherwise, without a proper Host: field, using the IP address won't work)."
From Stephane: "Also, the section is self-contradictoy when it says "it is easily circumvented by a technical savvy user that opts to use alternative DNS resolvers" while mentioning later than Turkey solved the problem of circumvention by hijacking Google Public DNS' addresses. Unlike what you seem to imply, it was a success for the turkish government, very difficult to circumvent (Google does not use any authentication technique on Google Public DNS and, besides, there is little deployment of these techniques in the DNS.)"
From Stephane: ""DNS Cache Poisoning is one of the rarer forms of prevention" In France, it is the most common since it is mandated by law for at least two cases (illegal gambling and promotion of terrorism)."
from Stephane: "The first sentence is specially confusing: "DNS Cache Poisoning refers to a mechanism where a censor interferes with the response sent by a DNS resolver to the requesting device by injecting an alternative IP address on the return path." If it is done after the resolver, the cache will never see the alternative IP address and so won't be poisoned."
From Stephane: "the title "DNS Cache Poisoning" is very misleading since not all censorship-via-DNS target the cache. "DNS cache poisoning" describes a limited set of specific attacks and you should not use it to describe any DNS mangling. Otherwise, discussions about possible solutions would be impossible (for instance, DNSSEC fixes the problem of DNS cache poisoning but certainly not all the DNS censorship techniques)." Seems like the title needs to be fixed to "DNS Interference" or "DNS Censorship" and it be made broader to incorporate more features of DNS censorship.

1. This document describes the technical mechanisms used by censorship  <ins> regimes around the world to block or degrade internet traffic (see RFC7754 for a discussion of Internet blocking and filtering in terms of Internet architecture).  To that end, we describe three elements of Internet censorship: aggregation, identification, and prevention. Aggregation is the process by which censors determine what they should block, i.e. they decide to block a list of pornographic websites.  Identification is the process by which censors determine whether content is blocked, i.e. the censor blocks all webpages containing "sex" in the title.  Prevention is the process by which the censor intercedes in communication and prevents access to censored materials. </ins> 2. 4.3.  <ins> There are a variety of mechanisms that censors can use to block or filter access to content by altering responses from the DNS ICANN- SSAC-2012, including blocking the response, replying with an error message, or responding with an incorrect address (potentially to a server that can communicate to the end-user a reason for blocking access to that resource, for example using HTTP Status Code 451 RFC7725). DNS poisoning refers to a mechanism where a censor interferes with the response sent by a DNS server to the requesting device by </ins> injecting an alternative IP address into the response message on the  <ins> return path ViewDNS-2011.  Cache poisoning occurs after the requested site's name servers resolve the request and attempt to forward the IP back to the requesting device; on the return route the resolved IP is recursively cached by each DNS server that initially forwarded the request.  During this caching process if an undesirable keyword is recognized, the resolved IP is "poisoned" and an alternative IP (or NXDOMAIN error) is returned.  The alternative IPs usually direct to a nonsense domain or a warning page.  Alternatively, Iranian censorship appears to prevent the communication en-route, preventing a response from ever being sent Aryan-2012. Trade-offs: DNS interference requires the censor to force a user to traverse a controlled DNS hierarchy (or intervening network on which the censor serves as a Active Pervastive Attacker RFC7624 to rewrite DNS responses) for the mechanism to be effective.  It can be circumvented by a technical savvy user that opts to use alternative DNS resolvers (such as the public DNS resolvers provided by Google or OpenDNS) or Virtual Private Network technology.  DNS poisoning also implies returning an incorrect IP to those attempting to resolve a domain name, but in some cases the destination may be technically acessible; over HTTP, for example, the user may have another method of obtaining the IP address of the desired site and may be able to access it if the site is configured to be the defualt server listening at this IP address.  Blocking overflow has also been a </ins> problem, as occasionally users outside of the censors region will be  <ins> directed through a DNS servers or DNS-rewriting network equipment controlled by a censor, causing the request to fail.  The ease of circumvention paired with the large risk of overblocking and blocking overflow make DNS interference a partial, difficult, and less than ideal censorship mechanism. Empirical Evidence: DNS interference, when properly implemented, is easy to identify based on the shortcomings identified above.  Turkey relied on DNS interference for its country-wide block of websites such Twitter and Youtube for almost week in March of 2014 but the ease of circumvention resulted in an increase in the popularity of Twitter until Turkish ISPs implementing an IP blacklist to achieve the governmental mandate Zmijewki-2014.  Ultimately, Turkish ISPs started hijacking all requests to Google and Level 3's international DNS resolvers Zmijewki-2014.  DNS interference, when incorrectly implemented, has resulted in some of the largest "censorship disasters".  In January 2014 China started directing all requests passing through the Great Fire Wall to a single domain, dongtaiwang.com, due to an improperly configured DNS poisoning attempt; this incident is thought to be the largest internet-service outage in history Anon-SIGCOMM12.  Countries such as China, Iran, Turkey, and the United States have discussed blocking entire TLDs as well, but only Iran has acted by blocking all Israeli (.il) domains Albert-2011. </ins> 4.4. 6.2. As Domain Names are resolved recursively, if a TLD deregisters a  <ins> domain all other DNS servers will be unable to properly forward and </ins> cache the site.  Domain name registration is only really a risk where undesirable content is hosted on TLD controlled by the censoring  <ins> country, such as .cn or .ru Anderson-2011. </ins> 6.3.


inspect a copy of the information, usually mirrored by an optical splitter, making it an ideal pairing for DPI and Protocol Identification Weaver-2009 (this asynchronous version of a MITM is <del> ofen called a Man-on-the-Side (MOTS)).  RST Packet Injection also has the advantage of only requiring one of the two endpoints to accept the spoofed packet for the connection to be interrupted.  The </del>  difficult part of RST Packet Injection is spoofing "enough" correct information to ensure one end-point accepts a RST packet as legitimate; this generally implies a correct IP, port, and (TCP) As the name implies, sometimes manpower is the easiest way to figure out which content to block.  Manual Filtering differs from the common <del> tactic of building up blacklists in that is doesn't necessarily </del>  target a specific IP or DNS, but instead removes or flags content. Given the imprecise nature of automatic filtering, manually sorting through content and flagging dissenting websites, blogs, articles and

A few more typos I found while I was reading this I-D.
Thanks again!

inspect a copy of the information, usually mirrored by an optical splitter, making it an ideal pairing for DPI and Protocol Identification Weaver-2009 (this asynchronous version of a MITM is  <ins> often called a Man-on-the-Side (MOTS)).  RST Packet Injection also has the advantage of only requiring one of the two endpoints to accept the spoofed packet for the connection to be interrupted.  The </ins> difficult part of RST Packet Injection is spoofing "enough" correct information to ensure one end-point accepts a RST packet as legitimate; this generally implies a correct IP, port, and (TCP) As the name implies, sometimes manpower is the easiest way to figure out which content to block.  Manual Filtering differs from the common  <ins> tactic of building up blacklists in that it doesn't necessarily </ins> target a specific IP or DNS, but instead removes or flags content. Given the imprecise nature of automatic filtering, manually sorting through content and flagging dissenting websites, blogs, articles and


Abstract This document describes the technical mechanisms used by censorship <del> regimes around the world to block or degrade Internet traffic.  It </del>  aims to make designers, implementers, and users of Internet protocols aware of the properties being exploited and mechanisms used to censor end-user access to information.  This document makes no suggestions 1.  This document describes the technical mechanisms used by censorship <del> regimes around the world to block or degrade Internet traffic (see </del>  RFC7754 for a discussion of Internet blocking and filtering in terms of Internet architecture).  To that end, we describe three elements <del> of Internet censorship: aggregation, identification, and prevention. Aggregation is the process by which censors determine what they should block, i.e. they decide to block a list of pornographic websites.  Identification is the process by which censors determine whether content is blocked, i.e. the censor blocks all webpages containing "sex" in the title.  Prevention is the process by which the censor intercedes in communication and prevents access to censored materials. </del>  2. <del> Aggregation is the process of figuring out what censors would like to block Glanville-2008.  Generally, censors aggregate "to block" </del>  information in blacklists or using real-time heuristic assessment of content Ding-1999.  There are typically three types of blacklists: Keyword, Domain Name, or IP.  Keyword and Domain Name blocking take At all levels of the network hierarchy, the filtration mechanisms used to detect undesirable traffic are essentially the same: a censor sniffs transmitting packets and identifies undesirable content, and <del> then uses a blocking or shaping mechanism to prevent or degrade </del>  access.  Identification of undesirable traffic can occur at the application, transport, or network layer of the IP stack.  Censors are almost always concerned with web traffic, so the relevant 3.3.2. Censors sometimes identify entire protocols to be blocked using a <del> variety of traffic characteristics.  For example, Iran degrades the </del>  performance of HTTPS traffic, a protocol that prevents further analysis, to encourage users to switch to HTTP, a protocol that they can analyze Aryan-2012.  A simple protocol identification would be to somewhat challenging from a QoS perspective. Empirical Examples: Packet Dropping is a very common form of <del> technical prevention and lends itself to accurate detection given the unique nature of the time-out requests it leaves in its wake.  The Great Firewall of China uses packet dropping as one of its primary mechanisms of technical censorship Ensafi-2013.  Iran also uses Packet Dropping as the mechanisms for throttling SSH Aryan-2012. </del>  These are but two examples of a ubiquitous censorship practice. 4.2. Trade-offs: RST Packet Injection has a few advantages that make it extremely popular as a censorship technique.  RST Packet Injection is <del> an out-of-band prevention mechanism, allowing the avoidance of the </del>  the QoS bottleneck one can encounter with inline techniques such as Packet Dropping.  This out-of-band property allows a censor to inspect a copy of the information, usually mirrored by an optical BitTorrent Schoen-2007, this later led to a US Federal Communications Commission ruling against Comcast VonLohmann-2008.  China has also been known to use RST Packet Injection for censorship purposes.  This <del> prevention is especially evident in the interruption of encrypted/ </del>  obfuscated protocols, such as those used by Tor Winter-2012. 4.3.

…nce. defines censorship. fixes definition of identification in intro.
First, one thing that isn’t clear immediately from the introduction is who/what is a “censor”. I find it a little strange, actually, to suggest that a censor performs "aggregation". Is the censor an ISP? A government? Something else? For example, a government may have loose policies about what kind of content to censor (e.g., "hate speech"). An ISP might in turn implement these loose policies in different ways. Policies can also differ across a country, etc. The other terms---identification and prevention---are similarly confusing, although I think the term "identification" isn't as problematic as its (incorrect?) definition in the introduction. "Identification is the process by which censors determine whether content is blocked" - NO. I think it is the process by which a censor might classify traffic to determine whether to block a traffic flow or now. I would suggest something like: prescription, identification, and interference.
Wondering what you think about "design, identification, and interference"? I think for the purposes of todays 20:00 ET IETF drafts deadline, I'll change the terminology throughout to match prescription, identification, and interference and I'll correct the other things mentioned here (define censor, fix definition of identification in intro).
That seems a bit more clear, indeed! Ah, I didn't realize there was a deadline of today 2000h. Not sure I can get you a pull request by then, but will try.
I'll leave this open. You by no means need to get a pull request by 20:00! I just want to do my best to make changes responsive to your feedback. I'll leave this open and you can see what I've done (I'll be working on trying to clear out issues until then), and feel free to submit changes as you think are needed.

Abstract This document describes the technical mechanisms used by censorship  <ins> regimes around the world to block or impair Internet traffic.  It </ins> aims to make designers, implementers, and users of Internet protocols aware of the properties being exploited and mechanisms used to censor end-user access to information.  This document makes no suggestions 1. <ins> Censorship is where an entity in a position of power - such as a government, organization, or individual - supresses communication that it considers objectionable, harmful, sensitive, politically incorrect or inconvenient.  (While censors that engage in censorship or establish censorship regimes must do so through legal, military, or other sources of power, this document focuses largely on technical mechanisms used to achieve network censorship.) </ins> This document describes the technical mechanisms used by censorship  <ins> regimes around the world to block or impair Internet traffic (see </ins> RFC7754 for a discussion of Internet blocking and filtering in terms of Internet architecture).  To that end, we describe three elements  <ins> of Internet censorship: prescription, identification, and interference.  Prescription is the process by which censors determine what types of material they should block, i.e. they decide to block a list of pornographic websites.  Identification is the process by which censors classify specific traffic to be blocked or impaird, i.e. the censor blocks or impairs all webpages containing "sex" in the title or traffic to sex.com.  Interference is the process by which the censor intercedes in communication and prevents access to censored materials by blocking access or impairing the connection. </ins> 2.  <ins> Prescription is the process of figuring out what censors would like to block Glanville-2008.  Generally, censors aggregate "to block" </ins> information in blacklists or using real-time heuristic assessment of content Ding-1999.  There are typically three types of blacklists: Keyword, Domain Name, or IP.  Keyword and Domain Name blocking take At all levels of the network hierarchy, the filtration mechanisms used to detect undesirable traffic are essentially the same: a censor sniffs transmitting packets and identifies undesirable content, and  <ins> then uses a blocking or shaping mechanism to prevent or impair </ins> access.  Identification of undesirable traffic can occur at the application, transport, or network layer of the IP stack.  Censors are almost always concerned with web traffic, so the relevant 3.3.2. Censors sometimes identify entire protocols to be blocked using a  <ins> variety of traffic characteristics.  For example, Iran impairs the </ins> performance of HTTPS traffic, a protocol that prevents further analysis, to encourage users to switch to HTTP, a protocol that they can analyze Aryan-2012.  A simple protocol identification would be to somewhat challenging from a QoS perspective. Empirical Examples: Packet Dropping is a very common form of  <ins> technical interference and lends itself to accurate detection given the unique nature of the time-out requests it leaves in its wake. The Great Firewall of China uses packet dropping as one of its primary mechanisms of technical censorship Ensafi-2013.  Iran also uses Packet Dropping as the mechanisms for throttling SSH Aryan-2012. </ins> These are but two examples of a ubiquitous censorship practice. 4.2. Trade-offs: RST Packet Injection has a few advantages that make it extremely popular as a censorship technique.  RST Packet Injection is  <ins> an out-of-band interference mechanism, allowing the avoidance of the </ins> the QoS bottleneck one can encounter with inline techniques such as Packet Dropping.  This out-of-band property allows a censor to inspect a copy of the information, usually mirrored by an optical BitTorrent Schoen-2007, this later led to a US Federal Communications Commission ruling against Comcast VonLohmann-2008.  China has also been known to use RST Packet Injection for censorship purposes.  This  <ins> interference is especially evident in the interruption of encrypted/ </ins> obfuscated protocols, such as those used by Tor Winter-2012. 4.3.