tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Gloss.     Arch.     IMS     UICC    |    Misc.    |    search     info

RFC 7390

Experimental
Pages: 46
Top     in Index     Prev     Next
in Group Index     Prev in Group     Next in Group     Group: CORE

Group Communication for the Constrained Application Protocol (CoAP)

Part 1 of 3, p. 1 to 17
None       Next RFC Part

 


Top       ToC       Page 1 
Internet Engineering Task Force (IETF)                    A. Rahman, Ed.
Request for Comments: 7390              InterDigital Communications, LLC
Category: Experimental                                      E. Dijk, Ed.
ISSN: 2070-1721                                         Philips Research
                                                            October 2014


  Group Communication for the Constrained Application Protocol (CoAP)

Abstract

   The Constrained Application Protocol (CoAP) is a specialized web
   transfer protocol for constrained devices and constrained networks.
   It is anticipated that constrained devices will often naturally
   operate in groups (e.g., in a building automation scenario, all
   lights in a given room may need to be switched on/off as a group).
   This specification defines how CoAP should be used in a group
   communication context.  An approach for using CoAP on top of IP
   multicast is detailed based on existing CoAP functionality as well as
   new features introduced in this specification.  Also, various use
   cases and corresponding protocol flows are provided to illustrate
   important concepts.  Finally, guidance is provided for deployment in
   various network topologies.

Status of This Memo

   This document is not an Internet Standards Track specification; it is
   published for examination, experimental implementation, and
   evaluation.

   This document defines an Experimental Protocol for the Internet
   community.  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).  Not
   all documents approved by the IESG are a candidate for any level of
   Internet Standard; see 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/rfc7390.

Page 2 
Copyright Notice

   Copyright (c) 2014 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.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.1.  Background  . . . . . . . . . . . . . . . . . . . . . . .   3
     1.2.  Scope . . . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.3.  Conventions and Terminology . . . . . . . . . . . . . . .   4
   2.  Protocol Considerations . . . . . . . . . . . . . . . . . . .   5
     2.1.  IP Multicast Background . . . . . . . . . . . . . . . . .   5
     2.2.  Group Definition and Naming . . . . . . . . . . . . . . .   6
     2.3.  Port and URI Configuration  . . . . . . . . . . . . . . .   7
     2.4.  RESTful Methods . . . . . . . . . . . . . . . . . . . . .   9
     2.5.  Request and Response Model  . . . . . . . . . . . . . . .   9
     2.6.  Membership Configuration  . . . . . . . . . . . . . . . .  10
       2.6.1.  Background  . . . . . . . . . . . . . . . . . . . . .  10
       2.6.2.  Membership Configuration RESTful Interface  . . . . .  11
     2.7.  Request Acceptance and Response Suppression Rules . . . .  17
     2.8.  Congestion Control  . . . . . . . . . . . . . . . . . . .  19
     2.9.  Proxy Operation . . . . . . . . . . . . . . . . . . . . .  20
     2.10. Exceptions  . . . . . . . . . . . . . . . . . . . . . . .  21
   3.  Use Cases and Corresponding Protocol Flows  . . . . . . . . .  22
     3.1.  Introduction  . . . . . . . . . . . . . . . . . . . . . .  22
     3.2.  Network Configuration . . . . . . . . . . . . . . . . . .  22
     3.3.  Discovery of Resource Directory . . . . . . . . . . . . .  25
     3.4.  Lighting Control  . . . . . . . . . . . . . . . . . . . .  26
     3.5.  Lighting Control in MLD-Enabled Network . . . . . . . . .  30
     3.6.  Commissioning the Network Based on Resource Directory . .  31
   4.  Deployment Guidelines . . . . . . . . . . . . . . . . . . . .  32
     4.1.  Target Network Topologies . . . . . . . . . . . . . . . .  32
     4.2.  Networks Using the MLD Protocol . . . . . . . . . . . . .  33
     4.3.  Networks Using RPL Multicast without MLD  . . . . . . . .  33
     4.4.  Networks Using MPL Forwarding without MLD . . . . . . . .  34
     4.5.  6LoWPAN Specific Guidelines for the 6LBR  . . . . . . . .  35
   5.  Security Considerations . . . . . . . . . . . . . . . . . . .  35
     5.1.  Security Configuration  . . . . . . . . . . . . . . . . .  35
     5.2.  Threats . . . . . . . . . . . . . . . . . . . . . . . . .  36

Top      ToC       Page 3 
     5.3.  Threat Mitigation . . . . . . . . . . . . . . . . . . . .  36
       5.3.1.  WiFi Scenario . . . . . . . . . . . . . . . . . . . .  37
       5.3.2.  6LoWPAN Scenario  . . . . . . . . . . . . . . . . . .  37
       5.3.3.  Future Evolution  . . . . . . . . . . . . . . . . . .  37
     5.4.  Monitoring Considerations . . . . . . . . . . . . . . . .  38
       5.4.1.  General Monitoring  . . . . . . . . . . . . . . . . .  38
       5.4.2.  Pervasive Monitoring  . . . . . . . . . . . . . . . .  38
   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  39
     6.1.  New 'core.gp' Resource Type . . . . . . . . . . . . . . .  39
     6.2.  New 'coap-group+json' Internet Media Type . . . . . . . .  39
   7.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  41
     7.1.  Normative References  . . . . . . . . . . . . . . . . . .  41
     7.2.  Informative References  . . . . . . . . . . . . . . . . .  43
   Appendix A.  Multicast Listener Discovery (MLD) . . . . . . . . .  45
   Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .  45
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  46

1.  Introduction

1.1.  Background

   CoAP is a web transfer protocol based on Representational State
   Transfer (REST) for resource constrained devices operating in an IP
   network [RFC7252].  CoAP has many similarities to HTTP [RFC7230] but
   also some key differences.  Constrained devices can be large in
   numbers but are often related to each other in function or by
   location.  For example, all the light switches in a building may
   belong to one group, and all the thermostats may belong to another
   group.  Groups may be preconfigured before deployment or dynamically
   formed during operation.  If information needs to be sent to or
   received from a group of devices, group communication mechanisms can
   improve efficiency and latency of communication and reduce bandwidth
   requirements for a given application.  HTTP does not support any
   equivalent functionality to CoAP group communication.

1.2.  Scope

   Group communication involves a one-to-many relationship between CoAP
   endpoints.  Specifically, a single CoAP client can simultaneously get
   (or set) resources from multiple CoAP servers using CoAP over IP
   multicast.  An example would be a CoAP light switch turning on/off
   multiple lights in a room with a single CoAP group communication PUT
   request and handling the potential multitude of (unicast) responses.

   The base protocol aspects of sending CoAP requests on top of IP
   multicast and processing the (unicast IP) responses are given in
   Section 8 of [RFC7252].  To provide a more complete CoAP group
   communication functionality, this specification introduces new CoAP

Top      ToC       Page 4 
   processing functionality (e.g., new rules for reuse of Token values,
   request suppression, and proxy operation) and a new management
   interface for RESTful group membership configuration.

   CoAP group communication will run in the Any Source Multicast (ASM)
   mode [RFC5110] of IP multicast operation.  This means that there is
   no restriction on the source node that sends (originates) the CoAP
   messages to the IP multicast group.  For example, the source node may
   or may not be part of the IP multicast group.  Also, there is no
   restriction on the number of source nodes.

   While Section 9.1 of [RFC7252] supports various modes of security
   based on Datagram Transport Layer Security (DTLS) for CoAP over
   unicast IP, it does not specify any security modes for CoAP over IP
   multicast.  That is, it is assumed per [RFC7252] that CoAP over IP
   multicast is not encrypted, nor authenticated, nor access controlled.
   This document assumes the same security model (see Section 5.1).
   However, there are several promising security approaches being
   developed that should be considered in the future for protecting CoAP
   group communications (see Section 5.3.3).

1.3.  Conventions and Terminology

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in
   [RFC2119] when they appear in ALL CAPS.  When these words are not in
   ALL CAPS (such as "should" or "Should"), they have their usual
   English meanings and are not to be interpreted as [RFC2119] key
   words.

   Note that this document refers back to other RFCs, and especially
   [RFC7252], to help explain overall CoAP group communication features.
   However, use of [RFC2119] key words is reserved for new CoAP
   functionality introduced by this specification.

   This document assumes readers are familiar with the terms and
   concepts that are used in [RFC7252].  In addition, this document
   defines the following terminology:

   Group Communication:
      A source node sends a single application-layer (e.g., CoAP)
      message that is delivered to multiple destination nodes, where all
      destinations are identified to belong to a specific group.  The
      source node itself may be part of the group.  The underlying
      mechanisms for CoAP group communication are UDP/IP multicast for

Top      ToC       Page 5 
      the requests and unicast UDP/IP for the responses.  The network
      involved may be a constrained network such as a low-power, lossy
      network.

   Reliable Group Communication:
      A special case of group communication where for each destination
      node, it is guaranteed that the node either 1) eventually receives
      the message sent by the source node or 2) does not receive the
      message and the source node is notified of the non-reception
      event.  An example of a reliable group communication protocol is
      [RFC5740].

   Multicast:
      Sending a message to multiple destination nodes with one network
      invocation.  There are various options to implement multicast,
      including layer 2 (Media Access Control) and layer 3 (IP)
      mechanisms.

   IP Multicast:
      A specific multicast approach based on the use of IP multicast
      addresses as defined in "IANA Guidelines for IPv4 Multicast
      Address Assignments" [RFC5771] and "IP Version 6 Addressing
      Architecture" [RFC4291].  A complete IP multicast solution may
      include support for managing group memberships and IP multicast
      routing/forwarding (see Section 2.1).

   Low-Power and Lossy Network (LLN):
      A type of constrained IP network where devices are interconnected
      by low-power and lossy links.  The links may be composed of one or
      more technologies such as IEEE 802.15.4, Bluetooth Low Energy
      (BLE), Digital Enhanced Cordless Telecommunication (DECT), and
      IEEE P1901.2 power-line communication.

2.  Protocol Considerations

2.1.  IP Multicast Background

   IP multicast protocols have been evolving for decades, resulting in
   standards such as Protocol Independent Multicast - Sparse Mode (PIM-
   SM) [RFC4601].  IP multicast is very popular in specific deployments
   such as in enterprise networks (e.g., for video conferencing), smart
   home networks (e.g., Universal Plug and Play (UPnP)), and carrier
   IPTV deployments.  The packet economy and minimal host complexity of
   IP multicast make it attractive for group communication in
   constrained environments.

Top      ToC       Page 6 
   To achieve IP multicast beyond link-local (LL) scope, an IP multicast
   routing or forwarding protocol needs to be active on IP routers.  An
   example of a routing protocol specifically for LLNs is the IPv6
   Routing Protocol for Low-Power and Lossy Networks (RPL) (Section 12
   of [RFC6550]), and an example of a forwarding protocol for LLNs is
   the Multicast Protocol for Low-Power and Lossy Networks (MPL)
   [MCAST-MPL].  RPL and MPL do not depend on each other; each can be
   used in isolation, and both can be used in combination in a network.
   Finally, PIM-SM [RFC4601] is often used for multicast routing in
   traditional IP networks (i.e., networks that are not constrained).

   IP multicast can also be run in an LL scope.  This means that there
   is no routing involved, and an IP multicast message is only received
   over the link on which it was sent.

   For a complete IP multicast solution, in addition to a routing/
   forwarding protocol, a "listener" protocol may be needed for the
   devices to subscribe to groups (see Section 4.2).  Also, a multicast
   forwarding proxy node [RFC4605] may be required.

   IP multicast is generally classified as an unreliable service in that
   packets are not guaranteed to be delivered to each and every member
   of the group.  In other words, it cannot be directly used as a basis
   for "reliable group communication" as defined in Section 1.3.
   However, the level of reliability can be increased by employing a
   multicast protocol that performs periodic retransmissions as is done,
   for example, in MPL.

2.2.  Group Definition and Naming

   A CoAP group is defined as a set of CoAP endpoints, where each
   endpoint is configured to receive CoAP group communication requests
   that are sent to the group's associated IP multicast address.  The
   individual response by each endpoint receiver to a CoAP group
   communication request is always sent back as unicast.  An endpoint
   may be a member of multiple groups.  Group membership of an endpoint
   may dynamically change over time.

   All CoAP server nodes SHOULD join the "All CoAP Nodes" multicast
   group (Section 12.8 of [RFC7252]) by default to enable CoAP
   discovery.  For IPv4, the address is 224.0.1.187, and for IPv6, a
   server node joins at least both the link-local scoped address
   ff02::fd and the site-local scoped address ff05::fd.  IPv6 addresses
   of other scopes MAY be enabled.

   A CoAP group URI has the scheme 'coap' and includes in the authority
   part either a group IP multicast address or a hostname (e.g., Group
   Fully Qualified Domain Name (FQDN)) that can be resolved to the group

Top      ToC       Page 7 
   IP multicast address.  A group URI also contains an optional CoAP
   port number in the authority part.  Group URIs follow the regular
   CoAP URI syntax (Section 6 of [RFC7252]).

   Note: A group URI is needed to initiate CoAP group communications.
   For CoAP client implementations, it is recommended to use the URI
   decomposition method of Section 6.4 of [RFC7252] in such a way that,
   from a group URI, a CoAP group communication request is generated.

   For sending nodes, it is recommended to use the IP multicast address
   literal in a group URI.  (This is because DNS infrastructure may not
   be deployed in many constrained network deployments.)  However, in
   case a group hostname is used, it can be uniquely mapped to an IP
   multicast address via DNS resolution (if supported).  Some examples
   of hierarchical group FQDN naming (and scoping) for a building
   control application are shown below:

     URI authority                           Targeted group of nodes
     --------------------------------------- --------------------------
     all.bldg6.example.com                   "all nodes in building 6"
     all.west.bldg6.example.com              "all nodes in west wing,
                                              building 6"
     all.floor1.west.bldg6.example.com       "all nodes in floor 1,
                                              west wing, building 6"
     all.bu036.floor1.west.bldg6.example.com "all nodes in office bu036,
                                              floor 1, west wing,
                                              building 6"

   Similarly, if supported, reverse mapping (from IP multicast address
   to Group FQDN) is possible using the reverse DNS resolution technique
   ([RFC1033]).  Reverse mapping is important, for example, in
   troubleshooting to translate IP multicast addresses back to human-
   readable hostnames to show in a diagnostics user interface.

2.3.  Port and URI Configuration

   A CoAP server that is a member of a group listens for CoAP messages
   on the group's IP multicast address, usually on the CoAP default UDP
   port, 5683.  If the group uses a specified non-default UDP port, be
   careful to ensure that all group members are configured to use that
   same port.

   Different ports for the same IP multicast address are preferably not
   used to specify different CoAP groups.  If disjoint groups share the
   same IP multicast address, then all the devices interested in one
   group will accept IP traffic also for the other disjoint groups, only
   to ultimately discard the traffic higher in their IP stack (based on
   UDP port discrimination).

Top      ToC       Page 8 
   CoAP group communication will not work if there is diversity in the
   authority port (e.g., different dynamic port addresses across the
   group) or if other parts of the group URI such as the path, or the
   query, differ on different endpoints.  Therefore, some measures must
   be present to ensure uniformity in port number and resource names/
   locations within a group.  All CoAP group communication requests MUST
   be sent using a port number according to one of the below options:

   1.  A preconfigured port number.

   2.  If the client is configured to use service discovery including
       URI and port discovery, it uses the port number obtained via a
       service discovery lookup operation for the targeted CoAP group.

   3.  Use the default CoAP UDP port (5683).

   For a CoAP server node that supports resource discovery, the default
   port 5683 must be supported (Section 7.1 of [RFC7252]) for the "All
   CoAP Nodes" group.  Regardless of the method of selecting the port
   number, the same port MUST be used across all CoAP servers in a group
   and across all CoAP clients performing the group requests.

   All CoAP group communication requests SHOULD operate on group URI
   paths in one of the following ways:

   1.  Preconfigured group URI paths, if available.  Implementers are
       free to define the paths as they see fit.  However, note that
       [RFC7320] prescribes that a specification must not constrain or
       define the structure or semantics for any path component.  So for
       this reason, a predefined URI path is not specified in this
       document and also must not be provided in other specifications.

   2.  If the client is configured to use default Constrained RESTful
       Environments (CoRE) resource discovery, it uses URI paths
       retrieved from a "/.well-known/core" lookup on a group member.
       The URI paths the client will use MUST be known to be available
       also in all other endpoints in the group.  The URI path
       configuration mechanism on servers MUST ensure that these URIs
       (identified as being supported by the group) are configured on
       all group endpoints.

   3.  If the client is configured to use another form of service
       discovery, it uses group URI paths from an equivalent service
       discovery lookup that returns the resources supported by all
       group members.

Top      ToC       Page 9 
   4.  If the client has received a group URI through a previous RESTful
       interaction with a trusted server, it can use this URI in a CoAP
       group communication request.  For example, a commissioning tool
       may instruct a sensor device in this way to which target group
       (group URI) it should report sensor events.

   However, when the URI path is selected, the same path MUST be used
   across all CoAP servers in a group and all CoAP clients performing
   the group requests.

2.4.  RESTful Methods

   Group communication most often uses the idempotent CoAP methods GET
   and PUT.  The idempotent method DELETE can also be used.  The non-
   idempotent CoAP method POST may only be used for group communication
   if the resource being POSTed to has been designed to cope with the
   unreliable and lossy nature of IP multicast.  For example, a client
   may resend a multicast POST request for additional reliability.  Some
   servers will receive the request two times while others may receive
   it only once.  For idempotent methods, all these servers will be in
   the same state while for POST, this is not guaranteed; so, the
   resource POST operation must be specifically designed to take message
   loss into account.

2.5.  Request and Response Model

   All CoAP requests that are sent via IP multicast must be Non-
   confirmable (Section 8.1 of [RFC7252]).  The Message ID in an IP
   multicast CoAP message is used for optional message deduplication as
   detailed in Section 4.5 of [RFC7252].

   A server optionally sends back a unicast response to the CoAP group
   communication request (e.g., response "2.05 Content" to a group GET
   request).  The unicast responses received by the CoAP client may be a
   mixture of success (e.g., 2.05 Content) and failure (e.g., 4.04 Not
   Found) codes depending on the individual server processing results.
   Detailed processing rules for IP multicast request acceptance and
   unicast response suppression are given in Section 2.7.

   A CoAP request sent over IP multicast and any unicast response it
   causes must take into account the congestion control rules defined in
   Section 2.8.

   The CoAP client can distinguish the origin of multiple server
   responses by the source IP address of the UDP message containing the
   CoAP response or any other available unique identifier (e.g.,

Top      ToC       Page 10 
   contained in the CoAP payload).  In case a CoAP client sent multiple
   group requests, the responses are as usual matched to a request using
   the CoAP Token.

   For multicast CoAP requests, there are additional constraints on the
   reuse of Token values, compared to the unicast case.  In the unicast
   case, receiving a response effectively frees up its Token value for
   reuse since no more responses will follow.  However, for multicast
   CoAP, the number of responses is not bounded a priori.  Therefore,
   the reception of a response cannot be used as a trigger to "free up"
   a Token value for reuse.  Reusing a Token value too early could lead
   to incorrect response/request matching in the client and would be a
   protocol error.  Therefore, the time between reuse of Token values
   used in multicast requests MUST be greater than:

   NON_LIFETIME + MAX_LATENCY + MAX_SERVER_RESPONSE_DELAY

   where NON_LIFETIME and MAX_LATENCY are defined in Section 4.8 of
   [RFC7252].  MAX_SERVER_RESPONSE_DELAY is defined here as the expected
   maximum response delay over all servers that the client can send a
   multicast request to.  This delay includes the maximum Leisure time
   period as defined in Section 8.2 of [RFC7252].  CoAP does not define
   a time limit for the server response delay.  Using the default CoAP
   parameters, the Token reuse time MUST be greater than 250 seconds
   plus MAX_SERVER_RESPONSE_DELAY.  A preferred solution to meet this
   requirement is to generate a new unique Token for every multicast
   request, such that a Token value is never reused.  If a client has to
   reuse Token values for some reason, and also
   MAX_SERVER_RESPONSE_DELAY is unknown, then using
   MAX_SERVER_RESPONSE_DELAY = 250 seconds is a reasonable guideline.
   The time between Token reuses is in that case set to a value greater
   than 500 seconds.

2.6.  Membership Configuration

2.6.1.  Background

2.6.1.1.  Member Discovery

   CoAP groups, and the membership of these groups, can be discovered
   via the lookup interfaces in the Resource Directory (RD) defined in
   [CoRE-RD].  This discovery interface is not required to invoke CoAP
   group communications.  However, it is a potential complementary
   interface useful for overall management of CoAP groups.  Other
   methods to discover groups (e.g., proprietary management systems) can
   also be used.  An example of doing some of the RD-based lookups is
   given in Section 3.6.

Top      ToC       Page 11 
2.6.1.2.  Configuring Members

   The group membership of a CoAP endpoint may be configured in one of
   the following ways.  First, the group membership may be preconfigured
   before node deployment.  Second, a node may be programmed to discover
   (query) its group membership using a specific service discovery
   means.  Third, it may be configured by another node (e.g., a
   commissioning device).

   In the first case, the preconfigured group information may be either
   an IP multicast address or a hostname (FQDN) that is resolved later
   (during operation) to an IP multicast address by the endpoint using
   DNS (if supported).

   For the second case, a CoAP endpoint may look up its group membership
   using techniques such as DNS-based Service Discovery (DNS-SD) and RD
   [CoRE-RD].

   In the third case, typical in scenarios such as building control, a
   dynamic commissioning tool determines to which group(s) a sensor or
   actuator node belongs, and writes this information to the node, which
   can subsequently join the correct IP multicast group(s) on its
   network interface.  The information written per group may again be an
   IP multicast address or a hostname.

2.6.2.  Membership Configuration RESTful Interface

   To achieve better interoperability between endpoints from different
   manufacturers, an OPTIONAL CoAP membership configuration RESTful
   interface for configuring endpoints with relevant group information
   is described here.  This interface provides a solution for the third
   case mentioned above.  To access this interface, a client will use
   unicast CoAP methods (GET/PUT/POST/DELETE).  This interface is a
   method of configuring group information in individual endpoints.

   Also, a form of authorization (preferably making use of unicast DTLS-
   secured CoAP per Section 9.1 of [RFC7252]) should be used such that
   only authorized controllers are allowed by an endpoint to configure
   its group membership.

   It is important to note that other approaches may be used to
   configure CoAP endpoints with relevant group information.  These
   alternative approaches may support a subset or superset of the
   membership configuration RESTful interface described in this
   document.  For example, a simple interface to just read the endpoint
   group information may be implemented via a classical Management
   Information Base (MIB) approach (e.g., following the approach of
   [RFC3433]).

Top      ToC       Page 12 
2.6.2.1.  CoAP-Group Resource Type and Media Type

   CoAP endpoints implementing the membership configuration RESTful
   interface MUST support the CoAP group configuration Internet Media
   Type "application/coap-group+json" (Section 6.2).

   A resource offering this representation can be annotated for direct
   discovery [RFC6690] using the Resource Type (rt=) Link Target
   Attribute "core.gp", where "gp" is shorthand for "group"
   (Section 6.1).  An authorized client uses this media type to query/
   manage group membership of a CoAP endpoint as defined in the
   following subsections.

   The Group Configuration resource and its sub-resources have a content
   format based on JavaScript Object Notation (JSON) (as indicated by
   the "application/coap-group+json" media type).  The resource includes
   zero or more group membership JSON objects [RFC7159] in a format as
   defined in Section 2.6.2.4.  A group membership JSON object contains
   one or more key/value pairs as defined below, and represents a single
   IP multicast group membership for the CoAP endpoint.  Each key/value
   pair is encoded as a member of the JSON object, where the key is the
   member name and the value is the member's value.

   Examples of four different group membership objects are as follows:

      { "n": "All-Devices.floor1.west.bldg6.example.com",
        "a": "[ff15::4200:f7fe:ed37:abcd]:4567" }

      { "n": "sensors.floor2.east.bldg6.example.com" }

      { "n": "coap-test",
        "a": "224.0.1.187:56789" }

      { "a": "[ff15::c0a7:15:c001]" }

   The OPTIONAL "n" key/value pair stands for "name" and identifies the
   group with a hostname (and optionally the port number), for example,
   an FQDN.  The OPTIONAL "a" key/value pair specifies the IP multicast
   address (and optionally the port number) of the group.  It contains
   an IPv4 address (in dotted-decimal notation) or an IPv6 address.  The
   following ABNF rule can be used for parsing the address, referring to
   the definitions in Section 3.2.2 of [RFC3986] that are also used in
   the base CoAP (Section 6 of [RFC7252].

      group-address = IPv4address [ ":" port ]
                      / "[" IPv6address "]" [":" port ]

Top      ToC       Page 13 
   In any group membership object, if the IP address is known when the
   object is created, it is included in the "a" key/value pair.  If the
   "a" value cannot be provided, the "n" value MUST be included,
   containing a valid hostname with an optional port number that can be
   translated to an IP multicast address via DNS.

      group-name = host [ ":" port ]

   If the port number is not provided, then the endpoint will attempt to
   look up the port number from DNS if it supports a method to do this.
   The possible DNS methods include DNS SRV [RFC2782] or DNS-SD
   [RFC6763].  If port lookup is not supported or not provided by DNS,
   the default CoAP port (5683) is assumed.

   After any change on a Group Configuration resource, the endpoint MUST
   effect registration/deregistration from the corresponding IP
   multicast group(s) by making use of APIs such as IPV6_RECVPKTINFO
   [RFC3542].

2.6.2.2.  Creating a New Multicast Group Membership (POST)

   Method:       POST
   URI Template: /{+gp}
   Location-URI Template: /{+gp}/{index}
   URI Template Variables:
     gp    - Group Configuration Function Set path (mandatory).
     index - Group index.  Index MUST be a string of maximum two (2)
       alphanumeric ASCII characters (case insensitive).  It MUST be
       locally unique to the endpoint server.  It indexes the particular
       endpoint's list of group memberships.

   Example:
     Req: POST /coap-group
          Content-Format: application/coap-group+json
       { "n": "All-Devices.floor1.west.bldg6.example.com",
         "a": "[ff15::4200:f7fe:ed37:abcd]:4567" }
     Res: 2.01 Created
          Location-Path: /coap-group/12

   For the 'gp' variable, it is recommended to use the path "coap-group"
   by default.  The "a" key/value pair is always used if it is given.
   The "n" pair is only used when there is no "a" pair.  If only the "n"
   pair is given, the CoAP endpoint performs DNS resolution to obtain
   the IP multicast address from the hostname in the "n" pair.  If DNS
   resolution is not successful, then the endpoint does not attempt
   joining or listening to any multicast group for this case since the
   IP multicast address is unknown.

Top      ToC       Page 14 
   After any change on a Group Configuration resource, the endpoint MUST
   effect registration/deregistration from the corresponding IP
   multicast group(s) by making use of APIs such as IPV6_RECVPKTINFO
   [RFC3542].  When a POST payload contains an "a", an IP multicast
   address to which the endpoint is already subscribed, no change to
   that subscription is needed.

2.6.2.3.  Deleting a Single Group Membership (DELETE)

   Method:       DELETE
   URI Template: {+location}
   URI Template Variables:
     location - The Location-Path returned by the CoAP server
       as a result of a successful group creation.

   Example:
     Req: DELETE /coap-group/12
     Res: 2.02 Deleted

2.6.2.4.  Reading All Group Memberships at Once (GET)

   A (unicast) GET on the CoAP-group resource returns a JSON object
   containing multiple keys and values.  The keys (member names) are
   group indices, and the values (member values) are the corresponding
   group membership objects.  Each group membership object describes one
   IP multicast group membership.  If no group memberships are
   configured, then an empty JSON object is returned.

   Method: GET

   URI Template: /{+gp}

   URI Template Variables:

   gp - see Section 2.6.2.2

   Example:
     Req: GET /coap-group
     Res: 2.05 Content
          Content-Format: application/coap-group+json
       { "8" :{ "a": "[ff15::4200:f7fe:ed37:14ca]" },
         "11":{ "n": "sensors.floor1.west.bldg6.example.com",
                "a": "[ff15::4200:f7fe:ed37:25cb]" },
         "12":{ "n": "All-Devices.floor1.west.bldg6.example.com",
                "a": "[ff15::4200:f7fe:ed37:abcd]:4567" }
       }

Top      ToC       Page 15 
   Note: the returned IPv6 address string will represent the same IPv6
   address that was originally submitted in group membership creation,
   though it might be a different string because of different choices in
   IPv6 string representation formatting that may be allowed for the
   same address (see [RFC5952]).

2.6.2.5.  Reading a Single Group Membership (GET)

   Similar to Section 2.6.2.4, but only a single group membership is
   read.  If the requested group index does not exist, then a 4.04 Not
   Found response is returned.

   Method: GET

   URI Template 1: {+location}

   URI Template 2: /{+gp}/{index}

   URI Template Variables:

   location - see Section 2.6.2.3

   gp, index - see Section 2.6.2.2

   Example:
     Req: GET /coap-group/12
     Res: 2.05 Content
          Content-Format: application/coap-group+json
       {"n": "All-Devices.floor1.west.bldg6.example.com",
        "a": "[ff15::4200:f7fe:ed37:abcd]:4567"}

2.6.2.6.  Creating/Updating All Group Memberships at Once (PUT)

   A (unicast) PUT with a group configuration media type as payload will
   replace all current group memberships in the endpoint with the new
   ones defined in the PUT request.  This operation MUST only be used to
   delete or update group membership objects for which the CoAP client,
   invoking this operation, is responsible.  The responsibility is based
   on application-level knowledge.  For example, a commissioning tool
   will be responsible for any group membership objects that it created.

   Method: PUT

   URI Template: /{+gp}

   URI Template Variables:

   gp - see Section 2.6.2.2

Top      ToC       Page 16 
   Example: (replacing all existing group memberships with two new
             group memberships)
     Req: PUT /coap-group
          Content-Format: application/coap-group+json
       { "1":{ "a": "[ff15::4200:f7fe:ed37:1234]" },
         "2":{ "a": "[ff15::4200:f7fe:ed37:5678]" }
       }
     Res: 2.04 Changed

   Example: (clearing all group memberships at once)
     Req: PUT /coap-group
          Content-Format: application/coap-group+json
       {}
     Res: 2.04 Changed

   After a successful PUT on the Group Configuration resource, the
   endpoint MUST effect registration to any new IP multicast group(s)
   and deregistration from any previous IP multicast group(s), i.e., not
   any more present in the new memberships.  An API such as
   IPV6_RECVPKTINFO [RFC3542] should be used for this purpose.  Also, it
   MUST take into account the group indices present in the new resource
   during the generation of any new unique group indices in the future.

2.6.2.7.  Updating a Single Group Membership (PUT)

   A (unicast) PUT with a group membership JSON object will replace an
   existing group membership in the endpoint with the new one defined in
   the PUT request.  This can be used to update the group membership.

   Method: PUT

   URI Template 1: {+location}

   URI Template 2: /{+gp}/{index}

   URI Template Variables:

   location - see Section 2.6.2.3

   gp, index - see Section 2.6.2.2

   Example: (group name and IP multicast port change)
     Req: PUT /coap-group/12
          Content-Format: application/coap-group+json
       {"n": "All-My-Devices.floor1.west.bldg6.example.com",
        "a": "[ff15::4200:f7fe:ed37:abcd]"}
     Res: 2.04 Changed

Top      ToC       Page 17 
   After a successful PUT on the Group Configuration resource, the
   endpoint MUST effect registration to any new IP multicast group(s)
   and deregistration from any previous IP multicast group(s), i.e., not
   any more present in the new membership.  An API such as
   IPV6_RECVPKTINFO [RFC3542] should be used for this purpose.



(page 17 continued on part 2)

Next RFC Part