doc: Add RFC documents

1 files changed, 1235 insertions, 0 deletions

diff --git a/doc/rfc/rfc6690.txt b/doc/rfc/rfc6690.txt
new file mode 100644
index 0000000..37209df
--- /dev/null
+++ b/doc/rfc/rfc6690.txt
@@ -0,0 +1,1235 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF)                         Z. Shelby
+Request for Comments: 6690                                     Sensinode
+Category: Standards Track                                    August 2012
+ISSN: 2070-1721
+
+
+          Constrained RESTful Environments (CoRE) Link Format
+
+Abstract
+
+   This specification defines Web Linking using a link format for use by
+   constrained web servers to describe hosted resources, their
+   attributes, and other relationships between links.  Based on the HTTP
+   Link Header field defined in RFC 5988, the Constrained RESTful
+   Environments (CoRE) Link Format is carried as a payload and is
+   assigned an Internet media type.  "RESTful" refers to the
+   Representational State Transfer (REST) architecture.  A well-known
+   URI is defined as a default entry point for requesting the links
+   hosted by a server.
+
+Status of This Memo
+
+   This is an Internet Standards Track document.
+
+   This document is a product of the Internet Engineering Task Force
+   (IETF).  It represents the consensus of the IETF community.  It has
+   received public review and has been approved for publication by the
+   Internet Engineering Steering Group (IESG).  Further information on
+   Internet Standards is available in Section 2 of RFC 5741.
+
+   Information about the current status of this document, any errata,
+   and how to provide feedback on it may be obtained at
+   http://www.rfc-editor.org/info/rfc6690.
+
+Copyright Notice
+
+   Copyright (c) 2012 IETF Trust and the persons identified as the
+   document authors.  All rights reserved.
+
+   This document is subject to BCP 78 and the IETF Trust's Legal
+   Provisions Relating to IETF Documents
+   (http://trustee.ietf.org/license-info) in effect on the date of
+   publication of this document.  Please review these documents
+   carefully, as they describe your rights and restrictions with respect
+   to this document.  Code Components extracted from this document must
+   include Simplified BSD License text as described in Section 4.e of
+   the Trust Legal Provisions and are provided without warranty as
+   described in the Simplified BSD License.
+
+
+
+Shelby                       Standards Track                    [Page 1]
+
+RFC 6690                    CoRE Link Format                 August 2012
+
+
+Table of Contents
+
+   1. Introduction ....................................................3
+      1.1. Web Linking in CoRE ........................................3
+      1.2. Use Cases ..................................................4
+           1.2.1. Discovery ...........................................4
+           1.2.2. Resource Collections ................................5
+           1.2.3. Resource Directory ..................................5
+      1.3. Terminology ................................................6
+   2. Link Format .....................................................6
+      2.1. Target and Context URIs ....................................8
+      2.2. Link Relations .............................................8
+      2.3. Use of Anchors .............................................9
+   3. CoRE Link Attributes ............................................9
+      3.1. Resource Type 'rt' Attribute ...............................9
+      3.2. Interface Description 'if' Attribute ......................10
+      3.3. Maximum Size Estimate 'sz' Attribute ......................10
+   4. Well-Known Interface ...........................................10
+      4.1. Query Filtering ...........................................12
+   5. Examples .......................................................13
+   6. Security Considerations ........................................15
+   7. IANA Considerations ............................................16
+      7.1. Well-Known 'core' URI .....................................16
+      7.2. New 'hosts' Relation Type .................................16
+      7.3. New 'link-format' Internet Media Type .....................17
+      7.4. Constrained RESTful Environments (CoRE) Parameters
+           Registry ..................................................18
+   8. Acknowledgments ................................................19
+   9. References .....................................................20
+      9.1. Normative References ......................................20
+      9.2. Informative References ....................................20
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Shelby                       Standards Track                    [Page 2]
+
+RFC 6690                    CoRE Link Format                 August 2012
+
+
+1.  Introduction
+
+   The Constrained RESTful Environments (CoRE) realizes the
+   Representational State Transfer (REST) architecture [REST] in a
+   suitable form for the most constrained nodes (e.g., 8-bit
+   microcontrollers with limited memory) and networks (e.g., IPv6 over
+   Low-Power Wireless Personal Area Networks (6LoWPANs) [RFC4919]).
+   CoRE is aimed at Machine-to-Machine (M2M) applications such as smart
+   energy and building automation.
+
+   The discovery of resources hosted by a constrained server is very
+   important in machine-to-machine applications where there are no
+   humans in the loop and static interfaces result in fragility.  The
+   discovery of resources provided by an HTTP [RFC2616] web server is
+   typically called "Web Discovery" and the description of relations
+   between resources is called "Web Linking" [RFC5988].  In the present
+   specification, we refer to the discovery of resources hosted by a
+   constrained web server, their attributes, and other resource
+   relations as CoRE Resource Discovery.
+
+   The main function of such a discovery mechanism is to provide
+   Universal Resource Identifiers (URIs, called links) for the resources
+   hosted by the server, complemented by attributes about those
+   resources and possible further link relations.  In CoRE, this
+   collection of links is carried as a resource of its own (as opposed
+   to HTTP headers delivered with a specific resource).  This document
+   specifies a link format for use in CoRE Resource Discovery by
+   extending the HTTP Link Header format [RFC5988] to describe these
+   link descriptions.  The CoRE Link Format is carried as a payload and
+   is assigned an Internet media type.  A well-known relative URI
+   "/.well-known/core" is defined as a default entry point for
+   requesting the list of links about resources hosted by a server and
+   thus performing CoRE Resource Discovery.  This specification is
+   applicable for use with Constrained Application Protocol (CoAP)
+   [COAP], HTTP, or any other suitable web transfer protocol.  The link
+   format can also be saved in file format.
+
+1.1.  Web Linking in CoRE
+
+   Technically, the CoRE Link Format is a serialization of a typed link
+   as specified in [RFC5988], used to describe relationships between
+   resources, so-called "Web Linking".  In this specification, Web
+   Linking is extended with specific constrained M2M attributes; links
+   are carried as a message payload rather than in an HTTP Link Header
+   field, and a default interface is defined to discover resources
+   hosted by a server.  This specification also defines a new relation
+
+
+
+
+
+Shelby                       Standards Track                    [Page 3]
+
+RFC 6690                    CoRE Link Format                 August 2012
+
+
+   type "hosts" (from the verb "to host"), which indicates that the
+   resource is hosted by the server from which the link document was
+   requested.
+
+   In HTTP, the Link Header can be used to carry link information about
+   a resource along with an HTTP response.  This works well for the
+   typical use case for a web server and browser, where further
+   information about a particular resource is useful after accessing it.
+   In CoRE, the main use case for Web Linking is the discovery of which
+   resources a server hosts in the first place.  Although some resources
+   may have further links associated with them, this is expected to be
+   an exception.  For that reason, the CoRE Link Format serialization is
+   carried as a resource representation of a well-known URI.  The CoRE
+   Link Format does reuse the format of the HTTP Link Header
+   serialization defined in [RFC5988].
+
+1.2.  Use Cases
+
+   Typical use cases for Web Linking on today's web include, e.g.,
+   describing the author of a web page or describing relations between
+   web pages (next chapter, previous chapter, etc.).  Web Linking can
+   also be applied to M2M applications, where typed links are used to
+   assist a machine client in finding and understanding how to use
+   resources on a server.  In this section a few use cases are described
+   for how the CoRE Link Format could be used in M2M applications.  For
+   further technical examples, see Section 5.  As there is a large range
+   of M2M applications, these use cases are purposely generic.  This
+   specification assumes that different deployments or application
+   domains will define the appropriate REST Interface Descriptions along
+   with Resource Types to make discovery meaningful.
+
+1.2.1.  Discovery
+
+   In M2M applications, for example, home or building automation, there
+   is a need for local clients and servers to find and interact with
+   each other without human intervention.  The CoRE Link Format can be
+   used by servers in such environments to enable Resource Discovery of
+   the resources hosted by the server.
+
+   Resource Discovery can be performed either unicast or multicast.
+   When a server's IP address is already known, either a priori or
+   resolved via the Domain Name System (DNS) [RFC1034][RFC1035], unicast
+   discovery is performed in order to locate the entry point to the
+   resource of interest.  In this specification, this is performed using
+   a GET to "/.well-known/core" on the server, which returns a payload
+   in the CoRE Link Format.  A client would then match the appropriate
+   Resource Type, Interface Description, and possible media type
+
+
+
+
+Shelby                       Standards Track                    [Page 4]
+
+RFC 6690                    CoRE Link Format                 August 2012
+
+
+   [RFC2045] for its application.  These attributes may also be included
+   in the query string in order to filter the number of links returned
+   in a response.
+
+   Multicast Resource Discovery is useful when a client needs to locate
+   a resource within a limited scope, and that scope supports IP
+   multicast.  A GET request to the appropriate multicast address is
+   made for "/.well-known/core".  In order to limit the number and size
+   of responses, a query string is recommended with the known
+   attributes.  Typically, a resource would be discovered based on its
+   Resource Type and/or Interface Description, along with possible
+   application-specific attributes.
+
+1.2.2.  Resource Collections
+
+   RESTful designs of M2M interfaces often make use of collections of
+   resources.  For example, an index of temperature sensors on a data
+   collection node or a list of alarms on a home security controller.
+   The CoRE Link Format can be used to make it possible to find the
+   entry point to a collection and traverse its members.  The entry
+   point of a collection would always be included in "/.well-known/core"
+   to enable its discovery.  The members of the collection can be
+   defined either through the Interface Description of the resource
+   along with a parameter resource for the size of the collection or by
+   using the link format to describe each resource in the collection.
+   These links could be located under "/.well-known/core" or hosted, for
+   example, in the root resource of the collection.
+
+1.2.3.  Resource Directory
+
+   In many deployment scenarios, for example, constrained networks with
+   sleeping servers or large M2M deployments with bandwidth limited
+   access networks, it makes sense to deploy resource directory entities
+   that store links to resources stored on other servers.  Think of this
+   as a limited search engine for constrained M2M resources.
+
+   The CoRE Link Format can be used by a server to register resources
+   with a resource directory or to allow a resource directory to poll
+   for resources.  Resource registration can be achieved by having each
+   server POST their resources to "/.well-known/core" on the resource
+   directory.  This, in turn, adds links to the resource directory under
+   an appropriate resource.  These links can then be discovered by any
+   client by making a request to a resource directory lookup interface.
+
+
+
+
+
+
+
+
+Shelby                       Standards Track                    [Page 5]
+
+RFC 6690                    CoRE Link Format                 August 2012
+
+
+1.3.  Terminology
+
+   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+   specification are to be interpreted as described in [RFC2119].
+
+   This specification makes use of the Augmented Backus-Naur Form (ABNF)
+   [RFC5234] notation, including the core rules defined in Appendix B of
+   that document.
+
+   This specification requires readers to be familiar with all the terms
+   and concepts that are discussed in [RFC5988] and [RFC6454].  In
+   addition, this specification makes use of the following terminology:
+
+   Web Linking
+      A framework for indicating the relationships between web
+      resources.
+
+   Link
+      Also called "typed links" in [RFC5988].  A link is a typed
+      connection between two resources identified by URI and is made up
+      of a context URI, a link relation type, a target URI, and optional
+      target attributes.
+
+   Link Format
+      A particular serialization of typed links.
+
+   CoRE Link Format
+      A particular serialization of typed links based on the HTTP Link
+      Header field serialization defined in Section 5 of [RFC5988] but
+      carried as a resource representation with a media type.
+
+   Attribute
+      Properly called "Target Attribute" in [RFC5988].  A key/value pair
+      that describes the link or its target.
+
+   CoRE Resource Discovery
+      When a client discovers the list of resources hosted by a server,
+      their attributes, and other link relations by accessing
+      "/.well-known/core".
+
+2.  Link Format
+
+   The CoRE Link Format extends the HTTP Link Header field specified in
+   [RFC5988].  The format does not require special XML or binary
+   parsing, is fairly compact, and is extensible -- all important
+   characteristics for CoRE.  It should be noted that this link format
+   is just one serialization of typed links defined in [RFC5988]; others
+
+
+
+Shelby                       Standards Track                    [Page 6]
+
+RFC 6690                    CoRE Link Format                 August 2012
+
+
+   include HTML links, Atom feed links [RFC4287], or HTTP Link Header
+   fields.  It is expected that resources discovered in the CoRE Link
+   Format may also be made available in alternative formats on the
+   greater Internet.  The CoRE Link Format is only expected to be
+   supported in constrained networks and M2M systems.
+
+   Section 5 of [RFC5988] did not require an Internet media type for the
+   defined link format, as it was defined to be carried in an HTTP
+   header.  This specification thus defines the Internet media type
+   'application/link-format' for the CoRE Link Format (see Section 7.3).
+   Whereas the HTTP Link Header field depends on [RFC2616] for its
+   encoding, the CoRE Link Format is encoded as UTF-8 [RFC3629].  A
+   decoder of the format is not expected to validate UTF-8 encoding (but
+   is not prohibited from doing so) and doesn't need to perform any
+   UTF-8 normalization.  UTF-8 data can be compared bitwise, which
+   allows values to contain UTF-8 data without any added complexity for
+   constrained nodes.
+
+   The CoRE Link Format is equivalent to the [RFC5988] link format;
+   however, the ABNF in the present specification is repeated with
+   improvements to be compliant with [RFC5234] and includes new link
+   parameters.  The link parameter "href" is reserved for use as a query
+   parameter for filtering in this specification (see Section 4.1) and
+   MUST NOT be defined as a link parameter.  As in [RFC5988], multiple
+   link descriptions are separated by commas.  Note that commas can also
+   occur in quoted strings and URIs but do not end a description.  In
+   order to convert an HTTP Link Header field to this link format, first
+   the "Link:" HTTP header is removed, any linear whitespace (LWS) is
+   removed, the header value is converted to UTF-8, and any percent-
+   encodings are decoded.
+
+    Link            = link-value-list
+    link-value-list = [ link-value *[ "," link-value ]]
+    link-value     = "<" URI-Reference ">" *( ";" link-param )
+    link-param     = ( ( "rel" "=" relation-types )
+                   / ( "anchor" "=" DQUOTE URI-Reference DQUOTE )
+                   / ( "rev" "=" relation-types )
+                   / ( "hreflang" "=" Language-Tag )
+                   / ( "media" "=" ( MediaDesc
+                          / ( DQUOTE MediaDesc DQUOTE ) ) )
+                   / ( "title" "=" quoted-string )
+                   / ( "title*" "=" ext-value )
+                   / ( "type" "=" ( media-type / quoted-mt ) )
+                   / ( "rt" "=" relation-types )
+                   / ( "if" "=" relation-types )
+                   / ( "sz" "=" cardinal )
+                   / ( link-extension ) )
+    link-extension = ( parmname [ "=" ( ptoken / quoted-string ) ] )
+
+
+
+Shelby                       Standards Track                    [Page 7]
+
+RFC 6690                    CoRE Link Format                 August 2012
+
+
+                   / ( ext-name-star "=" ext-value )
+    ext-name-star  = parmname "*" ; reserved for RFC-2231-profiled
+                                  ; extensions.  Whitespace NOT
+                                  ; allowed in between.
+    ptoken         = 1*ptokenchar
+    ptokenchar     = "!" / "#" / "$" / "%" / "&" / "'" / "("
+                   / ")" / "*" / "+" / "-" / "." / "/" / DIGIT
+                   / ":" / "<" / "=" / ">" / "?" / "@" / ALPHA
+                   / "[" / "]" / "^" / "_" / "`" / "{" / "|"
+                   / "}" / "~"
+    media-type     = type-name "/" subtype-name
+    quoted-mt      = DQUOTE media-type DQUOTE
+    relation-types = relation-type
+                   / DQUOTE relation-type *( 1*SP relation-type ) DQUOTE
+    relation-type  = reg-rel-type / ext-rel-type
+    reg-rel-type   = LOALPHA *( LOALPHA / DIGIT / "." / "-" )
+    ext-rel-type   = URI
+    cardinal       = "0" / ( %x31-39 *DIGIT )
+    LOALPHA        = %x61-7A   ; a-z
+    quoted-string  = <defined in [RFC2616]>
+    URI            = <defined in [RFC3986]>
+    URI-Reference  = <defined in [RFC3986]>
+    type-name      = <defined in [RFC4288]>
+    subtype-name   = <defined in [RFC4288]>
+    MediaDesc      = <defined in [W3C.HTML.4.01]>
+    Language-Tag   = <defined in [RFC5646]>
+    ext-value      = <defined in [RFC5987]>
+    parmname       = <defined in [RFC5987]>
+
+2.1.  Target and Context URIs
+
+   Each link conveys one target URI as a URI-reference inside angle
+   brackets ("<>").  The context URI of a link (also called the base URI
+   in [RFC3986]) is determined by the following rules in this
+   specification:
+
+   (a)  The context URI is set to the anchor parameter, when specified.
+
+   (b)  Origin of the target URI, when specified.
+
+   (c)  Origin of the link format resource's base URI.
+
+2.2.  Link Relations
+
+   Since links in the CoRE Link Format are typically used to describe
+   resources hosted by a server, the new relation type "hosts" is
+   assumed in the absence of the relation parameter (see Section 7.2).
+   The "hosts" relation type (from the verb "to host") indicates that
+
+
+
+Shelby                       Standards Track                    [Page 8]
+
+RFC 6690                    CoRE Link Format                 August 2012
+
+
+   the target URI is a resource hosted by the server (i.e., server hosts
+   resource) indicated by the context URI.  The target URI MUST be a
+   relative URI of the context URI for this relation type.
+
+   To express other relations, links can make use of any registered
+   relation by including the relation parameter.  The context of a
+   relation can be defined using the anchor parameter.  In this way,
+   relations between resources hosted on a server or between hosted
+   resources and external resources can be expressed.
+
+2.3.  Use of Anchors
+
+   As per Section 5.2 of [RFC5988], a link description MAY include an
+   "anchor" parameter, in which case the context is the URI included in
+   that attribute.  This is used to describe a relationship between two
+   resources.  A consuming implementation can, however, choose to ignore
+   such links.  It is not expected that all implementations will be able
+   to derive useful information from explicitly anchored links.
+
+3.  CoRE Link Attributes
+
+   The following CoRE-specific target attributes are defined in addition
+   to those already defined in [RFC5988].  These attributes describe
+   information useful in accessing the target link of the relation and,
+   in some cases, can use the syntactical form of a URI.  Such a URI MAY
+   be dereferenced (for instance, to obtain a description of the link
+   relation), but that is not part of the protocol and MUST NOT be done
+   automatically on link evaluation.  When the values of attributes are
+   compared, they MUST be compared as strings.
+
+3.1.  Resource Type 'rt' Attribute
+
+   The Resource Type 'rt' attribute is an opaque string used to assign
+   an application-specific semantic type to a resource.  One can think
+   of this as a noun describing the resource.  In the case of a
+   temperature resource, this could be, e.g., an application-specific
+   semantic type like "outdoor-temperature" or a URI referencing a
+   specific concept in an ontology like
+   "http://sweet.jpl.nasa.gov/2.0/phys.owl#Temperature".  Multiple
+   Resource Types MAY be included in the value of this parameter, each
+   separated by a space, similar to the relation attribute.  The
+   registry for Resource Type values is defined in Section 7.4.
+
+   The Resource Type attribute is not meant to be used to assign a
+   human-readable name to a resource.  The "title" attribute defined in
+   [RFC5988] is meant for that purpose.  The Resource Type attribute
+   MUST NOT appear more than once in a link.
+
+
+
+
+Shelby                       Standards Track                    [Page 9]
+
+RFC 6690                    CoRE Link Format                 August 2012
+
+
+3.2.  Interface Description 'if' Attribute
+
+   The Interface Description 'if' attribute is an opaque string used to
+   provide a name or URI indicating a specific interface definition used
+   to interact with the target resource.  One can think of this as
+   describing verbs usable on a resource.  The Interface Description
+   attribute is meant to describe the generic REST interface to interact
+   with a resource or a set of resources.  It is expected that an
+   Interface Description will be reused by different Resource Types.
+   For example, the Resource Types "outdoor-temperature", "dew-point",
+   and "rel-humidity" could all be accessible using the Interface
+   Description "http://www.example.org/myapp.wadl#sensor".  Multiple
+   Interface Descriptions MAY be included in the value of this
+   parameter, each separated by a space, similar to the relation
+   attribute.  The registry for Interface Description values is defined
+   in Section 7.4.
+
+   The Interface Description could be, for example, the URI of a Web
+   Application Description Language (WADL) [WADL] definition of the
+   target resource "http://www.example.org/myapp.wadl#sensor", a URN
+   indicating the type of interface to the resource "urn:myapp:sensor",
+   or an application-specific name "sensor".  The Interface Description
+   attribute MUST NOT appear more than once in a link.
+
+3.3.  Maximum Size Estimate 'sz' Attribute
+
+   The maximum size estimate attribute 'sz' gives an indication of the
+   maximum size of the resource representation returned by performing a
+   GET on the target URI.  For links to CoAP resources, this attribute
+   is not expected to be included for small resources that can
+   comfortably be carried in a single Maximum Transmission Unit (MTU)
+   but SHOULD be included for resources larger than that.  The maximum
+   size estimate attribute MUST NOT appear more than once in a link.
+
+   Note that there is no defined upper limit to the value of the 'sz'
+   attributes.  Implementations MUST be prepared to accept large values.
+   One implementation strategy is to convert any value larger than a
+   reasonable size limit for this implementation to a special value
+   "Big", which in further processing would indicate that a size value
+   was given that was so big that it cannot be processed by this
+   implementation.
+
+4.  Well-Known Interface
+
+   Resource discovery in CoRE is accomplished through the use of a well-
+   known resource URI that returns a list of links about resources
+   hosted by that server and other link relations.  Well-known resources
+
+
+
+
+Shelby                       Standards Track                   [Page 10]
+
+RFC 6690                    CoRE Link Format                 August 2012
+
+
+   have a path component that begins with "/.well-known/" as specified
+   in [RFC5785].  This specification defines a new well-known resource
+   for CoRE Resource Discovery: "/.well-known/core".
+
+   A server implementing this specification MUST support this resource
+   on the default port appropriate for the protocol for the purpose of
+   resource discovery.  It is, however, up to the application which
+   links are included and how they are organized.  The resource
+   "/.well-known/core" is meant to be used to return links to the entry
+   points of resource interfaces on a server.  More sophisticated link
+   organization can be achieved by including links to CoRE Link Format
+   resources located elsewhere on the server, for example, to achieve an
+   index.  In the absence of any links, a zero-length payload is
+   returned.  The resource representation of this resource MUST be the
+   CoRE Link Format described in Section 2.
+
+   The CoRE resource discovery interface supports the following
+   interactions:
+
+   o  Performing a GET on "/.well-known/core" to the default port
+      returns a set of links available from the server (if any) in the
+      CoRE Link Format.  These links might describe resources hosted on
+      that server or on other servers or express other kinds of link
+      relations as described in Section 2.
+
+   o  Filtering may be performed on any of the link format attributes
+      using a query string as specified in Section 4.1.  For example,
+      [GET /.well-known/core?rt=temperature-c] would request resources
+      with the Resource Type temperature-c.  A server is not, however,
+      required to support filtering.
+
+   o  More capable servers such as proxies could support a resource
+      directory by requesting the resource descriptions of other end-
+      points or allowing servers to POST requests to "/.well-known/
+      core".  The details of such resource directory functionality is,
+      however, out of the scope of this specification and is expected to
+      be specified separately.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Shelby                       Standards Track                   [Page 11]
+
+RFC 6690                    CoRE Link Format                 August 2012
+
+
+4.1.  Query Filtering
+
+   A server implementing this specification MAY recognize the query part
+   of a resource discovery URI as a filter on the resources to be
+   returned.  The path and query components together should conform to
+   the following level-4 URI Template [RFC6570]:
+
+       /.well-known/core{?search*}
+
+   where the variable "search" is a 1-element list that has a single
+   name/value pair, where
+
+   o  name is either "href", a link-param name defined in this
+      specification, or any other link-extension name, and
+
+   o  value is either a Complete Value String that does not end in an
+      "*" (%2A), or a Prefix Value String followed by an "*" (%2A).
+
+   The search name "href" refers to the URI-reference between the "<"
+   and ">" characters of a link.  Both Value Strings match a target
+   attribute only if it exists.  Value Strings are percent-decoded
+   ([RFC3986], Section 2.1) before matching; similarly, any target
+   attributes notated as quoted-string are interpreted as defined in
+   Section 2.2 of [RFC2616].  After these steps, a Complete Value String
+   matches a target attribute if it is bitwise identical.  A Prefix
+   Value String matches a target attribute if it is a bitwise prefix of
+   the target attribute (where any string is a prefix of itself).  Empty
+   Prefix Value Strings are allowed; by the definition above, they match
+   any target attribute that does exist.  Note that relation-type target
+   attributes can contain multiple values, and each value MUST be
+   treated as a separate target attribute when matching.
+
+   It is not expected that very constrained nodes support filtering.
+   Implementations not supporting filtering MUST simply ignore the query
+   string and return the whole resource for unicast requests.
+
+   When using a transfer protocol like the Constrained Application
+   Protocol (CoAP) that supports multicast requests, special care needs
+   to be taken.  A multicast request with a query string SHOULD NOT be
+   responded to if filtering is not supported or if the filter does not
+   match (to avoid a needless response storm).  The exception is in
+   cases where the IP stack interface is not able to indicate that the
+   destination address was multicast.
+
+
+
+
+
+
+
+
+Shelby                       Standards Track                   [Page 12]
+
+RFC 6690                    CoRE Link Format                 August 2012
+
+
+   The following are examples of valid query URIs:
+
+   o  ?href=/foo matches a link-value that is anchored at /foo
+
+   o  ?href=/foo* matches a link-value that is anchored at a URI that
+      starts with /foo
+
+   o  ?foo=bar matches a link-value that has a target attribute named
+      foo with the exact value bar
+
+   o  ?foo=bar* matches a link-value that has a target attribute named
+      foo, the value of which starts with bar, e.g., bar or barley
+
+   o  ?foo=* matches a link-value that has a target attribute named foo
+
+5.  Examples
+
+   A few examples of typical link descriptions in this format follows.
+   Multiple resource descriptions in a representation are separated by
+   commas.  Linefeeds are also included in these examples for
+   readability.  Although the following examples use CoAP response
+   codes, the examples are applicable to HTTP as well (the corresponding
+   response code would be 200 OK).
+
+   This example includes links to two different sensors sharing the same
+   Interface Description.  Note that the default relation type for this
+   link format is "hosts" in links with no rel= target attribute.  Thus,
+   the links in this example tell that the Origin server from which
+   /.well-known/core was requested (the context) hosts the resources
+   /sensors/temp and /sensors/light (each a target).
+
+   REQ: GET /.well-known/core
+
+   RES: 2.05 Content
+   </sensors/temp>;if="sensor",
+   </sensors/light>;if="sensor"
+
+   Without the linefeeds inserted here for readability, the format
+   actually looks as follows.
+
+   </sensors/temp>;if="sensor",</sensors/light>;if="sensor"
+
+   This example arranges link descriptions hierarchically, with the
+   entry point including a link to a sub-resource containing links about
+   the sensors.
+
+
+
+
+
+
+Shelby                       Standards Track                   [Page 13]
+
+RFC 6690                    CoRE Link Format                 August 2012
+
+
+   REQ: GET /.well-known/core
+
+   RES: 2.05 Content
+   </sensors>;ct=40
+
+   REQ: GET /sensors
+
+   RES: 2.05 Content
+   </sensors/temp>;rt="temperature-c";if="sensor",
+   </sensors/light>;rt="light-lux";if="sensor"
+
+   An example query filter may look like:
+
+   REQ: GET /.well-known/core?rt=light-lux
+
+   RES: 2.05 Content
+   </sensors/light>;rt="light-lux";if="sensor"
+
+   Note that relation-type attributes like 'rt', 'if', and 'rel' can
+   have multiple values separated by spaces.  A query filter parameter
+   can match any one of those values, as in this example:
+
+   REQ: GET /.well-known/core?rt=light-lux
+
+   RES: 2.05 Content
+   </sensors/light>;rt="light-lux core.sen-light";if="sensor"
+
+   This example shows the use of an "anchor" attribute to relate the
+   temperature sensor resource to an external description and to an
+   alternative URI.
+
+   REQ: GET /.well-known/core
+
+   RES: 2.05 Content
+   </sensors>;ct=40;title="Sensor Index",
+   </sensors/temp>;rt="temperature-c";if="sensor",
+   </sensors/light>;rt="light-lux";if="sensor",
+   <http://www.example.com/sensors/t123>;anchor="/sensors/temp"
+   ;rel="describedby",
+   </t>;anchor="/sensors/temp";rel="alternate"
+
+
+
+
+
+
+
+
+
+
+
+Shelby                       Standards Track                   [Page 14]
+
+RFC 6690                    CoRE Link Format                 August 2012
+
+
+   If a client is interested in finding relations about a particular
+   resource, it can perform a query on the anchor parameter:
+
+   REQ: GET /.well-known/core?anchor=/sensors/temp
+
+   RES: 2.05 Content
+   <http://www.example.com/sensors/temp123>;anchor="/sensors/temp"
+   ;rel="describedby",
+   </t>;anchor="/sensors/temp";rel="alternate"
+
+   The following example shows a large firmware resource with a size
+   attribute.  The consumer of this link would use the 'sz' attribute to
+   determine if the resource representation is too large and if block
+   transfer would be required to request it.  In this case, a client
+   with only a 64 KiB flash might only support a 16-bit integer for
+   storing the 'sz' attribute.  Thus, a special flag or value should be
+   used to indicate "Big" (larger than 64 KiB).
+
+   REQ: GET /.well-known/core?rt=firmware
+
+   RES: 2.05 Content
+   </firmware/v2.1>;rt="firmware";sz=262144
+
+6.  Security Considerations
+
+   This specification has the same security considerations as described
+   in Section 7 of [RFC5988].  The "/.well-known/core" resource MAY be
+   protected, e.g., using Datagram Transport Layer Security (DTLS) when
+   hosted on a CoAP server as per [COAP], Section 9.1.
+
+   Some servers might provide resource discovery services to a mix of
+   clients that are trusted to different levels.  For example, a
+   lighting control system might allow any client to read state
+   variables, but only certain clients to write state (turn lights on or
+   off).  Servers that have authentication and authorization features
+   SHOULD support authentication features of the underlying transport
+   protocols (HTTP or DTLS/TLS) and allow servers to return different
+   lists of links based on a client's identity and authorization.  While
+   such servers might not return all links to all requesters, not
+   providing the link does not, by itself, control access to the
+   relevant resource -- a bad actor could know or guess the right URIs.
+   Servers can also lie about the resources available.  If it is
+   important for a client to only get information from a known source,
+   then that source needs to be authenticated.
+
+
+
+
+
+
+
+Shelby                       Standards Track                   [Page 15]
+
+RFC 6690                    CoRE Link Format                 August 2012
+
+
+   Multicast requests using CoAP for the well-known link-format
+   resources could be used to perform denial of service on a constrained
+   network.  A multicast request SHOULD only be accepted if the request
+   is sufficiently authenticated and secured using, e.g., IPsec or an
+   appropriate object security mechanism.
+
+   CoRE Link Format parsers should be aware that a link description may
+   be cyclical, i.e., contain a link to itself.  These cyclical links
+   could be direct or indirect (i.e., through referenced link
+   resources).  Care should be taken when parsing link descriptions and
+   accessing cyclical links.
+
+7.  IANA Considerations
+
+7.1.  Well-Known 'core' URI
+
+   This memo registers the 'core' well-known URI in the Well-Known URIs
+   registry as defined by [RFC5785].
+
+   URI suffix: core
+
+   Change controller: IETF
+
+   Specification document(s): RFC 6690
+
+   Related information: None
+
+7.2.  New 'hosts' Relation Type
+
+   This memo registers the new "hosts" Web Linking relation type as per
+   [RFC5988].
+
+   Relation Name: hosts
+
+   Description: Refers to a resource hosted by the server indicated by
+   the link context.
+
+   Reference: RFC 6690
+
+   Notes: This relation is used in CoRE where links are retrieved as a
+   "/.well-known/core" resource representation and is the default
+   relation type in the CoRE Link Format.
+
+   Application Data: None
+
+
+
+
+
+
+
+Shelby                       Standards Track                   [Page 16]
+
+RFC 6690                    CoRE Link Format                 August 2012
+
+
+7.3.  New 'link-format' Internet Media Type
+
+   This memo registers the a new Internet media type for the CoRE Link
+   Format, 'application/link-format'.
+
+   Type name: application
+
+   Subtype name: link-format
+
+   Required parameters: None
+
+   Optional parameters: None
+
+   Encoding considerations: Binary data (UTF-8)
+
+   Security considerations:
+
+   Multicast requests using CoAP for the well-known link-format
+   resources could be used to perform denial of service on a constrained
+   network.  A multicast request SHOULD only be accepted if the request
+   is sufficiently authenticated and secured using, e.g., IPsec or an
+   appropriate object security mechanism.
+
+   CoRE Link Format parsers should be aware that a link description may
+   be cyclical, i.e., contain a link to itself.  These cyclical links
+   could be direct or indirect (i.e., through referenced link
+   resources).  Care should be taken when parsing link descriptions and
+   accessing cyclical links.
+
+   Interoperability considerations: None
+
+   Published specification: RFC 6690
+
+   Applications that use this media type: CoAP server and client
+   implementations for resource discovery and HTTP applications that use
+   the link-format as a payload.
+
+   Additional information:
+
+   Magic number(s):
+
+   File extension(s): *.wlnk
+
+   Macintosh file type code(s):
+
+   Intended usage: COMMON
+
+   Restrictions on usage: None
+
+
+
+Shelby                       Standards Track                   [Page 17]
+
+RFC 6690                    CoRE Link Format                 August 2012
+
+
+   Author: CoRE WG
+
+   Change controller: IETF
+
+7.4.  Constrained RESTful Environments (CoRE) Parameters Registry
+
+   This specification establishes a new Constrained RESTful Environments
+   (CoRE) Parameters registry, which contains two new sub-registries of
+   Link Target Attribute values (defined in [RFC5988]), one for Resource
+   Type (rt=) Link Target Attribute values and the other for Interface
+   Description (if=) Link Target Attribute values.  No initial entries
+   are defined by this specification for either sub-registry.
+
+   For both sub-registries, values starting with the characters "core"
+   are registered using the IETF Review registration policy [RFC5226].
+   All other values are registered using the Specification Required
+   policy, which requires review by a designated expert appointed by the
+   IESG or their delegate.
+
+   The designated expert will enforce the following requirements:
+
+   o  Registration values MUST be related to the intended purpose of
+      these attributes as described in Section 3.
+
+   o  Registered values MUST conform to the ABNF reg-rel-type definition
+      of Section 2, meaning that the value starts with a lowercase
+      alphabetic character, followed by a sequence of lowercase
+      alphabetic, numeric, ".", or "-" characters, and contains no white
+      space.
+
+   o  It is recommended that the period "." character be used for
+      dividing name segments and that the dash "-" character be used for
+      making a segment more readable.  Example Interface Description
+      values might be "core.batch" and "core.link-batch".
+
+   o  URIs are reserved for free use as extension values for these
+      attributes and MUST NOT be registered.
+
+   Registration requests consist of the completed registration template
+   below, with the reference pointing to the required specification.  To
+   allow for the allocation of values prior to publication, the
+   designated expert may approve registration once they are satisfied
+   that a specification will be published.
+
+   Note that Link Target Attribute Values can be registered by third
+   parties if the Designated Expert determines that an unregistered Link
+   Target Attribute Value is widely deployed and not likely to be
+   registered in a timely manner.
+
+
+
+Shelby                       Standards Track                   [Page 18]
+
+RFC 6690                    CoRE Link Format                 August 2012
+
+
+   The registration template for both sub-registries is:
+
+   o  Attribute Value:
+
+   o  Description:
+
+   o  Reference:
+
+   o  Notes: [optional]
+
+   Registration requests should be sent to the core-parameters@ietf.org
+   mailing list, marked clearly in the subject line (e.g., "NEW RESOURCE
+   TYPE - example" to register an "example" relation type or "NEW
+   INTERFACE DESCRIPTION - example" to register an "example" Interface
+   Description).
+
+   Within at most 14 days of the request, the Designated Expert(s) will
+   either approve or deny the registration request, communicating this
+   decision to the review list and IANA.  Denials should include an
+   explanation and, if applicable, suggestions as to how to make the
+   request successful.
+
+   Decisions (or lack thereof) made by the Designated Expert can be
+   first appealed to Application Area Directors (contactable using the
+   app-ads@tools.ietf.org email address or directly by looking up their
+   email addresses on http://www.iesg.org/ website) and, if the
+   appellant is not satisfied with the response, to the full IESG (using
+   the iesg@ietf.org mailing list).
+
+8.  Acknowledgments
+
+   Special thanks to Peter Bigot, who has made a considerable number of
+   reviews and text contributions that greatly improved the document.
+   In particular, Peter is responsible for early improvements to the
+   ABNF descriptions and the idea for a new 'hosts' relation type.
+
+   Thanks to Mark Nottingham and Eran Hammer-Lahav for the discussions
+   and ideas that led to this document, and to Carsten Bormann, Martin
+   Thomson, Alexey Melnikov, Julian Reschke, Joel Halpern, Richard
+   Barnes, Barry Leiba, and Peter Saint-Andre for extensive comments and
+   contributions that improved the text.
+
+   Thanks to Michael Stuber, Richard Kelsey, Cullen Jennings, Guido
+   Moritz, Peter Van Der Stok, Adriano Pezzuto, Lisa Dussealt, Alexey
+   Melnikov, Gilbert Clark, Salvatore Loreto, Petri Mutka, Szymon Sasin,
+   Robert Quattlebaum, Robert Cragie, Angelo Castellani, Tom Herbst, Ed
+   Beroset, Gilman Tolle, Robby Simpson, Colin O'Flynn, and David Ryan
+   for helpful comments and discussions that have shaped the document.
+
+
+
+Shelby                       Standards Track                   [Page 19]
+
+RFC 6690                    CoRE Link Format                 August 2012
+
+
+9.  References
+
+9.1.  Normative References
+
+   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
+              Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+   [RFC2616]  Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
+              Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
+              Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
+
+   [RFC3629]  Yergeau, F., "UTF-8, a transformation format of ISO
+              10646", STD 63, RFC 3629, November 2003.
+
+   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
+              Resource Identifier (URI): Generic Syntax", STD 66,
+              RFC 3986, January 2005.
+
+   [RFC4288]  Freed, N. and J. Klensin, "Media Type Specifications and
+              Registration Procedures", BCP 13, RFC 4288, December 2005.
+
+   [RFC5226]  Narten, T. and H. Alvestrand, "Guidelines for Writing an
+              IANA Considerations Section in RFCs", BCP 26, RFC 5226,
+              May 2008.
+
+   [RFC5234]  Crocker, D. and P. Overell, "Augmented BNF for Syntax
+              Specifications: ABNF", STD 68, RFC 5234, January 2008.
+
+   [RFC5646]  Phillips, A. and M. Davis, "Tags for Identifying
+              Languages", BCP 47, RFC 5646, September 2009.
+
+   [RFC5987]  Reschke, J., "Character Set and Language Encoding for
+              Hypertext Transfer Protocol (HTTP) Header Field
+              Parameters", RFC 5987, August 2010.
+
+   [RFC5988]  Nottingham, M., "Web Linking", RFC 5988, October 2010.
+
+   [RFC6570]  Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
+              and D. Orchard, "URI Template", RFC 6570, March 2012.
+
+9.2.  Informative References
+
+   [COAP]     Shelby, Z., Hartke, K., Bormann, C., and B. Frank,
+              "Constrained Application Protocol (CoAP)", Work in
+              Progress, July 2012.
+
+
+
+
+
+
+Shelby                       Standards Track                   [Page 20]
+
+RFC 6690                    CoRE Link Format                 August 2012
+
+
+   [REST]     Fielding, R., "Architectural Styles and the Design of
+              Network-based Software Architectures", 2000,
+              <http://www.ics.uci.edu/~fielding/pubs/dissertation/
+              top.htm>.
+
+   [RFC1034]  Mockapetris, P., "Domain names - concepts and facilities",
+              STD 13, RFC 1034, November 1987.
+
+   [RFC1035]  Mockapetris, P., "Domain names - implementation and
+              specification", STD 13, RFC 1035, November 1987.
+
+   [RFC2045]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
+              Extensions (MIME) Part One: Format of Internet Message
+              Bodies", RFC 2045, November 1996.
+
+   [RFC2231]  Freed, N. and K. Moore, "MIME Parameter Value and Encoded
+              Word Extensions: Character Sets, Languages, and
+              Continuations", RFC 2231, November 1997.
+
+   [RFC4287]  Nottingham, M., Ed. and R. Sayre, Ed., "The Atom
+              Syndication Format", RFC 4287, December 2005.
+
+   [RFC4919]  Kushalnagar, N., Montenegro, G., and C. Schumacher, "IPv6
+              over Low-Power Wireless Personal Area Networks (6LoWPANs):
+              Overview, Assumptions, Problem Statement, and Goals",
+              RFC 4919, August 2007.
+
+   [RFC5785]  Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known
+              Uniform Resource Identifiers (URIs)", RFC 5785,
+              April 2010.
+
+   [RFC6454]  Barth, A., "The Web Origin Concept", RFC 6454,
+              December 2011.
+
+   [W3C.HTML.4.01]
+              Raggett, D., Le Hors, A., and I. Jacobs, "HTML 4.01
+              Specification", World Wide Web Consortium
+              Recommendation REC-html401-19991224, December 1999,
+              <http://www.w3.org/TR/1999/REC-html401-19991224>.
+
+   [WADL]     Hadley, M., "Web Application Description Language (WADL)",
+              2009, <http://java.net/projects/wadl/sources/svn/content/
+              trunk/www/wadl20090202.pdf>.
+
+
+
+
+
+
+
+
+Shelby                       Standards Track                   [Page 21]
+
+RFC 6690                    CoRE Link Format                 August 2012
+
+
+Author's Address
+
+   Zach Shelby
+   Sensinode
+   Kidekuja 2
+   Vuokatti  88600
+   Finland
+
+   Phone: +358407796297
+   EMail: zach@sensinode.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Shelby                       Standards Track                   [Page 22]
+