Welcome¶

Great that you considering the Eclipse IoT-Testware to test your implementations. We would like to guide you to start with the test suites.

Quickstart Guide¶

The easiest way to get started is to use Docker. The provided Dockerfile hides the complexity of TTCN-3 from the user. Therefore the user has more time to test his systems.

Preparation¶

Make sure you have a working Git installation
Make sure you have a working Docker installation
(optional) Set the following environment variables
```
TESTWARE=iot_testware
```

Installation¶

Clone the IoT-Testware Dashboard project

git clone https://github.com/eclipse/iottestware.dashboard
cd iottestware.dashboard

Build the Docker image

docker build -t $TESTWARE .

Start the Docker container

docker run --network=host -ti $TESTWARE

Call the Dashboard in your browser from https://localhost:3001

Installation¶

Target Environment¶

It is possible to install and run (parts of) the IoT-Testware in at least three different ways:

Dashboard
CLI
Manual

For each of the mentioned possibilities exists different requirements for the environment to be set up. Please consider your favorite way of using the IoT-Testware and make sure you fullfill all requirements.

Dashboard¶

Preparation¶

Make sure you have a working Git installation
Make sure you have a working Docker installation
(optional) Set the following environment variables
```
TESTWARE=iot_testware
```

Installation¶

Clone the IoT-Testware Dashboard project

git clone https://github.com/eclipse/iottestware.dashboard
cd iottestware.dashboard

Build the Docker image

docker build -t $TESTWARE .

Start the Docker container

docker run --network=host -ti $TESTWARE

Call the Dashboard in your browser from https://localhost:3001

Dockerized Command Line¶

If you are already familiar with concepts and the CLI of Eclipse Titan than this way is a light-weight solution to run the Testware without webserver and dashboard.

Preparation¶

Make sure you have a working Git installation
Make sure you have a working Docker installation

Installation¶

Clone the main IoT-Testware project

git clone https://github.com/eclipse/iottestware
cd iottestware

Build the Docker image

docker build -t TESTWARE .

Start the Docker container

docker run -ti TESTWARE /bin/bash

Run Test Campaigns¶

The IoT-Testware Docker image ships currently two test suites for MQTT and CoAP. We will show you quickly how to configure and run the test suites.

Starting test suites with TITAN

ttcn3_start [-ip host_ip_address] executable [file.cfg] {module_name[.testcase_name]}

Looks quite easy: in order to start a test campaign TITAN requires us to provide an executable test suite. As we want also be able to provide different kinds of configurations, we also need to provide a .cfg file. Fortunately, we already have all the components in Docker. Let’s see how we can run some MQTT conformance tests against your System Under Test (SUT).

Change directory to the MQTT playground and make yourself familiar with the provided files.

cd /home/titan/playground/mqtt; ls

By default, the public MQTT Broker iot.eclipse.org is preconfigured in the provided configuration file. If you want to change the default configuration follow the next instructions.

1.1 (optional) get started with your own configuration

cp BasicConfig.cfg YOUR_CONFIG.cfg
vi YOUR_CONFIG.cfg

1.2 (optional) to configure the TS (Test System) for your SUT you can change the hostName, portNumber and credentials definitions.

tsp_addresses :=
{
  {
    id := "mqtt_server",
    hostName := "iot.eclipse.org",
    portNumber := 1883
  }, {
    id := "mqtt_client",
    hostName := "0.0.0.0",
    portNumber := 45679,
    credentials :=
    {
      clientId := "CLIENT_ID",
      username := "USER_NAME",
      password := "PASSWORD",
      topicName := "your/mqtt/topic/name"
    }
  }
}

1.3 (optional) put together your own test campaing by choosing test cases from the [EXECUTE] section.

Note

The configuration file can contain any white space characters. There are three ways to put comments in the file: you can use the C comment delimiters (i.e. /* and */). Additionally, characters beginning with # or // are treated as comments until the end of line.
[EXECUTE]
### CONNECT Control Packet
MQTT_TestCases.TC_MQTT_BROKER_CONNECT_001   # <- will execute
MQTT_TestCases.TC_MQTT_BROKER_CONNECT_002   # <- will execute
#MQTT_TestCases.TC_MQTT_BROKER_CONNECT_003  # <- won't execute
...

2.1 Run the whole test campaign given in YOUR_CONFIG.cfg

ttcn3_start iottestware.mqtt YOUR_CONFIG.cfg

2.2 (alternative) Run a single test case TC_MQTT_BROKER_CONNECT_001 from MQTT_TestCases

ttcn3_start iottestware.mqtt YOUR_CONFIG.cfg MQTT_TestCases.TC_MQTT_BROKER_CONNECT_001

Manual Installation¶

The IoT-Testware is composed of several test suites from different repositories with once again several dependencies to the Eclipse Titan runtime. Hence, the process for a native installation can become quite complex. However, a native installation is very helpful for development. Therefore we provide additional ‘flavours’ of installation for development purposes.

We highly recommend to consider the Titan installation guide to set up Titan properly (check the supported OS ons the side beforehand).
If you are not using one of the supported OS, we recommend to set up a virtual machine or use Titan with Docker.

install.py ¶

This documentation helps you to understand and use the install.py script.

Contents

install.py

Prerequisites ¶

Latest version of Python
Latest version of Eclipse Titan. For installation details please consult the official downloads

help command ¶

You can refer to the help command if you don’t know how to continue at any point. Simply run one the following command:

python install.py -h
python install.py --help

The result gives you a first idea, what is possible with the script. The output looks like this:

`-h`	show this help message and exit
`-p PROTO`	available protocol test suites are {mqtt, coap, opcua} sets a protocol that will be cloned together with its dependencies
`-b`	build the project and create a Makefile
`--path PATH`	specify optionally your root directory, where all dependencies will be stored
`-e NAME`	set the name of the executable that will be generated
`-v`	progress status output is verbose

protocol command ¶

The protocol command is the a mandatory flag. It will scan your working directory to check whether all dependencies are met. In case there is something missing, the script will download the missing dependencies automatically. The command demands a parameter representing the interesting protocol.

Let’s assume you would like to run tests against a CoAP implementation. Run one of the following command to get the CoAP conformance test suite and all it’s dependencies:

python install.py -p coap
python install.py --protocol coap

Use the same procedure for any available protocol.

build command ¶

This optional command can be used to build the IoT-Tesware. It builds a Makefile first and creates an executable afterwards. You can only build one protocol at a time. It is determined by the protocol command. To build the CoAP test suite for example, run one of the following commands:

python install.py -p coap -b
python install.py -p coap --build

path command ¶

When you run the install script, it creates a folder structure under ~/Titan by default. This is your base directory where the IoT-Testware and all it’s dependencies are stored:

IoT-Testware You find the test suites for the protocols you have chosen via the protocol command. It creates a folder for every protocol separately in the form of iottestware.<PROTOCOL>

Libraries Collection of libraries needed for the specific IoT-Testware protocol.

ProtocolModules The protocol modules, provided in developer resources, are included inside this directory. The subset of protocol modules are protocol dependent. They define the protocol types.

TestPorts To bridge the gap between the test suite and the system under test (SUT), test ports are needed. They are provided by Eclipse Titan project.

executable command ¶

With this command it is possible to name the executable that is generated when calling the build command. In contrast, the install script chose a default name for the executable following the scheme:

iottestware.<PROTOCOL>

To set your own name for the resulting executable, let’s say “myExecutable” simply run one of this command:

python install.py -p coap -e myExecutable
python install.py -p coap --executable_name myExecutable

verbose command ¶

If you set this command, the console output will be verbose and give you more information during the process. By default, the output is quite, meaning only important messages are shown. To switch the verbose output on, you add either `` -v `` or `` –verbose `` to your command like in the following examples:

python install.py -p coap --verbose -e myExecutable
python install.py -p coap -b -v
python install.py --verbose --protocol coap

Install with Eclipse IDE ¶

These instructions will get you a clean IoT-Testware clone up and running on your local machine for development and testing purposes.

Contents

Install with Eclipse IDE

Prerequisites ¶

Latest version of Java
Latest version of Python (v2 or v3)
Latest version of Eclipse Titan. For installation details please consult the official Eclipse Titan

Installing Quickstart ¶

Note: Make sure all prerequisites are met. As we use Eclipse Titan (natively running under Linux) to compile and execute our test suite, the following instruction won’t cover other OS like Windows or MacOS. We recommend installing a Linux derivate in a virtual machine.

Set up ¶

Firstly, you need to get all needed dependencies to run the test suites. To do so, simply run the python script install.py with your protocol of choice:

python install.py -p <PROTOCOL>

This is the most minimalistic way of getting the dependencies. For a more complete explanation of the installation script please refer to the documentation. With Eclipse Titan you are free to choose to work either from the Command Line (CLI) or from Eclipse IDE. Go ahead and read further instructions of your preferred way of working.

Eclipse IDE ¶

In every of our protocol repositories you find a iottestware.<PROTOCOL>.tpd file that you need to import. Open the Titan IDE in your desired workspace and use the import feature File -> Import -> TITAN -> Project from .tpd file

Klick Next and choose the iottestware.<PROTOCOL>.tpd from ${PATH_BASE}

Klick Next and choose importation options.

Klick Finish and the IDE will import all the required Projects and open the properties for each. Make sure each project is configured to _generate Makefile for use with the function test runtime_.

Right-click the iottestware.<PROTOCOL> project and select Build Project.

Note: Make sure you are in the TITAN Editing Perspective, otherwise the Build Project might be not available.

Install with Docker ¶

For an easy deployment, you can use the shipped Dockerfile coming with the repository.

Contents

Install with Docker

Docker is a computer program that performs operating-system-level virtualization. It uses the resource isolation features of the Linux kernel to allow independent containers to run within a single Linux instance, avoiding the overhead of staring and maintaining virtual machines.

Docker will perform all the heavy lifting of virtualization and running the IoT-Testware including Eclipse Titan. Therefore, an installed and functioning Docker is the only prerequisite.

Note

Although, it is possible to run Docker containers on different operating systems, Docker’s host networking driver only works on Linux hosts. Hence, it is recommended to run the Docker containers on a Linux machine.

Preparations ¶

Make sure you have a working Docker installation

(optional) Set the following environment variables

TW_CONTAINER_NAME=iot_testware
TW_NETWORK_NAME=iottestware_net
TW_SUBNET=172.18.0.0/16
TW_FIXED_IP=172.18.0.4

TW_VOLUME_NAME=testware_volume
TW_VOLUME_PATH=/home/titan/iottestware.webserver/backend/resources/history

(optional) Create separated Docker network

docker network create --subnet $TW_SUBNET $TW_NETWORK_NAME
docker network ls

(optional) Create persistend storage and docker volumes
```
docker volume create $TW_VOLUME_NAME
```
Build the Docker container
```
docker build -t $TW_CONTAINER_NAME .
```

Additional Docker commands ¶

Stop all running container
```
docker stop $(docker ps -aq)
```
Delete all containers
```
docker rm $(docker ps -aq)
```
Delete all images
```
docker rmi $(docker images -q)
```
Force delete a specific image
```
docker rmi -f <IMAGE_ID>
```

open second bashwindow

docker exec -it <CONTAINER_ID> /bin/bash

Start Docker container ¶

Docker offers many options for starting and integrating containers. In this section we will show how the container can be started with persistend storage and how to attach the container to the previously created sub-network. Read the Docker networking overview for more information.

Most basic way to start a Docker container without persistend storage and using the host’s network interface

docker run --network host $TW_CONTAINER_NAME

Isolated Docker container which is attached to the sub-network with a fixed IP and without persistend storage

docker run --network $TW_NETWORK_NAME --ip $TW_FIXED_IP $TW_CONTAINER_NAME

Using host’s network interface and with persistend storage

docker run --network host -v $TW_VOLUME:$TW_VOLUME_PATH $TW_CONTAINER_NAME

Isolated Docker container which is attached to the sub-network with a fixed IP and with persistend storage

docker run --network $TW_NETWORK_NAME --ip $TW_FIXED_IP -v $TW_VOLUME:$TW_VOLUME_PATH $TW_CONTAINER_NAME

Run the Dashboard ¶

Note

This step requires that you have used the Dashboard Docker file

Once everything is correctly deployed and started you can access the IoT-Testware Dashboard from your browser. Dependent on you network configuration simply open one of the following URLs in your browser:

If you used the host network for the container: https://localhost:3001
If you deployed the container with a custom network and given fixed IP: https://$TW_FIXED_IP:3001

Useful

Protocol Conformance Testing ¶

Contents

Protocol Conformance Testing

General ¶

The purpose of conformance testing is to determine to what extent a single implementation of a particular standard conforms to the individual requirements of that standard. Please find additional and more detailed information about conformance testing at ETSI’s Center for Testing & Interoperability

The ISO standard for the methodology of conformance testing (ISO/IEC 9646-1 and ISO/IEC 9646-2) as well as the ETSI rules for conformance testing (ETSI ETS 300 406) are used as a basis for the test methodology.

To implement this methodology we require several intermediary artefacts. Those single artefacts break down the whole complexity of conformance testing into smaller pieces, each with a specific perspective on the problem.

Test Suite Structure ¶

In the first step we define a TSS for a specific IUT.

The TSS reflects the coverage of the reference specification by the TS: it is a synopsis of “which tests are performed on which aspects of the reference specification”. The conformance requirements and the ICS proforma of the base specification are an essential source of cross-reference to check that the coverage of the test suite specified by the TSS&TP is acceptable.

Test Configurations ¶

TODO: Why do we need Test configurations?

Test Purpose Catalogues ¶

A TP (Test Purpose) is a formal description of a test case. A formal description in the form of a TP offers a possibility of describing the purpose of a test without having the later technical implementation in mind. Following the TSS the tester is supported in systematically covering the complete IUT specification.

The listing below shows a simple MQTT TP specified in TDL-TO.

Test Purpose {
  TP Id TP_MQTT_Broker_CONNECT_001

  Test objective
  "The IUT MUST close the network connection if fixed header flags in CONNECT Control Packet are invalid"
  Reference
    "[MQTT-2.2.2-1], [MQTT-2.2.2-2], [MQTT-3.1.4-1], [MQTT-3.2.2-6]"
  PICS Selection PICS_BROKER_BASIC

  Expected behaviour
  ensure that {
    when {
        the IUT entity receives a CONNECT message containing
        header_flags indicating value '1111'B;
    }
    then {
        the IUT entity closes the TCP_CONNECTION
    }
  }
}

The exemple below shows a simplified tabular representation for the TP.

TP-ID	TP_MQTT_BROKER_CONNECT_01
Selection	PICS_Broker
Summary	The IUT MUST close the network connection if…
Reference	[MQTT-2.2.2-1], [MQTT-2.2.2-2]
Expected bahaviour
initial condition statement
ensure that statement

IoT-Testware Test Suites ¶

This steps focuses on a technical implementation of the TPs. We use TTCN-3 and Eclipse Titan to implement each TP into a TC and orchestrate to executable test suites.

MQTT Test Suite ¶

Contents

MQTT Test Suite

MQTT Protocol ¶

A very brief summary of MQTT from the FAQ: MQTT stands for MQ Telemetry Transport. It is a publish/subscribe, extremely simple and lightweight messaging protocol, designed for constrained devices and low-bandwidth, high-latency or unreliable networks.

Note

We provide an annotated version of the official MQTT specification which can be directly referenced (e.g. [MQTT-1.5.3-1] and [MQTT-1.5.3-2])

Test Configurations ¶

From a general and abstract perspective MQTT has two basic architectures for testing. This architecture directly reflects the choice of your SUT. We will call the first architecture Broker Testing. A MQTT Broker is the SUT as shown in the figure blow:

The second major architecture we will call Client Testing as now, the Client is in focus as the SUT.

Now we can start to extract different configurations from the test architectures. The image below depicts the step of retrieving test configurations from the architecture:

The output of this exemplary step is a test configuration (CF01) where the Broker is the SUT and the TS takes the role of a MQTT Client.

The MQTT test suite uses four test configurations in order to cover the different test scenarios. In these configurations, the tester simulates one or several MQTT clients or brokers implementing the MQTT protocol.

ID:	MQTT_Conf_01
Description:	The MQTT Broker is the IUT and the TS takes the role of a MQTT Client

ID:	MQTT_Conf_02
Description:	The MQTT Broker is the IUT and the TS takes the role of multiple MQTT Clients.

ID:	MQTT_Conf_03
Description:	The MQTT Client is the IUT and the TS takes the role of a MQTT Broker. For this configuration an optional UT might be required.

ID:	MQTT_Conf_04
Description:	As well the MQTT Broker as the MQTT Client, each is a IUT in this configuration. The part of the UT from the previous configuration is here replaced by a concrete application.

Test Purposes ¶

TODO: link to .tplan2 from GitHub and .pdf from ETSI

  Test Purpose {
    TP Id TP_MQTT_Broker_CONNECT_001

    Test objective
    "The IUT MUST close the network connection if fixed header flags in CONNECT Control Packet are invalid"
    Reference
      "[MQTT-2.2.2-1], [MQTT-2.2.2-2], [MQTT-3.1.4-1], [MQTT-3.2.2-6]"
    PICS Selection PICS_BROKER_BASIC

    Expected behaviour
    ensure that {
      when {
          the IUT entity receives a CONNECT message containing
          header_flags indicating value '1111'B;
      }
      then {
          the IUT entity closes the TCP_CONNECTION
      }
    }
  }

Test System ¶

TODO: describe Test System -> TTCN-3 code

Test Cases ¶

You can find all MQTT Tests on GitHub.

We will examine the procedure of a single TC in order to get the understanding of the code structure.

The code block below shows the TTCN-3 implementation of the TC TC_MQTT_BROKER_CONNECT_01 for the cohesive TP TP_MQTT_BROKER_CONNECT_01

/*
* @purpose The IUT MUST close the network connection if fixed header flags in CONNECT Control Packet are invalid
*
* @reference [MQTT-2.2.2-2], [MQTT-3.1.4-1], [MQTT-3.2.2-6]
*/
testcase TC_MQTT_BROKER_CONNECT_001() runs on MQTT_Client
{
  if(f_init("mqtt_client", "mqtt_server"))
  {
    f_TC_MQTT_BROKER_CONNECT_001();
  }
  f_cleanUp();
}

Let’s have a deeper look into the details of a TC. The first block comment contains only two TTCN-3 documentation tags but these give us a direct connection between a TC, a TP, and the MQTT specification.

/*
* @purpose The IUT MUST close the network connection if fixed header flags in CONNECT Control Packet are invalid
*
* @reference [MQTT-2.2.2-2], [MQTT-3.1.4-1], [MQTT-3.2.2-6]
*/

The signature of a TTCN-3 TC contains many information which help us to reflect the Test Architecture.

testcase TC_MQTT_BROKER_CONNECT_001() runs on MQTT_Client

We have a distinct name for the TC which can be easy mapped to it’s cohesive TP. (see in the MQTT |tp| catalogue for TP_MQTT_BROKER_CONNECT_001) The signature tells us also, that this TC will be executed on a Client (runs on MQTT_Client).

The body of the TC is used to initialize the test configuration and start the TC behaviour which is wrapped into a single function.

  if(f_init("mqtt_client", "mqtt_server"))
  {
    f_TC_MQTT_BROKER_CONNECT_001();
  }
  f_cleanUp();

Test Case Functions ¶

How does a TC function look like?

function f_TC_MQTT_BROKER_CONNECT_001() runs on MQTT_Client
{
  var UTF8EncodedString v_clientId := f_getClientId();

  var template MQTT_v3_1_1_Message v_conMsg := t_connect_flags(p_client_id := v_clientId, p_flags := '1111'B);
  f_send(valueof(v_conMsg));

  if(f_receiveNetworkClosedEvent())
  {
    setverdict(pass, "IUT closed the Network Connection correctly");
  }
  else
  {
    setverdict(fail, "IUT MUST close the Network Connection");
    f_disconnectMqtt();
  }
}

While syntactically this function might appear confusing, though the semantic behind is quite powerful and simple. Let’s go through the implemented TC and the according TP.

Translation Port ¶

TODO: Explain translation port

Generic Functions ¶

TODO: describe MQTT_Functions module

Test Templates ¶

TODO: describe templates

Default Behaviours ¶

TODO: describe the default behaviours

CoAP Test Suite ¶

Contents

CoAP Test Suite

CoAP Protocol ¶

CoAP is a specialized Internet Application Protocol for constrained devices, as defined in RFC 7252: The Constrained Application Protocol (CoAP) is a specialized web transfer protocol for use with constrained nodes and constrained (e.g., low-power, lossy) networks. The nodes often have 8-bit microcontrollers with small amounts of ROM and RAM, while constrained networks such as IPv6 over Low-Power Wireless Personal Area Networks (6LoWPANs) often have high packet error rates and a typical throughput of 10s of kbit/s. The protocol is designed for machine- to-machine (M2M) applications such as smart energy and building automation.

Note

We provide an annotated version of the official RFC which can be directly referenced (e.g. [CoAP-3.0-3] or [CoAP-3.0-4])

Test Configurations ¶

The concrete CoAP test configurations are listed below:

ID:	CoAP_Conf_01
Description:	The CoAP Server is the IUT and the TS takes the role of a CoAP Client

ID:	CoAP_Conf_02
Description:	The CoAP Server is the IUT and the TS takes the role of multiple CoAP Clients.

ID:	CoAP_Conf_03
Description:	The CoAP Client is the IUT and the TS takes the role of a CoAP Server. For this configuration an optional UT might be required.

ID:	CoAP_Conf_04
Description:	As well the CoAP Server as the CoAP Client, each is a IUT in this configuration. The part of the UT from the previous configuration is here replaced by a concrete application.

Test Purposes ¶

TODO: link to .tplan2 from GitHub and .pdf from ETSI

  Test Purpose {
     TP Id TP_CoAP_MessageFormat_Header_Version_001

     Test objective
     "The IUT is responding on a correctly set version number."

     Reference
     "RFC7252#section-3", "https://tools.ietf.org/html/rfc7252#section-3",
     "RFC7252#section-4.1", "https://tools.ietf.org/html/rfc7252#section-4.1",
     "RFC7252#section-4.2 (b)", "https://tools.ietf.org/html/rfc7252#section-4.2"

     PICS Selection PIC_Server

     Expected behaviour
     ensure that {
        when {
           the IUT entity receives a request message containing
              version indicating value 1,
              msg_type indicating value 0, //Confirmable
              token_length indicating value 0,
              code indicating value 0.00, //Empty Message
              msg_id corresponding to MSG_ID1;
        } then {
           the IUT entity sends a response message containing
              version indicating value 1,
              msg_type indicating value 3, //Reset
              token_length indicating value 0,
              code indicating value 0.00, //Empty Message
              msg_id corresponding to MSG_ID1;
           or the client entity times_out //from section 4.2 (b)
        }
     }
  }

Test System ¶

TODO: describe Test System -> TTCN-3 code

Test Cases ¶

You can find all CoAP Tests on GitHub.

testcase TC_COAP_SERVER_001() runs on MTC_CT
{
  map(self:p, system:p);
  f_TC_COAP_SERVER_001();
  unmap(self:p, system:p);
}

Test Case Functions ¶

TODO: describe a CoAP Test Case Function

function f_TC_COAP_SERVER_001() runs on MTC_CT
{
  f_sendMessage(m_coapPingMessage);
  f_receiveMessage(m_coapEmptyMessage);
}

Translation Port ¶

TODO: Explain translation port

Generic Functions ¶

TODO: describe MQTT_Functions module

Test Templates ¶

TODO: describe templates

Default Behaviours ¶

TODO: describe the default behaviours

OPC-UA Test Suite¶

ETSI and Eclipse Foundation¶

Test projects currently cover MQTT, CoAP, Lo-RaWAN and foundational security IoT-Profile of IEC 62443-4-2. The work of ETSI MTS-TST is correlated with the IoT-Testware which is hosted by the Eclipse Foundation. The technical contributions from the Eclipse members are coordinated by several dedicated Eclipse committers. The work includes Test purposes in TDL (primarily TDL-TO which is an extension of TDL for Structured Test Objective Specification) but also TTCN-3 test code developments that is important for test campaign execution in the test labs. In particular, ETSI members from MTS-TST control the test purposes developments and are responsible for the utilization of the resulting TP definitions for the ETSI working items and technical specifications. This approach allows to get input from active developers from the Eclipse community and a fast implementation of the target test suites for the interested industry but also support a faster develop-ment of ETSI specifications.

The illustrates an overview regarding two development procedures and its relationships: (a) the defini-tion and implementation of the target system (under test) that needs to address subjects, assets and require-ments as well as threats, policies and assumptions, and (b) the test development including test architecture, test purposes and test suite structure. System and test engi-neers need to derive the test implementation to be executed and analysed, e.g. for certification purposes.

Dashboard ¶

Contents

Dashboard

Introduction ¶

The Eclipse IoT-Testware Dashboard is a collection of several tools and test suites which makes it extremely flexible and powerful. Firstly the Backend which runs in background and provides the core functionality. Secondly, the Frontend, a thin ReactJS Application which provides a convenient user interface. And last but not least, the IoT-Testware with the test suites itself.

Overview ¶

The first picture gives a brief overview about the basic idea.

Building upon the overview, the next picture is intended to give a more detailed view on the whole system.

Backend ¶

The backend component is a node.js application which is intended to abstract the “low-level” handling of testing tools and their configurations.

Frontend ¶

The frontend component is a JavaScript application which serves as a user interface to the backend component. Through the nature of the architecture the frontend is intended to be a thin client.

Integration ¶

The sequence diagram below gives an overview about the interaction of involved components, starting from the user and ending with the SUT.

Fuzzing¶

TODO: What is fuzzing and how do we make use of fuzzing?

Smart Fuzzing Proxy ¶

Contents

Installation ¶

Prerequisite ¶

Make sure the following prerequisites are met.

Python (at least version 3, 3.7 is recommended)
pip
python3-venv

Set-up a Virtual Environment ¶

The Fuzzing Proxy requires a set of external libraries which must be installed beforehand. To get you started as easy as possible, a helping Monkey (based on the Infinite monkey theorem) is provided to assist you with your fuzzing endeavor. Provided that your system meets the prerequisites, instruct the Monkey to setup a virtual environment for you:

./monkey setup

This will create a Python virtual environment in ./venv directory.

Manual Set-up of a Virtual Environment ¶

The previously introduced Bash script provides an easy way to set up a virtual environment and installation of all required dependencies. However, the script might fail or you just might want to set up the virtual environment on your own. In this case the following steps will be required.

Create a virtual environment with python3 -m venv {VENV_DIRECTORY}
Activate the virtual environment with source {VENV_DIRECTORY}/bin/activate
Install pipenv for your virtual environment with pip install pipenv
Install all required libraries with pipenv install
1. if installation fails with a FileNotFoundError probably pdflatex is missing as discussed on GitHub
2. Quickfix: simply install LaTeX with e.g. apt install texlive-latex-base and repeat step 4

Note

If you choose to create your {VENV_DIRECTORY} other than ./venv the Monkey won’t be any longer able to find your virtual environment. To overcome this issue you will either need change the directory in the monkey script or simply replace monkey with python3 proxy.py in the following examples.

Quickstart ¶

To start the Fuzzing Proxy against iot.eclipse.org:1883 with a sample configuration execute the following command:

./monkey fuzzing -l 1883 -r iot.eclipse.org -c resources/samples/mqtt_01.json

This will start the Fuzzing Proxy which will proxy the MQTT traffic from your local machine to iot.eclipse.org and vice versa.

You can further explore the functionalities provided by the Fuzzing Proxy by using the built-in help.

./monkey --help
./monkey {command} --help

Important

Do not fuzz against production environments or systems other than your ones without permission.

General Concept ¶

The Fuzzing Proxy is a MITM (Man-in-the-middle) Fuzzer which is capable of proxying the network traffic between to systems and altering this traffic on behalf of predefined rules. The Fuzzing Proxy does not generate any message on it’s own. To trigger the fuzzing you need to provide (more or less) valid templates.

In the next sections we will show you how to use the Fuzzing Proxy by applying a 5 Steps Fuzzing Workflow as shown in the following graphic.

Identify the SUT ¶

Identifying the SUT (System Under Test) is the first step in the workflow.

Note

Needs to be further documented.

Identify Input fields ¶

Identifying input fields and corresponding mutators for your fuzzing session is probably the most challenging part in the whole workflow. In this section we will demonstrate how interesting input fields can be chosen and corresponding mutators defined in the configuration file.

The configuration file provided to the Fuzzing Proxy contains abstract fuzzing instructions which are used at runtime for manipulation of proxied messages. This section will explain the basic concepts behind the configuration file and show you how to build a fuzzing scenario.

The configuration file is a plain JSON file following a specific schema. Below each single configuration block is described in detail.

Protocol Module ¶

First, we will start with the protocolModule block which simply defines some basic information about the fuzzed protocol.

{
  "protocolModule": {
    "protocol": "MQTT",
    "encoding": "utf-8",
    "payload": "json" }
}

protocol obviously, defines which protocol will be used.
encoding defines how strings within the protocol fields should be handled.
payload defines how to handle payloads within messages. Currently, only json and raw are possible.

You can simply ask the Monkey to tell you the supported protocols:

./monkey protocols

Protocol Message Examples ¶

For the next steps we will require some insights into the protocol chosen in the protocol module. Especially, the field namings and message structures provided by Scapy (which is used to decode and encode the messages) are required in the next steps. To get familiar with Scapy’s representation of protocol messages, you can use some provided message examples.

Again, simply ask the Monkey to give you some examples for your chosen protocol:

./monkey samples mqtt

Fuzzdata Generators ¶

The Fuzzing Proxy is capable of using multiple fuzzdata generators. Currently, only a basic random generator is implemented. However, the integration of different kinds of more sophisticated fuzz-data generators like Fuzzino might be implemented in the future.

{
  "generators": [
  { "id": "g_rand_uniform" },
  { "id": "g_rand_uniform_2" },
  { "id": "g_with_seed", "seed": 123 } ]
}

For now, each basic generator requires only an unique id which we will use later on to reference the generators. Additionallly, each generator can be initialised with a predefined seed for deterministic results.

Note

Generator IDs are enforced to start with g_

Fuzzing Mutators ¶

Now things start getting interesting. Fuzzing Mutators are one of the basic concepts of the Fuzzing Proxy. The following block shows a set of different mutators, which will be explained in detail afterwards.

{
  "mutators": [
  { "id": "m_xor_protoname_fixed", "field": "protoname", "binary": "XOR", "hex": "0xA5A5" },
  { "id": "m_inc_protolevel", "field": "protolevel", "unary": "INCR" },
  { "id": "m_inc_clientid_len", "field": "clientIdlen", "unary": "INCR" },
  { "id": "m_replace_clientid", "field": "clientId",  "binary": "SET", "generator": "g_with_seed" },
  { "id": "m_replace_username", "field": "username",  "binary": "SET", "generator": "g_rand_uniform_2" },
  { "id": "m_invert_username_flag", "field": "usernameflag", "unary": "NOT" },
  { "id": "m_invert_flags_dup", "field": "DUP", "unary": "NOT" },
  { "id": "m_invert_flags_qos", "field": "QOS", "unary": "NOT" }]
}

Note

Mutator IDs are enforced to start with m_

Generally, each mutator requires an unique id and is always bound to a specific message field with an operation. For now, two kinds of operations exist: unary and binary operations.

Unary Operators ¶

Unary Operators, as the name implies, are unary with respect to the number of parameters which they expect. An unary operator expects only one single parameter. It takes the value of the specified field (as the one and only parameter) and applies a fuzzing operation on it. The following example of an increment operator is an unary operation without any additional parameter:

{ "id": "m_inc_protolevel", "field": "protolevel", "unary": "INCR" }

Or, if you want to think about the mutator in a more functional way:

function increment(value) => { return (value + 1) }

protolevel := increment(protolevel)

The class of Unary Operators has the following concrete operators:

INCR which simply increments the given value by one
DECR which simply decrements the given value by one
NOT which simply inverts the given value

Binary Operators ¶

Binary Operators on the other hand, take two parameters, the value of the specified field and either a fixed value or a generator as the second parameter. The following example of a xor operator is a binary operator with a fixed value:

{ "id": "m_xor_protoname_fixed", "field": "protoname", "binary": "XOR", "hex": "0xA5A5" }

This mutator will take value of the field protoname and apply the XOR operator with a fixed hex value of 0xA5A5. Or, if you want to think about the mutator in a more functional way:

function xor(value, mask) => { return (value ^ mask) }

protoname := xor(protoname, 0xA5A5)

Additionally, Binary Operators can be also provided with generators which generate dynamically (random) values. The following example of a set operator is a binary operator with a dynamically generated value:

{ "id": "m_replace_clientid", "field": "clientId",  "binary": "SET", "generator": "g_with_seed" }

This mutator will take the value of the field clientId and appyl the SET operator with a dynamically generated value generated by the generator with the ID g_with_seed. Or, if you want to think about the mutator in a more functional way:

function set(value, generator) => { return generator.rand(typeof(value)) }

clientId := set(clientId, g_with_seed)

All Binary Operators can either be used with a fixed and predefined hex-value or with a generator. The example below is also perfectly valid:

{ "id": "m_replace_clientid", "field": "clientId",  "binary": "SET", "hex": "0xA5A5" }
{ "id": "m_xor_protoname_fixed", "field": "protoname", "binary": "XOR", "generator": "g_with_seed" }

In a functional representation, these would look as follows:

function set(field, hex_mask) => { return hex_mask) }
function xor(field, generator) => { return (field ^ generator.rand(typeof(field)) }

clientId := set(clientId, 0xA5A5)
protoname := xor(protoname, g_with_seed)

The class of Binary Operators has the following concrete operators:

XOR which applies an xor operation with the given second parameter on the given value
AND which applies an and operation with the given second parameter on the given value
OR which applies an or operation with the given second parameter on the given value
SET which applies an set operation with the given second parameter on the given value

Filters ¶

After mutators, filters are the second building blocks on the path of building fuzzing rules. These fuzzing filters are conceptually very similar to Wireshark’s DisplayFilters and serve pretty much the same purpose. As one might want to intercept more complex protocol behaviours, altering each single message would be a bad idea. The concept of filters allows the user to pick only specific messages for fuzzing, while other message not matching any filter are simply passed through without being fuzzed. The given example below contains two filters which will be explained in more detail afterwards:

{
  "filters": [
  {
    "id": "f_all_connect",
    "description": "This filter matches all connect packets",
    "direction": "Request",
    "filter": { "field": "type", "op": "-eq", "value": 1 }
  }, {
    "id": "f_publish_subscribe",
    "descritpion": "Matches all publish or subscribe or unsubscribe packets",
    "direction": "All",
    "left": {
      "left": { "filter": { "field": "type", "op": "-eq", "value": 3 } },
      "op": "OR",
      "right": { "filter": { "field": "type", "op": "-eq", "value": 8 } } },
    "op": "OR",
    "right": { "filter": { "field": "type", "op": "-eq", "value": 10 } }
  } ]
}

Note

Filter IDs are enforced to start with f_

The first filter with the ID f_all_connect is a quite simple one and more or less self explanatory. However, the filter demonstrates the basic concept. While id and description are quite obvious, the direction and filter fields require a little more explanation.

Filter Direction ¶

The direction field defines the direction of the filter. Valid directions are Request, Response and All. Filters with "direction": "Request" will be only applied on messages passing through the Fuzzing Proxy from the client to the server. On the other hand, filters with "direction": "Response" will only look for responses coming from the server. And obviously, "direction": "All" will look for both directions.

Filter Definition ¶

The filter field is actually the part which defines the filtering criteria. The following example filter matches all packets of the type = 1 (the CONNECT Control Packet in case of MQTT):

{ "filter": { "field": "type", "op": "-eq", "value": 1 } }

Conceptually, this filter can be thought of as follows:

But filters can be more complex and contain multiple filtering criteria as demonstrated by the filter with the ID f_publish_subscribe: This filter contains a combination of three simple filters.

{
  "left": {
    "left": { "filter": { "field": "type", "op": "-eq", "value": 3 } },
    "op": "OR",
    "right": { "filter": { "field": "type", "op": "-eq", "value": 8 } } },
  "op": "OR",
  "right": { "filter": { "field": "type", "op": "-eq", "value": 10 } }
}

Conceptually, this filter can be thought of as follows:

As one can see, we have two types of operators (op) in filters. The comparison operators are used within concrete filter definitions as shown below:

Valid comparison operators are:

-eq which stands for ==
-ne which stands for !=
-gt which stands for >
-lt which stands for <
-ge which stands for >=
-le which stands for <=

The logical operators, on the other hand, are used to combine multiple single filter logically.

Valid logical operators are: OR, and AND

Rules ¶

Finally, the Rules Engine can be build by combining mutators and filters to concrete fuzzing rules. The given example below contains two rules which will be explained in more detail afterwards:

{
  "rules": [
  {
    "match": "f_all_connect",
    "mutators": [ "m_inc_clientid_len", "m_xor_protoname_fixed", "m_inc_protolevel" ]
  }, {
    "match": "f_publish_subscribe",
    "distribution": {
      "model": "multinomial",
      "seed": 12345,
      "nxp": 10
      "items": [
        { "strength": 11, "mutators": [ "m_invert_flags_retain", "m_inc_flags_qos", "m_or_topic" ] },
        { "strength": 12, "mutators": [ "m_invert_flags_retain", "m_xor_topic", "m_inc_pl_length" ] },
        { "strength": 13, "mutators": [ "m_inc_pl_length" ] },
        { "strength": 14, "mutators": [ ] }
      ] }
  } ]
}

The first rule is a quite simple one and contains two fields. The match field references a matching filter previously defined in Filters and a set of mutators previously defined in Fuzzing Mutators. You can think of the first rule as follows: Once the matching filter with the ID f_all_connect matches a message, apply all three given mutators with the IDs m_inc_clientid_len, m_xor_protoname_fixed and m_inc_protolevel to this message.

The second rule is a little more complex, though more flexible and powerful with regards to it’s capabilities to manipulate protocol messages. Once again, the match field references a matching filter. However, this time the rule does not contain a simple fixed list of mutators but rather a distribution of several lists. Let’s have a closer look at the distribution block. The model field defines the kind of the distribution which will be used to choose one of the items. Currently, multinomial distribution is the only one possible. (The concrete implementation uses the numpy.random.multinomial module.) The distribution can also be configured with a seed and nxp (Number of experiments). However, these fields are optional and can be omitted. The items list represents all the possibilities the distribution can choose from. Each set of mutators within a distribution is not necessarily equally weighted. That means, you can favor specific sets of mutators and disfavor others via the strength field. Thereby applies, the higher the strength, the higher the probability to be chosen. In concrete, in the example above the distribution has four items with an overall strength of $11+12+13+14=50$. That means, the probability to get the empty list of mutators (the last one, which in fact won’t manipulate any fields at all) is $p_4=\frac{14}{50}=0.28$ whereas the probability to get the first list is only $p_1=\frac{11}{50}=0.22$ and so on.

Warning

The total number of rules/filters should be kept as small as possible. In worst case scenarios each single filter must be checked for each message. Therefore, messages which do not match any filter (or the last one) need to be checked agains each single filter. The filter mechanism has a $O(n)$ time complexity. This might lead to performance issues on large sets of filters.

Note

The total number of items within a distribution has a $O(1)$ time complexity, which means, you can theoretically have as many items as you need without influencing the runtime performance.

Checking the configuration ¶

A fuzzing configuration can be become quite complex and confusing which might lead to errors at runtime. To ensure that your configuration is valid, the validate command comes handy. Once you have finished your configuration, ask the Monkey to validate your configuration:

./monkey validate {CONFIGURATION}

Where {CONFIGURATION} can be either a relative or absolute path to your configuration file.

Choose a Test Data Generator ¶

As testcase generator you can either use a simple client of your choice or use an according IoT-Testware conformance test suite.

Running a Fuzzing Session ¶

Once you have build and validated your configuration you are ready to start fuzzing. The Fuzzing Proxy can help you to start the Fuzzing Proxy:

./monkey fuzzing -l {LISTEN_PORT} -r {REMOTE_ADDRESS} -c {CONFIGURATION}

Where {LISTEN_PORT} is the port on which the fuzzing proxy will listen for incoming requests and forward to {REMOTE_ADDRESS}:{LISTEN_PORT} with considering the rules given in {CONFIGURATION}. The following sketch demonstrates the following fuzzing setup: 0.0.0.0:{LISTEN_PORT} <-> {REMOTE_ADDRESS}:{LISTEN_PORT}

If you need to further configure the ports and interfaces you can provide parameters as follows:

./monkey fuzzing -l {LOCAL_LISTEN_PORT} -r {REMOTE_ADDRESS} -p {REMOTE_LISTEN_PORT} -c {CONFIGURATION}

This will result in the following fuzzing setup: 0.0.0.0:{LOCAL_LISTEN_PORT} <-> {REMOTE_ADDRESS}:{REMOTE_LISTEN_PORT}

To stop the Fuzzing Proxy press Ctrl + C

Analyzing Fuzzing Logging ¶

Once you have finished a fuzzing session, you will find within the logs folder a newly created folder with a timestamped naming e.g. 20190822_13_38_24 (which is in fact the datetime when the Fuzzing Proxy was started). Inside of this folder you will find at least the two log files fuzzing_operations.log and proxy_traffic.log which can be used to analyze the fuzzing session. In general, the proxy_traffic.log contains all events happened, mainly incoming and outgoing messages and network events. On the other hand, the fuzzing_operations.log contains all events which were executed by the fuzzer during the reception and the forwarding of each single messages.

Let’s have a closer look at an exemplary log file of a MQTT session. First we will look into the proxy_traffic.log and go through the snipped line by line:

In line 1 we see a network event (TCP connection) coming from a client (127.0.0.1:58636) and on line 2 the client sent immediatelly a message over this connection. This message is a MQTT Connect Control Packet triggered by the client to request a (MQTT) connection to the server. If you like to look into the MQTT message, ask the Monkey to decode the bytestream for you:

./monkey decode -p mqtt -o '101c00044d5154540402003c00104d5154545f46585f436c69656e745f32'O

So far so good, everything went fine so far and the fuzzer didn’t intercept. In line 3 we can observe how the Fuzzing Proxy proxies the original network event (TCP connection) to the SUT (192.168.56.101:1883) and forwards the original, though manipulated, MQTT Connect Control Packet. Finally, the SUT reacts with an error handling routine by simply closing the network connection due to a protocol violation. So, what happend inside the Fuzzing Proxy and what was the reason for the protocol violation? First, we might take a closer look at the incoming and outgoing MQTT packets:

Well, didn’t change that much. Let’s consult the fuzzing_operations.log to figure out what happened in between. There we will find a line like the following one:

First of all, we can acknowledge this fuzzing operation took place in between the reception and forwarding of the MQTT packet by comparing the timestamps. Second, by following the [f_all_connect.3] hint, we can clearly traceback to applied rule, matching filter and set of mutators. And finally, with [NOT(DUP)=0->1; NOT(QOS)=0->1] we get a summary of the complete set of mutators applied to this message.

In the following code block we can see the corresponding rule and the marked item:

{
  "match": "f_all_connect",
  "distribution": {
    "model": "multinomial",
    "seed": 3456,
    "nxp": 10,
    "items": [
      { "strength": 1, "mutators": [ "m_xor_protoname_fixed", "m_inc_protolevel" ] },
      { "strength": 12, "mutators": [ "m_replace_username", "m_invert_username_flag" ] },
      { "strength": 15, "mutators": [ "m_inc_clientid_len", "m_replace_clientid" ] },
      { "strength": 7, "mutators": [ "m_invert_flags_dup", "m_invert_flags_qos" ] },
      { "strength": 15, "mutators": [ ] }
    ] }
}

By having this information, we can now even further precise the protocol violation.

However, it should be noted, that this example is not a perfect fuzzing example as the broker responded perfectly conformant according to the specification without crashing or exposing any weaknesses. But this simple example should only serve as an illustration of the capabilities of the fuzzer and demonstrate the workflow.

About Eclipse IoT-Testware¶

IoT-Testware Team¶

Who’s involved

Objective¶

As stated in [MVQ18] communication protocols for the IoT are currently in a immature state and offer different kinds of attack vectors. We believe… TODO!

Conformance Test Methodology and Framework¶

The IoT-Testware test suites will have a well-defined test suite structure (TSS) and a set of protocol implementation conformance statements (PICS) as well as protocol implementation extra information for testing (PIXIT). The work will follow the standardized approach as defined in ISO “Conformance Test Methodology and Framework” ISO 9646 and the best practices as described by ETSI White Paper No 3 “Achieving Technical Interoperability – the ETSI Approach”.

Implementation¶

The Eclipse IoT-Testware project provides standardized Abstract Test Suite (ATS) for popular IoT protocols. For the implementation of the ATS for CoAP and MQTT we apply ETSI Test Methodology which is well-proven in standardizing and testing of telecommunication systems.

Such an ATS contains of several parts which are required to implement the Conformance Test Methodology and Framework. But ATS, as the name says, are abstract, which means we need a system which executes the ATS. Just like Java code requires the JVM to be executed, an ATS requires in our case a TTCN-3 runtime. As our TTCN-3 runtime we have chosen Eclipse Titan which can compile and run our ATS.

The Executable Test Suite (ETS) is, as the name states, is a test suite under execution, just like running Java code.

Glossary¶

ASP: Abstract Service Primitive
ATS: Abstract Test Suite
CoAP: The Constrained Application Protocol (CoAP) is a specialized web transfer protocol for use with constrained nodes and constrained (e.g., low-power, lossy) networks. RFC 7252
ETS: Executable Test Suite
ETSI: The European Telecommunications Standards Institute is an independent, not-for-profit, standardization organization in the telecommunications industry (equipment makers and network operators) in Europe, headquartered in Sophia-Antipolis, France, with worldwide projection.
IoT: see Internet of Things
Internet of Things: The internet of things, or IoT, is a system of interrelated computing devices, mechanical and digital machines, objects, animals or people that are provided with unique identifiers and the ability to transfer data over a network without requiring human-to-human or human-to-computer interaction.
IUT: Implementation Under Test
MQTT: The MQ Telemetry Transport is a machine-to-machine (M2M) / Internet of Things connectivity protocol. It was designed as an extremely lightweight publish/subscribe messaging transport. It is useful for connections with remote locations where a small code footprint is required and/or network bandwidth is at a premium. mqtt.org
PCO: Point of Control and Observation
PDU: Protocol Data Unit
SUT: System Under Test
Test Case: A test case is…
Test Purpose: A test purpose is…
TC: see Test Case
TDL: Test Description Language (TDL) is a new language for the specification of test descriptions and the presentation of test execution results. tdl.etsi.org
Thing: The Thing in the context of IoT is an entity which is connected to the IoT and consumes or provides digital services.
TP: Test Purpose
TS: Test System
TSS: Test Suite Structure
TTCN-3: Testing and Test Control Notation version 3 is a standardized, modular testing language specifically designed for testing communication systems. ttcn-3.org
UT: Upper Tester

References¶

Sascha Hackel, Dorian Knobloch, and Axel Rennoch. Qualitätsanalyse mit IoT-Testware. url: https://gi.de/fileadmin/FG/TAV/42.TAV/42_GI-TAV_paper_1.pdf, 2017.

[KKR17]

Alexander Kaiser, Sascha Kretzschmann, and Axel Rennoch. Eclipse IoT-Testware: Die Open-Source-Testsuite für das MQTT-Protokoll. url: http://www.sigs.de/public/ots/2017/OTS_Testing_2017/Kaiser_OTS_Testing_2017.pdf, 2017.

[MVQ18]

Federico Maggi, Rainer Vosseler, and Davide Quarta. The Fragility of Industrial IoT’s Data Backbone. Trend Micro Research White Paper, pages 65, 2018.

[RH18]

Axel Rennoch and Sascha Hackel. Quality analysis with IoT-Testware. url: http://publica.fraunhofer.de/eprints/urn_nbn_de_0011-n-4971018.pdf, 2018.

[RHK18]

Axel Rennoch, Sascha Hackel, and Dorian Knobloch. Test Execution Infrastructure for IoT Quality Analysis. url: http://vvass2018.ist.tugraz.at/wp-content/uploads/2018/08/IoT-T_Testware_VVASS.pdf, 2018.

[RK19]

(1, 2) Axel Rennoch and Alexander Kaiser. Functional and non-functional testing for the IoT. url: http://publica.fraunhofer.de/eprints/urn_nbn_de_0011-n-5344321.pdf, 2019.

[SR17]

Schieferdecker, Ina and Axel Rennoch. IoT Testing and the Eclipse IoT Testware. url: https://paris.utdallas.edu/qrs17/docs/Keynote-Ina-Schieferdecker-slides.pdf, 2017.

[Sch18]

Ina Schieferdecker. IoT Testware - Modern Automated Test Solutions for IoT Components and Systems. 2018.

[SKRW17]

Ina Schieferdecker, Sascha Kretzschmann, Axel Rennoch, and Michael Wagner. IoT-testware - an eclipse project. url: https://ieeexplore.ieee.org/document/8009903, 2017.

[RennochAxel17]

Rennoch, Axel. Test automation for the iot: iot-testware. url: https://www.iotcamp.net/fileadmin/iot-barcamp/IoTcamp2017_FOKUS-Rennoch.pdf, 2017.

License¶

Eclipse Public License - v 1.0

THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE PUBLIC
LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE PROGRAM
CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT.

1. DEFINITIONS

"Contribution" means:

a) in the case of the initial Contributor, the initial code and documentation
   distributed under this Agreement, and
b) in the case of each subsequent Contributor:
    i) changes to the Program, and
   ii) additions to the Program;

   where such changes and/or additions to the Program originate from and are
   distributed by that particular Contributor. A Contribution 'originates'
   from a Contributor if it was added to the Program by such Contributor
   itself or anyone acting on such Contributor's behalf. Contributions do not
   include additions to the Program which: (i) are separate modules of
   software distributed in conjunction with the Program under their own
   license agreement, and (ii) are not derivative works of the Program.

"Contributor" means any person or entity that distributes the Program.

"Licensed Patents" mean patent claims licensable by a Contributor which are
necessarily infringed by the use or sale of its Contribution alone or when
combined with the Program.

"Program" means the Contributions distributed in accordance with this
Agreement.

"Recipient" means anyone who receives the Program under this Agreement,
including all Contributors.

2. GRANT OF RIGHTS
  a) Subject to the terms of this Agreement, each Contributor hereby grants
     Recipient a non-exclusive, worldwide, royalty-free copyright license to
     reproduce, prepare derivative works of, publicly display, publicly
     perform, distribute and sublicense the Contribution of such Contributor,
     if any, and such derivative works, in source code and object code form.
  b) Subject to the terms of this Agreement, each Contributor hereby grants
     Recipient a non-exclusive, worldwide, royalty-free patent license under
     Licensed Patents to make, use, sell, offer to sell, import and otherwise
     transfer the Contribution of such Contributor, if any, in source code and
     object code form. This patent license shall apply to the combination of
     the Contribution and the Program if, at the time the Contribution is
     added by the Contributor, such addition of the Contribution causes such
     combination to be covered by the Licensed Patents. The patent license
     shall not apply to any other combinations which include the Contribution.
     No hardware per se is licensed hereunder.
  c) Recipient understands that although each Contributor grants the licenses
     to its Contributions set forth herein, no assurances are provided by any
     Contributor that the Program does not infringe the patent or other
     intellectual property rights of any other entity. Each Contributor
     disclaims any liability to Recipient for claims brought by any other
     entity based on infringement of intellectual property rights or
     otherwise. As a condition to exercising the rights and licenses granted
     hereunder, each Recipient hereby assumes sole responsibility to secure
     any other intellectual property rights needed, if any. For example, if a
     third party patent license is required to allow Recipient to distribute
     the Program, it is Recipient's responsibility to acquire that license
     before distributing the Program.
  d) Each Contributor represents that to its knowledge it has sufficient
     copyright rights in its Contribution, if any, to grant the copyright
     license set forth in this Agreement.

3. REQUIREMENTS

A Contributor may choose to distribute the Program in object code form under
its own license agreement, provided that:

  a) it complies with the terms and conditions of this Agreement; and
  b) its license agreement:
      i) effectively disclaims on behalf of all Contributors all warranties
         and conditions, express and implied, including warranties or
         conditions of title and non-infringement, and implied warranties or
         conditions of merchantability and fitness for a particular purpose;
     ii) effectively excludes on behalf of all Contributors all liability for
         damages, including direct, indirect, special, incidental and
         consequential damages, such as lost profits;
    iii) states that any provisions which differ from this Agreement are
         offered by that Contributor alone and not by any other party; and
     iv) states that source code for the Program is available from such
         Contributor, and informs licensees how to obtain it in a reasonable
         manner on or through a medium customarily used for software exchange.

When the Program is made available in source code form:

  a) it must be made available under this Agreement; and
  b) a copy of this Agreement must be included with each copy of the Program.
     Contributors may not remove or alter any copyright notices contained
     within the Program.

Each Contributor must identify itself as the originator of its Contribution,
if
any, in a manner that reasonably allows subsequent Recipients to identify the
originator of the Contribution.

4. COMMERCIAL DISTRIBUTION

Commercial distributors of software may accept certain responsibilities with
respect to end users, business partners and the like. While this license is
intended to facilitate the commercial use of the Program, the Contributor who
includes the Program in a commercial product offering should do so in a manner
which does not create potential liability for other Contributors. Therefore,
if a Contributor includes the Program in a commercial product offering, such
Contributor ("Commercial Contributor") hereby agrees to defend and indemnify
every other Contributor ("Indemnified Contributor") against any losses,
damages and costs (collectively "Losses") arising from claims, lawsuits and
other legal actions brought by a third party against the Indemnified
Contributor to the extent caused by the acts or omissions of such Commercial
Contributor in connection with its distribution of the Program in a commercial
product offering. The obligations in this section do not apply to any claims
or Losses relating to any actual or alleged intellectual property
infringement. In order to qualify, an Indemnified Contributor must:
a) promptly notify the Commercial Contributor in writing of such claim, and
b) allow the Commercial Contributor to control, and cooperate with the
Commercial Contributor in, the defense and any related settlement
negotiations. The Indemnified Contributor may participate in any such claim at
its own expense.

For example, a Contributor might include the Program in a commercial product
offering, Product X. That Contributor is then a Commercial Contributor. If
that Commercial Contributor then makes performance claims, or offers
warranties related to Product X, those performance claims and warranties are
such Commercial Contributor's responsibility alone. Under this section, the
Commercial Contributor would have to defend claims against the other
Contributors related to those performance claims and warranties, and if a
court requires any other Contributor to pay any damages as a result, the
Commercial Contributor must pay those damages.

5. NO WARRANTY

EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS PROVIDED ON AN
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR
IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE,
NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each
Recipient is solely responsible for determining the appropriateness of using
and distributing the Program and assumes all risks associated with its
exercise of rights under this Agreement , including but not limited to the
risks and costs of program errors, compliance with applicable laws, damage to
or loss of data, programs or equipment, and unavailability or interruption of
operations.

6. DISCLAIMER OF LIABILITY

EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR ANY
CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION
LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE
EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY
OF SUCH DAMAGES.

7. GENERAL

If any provision of this Agreement is invalid or unenforceable under
applicable law, it shall not affect the validity or enforceability of the
remainder of the terms of this Agreement, and without further action by the
parties hereto, such provision shall be reformed to the minimum extent
necessary to make such provision valid and enforceable.

If Recipient institutes patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Program itself
(excluding combinations of the Program with other software or hardware)
infringes such Recipient's patent(s), then such Recipient's rights granted
under Section 2(b) shall terminate as of the date such litigation is filed.

All Recipient's rights under this Agreement shall terminate if it fails to
comply with any of the material terms or conditions of this Agreement and does
not cure such failure in a reasonable period of time after becoming aware of
such noncompliance. If all Recipient's rights under this Agreement terminate,
Recipient agrees to cease use and distribution of the Program as soon as
reasonably practicable. However, Recipient's obligations under this Agreement
and any licenses granted by Recipient relating to the Program shall continue
and survive.

Everyone is permitted to copy and distribute copies of this Agreement, but in
order to avoid inconsistency the Agreement is copyrighted and may only be
modified in the following manner. The Agreement Steward reserves the right to
publish new versions (including revisions) of this Agreement from time to
time. No one other than the Agreement Steward has the right to modify this
Agreement. The Eclipse Foundation is the initial Agreement Steward. The
Eclipse Foundation may assign the responsibility to serve as the Agreement
Steward to a suitable separate entity. Each new version of the Agreement will
be given a distinguishing version number. The Program (including
Contributions) may always be distributed subject to the version of the
Agreement under which it was received. In addition, after a new version of the
Agreement is published, Contributor may elect to distribute the Program
(including its Contributions) under the new version. Except as expressly
stated in Sections 2(a) and 2(b) above, Recipient receives no rights or
licenses to the intellectual property of any Contributor under this Agreement,
whether expressly, by implication, estoppel or otherwise. All rights in the
Program not expressly granted under this Agreement are reserved.

This Agreement is governed by the laws of the State of New York and the
intellectual property laws of the United States of America. No party to this
Agreement will bring a legal action under this Agreement more than one year
after the cause of action arose. Each party waives its rights to a jury trial in
any resulting litigation.

MQTT Specification¶

MQTT Version 3.1.1

OASIS Standard

29 October 2014

Specification URIs

This version:

http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.doc (Authoritative)

http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html

http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.pdf

Previous version:

http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/cos01/mqtt-v3.1.1-cos01.doc (Authoritative)

http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/cos01/mqtt-v3.1.1-cos01.html

http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/cos01/mqtt-v3.1.1-cos01.pdf

Latest version:

http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.doc (Authoritative)

http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html

http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.pdf

Technical Committee:

OASIS Message Queuing Telemetry Transport (MQTT) TC

Chairs:

Raphael J Cohn (raphael.cohn@stormmq.com), Individual

Richard J Coppen (coppen@uk.ibm.com), IBM

Editors:

Andrew Banks (Andrew_Banks@uk.ibm.com), IBM

Rahul Gupta (rahul.gupta@us.ibm.com), IBM

Related work:

This specification is related to:

MQTT and the NIST Cybersecurity Framework Version 1.0. Edited by Geoff Brown and Louis-Philippe Lamoureux. Latest version: http://docs.oasis-open.org/mqtt/mqtt-nist-cybersecurity/v1.0/mqtt-nist-cybersecurity-v1.0.html.

Abstract:

MQTT is a Client Server publish/subscribe messaging transport protocol. It is light weight, open, simple, and designed so as to be easy to implement. These characteristics make it ideal for use in many situations, including constrained environments such as for communication in Machine to Machine (M2M) and Internet of Things (IoT) contexts where a small code footprint is required and/or network bandwidth is at a premium.

The protocol runs over TCP/IP, or over other network protocols that provide ordered, lossless, bi-directional connections. Its features include:

- Use of the publish/subscribe message pattern which provides one-to-many message distribution and decoupling of applications.

- A messaging transport that is agnostic to the content of the payload.

- Three qualities of service for message delivery:

- "At most once", where messages are delivered according to the best efforts of the operating environment. Message loss can occur. This level could be used, for example, with ambient sensor data where it does not matter if an individual reading is lost as the next one will be published soon after.

- "At least once", where messages are assured to arrive but duplicates can occur.

- "Exactly once", where message are assured to arrive exactly once. This level could be used, for example, with billing systems where duplicate or lost messages could lead to incorrect charges being applied.

- A small transport overhead and protocol exchanges minimized to reduce network traffic.

- A mechanism to notify interested parties when an abnormal disconnection occurs.

Status:

This document was last revised or approved by the membership of OASIS on the above date. The level of approval is also listed above. Check the "Latest version" location noted above for possible later revisions of this document. Any other numbered Versions and other technical work produced by the Technical Committee (TC) are listed at https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=mqtt#technical.

TC members should send comments on this specification to the TC's email list. Others should send comments to the TC's public comment list, after subscribing to it by following the instructions at the "Send A Comment" button on the TC's web page at https://www.oasis-open.org/committees/mqtt/.

For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the Technical Committee web page (https://www.oasis-open.org/committees/mqtt/ipr.php).

Citation format:

When referencing this specification the following citation format should be used:

[mqtt-v3.1.1]

MQTT Version 3.1.1. Edited by Andrew Banks and Rahul Gupta. 29 October 2014. OASIS Standard. http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html. Latest version: http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html.

Notices

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.

OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.

OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.

The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see https://www.oasis-open.org/policies-guidelines/trademark for above guidance.

Table of Contents

1 Introduction. 9

1.1 Organization of MQTT. 9

1.2 Terminology. 9

1.3 Normative references. 10

1.4 Non normative references. 11

1.5 Data representations. 13

1.5.1 Bits. 13

1.5.2 Integer data values. 13

1.5.3 UTF-8 encoded strings. 13

1.6 Editing conventions. 15

2 MQTT Control Packet format 16

2.1 Structure of an MQTT Control Packet 16

2.2 Fixed header 16

2.2.1 MQTT Control Packet type. 16

2.2.2 Flags. 17

2.2.3 Remaining Length. 18

2.3 Variable header 19

2.3.1 Packet Identifier 20

2.4 Payload. 21

3 MQTT Control Packets. 23

3.1 CONNECT - Client requests a connection to a Server 23

3.1.1 Fixed header 23

3.1.2 Variable header 23

3.1.3 Payload. 29

3.1.4 Response. 30

3.2 CONNACK - Acknowledge connection request 31

3.2.1 Fixed header 31

3.2.2 Variable header 31

3.2.3 Payload. 33

3.3 PUBLISH - Publish message. 33

3.3.1 Fixed header 33

3.3.2 Variable header 35

3.3.3 Payload. 36

3.3.4 Response. 36

3.3.5 Actions. 36

3.4 PUBACK - Publish acknowledgement 37

3.4.1 Fixed header 37

3.4.2 Variable header 37

3.4.3 Payload. 37

3.4.4 Actions. 37

3.5 PUBREC - Publish received (QoS 2 publish received, part 1) 37

3.5.1 Fixed header 38

3.5.2 Variable header 38

3.5.3 Payload. 38

3.5.4 Actions. 38

3.6 PUBREL - Publish release (QoS 2 publish received, part 2) 38

3.6.1 Fixed header 38

3.6.2 Variable header 39

3.6.3 Payload. 39

3.6.4 Actions. 39

3.7 PUBCOMP - Publish complete (QoS 2 publish received, part 3) 39

3.7.1 Fixed header 39

3.7.2 Variable header 40

3.7.3 Payload. 40

3.7.4 Actions. 40

3.8 SUBSCRIBE - Subscribe to topics. 40

3.8.1 Fixed header 40

3.8.2 Variable header 40

3.8.3 Payload. 41

3.8.4 Response. 42

3.9 SUBACK - Subscribe acknowledgement 43

3.9.1 Fixed header 44

3.9.2 Variable header 44

3.9.3 Payload. 44

3.10 UNSUBSCRIBE - Unsubscribe from topics. 45

3.10.1 Fixed header 45

3.10.2 Variable header 45

3.10.3 Payload. 46

3.10.4 Response. 46

3.11 UNSUBACK - Unsubscribe acknowledgement 47

3.11.1 Fixed header 47

3.11.2 Variable header 47

3.11.3 Payload. 48

3.12 PINGREQ - PING request 48

3.12.1 Fixed header 48

3.12.2 Variable header 48

3.12.3 Payload. 48

3.12.4 Response. 48

3.13 PINGRESP - PING response. 48

3.13.1 Fixed header 48

3.13.2 Variable header 49

3.13.3 Payload. 49

3.14 DISCONNECT - Disconnect notification. 49

3.14.1 Fixed header 49

3.14.2 Variable header 49

3.14.3 Payload. 49

3.14.4 Response. 49

4 Operational behavior 51

4.1 Storing state. 51

4.1.1 Non normative example. 51

4.2 Network Connections. 52

4.3 Quality of Service levels and protocol flows. 52

4.3.1 QoS 0: At most once delivery. 52

4.3.2 QoS 1: At least once delivery. 53

4.3.3 QoS 2: Exactly once delivery. 54

4.4 Message delivery retry. 55

4.5 Message receipt 56

4.6 Message ordering. 56

4.7 Topic Names and Topic Filters. 57

4.7.1 Topic wildcards. 57

4.7.2 Topics beginning with $. 58

4.7.3 Topic semantic and usage. 58

4.8 Handling errors. 59

5 Security. 60

5.1 Introduction. 60

5.2 MQTT solutions: security and certification. 60

5.3 Lightweight cryptography and constrained devices. 61

5.4 Implementation notes. 61

5.4.1 Authentication of Clients by the Server 61

5.4.2 Authorization of Clients by the Server 61

5.4.3 Authentication of the Server by the Client 61

5.4.4 Integrity of Application Messages and Control Packets. 62

5.4.5 Privacy of Application Messages and Control Packets. 62

5.4.6 Non-repudiation of message transmission. 62

5.4.7 Detecting compromise of Clients and Servers. 62

5.4.8 Detecting abnormal behaviors. 63

5.4.9 Other security considerations. 63

5.4.10 Use of SOCKS. 64

5.4.11 Security profiles. 64

6 Using WebSocket as a network transport 65

6.1 IANA Considerations. 65

7 Conformance. 66

7.1 Conformance Targets. 66

7.1.1 MQTT Server 66

7.1.2 MQTT Client 66

Appendix A. Acknowledgements (non normative) 68

Appendix B. Mandatory normative statements (non normative) 70

Appendix C. Revision history (non normative) 80

Table of Figures and Tables

Figure 1.1 Structure of UTF-8 encoded strings. 13

Figure 1.2 UTF-8 encoded string non normative example

Figure 2.1 Structure of an MQTT Control Packet 16

Figure 2.2 Fixed header format 16

Table 2.1 Control packet types. 16

Table 2.2 Flag Bits. 17

Table 2.4 Size of Remaining Length field. 18

Figure 2.3 Packet Identifier bytes. 20

Table 2.5 Control Packets that contain a Packet Identifier 20

Table 2.6 Control Packets that contain a Payload. 21

Figure 3.1 CONNECT Packet fixed header 23

Figure 3.2 Protocol Name bytes. 23

Figure 3.3 Protocol Level byte. 24

Figure 3.4 Connect Flag bits. 24

Figure 3.5 Keep Alive bytes. 27

Figure 3.6 Variable header non normative example. 28

Figure 3.7 Password bytes. 30

Figure 3.8 CONNACK Packet fixed header 31

Figure 3.9 CONNACK Packet variable header 31

Table 3.1 Connect Return code values. 32

Figure 3.10 PUBLISH Packet fixed header 33

Table 3.2 QoS definitions. 34

Table 3.3 Publish Packet non normative example. 35

Figure 3.11 Publish Packet variable header non normative example. 35

Table 3.4 Expected Publish Packet response. 36

Figure 3.12 PUBACK Packet fixed header 37

Figure 3.13 PUBACK Packet variable header 37

Figure 3.14 PUBREC Packet fixed header 38

Figure 3.15 PUBREC Packet variable header 38

Figure 3.16 PUBREL Packet fixed header 38

Figure 3.17 PUBREL Packet variable header 39

Figure 3.18 PUBCOMP Packet fixed header 39

Figure 3.19 PUBCOMP Packet variable header 40

Figure 3.20 SUBSCRIBE Packet fixed header 40

Figure 3.21 Variable header with a Packet Identifier of 10, Non normative example. 41

Figure 3.22 SUBSCRIBE Packet payload format 41

Table 3.5 Payload non normative example. 42

Figure 3.23 Payload byte format non normative example. 42

Figure 3.24 SUBACK Packet fixed header 44

Figure 3.25 SUBACK Packet variable header 44

Figure 3.26 SUBACK Packet payload format 44

Table 3.6 Payload non normative example. 45

Figure 3.27 Payload byte format non normative example. 45

Figure 3.28 UNSUBSCRIBE Packet Fixed header 45

Figure 3.29 UNSUBSCRIBE Packet variable header 45

Table3.7 - Payload non normative example. 46

Figure 3.30 - Payload byte format non normative example. 46

Figure 3.31 UNSUBACK Packet fixed header 47

Figure 3.32 UNSUBACK Packet variable header 47

Figure 3.33 PINGREQ Packet fixed header 48

Figure 3.34 PINGRESP Packet fixed header 48

Figure 3.35 DISCONNECT Packet fixed header 49

Figure 4.1 QoS 0 protocol flow diagram, non normative example. 52

Figure 4.2 QoS 1 protocol flow diagram, non normative example. 53

Figure 4.3 QoS 2 protocol flow diagram, non normative example. 54

Figure 6.1 - IANA WebSocket Identifier 65

1 Introduction

1.1 Organization of MQTT

This specification is split into seven chapters:

� Chapter 1 - Introduction

� Chapter 2 - MQTT Control Packet format

� Chapter 3 - MQTT Control Packets

� Chapter 4 - Operational behavior

� Chapter 5 - Security

� Chapter 6 - Using WebSocket as a network transport

� Chapter 7 - Conformance Targets

1.2 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 IETF RFC 2119 [RFC2119].

Network Connection:

A construct provided by the underlying transport protocol that is being used by MQTT.

� It connects the Client to the Server.

� It provides the means to send an ordered, lossless, stream of bytes in both directions.

For examples see Section 4.2.

Application Message:
The data carried by the MQTT protocol across the network for the application. When Application Messages are transported by MQTT they have an associated Quality of Service and a Topic Name.

Client:

A program or device that uses MQTT. A Client always establishes the Network Connection to the Server. It can

� Publish Application Messages that other Clients might be interested in.

� Subscribe to request Application Messages that it is interested in receiving.

� Unsubscribe to remove a request for Application Messages.

� Disconnect from the Server.

Server:
A program or device that acts as an intermediary between Clients which publish Application Messages and Clients which have made Subscriptions. A Server

� Accepts Network Connections from Clients.

� Accepts Application Messages published by Clients.

� Processes Subscribe and Unsubscribe requests from Clients.

� Forwards Application Messages that match Client Subscriptions.

Subscription:
A Subscription comprises a Topic Filter and a maximum QoS. A Subscription is associated with a single Session. A Session can contain more than one Subscription. Each Subscription within a session has a different Topic Filter.

Topic Name:
The label attached to an Application Message which is matched against the Subscriptions known to the Server. The Server sends a copy of the Application Message to each Client that has a matching Subscription.

Topic Filter:
An expression contained in a Subscription, to indicate an interest in one or more topics. A Topic Filter can include wildcard characters.

Session:
A stateful interaction between a Client and a Server. Some Sessions last only as long as the Network Connection, others can span multiple consecutive Network Connections between a Client and a Server.

MQTT Control Packet:
A packet of information that is sent across the Network Connection. The MQTT specification defines fourteen different types of Control Packet, one of which (the PUBLISH packet) is used to convey Application Messages.

1.3 Normative references

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
http://www.ietf.org/rfc/rfc2119.txt

[RFC3629]

Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003
http://www.ietf.org/rfc/rfc3629.txt

[RFC5246]

Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, August 2008.

http://www.ietf.org/rfc/rfc5246.txt

[RFC6455]

Fette, I. and A. Melnikov, "The WebSocket Protocol", RFC 6455, December 2011.

http://www.ietf.org/rfc/rfc6455.txt

[Unicode]

The Unicode Consortium. The Unicode Standard.

http://www.unicode.org/versions/latest/

1.4 Non normative references

[RFC793]

Postel, J. Transmission Control Protocol. STD 7, IETF RFC 793, September 1981.

http://www.ietf.org/rfc/rfc793.txt

[AES]

Advanced Encryption Standard (AES) (FIPS PUB 197).

http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf

[DES]

Data Encryption Standard (DES).

http://csrc.nist.gov/publications/fips/fips46-3/fips46-3.pdf

[FIPS1402]

Security Requirements for Cryptographic Modules (FIPS PUB 140-2)

http://csrc.nist.gov/publications/fips/fips140-2/fips1402.pdf

[IEEE 802.1AR]

IEEE Standard for Local and metropolitan area networks - Secure Device Identity

http://standards.ieee.org/findstds/standard/802.1AR-2009.html

[ISO29192]

ISO/IEC 29192-1:2012 Information technology -- Security techniques -- Lightweight cryptography -- Part 1: General

http://www.iso.org/iso/home/store/catalogue_tc/catalogue_detail.htm?csnumber=56425

[MQTT NIST]

MQTT supplemental publication, MQTT and the NIST Framework for Improving Critical Infrastructure Cybersecurity

http://docs.oasis-open.org/mqtt/mqtt-nist-cybersecurity/v1.0/mqtt-nist-cybersecurity-v1.0.html

[MQTTV31]

MQTT V3.1 Protocol Specification.

http://public.dhe.ibm.com/software/dw/webservices/ws-mqtt/mqtt-v3r1.html

[NISTCSF]

Improving Critical Infrastructure Cybersecurity Executive Order 13636

http://www.nist.gov/itl/upload/preliminary-cybersecurity-framework.pdf

[NIST7628]

NISTIR 7628 Guidelines for Smart Grid Cyber Security

http://www.nist.gov/smartgrid/upload/nistir-7628_total.pdf

[NSAB]

NSA Suite B Cryptography

http://www.nsa.gov/ia/programs/suiteb_cryptography/

[PCIDSS]

PCI-DSS Payment Card Industry Data Security Standard

https://www.pcisecuritystandards.org/security_standards/

[RFC1928]

Leech, M., Ganis, M., Lee, Y., Kuris, R., Koblas, D., and L. Jones, "SOCKS Protocol Version 5", RFC 1928, March 1996.

http://www.ietf.org/rfc/rfc1928.txt

[RFC4511]

Sermersheim, J., Ed., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006.

http://www.ietf.org/rfc/rfc4511.txt

[RFC5077]

Salowey, J., Zhou, H., Eronen, P., and H. Tschofenig, "Transport Layer Security (TLS) Session Resumption without Server-Side State", RFC 5077, January 2008.

http://www.ietf.org/rfc/rfc5077.txt

[RFC5280]

Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, R., and W. Polk, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 5280, May 2008.

http://www.ietf.org/rfc/rfc5280.txt

[RFC6066]

Eastlake 3rd, D., "Transport Layer Security (TLS) Extensions: Extension Definitions", RFC 6066, January 2011.

http://www.ietf.org/rfc/rfc6066.txt

[RFC6749]

Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, October 2012.

http://www.ietf.org/rfc/rfc6749.txt

[RFC6960]

Santesson, S., Myers, M., Ankney, R., Malpani, A., Galperin, S., and C. Adams, "X.509 Internet Public Key Infrastructure Online Certificate Status Protocol - OCSP", RFC 6960, June 2013.

http://www.ietf.org/rfc/rfc6960.txt

[SARBANES]

Sarbanes-Oxley Act of 2002.

http://www.gpo.gov/fdsys/pkg/PLAW-107publ204/html/PLAW-107publ204.htm

[USEUSAFEHARB]

U.S.-EU Safe Harbor

http://export.gov/safeharbor/eu/eg_main_018365.asp

1.5 Data representations

1.5.1 Bits

Bits in a byte are labeled 7 through 0. Bit number 7 is the most significant bit, the least significant bit is assigned bit number 0.

1.5.2 Integer data values

Integer data values are 16 bits in big-endian order: the high order byte precedes the lower order byte. This means that a 16-bit word is presented on the network as Most Significant Byte (MSB), followed by Least Significant Byte (LSB).

1.5.3 UTF-8 encoded strings

Text fields in the Control Packets described later are encoded as UTF-8 strings. UTF-8 [RFC3629] is an efficient encoding of Unicode [Unicode] characters that optimizes the encoding of ASCII characters in support of text-based communications.

Each of these strings is prefixed with a two byte length field that gives the number of bytes in a UTF-8 encoded string itself, as illustrated in Figure 1.1 Structure of UTF-8 encoded strings below. Consequently there is a limit on the size of a string that can be passed in one of these UTF-8 encoded string components; you cannot use a string that would encode to more than 65535 bytes.

Unless stated otherwise all UTF-8 encoded strings can have any length in the range 0 to 65535 bytes.

Figure 1.1 Structure of UTF-8 encoded strings

Bit	7	6	5	4	3	2	1	0
byte 1	String length MSB
byte 2	String length LSB
byte 3 �.	UTF-8 Encoded Character Data, if length > 0.

The character data in a UTF-8 encoded string MUST be well-formed UTF-8 as defined by the Unicode specification [Unicode] and restated in RFC 3629 [RFC3629]. In particular this data MUST NOT include encodings of code points between U+D800 and U+DFFF. If a Server or Client receives a Control Packet containing ill-formed UTF-8 it MUST close the Network Connection [MQTT-1.5.3-1].

A UTF-8 encoded string MUST NOT include an encoding of the null character U+0000. If a receiver (Server or Client) receives a Control Packet containing U+0000 it MUST close the Network Connection [MQTT-1.5.3-2].

The data SHOULD NOT include encodings of the Unicode [Unicode] code points listed below. If a receiver (Server or Client) receives a Control Packet containing any of them it MAY close the Network Connection:

U+0001..U+001F control characters
U+007F..U+009F control characters
Code points defined in the Unicode specification [Unicode] to be non-characters (for example U+0FFFF)

A UTF-8 encoded sequence 0xEF 0xBB 0xBF is always to be interpreted to mean U+FEFF ("ZERO WIDTH NO-BREAK SPACE") wherever it appears in a string and MUST NOT be skipped over or stripped off by a packet receiver [MQTT-1.5.3-3].

1.5.3.1 Non normative example

For example, the string A𪛔 which is LATIN CAPITAL Letter A followed by the code point U+2A6D4 (which represents a CJK IDEOGRAPH EXTENSION B character) is encoded as follows:

Figure 1.2 UTF-8 encoded string non normative example

Bit	7	6	5	4	3	2	1	0
byte 1	String Length MSB (0x00)
	0	0	0	0	0	0	0	0
byte 2	String Length LSB (0x05)
	0	0	0	0	0	1	0	1
byte 3	�A� (0x41)
	0	1	0	0	0	0	0	1
byte 4	(0xF0)
	1	1	1	1	0	0	0	0
byte 5	(0xAA)
	1	0	1	0	1	0	1	0
byte 6	(0x9B)
	1	0	0	1	1	0	1	1
byte 7	(0x94)
	1	0	0	1	0	1	0	0

1.6 Editing conventions

Text highlighted in Yellow within this specification identifies conformance statements. Each conformance statement has been assigned a reference in the format [MQTT-x.x.x-y].

2 MQTT Control Packet format

2.1 Structure of an MQTT Control Packet

The MQTT protocol works by exchanging a series of MQTT Control Packets in a defined way. This section describes the format of these packets.

An MQTT Control Packet consists of up to three parts, always in the following order as illustrated in Figure 2.1 - Structure of an MQTT Control Packet.

Figure 2.1 � Structure of an MQTT Control Packet

Fixed header, present in all MQTT Control Packets

Variable header, present in some MQTT Control Packets

Payload, present in some MQTT Control Packets

2.2 Fixed header

Each MQTT Control Packet contains a fixed header. Figure 2.2 - Fixed header format illustrates the fixed header format.

Figure 2.2 - Fixed header format

Bit	7	6	5	4	3	2	1	0
byte 1	MQTT Control Packet type				Flags specific to each MQTT Control Packet type
byte 2�	Remaining Length

2.2.1 MQTT Control Packet type

Position: byte 1, bits 7-4.

Represented as a 4-bit unsigned value, the values are listed in Table 2.1 - Control packet types.

Table 2.1 - Control packet types

Name	Value		Direction of flow	Description
Reserved	0	Forbidden		Reserved
CONNECT	1	Client to Server		Client request to connect to Server
CONNACK	2	Server to Client		Connect acknowledgment
PUBLISH	3	Client to Server or Server to Client		Publish message
PUBACK	4	Client to Server or Server to Client		Publish acknowledgment
PUBREC	5	Client to Server or Server to Client		Publish received (assured delivery part 1)
PUBREL	6	Client to Server or Server to Client		Publish release (assured delivery part 2)
PUBCOMP	7	Client to Server or Server to Client		Publish complete (assured delivery part 3)
SUBSCRIBE	8	Client to Server		Client subscribe request
SUBACK	9	Server to Client		Subscribe acknowledgment
UNSUBSCRIBE	10	Client to Server		Unsubscribe request
UNSUBACK	11	Server to Client		Unsubscribe acknowledgment
PINGREQ	12	Client to Server		PING request
PINGRESP	13	Server to Client		PING response
DISCONNECT	14	Client to Server		Client is disconnecting
Reserved	15	Forbidden		Reserved

2.2.2 Flags

The remaining bits [3-0] of byte 1 in the fixed header contain flags specific to each MQTT Control Packet type as listed in the Table 2.2 - Flag Bits below. Where a flag bit is marked as �Reserved� in Table 2.2 - Flag Bits, it is reserved for future use and MUST be set to the value listed in that table [MQTT-2.2.2-1]. If invalid flags are received, the receiver MUST close the Network Connection [MQTT-2.2.2-2]. See Section 4.8 for details about handling errors.

Table 2.2 - Flag Bits

Control Packet	Fixed header flags	Bit 3	Bit 2	Bit 1	Bit 0
CONNECT	Reserved	0	0	0	0
CONNACK	Reserved	0	0	0	0
PUBLISH	Used in MQTT 3.1.1	DUP¹	QoS²	QoS²	RETAIN³
PUBACK	Reserved	0	0	0	0
PUBREC	Reserved	0	0	0	0
PUBREL	Reserved	0	0	1	0
PUBCOMP	Reserved	0	0	0	0
SUBSCRIBE	Reserved	0	0	1	0
SUBACK	Reserved	0	0	0	0
UNSUBSCRIBE	Reserved	0	0	1	0
UNSUBACK	Reserved	0	0	0	0
PINGREQ	Reserved	0	0	0	0
PINGRESP	Reserved	0	0	0	0
DISCONNECT	Reserved	0	0	0	0

DUP¹ = Duplicate delivery of a PUBLISH Control Packet

QoS² = PUBLISH Quality of Service

RETAIN³ = PUBLISH Retain flag

See Section 3.3.1 for a description of the DUP, QoS, and RETAIN flags in the PUBLISH Control Packet.

2.2.3 Remaining Length

Position: starts at byte 2.

The Remaining Length is the number of bytes remaining within the current packet, including data in the variable header and the payload. The Remaining Length does not include the bytes used to encode the Remaining Length.

The Remaining Length is encoded using a variable length encoding scheme which uses a single byte for values up to 127. Larger values are handled as follows. The least significant seven bits of each byte encode the data, and the most significant bit is used to indicate that there are following bytes in the representation. Thus each byte encodes 128 values and a "continuation bit". The maximum number of bytes in the Remaining Length field is four.

Non normative comment

For example, the number 64 decimal is encoded as a single byte, decimal value 64, hexadecimal 0x40. The number 321 decimal (= 65 + 2*128) is encoded as two bytes, least significant first. The first byte is 65+128 = 193. Note that the top bit is set to indicate at least one following byte. The second byte is 2.

Non normative comment

This allows applications to send Control Packets of size up to 268,435,455 (256 MB). The representation of this number on the wire is: 0xFF, 0xFF, 0xFF, 0x7F.

Table 2.4 shows the Remaining Length values represented by increasing numbers of bytes.

Table 2.4 Size of Remaining Length field

Digits	From	To
1	0 (0x00)	127 (0x7F)
2	128 (0x80, 0x01)	16 383 (0xFF, 0x7F)
3	16 384 (0x80, 0x80, 0x01)	2 097 151 (0xFF, 0xFF, 0x7F)
4	2 097 152 (0x80, 0x80, 0x80, 0x01)	268 435 455 (0xFF, 0xFF, 0xFF, 0x7F)

Non normative comment

The algorithm for encoding a non negative integer (X) into the variable length encoding scheme is as follows:

do

encodedByte = X MOD 128

X = X DIV 128

// if there are more data to encode, set the top bit of this byte

if ( X > 0 )

encodedByte = encodedByte OR 128

endif

'output' encodedByte

while ( X > 0 )

Where MOD is the modulo operator (% in C), DIV is integer division (/ in C), and OR is bit-wise or (| in C).

Non normative comment

The algorithm for decoding the Remaining Length field is as follows:

multiplier = 1

value = 0

do

encodedByte = 'next byte from stream'

value += (encodedByte AND 127) * multiplier

multiplier *= 128

if (multiplier > 128*128*128)

throw Error(Malformed Remaining Length)

while ((encodedByte AND 128) != 0)

where AND is the bit-wise and operator (& in C).

When this algorithm terminates, value contains the Remaining Length value.

2.3 Variable header

Some types of MQTT Control Packets contain a variable header component. It resides between the fixed header and the payload. The content of the variable header varies depending on the Packet type. The Packet Identifier field of variable header is common in several packet types.

2.3.1 Packet Identifier

Figure 2.3 - Packet Identifier bytes

Bit	7	6	5	4	3	2	1	0
byte 1	Packet Identifier MSB
byte 2	Packet Identifier LSB

The variable header component of many of the Control Packet types includes a 2 byte Packet Identifier field. These Control Packets are PUBLISH (where QoS > 0), PUBACK, PUBREC, PUBREL, PUBCOMP, SUBSCRIBE, SUBACK, UNSUBSCRIBE, UNSUBACK.

SUBSCRIBE, UNSUBSCRIBE, and PUBLISH (in cases where QoS > 0) Control Packets MUST contain a non-zero 16-bit Packet Identifier [MQTT-2.3.1-1]. Each time a Client sends a new packet of one of these types it MUST assign it a currently unused Packet Identifier [MQTT-2.3.1-2]. If a Client re-sends a particular Control Packet, then it MUST use the same Packet Identifier in subsequent re-sends of that packet. The Packet Identifier becomes available for reuse after the Client has processed the corresponding acknowledgement packet. In the case of a QoS 1 PUBLISH this is the corresponding PUBACK; in the case of QoS 2 it is PUBCOMP. For SUBSCRIBE or UNSUBSCRIBE it is the corresponding SUBACK or UNSUBACK [MQTT-2.3.1-3]. The same conditions apply to a Server when it sends a PUBLISH with QoS > 0 [MQTT-2.3.1-4].

A PUBLISH Packet MUST NOT contain a Packet Identifier if its QoS value is set to 0 [MQTT-2.3.1-5].

A PUBACK, PUBREC or PUBREL Packet MUST contain the same Packet Identifier as the PUBLISH Packet that was originally sent [MQTT-2.3.1-6]. Similarly SUBACK and UNSUBACK MUST contain the Packet Identifier that was used in the corresponding SUBSCRIBE and UNSUBSCRIBE Packet respectively [MQTT-2.3.1-7].

Control Packets that require a Packet Identifier are listed in Table 2.5 - Control Packets that contain a Packet Identifier.

Table 2.5 - Control Packets that contain a Packet Identifier

Control Packet	Packet Identifier field
CONNECT	NO
CONNACK	NO
PUBLISH	YES (If QoS > 0)
PUBACK	YES
PUBREC	YES
PUBREL	YES
PUBCOMP	YES
SUBSCRIBE	YES
SUBACK	YES
UNSUBSCRIBE	YES
UNSUBACK	YES
PINGREQ	NO
PINGRESP	NO
DISCONNECT	NO

The Client and Server assign Packet Identifiers independently of each other. As a result, Client Server pairs can participate in concurrent message exchanges using the same Packet Identifiers.

Non normative comment

It is possible for a Client to send a PUBLISH Packet with Packet Identifier 0x1234 and then receive a different PUBLISH with Packet Identifier 0x1234 from its Server before it receives a PUBACK for the PUBLISH that it sent.

Client Server

PUBLISH Packet Identifier=0x1234---�

�--PUBLISH Packet Identifier=0x1234

PUBACK Packet Identifier=0x1234---�

�--PUBACK Packet Identifier=0x1234

2.4 Payload

Some MQTT Control Packets contain a payload as the final part of the packet, as described in Chapter 3. In the case of the PUBLISH packet this is the Application Message. Table 2.6 - Control Packets that contain a Payload lists the Control Packets that require a Payload.

Table 2.6 - Control Packets that contain a Payload

Control Packet	Payload
CONNECT	Required
CONNACK	None
PUBLISH	Optional
PUBACK	None
PUBREC	None
PUBREL	None
PUBCOMP	None
SUBSCRIBE	Required
SUBACK	Required
UNSUBSCRIBE	Required
UNSUBACK	None
PINGREQ	None
PINGRESP	None
DISCONNECT	None

3 MQTT Control Packets

3.1 CONNECT � Client requests a connection to a Server

After a Network Connection is established by a Client to a Server, the first Packet sent from the Client to the Server MUST be a CONNECT Packet [MQTT-3.1.0-1].

A Client can only send the CONNECT Packet once over a Network Connection. The Server MUST process a second CONNECT Packet sent from a Client as a protocol violation and disconnect the Client [MQTT-3.1.0-2]. See section 4.8 for information about handling errors.

The payload contains one or more encoded fields. They specify a unique Client identifier for the Client, a Will topic, Will Message, User Name and Password. All but the Client identifier are optional and their presence is determined based on flags in the variable header.

3.1.1 Fixed header

Figure 3.1 � CONNECT Packet fixed header

Bit	7	6	5	4	3	2	1	0
byte 1	MQTT Control Packet type (1)				Reserved
	0	0	0	1	0	0	0	0
byte 2�	Remaining Length

Remaining Length field

Remaining Length is the length of the variable header (10 bytes) plus the length of the Payload. It is encoded in the manner described in section 2.2.3.

3.1.2 Variable header

The variable header for the CONNECT Packet consists of four fields in the following order: Protocol Name, Protocol Level, Connect Flags, and Keep Alive.

3.1.2.1 Protocol Name

Figure 3.2 - Protocol Name bytes

	Description	7	6	5	4	3	2	1	0
Protocol Name
byte 1	Length MSB (0)	0	0	0	0	0	0	0	0
byte 2	Length LSB (4)	0	0	0	0	0	1	0	0
byte 3	�M�	0	1	0	0	1	1	0	1
byte 4	�Q�	0	1	0	1	0	0	0	1
byte 5	�T�	0	1	0	1	0	1	0	0
byte 6	�T�	0	1	0	1	0	1	0	0

The Protocol Name is a UTF-8 encoded string that represents the protocol name �MQTT�, capitalized as shown. The string, its offset and length will not be changed by future versions of the MQTT specification.

If the protocol name is incorrect the Server MAY disconnect the Client, or it MAY continue processing the CONNECT packet in accordance with some other specification. In the latter case, the Server MUST NOT continue to process the CONNECT packet in line with this specification [MQTT-3.1.2-1].

Non normative comment

Packet inspectors, such as firewalls, could use the Protocol Name to identify MQTT traffic.

3.1.2.2 Protocol Level

Figure 3.3 - Protocol Level byte

	Description	7	6	5	4	3	2	1	0
Protocol Level
byte 7	Level(4)	0	0	0	0	0	1	0	0

The 8 bit unsigned value that represents the revision level of the protocol used by the Client. The value of the Protocol Level field for the version 3.1.1 of the protocol is 4 (0x04). The Server MUST respond to the CONNECT Packet with a CONNACK return code 0x01 (unacceptable protocol level) and then disconnect the Client if the Protocol Level is not supported by the Server [MQTT-3.1.2-2].

3.1.2.3 Connect Flags

The Connect Flags byte contains a number of parameters specifying the behavior of the MQTT connection. It also indicates the presence or absence of fields in the payload.

Figure 3.4 - Connect Flag bits

Bit	7	6	5	4	3	2	1	0
	User Name Flag	Password Flag	Will Retain	Will QoS		Will Flag	Clean Session	Reserved
byte 8	X	X	X	X	X	X	X	0

The Server MUST validate that the reserved flag in the CONNECT Control Packet is set to zero and disconnect the Client if it is not zero [MQTT-3.1.2-3].

3.1.2.4 Clean Session

Position: bit 1 of the Connect Flags byte.

This bit specifies the handling of the Session state.

The Client and Server can store Session state to enable reliable messaging to continue across a sequence of Network Connections. This bit is used to control the lifetime of the Session state.

If CleanSession is set to 0, the Server MUST resume communications with the Client based on state from the current Session (as identified by the Client identifier). If there is no Session associated with the Client identifier the Server MUST create a new Session. The Client and Server MUST store the Session after the Client and Server are disconnected [MQTT-3.1.2-4]. After the disconnection of a Session that had CleanSession set to 0, the Server MUST store further QoS 1 and QoS 2 messages that match any subscriptions that the client had at the time of disconnection as part of the Session state [MQTT-3.1.2-5]. It MAY also store QoS 0 messages that meet the same criteria.

If CleanSession is set to 1, the Client and Server MUST discard any previous Session and start a new one. This Session lasts as long as the Network Connection. State data associated with this Session MUST NOT be reused in any subsequent Session [MQTT-3.1.2-6].

The Session state in the Client consists of:

� QoS 1 and QoS 2 messages which have been sent to the Server, but have not been completely acknowledged.

� QoS 2 messages which have been received from the Server, but have not been completely acknowledged.

The Session state in the Server consists of:

� The existence of a Session, even if the rest of the Session state is empty.

� The Client�s subscriptions.

� QoS 1 and QoS 2 messages which have been sent to the Client, but have not been completely acknowledged.

� QoS 1 and QoS 2 messages pending transmission to the Client.

� QoS 2 messages which have been received from the Client, but have not been completely acknowledged.

� Optionally, QoS 0 messages pending transmission to the Client.

Retained messages do not form part of the Session state in the Server, they MUST NOT be deleted when the Session ends [MQTT-3.1.2.7].

See Section 4.1 for details and limitations of stored state.

When CleanSession is set to 1 the Client and Server need not process the deletion of state atomically.

Non normative comment

To ensure consistent state in the event of a failure, the Client should repeat its attempts to connect with CleanSession set to 1, until it connects successfully.

Non normative comment

Typically, a Client will always connect using CleanSession set to 0 or CleanSession set to 1 and not swap between the two values. The choice will depend on the application. A Client using CleanSession set to 1 will not receive old Application Messages and has to subscribe afresh to any topics that it is interested in each time it connects. A Client using CleanSession set to 0 will receive all QoS 1 or QoS 2 messages that were published while it was disconnected. Hence, to ensure that you do not lose messages while disconnected, use QoS 1 or QoS 2 with CleanSession set to 0.

Non normative comment

When a Client connects with CleanSession set to 0, it is requesting that the Server maintain its MQTT session state after it disconnects. Clients should only connect with CleanSession set to 0, if they intend to reconnect to the Server at some later point in time. When a Client has determined that it has no further use for the session it should do a final connect with CleanSession set to 1 and then disconnect.

3.1.2.5 Will Flag

Position: bit 2 of the Connect Flags.

If the Will Flag is set to 1 this indicates that, if the Connect request is accepted, a Will Message MUST be stored on the Server and associated with the Network Connection. The Will Message MUST be published when the Network Connection is subsequently closed unless the Will Message has been deleted by the Server on receipt of a DISCONNECT Packet [MQTT-3.1.2-8].

Situations in which the Will Message is published include, but are not limited to:

An I/O error or network failure detected by the Server.
The Client fails to communicate within the Keep Alive time.
The Client closes the Network Connection without first sending a DISCONNECT Packet.
The Server closes the Network Connection because of a protocol error.

If the Will Flag is set to 1, the Will QoS and Will Retain fields in the Connect Flags will be used by the Server, and the Will Topic and Will Message fields MUST be present in the payload [MQTT-3.1.2-9].

The Will Message MUST be removed from the stored Session state in the Server once it has been published or the Server has received a DISCONNECT packet from the Client [MQTT-3.1.2-10].

If the Will Flag is set to 0 the Will QoS and Will Retain fields in the Connect Flags MUST be set to zero and the Will Topic and Will Message fields MUST NOT be present in the payload [MQTT-3.1.2-11].

If the Will Flag is set to 0, a Will Message MUST NOT be published when this Network Connection ends [MQTT-3.1.2-12].

The Server SHOULD publish Will Messages promptly. In the case of a Server shutdown or failure the server MAY defer publication of Will Messages until a subsequent restart. If this happens there might be a delay between the time the server experienced failure and a Will Message being published.

3.1.2.6 Will QoS

Position: bits 4 and 3 of the Connect Flags.

These two bits specify the QoS level to be used when publishing the Will Message.

If the Will Flag is set to 0, then the Will QoS MUST be set to 0 (0x00) [MQTT-3.1.2-13].

If the Will Flag is set to 1, the value of Will QoS can be 0 (0x00), 1 (0x01), or 2 (0x02). It MUST NOT be 3 (0x03) [MQTT-3.1.2-14].

3.1.2.7 Will Retain

Position: bit 5 of the Connect Flags.

This bit specifies if the Will Message is to be Retained when it is published.

If the Will Flag is set to 0, then the Will Retain Flag MUST be set to 0 [MQTT-3.1.2-15].

If the Will Flag is set to 1:

If Will Retain is set to 0, the Server MUST publish the Will Message as a non-retained message [MQTT-3.1.2-16].
If Will Retain is set to 1, the Server MUST publish the Will Message as a retained message [MQTT-3.1.2-17].

3.1.2.8 User Name Flag

Position: bit 7 of the Connect Flags.

If the User Name Flag is set to 0, a user name MUST NOT be present in the payload [MQTT-3.1.2-18].

If the User Name Flag is set to 1, a user name MUST be present in the payload [MQTT-3.1.2-19].

3.1.2.9 Password Flag

Position: bit 6 of the Connect Flags byte.

If the Password Flag is set to 0, a password MUST NOT be present in the payload [MQTT-3.1.2-20].

If the Password Flag is set to 1, a password MUST be present in the payload [MQTT-3.1.2-21].

If the User Name Flag is set to 0, the Password Flag MUST be set to 0 [MQTT-3.1.2-22].

3.1.2.10 Keep Alive

Figure 3.5 Keep Alive bytes

Bit	7	6	5	4	3	2	1	0
byte 9	Keep Alive MSB
byte 10	Keep Alive LSB

The Keep Alive is a time interval measured in seconds. Expressed as a 16-bit word, it is the maximum time interval that is permitted to elapse between the point at which the Client finishes transmitting one Control Packet and the point it starts sending the next. It is the responsibility of the Client to ensure that the interval between Control Packets being sent does not exceed the Keep Alive value. In the absence of sending any other Control Packets, the Client MUST send a PINGREQ Packet [MQTT-3.1.2-23].

The Client can send PINGREQ at any time, irrespective of the Keep Alive value, and use the PINGRESP to determine that the network and the Server are working.

If the Keep Alive value is non-zero and the Server does not receive a Control Packet from the Client within one and a half times the Keep Alive time period, it MUST disconnect the Network Connection to the Client as if the network had failed [MQTT-3.1.2-24].

If a Client does not receive a PINGRESP Packet within a reasonable amount of time after it has sent a PINGREQ, it SHOULD close the Network Connection to the Server.

A Keep Alive value of zero (0) has the effect of turning off the keep alive mechanism. This means that, in this case, the Server is not required to disconnect the Client on the grounds of inactivity.
Note that a Server is permitted to disconnect a Client that it determines to be inactive or non-responsive at any time, regardless of the Keep Alive value provided by that Client.

Non normative comment

The actual value of the Keep Alive is application specific; typically this is a few minutes. The maximum value is 18 hours 12 minutes and 15 seconds.

3.1.2.11 Variable header non normative example

Figure 3.6 - Variable header non normative example

	Description	7	6	5	4	3	2	1	0
Protocol Name
byte 1	Length MSB (0)	0	0	0	0	0	0	0	0
byte 2	Length LSB (4)	0	0	0	0	0	1	0	0
byte 3	�M�	0	1	0	0	1	1	0	1
byte 4	�Q�	0	1	0	1	0	0	0	1
byte 5	�T�	0	1	0	1	0	1	0	0
byte 6	�T�	0	1	0	1	0	1	0	0
Protocol Level
	Description	7	6	5	4	3	2	1	0
byte 7	Level (4)	0	0	0	0	0	1	0	0
Connect Flags
byte 8	User Name Flag (1) Password Flag (1) Will Retain (0) Will QoS (01) Will Flag (1) Clean Session (1) Reserved (0)	1	1	0	0	1	1	1	0
Keep Alive
byte 9	Keep Alive MSB (0)	0	0	0	0	0	0	0	0
byte 10	Keep Alive LSB (10)	0	0	0	0	1	0	1	0

3.1.3 Payload

The payload of the CONNECT Packet contains one or more length-prefixed fields, whose presence is determined by the flags in the variable header. These fields, if present, MUST appear in the order Client Identifier, Will Topic, Will Message, User Name, Password [MQTT-3.1.3-1].

3.1.3.1 Client Identifier

The Client Identifier (ClientId) identifies the Client to the Server. Each Client connecting to the Server has a unique ClientId. The ClientId MUST be used by Clients and by Servers to identify state that they hold relating to this MQTT Session between the Client and the Server [MQTT-3.1.3-2].

The Client Identifier (ClientId) MUST be present and MUST be the first field in the CONNECT packet payload [MQTT-3.1.3-3].

The ClientId MUST be a UTF-8 encoded string as defined in Section 1.5.3 [MQTT-3.1.3-4].

The Server MUST allow ClientIds which are between 1 and 23 UTF-8 encoded bytes in length, and that contain only the characters

"0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ" [MQTT-3.1.3-5].

The Server MAY allow ClientId�s that contain more than 23 encoded bytes. The Server MAY allow ClientId�s that contain characters not included in the list given above.

A Server MAY allow a Client to supply a ClientId that has a length of zero bytes, however if it does so the Server MUST treat this as a special case and assign a unique ClientId to that Client. It MUST then process the CONNECT packet as if the Client had provided that unique ClientId [MQTT-3.1.3-6].

If the Client supplies a zero-byte ClientId, the Client MUST also set CleanSession to 1 [MQTT-3.1.3-7].

If the Client supplies a zero-byte ClientId with CleanSession set to 0, the Server MUST respond to the CONNECT Packet with a CONNACK return code 0x02 (Identifier rejected) and then close the Network Connection [MQTT-3.1.3-8].

If the Server rejects the ClientId it MUST respond to the CONNECT Packet with a CONNACK return code 0x02 (Identifier rejected) and then close the Network Connection [MQTT-3.1.3-9].

Non normative comment

A Client implementation could provide a convenience method to generate a random ClientId. Use of such a method should be actively discouraged when the CleanSession is set to 0.

3.1.3.2 Will Topic

If the Will Flag is set to 1, the Will Topic is the next field in the payload. The Will Topic MUST be a UTF-8 encoded string as defined in Section 1.5.3 [MQTT-3.1.3-10].

3.1.3.3 Will Message

If the Will Flag is set to 1 the Will Message is the next field in the payload. The Will Message defines the Application Message that is to be published to the Will Topic as described in Section 3.1.2.5. This field consists of a two byte length followed by the payload for the Will Message expressed as a sequence of zero or more bytes. The length gives the number of bytes in the data that follows and does not include the 2 bytes taken up by the length itself.

When the Will Message is published to the Will Topic its payload consists only of the data portion of this field, not the first two length bytes.

3.1.3.4 User Name

If the User Name Flag is set to 1, this is the next field in the payload. The User Name MUST be a UTF-8 encoded string as defined in Section 1.5.3 [MQTT-3.1.3-11]. It can be used by the Server for authentication and authorization.

3.1.3.5 Password

If the Password Flag is set to 1, this is the next field in the payload. The Password field contains 0 to 65535 bytes of binary data prefixed with a two byte length field which indicates the number of bytes used by the binary data (it does not include the two bytes taken up by the length field itself).

Figure 3.7 - Password bytes

Bit	7	6	5	4	3	2	1	0
byte 1	Data length MSB
byte 2	Data length LSB
byte 3 �.	Data, if length > 0.

3.1.4 Response

Note that a Server MAY support multiple protocols (including earlier versions of this protocol) on the same TCP port or other network endpoint. If the Server determines that the protocol is MQTT 3.1.1 then it validates the connection attempt as follows.

1. If the Server does not receive a CONNECT Packet within a reasonable amount of time after the Network Connection is established, the Server SHOULD close the connection.

2. The Server MUST validate that the CONNECT Packet conforms to section 3.1 and close the Network Connection without sending a CONNACK if it does not conform [MQTT-3.1.4-1].

3. The Server MAY check that the contents of the CONNECT Packet meet any further restrictions and MAY perform authentication and authorization checks. If any of these checks fail, it SHOULD send an appropriate CONNACK response with a non-zero return code as described in section 3.2 and it MUST close the Network Connection.

If validation is successful the Server performs the following steps.

1. If the ClientId represents a Client already connected to the Server then the Server MUST disconnect the existing Client [MQTT-3.1.4-2].

2. The Server MUST perform the processing of CleanSession that is described in section 3.1.2.4 [MQTT-3.1.4-3].

3. The Server MUST acknowledge the CONNECT Packet with a CONNACK Packet containing a zero return code [MQTT-3.1.4-4].

4. Start message delivery and keep alive monitoring.

Clients are allowed to send further Control Packets immediately after sending a CONNECT Packet; Clients need not wait for a CONNACK Packet to arrive from the Server. If the Server rejects the CONNECT, it MUST NOT process any data sent by the Client after the CONNECT Packet [MQTT-3.1.4-5].

Non normative comment
Clients typically wait for a CONNACK Packet, However, if the Client exploits its freedom to send Control Packets before it receives a CONNACK, it might simplify the Client implementation as it does not have to police the connected state. The Client accepts that any data that it sends before it receives a CONNACK packet from the Server will not be processed if the Server rejects the connection.

3.2 CONNACK � Acknowledge connection request

The CONNACK Packet is the packet sent by the Server in response to a CONNECT Packet received from a Client. The first packet sent from the Server to the Client MUST be a CONNACK Packet [MQTT-3.2.0-1].

If the Client does not receive a CONNACK Packet from the Server within a reasonable amount of time, the Client SHOULD close the Network Connection. A "reasonable" amount of time depends on the type of application and the communications infrastructure.

3.2.1 Fixed header

The fixed header format is illustrated in Figure 3.8 � CONNACK Packet fixed header.

Figure 3.8 � CONNACK Packet fixed header

Bit	7	6	5	4	3	2	1	0
byte 1	MQTT Control Packet Type (2)				Reserved
	0	0	1	0	0	0	0	0
byte 2	Remaining Length (2)
	0	0	0	0	0	0	1	0

Remaining Length field

This is the length of the variable header. For the CONNACK Packet this has the value 2.

3.2.2 Variable header

The variable header format is illustrated in Figure 3.9 � CONNACK Packet variable header.

Figure 3.9 � CONNACK Packet variable header

	Description	7	6	5	4	3	2	1	0
Connect Acknowledge Flags		Reserved							SP¹
byte 1		0	0	0	0	0	0	0	X
Connect Return code
byte 2		X	X	X	X	X	X	X	X

3.2.2.1 Connect Acknowledge Flags

Byte 1 is the "Connect Acknowledge Flags". Bits 7-1 are reserved and MUST be set to 0.

Bit 0 (SP¹) is the Session Present Flag.

3.2.2.2 Session Present

Position: bit 0 of the Connect Acknowledge Flags.

If the Server accepts a connection with CleanSession set to 1, the Server MUST set Session Present to 0 in the CONNACK packet in addition to setting a zero return code in the CONNACK packet [MQTT-3.2.2-1].

If the Server accepts a connection with CleanSession set to 0, the value set in Session Present depends on whether the Server already has stored Session state for the supplied client ID. If the Server has stored Session state, it MUST set Session Present to 1 in the CONNACK packet [MQTT-3.2.2-2]. If the Server does not have stored Session state, it MUST set Session Present to 0 in the CONNACK packet. This is in addition to setting a zero return code in the CONNACK packet [MQTT-3.2.2-3].

The Session Present flag enables a Client to establish whether the Client and Server have a consistent view about whether there is already stored Session state.

Once the initial setup of a Session is complete, a Client with stored Session state will expect the Server to maintain its stored Session state. In the event that the value of Session Present received by the Client from the Server is not as expected, the Client can choose whether to proceed with the Session or to disconnect. The Client can discard the Session state on both Client and Server by disconnecting, connecting with Clean Session set to 1 and then disconnecting again.

If a server sends a CONNACK packet containing a non-zero return code it MUST set Session Present to 0 [MQTT-3.2.2-4].

3.2.2.3 Connect Return code

Byte 2 in the Variable header.

The values for the one byte unsigned Connect Return code field are listed in Table 3.1 � Connect Return code values. If a well formed CONNECT Packet is received by the Server, but the Server is unable to process it for some reason, then the Server SHOULD attempt to send a CONNACK packet containing the appropriate non-zero Connect return code from this table. If a server sends a CONNACK packet containing a non-zero return code it MUST then close the Network Connection [MQTT-3.2.2-5].

Table 3.1 � Connect Return code values

Value	Return Code Response	Description
0	0x00 Connection Accepted	Connection accepted
1	0x01 Connection Refused, unacceptable protocol version	The Server does not support the level of the MQTT protocol requested by the Client
2	0x02 Connection Refused, identifier rejected	The Client identifier is correct UTF-8 but not allowed by the Server
3	0x03 Connection Refused, Server unavailable	The Network Connection has been made but the MQTT service is unavailable
4	0x04 Connection Refused, bad user name or password	The data in the user name or password is malformed
5	0x05 Connection Refused, not authorized	The Client is not authorized to connect
6-255		Reserved for future use

If none of the return codes listed in Table 3.1 � Connect Return code values are deemed applicable, then the Server MUST close the Network Connection without sending a CONNACK [MQTT-3.2.2-6].

3.2.3 Payload

The CONNACK Packet has no payload.

3.3 PUBLISH � Publish message

A PUBLISH Control Packet is sent from a Client to a Server or from Server to a Client to transport an Application Message.

3.3.1 Fixed header

Figure 3.10 � PUBLISH Packet fixed header illustrates the fixed header format:

Figure 3.10 � PUBLISH Packet fixed header

Bit	7	6	5	4	3	2	1	0
byte 1	MQTT Control Packet type (3)				DUP flag	QoS level		RETAIN
	0	0	1	1	X	X	X	X
byte 2	Remaining Length

3.3.1.1 DUP

Position: byte 1, bit 3.

If the DUP flag is set to 0, it indicates that this is the first occasion that the Client or Server has attempted to send this MQTT PUBLISH Packet. If the DUP flag is set to 1, it indicates that this might be re-delivery of an earlier attempt to send the Packet.

The DUP flag MUST be set to 1 by the Client or Server when it attempts to re-deliver a PUBLISH Packet [MQTT-3.3.1.-1]. The DUP flag MUST be set to 0 for all QoS 0 messages [MQTT-3.3.1-2].

The value of the DUP flag from an incoming PUBLISH packet is not propagated when the PUBLISH Packet is sent to subscribers by the Server. The DUP flag in the outgoing PUBLISH packet is set independently to the incoming PUBLISH packet, its value MUST be determined solely by whether the outgoing PUBLISH packet is a retransmission [MQTT-3.3.1-3].

Non normative comment

The recipient of a Control Packet that contains the DUP flag set to 1 cannot assume that it has seen an earlier copy of this packet.

Non normative comment

It is important to note that the DUP flag refers to the Control Packet itself and not to the Application Message that it contains. When using QoS 1, it is possible for a Client to receive a PUBLISH Packet with DUP flag set to 0 that contains a repetition of an Application Message that it received earlier, but with a different Packet Identifier. Section 2.3.1 provides more information about Packet Identifiers.

3.3.1.2 QoS

Position: byte 1, bits 2-1.

This field indicates the level of assurance for delivery of an Application Message. The QoS levels are listed in the Table 3.2 - QoS definitions, below.

Table 3.2 - QoS definitions

QoS value	Bit 2	bit 1	Description
0	0	0	At most once delivery
1	0	1	At least once delivery
2	1	0	Exactly once delivery
-	1	1	Reserved � must not be used

A PUBLISH Packet MUST NOT have both QoS bits set to 1. If a Server or Client receives a PUBLISH Packet which has both QoS bits set to 1 it MUST close the Network Connection [MQTT-3.3.1-4].

3.3.1.3 RETAIN

Position: byte 1, bit 0.

If the RETAIN flag is set to 1, in a PUBLISH Packet sent by a Client to a Server, the Server MUST store the Application Message and its QoS, so that it can be delivered to future subscribers whose subscriptions match its topic name [MQTT-3.3.1-5]. When a new subscription is established, the last retained message, if any, on each matching topic name MUST be sent to the subscriber [MQTT-3.3.1-6]. If the Server receives a QoS 0 message with the RETAIN flag set to 1 it MUST discard any message previously retained for that topic. It SHOULD store the new QoS 0 message as the new retained message for that topic, but MAY choose to discard it at any time - if this happens there will be no retained message for that topic [MQTT-3.3.1-7]. See Section 4.1 for more information on storing state.

When sending a PUBLISH Packet to a Client the Server MUST set the RETAIN flag to 1 if a message is sent as a result of a new subscription being made by a Client [MQTT-3.3.1-8]. It MUST set the RETAIN flag to 0 when a PUBLISH Packet is sent to a Client because it matches an established subscription regardless of how the flag was set in the message it received [MQTT-3.3.1-9].

A PUBLISH Packet with a RETAIN flag set to 1 and a payload containing zero bytes will be processed as normal by the Server and sent to Clients with a subscription matching the topic name. Additionally any existing retained message with the same topic name MUST be removed and any future subscribers for the topic will not receive a retained message [MQTT-3.3.1-10]. �As normal� means that the RETAIN flag is not set in the message received by existing Clients. A zero byte retained message MUST NOT be stored as a retained message on the Server [MQTT-3.3.1-11].

If the RETAIN flag is 0, in a PUBLISH Packet sent by a Client to a Server, the Server MUST NOT store the message and MUST NOT remove or replace any existing retained message [MQTT-3.3.1-12].

Non normative comment

Retained messages are useful where publishers send state messages on an irregular basis. A new subscriber will receive the most recent state.

Remaining Length field

This is the length of variable header plus the length of the payload.

3.3.2 Variable header

The variable header contains the following fields in the order: Topic Name, Packet Identifier.

3.3.2.1 Topic Name

The Topic Name identifies the information channel to which payload data is published.

The Topic Name MUST be present as the first field in the PUBLISH Packet Variable header. It MUST be a UTF-8 encoded string [MQTT-3.3.2-1] as defined in section 1.5.3.

The Topic Name in the PUBLISH Packet MUST NOT contain wildcard characters [MQTT-3.3.2-2].

The Topic Name in a PUBLISH Packet sent by a Server to a subscribing Client MUST match the Subscription�s Topic Filter according to the matching process defined in Section 4.7 [MQTT-3.3.2-3]. However, since the Server is permitted to override the Topic Name, it might not be the same as the Topic Name in the original PUBLISH Packet.

3.3.2.2 Packet Identifier

The Packet Identifier field is only present in PUBLISH Packets where the QoS level is 1 or 2. Section 2.3.1 provides more information about Packet Identifiers.

3.3.2.3 Variable header non normative example

Figure 3.11 - Publish Packet variable header non normative example illustrates an example variable header for the PUBLISH Packet briefly described in Table 3.3 - Publish Packet non normative example.

Table 3.3 - Publish Packet non normative example

Field	Value
Topic Name	a/b
Packet Identifier	10

Figure 3.11 - Publish Packet variable header non normative example

	Description	7	6	5	4	3	2	1	0
Topic Name
byte 1	Length MSB (0)	0	0	0	0	0	0	0	0
byte 2	Length LSB (3)	0	0	0	0	0	0	1	1
byte 3	�a� (0x61)	0	1	1	0	0	0	0	1
byte 4	�/� (0x2F)	0	0	1	0	1	1	1	1
byte 5	�b� (0x62)	0	1	1	0	0	0	1	0
Packet Identifier
byte 6	Packet Identifier MSB (0)	0	0	0	0	0	0	0	0
byte 7	Packet Identifier LSB (10)	0	0	0	0	1	0	1	0

3.3.3 Payload

The Payload contains the Application Message that is being published. The content and format of the data is application specific. The length of the payload can be calculated by subtracting the length of the variable header from the Remaining Length field that is in the Fixed Header. It is valid for a PUBLISH Packet to contain a zero length payload.

3.3.4 Response

The receiver of a PUBLISH Packet MUST respond according to Table 3.4 - Expected Publish Packet response as determined by the QoS in the PUBLISH Packet [MQTT-3.3.4-1].

Table 3.4 - Expected Publish Packet response

QoS Level	Expected Response
QoS 0	None
QoS 1	PUBACK Packet
QoS 2	PUBREC Packet

3.3.5 Actions

The Client uses a PUBLISH Packet to send an Application Message to the Server, for distribution to Clients with matching subscriptions.

The Server uses a PUBLISH Packet to send an Application Message to each Client which has a matching subscription.

When Clients make subscriptions with Topic Filters that include wildcards, it is possible for a Client�s subscriptions to overlap so that a published message might match multiple filters. In this case the Server MUST deliver the message to the Client respecting the maximum QoS of all the matching subscriptions [MQTT-3.3.5-1]. In addition, the Server MAY deliver further copies of the message, one for each additional matching subscription and respecting the subscription�s QoS in each case.

The action of the recipient when it receives a PUBLISH Packet depends on the QoS level as described in Section 4.3.

If a Server implementation does not authorize a PUBLISH to be performed by a Client; it has no way of informing that Client. It MUST either make a positive acknowledgement, according to the normal QoS rules, or close the Network Connection [MQTT-3.3.5-2].

3.4 PUBACK � Publish acknowledgement

A PUBACK Packet is the response to a PUBLISH Packet with QoS level 1.

3.4.1 Fixed header

Figure 3.12 - PUBACK Packet fixed header

Bit	7	6	5	4	3	2	1	0
byte 1	MQTT Control Packet type (4)				Reserved
	0	1	0	0	0	0	0	0
byte 2	Remaining Length (2)
	0	0	0	0	0	0	1	0

Remaining Length field

This is the length of the variable header. For the PUBACK Packet this has the value 2.

3.4.2 Variable header

This contains the Packet Identifier from the PUBLISH Packet that is being acknowledged.

Figure 3.13 � PUBACK Packet variable header

Bit	7	6	5	4	3	2	1	0
byte 1	Packet Identifier MSB
byte 2	Packet Identifier LSB

3.4.3 Payload

The PUBACK Packet has no payload.

3.4.4 Actions

This is fully described in Section 4.3.2.

3.5 PUBREC � Publish received (QoS 2 publish received, part 1)

A PUBREC Packet is the response to a PUBLISH Packet with QoS 2. It is the second packet of the QoS 2 protocol exchange.

3.5.1 Fixed header

Figure 3.14 � PUBREC Packet fixed header

Bit	7	6	5	4	3	2	1	0
byte 1	MQTT Control Packet type (5)				Reserved
	0	1	0	1	0	0	0	0
byte 2	Remaining Length (2)
	0	0	0	0	0	0	1	0

Remaining Length field

This is the length of the variable header. For the PUBREC Packet this has the value 2.

3.5.2 Variable header

The variable header contains the Packet Identifier from the PUBLISH Packet that is being acknowledged.

Figure 3.15 � PUBREC Packet variable header

Bit	7	6	5	4	3	2	1	0
byte 1	Packet Identifier MSB
byte 2	Packet Identifier LSB

3.5.3 Payload

The PUBREC Packet has no payload.

3.5.4 Actions

This is fully described in Section 4.3.3.

3.6 PUBREL � Publish release (QoS 2 publish received, part 2)

A PUBREL Packet is the response to a PUBREC Packet. It is the third packet of the QoS 2 protocol exchange.

3.6.1 Fixed header

Figure 3.16 � PUBREL Packet fixed header

Bit	7	6	5	4	3	2	1	0
byte 1	MQTT Control Packet type (6)				Reserved
	0	1	1	0	0	0	1	0
byte 2	Remaining Length (2)
	0	0	0	0	0	0	1	0

Bits 3,2,1 and 0 of the fixed header in the PUBREL Control Packet are reserved and MUST be set to 0,0,1 and 0 respectively. The Server MUST treat any other value as malformed and close the Network Connection [MQTT-3.6.1-1].

Remaining Length field

This is the length of the variable header. For the PUBREL Packet this has the value 2.

3.6.2 Variable header

The variable header contains the same Packet Identifier as the PUBREC Packet that is being acknowledged.

Figure 3.17 � PUBREL Packet variable header

Bit	7	6	5	4	3	2	1	0
byte 1	Packet Identifier MSB
byte 2	Packet Identifier LSB

3.6.3 Payload

The PUBREL Packet has no payload.

3.6.4 Actions

This is fully described in Section 4.3.3.

3.7 PUBCOMP � Publish complete (QoS 2 publish received, part 3)

The PUBCOMP Packet is the response to a PUBREL Packet. It is the fourth and final packet of the QoS 2 protocol exchange.

3.7.1 Fixed header

Figure 3.18 � PUBCOMP Packet fixed header

Bit	7	6	5	4	3	2	1	0
byte 1	MQTT Control Packet type (7)				Reserved
	0	1	1	1	0	0	0	0
byte 2	Remaining Length (2)
	0	0	0	0	0	0	1	0

Remaining Length field

This is the length of the variable header. For the PUBCOMP Packet this has the value 2.

3.7.2 Variable header

The variable header contains the same Packet Identifier as the PUBREL Packet that is being acknowledged.

Figure 3.19 � PUBCOMP Packet variable header

Bit	7	6	5	4	3	2	1	0
byte 1	Packet Identifier MSB
byte 2	Packet Identifier LSB

3.7.3 Payload

The PUBCOMP Packet has no payload.

3.7.4 Actions

This is fully described in Section 4.3.3.

3.8 SUBSCRIBE - Subscribe to topics

The SUBSCRIBE Packet is sent from the Client to the Server to create one or more Subscriptions. Each Subscription registers a Client�s interest in one or more Topics. The Server sends PUBLISH Packets to the Client in order to forward Application Messages that were published to Topics that match these Subscriptions. The SUBSCRIBE Packet also specifies (for each Subscription) the maximum QoS with which the Server can send Application Messages to the Client.

3.8.1 Fixed header

Figure 3.20 � SUBSCRIBE Packet fixed header

Bit	7	6	5	4	3	2	1	0
byte 1	MQTT Control Packet type (8)				Reserved
	1	0	0	0	0	0	1	0
byte 2	Remaining Length

Bits 3,2,1 and 0 of the fixed header of the SUBSCRIBE Control Packet are reserved and MUST be set to 0,0,1 and 0 respectively. The Server MUST treat any other value as malformed and close the Network Connection [MQTT-3.8.1-1].

Remaining Length field

This is the length of variable header (2 bytes) plus the length of the payload.

3.8.2 Variable header

The variable header contains a Packet Identifier. Section 2.3.1 provides more information about Packet Identifiers.

3.8.2.1 Variable header non normative example

Figure 3.21 shows a variable header with Packet Identifier set to 10.

Figure 3.21 - Variable header with a Packet Identifier of 10, Non normative example

	Description	7	6	5	4	3	2	1	0
Packet Identifier
byte 1	Packet Identifier MSB (0)	0	0	0	0	0	0	0	0
byte 2	Packet Identifier LSB (10)	0	0	0	0	1	0	1	0

3.8.3 Payload

The payload of a SUBSCRIBE Packet contains a list of Topic Filters indicating the Topics to which the Client wants to subscribe. The Topic Filters in a SUBSCRIBE packet payload MUST be UTF-8 encoded strings as defined in Section 1.5.3 [MQTT-3.8.3-1]. A Server SHOULD support Topic filters that contain the wildcard characters defined in Section 4.7.1. If it chooses not to support topic filters that contain wildcard characters it MUST reject any Subscription request whose filter contains them [MQTT-3.8.3-2]. Each filter is followed by a byte called the Requested QoS. This gives the maximum QoS level at which the Server can send Application Messages to the Client.

The payload of a SUBSCRIBE packet MUST contain at least one Topic Filter / QoS pair. A SUBSCRIBE packet with no payload is a protocol violation [MQTT-3.8.3-3]. See section 4.8 for information about handling errors.

The requested maximum QoS field is encoded in the byte following each UTF-8 encoded topic name, and these Topic Filter / QoS pairs are packed contiguously.

Figure 3.22 � SUBSCRIBE Packet payload format

Description	7	6	5	4	3	2	1	0
Topic Filter
byte 1	Length MSB
byte 2	Length LSB
bytes 3..N	Topic Filter
Requested QoS
	Reserved						QoS
byte N+1	0	0	0	0	0	0	X	X

The upper 6 bits of the Requested QoS byte are not used in the current version of the protocol. They are reserved for future use. The Server MUST treat a SUBSCRIBE packet as malformed and close the Network Connection if any of Reserved bits in the payload are non-zero, or QoS is not 0,1 or 2 [MQTT-3-8.3-4].

3.8.3.1 Payload non normative example

Figure 3.23 - Payload byte format non normative example shows the payload for the SUBSCRIBE Packet briefly described in Table 3.5 - Payload non normative example.

Table 3.5 - Payload non normative example

Topic Name	�a/b�
Requested QoS	0x01
Topic Name	�c/d�
Requested QoS	0x02

Figure 3.23 - Payload byte format non normative example

	Description	7	6	5	4	3	2	1	0
Topic Filter
byte 1	Length MSB (0)	0	0	0	0	0	0	0	0
byte 2	Length LSB (3)	0	0	0	0	0	0	1	1
byte 3	�a� (0x61)	0	1	1	0	0	0	0	1
byte 4	�/� (0x2F)	0	0	1	0	1	1	1	1
byte 5	�b� (0x62)	0	1	1	0	0	0	1	0
Requested QoS
byte 6	Requested QoS(1)	0	0	0	0	0	0	0	1
Topic Filter
byte 7	Length MSB (0)	0	0	0	0	0	0	0	0
byte 8	Length LSB (3)	0	0	0	0	0	0	1	1
byte 9	�c� (0x63)	0	1	1	0	0	0	1	1
byte 10	�/� (0x2F)	0	0	1	0	1	1	1	1
byte 11	�d� (0x64)	0	1	1	0	0	1	0	0
Requested QoS
byte 12	Requested QoS(2)	0	0	0	0	0	0	1	0

3.8.4 Response

When the Server receives a SUBSCRIBE Packet from a Client, the Server MUST respond with a SUBACK Packet [MQTT-3.8.4-1]. The SUBACK Packet MUST have the same Packet Identifier as the SUBSCRIBE Packet that it is acknowledging [MQTT-3.8.4-2].

The Server is permitted to start sending PUBLISH packets matching the Subscription before the Server sends the SUBACK Packet.

If a Server receives a SUBSCRIBE Packet containing a Topic Filter that is identical to an existing Subscription�s Topic Filter then it MUST completely replace that existing Subscription with a new Subscription. The Topic Filter in the new Subscription will be identical to that in the previous Subscription, although its maximum QoS value could be different. Any existing retained messages matching the Topic Filter MUST be re-sent, but the flow of publications MUST NOT be interrupted [MQTT-3.8.4-3].

Where the Topic Filter is not identical to any existing Subscription�s filter, a new Subscription is created and all matching retained messages are sent.

If a Server receives a SUBSCRIBE packet that contains multiple Topic Filters it MUST handle that packet as if it had received a sequence of multiple SUBSCRIBE packets, except that it combines their responses into a single SUBACK response [MQTT-3.8.4-4].

The SUBACK Packet sent by the Server to the Client MUST contain a return code for each Topic Filter/QoS pair. This return code MUST either show the maximum QoS that was granted for that Subscription or indicate that the subscription failed [MQTT-3.8.4-5]. The Server might grant a lower maximum QoS than the subscriber requested. The QoS of Payload Messages sent in response to a Subscription MUST be the minimum of the QoS of the originally published message and the maximum QoS granted by the Server. The server is permitted to send duplicate copies of a message to a subscriber in the case where the original message was published with QoS 1 and the maximum QoS granted was QoS 0 [MQTT-3.8.4-6].

Non normative examples

If a subscribing Client has been granted maximum QoS 1 for a particular Topic Filter, then a QoS 0 Application Message matching the filter is delivered to the Client at QoS 0. This means that at most one copy of the message is received by the Client. On the other hand a QoS 2 Message published to the same topic is downgraded by the Server to QoS 1 for delivery to the Client, so that Client might receive duplicate copies of the Message.

If the subscribing Client has been granted maximum QoS 0, then an Application Message originally published as QoS 2 might get lost on the hop to the Client, but the Server should never send a duplicate of that Message. A QoS 1 Message published to the same topic might either get lost or duplicated on its transmission to that Client.

Non normative comment

Subscribing to a Topic Filter at QoS 2 is equivalent to saying "I would like to receive Messages matching this filter at the QoS with which they were published". This means a publisher is responsible for determining the maximum QoS a Message can be delivered at, but a subscriber is able to require that the Server downgrades the QoS to one more suitable for its usage.

3.9 SUBACK � Subscribe acknowledgement

A SUBACK Packet is sent by the Server to the Client to confirm receipt and processing of a SUBSCRIBE Packet.

A SUBACK Packet contains a list of return codes, that specify the maximum QoS level that was granted in each Subscription that was requested by the SUBSCRIBE.

3.9.1 Fixed header

Figure 3.24 � SUBACK Packet fixed header

Bit	7	6	5	4	3	2	1	0
byte 1	MQTT Control Packet type (9)				Reserved
	1	0	0	1	0	0	0	0
byte 2	Remaining Length

Remaining Length field

This is the length of variable header (2 bytes) plus the length of the payload.

3.9.2 Variable header

The variable header contains the Packet Identifier from the SUBSCRIBE Packet that is being acknowledged. Figure 3.25 - variable header format below illustrates the format of the variable header.

Figure 3.25 � SUBACK Packet variable header

Bit	7	6	5	4	3	2	1	0
byte 1	Packet Identifier MSB
byte 2	Packet Identifier LSB

3.9.3 Payload

The payload contains a list of return codes. Each return code corresponds to a Topic Filter in the SUBSCRIBE Packet being acknowledged. The order of return codes in the SUBACK Packet MUST match the order of Topic Filters in the SUBSCRIBE Packet [MQTT-3.9.3-1].

Figure 3.26 - Payload format below illustrates the Return Code field encoded in a byte in the Payload.

Figure 3.26 � SUBACK Packet payload format

Bit	7	6	5	4	3	2	1	0
	Return Code
byte 1	X	0	0	0	0	0	X	X

Allowed return codes:

0x00 - Success - Maximum QoS 0
0x01 - Success - Maximum QoS 1
0x02 - Success - Maximum QoS 2
0x80 - Failure

SUBACK return codes other than 0x00, 0x01, 0x02 and 0x80 are reserved and MUST NOT be used [MQTT-3.9.3-2].

3.9.3.1 Payload non normative example

Figure 3.27 - Payload byte format non normative example shows the payload for the SUBACK Packet briefly described in Table 3.6 - Payload non normative example.

Table 3.6 - Payload non normative example

Success - Maximum QoS 0	0
Success - Maximum QoS 2	2
Failure	128

Figure 3.27 - Payload byte format non normative example

	Description	7	6	5	4	3	2	1
byte 1	Success - Maximum QoS 0	0	0	0	0	0	0	0
byte 2	Success - Maximum QoS 2	0	0	0	0	0	0	1
byte 3	Failure	1	0	0	0	0	0	0

3.10 UNSUBSCRIBE � Unsubscribe from topics

An UNSUBSCRIBE Packet is sent by the Client to the Server, to unsubscribe from topics.

3.10.1 Fixed header

Figure 3.28 � UNSUBSCRIBE Packet Fixed header

Bit	7	6	5	4	3	2	1	0
byte 1	MQTT Control Packet type (10)				Reserved
	1	0	1	0	0	0	1	0
byte 2	Remaining Length

Bits 3,2,1 and 0 of the fixed header of the UNSUBSCRIBE Control Packet are reserved and MUST be set to 0,0,1 and 0 respectively. The Server MUST treat any other value as malformed and close the Network Connection [MQTT-3.10.1-1].

Remaining Length field

This is the length of variable header (2 bytes) plus the length of the payload.

3.10.2 Variable header

The variable header contains a Packet Identifier. Section 2.3.1 provides more information about Packet Identifiers.

Figure 3.29 � UNSUBSCRIBE Packet variable header

Bit	7	6	5	4	3	2	1	0
byte 1	Packet Identifier MSB
byte 2	Packet Identifier LSB

3.10.3 Payload

The payload for the UNSUBSCRIBE Packet contains the list of Topic Filters that the Client wishes to unsubscribe from. The Topic Filters in an UNSUBSCRIBE packet MUST be UTF-8 encoded strings as defined in Section 1.5.3, packed contiguously [MQTT-3.10.3-1].

The Payload of an UNSUBSCRIBE packet MUST contain at least one Topic Filter. An UNSUBSCRIBE packet with no payload is a protocol violation [MQTT-3.10.3-2]. See section 4.8 for information about handling errors.

3.10.3.1 Payload non normative example

Figure 3.30 - Payload byte format non normative example show the payload for the UNSUBSCRIBE Packet briefly described in Table3.7 - Payload non normative example.

Table3.7 - Payload non normative example

Topic Filter	�a/b�
Topic Filter	�c/d�

Figure 3.30 - Payload byte format non normative example

	Description	7	6	5	4	3	2	1	0
Topic Filter
byte 1	Length MSB (0)	0	0	0	0	0	0	0	0
byte 2	Length LSB (3)	0	0	0	0	0	0	1	1
byte 3	�a� (0x61)	0	1	1	0	0	0	0	1
byte 4	�/� (0x2F)	0	0	1	0	1	1	1	1
byte 5	�b� (0x62)	0	1	1	0	0	0	1	0
Topic Filter
byte 6	Length MSB (0)	0	0	0	0	0	0	0	0
byte 7	Length LSB (3)	0	0	0	0	0	0	1	1
byte 8	�c� (0x63)	0	1	1	0	0	0	1	1
byte 9	�/� (0x2F)	0	0	1	0	1	1	1	1
byte 10	�d� (0x64)	0	1	1	0	0	1	0	0

3.10.4 Response

The Topic Filters (whether they contain wildcards or not) supplied in an UNSUBSCRIBE packet MUST be compared character-by-character with the current set of Topic Filters held by the Server for the Client. If any filter matches exactly then its owning Subscription is deleted, otherwise no additional processing occurs [MQTT-3.10.4-1].

If a Server deletes a Subscription:

It MUST stop adding any new messages for delivery to the Client [MQTT-3.10.4-2].
It MUST complete the delivery of any QoS 1 or QoS 2 messages which it has started to send to the Client [MQTT-3.10.4-3].
It MAY continue to deliver any existing messages buffered for delivery to the Client.

The Server MUST respond to an UNSUBSUBCRIBE request by sending an UNSUBACK packet. The UNSUBACK Packet MUST have the same Packet Identifier as the UNSUBSCRIBE Packet [MQTT-3.10.4-4]. Even where no Topic Subscriptions are deleted, the Server MUST respond with an UNSUBACK [MQTT-3.10.4-5].

If a Server receives an UNSUBSCRIBE packet that contains multiple Topic Filters it MUST handle that packet as if it had received a sequence of multiple UNSUBSCRIBE packets, except that it sends just one UNSUBACK response [MQTT-3.10.4-6].

3.11 UNSUBACK � Unsubscribe acknowledgement

The UNSUBACK Packet is sent by the Server to the Client to confirm receipt of an UNSUBSCRIBE Packet.

3.11.1 Fixed header

Figure 3.31 � UNSUBACK Packet fixed header

Bit	7	6	5	4	3	2	1	0
byte 1	MQTT Control Packet type (11)				Reserved
	1	0	1	1	0	0	0	0
byte 2	Remaining Length (2)
	0	0	0	0	0	0	1	0

Remaining Length field

This is the length of the variable header. For the UNSUBACK Packet this has the value 2.

3.11.2 Variable header

The variable header contains the Packet Identifier of the UNSUBSCRIBE Packet that is being acknowledged.

Figure 3.32 � UNSUBACK Packet variable header

Bit	7	6	5	4	3	2	1	0
byte 1	Packet Identifier MSB
byte 2	Packet Identifier LSB

3.11.3 Payload

The UNSUBACK Packet has no payload.

3.12 PINGREQ � PING request

The PINGREQ Packet is sent from a Client to the Server. It can be used to:

Indicate to the Server that the Client is alive in the absence of any other Control Packets being sent from the Client to the Server.
Request that the Server responds to confirm that it is alive.
Exercise the network to indicate that the Network Connection is active.

This Packet is used in Keep Alive processing, see Section 3.1.2.10 for more details.

3.12.1 Fixed header

Figure 3.33 � PINGREQ Packet fixed header

Bit	7	6	5	4	3	2	1	0
byte 1	MQTT Control Packet type (12)				Reserved
	1	1	0	0	0	0	0	0
byte 2	Remaining Length (0)
	0	0	0	0	0	0	0	0

3.12.2 Variable header

The PINGREQ Packet has no variable header.

3.12.3 Payload

The PINGREQ Packet has no payload.

3.12.4 Response

The Server MUST send a PINGRESP Packet in response to a PINGREQ Packet [MQTT-3.12.4-1].

3.13 PINGRESP � PING response

A PINGRESP Packet is sent by the Server to the Client in response to a PINGREQ Packet. It indicates that the Server is alive.

This Packet is used in Keep Alive processing, see Section 3.1.2.10 for more details.

3.13.1 Fixed header

Figure 3.34 � PINGRESP Packet fixed header

Bit	7	6	5	4	3	2	1	0
byte 1	MQTT Control Packet type (13)				Reserved
	1	1	0	1	0	0	0	0
byte 2	Remaining Length (0)
	0	0	0	0	0	0	0	0

3.13.2 Variable header

The PINGRESP Packet has no variable header.

3.13.3 Payload

The PINGRESP Packet has no payload.

3.14 DISCONNECT � Disconnect notification

The DISCONNECT Packet is the final Control Packet sent from the Client to the Server. It indicates that the Client is disconnecting cleanly.

3.14.1 Fixed header

Figure 3.35 � DISCONNECT Packet fixed header

Bit	7	6	5	4	3	2	1	0
byte 1	MQTT Control Packet type (14)				Reserved
	1	1	1	0	0	0	0	0
byte 2	Remaining Length (0)
	0	0	0	0	0	0	0	0

The Server MUST validate that reserved bits are set to zero and disconnect the Client if they are not zero [MQTT-3.14.1-1].

3.14.2 Variable header

The DISCONNECT Packet has no variable header.

3.14.3 Payload

The DISCONNECT Packet has no payload.

3.14.4 Response

After sending a DISCONNECT Packet the Client:

MUST close the Network Connection [MQTT-3.14.4-1].
MUST NOT send any more Control Packets on that Network Connection [MQTT-3.14.4-2].

On receipt of DISCONNECT the Server:

MUST discard any Will Message associated with the current connection without publishing it, as described in Section 3.1.2.5 [MQTT-3.14.4-3].
SHOULD close the Network Connection if the Client has not already done so.

4 Operational behavior

4.1 Storing state

It is necessary for the Client and Server to store Session state in order to provide Quality of Service guarantees. The Client and Server MUST store Session state for the entire duration of the Session [MQTT-4.1.0-1]. A Session MUST last at least as long it has an active Network Connection [MQTT-4.1.0-2].

Retained messages do not form part of the Session state in the Server. The Server SHOULD retain such messages until deleted by a Client.

Non normative comment

The storage capabilities of Client and Server implementations will of course have limits in terms of capacity and may be subject to administrative policies such as the maximum time that Session state is stored between Network Connections. Stored Session state can be discarded as a result of an administrator action, including an automated response to defined conditions. This has the effect of terminating the Session. These actions might be prompted by resource constraints or for other operational reasons. It is prudent to evaluate the storage capabilities of the Client and Server to ensure that they are sufficient.

Non normative comment

It is possible that hardware or software failures may result in loss or corruption of Session state stored by the Client or Server.

Non normative comment

Normal operation of the Client of Server could mean that stored state is lost or corrupted because of administrator action, hardware failure or software failure. An administrator action could be an automated response to defined conditions. These actions might be prompted by resource constraints or for other operational reasons. For example the server might determine that based on external knowledge, a message or messages can no longer be delivered to any current or future client.

Non normative comment

An MQTT user should evaluate the storage capabilities of the MQTT Client and Server implementations to ensure that they are sufficient for their needs.

4.1.1 Non normative example

For example, a user wishing to gather electricity meter readings may decide that they need to use QoS 1 messages because they need to protect the readings against loss over the network, however they may have determined that the power supply is sufficiently reliable that the data in the Client and Server can be stored in volatile memory without too much risk of its loss.

Conversely a parking meter payment application provider might decide that there are no circumstances where a payment message can be lost so they require that all data are force written to non-volatile memory before it is transmitted across the network.

4.2 Network Connections

The MQTT protocol requires an underlying transport that provides an ordered, lossless, stream of bytes from the Client to Server and Server to Client.

Non normative comment

The transport protocol used to carry MQTT 3.1 was TCP/IP as defined in [RFC793]. TCP/IP can be used for MQTT 3.1.1. The following are also suitable:

� TLS [RFC5246]

� WebSocket [RFC6455]

Non normative comment

TCP ports 8883 and 1883 are registered with IANA for MQTT TLS and non TLS communication respectively.

Connectionless network transports such as User Datagram Protocol (UDP) are not suitable on their own because they might lose or reorder data.

4.3 Quality of Service levels and protocol flows

MQTT delivers Application Messages according to the Quality of Service (QoS) levels defined here. The delivery protocol is symmetric, in the description below the Client and Server can each take the role of either Sender or Receiver. The delivery protocol is concerned solely with the delivery of an application message from a single Sender to a single Receiver. When the Server is delivering an Application Message to more than one Client, each Client is treated independently. The QoS level used to deliver an Application Message outbound to the Client could differ from that of the inbound Application Message.

The non-normative flow diagrams in the following sections are intended to show possible implementation approaches.

4.3.1 QoS 0: At most once delivery

The message is delivered according to the capabilities of the underlying network. No response is sent by the receiver and no retry is performed by the sender. The message arrives at the receiver either once or not at all.

In the QoS 0 delivery protocol, the Sender

� MUST send a PUBLISH packet with QoS=0, DUP=0 [MQTT-4.3.1-1].

In the QoS 0 delivery protocol, the Receiver

� Accepts ownership of the message when it receives the PUBLISH packet.

Figure 4.1 � QoS 0 protocol flow diagram, non normative example

Sender Action	Control Packet	Receiver Action
PUBLISH QoS 0, DUP=0
	---------->
		Deliver Application Message to appropriate onward recipient(s)

4.3.2 QoS 1: At least once delivery

This quality of service ensures that the message arrives at the receiver at least once. A QoS 1 PUBLISH Packet has a Packet Identifier in its variable header and is acknowledged by a PUBACK Packet. Section 2.3.1 provides more information about Packet Identifiers.

In the QoS 1 delivery protocol, the Sender

� MUST assign an unused Packet Identifier each time it has a new Application Message to publish.

� MUST send a PUBLISH Packet containing this Packet Identifier with QoS=1, DUP=0.

� MUST treat the PUBLISH Packet as �unacknowledged� until it has received the corresponding PUBACK packet from the receiver. See Section 4.4 for a discussion of unacknowledged messages.

[MQTT-4.3.2-1].

The Packet Identifier becomes available for reuse once the Sender has received the PUBACK Packet.

Note that a Sender is permitted to send further PUBLISH Packets with different Packet Identifiers while it is waiting to receive acknowledgements.

In the QoS 1 delivery protocol, the Receiver

MUST respond with a PUBACK Packet containing the Packet Identifier from the incoming PUBLISH Packet, having accepted ownership of the Application Message
After it has sent a PUBACK Packet the Receiver MUST treat any incoming PUBLISH packet that contains the same Packet Identifier as being a new publication, irrespective of the setting of its DUP flag.

[MQTT-4.3.2-2].

Figure 4.2 � QoS 1 protocol flow diagram, non normative example

Sender Action	Control Packet	Receiver action
Store message
Send PUBLISH QoS 1, DUP 0, <Packet Identifier>	---------->
		Initiate onward delivery of the Application Message¹
	<----------	Send PUBACK <Packet Identifier>
Discard message

¹The receiver is not required to complete delivery of the Application Message before sending the PUBACK. When its original sender receives the PUBACK packet, ownership of the Application Message is transferred to the receiver.

4.3.3 QoS 2: Exactly once delivery

This is the highest quality of service, for use when neither loss nor duplication of messages are acceptable. There is an increased overhead associated with this quality of service.

A QoS 2 message has a Packet Identifier in its variable header. Section 2.3.1 provides more information about Packet Identifiers. The receiver of a QoS 2 PUBLISH Packet acknowledges receipt with a two-step acknowledgement process.

In the QoS 2 delivery protocol, the Sender

MUST assign an unused Packet Identifier when it has a new Application Message to publish.
MUST send a PUBLISH packet containing this Packet Identifier with QoS=2, DUP=0.
MUST treat the PUBLISH packet as �unacknowledged� until it has received the corresponding PUBREC packet from the receiver. See Section 4.4 for a discussion of unacknowledged messages.
MUST send a PUBREL packet when it receives a PUBREC packet from the receiver. This PUBREL packet MUST contain the same Packet Identifier as the original PUBLISH packet.
MUST treat the PUBREL packet as �unacknowledged� until it has received the corresponding PUBCOMP packet from the receiver.
MUST NOT re-send the PUBLISH once it has sent the corresponding PUBREL packet.

[MQTT-4.3.3-1].

The Packet Identifier becomes available for reuse once the Sender has received the PUBCOMP Packet.

Note that a Sender is permitted to send further PUBLISH Packets with different Packet Identifiers while it is waiting to receive acknowledgements.

In the QoS 2 delivery protocol, the Receiver

MUST respond with a PUBREC containing the Packet Identifier from the incoming PUBLISH Packet, having accepted ownership of the Application Message.
Until it has received the corresponding PUBREL packet, the Receiver MUST acknowledge any subsequent PUBLISH packet with the same Packet Identifier by sending a PUBREC. It MUST NOT cause duplicate messages to be delivered to any onward recipients in this case.
MUST respond to a PUBREL packet by sending a PUBCOMP packet containing the same Packet Identifier as the PUBREL.
After it has sent a PUBCOMP, the receiver MUST treat any subsequent PUBLISH packet that contains that Packet Identifier as being a new publication.

[MQTT-4.3.3-2].

Figure 4.3 � QoS 2 protocol flow diagram, non normative example

Sender Action	Control Packet	Receiver Action
Store message
PUBLISH QoS 2, DUP 0 <Packet Identifier>
	---------->
		Method A, Store message or Method B, Store <Packet Identifier> then Initiate onward delivery of the Application Message¹
		PUBREC <Packet Identifier>
	<----------
Discard message, Store PUBREC received <Packet Identifier>
PUBREL <Packet Identifier>
	---------->
		Method A, Initiate onward delivery of the Application Message¹ then discard message or Method B, Discard <Packet Identifier>
		Send PUBCOMP <Packet Identifier>
	<----------
Discard stored state

¹The receiver is not required to complete delivery of the Application Message before sending the PUBREC or PUBCOMP. When its original sender receives the PUBREC packet, ownership of the Application Message is transferred to the receiver.

Figure 4.3 shows that there are two methods by which QoS 2 can be handled by the receiver. They differ in the point within the flow at which the message is made available for onward delivery. The choice of Method A or Method B is implementation specific. As long as an implementation chooses exactly one of these approaches, this does not affect the guarantees of a QoS 2 flow.

4.4 Message delivery retry

When a Client reconnects with CleanSession set to 0, both the Client and Server MUST re-send any unacknowledged PUBLISH Packets (where QoS > 0) and PUBREL Packets using their original Packet Identifiers [MQTT-4.4.0-1]. This is the only circumstance where a Client or Server is REQUIRED to redeliver messages.

Non normative comment
Historically retransmission of Control Packets was required to overcome data loss on some older TCP networks. This might remain a concern where MQTT 3.1.1 implementations are to be deployed in such environments.

4.5 Message receipt

When a Server takes ownership of an incoming Application Message it MUST add it to the Session state of those clients that have matching Subscriptions. Matching rules are defined in Section 4.7 [MQTT-4.5.0-1].

Under normal circumstances Clients receive messages in response to Subscriptions they have created. A Client could also receive messages that do not match any of its explicit Subscriptions. This can happen if the Server automatically assigned a subscription to the Client. A Client could also receive messages while an UNSUBSCRIBE operation is in progress. The Client MUST acknowledge any Publish Packet it receives according to the applicable QoS rules regardless of whether it elects to process the Application Message that it contains [MQTT-4.5.0-2].

4.6 Message ordering

A Client MUST follow these rules when implementing the protocol flows defined elsewhere in this chapter:

When it re-sends any PUBLISH packets, it MUST re-send them in the order in which the original PUBLISH packets were sent (this applies to QoS 1 and QoS 2 messages) [MQTT-4.6.0-1]
It MUST send PUBACK packets in the order in which the corresponding PUBLISH packets were received (QoS 1 messages) [MQTT-4.6.0-2]
It MUST send PUBREC packets in the order in which the corresponding PUBLISH packets were received (QoS 2 messages) [MQTT-4.6.0-3]
It MUST send PUBREL packets in the order in which the corresponding PUBREC packets were received (QoS 2 messages) [MQTT-4.6.0-4]

A Server MUST by default treat each Topic as an "Ordered Topic". It MAY provide an administrative or other mechanism to allow one or more Topics to be treated as an "Unordered Topic" [MQTT-4.6.0-5].

When a Server processes a message that has been published to an Ordered Topic, it MUST follow the rules listed above when delivering messages to each of its subscribers. In addition it MUST send PUBLISH packets to consumers (for the same Topic and QoS) in the order that they were received from any given Client [MQTT-4.6.0-6].

Non normative comment

The rules listed above ensure that when a stream of messages is published and subscribed to with QoS 1, the final copy of each message received by the subscribers will be in the order that they were originally published in, but the possibility of message duplication could result in a re-send of an earlier message being received after one of its successor messages. For example a publisher might send messages in the order 1,2,3,4 and the subscriber might receive them in the order 1,2,3,2,3,4.

If both Client and Server make sure that no more than one message is �in-flight� at any one time (by not sending a message until its predecessor has been acknowledged), then no QoS 1 message will be received after any later one - for example a subscriber might receive them in the order 1,2,3,3,4 but not 1,2,3,2,3,4. Setting an in-flight window of 1 also means that order will be preserved even if the publisher sends a sequence of messages with different QoS levels on the same topic.

4.7 Topic Names and Topic Filters

4.7.1 Topic wildcards

The topic level separator is used to introduce structure into the Topic Name. If present, it divides the Topic Name into multiple �topic levels�.

A subscription�s Topic Filter can contain special wildcard characters, which allow you to subscribe to multiple topics at once.

The wildcard characters can be used in Topic Filters, but MUST NOT be used within a Topic Name [MQTT-4.7.1-1].

4.7.1.1 Topic level separator

The forward slash (�/� U+002F) is used to separate each level within a topic tree and provide a hierarchical structure to the Topic Names. The use of the topic level separator is significant when either of the two wildcard characters is encountered in Topic Filters specified by subscribing Clients. Topic level separators can appear anywhere in a Topic Filter or Topic Name. Adjacent Topic level separators indicate a zero length topic level.

4.7.1.2 Multi-level wildcard

The number sign (�#� U+0023) is a wildcard character that matches any number of levels within a topic. The multi-level wildcard represents the parent and any number of child levels. The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic Filter [MQTT-4.7.1-2].

Non normative comment

For example, if a Client subscribes to �sport/tennis/player1/#�, it would receive messages published using these topic names:

� �sport/tennis/player1�

� �sport/tennis/player1/ranking�

� �sport/tennis/player1/score/wimbledon�

Non normative comment

� �sport/#� also matches the singular �sport�, since # includes the parent level.

� �#� is valid and will receive every Application Message

� �sport/tennis/#� is valid

� �sport/tennis#� is not valid

� �sport/tennis/#/ranking� is not valid

4.7.1.3 Single level wildcard

The plus sign (�+� U+002B) is a wildcard character that matches only one topic level.

The single-level wildcard can be used at any level in the Topic Filter, including first and last levels. Where it is used it MUST occupy an entire level of the filter [MQTT-4.7.1-3]. It can be used at more than one level in the Topic Filter and can be used in conjunction with the multilevel wildcard.

Non normative comment

For example, �sport/tennis/+� matches �sport/tennis/player1� and �sport/tennis/player2�, but not �sport/tennis/player1/ranking�. Also, because the single-level wildcard matches only a single level, �sport/+� does not match �sport� but it does match �sport/�.

Non normative comment

� �+� is valid

� �+/tennis/#� is valid

� �sport+� is not valid

� �sport/+/player1� is valid

� �/finance� matches �+/+� and �/+�, but not �+�

4.7.2 Topics beginning with $

The Server MUST NOT match Topic Filters starting with a wildcard character (# or +) with Topic Names beginning with a $ character [MQTT-4.7.2-1]. The Server SHOULD prevent Clients from using such Topic Names to exchange messages with other Clients. Server implementations MAY use Topic Names that start with a leading $ character for other purposes.

Non normative comment

� $SYS/ has been widely adopted as a prefix to topics that contain Server-specific information or control APIs

� Applications cannot use a topic with a leading $ character for their own purposes

Non normative comment

� A subscription to �#� will not receive any messages published to a topic beginning with a $

� A subscription to �+/monitor/Clients� will not receive any messages published to �$SYS/monitor/Clients�

� A subscription to �$SYS/#� will receive messages published to topics beginning with �$SYS/�

� A subscription to �$SYS/monitor/+� will receive messages published to �$SYS/monitor/Clients�

� For a Client to receive messages from topics that begin with $SYS/ and from topics that don�t begin with a $, it has to subscribe to both �#� and �$SYS/#�

4.7.3 Topic semantic and usage

The following rules apply to Topic Names and Topic Filters:

All Topic Names and Topic Filters MUST be at least one character long [MQTT-4.7.3-1]
Topic Names and Topic Filters are case sensitive
Topic Names and Topic Filters can include the space character
A leading or trailing �/� creates a distinct Topic Name or Topic Filter
A Topic Name or Topic Filter consisting only of the �/� character is valid
Topic Names and Topic Filters MUST NOT include the null character (Unicode U+0000) [Unicode] [MQTT-4.7.3-2]
Topic Names and Topic Filters are UTF-8 encoded strings, they MUST NOT encode to more than 65535 bytes [MQTT-4.7.3-3]. See Section 1.5.3

There is no limit to the number of levels in a Topic Name or Topic Filter, other than that imposed by the overall length of a UTF-8 encoded string.

When it performs subscription matching the Server MUST NOT perform any normalization of Topic Names or Topic Filters, or any modification or substitution of unrecognized characters [MQTT-4.7.3-4]. Each non-wildcarded level in the Topic Filter has to match the corresponding level in the Topic Name character for character for the match to succeed.

Non normative comment

The UTF-8 encoding rules mean that the comparison of Topic Filter and Topic Name could be performed either by comparing the encoded UTF-8 bytes, or by comparing decoded Unicode characters

Non normative comment

� �ACCOUNTS� and �Accounts� are two different topic names

� �Accounts payable� is a valid topic name

� �/finance� is different from �finance�

An Application Message is sent to each Client Subscription whose Topic Filter matches the Topic Name attached to an Application Message. The topic resource MAY be either predefined in the Server by an administrator or it MAY be dynamically created by the Server when it receives the first subscription or an Application Message with that Topic Name. The Server MAY also use a security component to selectively authorize actions on the topic resource for a given Client.

4.8 Handling errors

Unless stated otherwise, if either the Server or Client encounters a protocol violation, it MUST close the Network Connection on which it received that Control Packet which caused the protocol violation [MQTT-4.8.0-1].

A Client or Server implementation might encounter a Transient Error (for example an internal buffer full condition) that prevents successful processing of an MQTT packet.

If the Client or Server encounters a Transient Error while processing an inbound Control Packet it MUST close the Network Connection on which it received that Control Packet [MQTT-4.8.0-2]. If a Server detects a Transient Error it SHOULD NOT disconnect or have any other effect on its interactions with any other Client.

5 Security

5.1 Introduction

This Chapter is provided for guidance only and is Non Normative. However, it is strongly recommended that Server implementations that offer TLS [RFC5246] SHOULD use TCP port 8883 (IANA service name: secure-mqtt).

There are a number of threats that solution providers should consider. For example:

Devices could be compromised
Data at rest in Clients and Servers might be accessible
Protocol behaviors could have side effects (e.g. �timing attacks�)
Denial of Service (DoS) attacks
Communications could be intercepted, altered, re-routed or disclosed
Injection of spoofed Control Packets

MQTT solutions are often deployed in hostile communication environments. In such cases, implementations will often need to provide mechanisms for:

Authentication of users and devices
Authorization of access to Server resources
Integrity of MQTT Control Packets and application data contained therein
Privacy of MQTT Control Packets and application data contained therein

As a transport protocol, MQTT is concerned only with message transmission and it is the implementer's responsibility to provide appropriate security features. This is commonly achieved by using TLS [RFC5246].

In addition to technical security issues there could also be geographic (e.g. U.S.-EU SafeHarbor [USEUSAFEHARB]), industry specific (e.g. PCI DSS [PCIDSS]) and regulatory considerations (e.g. Sarbanes-Oxley [SARBANES]).

5.2 MQTT solutions: security and certification

An implementation might want to provide conformance with specific industry security standards such as NIST Cyber Security Framework [NISTCSF], PCI-DSS [PCIDSS]), FIPS-140-2 [FIPS1402] and NSA Suite B [NSAB].

Guidance on using MQTT within the NIST Cyber Security Framework [NISTCSF] can be found in the MQTT supplemental publication, MQTT and the NIST Framework for Improving Critical Infrastructure Cybersecurity [MQTT NIST]. The use of industry proven, independently verified and certified technologies will help meet compliance requirements.

5.3 Lightweight cryptography and constrained devices

Advanced Encryption Standard [AES] and Data Encryption Standard [DES] are widely adopted.

ISO 29192 [ISO29192] makes recommendations for cryptographic primitives specifically tuned to perform on constrained �low end� devices.

5.4 Implementation notes

There are many security concerns to consider when implementing or using MQTT. The following section should not be considered a �check list�.

An implementation might want to achieve some, or all, of the following:

5.4.1 Authentication of Clients by the Server

The CONNECT Packet contains Username and Password fields. Implementations can choose how to make use of the content of these fields. They may provide their own authentication mechanism, use an external authentication system such as LDAP [RFC4511] or OAuth [RFC6749] tokens, or leverage operating system authentication mechanisms.

Implementations passing authentication data in clear text, obfuscating such data elements or requiring no authentication data should be aware this can give rise to Man-in-the-Middle and replay attacks. Section 5.4.5 introduces approaches to ensure data privacy.

A Virtual Private Network (VPN) between the Clients and Servers can provide confidence that data is only being received from authorized Clients.

Where TLS [RFC5246] is used, SSL Certificates sent from the Client can be used by the Server to authenticate the Client.

An implementation might allow for authentication where the credentials are sent in an Application Message from the Client to the Server.

5.4.2 Authorization of Clients by the Server

An implementation may restrict access to Server resources based on information provided by the Client such as User Name, Client Identifier, the hostname/IP address of the Client, or the outcome of authentication mechanisms.

5.4.3 Authentication of the Server by the Client

The MQTT protocol is not trust symmetrical: it provides no mechanism for the Client to authenticate the Server.

Where TLS [RFC5246] is used, SSL Certificates sent from the Server can be used by the Client to authenticate the Server. Implementations providing MQTT service for multiple hostnames from a single IP address should be aware of the Server Name Indication extension to TLS defined in section 3 of RFC 6066 [RFC6066].This allows a Client to tell the Server the hostname of the Server it is trying to connect to.

An implementation might allow for authentication where the credentials are sent in an Application Message from the Server to the Client.

A VPN between Clients and Servers can provide confidence that Clients are connecting to the intended Server.

5.4.4 Integrity of Application Messages and Control Packets

Applications can independently include hash values in their Application Messages. This can provide integrity of the contents of Publish Control Packets across the network and at rest.

TLS [RFC5246] provides hash algorithms to verify the integrity of data sent over the network.

The use of VPNs to connect Clients and Servers can provide integrity of data across the section of the network covered by a VPN.

5.4.5 Privacy of Application Messages and Control Packets

TLS [RFC5246] can provide encryption of data sent over the network. There are valid TLS cipher suites that include a NULL encryption algorithm that does not encrypt data. To ensure privacy Clients and Servers should avoid these cipher suites.

An application might independently encrypt the contents of its Application Messages. This could provide privacy of the Application Message both over the network and at rest. This would not provide privacy for other properties of the Application Message such as Topic Name.

Client and Server implementations can provide encrypted storage for data at rest such as Application Messages stored as part of a Session.

The use of VPNs to connect Clients and Servers can provide privacy of data across the section of the network covered by a VPN.

5.4.6 Non-repudiation of message transmission

Application designers might need to consider appropriate strategies to achieve end to end non-repudiation.

5.4.7 Detecting compromise of Clients and Servers

Client and Server implementations using TLS [RFC5246] should provide capabilities to ensure that any SSL certificates provided when initiating a TLS [RFC5246] connection are associated with the hostname of the Client connecting or Server being connected to.

Client and Server implementations using TLS [RFC5246] can choose to provide capabilities to check Certificate Revocation Lists (CRLs [RFC5280]) and Online Certificate Status Protocol (OSCP) [RFC6960] to prevent revoked certificates from being used.

Physical deployments might combine tamper-proof hardware with the transmission of specific data in Application Messages. For example a meter might have an embedded GPS to ensure it is not used in an unauthorized location. [IEEE 802.1AR] is a standard for implementing mechanisms to authenticate a device�s identity using a cryptographically bound identifier.

5.4.8 Detecting abnormal behaviors

Server implementations might monitor Client behavior to detect potential security incidents. For example:

Repeated connection attempts
Repeated authentication attempts
Abnormal termination of connections
Topic scanning (attempts to send or subscribe to many topics)
Sending undeliverable messages (no subscribers to the topics)
Clients that connect but do not send data

Server implementations might disconnect Clients that breach its security rules.

Server implementations detecting unwelcome behavior might implement a dynamic block list based on identifiers such as IP address or Client Identifier.

Deployments might use network level controls (where available) to implement rate limiting or blocking based on IP address or other information.

5.4.9 Other security considerations

If Client or Server SSL certificates are lost or it is considered that they might be compromised they should be revoked (utilizing CRLs [RFC5280] and/or OSCP [RFC6960]).

Client or Server authentication credentials, such as User Name and Password, that are lost or considered compromised should be revoked and/or reissued.

In the case of long lasting connections:

Client and Server implementations using TLS [RFC5246] should allow for session renegotiation to establish new cryptographic parameters (replace session keys, change cipher suites, change authentication credentials).

Servers may disconnect Clients and require them to re-authenticate with new credentials.

Constrained devices and Clients on constrained networks can make use of TLS session resumption [RFC5077], in order to reduce the costs of reconnecting TLS [RFC5246] sessions.

Clients connected to a Server have a transitive trust relationship with other Clients connected to the same Server and who have authority to publish data on the same topics.

5.4.10 Use of SOCKS

Implementations of Clients should be aware that some environments will require the use of SOCKSv5 [RFC1928] proxies to make outbound Network Connections. Some MQTT implementations could make use of alternative secured tunnels (e.g. SSH) through the use of SOCKS. Where implementations choose to use SOCKS, they should support both anonymous and user-name password authenticating SOCKS proxies. In the latter case, implementations should be aware that SOCKS authentication might occur in plain-text and so should avoid using the same credentials for connection to a MQTT Server.

5.4.11 Security profiles

Implementers and solution designers might wish to consider security as a set of profiles which can be applied to the MQTT protocol. An example of a layered security hierarchy is presented below.

5.4.11.1 Clear communication profile

When using the clear communication profile, the MQTT protocol runs over an open network with no additional secure communication mechanisms in place.

5.4.11.2 Secured network communication profile

When using the secured network communication profile, the MQTT protocol runs over a physical or virtual network which has security controls e.g., VPNs or physically secure network.

5.4.11.3 Secured transport profile

When using the secured transport profile, the MQTT protocol runs over a physical or virtual network and using TLS [RFC5246] which provides authentication, integrity and privacy.

TLS [RFC5246] Client authentication can be used in addition to � or in place of � MQTT Client authentication as provided by the Username and Password fields.

5.4.11.4 Industry specific security profiles

It is anticipated that the MQTT protocol will be designed into industry specific application profiles, each defining a threat model and the specific security mechanisms to be used to address these threats. Recommendations for specific security mechanisms will often be taken from existing works including:

[NISTCSF] NIST Cyber Security Framework
[NIST7628] NISTIR 7628 Guidelines for Smart Grid Cyber Security
[FIPS1402] Security Requirements for Cryptographic Modules (FIPS PUB 140-2)
[PCIDSS] PCI-DSS Payment Card Industry Data Security Standard
[NSAB] NSA Suite B Cryptography

6 Using WebSocket as a network transport

If MQTT is transported over a WebSocket [RFC6455] connection, the following conditions apply:

� MQTT Control Packets MUST be sent in WebSocket binary data frames. If any other type of data frame is received the recipient MUST close the Network Connection [MQTT-6.0.0-1].

� A single WebSocket data frame can contain multiple or partial MQTT Control Packets. The receiver MUST NOT assume that MQTT Control Packets are aligned on WebSocket frame boundaries [MQTT-6.0.0-2].

� The client MUST include �mqtt� in the list of WebSocket Sub Protocols it offers [MQTT-6.0.0-3].

� The WebSocket Sub Protocol name selected and returned by the server MUST be �mqtt� [MQTT-6.0.0-4].

� The WebSocket URI used to connect the client and server has no impact on the MQTT protocol.

6.1 IANA Considerations

This specification requests IANA to register the WebSocket MQTT sub-protocol under the �WebSocket Subprotocol Name� registry with the following data:

Figure 6. 1 - IANA WebSocket Identifier

Subprotocol Identifier	mqtt
Subprotocol Common Name	mqtt
Subprotocol Definition	http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html

7 Conformance

The MQTT specification defines conformance for MQTT Client implementations and MQTT Server implementations.

An MQTT implementation MAY conform as both an MQTT Client and MQTT Server implementation. A Server that both accepts inbound connections and establishes outbound connections to other Servers MUST conform as both an MQTT Client and MQTT Server [MQTT-7.0.0-1].

Conformant implementations MUST NOT require the use of any extensions defined outside of this specification in order to interoperate with any other conformant implementation [MQTT-7.0.0-2].

7.1 Conformance Targets

7.1.1 MQTT Server

An MQTT Server conforms to this specification only if it satisfies all the statements below:

1. The format of all Control Packets that the Server sends matches the format described in Chapter 2 and Chapter 3.

2. It follows the Topic matching rules described in Section 4.7.

3. It satisfies all of the MUST level requirements in the following chapters that are identified except for those that only apply to the Client:

- Chapter 1 - Introduction

- Chapter 2 - MQTT Control Packet format

- Chapter 3 - MQTT Control Packets

- Chapter 4 - Operational behavior

- Chapter 6 - (if MQTT is transported over a WebSocket connection)

- Chapter 7 - Conformance Targets

A conformant Server MUST support the use of one or more underlying transport protocols that provide an ordered, lossless, stream of bytes from the Client to Server and Server to Client [MQTT-7.1.1-1]. However conformance does not depend on it supporting any specific transport protocols. A Server MAY support any of the transport protocols listed in Section 4.2, or any other transport protocol that meets the requirements of [MQTT-7.1.1-1].

7.1.2 MQTT Client

An MQTT Client conforms to this specification only if it satisfies all the statements below:

1. The format of all Control Packets that the Client sends matches the format described in Chapter 2 and Chapter 3.

2. It satisfies all of the MUST level requirements in the following chapters that are identified except for those that only apply to the Server:

- Chapter 1 - Introduction

- Chapter 2 - MQTT Control Packet format

- Chapter 3 - MQTT Control Packets

- Chapter 4 - Operational behavior

- Chapter 6 - (if MQTT is transported over a WebSocket connection)

- Chapter 7 - Conformance Targets

A conformant Client MUST support the use of one or more underlying transport protocols that provide an ordered, lossless, stream of bytes from the Client to Server and Server to Client [MQTT-7.1.2-1]. However conformance does not depend on it supporting any specific transport protocols. A Client MAY support any of the transport protocols listed in Section 4.2, or any other transport protocol that meets the requirements of [MQTT-7.1.2-1].

Appendix A. Acknowledgements (non normative)

The TC owes special thanks to Dr Andy Stanford-Clark and Arlen Nipper as the original inventors of the MQTT protocol and for their continued support with the standardization process.

The following individuals were members of the OASIS Technical Committee during the creation of this specification and their contributions are gratefully acknowledged:

� Sanjay Aiyagari (VMware, Inc.)

� Ben Bakowski (IBM)

� Andrew Banks (IBM)

� Arthur Barr (IBM)

� William Bathurst (Machine-to-Machine Intelligence (M2MI) Corporation)

� Ken Borgendale (IBM)

� Geoff Brown (Machine-to-Machine Intelligence (M2MI) Corporation)

� James Butler (Cimetrics Inc.)

� Marco Carrer (Eurotech S.p.A.)

� Raphael Cohn (Individual)

� Sarah Cooper (Machine-to-Machine Intelligence (M2MI) Corporation)

� Richard Coppen (IBM)

� AJ Dalola (Telit Communications S.p.A.)

� Mark Darbyshire (TIBCO Software Inc.)

� Scott deDeugd (IBM)

� Paul Duffy (Cisco Systems)

� Phili DesAutels (LogMeIn Inc.)

� John Fallows (Kaazing)

� Pradeep Fernando (WSO2)

� Paul Fremantle (WSO2)

� Thomas Glover (Cognizant Technology Solutions)

� Rahul Gupta (IBM)

� Steve Huston (Individual)

� Wes Johnson (Eurotech S.p.A.)

� Christopher Kelley (Cisco Systems)

� David Kemper (TIBCO Software Inc.)

� James Kirkland (Red Hat)

� Alex Kritikos (Software AG, Inc.)

� Louis-P. Lamoureux (Machine-to-Machine Intelligence (M2MI) Corporation)

� David Locke (IBM)

� Shawn McAllister (Solace Systems)

� Dale Moberg (Axway Software)

� Manu Namboodiri (Machine-to-Machine Intelligence (M2MI) Corporation)

� Peter Niblett (IBM)

� Arlen Nipper (Individual)

� Julien Niset (Machine-to-Machine Intelligence (M2MI) Corporation)

� Mark Nixon (Emerson Process Management)

� Nicholas O'Leary (IBM)

� Sandor Palfy (LogMeIn Inc.)

� Dominik Obermaier (dc-square GmbH)

� Pavan Reddy (Cisco Systems)

� Andrew Schofield (IBM)

� Wadih Shaib (BlackBerry)

� Ian Skerrett (Eclipse Foundation)

� Joe Speed (IBM)

� Allan Stockdill-Mander (IBM)

� Gary Stuebing (Cisco Systems)

� Steve Upton (IBM)

� James Wert jr. (Telit Communications S.p.A.)

� T. Wyatt (Individual)

� SHAWN XIE (Machine-to-Machine Intelligence (M2MI) Corporation)

� Dominik Zajac (dc-square GmbH)

Secretary:

Geoff Brown (geoff.brown@m2mi.com), M2MI

Appendix B. Mandatory normative statements (non normative)

This Appendix is non-normative and is provided as a convenient summary of the numbered conformance statements found in the main body of this document. See Chapter 7 for a definitive list of conformance requirements.

Normative Statement Number	Normative Statement
[MQTT-1.5.3-1]	The character data in a UTF-8 encoded string MUST be well-formed UTF-8 as defined by the Unicode specification [Unicode] and restated in RFC 3629 [RFC3629]. In particular this data MUST NOT include encodings of code points between U+D800 and U+DFFF. If a Server or Client receives a Control Packet containing ill-formed UTF-8 it MUST close the Network Connection.
[MQTT-1.5.3-2]	A UTF-8 encoded string MUST NOT include an encoding of the null character U+0000. If a receiver (Server or Client) receives a Control Packet containing U+0000 it MUST close the Network Connection.
[MQTT-1.5.3-3]	A UTF-8 encoded sequence 0xEF 0xBB 0xBF is always to be interpreted to mean U+FEFF ("ZERO WIDTH NO-BREAK SPACE") wherever it appears in a string and MUST NOT be skipped over or stripped off by a packet receiver.
[MQTT-2.2.2-1]	Where a flag bit is marked as �Reserved� in Table 2.2 - Flag Bits, it is reserved for future use and MUST be set to the value listed in that table.
[MQTT-2.2.2-2]	If invalid flags are received, the receiver MUST close the Network Connection.
[MQTT-2.3.1-1]	SUBSCRIBE, UNSUBSCRIBE, and PUBLISH (in cases where QoS > 0) Control Packets MUST contain a non-zero 16-bit Packet Identifier.
[MQTT-2.3.1-2]	Each time a Client sends a new packet of one of these types it MUST assign it a currently unused Packet Identifier.
[MQTT-2.3.1-3]	If a Client re-sends a particular Control Packet, then it MUST use the same Packet Identifier in subsequent re-sends of that packet. The Packet Identifier becomes available for reuse after the Client has processed the corresponding acknowledgement packet. In the case of a QoS 1 PUBLISH this is the corresponding PUBACK; in the case of QO2 it is PUBCOMP. For SUBSCRIBE or UNSUBSCRIBE it is the corresponding SUBACK or UNSUBACK.
[MQTT-2.3.1-4]	The same conditions [MQTT-2.3.1-3] apply to a Server when it sends a PUBLISH with QoS >0.
[MQTT-2.3.1-5]	A PUBLISH Packet MUST NOT contain a Packet Identifier if its QoS value is set to 0.
[MQTT-2.3.1-6]	A PUBACK, PUBREC or PUBREL Packet MUST contain the same Packet Identifier as the PUBLISH Packet that was originally sent.
[MQTT-2.3.1-7]	Similarly to [MQTT-2.3.1-6], SUBACK and UNSUBACK MUST contain the Packet Identifier that was used in the corresponding SUBSCRIBE and UNSUBSCRIBE Packet respectively.
[MQTT-3.1.0-1]	After a Network Connection is established by a Client to a Server, the first Packet sent from the Client to the Server MUST be a CONNECT Packet.
[MQTT-3.1.0-2]	The Server MUST process a second CONNECT Packet sent from a Client as a protocol violation and disconnect the Client.
[MQTT-3.1.2-1]	If the protocol name is incorrect the Server MAY disconnect the Client, or it MAY continue processing the CONNECT packet in accordance with some other specification. In the latter case, the Server MUST NOT continue to process the CONNECT packet in line with this specification.
[MQTT-3.1.2-2]	The Server MUST respond to the CONNECT Packet with a CONNACK return code 0x01 (unacceptable protocol level) and then disconnect the Client if the Protocol Level is not supported by the Server.
[MQTT-3.1.2-3]	The Server MUST validate that the reserved flag in the CONNECT Control Packet is set to zero and disconnect the Client if it is not zero.
[MQTT-3.1.2-4]	If CleanSession is set to 0, the Server MUST resume communications with the Client based on state from the current Session (as identified by the Client identifier). If there is no Session associated with the Client identifier the Server MUST create a new Session. The Client and Server MUST store the Session after the Client and Server are disconnected.
[MQTT-3.1.2-5]	After the disconnection of a Session that had CleanSession set to 0, the Server MUST store further QoS 1 and QoS 2 messages that match any subscriptions that the client had at the time of disconnection as part of the Session state.
[MQTT-3.1.2-6]	If CleanSession is set to 1, the Client and Server MUST discard any previous Session and start a new one. This Session lasts as long as the Network Connection. State data associated with this Session MUST NOT be reused in any subsequent Session.
[MQTT-3.1.2.7]	Retained messages do not form part of the Session state in the Server, they MUST NOT be deleted when the Session ends.
[MQTT-3.1.2-8]	If the Will Flag is set to 1 this indicates that, if the Connect request is accepted, a Will Message MUST be stored on the Server and associated with the Network Connection. The Will Message MUST be published when the Network Connection is subsequently closed unless the Will Message has been deleted by the Server on receipt of a DISCONNECT Packet.
[MQTT-3.1.2-9]	If the Will Flag is set to 1, the Will QoS and Will Retain fields in the Connect Flags will be used by the Server, and the Will Topic and Will Message fields MUST be present in the payload.
[MQTT-3.1.2-10]	The Will Message MUST be removed from the stored Session state in the Server once it has been published or the Server has received a DISCONNECT packet from the Client.
[MQTT-3.1.2-11]	If the Will Flag is set to 0 the Will QoS and Will Retain fields in the Connect Flags MUST be set to zero and the Will Topic and Will Message fields MUST NOT be present in the payload.
[MQTT-3.1.2-12]	If the Will Flag is set to 0, a Will Message MUST NOT be published when this Network Connection ends.
[MQTT-3.1.2-13]	If the Will Flag is set to 0, then the Will QoS MUST be set to 0 (0x00).
[MQTT-3.1.2-14]	If the Will Flag is set to 1, the value of Will QoS can be 0 (0x00), 1 (0x01), or 2 (0x02). It MUST NOT be 3 (0x03).
[MQTT-3.1.2-15]	If the Will Flag is set to 0, then the Will Retain Flag MUST be set to 0.
[MQTT-3.1.2-16]	If the Will Flag is set to 1 and If Will Retain is set to 0, the Server MUST publish the Will Message as a non-retained message.
[MQTT-3.1.2-17]	If the Will Flag is set to 1 and If Will Retain is set to 1, the Server MUST publish the Will Message as a retained message.
[MQTT-3.1.2-18]	If the User Name Flag is set to 0, a user name MUST NOT be present in the payload.
[MQTT-3.1.2-19]	If the User Name Flag is set to 1, a user name MUST be present in the payload.
[MQTT-3.1.2-20]	If the Password Flag is set to 0, a password MUST NOT be present in the payload.
[MQTT-3.1.2-21]	If the Password Flag is set to 1, a password MUST be present in the payload.
[MQTT-3.1.2-22]	If the User Name Flag is set to 0, the Password Flag MUST be set to 0.
[MQTT-3.1.2-23]	It is the responsibility of the Client to ensure that the interval between Control Packets being sent does not exceed the Keep Alive value. In the absence of sending any other Control Packets, the Client MUST send a PINGREQ Packet.
[MQTT-3.1.2-24]	If the Keep Alive value is non-zero and the Server does not receive a Control Packet from the Client within one and a half times the Keep Alive time period, it MUST disconnect the Network Connection to the Client as if the network had failed.
[MQTT-3.1.3-1]	These fields, if present, MUST appear in the order Client Identifier, Will Topic, Will Message, User Name, Password.
[MQTT-3.1.3-2]	Each Client connecting to the Server has a unique ClientId. The ClientId MUST be used by Clients and by Servers to identify state that they hold relating to this MQTT Session between the Client and the Server.
[MQTT-3.1.3-3]	The Client Identifier (ClientId) MUST be present and MUST be the first field in the CONNECT packet payload.
[MQTT-3.1.3-4]	The ClientId MUST be a UTF-8 encoded string as defined in Section 1.5.3.
[MQTT-3.1.3-5]	The Server MUST allow ClientIds which are between 1 and 23 UTF-8 encoded bytes in length, and that contain only the characters "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ".
[MQTT-3.1.3-6]	A Server MAY allow a Client to supply a ClientId that has a length of zero bytes. However if it does so the Server MUST treat this as a special case and assign a unique ClientId to that Client. It MUST then process the CONNECT packet as if the Client had provided that unique ClientId.
[MQTT-3.1.3-7]	If the Client supplies a zero-byte ClientId, the Client MUST also set CleanSession to 1.
[MQTT-3.1.3-8]	If the Client supplies a zero-byte ClientId with CleanSession set to 0, the Server MUST respond to the CONNECT Packet with a CONNACK return code 0x02 (Identifier rejected) and then close the Network Connection.
[MQTT-3.1.3-9]	If the Server rejects the ClientId it MUST respond to the CONNECT Packet with a CONNACK return code 0x02 (Identifier rejected) and then close the Network Connection.
[MQTT-3.1.3-10]	The Will Topic MUST be a UTF-8 encoded string as defined in Section ‎1.5.3.
[MQTT-3.1.3-11]	The User Name MUST be a UTF-8 encoded string as defined in Section 1.5.3.
[MQTT-3.1.4-1]	The Server MUST validate that the CONNECT Packet conforms to section 3.1 and close the Network Connection without sending a CONNACK if it does not conform.
[MQTT-3.1.4-2]	If the ClientId represents a Client already connected to the Server then the Server MUST disconnect the existing Client.
[MQTT-3.1.4-3]	If CONNECT validation is successful the Server MUST perform the processing of CleanSession that is described in section 3.1.2.4.
[MQTT-3.1.4-4]	If CONNECT validation is successful the Server MUST acknowledge the CONNECT Packet with a CONNACK Packet containing a zero return code.
[MQTT-3.1.4-5]	If the Server rejects the CONNECT, it MUST NOT process any data sent by the Client after the CONNECT Packet.
[MQTT-3.2.0-1]	The first packet sent from the Server to the Client MUST be a CONNACK Packet.
[MQTT-3.2.2-1]	If the Server accepts a connection with CleanSession set to 1, the Server MUST set Session Present to 0 in the CONNACK packet in addition to setting a zero return code in the CONNACK packet.
[MQTT-3.2.2-2]	If the Server accepts a connection with CleanSession set to 0, the value set in Session Present depends on whether the Server already has stored Session state for the supplied client ID. If the Server has stored Session state, it MUST set Session Present to 1 in the CONNACK packet.
[MQTT-3.2.2-3]	If the Server does not have stored Session state, it MUST set Session Present to 0 in the CONNACK packet. This is in addition to setting a zero return code in the CONNACK packet.
[MQTT-3.2.2-4]	If a server sends a CONNACK packet containing a non-zero return code it MUST set Session Present to 0.
[MQTT-3.2.2-5]	If a server sends a CONNACK packet containing a non-zero return code it MUST then close the Network Connection.
[MQTT-3.2.2-6]	If none of the return codes listed in Table 3.1 � Connect Return code values are deemed applicable, then the Server MUST close the Network Connection without sending a CONNACK.
[MQTT-3.3.1-1]	The DUP flag MUST be set to 1 by the Client or Server when it attempts to re-deliver a PUBLISH Packet.
[MQTT-3.3.1-2]	The DUP flag MUST be set to 0 for all QoS 0 messages.
[MQTT-3.3.1-3]	The value of the DUP flag from an incoming PUBLISH packet is not propagated when the PUBLISH Packet is sent to subscribers by the Server. The DUP flag in the outgoing PUBLISH packet is set independently to the incoming PUBLISH packet, its value MUST be determined solely by whether the outgoing PUBLISH packet is a retransmission.
[MQTT-3.3.1-4]	A PUBLISH Packet MUST NOT have both QoS bits set to 1. If a Server or Client receives a PUBLISH Packet which has both QoS bits set to 1 it MUST close the Network Connection.
[MQTT-3.3.1-5]	If the RETAIN flag is set to 1, in a PUBLISH Packet sent by a Client to a Server, the Server MUST store the Application Message and its QoS, so that it can be delivered to future subscribers whose subscriptions match its topic name.
[MQTT-3.3.1-6]	When a new subscription is established, the last retained message, if any, on each matching topic name MUST be sent to the subscriber.
[MQTT-3.3.1-7]	If the Server receives a QoS 0 message with the RETAIN flag set to 1 it MUST discard any message previously retained for that topic. It SHOULD store the new QoS 0 message as the new retained message for that topic, but MAY choose to discard it at any time - if this happens there will be no retained message for that topic.
[MQTT-3.3.1-8]	When sending a PUBLISH Packet to a Client the Server MUST set the RETAIN flag to 1 if a message is sent as a result of a new subscription being made by a Client.
[MQTT-3.3.1-9]	It MUST set the RETAIN flag to 0 when a PUBLISH Packet is sent to a Client because it matches an established subscription regardless of how the flag was set in the message it received.
[MQTT-3.3.1-10]	A PUBLISH Packet with a RETAIN flag set to 1 and a payload containing zero bytes will be processed as normal by the Server and sent to Clients with a subscription matching the topic name. Additionally any existing retained message with the same topic name MUST be removed and any future subscribers for the topic will not receive a retained message.
[MQTT-3.3.1-11]	A zero byte retained message MUST NOT be stored as a retained message on the Server.
[MQTT-3.3.1-12]	If the RETAIN flag is 0, in a PUBLISH Packet sent by a Client to a Server, the Server MUST NOT store the message and MUST NOT remove or replace any existing retained message.
[MQTT-3.3.2-1]	The Topic Name MUST be present as the first field in the PUBLISH Packet Variable header. It MUST be a UTF-8 encoded string.
[MQTT-3.3.2-2]	The Topic Name in the PUBLISH Packet MUST NOT contain wildcard characters.
[MQTT-3.3.2-3]	The Topic Name in a PUBLISH Packet sent by a Server to a subscribing Client MUST match the Subscription�s Topic Filter according to the matching process defined in Section 4.7.
[MQTT-3.3.4-1]	The receiver of a PUBLISH Packet MUST respond according to Table 3.4 - Expected Publish Packet response as determined by the QoS in the PUBLISH Packet.
[MQTT-3.3.5-1]	The Server MUST deliver the message to the Client respecting the maximum QoS of all the matching subscriptions.
[MQTT-3.3.5-2]	If a Server implementation does not authorize a PUBLISH to be performed by a Client; it has no way of informing that Client. It MUST either make a positive acknowledgement, according to the normal QoS rules, or close the Network Connection.
[MQTT-3.6.1-1]	Bits 3,2,1 and 0 of the fixed header in the PUBREL Control Packet are reserved and MUST be set to 0,0,1 and 0 respectively. The Server MUST treat any other value as malformed and close the Network Connection.
[MQTT-3.8.1-1]	Bits 3,2,1 and 0 of the fixed header of the SUBSCRIBE Control Packet are reserved and MUST be set to 0,0,1 and 0 respectively. The Server MUST treat any other value as malformed and close the Network Connection.
[MQTT-3.8.3-1]	The Topic Filters in a SUBSCRIBE packet payload MUST be UTF-8 encoded strings as defined in Section 1.5.3.
[MQTT-3.8.3-2]	If the Server chooses not to support topic filters that contain wildcard characters it MUST reject any Subscription request whose filter contains them.
[MQTT-3.8.3-3]	The payload of a SUBSCRIBE packet MUST contain at least one Topic Filter / QoS pair. A SUBSCRIBE packet with no payload is a protocol violation.
[MQTT-3-8.3-4]	The Server MUST treat a SUBSCRIBE packet as malformed and close the Network Connection if any of Reserved bits in the payload are non-zero, or QoS is not 0,1 or 2.
[MQTT-3.8.4-1]	When the Server receives a SUBSCRIBE Packet from a Client, the Server MUST respond with a SUBACK Packet.
[MQTT-3.8.4-2]	The SUBACK Packet MUST have the same Packet Identifier as the SUBSCRIBE Packet that it is acknowledging.
[MQTT-3.8.4-3]	If a Server receives a SUBSCRIBE Packet containing a Topic Filter that is identical to an existing Subscription�s Topic Filter then it MUST completely replace that existing Subscription with a new Subscription. The Topic Filter in the new Subscription will be identical to that in the previous Subscription, although its maximum QoS value could be different. Any existing retained messages matching the Topic Filter MUST be re-sent, but the flow of publications MUST NOT be interrupted.
[MQTT-3.8.4-4]	If a Server receives a SUBSCRIBE packet that contains multiple Topic Filters it MUST handle that packet as if it had received a sequence of multiple SUBSCRIBE packets, except that it combines their responses into a single SUBACK response.
[MQTT-3.8.4-5]	The SUBACK Packet sent by the Server to the Client MUST contain a return code for each Topic Filter/QoS pair. This return code MUST either show the maximum QoS that was granted for that Subscription or indicate that the subscription failed.
[MQTT-3.8.4-6]	The Server might grant a lower maximum QoS than the subscriber requested. The QoS of Payload Messages sent in response to a Subscription MUST be the minimum of the QoS of the originally published message and the maximum QoS granted by the Server. The server is permitted to send duplicate copies of a message to a subscriber in the case where the original message was published with QoS 1 and the maximum QoS granted was QoS 0.
[MQTT-3.9.3-1]	The order of return codes in the SUBACK Packet MUST match the order of Topic Filters in the SUBSCRIBE Packet.
[MQTT-3.9.3-2]	SUBACK return codes other than 0x00, 0x01, 0x02 and 0x80 are reserved and MUST NOT be used.
[MQTT-3.10.1-1]	Bits 3,2,1 and 0 of the fixed header of the UNSUBSCRIBE Control Packet are reserved and MUST be set to 0,0,1 and 0 respectively. The Server MUST treat any other value as malformed and close the Network Connection.
[MQTT-3.10.3-1]	The Topic Filters in an UNSUBSCRIBE packet MUST be UTF-8 encoded strings as defined in Section 1.5.3, packed contiguously.
[MQTT-3.10.3-2]	The Payload of an UNSUBSCRIBE packet MUST contain at least one Topic Filter. An UNSUBSCRIBE packet with no payload is a protocol violation.
[MQTT-3.10.4-1]	The Topic Filters (whether they contain wildcards or not) supplied in an UNSUBSCRIBE packet MUST be compared character-by-character with the current set of Topic Filters held by the Server for the Client. If any filter matches exactly then its owning Subscription is deleted, otherwise no additional processing occurs.
[MQTT-3.10.4-2]	If a Server deletes a Subscription It MUST stop adding any new messages for delivery to the Client.
[MQTT-3.10.4-3]	If a Server deletes a Subscription It MUST complete the delivery of any QoS 1 or QoS 2 messages which it has started to send to the Client.
[MQTT-3.10.4-4]	The Server MUST respond to an UNSUBSUBCRIBE request by sending an UNSUBACK packet. The UNSUBACK Packet MUST have the same Packet Identifier as the UNSUBSCRIBE Packet.
[MQTT-3.10.4-5]	Even where no Topic Subscriptions are deleted, the Server MUST respond with an UNSUBACK.
[MQTT-3.10.4-6]	If a Server receives an UNSUBSCRIBE packet that contains multiple Topic Filters it MUST handle that packet as if it had received a sequence of multiple UNSUBSCRIBE packets, except that it sends just one UNSUBACK response.
[MQTT-3.12.4-1]	The Server MUST send a PINGRESP Packet in response to a PINGREQ packet.
[MQTT-3.14.1-1]	The Server MUST validate that reserved bits are set to zero and disconnect the Client if they are not zero.
[MQTT-3.14.4-1]	After sending a DISCONNECT Packet the Client MUST close the Network Connection.
[MQTT-3.14.4-2]	After sending a DISCONNECT Packet the Client MUST NOT send any more Control Packets on that Network Connection.
[MQTT-3.14.4-3]	On receipt of DISCONNECT the Server MUST discard any Will Message associated with the current connection without publishing it, as described in Section 3.1.2.5.
[MQTT-4.1.0-1]	The Client and Server MUST store Session state for the entire duration of the Session.
[MQTT-4.1.0-2]	A Session MUST last at least as long it has an active Network Connection.
[MQTT-4.3.1-1]	In the QoS 0 delivery protocol, the Sender � MUST send a PUBLISH packet with QoS=0, DUP=0.
[MQTT-4.3.2-1]	In the QoS 1 delivery protocol, the Sender � MUST assign an unused Packet Identifier each time it has a new Application Message to publish. � MUST send a PUBLISH Packet containing this Packet Identifier with QoS=1, DUP=0. � MUST treat the PUBLISH Packet as "unacknowledged" until it has received the corresponding PUBACK packet from the receiver. See Section 4.4 for a discussion of unacknowledged messages.
[MQTT-4.3.2-2]	In the QoS 1 delivery protocol, the Receiver MUST respond with a PUBACK Packet containing the Packet Identifier from the incoming PUBLISH Packet, having accepted ownership of the Application Message. After it has sent a PUBACK Packet the Receiver MUST treat any incoming PUBLISH packet that contains the same Packet Identifier as being a new publication, irrespective of the setting of its DUP flag.
[MQTT-4.3.3-1]	In the QoS 2 delivery protocol, the Sender MUST assign an unused Packet Identifier when it has a new Application Message to publish. MUST send a PUBLISH packet containing this Packet Identifier with QoS=2, DUP=0. MUST treat the PUBLISH packet as "unacknowledged" until it has received the corresponding PUBREC packet from the receiver. See Section 4.4 for a discussion of unacknowledged messages. MUST send a PUBREL packet when it receives a PUBREC packet from the receiver. This PUBREL packet MUST contain the same Packet Identifier as the original PUBLISH packet. MUST treat the PUBREL packet as "unacknowledged" until it has received the corresponding PUBCOMP packet from the receiver. MUST NOT re-send the PUBLISH once it has sent the corresponding PUBREL packet.
[MQTT-4.3.3-2]	In the QoS 2 delivery protocol, the Receiver MUST respond with a PUBREC containing the Packet Identifier from the incoming PUBLISH Packet, having accepted ownership of the Application Message. Until it has received the corresponding PUBREL packet, the Receiver MUST acknowledge any subsequent PUBLISH packet with the same Packet Identifier by sending a PUBREC. It MUST NOT cause duplicate messages to be delivered to any onward recipients in this case. MUST respond to a PUBREL packet by sending a PUBCOMP packet containing the same Packet Identifier as the PUBREL. After it has sent a PUBCOMP, the receiver MUST treat any subsequent PUBLISH packet that contains that Packet Identifier as being a new publication.
[MQTT-4.4.0-1]	When a Client reconnects with CleanSession set to 0, both the Client and Server MUST re-send any unacknowledged PUBLISH Packets (where QoS > 0) and PUBREL Packets using their original Packet Identifiers.
[MQTT-4.5.0-1]	When a Server takes ownership of an incoming Application Message it MUST add it to the Session state of those clients that have matching Subscriptions. Matching rules are defined in Section 4.7.
[MQTT-4.5.0-2]	The Client MUST acknowledge any Publish Packet it receives according to the applicable QoS rules regardless of whether it elects to process the Application Message that it contains.
[MQTT-4.6.0-1]	When it re-sends any PUBLISH packets, it MUST re-send them in the order in which the original PUBLISH packets were sent (this applies to QoS 1 and QoS 2 messages).
[MQTT-4.6.0-2]	Client MUST send PUBACK packets in the order in which the corresponding PUBLISH packets were received (QoS 1 messages).
[MQTT-4.6.0-3]	Client MUST send PUBREC packets in the order in which the corresponding PUBLISH packets were received (QoS 2 messages).
[MQTT-4.6.0-4]	Client MUST send PUBREL packets in the order in which the corresponding PUBREC packets were received (QoS 2 messages).
[MQTT-4.6.0-5]	A Server MUST by default treat each Topic as an "Ordered Topic". It MAY provide an administrative or other mechanism to allow one or more Topics to be treated as an "Unordered Topic".
[MQTT-4.6.0-6]	When a Server processes a message that has been published to an Ordered Topic, it MUST follow the rules listed above when delivering messages to each of its subscribers. In addition it MUST send PUBLISH packets to consumers (for the same Topic and QoS) in the order that they were received from any given Client.
[MQTT-4.7.1-1]	The wildcard characters can be used in Topic Filters, but MUST NOT be used within a Topic Name.
[MQTT-4.7.1-2]	The multi-level wildcard character MUST be specified either on its own or following a topic level separator. In either case it MUST be the last character specified in the Topic Filter.
[MQTT-4.7.1-3]	The single-level wildcard can be used at any level in the Topic Filter, including first and last levels. Where it is used it MUST occupy an entire level of the filter.
[MQTT-4.7.2-1]	The Server MUST NOT match Topic Filters starting with a wildcard character (# or +) with Topic Names beginning with a $ character.
[MQTT-4.7.3-1]	All Topic Names and Topic Filters MUST be at least one character long.
[MQTT-4.7.3-2]	Topic Names and Topic Filters MUST NOT include the null character (Unicode U+0000).
[MQTT-4.7.3-3]	Topic Names and Topic Filters are UTF-8 encoded strings, they MUST NOT encode to more than 65535 bytes.
[MQTT-4.7.3-4]	When it performs subscription matching the Server MUST NOT perform any normalization of Topic Names or Topic Filters, or any modification or substitution of unrecognized characters.
[MQTT-4.8.0-1]	Unless stated otherwise, if either the Server or Client encounters a protocol violation, it MUST close the Network Connection on which it received that Control Packet which caused the protocol violation.
[MQTT-4.8.0-2]	If the Client or Server encounters a Transient Error while processing an inbound Control Packet it MUST close the Network Connection on which it received that Control Packet.
[MQTT-6.0.0-1]	MQTT Control Packets MUST be sent in WebSocket binary data frames. If any other type of data frame is received the recipient MUST close the Network Connection.
[MQTT-6.0.0-2]	A single WebSocket data frame can contain multiple or partial MQTT Control Packets. The receiver MUST NOT assume that MQTT Control Packets are aligned on WebSocket frame boundaries.
[MQTT-6.0.0-3]	The client MUST include �mqtt� in the list of WebSocket Sub Protocols it offers.
[MQTT-6.0.0-4]	The WebSocket Sub Protocol name selected and returned by the server MUST be �mqtt�.
[MQTT-7.0.0-1]	A Server that both accepts inbound connections and establishes outbound connections to other Servers MUST conform as both an MQTT Client and MQTT Server.
[MQTT-7.0.0-2]	Conformant implementations MUST NOT require the use of any extensions defined outside of this specification in order to interoperate with any other conformant implementation.
[MQTT-7.1.1-1]	A conformant Server MUST support the use of one or more underlying transport protocols that provide an ordered, lossless, stream of bytes from the Client to Server and Server to Client.
[MQTT-7.1.2-1]	A conformant Client MUST support the use of one or more underlying transport protocols that provide an ordered, lossless, stream of bytes from the Client to Server and Server to Client.

Appendix C. Revision history (non normative)

Revision	Date	Editor	Changes Made
[02]	[29 April 2013]	[A Banks]	[Tighten up language for Connect packet]
[03]	[09 May 2013]	[ A Banks]	[Tighten up language in Section 02 Command Message Format]
[04]	[20 May 2013]	[Rahul Gupta]	Tighten up language for PUBLISH message
[05]	[5th June 2013]	[ A Banks] [Rahul Gupta]	[ Issues -5,9,13 ] [Formatting and language tighten up in PUBACK, PUBREC, PUBREL, PUBCOMP message]
[06]	[20^th June 2013]	[Rahul Gupta]	[Issue � 17, 2, 28, 33] [Formatting and language tighten up in SUBSCRIBE, SUBACK, UNSUBSCRIBE, UNSUBACK, PINGREQ, PINGRESP, DISCONNECT Control Packets] Terms Command message change to Control Packet Term �message� is generically used, replaced this word accordingly with packet, publication, subscription.
[06]	[21 June 2013]	[A Banks] [Rahul Gupta]	Resolved Issues � 12,20,15, 3, 35, 34, 23, 5, 21 Resolved Issues � 32,39, 41
[07]	[03 July 2013]	[A Banks] [Rahul Gupta]	Resolved Issues � 18,11,4 Resolved Issues � 26,31,36,37
[08]	[19 July 2013]	[A Banks] [Rahul Gupta]	Resolved Issues � 6, 29, 45 Resolved Issues � 36, 25, 24 Added table for fixed header and payload
[09]	[01 August 2013]	[A Banks]	Resolved Issues � 49, 53, 46, 67, 29, 66, 62, 45, 69, 40, 61, 30
[10]	[10 August 2013]	[A Banks] [Rahul Gupta]	Resolved Issues � 19, 63, 57, 65, 72 Conformance section added
[11]	[10 September 2013]	[A Banks] [N O'Leary & Rahul Gupta]	Resolved Issues � 56 Updated Conformance section
[12]	[18 September 2013]	[Rahul Gupta] [A Banks]	Resolved Issues � 22, 42, 81, 84, 85, 7, 8, 14, 16, Security section is added Resolved Issue -1
[13]	[27 September 2013]	[A Banks]	Resolved Issues � 64, 68, 76, 86, 27, 60, 82, 55, 78, 51, 83, 80
[14]	[10 October 2013]	[A Banks] [Rahul Gupta]	Resolved Issues � 58, 59, 10, 89, 90, 88, 77 Resolved Issues � 94, 96, 93, 92, 95, 87, 74, 71
[15]	[24 October 2013]	[A Banks] [Rahul Gupta]	Resolved Issues � 52, 97, 98, 101 Resolved Issues � 100 Added normative statement numbering and Appendix A
[16]	[21 November 2013]	[A Banks]	Resolved Issues -103, 104, 44
[17]	[05 December 2013]	[A Banks] [Rahul Gupta]	Resolved Issues � 105, 70, 102, 106, 107, 108, 109, 110 Updated normative statement numbering and Appendix A
[CSD04]	[28January 2014]	[Rahul Gupta]	Resolved Issues � 112, 114, 115, 120, 117, 134, 132, 133, 130, 131, 129
[18]	[20 February 2014]	[A Banks] [Rahul Gupta]	Resolved Issues � 175, 139, 176, 166, 149, 164, 140, 154, 178, 188, 181, 155, 170, 196, 173, 157, 195, 191, 150, 179, 185, 174, 163 Resolved Issues � 135, 136, 147, 161, 169, 180, 182, 184, 189, 187
[19]	[28 February 2014]	[A Banks] [Rahul Gupta]	Resolved Issues � 167, 192, 141, 138, 137, 198, 165 Resolved Issues � 199, 144, 159,
[20]	[07 March 2014]	[A Banks] [Rahul Gupta]	Resolved Issues � 113, 162, 158, 146 Resolved Issues � 172, 190, 202, 201
[21]	[17 March 2014]	[A Banks] [Rahul Gupta]	Resolved Issues � 151, 194, 160, 168 Resolved Issues � 205,
[22]	[27 March 2014]	[Rahul Gupta] [A Banks]	Resolved Issues � 145, 186, 142 Resolved Issues � 152, 193
[23]	[28 March 2014]	[A Banks]	Resolved Issues � 204, 148, 210, 208, 209, 171, 183, 117, 212
[24]	[7 April 2014]	[Rahul Gupta] [A Banks]	Added Table of figures Corrected Issue 209
[25]	[8 May 2014]	[Rahul Gupta]	Resolved Issues � 213, 214
[25]	[3 September 2014]	[A Banks]	Resolved Issues � 240, 242, 246
[26]	[17 September 2014]	[Rahul Gupta]	Resolved Issues � 247

CoAP RFC 7252¶

RFC 7252 - The Constrained Application Protocol (CoAP)

[Docs] [txt|pdf] [draft-ietf-core...] [Tracker] [Diff1] [Diff2] [Errata]

Updated by: 7959 PROPOSED STANDARD
Errata Exist

Internet Engineering Task Force (IETF)                         Z. Shelby
Request for Comments: 7252                                           ARM
Category: Standards Track                                      K. Hartke
ISSN: 2070-1721                                               C. Bormann
                                                 Universitaet Bremen TZI
                                                               June 2014


              The Constrained Application Protocol (CoAP)

Abstract

   The Constrained Application Protocol (CoAP) is a specialized web
   transfer protocol for use with constrained nodes and constrained
   (e.g., low-power, lossy) networks.  The nodes often have 8-bit
   microcontrollers with small amounts of ROM and RAM, while constrained
   networks such as IPv6 over Low-Power Wireless Personal Area Networks
   (6LoWPANs) often have high packet error rates and a typical
   throughput of 10s of kbit/s.  The protocol is designed for machine-
   to-machine (M2M) applications such as smart energy and building
   automation.

   CoAP provides a request/response interaction model between
   application endpoints, supports built-in discovery of services and
   resources, and includes key concepts of the Web such as URIs and
   Internet media types.  CoAP is designed to easily interface with HTTP
   for integration with the Web while meeting specialized requirements
   such as multicast support, very low overhead, and simplicity for
   constrained environments.

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/rfc7252.








Shelby, et al.               Standards Track                    [Page 1]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


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.

Annotations from the IoT-Testware Team

Conformance Statements

  The concept of referenceable conformance statements has proven
  to be handy as it facilitates the implementation of Test Purposes.


Table of Conformance Statements

   3.  Message Format  . . . . . . . . . . . . . . . . . . . . . . .  15
         [CoAP-3.0-1]  . . . . . . . . . . . . . . . . . . . . . . .  15
         [CoAP-3.0-2]  . . . . . . . . . . . . . . . . . . . . . . .  15
         [CoAP-3.0-3]  . . . . . . . . . . . . . . . . . . . . . . .  15
         [CoAP-3.0-4]  . . . . . . . . . . . . . . . . . . . . . . .  16


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   5
     1.1.  Features  . . . . . . . . . . . . . . . . . . . . . . . .   5
     1.2.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   6
   2.  Constrained Application Protocol  . . . . . . . . . . . . . .  10
     2.1.  Messaging Model . . . . . . . . . . . . . . . . . . . . .  11
     2.2.  Request/Response Model  . . . . . . . . . . . . . . . . .  12
     2.3.  Intermediaries and Caching  . . . . . . . . . . . . . . .  15
     2.4.  Resource Discovery  . . . . . . . . . . . . . . . . . . .  15
   3.  Message Format  . . . . . . . . . . . . . . . . . . . . . . .  15
     3.1.  Option Format . . . . . . . . . . . . . . . . . . . . . .  17
     3.2.  Option Value Formats  . . . . . . . . . . . . . . . . . .  19
   4.  Message Transmission  . . . . . . . . . . . . . . . . . . . .  20
     4.1.  Messages and Endpoints  . . . . . . . . . . . . . . . . .  20
     4.2.  Messages Transmitted Reliably . . . . . . . . . . . . . .  21
     4.3.  Messages Transmitted without Reliability  . . . . . . . .  23
     4.4.  Message Correlation . . . . . . . . . . . . . . . . . . .  24
     4.5.  Message Deduplication . . . . . . . . . . . . . . . . . .  24
     4.6.  Message Size  . . . . . . . . . . . . . . . . . . . . . .  25
     4.7.  Congestion Control  . . . . . . . . . . . . . . . . . . .  26
     4.8.  Transmission Parameters . . . . . . . . . . . . . . . . .  27
       4.8.1.  Changing the Parameters . . . . . . . . . . . . . . .  27
       4.8.2.  Time Values Derived from Transmission Parameters  . .  28
   5.  Request/Response Semantics  . . . . . . . . . . . . . . . . .  31
     5.1.  Requests  . . . . . . . . . . . . . . . . . . . . . . . .  31
     5.2.  Responses . . . . . . . . . . . . . . . . . . . . . . . .  31
       5.2.1.  Piggybacked . . . . . . . . . . . . . . . . . . . . .  33
       5.2.2.  Separate  . . . . . . . . . . . . . . . . . . . . . .  33
       5.2.3.  Non-confirmable . . . . . . . . . . . . . . . . . . .  34
     5.3.  Request/Response Matching . . . . . . . . . . . . . . . .  34
       5.3.1.  Token . . . . . . . . . . . . . . . . . . . . . . . .  34
       5.3.2.  Request/Response Matching Rules . . . . . . . . . . .  35



Shelby, et al.               Standards Track                    [Page 2]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


     5.4.  Options . . . . . . . . . . . . . . . . . . . . . . . . .  36
       5.4.1.  Critical/Elective . . . . . . . . . . . . . . . . . .  37
       5.4.2.  Proxy Unsafe or Safe-to-Forward and NoCacheKey  . . .  38
       5.4.3.  Length  . . . . . . . . . . . . . . . . . . . . . . .  38
       5.4.4.  Default Values  . . . . . . . . . . . . . . . . . . .  38
       5.4.5.  Repeatable Options  . . . . . . . . . . . . . . . . .  39
       5.4.6.  Option Numbers  . . . . . . . . . . . . . . . . . . .  39
     5.5.  Payloads and Representations  . . . . . . . . . . . . . .  40
       5.5.1.  Representation  . . . . . . . . . . . . . . . . . . .  40
       5.5.2.  Diagnostic Payload  . . . . . . . . . . . . . . . . .  41
       5.5.3.  Selected Representation . . . . . . . . . . . . . . .  41
       5.5.4.  Content Negotiation . . . . . . . . . . . . . . . . .  41
     5.6.  Caching . . . . . . . . . . . . . . . . . . . . . . . . .  42
       5.6.1.  Freshness Model . . . . . . . . . . . . . . . . . . .  43
       5.6.2.  Validation Model  . . . . . . . . . . . . . . . . . .  43
     5.7.  Proxying  . . . . . . . . . . . . . . . . . . . . . . . .  44
       5.7.1.  Proxy Operation . . . . . . . . . . . . . . . . . . .  44
       5.7.2.  Forward-Proxies . . . . . . . . . . . . . . . . . . .  46
       5.7.3.  Reverse-Proxies . . . . . . . . . . . . . . . . . . .  46
     5.8.  Method Definitions  . . . . . . . . . . . . . . . . . . .  47
       5.8.1.  GET . . . . . . . . . . . . . . . . . . . . . . . . .  47
       5.8.2.  POST  . . . . . . . . . . . . . . . . . . . . . . . .  47
       5.8.3.  PUT . . . . . . . . . . . . . . . . . . . . . . . . .  48
       5.8.4.  DELETE  . . . . . . . . . . . . . . . . . . . . . . .  48
     5.9.  Response Code Definitions . . . . . . . . . . . . . . . .  48
       5.9.1.  Success 2.xx  . . . . . . . . . . . . . . . . . . . .  48
       5.9.2.  Client Error 4.xx . . . . . . . . . . . . . . . . . .  50
       5.9.3.  Server Error 5.xx . . . . . . . . . . . . . . . . . .  51
     5.10. Option Definitions  . . . . . . . . . . . . . . . . . . .  52
       5.10.1.  Uri-Host, Uri-Port, Uri-Path, and Uri-Query  . . . .  53
       5.10.2.  Proxy-Uri and Proxy-Scheme . . . . . . . . . . . . .  54
       5.10.3.  Content-Format . . . . . . . . . . . . . . . . . . .  55
       5.10.4.  Accept . . . . . . . . . . . . . . . . . . . . . . .  55
       5.10.5.  Max-Age  . . . . . . . . . . . . . . . . . . . . . .  55
       5.10.6.  ETag . . . . . . . . . . . . . . . . . . . . . . . .  56
       5.10.7.  Location-Path and Location-Query . . . . . . . . . .  57
       5.10.8.  Conditional Request Options  . . . . . . . . . . . .  57
       5.10.9.  Size1 Option . . . . . . . . . . . . . . . . . . . .  59
   6.  CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . . .  59
     6.1.  coap URI Scheme . . . . . . . . . . . . . . . . . . . . .  59
     6.2.  coaps URI Scheme  . . . . . . . . . . . . . . . . . . . .  60
     6.3.  Normalization and Comparison Rules  . . . . . . . . . . .  61
     6.4.  Decomposing URIs into Options . . . . . . . . . . . . . .  61
     6.5.  Composing URIs from Options . . . . . . . . . . . . . . .  62
   7.  Discovery . . . . . . . . . . . . . . . . . . . . . . . . . .  64
     7.1.  Service Discovery . . . . . . . . . . . . . . . . . . . .  64
     7.2.  Resource Discovery  . . . . . . . . . . . . . . . . . . .  64
       7.2.1.  'ct' Attribute  . . . . . . . . . . . . . . . . . . .  64



Shelby, et al.               Standards Track                    [Page 3]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   8.  Multicast CoAP  . . . . . . . . . . . . . . . . . . . . . . .  65
     8.1.  Messaging Layer . . . . . . . . . . . . . . . . . . . . .  65
     8.2.  Request/Response Layer  . . . . . . . . . . . . . . . . .  66
       8.2.1.  Caching . . . . . . . . . . . . . . . . . . . . . . .  67
       8.2.2.  Proxying  . . . . . . . . . . . . . . . . . . . . . .  67
   9.  Securing CoAP . . . . . . . . . . . . . . . . . . . . . . . .  68
     9.1.  DTLS-Secured CoAP . . . . . . . . . . . . . . . . . . . .  69
       9.1.1.  Messaging Layer . . . . . . . . . . . . . . . . . . .  70
       9.1.2.  Request/Response Layer  . . . . . . . . . . . . . . .  71
       9.1.3.  Endpoint Identity . . . . . . . . . . . . . . . . . .  71
   10. Cross-Protocol Proxying between CoAP and HTTP . . . . . . . .  74
     10.1.  CoAP-HTTP Proxying . . . . . . . . . . . . . . . . . . .  75
       10.1.1.  GET  . . . . . . . . . . . . . . . . . . . . . . . .  76
       10.1.2.  PUT  . . . . . . . . . . . . . . . . . . . . . . . .  77
       10.1.3.  DELETE . . . . . . . . . . . . . . . . . . . . . . .  77
       10.1.4.  POST . . . . . . . . . . . . . . . . . . . . . . . .  77
     10.2.  HTTP-CoAP Proxying . . . . . . . . . . . . . . . . . . .  77
       10.2.1.  OPTIONS and TRACE  . . . . . . . . . . . . . . . . .  78
       10.2.2.  GET  . . . . . . . . . . . . . . . . . . . . . . . .  78
       10.2.3.  HEAD . . . . . . . . . . . . . . . . . . . . . . . .  79
       10.2.4.  POST . . . . . . . . . . . . . . . . . . . . . . . .  79
       10.2.5.  PUT  . . . . . . . . . . . . . . . . . . . . . . . .  79
       10.2.6.  DELETE . . . . . . . . . . . . . . . . . . . . . . .  80
       10.2.7.  CONNECT  . . . . . . . . . . . . . . . . . . . . . .  80
   11. Security Considerations . . . . . . . . . . . . . . . . . . .  80
     11.1.  Parsing the Protocol and Processing URIs . . . . . . . .  80
     11.2.  Proxying and Caching . . . . . . . . . . . . . . . . . .  81
     11.3.  Risk of Amplification  . . . . . . . . . . . . . . . . .  81
     11.4.  IP Address Spoofing Attacks  . . . . . . . . . . . . . .  83
     11.5.  Cross-Protocol Attacks . . . . . . . . . . . . . . . . .  84
     11.6.  Constrained-Node Considerations  . . . . . . . . . . . .  86
   12. IANA Considerations . . . . . . . . . . . . . . . . . . . . .  86
     12.1.  CoAP Code Registries . . . . . . . . . . . . . . . . . .  86
       12.1.1.  Method Codes . . . . . . . . . . . . . . . . . . . .  87
       12.1.2.  Response Codes . . . . . . . . . . . . . . . . . . .  88
     12.2.  CoAP Option Numbers Registry . . . . . . . . . . . . . .  89
     12.3.  CoAP Content-Formats Registry  . . . . . . . . . . . . .  91
     12.4.  URI Scheme Registration  . . . . . . . . . . . . . . . .  93
     12.5.  Secure URI Scheme Registration . . . . . . . . . . . . .  94
     12.6.  Service Name and Port Number Registration  . . . . . . .  95
     12.7.  Secure Service Name and Port Number Registration . . . .  96
     12.8.  Multicast Address Registration . . . . . . . . . . . . .  97
   13. Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .  97
   14. References  . . . . . . . . . . . . . . . . . . . . . . . . .  98
     14.1.  Normative References . . . . . . . . . . . . . . . . . .  98
     14.2.  Informative References . . . . . . . . . . . . . . . . . 100
   Appendix A.  Examples . . . . . . . . . . . . . . . . . . . . . . 104
   Appendix B.  URI Examples . . . . . . . . . . . . . . . . . . . . 110



Shelby, et al.               Standards Track                    [Page 4]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


1.  Introduction

   The use of web services (web APIs) on the Internet has become
   ubiquitous in most applications and depends on the fundamental
   Representational State Transfer [REST] architecture of the Web.

   The work on Constrained RESTful Environments (CoRE) aims at realizing
   the REST architecture in a suitable form for the most constrained
   nodes (e.g., 8-bit microcontrollers with limited RAM and ROM) and
   networks (e.g., 6LoWPAN, [RFC4944]).  Constrained networks such as
   6LoWPAN support the fragmentation of IPv6 packets into small link-
   layer frames; however, this causes significant reduction in packet
   delivery probability.  One design goal of CoAP has been to keep
   message overhead small, thus limiting the need for fragmentation.

   One of the main goals of CoAP is to design a generic web protocol for
   the special requirements of this constrained environment, especially
   considering energy, building automation, and other machine-to-machine
   (M2M) applications.  The goal of CoAP is not to blindly compress HTTP
   [RFC2616], but rather to realize a subset of REST common with HTTP
   but optimized for M2M applications.  Although CoAP could be used for
   refashioning simple HTTP interfaces into a more compact protocol,
   more importantly it also offers features for M2M such as built-in
   discovery, multicast support, and asynchronous message exchanges.

   This document specifies the Constrained Application Protocol (CoAP),
   which easily translates to HTTP for integration with the existing Web
   while meeting specialized requirements such as multicast support,
   very low overhead, and simplicity for constrained environments and
   M2M applications.

1.1.  Features

   CoAP has the following main features:

   o  Web protocol fulfilling M2M requirements in constrained
      environments

   o  UDP [RFC0768] binding with optional reliability supporting unicast
      and multicast requests.

   o  Asynchronous message exchanges.

   o  Low header overhead and parsing complexity.

   o  URI and Content-type support.

   o  Simple proxy and caching capabilities.



Shelby, et al.               Standards Track                    [Page 5]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   o  A stateless HTTP mapping, allowing proxies to be built providing
      access to CoAP resources via HTTP in a uniform way or for HTTP
      simple interfaces to be realized alternatively over CoAP.

   o  Security binding to Datagram Transport Layer Security (DTLS)
      [RFC6347].

1.2.  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.  These words may also appear
   in this document in lowercase, absent their normative meanings.

   This specification requires readers to be familiar with all the terms
   and concepts that are discussed in [RFC2616], including "resource",
   "representation", "cache", and "fresh".  (Having been completed
   before the updated set of HTTP RFCs, RFC 7230 to RFC 7235, became
   available, this specification specifically references the predecessor
   version -- RFC 2616.)  In addition, this specification defines the
   following terminology:

   PICS and Configurations
   Endpoint
      An entity participating in the CoAP protocol.  Colloquially, an
      endpoint lives on a "Node", although "Host" would be more
      consistent with Internet standards usage, and is further
      identified by transport-layer multiplexing information that can
      include a UDP port number and a security association
      (Section 4.1).

   Sender
      The originating endpoint of a message.  When the aspect of
      identification of the specific sender is in focus, also "source
      endpoint".

   Recipient
      The destination endpoint of a message.  When the aspect of
      identification of the specific recipient is in focus, also
      "destination endpoint".

   Client
      The originating endpoint of a request; the destination endpoint of
      a response.

   Server
      The destination endpoint of a request; the originating endpoint of
      a response.



Shelby, et al.               Standards Track                    [Page 6]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

   Origin Server
      The server on which a given resource resides or is to be created.

   Intermediary
      A CoAP endpoint that acts both as a server and as a client towards
      an origin server (possibly via further intermediaries).  A common
      form of an intermediary is a proxy; several classes of such
      proxies are discussed in this specification.

   Proxy
      An intermediary that mainly is concerned with forwarding requests
      and relaying back responses, possibly performing caching,
      namespace translation, or protocol translation in the process.  As
      opposed to intermediaries in the general sense, proxies generally
      do not implement specific application semantics.  Based on the
      position in the overall structure of the request forwarding, there
      are two common forms of proxy: forward-proxy and reverse-proxy.
      In some cases, a single endpoint might act as an origin server,
      forward-proxy, or reverse-proxy, switching behavior based on the
      nature of each request.

   Forward-Proxy
      An endpoint selected by a client, usually via local configuration
      rules, to perform requests on behalf of the client, doing any
      necessary translations.  Some translations are minimal, such as
      for proxy requests for "coap" URIs, whereas other requests might
      require translation to and from entirely different application-
      layer protocols.

   Reverse-Proxy
      An endpoint that stands in for one or more other server(s) and
      satisfies requests on behalf of these, doing any necessary
      translations.  Unlike a forward-proxy, the client may not be aware
      that it is communicating with a reverse-proxy; a reverse-proxy
      receives requests as if it were the origin server for the target
      resource.

   CoAP-to-CoAP Proxy
      A proxy that maps from a CoAP request to a CoAP request, i.e.,
      uses the CoAP protocol both on the server and the client side.
      Contrast to cross-proxy.

   Cross-Proxy
      A cross-protocol proxy, or "cross-proxy" for short, is a proxy
      that translates between different protocols, such as a CoAP-to-
      HTTP proxy or an HTTP-to-CoAP proxy.  While this specification
      makes very specific demands of CoAP-to-CoAP proxies, there is more
      variation possible in cross-proxies.



Shelby, et al.               Standards Track                    [Page 7]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014

   Confirmable Message
      Some messages require an acknowledgement.  These messages are
      called "Confirmable".  When no packets are lost, each Confirmable
      message elicits exactly one return message of type Acknowledgement
      or type Reset.

   Non-confirmable Message
      Some other messages do not require an acknowledgement.  This is
      particularly true for messages that are repeated regularly for
      application requirements, such as repeated readings from a sensor.

   Acknowledgement Message
      An Acknowledgement message acknowledges that a specific
      Confirmable message arrived.  By itself, an Acknowledgement
      message does not indicate success or failure of any request
      encapsulated in the Confirmable message, but the Acknowledgement
      message may also carry a Piggybacked Response (see below).

   Reset Message
      A Reset message indicates that a specific message (Confirmable or
      Non-confirmable) was received, but some context is missing to
      properly process it.  This condition is usually caused when the
      receiving node has rebooted and has forgotten some state that
      would be required to interpret the message.  Provoking a Reset
      message (e.g., by sending an Empty Confirmable message) is also
      useful as an inexpensive check of the liveness of an endpoint
      ("CoAP ping").

   Piggybacked Response
      A piggybacked Response is included right in a CoAP Acknowledgement
      (ACK) message that is sent to acknowledge receipt of the Request
      for this Response (Section 5.2.1).

   Separate Response
      When a Confirmable message carrying a request is acknowledged with
      an Empty message (e.g., because the server doesn't have the answer
      right away), a Separate Response is sent in a separate message
      exchange (Section 5.2.2).

   Empty Message
      A message with a Code of 0.00; neither a request nor a response.
      An Empty message only contains the 4-byte header.









Shelby, et al.               Standards Track                    [Page 8]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   Critical Option
      An option that would need to be understood by the endpoint
      ultimately receiving the message in order to properly process the
      message (Section 5.4.1).  Note that the implementation of critical
      options is, as the name "Option" implies, generally optional:
      unsupported critical options lead to an error response or summary
      rejection of the message.

   Elective Option
      An option that is intended to be ignored by an endpoint that does
      not understand it.  Processing the message even without
      understanding the option is acceptable (Section 5.4.1).

   Unsafe Option
      An option that would need to be understood by a proxy receiving
      the message in order to safely forward the message
      (Section 5.4.2).  Not every critical option is an unsafe option.

   Safe-to-Forward Option
      An option that is intended to be safe for forwarding by a proxy
      that does not understand it.  Forwarding the message even without
      understanding the option is acceptable (Section 5.4.2).

   Resource Discovery
      The process where a CoAP client queries a server for its list of
      hosted resources (i.e., links as defined in Section 7).

   Content-Format
      The combination of an Internet media type, potentially with
      specific parameters given, and a content-coding (which is often
      the identity content-coding), identified by a numeric identifier
      defined by the "CoAP Content-Formats" registry.  When the focus is
      less on the numeric identifier than on the combination of these
      characteristics of a resource representation, this is also called
      "representation format".

   Additional terminology for constrained nodes and constrained-node
   networks can be found in [RFC7228].

   In this specification, the term "byte" is used in its now customary
   sense as a synonym for "octet".

   All multi-byte integers in this protocol are interpreted in network
   byte order.

   Where arithmetic is used, this specification uses the notation
   familiar from the programming language C, except that the operator
   "**" stands for exponentiation.



Shelby, et al.               Standards Track                    [Page 9]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


2.  Constrained Application Protocol

   The interaction model of CoAP is similar to the client/server model
   of HTTP.  However, machine-to-machine interactions typically result
   in a CoAP implementation acting in both client and server roles.  A
   CoAP request is equivalent to that of HTTP and is sent by a client to
   request an action (using a Method Code) on a resource (identified by
   a URI) on a server.  The server then sends a response with a Response
   Code; this response may include a resource representation.

   Unlike HTTP, CoAP deals with these interchanges asynchronously over a
   datagram-oriented transport such as UDP.  This is done logically
   using a layer of messages that supports optional reliability (with
   exponential back-off).  CoAP defines four types of messages:
   Confirmable, Non-confirmable, Acknowledgement, Reset.  Method Codes
   and Response Codes included in some of these messages make them carry
   requests or responses.  The basic exchanges of the four types of
   messages are somewhat orthogonal to the request/response
   interactions; requests can be carried in Confirmable and Non-
   confirmable messages, and responses can be carried in these as well
   as piggybacked in Acknowledgement messages.

   One could think of CoAP logically as using a two-layer approach, a
   CoAP messaging layer used to deal with UDP and the asynchronous
   nature of the interactions, and the request/response interactions
   using Method and Response Codes (see Figure 1).  CoAP is however a
   single protocol, with messaging and request/response as just features
   of the CoAP header.

                        +----------------------+
                        |      Application     |
                        +----------------------+
                        +----------------------+  \
                        |  Requests/Responses  |  |
                        |----------------------|  | CoAP
                        |       Messages       |  |
                        +----------------------+  /
                        +----------------------+
                        |          UDP         |
                        +----------------------+

                    Figure 1: Abstract Layering of CoAP









Shelby, et al.               Standards Track                   [Page 10]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


2.1.  Messaging Model

   The CoAP messaging model is based on the exchange of messages over
   UDP between endpoints.

   CoAP uses a short fixed-length binary header (4 bytes) that may be
   followed by compact binary options and a payload.  This message
   format is shared by requests and responses.  The CoAP message format
   is specified in Section 3.  Each message contains a Message ID used
   to detect duplicates and for optional reliability.  (The Message ID
   is compact; its 16-bit size enables up to about 250 messages per
   second from one endpoint to another with default protocol
   parameters.)

   Reliability is provided by marking a message as Confirmable (CON).  A
   Confirmable message is retransmitted using a default timeout and
   exponential back-off between retransmissions, until the recipient
   sends an Acknowledgement message (ACK) with the same Message ID (in
   this example, 0x7d34) from the corresponding endpoint; see Figure 2.
   When a recipient is not at all able to process a Confirmable message
   (i.e., not even able to provide a suitable error response), it
   replies with a Reset message (RST) instead of an Acknowledgement
   (ACK).

                        Client              Server
                           |                  |
                           |   CON [0x7d34]   |
                           +----------------->|
                           |                  |
                           |   ACK [0x7d34]   |
                           |<-----------------+
                           |                  |

                  Figure 2: Reliable Message Transmission

   A message that does not require reliable transmission (for example,
   each single measurement out of a stream of sensor data) can be sent
   as a Non-confirmable message (NON).  These are not acknowledged, but
   still have a Message ID for duplicate detection (in this example,
   0x01a0); see Figure 3.  When a recipient is not able to process a
   Non-confirmable message, it may reply with a Reset message (RST).










Shelby, et al.               Standards Track                   [Page 11]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


                        Client              Server
                           |                  |
                           |   NON [0x01a0]   |
                           +----------------->|
                           |                  |

                 Figure 3: Unreliable Message Transmission

   See Section 4 for details of CoAP messages.

   As CoAP runs over UDP, it also supports the use of multicast IP
   destination addresses, enabling multicast CoAP requests.  Section 8
   discusses the proper use of CoAP messages with multicast addresses
   and precautions for avoiding response congestion.

   Several security modes are defined for CoAP in Section 9 ranging from
   no security to certificate-based security.  This document specifies a
   binding to DTLS for securing the protocol; the use of IPsec with CoAP
   is discussed in [IPsec-CoAP].

2.2.  Request/Response Model

   CoAP request and response semantics are carried in CoAP messages,
   which include either a Method Code or Response Code, respectively.
   Optional (or default) request and response information, such as the
   URI and payload media type are carried as CoAP options.  A Token is
   used to match responses to requests independently from the underlying
   messages (Section 5.3).  (Note that the Token is a concept separate
   from the Message ID.)

   A request is carried in a Confirmable (CON) or Non-confirmable (NON)
   message, and, if immediately available, the response to a request
   carried in a Confirmable message is carried in the resulting
   Acknowledgement (ACK) message.  This is called a piggybacked
   response, detailed in Section 5.2.1.  (There is no need for
   separately acknowledging a piggybacked response, as the client will
   retransmit the request if the Acknowledgement message carrying the
   piggybacked response is lost.)  Two examples for a basic GET request
   with piggybacked response are shown in Figure 4, one successful, one
   resulting in a 4.04 (Not Found) response.











Shelby, et al.               Standards Track                   [Page 12]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


        Client              Server       Client              Server
           |                  |             |                  |
           |   CON [0xbc90]   |             |   CON [0xbc91]   |
           | GET /temperature |             | GET /temperature |
           |   (Token 0x71)   |             |   (Token 0x72)   |
           +----------------->|             +----------------->|
           |                  |             |                  |
           |   ACK [0xbc90]   |             |   ACK [0xbc91]   |
           |   2.05 Content   |             |  4.04 Not Found  |
           |   (Token 0x71)   |             |   (Token 0x72)   |
           |     "22.5 C"     |             |   "Not found"    |
           |<-----------------+             |<-----------------+
           |                  |             |                  |

           Figure 4: Two GET Requests with Piggybacked Responses

   If the server is not able to respond immediately to a request carried
   in a Confirmable message, it simply responds with an Empty
   Acknowledgement message so that the client can stop retransmitting
   the request.  When the response is ready, the server sends it in a
   new Confirmable message (which then in turn needs to be acknowledged
   by the client).  This is called a "separate response", as illustrated
   in Figure 5 and described in more detail in Section 5.2.2.

                        Client              Server
                           |                  |
                           |   CON [0x7a10]   |
                           | GET /temperature |
                           |   (Token 0x73)   |
                           +----------------->|
                           |                  |
                           |   ACK [0x7a10]   |
                           |<-----------------+
                           |                  |
                           ... Time Passes  ...
                           |                  |
                           |   CON [0x23bb]   |
                           |   2.05 Content   |
                           |   (Token 0x73)   |
                           |     "22.5 C"     |
                           |<-----------------+
                           |                  |
                           |   ACK [0x23bb]   |
                           +----------------->|
                           |                  |

             Figure 5: A GET Request with a Separate Response




Shelby, et al.               Standards Track                   [Page 13]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   If a request is sent in a Non-confirmable message, then the response
   is sent using a new Non-confirmable message, although the server may
   instead send a Confirmable message.  This type of exchange is
   illustrated in Figure 6.

                        Client              Server
                           |                  |
                           |   NON [0x7a11]   |
                           | GET /temperature |
                           |   (Token 0x74)   |
                           +----------------->|
                           |                  |
                           |   NON [0x23bc]   |
                           |   2.05 Content   |
                           |   (Token 0x74)   |
                           |     "22.5 C"     |
                           |<-----------------+
                           |                  |

       Figure 6: A Request and a Response Carried in Non-confirmable
                                 Messages

   CoAP makes use of GET, PUT, POST, and DELETE methods in a similar
   manner to HTTP, with the semantics specified in Section 5.8.  (Note
   that the detailed semantics of CoAP methods are "almost, but not
   entirely unlike" [HHGTTG] those of HTTP methods: intuition taken from
   HTTP experience generally does apply well, but there are enough
   differences that make it worthwhile to actually read the present
   specification.)

   Methods beyond the basic four can be added to CoAP in separate
   specifications.  New methods do not necessarily have to use requests
   and responses in pairs.  Even for existing methods, a single request
   may yield multiple responses, e.g., for a multicast request
   (Section 8) or with the Observe option [OBSERVE].

   URI support in a server is simplified as the client already parses
   the URI and splits it into host, port, path, and query components,
   making use of default values for efficiency.  Response Codes relate
   to a small subset of HTTP status codes with a few CoAP-specific codes
   added, as defined in Section 5.9.










Shelby, et al.               Standards Track                   [Page 14]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


2.3.  Intermediaries and Caching

   The protocol supports the caching of responses in order to
   efficiently fulfill requests.  Simple caching is enabled using
   freshness and validity information carried with CoAP responses.  A
   cache could be located in an endpoint or an intermediary.  Caching
   functionality is specified in Section 5.6.

   Proxying is useful in constrained networks for several reasons,
   including to limit network traffic, to improve performance, to access
   resources of sleeping devices, and for security reasons.  The
   proxying of requests on behalf of another CoAP endpoint is supported
   in the protocol.  When using a proxy, the URI of the resource to
   request is included in the request, while the destination IP address
   is set to the address of the proxy.  See Section 5.7 for more
   information on proxy functionality.

   As CoAP was designed according to the REST architecture [REST], and
   thus exhibits functionality similar to that of the HTTP protocol, it
   is quite straightforward to map from CoAP to HTTP and from HTTP to
   CoAP.  Such a mapping may be used to realize an HTTP REST interface
   using CoAP or to convert between HTTP and CoAP.  This conversion can
   be carried out by a cross-protocol proxy ("cross-proxy"), which
   converts the Method or Response Code, media type, and options to the
   corresponding HTTP feature.  Section 10 provides more detail about
   HTTP mapping.

2.4.  Resource Discovery

   Resource discovery is important for machine-to-machine interactions
   and is supported using the CoRE Link Format [RFC6690] as discussed in
   Section 7.

3.  Message Format

   CoAP is based on the exchange of compact messages that, by default,
   are transported over UDP (i.e., each CoAP message occupies the data
   section of one UDP datagram).  CoAP may also be used over Datagram
   Transport Layer Security (DTLS) (see Section 9.1).  It could also be
   used over other transports such as SMS, TCP, or SCTP, the
   specification of which is out of this document's scope.  (UDP-lite
   [RFC3828] and UDP zero checksum [RFC6936] are not supported by CoAP.)

   CoAP messages are encoded in a simple binary format.  The message
   format starts with a fixed-size 4-byte header.  This is followed by a
   variable-length Token value, which can be between 0 and 8 bytes long.





Shelby, et al.               Standards Track                   [Page 15]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   Following the Token value comes a sequence of zero or more CoAP
   Options in Type-Length-Value (TLV) format, optionally followed by a
   payload that takes up the rest of the datagram.

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |Ver| T |  TKL  |      Code     |          Message ID           |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |   Token (if any, TKL bytes) ...
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |   Options (if any) ...
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |1 1 1 1 1 1 1 1|    Payload (if any) ...
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                         Figure 7: Message Format

   The fields in the header are defined as follows:

   Version (Ver):  2-bit unsigned integer.  Indicates the CoAP version
      number. [CoAP-3.0-1] Implementations of this specification MUST
      set this field to 1 (01 binary).  Other values are reserved for
      future versions.
      [CoAP-3.0-2] Messages with unknown version numbers MUST be
      silently ignored.

   Type (T):  2-bit unsigned integer.  Indicates if this message is of
      type Confirmable (0), Non-confirmable (1), Acknowledgement (2), or
      Reset (3).  The semantics of these message types are defined in
      Section 4.

   Token Length (TKL):  4-bit unsigned integer.  Indicates the length of
      the variable-length Token field (0-8 bytes). [CoAP-3.0-3] 
      Lengths 9-15 are reserved, MUST NOT be sent, and MUST be
      processed as a message format error.

   Code:  8-bit unsigned integer, split into a 3-bit class (most
      significant bits) and a 5-bit detail (least significant bits),
      documented as "c.dd" where "c" is a digit from 0 to 7 for the
      3-bit subfield and "dd" are two digits from 00 to 31 for the 5-bit
      subfield.  The class can indicate a request (0), a success
      response (2), a client error response (4), or a server error
      response (5).  (All other class values are reserved.)  As a
      special case, Code 0.00 indicates an Empty message.  In case of a
      request, the Code field indicates the Request Method; in case of a
      response, a Response Code.  Possible values are maintained in the
      CoAP Code Registries (Section 12.1).  The semantics of requests
      and responses are defined in Section 5.




Shelby, et al.               Standards Track                   [Page 16]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   Message ID:  16-bit unsigned integer in network byte order.  Used to
      detect message duplication and to match messages of type
      Acknowledgement/Reset to messages of type Confirmable/Non-
      confirmable.  The rules for generating a Message ID and matching
      messages are defined in Section 4.

   The header is followed by the Token value, which may be 0 to 8 bytes,
   as given by the Token Length field.  The Token value is used to
   correlate requests and responses.  The rules for generating a Token
   and correlating requests and responses are defined in Section 5.3.1.

   Header and Token are followed by zero or more Options (Section 3.1).
   An Option can be followed by the end of the message, by another
   Option, or by the Payload Marker and the payload.

   Following the header, token, and options, if any, comes the optional
   payload.  If present and of non-zero length, it is prefixed by a
   fixed, one-byte Payload Marker (0xFF), which indicates the end of
   options and the start of the payload.  The payload data extends from
   after the marker to the end of the UDP datagram, i.e., the Payload
   Length is calculated from the datagram size.  The absence of the
   Payload Marker denotes a zero-length payload.
   [CoAP-3.0-4] The presence of a marker followed by a zero-length
   payload MUST be processed as a message format error.

   Implementation Note:  The byte value 0xFF may also occur within an
      option length or value, so simple byte-wise scanning for 0xFF is
      not a viable technique for finding the payload marker.  The byte
      0xFF has the meaning of a payload marker only where the beginning
      of another option could occur.

3.1.  Option Format

   CoAP defines a number of options that can be included in a message.
   Each option instance in a message specifies the Option Number of the
   defined CoAP option, the length of the Option Value, and the Option
   Value itself.

   Instead of specifying the Option Number directly, the instances MUST
   appear in order of their Option Numbers and a delta encoding is used
   between them: the Option Number for each instance is calculated as
   the sum of its delta and the Option Number of the preceding instance
   in the message.  For the first instance in a message, a preceding
   option instance with Option Number zero is assumed.  Multiple
   instances of the same option can be included by using a delta of
   zero.





Shelby, et al.               Standards Track                   [Page 17]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   Option Numbers are maintained in the "CoAP Option Numbers" registry
   (Section 12.2).  See Section 5.4 for the semantics of the options
   defined in this document.

     0   1   2   3   4   5   6   7
   +---------------+---------------+
   |               |               |
   |  Option Delta | Option Length |   1 byte
   |               |               |
   +---------------+---------------+
   \                               \
   /         Option Delta          /   0-2 bytes
   \          (extended)           \
   +-------------------------------+
   \                               \
   /         Option Length         /   0-2 bytes
   \          (extended)           \
   +-------------------------------+
   \                               \
   /                               /
   \                               \
   /         Option Value          /   0 or more bytes
   \                               \
   /                               /
   \                               \
   +-------------------------------+

                          Figure 8: Option Format

   The fields in an option are defined as follows:

   Option Delta:  4-bit unsigned integer.  A value between 0 and 12
      indicates the Option Delta.  Three values are reserved for special
      constructs:

      13:  An 8-bit unsigned integer follows the initial byte and
         indicates the Option Delta minus 13.

      14:  A 16-bit unsigned integer in network byte order follows the
         initial byte and indicates the Option Delta minus 269.

      15:  Reserved for the Payload Marker.  If the field is set to this
         value but the entire byte is not the payload marker, this MUST
         be processed as a message format error.







Shelby, et al.               Standards Track                   [Page 18]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


      The resulting Option Delta is used as the difference between the
      Option Number of this option and that of the previous option (or
      zero for the first option).  In other words, the Option Number is
      calculated by simply summing the Option Delta values of this and
      all previous options before it.

   Option Length:  4-bit unsigned integer.  A value between 0 and 12
      indicates the length of the Option Value, in bytes.  Three values
      are reserved for special constructs:

      13:  An 8-bit unsigned integer precedes the Option Value and
         indicates the Option Length minus 13.

      14:  A 16-bit unsigned integer in network byte order precedes the
         Option Value and indicates the Option Length minus 269.

      15:  Reserved for future use.  If the field is set to this value,
         it MUST be processed as a message format error.

   Value:  A sequence of exactly Option Length bytes.  The length and
      format of the Option Value depend on the respective option, which
      MAY define variable-length values.  See Section 3.2 for the
      formats used in this document; options defined in other documents
      MAY make use of other option value formats.

3.2.  Option Value Formats

   The options defined in this document make use of the following option
   value formats.

   empty:    A zero-length sequence of bytes.

   opaque:   An opaque sequence of bytes.

   uint:     A non-negative integer that is represented in network byte
             order using the number of bytes given by the Option Length
             field.

             An option definition may specify a range of permissible
             numbers of bytes; if it has a choice, a sender SHOULD
             represent the integer with as few bytes as possible, i.e.,
             without leading zero bytes.  For example, the number 0 is
             represented with an empty option value (a zero-length
             sequence of bytes) and the number 1 by a single byte with
             the numerical value of 1 (bit combination 00000001 in most
             significant bit first notation).  A recipient MUST be
             prepared to process values with leading zero bytes.




Shelby, et al.               Standards Track                   [Page 19]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


             Implementation Note:  The exceptional behavior permitted
                for the sender is intended for highly constrained,
                templated implementations (e.g., hardware
                implementations) that use fixed-size options in the
                templates.

   string:   A Unicode string that is encoded using UTF-8 [RFC3629] in
             Net-Unicode form [RFC5198].

             Note that here, and in all other places where UTF-8
             encoding is used in the CoAP protocol, the intention is
             that the encoded strings can be directly used and compared
             as opaque byte strings by CoAP protocol implementations.
             There is no expectation and no need to perform
             normalization within a CoAP implementation (except where
             Unicode strings that are not known to be normalized are
             imported from sources outside the CoAP protocol).  Note
             also that ASCII strings (that do not make use of special
             control characters) are always valid UTF-8 Net-Unicode
             strings.

4.  Message Transmission

   CoAP messages are exchanged asynchronously between CoAP endpoints.
   They are used to transport CoAP requests and responses, the semantics
   of which are defined in Section 5.

   As CoAP is bound to unreliable transports such as UDP, CoAP messages
   may arrive out of order, appear duplicated, or go missing without
   notice.  For this reason, CoAP implements a lightweight reliability
   mechanism, without trying to re-create the full feature set of a
   transport like TCP.  It has the following features:

   o  Simple stop-and-wait retransmission reliability with exponential
      back-off for Confirmable messages.

   o  Duplicate detection for both Confirmable and Non-confirmable
      messages.

4.1.  Messages and Endpoints

   A CoAP endpoint is the source or destination of a CoAP message.  The
   specific definition of an endpoint depends on the transport being
   used for CoAP.  For the transports defined in this specification, the
   endpoint is identified depending on the security mode used (see
   Section 9): With no security, the endpoint is solely identified by an
   IP address and a UDP port number.  With other security modes, the
   endpoint is identified as defined by the security mode.



Shelby, et al.               Standards Track                   [Page 20]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   There are different types of messages.  The type of a message is
   specified by the Type field of the CoAP Header.

   Separate from the message type, a message may carry a request, a
   response, or be Empty.  This is signaled by the Request/Response Code
   field in the CoAP Header and is relevant to the request/response
   model.  Possible values for the field are maintained in the CoAP Code
   Registries (Section 12.1).

   An Empty message has the Code field set to 0.00.  The Token Length
   field MUST be set to 0 and bytes of data MUST NOT be present after
   the Message ID field.  If there are any bytes, they MUST be processed
   as a message format error.

4.2.  Messages Transmitted Reliably

   The reliable transmission of a message is initiated by marking the
   message as Confirmable in the CoAP header.  A Confirmable message
   always carries either a request or response, unless it is used only
   to elicit a Reset message, in which case it is Empty.  A recipient
   MUST either (a) acknowledge a Confirmable message with an
   Acknowledgement message or (b) reject the message if the recipient
   lacks context to process the message properly, including situations
   where the message is Empty, uses a code with a reserved class (1, 6,
   or 7), or has a message format error.  Rejecting a Confirmable
   message is effected by sending a matching Reset message and otherwise
   ignoring it.  The Acknowledgement message MUST echo the Message ID of
   the Confirmable message and MUST carry a response or be Empty (see
   Sections 5.2.1 and 5.2.2).  The Reset message MUST echo the Message
   ID of the Confirmable message and MUST be Empty.  Rejecting an
   Acknowledgement or Reset message (including the case where the
   Acknowledgement carries a request or a code with a reserved class, or
   the Reset message is not Empty) is effected by silently ignoring it.
   More generally, recipients of Acknowledgement and Reset messages MUST
   NOT respond with either Acknowledgement or Reset messages.

   The sender retransmits the Confirmable message at exponentially
   increasing intervals, until it receives an acknowledgement (or Reset
   message) or runs out of attempts.

   Retransmission is controlled by two things that a CoAP endpoint MUST
   keep track of for each Confirmable message it sends while waiting for
   an acknowledgement (or reset): a timeout and a retransmission
   counter.  For a new Confirmable message, the initial timeout is set
   to a random duration (often not an integral number of seconds)
   between ACK_TIMEOUT and (ACK_TIMEOUT * ACK_RANDOM_FACTOR) (see
   Section 4.8), and the retransmission counter is set to 0.  When the
   timeout is triggered and the retransmission counter is less than



Shelby, et al.               Standards Track                   [Page 21]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   MAX_RETRANSMIT, the message is retransmitted, the retransmission
   counter is incremented, and the timeout is doubled.  If the
   retransmission counter reaches MAX_RETRANSMIT on a timeout, or if the
   endpoint receives a Reset message, then the attempt to transmit the
   message is canceled and the application process informed of failure.
   On the other hand, if the endpoint receives an acknowledgement in
   time, transmission is considered successful.

   This specification makes no strong requirements on the accuracy of
   the clocks used to implement the above binary exponential back-off
   algorithm.  In particular, an endpoint may be late for a specific
   retransmission due to its sleep schedule and may catch up on the next
   one.  However, the minimum spacing before another retransmission is
   ACK_TIMEOUT, and the entire sequence of (re-)transmissions MUST stay
   in the envelope of MAX_TRANSMIT_SPAN (see Section 4.8.2), even if
   that means a sender may miss an opportunity to transmit.

   A CoAP endpoint that sent a Confirmable message MAY give up in
   attempting to obtain an ACK even before the MAX_RETRANSMIT counter
   value is reached.  For example, the application has canceled the
   request as it no longer needs a response, or there is some other
   indication that the CON message did arrive.  In particular, a CoAP
   request message may have elicited a separate response, in which case
   it is clear to the requester that only the ACK was lost and a
   retransmission of the request would serve no purpose.  However, a
   responder MUST NOT in turn rely on this cross-layer behavior from a
   requester, i.e., it MUST retain the state to create the ACK for the
   request, if needed, even if a Confirmable response was already
   acknowledged by the requester.

   Another reason for giving up retransmission MAY be the receipt of
   ICMP errors.  If it is desired to take account of ICMP errors, to
   mitigate potential spoofing attacks, implementations SHOULD take care
   to check the information about the original datagram in the ICMP
   message, including port numbers and CoAP header information such as
   message type and code, Message ID, and Token; if this is not possible
   due to limitations of the UDP service API, ICMP errors SHOULD be
   ignored.  Packet Too Big errors [RFC4443] ("fragmentation needed and
   DF set" for IPv4 [RFC0792]) cannot properly occur and SHOULD be
   ignored if the implementation note in Section 4.6 is followed;
   otherwise, they SHOULD feed into a path MTU discovery algorithm
   [RFC4821].  Source Quench and Time Exceeded ICMP messages SHOULD be
   ignored.  Host, network, port, or protocol unreachable errors or
   parameter problem errors MAY, after appropriate vetting, be used to
   inform the application of a failure in sending.






Shelby, et al.               Standards Track                   [Page 22]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


4.3.  Messages Transmitted without Reliability

   Some messages do not require an acknowledgement.  This is
   particularly true for messages that are repeated regularly for
   application requirements, such as repeated readings from a sensor
   where eventual success is sufficient.

   As a more lightweight alternative, a message can be transmitted less
   reliably by marking the message as Non-confirmable.  A Non-
   confirmable message always carries either a request or response and
   MUST NOT be Empty.  A Non-confirmable message MUST NOT be
   acknowledged by the recipient.  A recipient MUST reject the message
   if it lacks context to process the message properly, including the
   case where the message is Empty, uses a code with a reserved class
   (1, 6, or 7), or has a message format error.  Rejecting a Non-
   confirmable message MAY involve sending a matching Reset message, and
   apart from the Reset message the rejected message MUST be silently
   ignored.

   At the CoAP level, there is no way for the sender to detect if a Non-
   confirmable message was received or not.  A sender MAY choose to
   transmit multiple copies of a Non-confirmable message within
   MAX_TRANSMIT_SPAN (limited by the provisions of Section 4.7, in
   particular, by PROBING_RATE if no response is received), or the
   network may duplicate the message in transit.  To enable the receiver
   to act only once on the message, Non-confirmable messages specify a
   Message ID as well.  (This Message ID is drawn from the same number
   space as the Message IDs for Confirmable messages.)

   Summarizing Sections 4.2 and 4.3, the four message types can be used
   as in Table 1.  "*" means that the combination is not used in normal
   operation but only to elicit a Reset message ("CoAP ping").

                   +----------+-----+-----+-----+-----+
                   |          | CON | NON | ACK | RST |
                   +----------+-----+-----+-----+-----+
                   | Request  | X   | X   | -   | -   |
                   | Response | X   | X   | X   | -   |
                   | Empty    | *   | -   | X   | X   |
                   +----------+-----+-----+-----+-----+

                      Table 1: Usage of Message Types









Shelby, et al.               Standards Track                   [Page 23]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


4.4.  Message Correlation

   An Acknowledgement or Reset message is related to a Confirmable
   message or Non-confirmable message by means of a Message ID along
   with additional address information of the corresponding endpoint.
   The Message ID is a 16-bit unsigned integer that is generated by the
   sender of a Confirmable or Non-confirmable message and included in
   the CoAP header.  The Message ID MUST be echoed in the
   Acknowledgement or Reset message by the recipient.

   The same Message ID MUST NOT be reused (in communicating with the
   same endpoint) within the EXCHANGE_LIFETIME (Section 4.8.2).

   Implementation Note:  Several implementation strategies can be
      employed for generating Message IDs.  In the simplest case, a CoAP
      endpoint generates Message IDs by keeping a single Message ID
      variable, which is changed each time a new Confirmable or Non-
      confirmable message is sent, regardless of the destination address
      or port.  Endpoints dealing with large numbers of transactions
      could keep multiple Message ID variables, for example, per prefix
      or destination address.  (Note that some receiving endpoints may
      not be able to distinguish unicast and multicast packets addressed
      to it, so endpoints generating Message IDs need to make sure these
      do not overlap.)  It is strongly recommended that the initial
      value of the variable (e.g., on startup) be randomized, in order
      to make successful off-path attacks on the protocol less likely.

   For an Acknowledgement or Reset message to match a Confirmable or
   Non-confirmable message, the Message ID and source endpoint of the
   Acknowledgement or Reset message MUST match the Message ID and
   destination endpoint of the Confirmable or Non-confirmable message.

4.5.  Message Deduplication

   A recipient might receive the same Confirmable message (as indicated
   by the Message ID and source endpoint) multiple times within the
   EXCHANGE_LIFETIME (Section 4.8.2), for example, when its
   Acknowledgement went missing or didn't reach the original sender
   before the first timeout.  The recipient SHOULD acknowledge each
   duplicate copy of a Confirmable message using the same
   Acknowledgement or Reset message but SHOULD process any request or
   response in the message only once.  This rule MAY be relaxed in case
   the Confirmable message transports a request that is idempotent (see
   Section 5.1) or can be handled in an idempotent fashion.  Examples
   for relaxed message deduplication:






Shelby, et al.               Standards Track                   [Page 24]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   o  A server might relax the requirement to answer all retransmissions
      of an idempotent request with the same response (Section 4.2), so
      that it does not have to maintain state for Message IDs.  For
      example, an implementation might want to process duplicate
      transmissions of a GET, PUT, or DELETE request as separate
      requests if the effort incurred by duplicate processing is less
      expensive than keeping track of previous responses would be.

   o  A constrained server might even want to relax this requirement for
      certain non-idempotent requests if the application semantics make
      this trade-off favorable.  For example, if the result of a POST
      request is just the creation of some short-lived state at the
      server, it may be less expensive to incur this effort multiple
      times for a request than keeping track of whether a previous
      transmission of the same request already was processed.

   A recipient might receive the same Non-confirmable message (as
   indicated by the Message ID and source endpoint) multiple times
   within NON_LIFETIME (Section 4.8.2).  As a general rule that MAY be
   relaxed based on the specific semantics of a message, the recipient
   SHOULD silently ignore any duplicated Non-confirmable message and
   SHOULD process any request or response in the message only once.

4.6.  Message Size

   While specific link layers make it beneficial to keep CoAP messages
   small enough to fit into their link-layer packets (see Section 1),
   this is a matter of implementation quality.  The CoAP specification
   itself provides only an upper bound to the message size.  Messages
   larger than an IP packet result in undesirable packet fragmentation.
   A CoAP message, appropriately encapsulated, SHOULD fit within a
   single IP packet (i.e., avoid IP fragmentation) and (by fitting into
   one UDP payload) obviously needs to fit within a single IP datagram.
   If the Path MTU is not known for a destination, an IP MTU of 1280
   bytes SHOULD be assumed; if nothing is known about the size of the
   headers, good upper bounds are 1152 bytes for the message size and
   1024 bytes for the payload size.

   Implementation Note:  CoAP's choice of message size parameters works
      well with IPv6 and with most of today's IPv4 paths.  (However,
      with IPv4, it is harder to absolutely ensure that there is no IP
      fragmentation.  If IPv4 support on unusual networks is a
      consideration, implementations may want to limit themselves to
      more conservative IPv4 datagram sizes such as 576 bytes; per
      [RFC0791], the absolute minimum value of the IP MTU for IPv4 is as
      low as 68 bytes, which would leave only 40 bytes minus security
      overhead for a UDP payload.  Implementations extremely focused on
      this problem set might also set the IPv4 DF bit and perform some



Shelby, et al.               Standards Track                   [Page 25]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


      form of path MTU discovery [RFC4821]; this should generally be
      unnecessary in realistic use cases for CoAP, however.)  A more
      important kind of fragmentation in many constrained networks is
      that on the adaptation layer (e.g., 6LoWPAN L2 packets are limited
      to 127 bytes including various overheads); this may motivate
      implementations to be frugal in their packet sizes and to move to
      block-wise transfers [BLOCK] when approaching three-digit message
      sizes.

      Message sizes are also of considerable importance to
      implementations on constrained nodes.  Many implementations will
      need to allocate a buffer for incoming messages.  If an
      implementation is too constrained to allow for allocating the
      above-mentioned upper bound, it could apply the following
      implementation strategy for messages not using DTLS security:
      Implementations receiving a datagram into a buffer that is too
      small are usually able to determine if the trailing portion of a
      datagram was discarded and to retrieve the initial portion.  So,
      at least the CoAP header and options, if not all of the payload,
      are likely to fit within the buffer.  A server can thus fully
      interpret a request and return a 4.13 (Request Entity Too Large;
      see Section 5.9.2.9) Response Code if the payload was truncated.
      A client sending an idempotent request and receiving a response
      larger than would fit in the buffer can repeat the request with a
      suitable value for the Block Option [BLOCK].

4.7.  Congestion Control

   Basic congestion control for CoAP is provided by the exponential
   back-off mechanism in Section 4.2.

   In order not to cause congestion, clients (including proxies) MUST
   strictly limit the number of simultaneous outstanding interactions
   that they maintain to a given server (including proxies) to NSTART.
   An outstanding interaction is either a CON for which an ACK has not
   yet been received but is still expected (message layer) or a request
   for which neither a response nor an Acknowledgment message has yet
   been received but is still expected (which may both occur at the same
   time, counting as one outstanding interaction).  The default value of
   NSTART for this specification is 1.

   Further congestion control optimizations and considerations are
   expected in the future, may for example provide automatic
   initialization of the CoAP transmission parameters defined in
   Section 4.8, and thus may allow a value for NSTART greater than one.

   After EXCHANGE_LIFETIME, a client stops expecting a response to a
   Confirmable request for which no acknowledgment message was received.



Shelby, et al.               Standards Track                   [Page 26]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   The specific algorithm by which a client stops to "expect" a response
   to a Confirmable request that was acknowledged, or to a Non-
   confirmable request, is not defined.  Unless this is modified by
   additional congestion control optimizations, it MUST be chosen in
   such a way that an endpoint does not exceed an average data rate of
   PROBING_RATE in sending to another endpoint that does not respond.

   Note:  CoAP places the onus of congestion control mostly on the
      clients.  However, clients may malfunction or actually be
      attackers, e.g., to perform amplification attacks (Section 11.3).
      To limit the damage (to the network and to its own energy
      resources), a server SHOULD implement some rate limiting for its
      response transmission based on reasonable assumptions about
      application requirements.  This is most helpful if the rate limit
      can be made effective for the misbehaving endpoints, only.

4.8.  Transmission Parameters

   Message transmission is controlled by the following parameters:

                   +-------------------+---------------+
                   | name              | default value |
                   +-------------------+---------------+
                   | ACK_TIMEOUT       | 2 seconds     |
                   | ACK_RANDOM_FACTOR | 1.5           |
                   | MAX_RETRANSMIT    | 4             |
                   | NSTART            | 1             |
                   | DEFAULT_LEISURE   | 5 seconds     |
                   | PROBING_RATE      | 1 byte/second |
                   +-------------------+---------------+

                     Table 2: CoAP Protocol Parameters

4.8.1.  Changing the Parameters

   The values for ACK_TIMEOUT, ACK_RANDOM_FACTOR, MAX_RETRANSMIT,
   NSTART, DEFAULT_LEISURE (Section 8.2), and PROBING_RATE may be
   configured to values specific to the application environment
   (including dynamically adjusted values); however, the configuration
   method is out of scope of this document.  It is RECOMMENDED that an
   application environment use consistent values for these parameters;
   the specific effects of operating with inconsistent values in an
   application environment are outside the scope of the present
   specification.

   The transmission parameters have been chosen to achieve a behavior in
   the presence of congestion that is safe in the Internet.  If a
   configuration desires to use different values, the onus is on the



Shelby, et al.               Standards Track                   [Page 27]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   configuration to ensure these congestion control properties are not
   violated.  In particular, a decrease of ACK_TIMEOUT below 1 second
   would violate the guidelines of [RFC5405].  ([RTO-CONSIDER] provides
   some additional background.)  CoAP was designed to enable
   implementations that do not maintain round-trip-time (RTT)
   measurements.  However, where it is desired to decrease the
   ACK_TIMEOUT significantly or increase NSTART, this can only be done
   safely when maintaining such measurements.  Configurations MUST NOT
   decrease ACK_TIMEOUT or increase NSTART without using mechanisms that
   ensure congestion control safety, either defined in the configuration
   or in future standards documents.

   ACK_RANDOM_FACTOR MUST NOT be decreased below 1.0, and it SHOULD have
   a value that is sufficiently different from 1.0 to provide some
   protection from synchronization effects.

   MAX_RETRANSMIT can be freely adjusted, but a value that is too small
   will reduce the probability that a Confirmable message is actually
   received, while a larger value than given here will require further
   adjustments in the time values (see Section 4.8.2).

   If the choice of transmission parameters leads to an increase of
   derived time values (see Section 4.8.2), the configuration mechanism
   MUST ensure the adjusted value is also available to all the endpoints
   with which these adjusted values are to be used to communicate.

4.8.2.  Time Values Derived from Transmission Parameters

   The combination of ACK_TIMEOUT, ACK_RANDOM_FACTOR, and MAX_RETRANSMIT
   influences the timing of retransmissions, which in turn influences
   how long certain information items need to be kept by an
   implementation.  To be able to unambiguously reference these derived
   time values, we give them names as follows:

   o  MAX_TRANSMIT_SPAN is the maximum time from the first transmission
      of a Confirmable message to its last retransmission.  For the
      default transmission parameters, the value is (2+4+8+16)*1.5 = 45
      seconds, or more generally:

         ACK_TIMEOUT * ((2 ** MAX_RETRANSMIT) - 1) * ACK_RANDOM_FACTOR











Shelby, et al.               Standards Track                   [Page 28]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   o  MAX_TRANSMIT_WAIT is the maximum time from the first transmission
      of a Confirmable message to the time when the sender gives up on
      receiving an acknowledgement or reset.  For the default
      transmission parameters, the value is (2+4+8+16+32)*1.5 = 93
      seconds, or more generally:

         ACK_TIMEOUT * ((2 ** (MAX_RETRANSMIT + 1)) - 1) *
         ACK_RANDOM_FACTOR

   In addition, some assumptions need to be made on the characteristics
   of the network and the nodes.

   o  MAX_LATENCY is the maximum time a datagram is expected to take
      from the start of its transmission to the completion of its
      reception.  This constant is related to the MSL (Maximum Segment
      Lifetime) of [RFC0793], which is "arbitrarily defined to be 2
      minutes" ([RFC0793] glossary, page 81).  Note that this is not
      necessarily smaller than MAX_TRANSMIT_WAIT, as MAX_LATENCY is not
      intended to describe a situation when the protocol works well, but
      the worst-case situation against which the protocol has to guard.
      We, also arbitrarily, define MAX_LATENCY to be 100 seconds.  Apart
      from being reasonably realistic for the bulk of configurations as
      well as close to the historic choice for TCP, this value also
      allows Message ID lifetime timers to be represented in 8 bits
      (when measured in seconds).  In these calculations, there is no
      assumption that the direction of the transmission is irrelevant
      (i.e., that the network is symmetric); there is just the
      assumption that the same value can reasonably be used as a maximum
      value for both directions.  If that is not the case, the following
      calculations become only slightly more complex.

   o  PROCESSING_DELAY is the time a node takes to turn around a
      Confirmable message into an acknowledgement.  We assume the node
      will attempt to send an ACK before having the sender time out, so
      as a conservative assumption we set it equal to ACK_TIMEOUT.

   o  MAX_RTT is the maximum round-trip time, or:

         (2 * MAX_LATENCY) + PROCESSING_DELAY

   From these values, we can derive the following values relevant to the
   protocol operation:

   o  EXCHANGE_LIFETIME is the time from starting to send a Confirmable
      message to the time when an acknowledgement is no longer expected,
      i.e., message-layer information about the message exchange can be
      purged.  EXCHANGE_LIFETIME includes a MAX_TRANSMIT_SPAN, a
      MAX_LATENCY forward, PROCESSING_DELAY, and a MAX_LATENCY for the



Shelby, et al.               Standards Track                   [Page 29]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


      way back.  Note that there is no need to consider
      MAX_TRANSMIT_WAIT if the configuration is chosen such that the
      last waiting period (ACK_TIMEOUT * (2 ** MAX_RETRANSMIT) or the
      difference between MAX_TRANSMIT_SPAN and MAX_TRANSMIT_WAIT) is
      less than MAX_LATENCY -- which is a likely choice, as MAX_LATENCY
      is a worst-case value unlikely to be met in the real world.  In
      this case, EXCHANGE_LIFETIME simplifies to:

         MAX_TRANSMIT_SPAN + (2 * MAX_LATENCY) + PROCESSING_DELAY

      or 247 seconds with the default transmission parameters.

   o  NON_LIFETIME is the time from sending a Non-confirmable message to
      the time its Message ID can be safely reused.  If multiple
      transmission of a NON message is not used, its value is
      MAX_LATENCY, or 100 seconds.  However, a CoAP sender might send a
      NON message multiple times, in particular for multicast
      applications.  While the period of reuse is not bounded by the
      specification, an expectation of reliable detection of duplication
      at the receiver is on the timescales of MAX_TRANSMIT_SPAN.
      Therefore, for this purpose, it is safer to use the value:

         MAX_TRANSMIT_SPAN + MAX_LATENCY

      or 145 seconds with the default transmission parameters; however,
      an implementation that just wants to use a single timeout value
      for retiring Message IDs can safely use the larger value for
      EXCHANGE_LIFETIME.

   Table 3 lists the derived parameters introduced in this subsection
   with their default values.

                   +-------------------+---------------+
                   | name              | default value |
                   +-------------------+---------------+
                   | MAX_TRANSMIT_SPAN |          45 s |
                   | MAX_TRANSMIT_WAIT |          93 s |
                   | MAX_LATENCY       |         100 s |
                   | PROCESSING_DELAY  |           2 s |
                   | MAX_RTT           |         202 s |
                   | EXCHANGE_LIFETIME |         247 s |
                   | NON_LIFETIME      |         145 s |
                   +-------------------+---------------+

                   Table 3: Derived Protocol Parameters






Shelby, et al.               Standards Track                   [Page 30]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


5.  Request/Response Semantics

   CoAP operates under a similar request/response model as HTTP: a CoAP
   endpoint in the role of a "client" sends one or more CoAP requests to
   a "server", which services the requests by sending CoAP responses.
   Unlike HTTP, requests and responses are not sent over a previously
   established connection but are exchanged asynchronously over CoAP
   messages.

5.1.  Requests

   A CoAP request consists of the method to be applied to the resource,
   the identifier of the resource, a payload and Internet media type (if
   any), and optional metadata about the request.

   CoAP supports the basic methods of GET, POST, PUT, and DELETE, which
   are easily mapped to HTTP.  They have the same properties of safe
   (only retrieval) and idempotent (you can invoke it multiple times
   with the same effects) as HTTP (see Section 9.1 of [RFC2616]).  The
   GET method is safe; therefore, it MUST NOT take any other action on a
   resource other than retrieval.  The GET, PUT, and DELETE methods MUST
   be performed in such a way that they are idempotent.  POST is not
   idempotent, because its effect is determined by the origin server and
   dependent on the target resource; it usually results in a new
   resource being created or the target resource being updated.

   A request is initiated by setting the Code field in the CoAP header
   of a Confirmable or a Non-confirmable message to a Method Code and
   including request information.

   The methods used in requests are described in detail in Section 5.8.

5.2.  Responses

   After receiving and interpreting a request, a server responds with a
   CoAP response that is matched to the request by means of a client-
   generated token (Section 5.3); note that this is different from the
   Message ID that matches a Confirmable message to its Acknowledgement.

   A response is identified by the Code field in the CoAP header being
   set to a Response Code.  Similar to the HTTP Status Code, the CoAP
   Response Code indicates the result of the attempt to understand and
   satisfy the request.  These codes are fully defined in Section 5.9.
   The Response Code numbers to be set in the Code field of the CoAP
   header are maintained in the CoAP Response Code Registry
   (Section 12.1.2).





Shelby, et al.               Standards Track                   [Page 31]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


                              0
                              0 1 2 3 4 5 6 7
                             +-+-+-+-+-+-+-+-+
                             |class|  detail |
                             +-+-+-+-+-+-+-+-+

                  Figure 9: Structure of a Response Code

   The upper three bits of the 8-bit Response Code number define the
   class of response.  The lower five bits do not have any
   categorization role; they give additional detail to the overall class
   (Figure 9).

   As a human-readable notation for specifications and protocol
   diagnostics, CoAP code numbers including the Response Code are
   documented in the format "c.dd", where "c" is the class in decimal,
   and "dd" is the detail as a two-digit decimal.  For example,
   "Forbidden" is written as 4.03 -- indicating an 8-bit code value of
   hexadecimal 0x83 (4*0x20+3) or decimal 131 (4*32+3).

   There are 3 classes of Response Codes:

   2 - Success:  The request was successfully received, understood, and
      accepted.

   4 - Client Error:  The request contains bad syntax or cannot be
      fulfilled.

   5 - Server Error:  The server failed to fulfill an apparently valid
      request.

   The Response Codes are designed to be extensible: Response Codes in
   the Client Error or Server Error class that are unrecognized by an
   endpoint are treated as being equivalent to the generic Response Code
   of that class (4.00 and 5.00, respectively).  However, there is no
   generic Response Code indicating success, so a Response Code in the
   Success class that is unrecognized by an endpoint can only be used to
   determine that the request was successful without any further
   details.

   The possible Response Codes are described in detail in Section 5.9.

   Responses can be sent in multiple ways, which are defined in the
   following subsections.







Shelby, et al.               Standards Track                   [Page 32]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


5.2.1.  Piggybacked

   In the most basic case, the response is carried directly in the
   Acknowledgement message that acknowledges the request (which requires
   that the request was carried in a Confirmable message).  This is
   called a "Piggybacked Response".

   The response is returned in the Acknowledgement message, independent
   of whether the response indicates success or failure.  In effect, the
   response is piggybacked on the Acknowledgement message, and no
   separate message is required to return the response.

   Implementation Note:  The protocol leaves the decision whether to
      piggyback a response or not (i.e., send a separate response) to
      the server.  The client MUST be prepared to receive either.  On
      the quality-of-implementation level, there is a strong expectation
      that servers will implement code to piggyback whenever possible --
      saving resources in the network and both at the client and at the
      server.

5.2.2.  Separate

   It may not be possible to return a piggybacked response in all cases.
   For example, a server might need longer to obtain the representation
   of the resource requested than it can wait to send back the
   Acknowledgement message, without risking the client repeatedly
   retransmitting the request message (see also the discussion of
   PROCESSING_DELAY in Section 4.8.2).  The response to a request
   carried in a Non-confirmable message is always sent separately (as
   there is no Acknowledgement message).

   One way to implement this in a server is to initiate the attempt to
   obtain the resource representation and, while that is in progress,
   time out an acknowledgement timer.  A server may also immediately
   send an acknowledgement if it knows in advance that there will be no
   piggybacked response.  In both cases, the acknowledgement effectively
   is a promise that the request will be acted upon later.

   When the server finally has obtained the resource representation, it
   sends the response.  When it is desired that this message is not
   lost, it is sent as a Confirmable message from the server to the
   client and answered by the client with an Acknowledgement, echoing
   the new Message ID chosen by the server.  (It may also be sent as a
   Non-confirmable message; see Section 5.2.3.)

   When the server chooses to use a separate response, it sends the
   Acknowledgement to the Confirmable request as an Empty message.  Once
   the server sends back an Empty Acknowledgement, it MUST NOT send back



Shelby, et al.               Standards Track                   [Page 33]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   the response in another Acknowledgement, even if the client
   retransmits another identical request.  If a retransmitted request is
   received (perhaps because the original Acknowledgement was delayed),
   another Empty Acknowledgement is sent, and any response MUST be sent
   as a separate response.

   If the server then sends a Confirmable response, the client's
   Acknowledgement to that response MUST also be an Empty message (one
   that carries neither a request nor a response).  The server MUST stop
   retransmitting its response on any matching Acknowledgement (silently
   ignoring any Response Code or payload) or Reset message.

   Implementation Notes:  Note that, as the underlying datagram
      transport may not be sequence-preserving, the Confirmable message
      carrying the response may actually arrive before or after the
      Acknowledgement message for the request; for the purposes of
      terminating the retransmission sequence, this also serves as an
      acknowledgement.  Note also that, while the CoAP protocol itself
      does not make any specific demands here, there is an expectation
      that the response will come within a time frame that is reasonable
      from an application point of view.  As there is no underlying
      transport protocol that could be instructed to run a keep-alive
      mechanism, the requester may want to set up a timeout that is
      unrelated to CoAP's retransmission timers in case the server is
      destroyed or otherwise unable to send the response.

5.2.3.  Non-confirmable

   If the request message is Non-confirmable, then the response SHOULD
   be returned in a Non-confirmable message as well.  However, an
   endpoint MUST be prepared to receive a Non-confirmable response
   (preceded or followed by an Empty Acknowledgement message) in reply
   to a Confirmable request, or a Confirmable response in reply to a
   Non-confirmable request.

5.3.  Request/Response Matching

   Regardless of how a response is sent, it is matched to the request by
   means of a token that is included by the client in the request, along
   with additional address information of the corresponding endpoint.

5.3.1.  Token

   The Token is used to match a response with a request.  The token
   value is a sequence of 0 to 8 bytes.  (Note that every message
   carries a token, even if it is of zero length.)  Every request
   carries a client-generated token that the server MUST echo (without
   modification) in any resulting response.



Shelby, et al.               Standards Track                   [Page 34]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   A token is intended for use as a client-local identifier for
   differentiating between concurrent requests (see Section 5.3); it
   could have been called a "request ID".

   The client SHOULD generate tokens in such a way that tokens currently
   in use for a given source/destination endpoint pair are unique.
   (Note that a client implementation can use the same token for any
   request if it uses a different endpoint each time, e.g., a different
   source port number.)  An empty token value is appropriate e.g., when
   no other tokens are in use to a destination, or when requests are
   made serially per destination and receive piggybacked responses.
   There are, however, multiple possible implementation strategies to
   fulfill this.

   A client sending a request without using Transport Layer Security
   (Section 9) SHOULD use a nontrivial, randomized token to guard
   against spoofing of responses (Section 11.4).  This protective use of
   tokens is the reason they are allowed to be up to 8 bytes in size.
   The actual size of the random component to be used for the Token
   depends on the security requirements of the client and the level of
   threat posed by spoofing of responses.  A client that is connected to
   the general Internet SHOULD use at least 32 bits of randomness,
   keeping in mind that not being directly connected to the Internet is
   not necessarily sufficient protection against spoofing.  (Note that
   the Message ID adds little in protection as it is usually
   sequentially assigned, i.e., guessable, and can be circumvented by
   spoofing a separate response.)  Clients that want to optimize the
   Token length may further want to detect the level of ongoing attacks
   (e.g., by tallying recent Token mismatches in incoming messages) and
   adjust the Token length upwards appropriately.  [RFC4086] discusses
   randomness requirements for security.

   An endpoint receiving a token it did not generate MUST treat the
   token as opaque and make no assumptions about its content or
   structure.

5.3.2.  Request/Response Matching Rules

   The exact rules for matching a response to a request are as follows:

   1.  The source endpoint of the response MUST be the same as the
       destination endpoint of the original request.

   2.  In a piggybacked response, the Message ID of the Confirmable
       request and the Acknowledgement MUST match, and the tokens of the
       response and original request MUST match.  In a separate
       response, just the tokens of the response and original request
       MUST match.



Shelby, et al.               Standards Track                   [Page 35]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   In case a message carrying a response is unexpected (the client is
   not waiting for a response from the identified endpoint, at the
   endpoint addressed, and/or with the given token), the response is
   rejected (Sections 4.2 and 4.3).

   Implementation Note:  A client that receives a response in a CON
      message may want to clean up the message state right after sending
      the ACK.  If that ACK is lost and the server retransmits the CON,
      the client may no longer have any state to which to correlate this
      response, making the retransmission an unexpected message; the
      client will likely send a Reset message so it does not receive any
      more retransmissions.  This behavior is normal and not an
      indication of an error.  (Clients that are not aggressively
      optimized in their state memory usage will still have message
      state that will identify the second CON as a retransmission.
      Clients that actually expect more messages from the server
      [OBSERVE] will have to keep state in any case.)

5.4.  Options

   Both requests and responses may include a list of one or more
   options.  For example, the URI in a request is transported in several
   options, and metadata that would be carried in an HTTP header in HTTP
   is supplied as options as well.

   CoAP defines a single set of options that are used in both requests
   and responses:

   o  Content-Format

   o  ETag

   o  Location-Path

   o  Location-Query

   o  Max-Age

   o  Proxy-Uri

   o  Proxy-Scheme

   o  Uri-Host

   o  Uri-Path

   o  Uri-Port




Shelby, et al.               Standards Track                   [Page 36]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   o  Uri-Query

   o  Accept

   o  If-Match

   o  If-None-Match

   o  Size1

   The semantics of these options along with their properties are
   defined in detail in Section 5.10.

   Not all options are defined for use with all methods and Response
   Codes.  The possible options for methods and Response Codes are
   defined in Sections 5.8 and 5.9, respectively.  In case an option is
   not defined for a Method or Response Code, it MUST NOT be included by
   a sender and MUST be treated like an unrecognized option by a
   recipient.

5.4.1.  Critical/Elective

   Options fall into one of two classes: "critical" or "elective".  The
   difference between these is how an option unrecognized by an endpoint
   is handled:

   o  Upon reception, unrecognized options of class "elective" MUST be
      silently ignored.

   o  Unrecognized options of class "critical" that occur in a
      Confirmable request MUST cause the return of a 4.02 (Bad Option)
      response.  This response SHOULD include a diagnostic payload
      describing the unrecognized option(s) (see Section 5.5.2).

   o  Unrecognized options of class "critical" that occur in a
      Confirmable response, or piggybacked in an Acknowledgement, MUST
      cause the response to be rejected (Section 4.2).

   o  Unrecognized options of class "critical" that occur in a Non-
      confirmable message MUST cause the message to be rejected
      (Section 4.3).

   Note that, whether critical or elective, an option is never
   "mandatory" (it is always optional): these rules are defined in order
   to enable implementations to stop processing options they do not
   understand or implement.





Shelby, et al.               Standards Track                   [Page 37]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   Critical/elective rules apply to non-proxying endpoints.  A proxy
   processes options based on Unsafe/Safe-to-Forward classes as defined
   in Section 5.7.

5.4.2.  Proxy Unsafe or Safe-to-Forward and NoCacheKey

   In addition to an option being marked as critical or elective,
   options are also classified based on how a proxy is to deal with the
   option if it does not recognize it.  For this purpose, an option can
   either be considered Unsafe to forward (UnSafe is set) or Safe-to-
   Forward (UnSafe is clear).

   In addition, for an option that is marked Safe-to-Forward, the option
   number indicates whether or not it is intended to be part of the
   Cache-Key (Section 5.6) in a request.  If some of the NoCacheKey bits
   are 0, it is; if all NoCacheKey bits are 1, it is not (see
   Section 5.4.6).

   Note:  The Cache-Key indication is relevant only for proxies that do
      not implement the given option as a request option and instead
      rely on the Unsafe/Safe-to-Forward indication only.  For example,
      for ETag, actually using the request option as a part of the
      Cache-Key is grossly inefficient, but it is the best thing one can
      do if ETag is not implemented by a proxy, as the response is going
      to differ based on the presence of the request option.  A more
      useful proxy that does implement the ETag request option is not
      using ETag as a part of the Cache-Key.

      NoCacheKey is indicated in three bits so that only one out of
      eight codepoints is qualified as NoCacheKey, leaving seven out of
      eight codepoints for what appears to be the more likely case.

   Proxy behavior with regard to these classes is defined in
   Section 5.7.

5.4.3.  Length

   Option values are defined to have a specific length, often in the
   form of an upper and lower bound.  If the length of an option value
   in a request is outside the defined range, that option MUST be
   treated like an unrecognized option (see Section 5.4.1).

5.4.4.  Default Values

   Options may be defined to have a default value.  If the value of an
   option is intended to be this default value, the option SHOULD NOT be
   included in the message.  If the option is not present, the default
   value MUST be assumed.



Shelby, et al.               Standards Track                   [Page 38]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   Where a critical option has a default value, this is chosen in such a
   way that the absence of the option in a message can be processed
   properly both by implementations unaware of the critical option and
   by implementations that interpret this absence as the presence of the
   default value for the option.

5.4.5.  Repeatable Options

   The definition of some options specifies that those options are
   repeatable.  An option that is repeatable MAY be included one or more
   times in a message.  An option that is not repeatable MUST NOT be
   included more than once in a message.

   If a message includes an option with more occurrences than the option
   is defined for, each supernumerary option occurrence that appears
   subsequently in the message MUST be treated like an unrecognized
   option (see Section 5.4.1).

5.4.6.  Option Numbers

   An Option is identified by an option number, which also provides some
   additional semantics information, e.g., odd numbers indicate a
   critical option, while even numbers indicate an elective option.
   Note that this is not just a convention, it is a feature of the
   protocol: Whether an option is elective or critical is entirely
   determined by whether its option number is even or odd.

   More generally speaking, an Option number is constructed with a bit
   mask to indicate if an option is Critical or Elective, Unsafe or
   Safe-to-Forward, and, in the case of Safe-to-Forward, to provide a
   Cache-Key indication as shown by the following figure.  In the
   following text, the bit mask is expressed as a single byte that is
   applied to the least significant byte of the option number in
   unsigned integer representation.  When bit 7 (the least significant
   bit) is 1, an option is Critical (and likewise Elective when 0).
   When bit 6 is 1, an option is Unsafe (and likewise Safe-to-Forward
   when 0).  When bit 6 is 0, i.e., the option is not Unsafe, it is not
   a Cache-Key (NoCacheKey) if and only if bits 3-5 are all set to 1;
   all other bit combinations mean that it indeed is a Cache-Key.  These
   classes of options are explained in the next sections.

                       0   1   2   3   4   5   6   7
                     +---+---+---+---+---+---+---+---+
                     |           | NoCacheKey| U | C |
                     +---+---+---+---+---+---+---+---+

          Figure 10: Option Number Mask (Least Significant Byte)




Shelby, et al.               Standards Track                   [Page 39]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   An endpoint may use an equivalent of the C code in Figure 11 to
   derive the characteristics of an option number "onum".

   Critical = (onum & 1);
   UnSafe = (onum & 2);
   NoCacheKey = ((onum & 0x1e) == 0x1c);

       Figure 11: Determining Characteristics from an Option Number

   The option numbers for the options defined in this document are
   listed in the "CoAP Option Numbers" registry (Section 12.2).

5.5.  Payloads and Representations

   Both requests and responses may include a payload, depending on the
   Method or Response Code, respectively.  If a Method or Response Code
   is not defined to have a payload, then a sender MUST NOT include one,
   and a recipient MUST ignore it.

5.5.1.  Representation

   The payload of requests or of responses indicating success is
   typically a representation of a resource ("resource representation")
   or the result of the requested action ("action result").  Its format
   is specified by the Internet media type and content coding given by
   the Content-Format Option.  In the absence of this option, no default
   value is assumed, and the format will need to be inferred by the
   application (e.g., from the application context).  Payload "sniffing"
   SHOULD only be attempted if no content type is given.

   Implementation Note:  On a quality-of-implementation level, there is
      a strong expectation that a Content-Format indication will be
      provided with resource representations whenever possible.  This is
      not a "SHOULD" level requirement solely because it is not a
      protocol requirement, and it also would be difficult to outline
      exactly in what cases this expectation can be violated.

   For responses indicating a client or server error, the payload is
   considered a representation of the result of the requested action
   only if a Content-Format Option is given.  In the absence of this
   option, the payload is a Diagnostic Payload (Section 5.5.2).










Shelby, et al.               Standards Track                   [Page 40]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


5.5.2.  Diagnostic Payload

   If no Content-Format option is given, the payload of responses
   indicating a client or server error is a brief human-readable
   diagnostic message, explaining the error situation.  This diagnostic
   message MUST be encoded using UTF-8 [RFC3629], more specifically
   using Net-Unicode form [RFC5198].

   The message is similar to the Reason-Phrase on an HTTP status line.
   It is not intended for end users but for software engineers that
   during debugging need to interpret it in the context of the present,
   English-language specification; therefore, no mechanism for language
   tagging is needed or provided.  In contrast to what is usual in HTTP,
   the payload SHOULD be empty if there is no additional information
   beyond the Response Code.

5.5.3.  Selected Representation

   Not all responses carry a payload that provides a representation of
   the resource addressed by the request.  It is, however, sometimes
   useful to be able to refer to such a representation in relation to a
   response, independent of whether it actually was enclosed.

   We use the term "selected representation" to refer to the current
   representation of a target resource that would have been selected in
   a successful response if the corresponding request had used the
   method GET and excluded any conditional request options
   (Section 5.10.8).

   Certain response options provide metadata about the selected
   representation, which might differ from the representation included
   in the message for responses to some state-changing methods.  Of the
   response options defined in this specification, only the ETag
   response option (Section 5.10.6) is defined as metadata about the
   selected representation.

5.5.4.  Content Negotiation

   A server may be able to supply a representation for a resource in one
   of multiple representation formats.  Without further information from
   the client, it will provide the representation in the format it
   prefers.

   By using the Accept Option (Section 5.10.4) in a request, the client
   can indicate which content-format it prefers to receive.






Shelby, et al.               Standards Track                   [Page 41]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


5.6.  Caching

   CoAP endpoints MAY cache responses in order to reduce the response
   time and network bandwidth consumption on future, equivalent
   requests.

   The goal of caching in CoAP is to reuse a prior response message to
   satisfy a current request.  In some cases, a stored response can be
   reused without the need for a network request, reducing latency and
   network round-trips; a "freshness" mechanism is used for this purpose
   (see Section 5.6.1).  Even when a new request is required, it is
   often possible to reuse the payload of a prior response to satisfy
   the request, thereby reducing network bandwidth usage; a "validation"
   mechanism is used for this purpose (see Section 5.6.2).

   Unlike HTTP, the cacheability of CoAP responses does not depend on
   the request method, but it depends on the Response Code.  The
   cacheability of each Response Code is defined along the Response Code
   definitions in Section 5.9.  Response Codes that indicate success and
   are unrecognized by an endpoint MUST NOT be cached.

   For a presented request, a CoAP endpoint MUST NOT use a stored
   response, unless:

   o  the presented request method and that used to obtain the stored
      response match,

   o  all options match between those in the presented request and those
      of the request used to obtain the stored response (which includes
      the request URI), except that there is no need for a match of any
      request options marked as NoCacheKey (Section 5.4) or recognized
      by the Cache and fully interpreted with respect to its specified
      cache behavior (such as the ETag request option described in
      Section 5.10.6; see also Section 5.4.2), and

   o  the stored response is either fresh or successfully validated as
      defined below.

   The set of request options that is used for matching the cache entry
   is also collectively referred to as the "Cache-Key".  For URI schemes
   other than coap and coaps, matching of those options that constitute
   the request URI may be performed under rules specific to the URI
   scheme.








Shelby, et al.               Standards Track                   [Page 42]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


5.6.1.  Freshness Model

   When a response is "fresh" in the cache, it can be used to satisfy
   subsequent requests without contacting the origin server, thereby
   improving efficiency.

   The mechanism for determining freshness is for an origin server to
   provide an explicit expiration time in the future, using the Max-Age
   Option (see Section 5.10.5).  The Max-Age Option indicates that the
   response is to be considered not fresh after its age is greater than
   the specified number of seconds.

   The Max-Age Option defaults to a value of 60.  Thus, if it is not
   present in a cacheable response, then the response is considered not
   fresh after its age is greater than 60 seconds.  If an origin server
   wishes to prevent caching, it MUST explicitly include a Max-Age
   Option with a value of zero seconds.

   If a client has a fresh stored response and makes a new request
   matching the request for that stored response, the new response
   invalidates the old response.

5.6.2.  Validation Model

   When an endpoint has one or more stored responses for a GET request,
   but cannot use any of them (e.g., because they are not fresh), it can
   use the ETag Option (Section 5.10.6) in the GET request to give the
   origin server an opportunity both to select a stored response to be
   used, and to update its freshness.  This process is known as
   "validating" or "revalidating" the stored response.

   When sending such a request, the endpoint SHOULD add an ETag Option
   specifying the entity-tag of each stored response that is applicable.

   A 2.03 (Valid) response indicates the stored response identified by
   the entity-tag given in the response's ETag Option can be reused
   after updating it as described in Section 5.9.1.3.

   Any other Response Code indicates that none of the stored responses
   nominated in the request is suitable.  Instead, the response SHOULD
   be used to satisfy the request and MAY replace the stored response.










Shelby, et al.               Standards Track                   [Page 43]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


5.7.  Proxying

   A proxy is a CoAP endpoint that can be tasked by CoAP clients to
   perform requests on their behalf.  This may be useful, for example,
   when the request could otherwise not be made, or to service the
   response from a cache in order to reduce response time and network
   bandwidth or energy consumption.

   In an overall architecture for a Constrained RESTful Environment,
   proxies can serve quite different purposes.  Proxies can be
   explicitly selected by clients, a role that we term "forward-proxy".
   Proxies can also be inserted to stand in for origin servers, a role
   that we term "reverse-proxy".  Orthogonal to this distinction, a
   proxy can map from a CoAP request to a CoAP request (CoAP-to-CoAP
   proxy) or translate from or to a different protocol ("cross-proxy").
   Full definitions of these terms are provided in Section 1.2.

   Notes:  The terminology in this specification has been selected to be
      culturally compatible with the terminology used in the wider web
      application environments, without necessarily matching it in every
      detail (which may not even be relevant to Constrained RESTful
      Environments).  Not too much semantics should be ascribed to the
      components of the terms (such as "forward", "reverse", or
      "cross").

      HTTP proxies, besides acting as HTTP proxies, often offer a
      transport-protocol proxying function ("CONNECT") to enable end-to-
      end transport layer security through the proxy.  No such function
      is defined for CoAP-to-CoAP proxies in this specification, as
      forwarding of UDP packets is unlikely to be of much value in
      Constrained RESTful Environments.  See also Section 10.2.7 for the
      cross-proxy case.

   When a client uses a proxy to make a request that will use a secure
   URI scheme (e.g., "coaps" or "https"), the request towards the proxy
   SHOULD be sent using DTLS except where equivalent lower-layer
   security is used for the leg between the client and the proxy.

5.7.1.  Proxy Operation

   A proxy generally needs a way to determine potential request
   parameters for a request it places to a destination, based on the
   request it received from its client.  This way is fully specified for
   a forward-proxy but may depend on the specific configuration for a
   reverse-proxy.  In particular, the client of a reverse-proxy
   generally does not indicate a locator for the destination,





Shelby, et al.               Standards Track                   [Page 44]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   necessitating some form of namespace translation in the reverse-
   proxy.  However, some aspects of the operation of proxies are common
   to all its forms.

   If a proxy does not employ a cache, then it simply forwards the
   translated request to the determined destination.  Otherwise, if it
   does employ a cache but does not have a stored response that matches
   the translated request and is considered fresh, then it needs to
   refresh its cache according to Section 5.6.  For options in the
   request that the proxy recognizes, it knows whether the option is
   intended to act as part of the key used in looking up the cached
   value or not.  For example, since requests for different Uri-Path
   values address different resources, Uri-Path values are always part
   of the Cache-Key, while, e.g., Token values are never part of the
   Cache-Key.  For options that the proxy does not recognize but that
   are marked Safe-to-Forward in the option number, the option also
   indicates whether it is to be included in the Cache-Key (NoCacheKey
   is not all set) or not (NoCacheKey is all set).  (Options that are
   unrecognized and marked Unsafe lead to 4.02 Bad Option.)

   If the request to the destination times out, then a 5.04 (Gateway
   Timeout) response MUST be returned.  If the request to the
   destination returns a response that cannot be processed by the proxy
   (e.g, due to unrecognized critical options or message format errors),
   then a 5.02 (Bad Gateway) response MUST be returned.  Otherwise, the
   proxy returns the response to the client.

   If a response is generated out of a cache, the generated (or implied)
   Max-Age Option MUST NOT extend the max-age originally set by the
   server, considering the time the resource representation spent in the
   cache.  For example, the Max-Age Option could be adjusted by the
   proxy for each response using the formula:

      proxy-max-age = original-max-age - cache-age

   For example, if a request is made to a proxied resource that was
   refreshed 20 seconds ago and had an original Max-Age of 60 seconds,
   then that resource's proxied max-age is now 40 seconds.  Considering
   potential network delays on the way from the origin server, a proxy
   should be conservative in the max-age values offered.

   All options present in a proxy request MUST be processed at the
   proxy.  Unsafe options in a request that are not recognized by the
   proxy MUST lead to a 4.02 (Bad Option) response being returned by the
   proxy.  A CoAP-to-CoAP proxy MUST forward to the origin server all
   Safe-to-Forward options that it does not recognize.  Similarly,





Shelby, et al.               Standards Track                   [Page 45]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   Unsafe options in a response that are not recognized by the CoAP-to-
   CoAP proxy server MUST lead to a 5.02 (Bad Gateway) response.  Again,
   Safe-to-Forward options that are not recognized MUST be forwarded.

   Additional considerations for cross-protocol proxying between CoAP
   and HTTP are discussed in Section 10.

5.7.2.  Forward-Proxies

   CoAP distinguishes between requests made (as if) to an origin server
   and requests made through a forward-proxy.  CoAP requests to a
   forward-proxy are made as normal Confirmable or Non-confirmable
   requests to the forward-proxy endpoint, but they specify the request
   URI in a different way: The request URI in a proxy request is
   specified as a string in the Proxy-Uri Option (see Section 5.10.2),
   while the request URI in a request to an origin server is split into
   the Uri-Host, Uri-Port, Uri-Path, and Uri-Query Options (see
   Section 5.10.1).  Alternatively, the URI in a proxy request can be
   assembled from a Proxy-Scheme option and the split options mentioned.

   When a proxy request is made to an endpoint and the endpoint is
   unwilling or unable to act as proxy for the request URI, it MUST
   return a 5.05 (Proxying Not Supported) response.  If the authority
   (host and port) is recognized as identifying the proxy endpoint
   itself (see Section 5.10.2), then the request MUST be treated as a
   local (non-proxied) request.

   Unless a proxy is configured to forward the proxy request to another
   proxy, it MUST translate the request as follows: the scheme of the
   request URI defines the outgoing protocol and its details (e.g., CoAP
   is used over UDP for the "coap" scheme and over DTLS for the "coaps"
   scheme.)  For a CoAP-to-CoAP proxy, the origin server's IP address
   and port are determined by the authority component of the request
   URI, and the request URI is decoded and split into the Uri-Host, Uri-
   Port, Uri-Path and Uri-Query Options.  This consumes the Proxy-Uri or
   Proxy-Scheme option, which is therefore not forwarded to the origin
   server.

5.7.3.  Reverse-Proxies

   Reverse-proxies do not make use of the Proxy-Uri or Proxy-Scheme
   options but need to determine the destination (next hop) of a request
   from information in the request and information in their
   configuration.  For example, a reverse-proxy might offer various
   resources as if they were its own resources, after having learned of
   their existence through resource discovery.  The reverse-proxy is
   free to build a namespace for the URIs that identify these resources.
   A reverse-proxy may also build a namespace that gives the client more



Shelby, et al.               Standards Track                   [Page 46]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   control over where the request goes, e.g., by embedding host
   identifiers and port numbers into the URI path of the resources
   offered.

   In processing the response, a reverse-proxy has to be careful that
   ETag option values from different sources are not mixed up on one
   resource offered to its clients.  In many cases, the ETag can be
   forwarded unchanged.  If the mapping from a resource offered by the
   reverse-proxy to resources offered by its various origin servers is
   not unique, the reverse-proxy may need to generate a new ETag, making
   sure the semantics of this option are properly preserved.

5.8.  Method Definitions

   In this section, each method is defined along with its behavior.  A
   request with an unrecognized or unsupported Method Code MUST generate
   a 4.05 (Method Not Allowed) piggybacked response.

5.8.1.  GET

   The GET method retrieves a representation for the information that
   currently corresponds to the resource identified by the request URI.
   If the request includes an Accept Option, that indicates the
   preferred content-format of a response.  If the request includes an
   ETag Option, the GET method requests that ETag be validated and that
   the representation be transferred only if validation failed.  Upon
   success, a 2.05 (Content) or 2.03 (Valid) Response Code SHOULD be
   present in the response.

   The GET method is safe and idempotent.

5.8.2.  POST

   The POST method requests that the representation enclosed in the
   request be processed.  The actual function performed by the POST
   method is determined by the origin server and dependent on the target
   resource.  It usually results in a new resource being created or the
   target resource being updated.

   If a resource has been created on the server, the response returned
   by the server SHOULD have a 2.01 (Created) Response Code and SHOULD
   include the URI of the new resource in a sequence of one or more
   Location-Path and/or Location-Query Options (Section 5.10.7).  If the
   POST succeeds but does not result in a new resource being created on
   the server, the response SHOULD have a 2.04 (Changed) Response Code.
   If the POST succeeds and results in the target resource being
   deleted, the response SHOULD have a 2.02 (Deleted) Response Code.
   POST is neither safe nor idempotent.



Shelby, et al.               Standards Track                   [Page 47]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


5.8.3.  PUT

   The PUT method requests that the resource identified by the request
   URI be updated or created with the enclosed representation.  The
   representation format is specified by the media type and content
   coding given in the Content-Format Option, if provided.

   If a resource exists at the request URI, the enclosed representation
   SHOULD be considered a modified version of that resource, and a 2.04
   (Changed) Response Code SHOULD be returned.  If no resource exists,
   then the server MAY create a new resource with that URI, resulting in
   a 2.01 (Created) Response Code.  If the resource could not be created
   or modified, then an appropriate error Response Code SHOULD be sent.

   Further restrictions to a PUT can be made by including the If-Match
   (see Section 5.10.8.1) or If-None-Match (see Section 5.10.8.2)
   options in the request.

   PUT is not safe but is idempotent.

5.8.4.  DELETE

   The DELETE method requests that the resource identified by the
   request URI be deleted.  A 2.02 (Deleted) Response Code SHOULD be
   used on success or in case the resource did not exist before the
   request.

   DELETE is not safe but is idempotent.

5.9.  Response Code Definitions

   Each Response Code is described below, including any options required
   in the response.  Where appropriate, some of the codes will be
   specified in regards to related Response Codes in HTTP [RFC2616];
   this does not mean that any such relationship modifies the HTTP
   mapping specified in Section 10.

5.9.1.  Success 2.xx

   This class of Response Code indicates that the clients request was
   successfully received, understood, and accepted.

5.9.1.1.  2.01 Created

   Like HTTP 201 "Created", but only used in response to POST and PUT
   requests.  The payload returned with the response, if any, is a
   representation of the action result.




Shelby, et al.               Standards Track                   [Page 48]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   If the response includes one or more Location-Path and/or Location-
   Query Options, the values of these options specify the location at
   which the resource was created.  Otherwise, the resource was created
   at the request URI.  A cache receiving this response MUST mark any
   stored response for the created resource as not fresh.

   This response is not cacheable.

5.9.1.2.  2.02 Deleted

   This Response Code is like HTTP 204 "No Content" but only used in
   response to requests that cause the resource to cease being
   available, such as DELETE and, in certain circumstances, POST.  The
   payload returned with the response, if any, is a representation of
   the action result.

   This response is not cacheable.  However, a cache MUST mark any
   stored response for the deleted resource as not fresh.

5.9.1.3.  2.03 Valid

   This Response Code is related to HTTP 304 "Not Modified" but only
   used to indicate that the response identified by the entity-tag
   identified by the included ETag Option is valid.  Accordingly, the
   response MUST include an ETag Option and MUST NOT include a payload.

   When a cache that recognizes and processes the ETag response option
   receives a 2.03 (Valid) response, it MUST update the stored response
   with the value of the Max-Age Option included in the response
   (explicitly, or implicitly as a default value; see also
   Section 5.6.2).  For each type of Safe-to-Forward option present in
   the response, the (possibly empty) set of options of this type that
   are present in the stored response MUST be replaced with the set of
   options of this type in the response received.  (Unsafe options may
   trigger similar option-specific processing as defined by the option.)

5.9.1.4.  2.04 Changed

   This Response Code is like HTTP 204 "No Content" but only used in
   response to POST and PUT requests.  The payload returned with the
   response, if any, is a representation of the action result.

   This response is not cacheable.  However, a cache MUST mark any
   stored response for the changed resource as not fresh.







Shelby, et al.               Standards Track                   [Page 49]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


5.9.1.5.  2.05 Content

   This Response Code is like HTTP 200 "OK" but only used in response to
   GET requests.

   The payload returned with the response is a representation of the
   target resource.

   This response is cacheable: Caches can use the Max-Age Option to
   determine freshness (see Section 5.6.1) and (if present) the ETag
   Option for validation (see Section 5.6.2).

5.9.2.  Client Error 4.xx

   This class of Response Code is intended for cases in which the client
   seems to have erred.  These Response Codes are applicable to any
   request method.

   The server SHOULD include a diagnostic payload under the conditions
   detailed in Section 5.5.2.

   Responses of this class are cacheable: Caches can use the Max-Age
   Option to determine freshness (see Section 5.6.1).  They cannot be
   validated.

5.9.2.1.  4.00 Bad Request

   This Response Code is Like HTTP 400 "Bad Request".

5.9.2.2.  4.01 Unauthorized

   The client is not authorized to perform the requested action.  The
   client SHOULD NOT repeat the request without first improving its
   authentication status to the server.  Which specific mechanism can be
   used for this is outside this document's scope; see also Section 9.

5.9.2.3.  4.02 Bad Option

   The request could not be understood by the server due to one or more
   unrecognized or malformed options.  The client SHOULD NOT repeat the
   request without modification.

5.9.2.4.  4.03 Forbidden

   This Response Code is like HTTP 403 "Forbidden".






Shelby, et al.               Standards Track                   [Page 50]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


5.9.2.5.  4.04 Not Found

   This Response Code is like HTTP 404 "Not Found".

5.9.2.6.  4.05 Method Not Allowed

   This Response Code is like HTTP 405 "Method Not Allowed" but with no
   parallel to the "Allow" header field.

5.9.2.7.  4.06 Not Acceptable

   This Response Code is like HTTP 406 "Not Acceptable", but with no
   response entity.

5.9.2.8.  4.12 Precondition Failed

   This Response Code is like HTTP 412 "Precondition Failed".

5.9.2.9.  4.13 Request Entity Too Large

   This Response Code is like HTTP 413 "Request Entity Too Large".

   The response SHOULD include a Size1 Option (Section 5.10.9) to
   indicate the maximum size of request entity the server is able and
   willing to handle, unless the server is not in a position to make
   this information available.

5.9.2.10.  4.15 Unsupported Content-Format

   This Response Code is like HTTP 415 "Unsupported Media Type".

5.9.3.  Server Error 5.xx

   This class of Response Code indicates cases in which the server is
   aware that it has erred or is incapable of performing the request.
   These Response Codes are applicable to any request method.

   The server SHOULD include a diagnostic payload under the conditions
   detailed in Section 5.5.2.

   Responses of this class are cacheable: Caches can use the Max-Age
   Option to determine freshness (see Section 5.6.1).  They cannot be
   validated.

5.9.3.1.  5.00 Internal Server Error

   This Response Code is like HTTP 500 "Internal Server Error".




Shelby, et al.               Standards Track                   [Page 51]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


5.9.3.2.  5.01 Not Implemented

   This Response Code is like HTTP 501 "Not Implemented".

5.9.3.3.  5.02 Bad Gateway

   This Response Code is like HTTP 502 "Bad Gateway".

5.9.3.4.  5.03 Service Unavailable

   This Response Code is like HTTP 503 "Service Unavailable" but uses
   the Max-Age Option in place of the "Retry-After" header field to
   indicate the number of seconds after which to retry.

5.9.3.5.  5.04 Gateway Timeout

   This Response Code is like HTTP 504 "Gateway Timeout".

5.9.3.6.  5.05 Proxying Not Supported

   The server is unable or unwilling to act as a forward-proxy for the
   URI specified in the Proxy-Uri Option or using Proxy-Scheme (see
   Section 5.10.2).

5.10.  Option Definitions

   The individual CoAP options are summarized in Table 4 and explained
   in the subsections of this section.

   In this table, the C, U, and N columns indicate the properties
   Critical, UnSafe, and NoCacheKey, respectively.  Since NoCacheKey
   only has a meaning for options that are Safe-to-Forward (not marked
   Unsafe), the column is filled with a dash for UnSafe options.


















Shelby, et al.               Standards Track                   [Page 52]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   +-----+---+---+---+---+----------------+--------+--------+----------+
   | No. | C | U | N | R | Name           | Format | Length | Default  |
   +-----+---+---+---+---+----------------+--------+--------+----------+
   |   1 | x |   |   | x | If-Match       | opaque | 0-8    | (none)   |
   |   3 | x | x | - |   | Uri-Host       | string | 1-255  | (see     |
   |     |   |   |   |   |                |        |        | below)   |
   |   4 |   |   |   | x | ETag           | opaque | 1-8    | (none)   |
   |   5 | x |   |   |   | If-None-Match  | empty  | 0      | (none)   |
   |   7 | x | x | - |   | Uri-Port       | uint   | 0-2    | (see     |
   |     |   |   |   |   |                |        |        | below)   |
   |   8 |   |   |   | x | Location-Path  | string | 0-255  | (none)   |
   |  11 | x | x | - | x | Uri-Path       | string | 0-255  | (none)   |
   |  12 |   |   |   |   | Content-Format | uint   | 0-2    | (none)   |
   |  14 |   | x | - |   | Max-Age        | uint   | 0-4    | 60       |
   |  15 | x | x | - | x | Uri-Query      | string | 0-255  | (none)   |
   |  17 | x |   |   |   | Accept         | uint   | 0-2    | (none)   |
   |  20 |   |   |   | x | Location-Query | string | 0-255  | (none)   |
   |  35 | x | x | - |   | Proxy-Uri      | string | 1-1034 | (none)   |
   |  39 | x | x | - |   | Proxy-Scheme   | string | 1-255  | (none)   |
   |  60 |   |   | x |   | Size1          | uint   | 0-4    | (none)   |
   +-----+---+---+---+---+----------------+--------+--------+----------+

             C=Critical, U=Unsafe, N=NoCacheKey, R=Repeatable

                             Table 4: Options

5.10.1.  Uri-Host, Uri-Port, Uri-Path, and Uri-Query

   The Uri-Host, Uri-Port, Uri-Path, and Uri-Query Options are used to
   specify the target resource of a request to a CoAP origin server.
   The options encode the different components of the request URI in a
   way that no percent-encoding is visible in the option values and that
   the full URI can be reconstructed at any involved endpoint.  The
   syntax of CoAP URIs is defined in Section 6.

   The steps for parsing URIs into options is defined in Section 6.4.
   These steps result in zero or more Uri-Host, Uri-Port, Uri-Path, and
   Uri-Query Options being included in a request, where each option
   holds the following values:

   o  the Uri-Host Option specifies the Internet host of the resource
      being requested,

   o  the Uri-Port Option specifies the transport-layer port number of
      the resource,

   o  each Uri-Path Option specifies one segment of the absolute path to
      the resource, and



Shelby, et al.               Standards Track                   [Page 53]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   o  each Uri-Query Option specifies one argument parameterizing the
      resource.

   Note: Fragments ([RFC3986], Section 3.5) are not part of the request
   URI and thus will not be transmitted in a CoAP request.

   The default value of the Uri-Host Option is the IP literal
   representing the destination IP address of the request message.
   Likewise, the default value of the Uri-Port Option is the destination
   UDP port.  The default values for the Uri-Host and Uri-Port Options
   are sufficient for requests to most servers.  Explicit Uri-Host and
   Uri-Port Options are typically used when an endpoint hosts multiple
   virtual servers.

   The Uri-Path and Uri-Query Option can contain any character sequence.
   No percent-encoding is performed.  The value of a Uri-Path Option
   MUST NOT be "." or ".." (as the request URI must be resolved before
   parsing it into options).

   The steps for constructing the request URI from the options are
   defined in Section 6.5.  Note that an implementation does not
   necessarily have to construct the URI; it can simply look up the
   target resource by examining the individual options.

   Examples can be found in Appendix B.

5.10.2.  Proxy-Uri and Proxy-Scheme

   The Proxy-Uri Option is used to make a request to a forward-proxy
   (see Section 5.7).  The forward-proxy is requested to forward the
   request or service it from a valid cache and return the response.

   The option value is an absolute-URI ([RFC3986], Section 4.3).

   Note that the forward-proxy MAY forward the request on to another
   proxy or directly to the server specified by the absolute-URI.  In
   order to avoid request loops, a proxy MUST be able to recognize all
   of its server names, including any aliases, local variations, and the
   numeric IP addresses.

   An endpoint receiving a request with a Proxy-Uri Option that is
   unable or unwilling to act as a forward-proxy for the request MUST
   cause the return of a 5.05 (Proxying Not Supported) response.

   The Proxy-Uri Option MUST take precedence over any of the Uri-Host,
   Uri-Port, Uri-Path or Uri-Query options (each of which MUST NOT be
   included in a request containing the Proxy-Uri Option).




Shelby, et al.               Standards Track                   [Page 54]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   As a special case to simplify many proxy clients, the absolute-URI
   can be constructed from the Uri-* options.  When a Proxy-Scheme
   Option is present, the absolute-URI is constructed as follows: a CoAP
   URI is constructed from the Uri-* options as defined in Section 6.5.
   In the resulting URI, the initial scheme up to, but not including,
   the following colon is then replaced by the content of the Proxy-
   Scheme Option.  Note that this case is only applicable if the
   components of the desired URI other than the scheme component
   actually can be expressed using Uri-* options; for example, to
   represent a URI with a userinfo component in the authority, only
   Proxy-Uri can be used.

5.10.3.  Content-Format

   The Content-Format Option indicates the representation format of the
   message payload.  The representation format is given as a numeric
   Content-Format identifier that is defined in the "CoAP Content-
   Formats" registry (Section 12.3).  In the absence of the option, no
   default value is assumed, i.e., the representation format of any
   representation message payload is indeterminate (Section 5.5).

5.10.4.  Accept

   The CoAP Accept option can be used to indicate which Content-Format
   is acceptable to the client.  The representation format is given as a
   numeric Content-Format identifier that is defined in the "CoAP
   Content-Formats" registry (Section 12.3).  If no Accept option is
   given, the client does not express a preference (thus no default
   value is assumed).  The client prefers the representation returned by
   the server to be in the Content-Format indicated.  The server returns
   the preferred Content-Format if available.  If the preferred Content-
   Format cannot be returned, then a 4.06 "Not Acceptable" MUST be sent
   as a response, unless another error code takes precedence for this
   response.

5.10.5.  Max-Age

   The Max-Age Option indicates the maximum time a response may be
   cached before it is considered not fresh (see Section 5.6.1).

   The option value is an integer number of seconds between 0 and
   2**32-1 inclusive (about 136.1 years).  A default value of 60 seconds
   is assumed in the absence of the option in a response.

   The value is intended to be current at the time of transmission.
   Servers that provide resources with strict tolerances on the value of
   Max-Age SHOULD update the value before each retransmission.  (See
   also Section 5.7.1.)



Shelby, et al.               Standards Track                   [Page 55]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


5.10.6.  ETag

   An entity-tag is intended for use as a resource-local identifier for
   differentiating between representations of the same resource that
   vary over time.  It is generated by the server providing the
   resource, which may generate it in any number of ways including a
   version, checksum, hash, or time.  An endpoint receiving an entity-
   tag MUST treat it as opaque and make no assumptions about its content
   or structure.  (Endpoints that generate an entity-tag are encouraged
   to use the most compact representation possible, in particular in
   regards to clients and intermediaries that may want to store multiple
   ETag values.)

5.10.6.1.  ETag as a Response Option

   The ETag Option in a response provides the current value (i.e., after
   the request was processed) of the entity-tag for the "tagged
   representation".  If no Location-* options are present, the tagged
   representation is the selected representation (Section 5.5.3) of the
   target resource.  If one or more Location-* options are present and
   thus a location URI is indicated (Section 5.10.7), the tagged
   representation is the representation that would be retrieved by a GET
   request to the location URI.

   An ETag response option can be included with any response for which
   there is a tagged representation (e.g., it would not be meaningful in
   a 4.04 or 4.00 response).  The ETag Option MUST NOT occur more than
   once in a response.

   There is no default value for the ETag Option; if it is not present
   in a response, the server makes no statement about the entity-tag for
   the tagged representation.

5.10.6.2.  ETag as a Request Option

   In a GET request, an endpoint that has one or more representations
   previously obtained from the resource, and has obtained ETag response
   options with these, can specify an instance of the ETag Option for
   one or more of these stored responses.

   A server can issue a 2.03 Valid response (Section 5.9.1.3) in place
   of a 2.05 Content response if one of the ETags given is the entity-
   tag for the current representation, i.e., is valid; the 2.03 Valid
   response then echoes this specific ETag in a response option.

   In effect, a client can determine if any of the stored
   representations is current (see Section 5.6.2) without needing to
   transfer them again.



Shelby, et al.               Standards Track                   [Page 56]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   The ETag Option MAY occur zero, one, or multiple times in a request.

5.10.7.  Location-Path and Location-Query

   The Location-Path and Location-Query Options together indicate a
   relative URI that consists either of an absolute path, a query
   string, or both.  A combination of these options is included in a
   2.01 (Created) response to indicate the location of the resource
   created as the result of a POST request (see Section 5.8.2).  The
   location is resolved relative to the request URI.

   If a response with one or more Location-Path and/or Location-Query
   Options passes through a cache that interprets these options and the
   implied URI identifies one or more currently stored responses, those
   entries MUST be marked as not fresh.

   Each Location-Path Option specifies one segment of the absolute path
   to the resource, and each Location-Query Option specifies one
   argument parameterizing the resource.  The Location-Path and
   Location-Query Option can contain any character sequence.  No
   percent-encoding is performed.  The value of a Location-Path Option
   MUST NOT be "." or "..".

   The steps for constructing the location URI from the options are
   analogous to Section 6.5, except that the first five steps are
   skipped and the result is a relative URI-reference, which is then
   interpreted relative to the request URI.  Note that the relative URI-
   reference constructed this way always includes an absolute path
   (e.g., leaving out Location-Path but supplying Location-Query means
   the path component in the URI is "/").

   The options that are used to compute the relative URI-reference are
   collectively called Location-* options.  Beyond Location-Path and
   Location-Query, more Location-* options may be defined in the future
   and have been reserved option numbers 128, 132, 136, and 140.  If any
   of these reserved option numbers occurs in addition to Location-Path
   and/or Location-Query and are not supported, then a 4.02 (Bad Option)
   error MUST be returned.

5.10.8.  Conditional Request Options

   Conditional request options enable a client to ask the server to
   perform the request only if certain conditions specified by the
   option are fulfilled.







Shelby, et al.               Standards Track                   [Page 57]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   For each of these options, if the condition given is not fulfilled,
   then the server MUST NOT perform the requested method.  Instead, the
   server MUST respond with the 4.12 (Precondition Failed) Response
   Code.

   If the condition is fulfilled, the server performs the request method
   as if the conditional request options were not present.

   If the request would, without the conditional request options, result
   in anything other than a 2.xx or 4.12 Response Code, then any
   conditional request options MAY be ignored.

5.10.8.1.  If-Match

   The If-Match Option MAY be used to make a request conditional on the
   current existence or value of an ETag for one or more representations
   of the target resource.  If-Match is generally useful for resource
   update requests, such as PUT requests, as a means for protecting
   against accidental overwrites when multiple clients are acting in
   parallel on the same resource (i.e., the "lost update" problem).

   The value of an If-Match option is either an ETag or the empty
   string.  An If-Match option with an ETag matches a representation
   with that exact ETag.  An If-Match option with an empty value matches
   any existing representation (i.e., it places the precondition on the
   existence of any current representation for the target resource).

   The If-Match Option can occur multiple times.  If any of the options
   match, then the condition is fulfilled.

   If there is one or more If-Match Options, but none of the options
   match, then the condition is not fulfilled.

5.10.8.2.  If-None-Match

   The If-None-Match Option MAY be used to make a request conditional on
   the nonexistence of the target resource.  If-None-Match is useful for
   resource creation requests, such as PUT requests, as a means for
   protecting against accidental overwrites when multiple clients are
   acting in parallel on the same resource.  The If-None-Match Option
   carries no value.

   If the target resource does exist, then the condition is not
   fulfilled.

   (It is not very useful to combine If-Match and If-None-Match options
   in one request, because the condition will then never be fulfilled.)




Shelby, et al.               Standards Track                   [Page 58]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


5.10.9.  Size1 Option

   The Size1 option provides size information about the resource
   representation in a request.  The option value is an integer number
   of bytes.  Its main use is with block-wise transfers [BLOCK].  In the
   present specification, it is used in 4.13 responses (Section 5.9.2.9)
   to indicate the maximum size of request entity that the server is
   able and willing to handle.

6.  CoAP URIs

   CoAP uses the "coap" and "coaps" URI schemes for identifying CoAP
   resources and providing a means of locating the resource.  Resources
   are organized hierarchically and governed by a potential CoAP origin
   server listening for CoAP requests ("coap") or DTLS-secured CoAP
   requests ("coaps") on a given UDP port.  The CoAP server is
   identified via the generic syntax's authority component, which
   includes a host component and optional UDP port number.  The
   remainder of the URI is considered to be identifying a resource that
   can be operated on by the methods defined by the CoAP protocol.  The
   "coap" and "coaps" URI schemes can thus be compared to the "http" and
   "https" URI schemes, respectively.

   The syntax of the "coap" and "coaps" URI schemes is specified in this
   section in Augmented Backus-Naur Form (ABNF) [RFC5234].  The
   definitions of "host", "port", "path-abempty", "query", "segment",
   "IP-literal", "IPv4address", and "reg-name" are adopted from
   [RFC3986].

   Implementation Note:  Unfortunately, over time, the URI format has
      acquired significant complexity.  Implementers are encouraged to
      examine [RFC3986] closely.  For example, the ABNF for IPv6
      addresses is more complicated than maybe expected.  Also,
      implementers should take care to perform the processing of
      percent-decoding or percent-encoding exactly once on the way from
      a URI to its decoded components or back.  Percent-encoding is
      crucial for data transparency but may lead to unusual results such
      as a slash character in a path component.

6.1.  coap URI Scheme

   coap-URI = "coap:" "//" host [ ":" port ] path-abempty [ "?" query ]

   If the host component is provided as an IP-literal or IPv4address,
   then the CoAP server can be reached at that IP address.  If host is a
   registered name, then that name is considered an indirect identifier
   and the endpoint might use a name resolution service, such as DNS, to
   find the address of that host.  The host MUST NOT be empty; if a URI



Shelby, et al.               Standards Track                   [Page 59]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   is received with a missing authority or an empty host, then it MUST
   be considered invalid.  The port subcomponent indicates the UDP port
   at which the CoAP server is located.  If it is empty or not given,
   then the default port 5683 is assumed.

   The path identifies a resource within the scope of the host and port.
   It consists of a sequence of path segments separated by a slash
   character (U+002F SOLIDUS "/").

   The query serves to further parameterize the resource.  It consists
   of a sequence of arguments separated by an ampersand character
   (U+0026 AMPERSAND "&").  An argument is often in the form of a
   "key=value" pair.

   The "coap" URI scheme supports the path prefix "/.well-known/"
   defined by [RFC5785] for "well-known locations" in the namespace of a
   host.  This enables discovery of policy or other information about a
   host ("site-wide metadata"), such as hosted resources (see
   Section 7).

   Application designers are encouraged to make use of short but
   descriptive URIs.  As the environments that CoAP is used in are
   usually constrained for bandwidth and energy, the trade-off between
   these two qualities should lean towards the shortness, without
   ignoring descriptiveness.

6.2.  coaps URI Scheme

   coaps-URI = "coaps:" "//" host [ ":" port ] path-abempty
               [ "?" query ]

   All of the requirements listed above for the "coap" scheme are also
   requirements for the "coaps" scheme, except that a default UDP port
   of 5684 is assumed if the port subcomponent is empty or not given,
   and the UDP datagrams MUST be secured through the use of DTLS as
   described in Section 9.1.

   Considerations for caching of responses to "coaps" identified
   requests are discussed in Section 11.2.

   Resources made available via the "coaps" scheme have no shared
   identity with the "coap" scheme even if their resource identifiers
   indicate the same authority (the same host listening to the same UDP
   port).  They are distinct namespaces and are considered to be
   distinct origin servers.






Shelby, et al.               Standards Track                   [Page 60]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


6.3.  Normalization and Comparison Rules

   Since the "coap" and "coaps" schemes conform to the URI generic
   syntax, such URIs are normalized and compared according to the
   algorithm defined in [RFC3986], Section 6, using the defaults
   described above for each scheme.

   If the port is equal to the default port for a scheme, the normal
   form is to elide the port subcomponent.  Likewise, an empty path
   component is equivalent to an absolute path of "/", so the normal
   form is to provide a path of "/" instead.  The scheme and host are
   case insensitive and normally provided in lowercase; IP-literals are
   in recommended form [RFC5952]; all other components are compared in a
   case-sensitive manner.  Characters other than those in the "reserved"
   set are equivalent to their percent-encoded bytes (see [RFC3986],
   Section 2.1): the normal form is to not encode them.

   For example, the following three URIs are equivalent and cause the
   same options and option values to appear in the CoAP messages:

   coap://example.com:5683/~sensors/temp.xml
   coap://EXAMPLE.com/%7Esensors/temp.xml
   coap://EXAMPLE.com:/%7esensors/temp.xml

6.4.  Decomposing URIs into Options

   The steps to parse a request's options from a string |url| are as
   follows.  These steps either result in zero or more of the Uri-Host,
   Uri-Port, Uri-Path, and Uri-Query Options being included in the
   request or they fail.

   1.  If the |url| string is not an absolute URI ([RFC3986]), then fail
       this algorithm.

   2.  Resolve the |url| string using the process of reference
       resolution defined by [RFC3986].  At this stage, the URL is in
       ASCII encoding [RFC0020], even though the decoded components will
       be interpreted in UTF-8 [RFC3629] after steps 5, 8, and 9.

       NOTE: It doesn't matter what it is resolved relative to, since we
       already know it is an absolute URL at this point.

   3.  If |url| does not have a <scheme> component whose value, when
       converted to ASCII lowercase, is "coap" or "coaps", then fail
       this algorithm.

   4.  If |url| has a <fragment> component, then fail this algorithm.




Shelby, et al.               Standards Track                   [Page 61]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   5.  If the <host> component of |url| does not represent the request's
       destination IP address as an IP-literal or IPv4address, include a
       Uri-Host Option and let that option's value be the value of the
       <host> component of |url|, converted to ASCII lowercase, and then
       convert all percent-encodings ("%" followed by two hexadecimal
       digits) to the corresponding characters.

       NOTE: In the usual case where the request's destination IP
       address is derived from the host part, this ensures that a Uri-
       Host Option is only used for a <host> component of the form reg-
       name.

   6.  If |url| has a <port> component, then let |port| be that
       component's value interpreted as a decimal integer; otherwise,
       let |port| be the default port for the scheme.

   7.  If |port| does not equal the request's destination UDP port,
       include a Uri-Port Option and let that option's value be |port|.

   8.  If the value of the <path> component of |url| is empty or
       consists of a single slash character (U+002F SOLIDUS "/"), then
       move to the next step.

       Otherwise, for each segment in the <path> component, include a
       Uri-Path Option and let that option's value be the segment (not
       including the delimiting slash characters) after converting each
       percent-encoding ("%" followed by two hexadecimal digits) to the
       corresponding byte.

   9.  If |url| has a <query> component, then, for each argument in the
       <query> component, include a Uri-Query Option and let that
       option's value be the argument (not including the question mark
       and the delimiting ampersand characters) after converting each
       percent-encoding to the corresponding byte.

   Note that these rules completely resolve any percent-encoding.

6.5.  Composing URIs from Options

   The steps to construct a URI from a request's options are as follows.
   These steps either result in a URI or they fail.  In these steps,
   percent-encoding a character means replacing each of its
   (UTF-8-encoded) bytes by a "%" character followed by two hexadecimal
   digits representing the byte, where the digits A-F are in uppercase
   (as defined in Section 2.1 of [RFC3986]; to reduce variability, the
   hexadecimal notation for percent-encoding in CoAP URIs MUST use
   uppercase letters).  The definitions of "unreserved" and "sub-delims"
   are adopted from [RFC3986].



Shelby, et al.               Standards Track                   [Page 62]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   1.   If the request is secured using DTLS, let |url| be the string
        "coaps://".  Otherwise, let |url| be the string "coap://".

   2.   If the request includes a Uri-Host Option, let |host| be that
        option's value, where any non-ASCII characters are replaced by
        their corresponding percent-encoding.  If |host| is not a valid
        reg-name or IP-literal or IPv4address, fail the algorithm.  If
        the request does not include a Uri-Host Option, let |host| be
        the IP-literal (making use of the conventions of [RFC5952]) or
        IPv4address representing the request's destination IP address.

   3.   Append |host| to |url|.

   4.   If the request includes a Uri-Port Option, let |port| be that
        option's value.  Otherwise, let |port| be the request's
        destination UDP port.

   5.   If |port| is not the default port for the scheme, then append a
        single U+003A COLON character (:) followed by the decimal
        representation of |port| to |url|.

   6.   Let |resource name| be the empty string.  For each Uri-Path
        Option in the request, append a single character U+002F SOLIDUS
        (/) followed by the option's value to |resource name|, after
        converting any character that is not either in the "unreserved"
        set, in the "sub-delims" set, a U+003A COLON (:) character, or a
        U+0040 COMMERCIAL AT (@) character to its percent-encoded form.

   7.   If |resource name| is the empty string, set it to a single
        character U+002F SOLIDUS (/).

   8.   For each Uri-Query Option in the request, append a single
        character U+003F QUESTION MARK (?) (first option) or U+0026
        AMPERSAND (&) (subsequent options) followed by the option's
        value to |resource name|, after converting any character that is
        not either in the "unreserved" set, in the "sub-delims" set
        (except U+0026 AMPERSAND (&)), a U+003A COLON (:), a U+0040
        COMMERCIAL AT (@), a U+002F SOLIDUS (/), or a U+003F QUESTION
        MARK (?) character to its percent-encoded form.

   9.   Append |resource name| to |url|.

   10.  Return |url|.

   Note that these steps have been designed to lead to a URI in normal
   form (see Section 6.3).





Shelby, et al.               Standards Track                   [Page 63]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


7.  Discovery

7.1.  Service Discovery

   As a part of discovering the services offered by a CoAP server, a
   client has to learn about the endpoint used by a server.

   A server is discovered by a client (knowing or) learning a URI that
   references a resource in the namespace of the server.  Alternatively,
   clients can use multicast CoAP (see Section 8) and the "All CoAP
   Nodes" multicast address to find CoAP servers.

   Unless the port subcomponent in a "coap" or "coaps" URI indicates the
   UDP port at which the CoAP server is located, the server is assumed
   to be reachable at the default port.

   The CoAP default port number 5683 MUST be supported by a server that
   offers resources for resource discovery (see Section 7.2 below) and
   SHOULD be supported for providing access to other resources.  The
   default port number 5684 for DTLS-secured CoAP MAY be supported by a
   server for resource discovery and for providing access to other
   resources.  In addition, other endpoints may be hosted at other
   ports, e.g., in the dynamic port space.

   Implementation Note:  When a CoAP server is hosted by a 6LoWPAN node,
      header compression efficiency is improved when it also supports a
      port number in the 61616-61631 compressed UDP port space defined
      in [RFC4944] and [RFC6282].  (Note that, as its UDP port differs
      from the default port, it is a different endpoint from the server
      at the default port.)

7.2.  Resource Discovery

   The discovery of resources offered by a CoAP endpoint is extremely
   important in machine-to-machine applications where there are no
   humans in the loop and static interfaces result in fragility.  To
   maximize interoperability in a CoRE environment, a CoAP endpoint
   SHOULD support the CoRE Link Format of discoverable resources as
   described in [RFC6690], except where fully manual configuration is
   desired.  It is up to the server which resources are made
   discoverable (if any).

7.2.1.  'ct' Attribute

   This section defines a new Web Linking [RFC5988] attribute for use
   with [RFC6690].  The Content-Format code "ct" attribute provides a
   hint about the Content-Formats this resource returns.  Note that this
   is only a hint, and it does not override the Content-Format Option of



Shelby, et al.               Standards Track                   [Page 64]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   a CoAP response obtained by actually requesting the representation of
   the resource.  The value is in the CoAP identifier code format as a
   decimal ASCII integer and MUST be in the range of 0-65535 (16-bit
   unsigned integer).  For example, "application/xml" would be indicated
   as "ct=41".  If no Content-Format code attribute is present, then
   nothing about the type can be assumed.  The Content-Format code
   attribute MAY include a space-separated sequence of Content-Format
   codes, indicating that multiple content-formats are available.  The
   syntax of the attribute value is summarized in the production "ct-
   value" in Figure 12, where "cardinal", "SP", and "DQUOTE" are defined
   as in [RFC6690].

      ct-value =  cardinal
               /  DQUOTE cardinal *( 1*SP cardinal ) DQUOTE

                                 Figure 12

8.  Multicast CoAP

   CoAP supports making requests to an IP multicast group.  This is
   defined by a series of deltas to unicast CoAP.  A more general
   discussion of group communication with CoAP is in [GROUPCOMM].

   CoAP endpoints that offer services that they want other endpoints to
   be able to find using multicast service discovery join one or more of
   the appropriate all-CoAP-node multicast addresses (Section 12.8) and
   listen on the default CoAP port.  Note that an endpoint might receive
   multicast requests on other multicast addresses, including the all-
   nodes IPv6 address (or via broadcast on IPv4); an endpoint MUST
   therefore be prepared to receive such messages but MAY ignore them if
   multicast service discovery is not desired.

8.1.  Messaging Layer

   A multicast request is characterized by being transported in a CoAP
   message that is addressed to an IP multicast address instead of a
   CoAP endpoint.  Such multicast requests MUST be Non-confirmable.

   A server SHOULD be aware that a request arrived via multicast, e.g.,
   by making use of modern APIs such as IPV6_RECVPKTINFO [RFC3542], if
   available.

   To avoid an implosion of error responses, when a server is aware that
   a request arrived via multicast, it MUST NOT return a Reset message
   in reply to a Non-confirmable message.  If it is not aware, it MAY
   return a Reset message in reply to a Non-confirmable message as
   usual.  Because such a Reset message will look identical to one for a




Shelby, et al.               Standards Track                   [Page 65]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   unicast message from the sender, the sender MUST avoid using a
   Message ID that is also still active from this endpoint with any
   unicast endpoint that might receive the multicast message.

   At the time of writing, multicast messages can only be carried in UDP
   not in DTLS.  This means that the security modes defined for CoAP in
   this document are not applicable to multicast.

8.2.  Request/Response Layer

   When a server is aware that a request arrived via multicast, the
   server MAY always ignore the request, in particular if it doesn't
   have anything useful to respond (e.g., if it only has an empty
   payload or an error response).  The decision for this may depend on
   the application.  (For example, in query filtering as described in
   [RFC6690], a server should not respond to a multicast request if the
   filter does not match.  More examples are in [GROUPCOMM].)

   If a server does decide to respond to a multicast request, it should
   not respond immediately.  Instead, it should pick a duration for the
   period of time during which it intends to respond.  For the purposes
   of this exposition, we call the length of this period the Leisure.
   The specific value of this Leisure may depend on the application or
   MAY be derived as described below.  The server SHOULD then pick a
   random point of time within the chosen leisure period to send back
   the unicast response to the multicast request.  If further responses
   need to be sent based on the same multicast address membership, a new
   leisure period starts at the earliest after the previous one
   finishes.

   To compute a value for Leisure, the server should have a group size
   estimate G, a target data transfer rate R (which both should be
   chosen conservatively), and an estimated response size S; a rough
   lower bound for Leisure can then be computed as

                          lb_Leisure = S * G / R

   For example, for a multicast request with link-local scope on a 2.4
   GHz IEEE 802.15.4 (6LoWPAN) network, G could be (relatively
   conservatively) set to 100, S to 100 bytes, and the target rate to 8
   kbit/s = 1 kB/s.  The resulting lower bound for the Leisure is 10
   seconds.

   If a CoAP endpoint does not have suitable data to compute a value for
   Leisure, it MAY resort to DEFAULT_LEISURE.






Shelby, et al.               Standards Track                   [Page 66]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   When matching a response to a multicast request, only the token MUST
   match; the source endpoint of the response does not need to (and will
   not) be the same as the destination endpoint of the original request.

   For the purposes of interpreting the Location-* options and any links
   embedded in the representation, the request URI (i.e., the base URI
   relative to which the response is interpreted) is formed by replacing
   the multicast address in the Host component of the original request
   URI by the literal IP address of the endpoint actually responding.

8.2.1.  Caching

   When a client makes a multicast request, it always makes a new
   request to the multicast group (since there may be new group members
   that joined meanwhile or ones that did not get the previous request).
   It MAY update a cache with the received responses.  Then, it uses
   both cached-still-fresh and new responses as the result of the
   request.

   A response received in reply to a GET request to a multicast group
   MAY be used to satisfy a subsequent request on the related unicast
   request URI.  The unicast request URI is obtained by replacing the
   authority part of the request URI with the transport-layer source
   address of the response message.

   A cache MAY revalidate a response by making a GET request on the
   related unicast request URI.

   A GET request to a multicast group MUST NOT contain an ETag option.
   A mechanism to suppress responses the client already has is left for
   further study.

8.2.2.  Proxying

   When a forward-proxy receives a request with a Proxy-Uri or URI
   constructed from Proxy-Scheme that indicates a multicast address, the
   proxy obtains a set of responses as described above and sends all
   responses (both cached-still-fresh and new) back to the original
   client.

   This specification does not provide a way to indicate the unicast-
   modified request URI (base URI) in responses thus forwarded.
   Proxying multicast requests is discussed in more detail in
   [GROUPCOMM]; one proposal to address the base URI issue can be found
   in Section 3 of [CoAP-MISC].






Shelby, et al.               Standards Track                   [Page 67]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


9.  Securing CoAP

   This section defines the DTLS binding for CoAP.

   During the provisioning phase, a CoAP device is provided with the
   security information that it needs, including keying materials and
   access control lists.  This specification defines provisioning for
   the RawPublicKey mode in Section 9.1.3.2.1.  At the end of the
   provisioning phase, the device will be in one of four security modes
   with the following information for the given mode.  The NoSec and
   RawPublicKey modes are mandatory to implement for this specification.

   NoSec:  There is no protocol-level security (DTLS is disabled).
      Alternative techniques to provide lower-layer security SHOULD be
      used when appropriate.  The use of IPsec is discussed in
      [IPsec-CoAP].  Certain link layers in use with constrained nodes
      also provide link-layer security, which may be appropriate with
      proper key management.

   PreSharedKey:  DTLS is enabled, there is a list of pre-shared keys
      [RFC4279], and each key includes a list of which nodes it can be
      used to communicate with as described in Section 9.1.3.1.  At the
      extreme, there may be one key for each node this CoAP node needs
      to communicate with (1:1 node/key ratio).  Conversely, if more
      than two entities share a specific pre-shared key, this key only
      enables the entities to authenticate as a member of that group and
      not as a specific peer.

   RawPublicKey:  DTLS is enabled and the device has an asymmetric key
      pair without a certificate (a raw public key) that is validated
      using an out-of-band mechanism [RFC7250] as described in
      Section 9.1.3.2.  The device also has an identity calculated from
      the public key and a list of identities of the nodes it can
      communicate with.

   Certificate:  DTLS is enabled and the device has an asymmetric key
      pair with an X.509 certificate [RFC5280] that binds it to its
      subject and is signed by some common trust root as described in
      Section 9.1.3.3.  The device also has a list of root trust anchors
      that can be used for validating a certificate.

   In the "NoSec" mode, the system simply sends the packets over normal
   UDP over IP and is indicated by the "coap" scheme and the CoAP
   default port.  The system is secured only by keeping attackers from
   being able to send or receive packets from the network with the CoAP
   nodes; see Section 11.5 for an additional complication with this
   approach.




Shelby, et al.               Standards Track                   [Page 68]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   The other three security modes are achieved using DTLS and are
   indicated by the "coaps" scheme and DTLS-secured CoAP default port.
   The result is a security association that can be used to authenticate
   (within the limits of the security model) and, based on this
   authentication, authorize the communication partner.  CoAP itself
   does not provide protocol primitives for authentication or
   authorization; where this is required, it can either be provided by
   communication security (i.e., IPsec or DTLS) or by object security
   (within the payload).  Devices that require authorization for certain
   operations are expected to require one of these two forms of
   security.  Necessarily, where an intermediary is involved,
   communication security only works when that intermediary is part of
   the trust relationships.  CoAP does not provide a way to forward
   different levels of authorization that clients may have with an
   intermediary to further intermediaries or origin servers -- it
   therefore may be required to perform all authorization at the first
   intermediary.

9.1.  DTLS-Secured CoAP

   Just as HTTP is secured using Transport Layer Security (TLS) over
   TCP, CoAP is secured using Datagram TLS (DTLS) [RFC6347] over UDP
   (see Figure 13).  This section defines the CoAP binding to DTLS,
   along with the minimal mandatory-to-implement configurations
   appropriate for constrained environments.  The binding is defined by
   a series of deltas to unicast CoAP.  In practice, DTLS is TLS with
   added features to deal with the unreliable nature of the UDP
   transport.

                         +----------------------+
                         |      Application     |
                         +----------------------+
                         +----------------------+
                         |  Requests/Responses  |
                         |----------------------|  CoAP
                         |       Messages       |
                         +----------------------+
                         +----------------------+
                         |         DTLS         |
                         +----------------------+
                         +----------------------+
                         |          UDP         |
                         +----------------------+

             Figure 13: Abstract Layering of DTLS-Secured CoAP






Shelby, et al.               Standards Track                   [Page 69]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   In some constrained nodes (limited flash and/or RAM) and networks
   (limited bandwidth or high scalability requirements), and depending
   on the specific cipher suites in use, all modes of DTLS may not be
   applicable.  Some DTLS cipher suites can add significant
   implementation complexity as well as some initial handshake overhead
   needed when setting up the security association.  Once the initial
   handshake is completed, DTLS adds a limited per-datagram overhead of
   approximately 13 bytes, not including any initialization vectors/
   nonces (e.g., 8 bytes with TLS_PSK_WITH_AES_128_CCM_8 [RFC6655]),
   integrity check values (e.g., 8 bytes with TLS_PSK_WITH_AES_128_CCM_8
   [RFC6655]), and padding required by the cipher suite.  Whether the
   use of a given mode of DTLS is applicable for a CoAP-based
   application should be carefully weighed considering the specific
   cipher suites that may be applicable, whether the session maintenance
   makes it compatible with application flows, and whether sufficient
   resources are available on the constrained nodes and for the added
   network overhead.  (For some modes of using DTLS, this specification
   identifies a mandatory-to-implement cipher suite.  This is an
   implementation requirement to maximize interoperability in those
   cases where these cipher suites are indeed appropriate.  The specific
   security policies of an application may determine the actual set of
   cipher suites that can be used.)  DTLS is not applicable to group
   keying (multicast communication); however, it may be a component in a
   future group key management protocol.

9.1.1.  Messaging Layer

   The endpoint acting as the CoAP client should also act as the DTLS
   client.  It should initiate a session to the server on the
   appropriate port.  When the DTLS handshake has finished, the client
   may initiate the first CoAP request.  All CoAP messages MUST be sent
   as DTLS "application data".

   The following rules are added for matching an Acknowledgement message
   or Reset message to a Confirmable message, or a Reset message to a
   Non-confirmable message: The DTLS session MUST be the same, and the
   epoch MUST be the same.

   A message is the same when it is sent within the same DTLS session
   and same epoch and has the same Message ID.

   Note: When a Confirmable message is retransmitted, a new DTLS
   sequence_number is used for each attempt, even though the CoAP
   Message ID stays the same.  So a recipient still has to perform
   deduplication as described in Section 4.5.  Retransmissions MUST NOT
   be performed across epochs.





Shelby, et al.               Standards Track                   [Page 70]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   DTLS connections in RawPublicKey and Certificate mode are set up
   using mutual authentication so they can remain up and be reused for
   future message exchanges in either direction.  Devices can close a
   DTLS connection when they need to recover resources, but in general
   they should keep the connection up for as long as possible.  Closing
   the DTLS connection after every CoAP message exchange is very
   inefficient.

9.1.2.  Request/Response Layer

   The following rules are added for matching a response to a request:
   The DTLS session MUST be the same, and the epoch MUST be the same.

   This means the response to a DTLS secured request MUST always be DTLS
   secured using the same security session and epoch.  Any attempt to
   supply a NoSec response to a DTLS request simply does not match the
   request and therefore MUST be rejected (unless it does match an
   unrelated NoSec request).

9.1.3.  Endpoint Identity

   Devices SHOULD support the Server Name Indication (SNI) to indicate
   their authority in the SNI HostName field as defined in Section 3 of
   [RFC6066].  This is needed so that when a host that acts as a virtual
   server for multiple Authorities receives a new DTLS connection, it
   knows which keys to use for the DTLS session.

9.1.3.1.  Pre-Shared Keys

   When forming a connection to a new node, the system selects an
   appropriate key based on which nodes it is trying to reach and then
   forms a DTLS session using a PSK (Pre-Shared Key) mode of DTLS.
   Implementations in these modes MUST support the mandatory-to-
   implement cipher suite TLS_PSK_WITH_AES_128_CCM_8 as specified in
   [RFC6655].

   Depending on the commissioning model, applications may need to define
   an application profile for identity hints (as required and detailed
   in Section 5.2 of [RFC4279]) to enable the use of PSK identity hints.

   The security considerations of Section 7 of [RFC4279] apply.  In
   particular, applications should carefully weigh whether or not they
   need Perfect Forward Secrecy (PFS) and select an appropriate cipher
   suite (Section 7.1 of [RFC4279]).  The entropy of the PSK must be
   sufficient to mitigate against brute-force and (where the PSK is not
   chosen randomly but by a human) dictionary attacks (Section 7.2 of
   [RFC4279]).  The cleartext communication of client identities may
   leak data or compromise privacy (Section 7.3 of [RFC4279]).



Shelby, et al.               Standards Track                   [Page 71]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


9.1.3.2.  Raw Public Key Certificates

   In this mode, the device has an asymmetric key pair but without an
   X.509 certificate (called a raw public key); for example, the
   asymmetric key pair is generated by the manufacturer and installed on
   the device (see also Section 11.6).  A device MAY be configured with
   multiple raw public keys.  The type and length of the raw public key
   depends on the cipher suite used.  Implementations in RawPublicKey
   mode MUST support the mandatory-to-implement cipher suite
   TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 as specified in [RFC7251],
   [RFC5246], and [RFC4492].  The key used MUST be ECDSA capable.  The
   curve secp256r1 MUST be supported [RFC4492]; this curve is equivalent
   to the NIST P-256 curve.  The hash algorithm is SHA-256.
   Implementations MUST use the Supported Elliptic Curves and Supported
   Point Formats Extensions [RFC4492]; the uncompressed point format
   MUST be supported; [RFC6090] can be used as an implementation method.
   Some guidance relevant to the implementation of this cipher suite can
   be found in [W3CXMLSEC].  The mechanism for using raw public keys
   with TLS is specified in [RFC7250].

   Implementation Note:  Specifically, this means the extensions listed
      in Figure 14 with at least the values listed will be present in
      the DTLS handshake.

   Extension: elliptic_curves
    Type: elliptic_curves (0x000a)
    Length: 4
    Elliptic Curves Length: 2
    Elliptic curves (1 curve)
      Elliptic curve: secp256r1 (0x0017)

   Extension: ec_point_formats
    Type: ec_point_formats (0x000b)
    Length: 2
    EC point formats Length: 1
    Elliptic curves point formats (1)
      EC point format: uncompressed (0)

   Extension: signature_algorithms
    Type: signature_algorithms (0x000d)
    Length: 4
    Data (4 bytes): 00 02 04 03
      HashAlgorithm: sha256 (4)
      SignatureAlgorithm: ecdsa (3)

                  Figure 14: DTLS Extensions Present for
                    TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8




Shelby, et al.               Standards Track                   [Page 72]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


9.1.3.2.1.  Provisioning

   The RawPublicKey mode was designed to be easily provisioned in M2M
   deployments.  It is assumed that each device has an appropriate
   asymmetric public key pair installed.  An identifier is calculated by
   the endpoint from the public key as described in Section 2 of
   [RFC6920].  All implementations that support checking RawPublicKey
   identities MUST support at least the sha-256-120 mode (SHA-256
   truncated to 120 bits).  Implementations SHOULD also support longer
   length identifiers and MAY support shorter lengths.  Note that the
   shorter lengths provide less security against attacks, and their use
   is NOT RECOMMENDED.

   Depending on how identifiers are given to the system that verifies
   them, support for URI, binary, and/or human-speakable format
   [RFC6920] needs to be implemented.  All implementations SHOULD
   support the binary mode, and implementations that have a user
   interface SHOULD also support the human-speakable format.

   During provisioning, the identifier of each node is collected, for
   example, by reading a barcode on the outside of the device or by
   obtaining a pre-compiled list of the identifiers.  These identifiers
   are then installed in the corresponding endpoint, for example, an M2M
   data collection server.  The identifier is used for two purposes, to
   associate the endpoint with further device information and to perform
   access control.  During (initial and ongoing) provisioning, an access
   control list of identifiers with which the device may start DTLS
   sessions SHOULD also be installed and maintained.

9.1.3.3.  X.509 Certificates

   Implementations in Certificate Mode MUST support the mandatory-to-
   implement cipher suite TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 as
   specified in [RFC7251], [RFC5246], and [RFC4492].  Namely, the
   certificate includes a SubjectPublicKeyInfo that indicates an
   algorithm of id-ecPublicKey with namedCurves secp256r1 [RFC5480]; the
   public key format is uncompressed [RFC5480]; the hash algorithm is
   SHA-256; if included, the key usage extension indicates
   digitalSignature.  Certificates MUST be signed with ECDSA using
   secp256r1, and the signature MUST use SHA-256.  The key used MUST be
   ECDSA capable.  The curve secp256r1 MUST be supported [RFC4492]; this
   curve is equivalent to the NIST P-256 curve.  The hash algorithm is
   SHA-256.  Implementations MUST use the Supported Elliptic Curves and
   Supported Point Formats Extensions [RFC4492]; the uncompressed point
   format MUST be supported; [RFC6090] can be used as an implementation
   method.





Shelby, et al.               Standards Track                   [Page 73]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   The subject in the certificate would be built out of a long-term
   unique identifier for the device such as the EUI-64 [EUI64].  The
   subject could also be based on the Fully Qualified Domain Name (FQDN)
   that was used as the Host part of the CoAP URI.  However, the
   device's IP address should not typically be used as the subject, as
   it would change over time.  The discovery process used in the system
   would build up the mapping between IP addresses of the given devices
   and the subject for each device.  Some devices could have more than
   one subject and would need more than a single certificate.

   When a new connection is formed, the certificate from the remote
   device needs to be verified.  If the CoAP node has a source of
   absolute time, then the node SHOULD check that the validity dates of
   the certificate are within range.  The certificate MUST be validated
   as appropriate for the security requirements, using functionality
   equivalent to the algorithm specified in Section 6 of [RFC5280].  If
   the certificate contains a SubjectAltName, then the authority of the
   request URI MUST match at least one of the authorities of any CoAP
   URI found in a field of URI type in the SubjectAltName set.  If there
   is no SubjectAltName in the certificate, then the authority of the
   request URI MUST match the Common Name (CN) found in the certificate
   using the matching rules defined in [RFC3280] with the exception that
   certificates with wildcards are not allowed.

   CoRE support for certificate status checking requires further study.
   As a mapping of the Online Certificate Status Protocol (OCSP)
   [RFC6960] onto CoAP is not currently defined and OCSP may also not be
   easily applicable in all environments, an alternative approach may be
   using the TLS Certificate Status Request extension (Section 8 of
   [RFC6066]; also known as "OCSP stapling") or preferably the Multiple
   Certificate Status Extension ([RFC6961]), if available.

   If the system has a shared key in addition to the certificate, then a
   cipher suite that includes the shared key such as
   TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA [RFC5489] SHOULD be used.

10.  Cross-Protocol Proxying between CoAP and HTTP

   CoAP supports a limited subset of HTTP functionality, and thus cross-
   protocol proxying to HTTP is straightforward.  There might be several
   reasons for proxying between CoAP and HTTP, for example, when
   designing a web interface for use over either protocol or when
   realizing a CoAP-HTTP proxy.  Likewise, CoAP could equally be proxied
   to other protocols such as XMPP [RFC6120] or SIP [RFC3264]; the
   definition of these mechanisms is out of scope for this
   specification.





Shelby, et al.               Standards Track                   [Page 74]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   There are two possible directions to access a resource via a forward-
   proxy:

   CoAP-HTTP Proxying:  Enables CoAP clients to access resources on HTTP
      servers through an intermediary.  This is initiated by including
      the Proxy-Uri or Proxy-Scheme Option with an "http" or "https" URI
      in a CoAP request to a CoAP-HTTP proxy.

   HTTP-CoAP Proxying:  Enables HTTP clients to access resources on CoAP
      servers through an intermediary.  This is initiated by specifying
      a "coap" or "coaps" URI in the Request-Line of an HTTP request to
      an HTTP-CoAP proxy.

   Either way, only the request/response model of CoAP is mapped to
   HTTP.  The underlying model of Confirmable or Non-confirmable
   messages, etc., is invisible and MUST have no effect on a proxy
   function.  The following sections describe the handling of requests
   to a forward-proxy.  Reverse-proxies are not specified, as the proxy
   function is transparent to the client with the proxy acting as if it
   were the origin server.  However, similar considerations apply to
   reverse-proxies as to forward-proxies, and there generally will be an
   expectation that reverse-proxies operate in a similar way forward-
   proxies would.  As an implementation note, HTTP client libraries may
   make it hard to operate an HTTP-CoAP forward-proxy by not providing a
   way to put a CoAP URI on the HTTP Request-Line; reverse-proxying may
   therefore lead to wider applicability of a proxy.  A separate
   specification may define a convention for URIs operating such an
   HTTP-CoAP reverse-proxy [MAPPING].

10.1.  CoAP-HTTP Proxying

   If a request contains a Proxy-Uri or Proxy-Scheme Option with an
   'http' or 'https' URI [RFC2616], then the receiving CoAP endpoint
   (called "the proxy" henceforth) is requested to perform the operation
   specified by the request method on the indicated HTTP resource and
   return the result to the client.  (See also Section 5.7 for how the
   request to the proxy is formulated, including security requirements.)

   This section specifies for any CoAP request the CoAP response that
   the proxy should return to the client.  How the proxy actually
   satisfies the request is an implementation detail, although the
   typical case is expected to be that the proxy translates and forwards
   the request to an HTTP origin server.








Shelby, et al.               Standards Track                   [Page 75]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   Since HTTP and CoAP share the basic set of request methods,
   performing a CoAP request on an HTTP resource is not so different
   from performing it on a CoAP resource.  The meanings of the
   individual CoAP methods when performed on HTTP resources are
   explained in the subsections of this section.

   If the proxy is unable or unwilling to service a request with an HTTP
   URI, a 5.05 (Proxying Not Supported) response is returned to the
   client.  If the proxy services the request by interacting with a
   third party (such as the HTTP origin server) and is unable to obtain
   a result within a reasonable time frame, a 5.04 (Gateway Timeout)
   response is returned; if a result can be obtained but is not
   understood, a 5.02 (Bad Gateway) response is returned.

10.1.1.  GET

   The GET method requests the proxy to return a representation of the
   HTTP resource identified by the request URI.

   Upon success, a 2.05 (Content) Response Code SHOULD be returned.  The
   payload of the response MUST be a representation of the target HTTP
   resource, and the Content-Format Option MUST be set accordingly.  The
   response MUST indicate a Max-Age value that is no greater than the
   remaining time the representation can be considered fresh.  If the
   HTTP entity has an entity-tag, the proxy SHOULD include an ETag
   Option in the response and process ETag Options in requests as
   described below.

   A client can influence the processing of a GET request by including
   the following option:

   Accept:  The request MAY include an Accept Option, identifying the
      preferred response content-format.

   ETag:  The request MAY include one or more ETag Options, identifying
      responses that the client has stored.  This requests the proxy to
      send a 2.03 (Valid) response whenever it would send a 2.05
      (Content) response with an entity-tag in the requested set
      otherwise.  Note that CoAP ETags are always strong ETags in the
      HTTP sense; CoAP does not have the equivalent of HTTP weak ETags,
      and there is no good way to make use of these in a cross-proxy.










Shelby, et al.               Standards Track                   [Page 76]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


10.1.2.  PUT

   The PUT method requests the proxy to update or create the HTTP
   resource identified by the request URI with the enclosed
   representation.

   If a new resource is created at the request URI, a 2.01 (Created)
   response MUST be returned to the client.  If an existing resource is
   modified, a 2.04 (Changed) response MUST be returned to indicate
   successful completion of the request.

10.1.3.  DELETE

   The DELETE method requests the proxy to delete the HTTP resource
   identified by the request URI at the HTTP origin server.

   A 2.02 (Deleted) response MUST be returned to the client upon success
   or if the resource does not exist at the time of the request.

10.1.4.  POST

   The POST method requests the proxy to have the representation
   enclosed in the request be processed by the HTTP origin server.  The
   actual function performed by the POST method is determined by the
   origin server and dependent on the resource identified by the request
   URI.

   If the action performed by the POST method does not result in a
   resource that can be identified by a URI, a 2.04 (Changed) response
   MUST be returned to the client.  If a resource has been created on
   the origin server, a 2.01 (Created) response MUST be returned.

10.2.  HTTP-CoAP Proxying

   If an HTTP request contains a Request-URI with a "coap" or "coaps"
   URI, then the receiving HTTP endpoint (called "the proxy" henceforth)
   is requested to perform the operation specified by the request method
   on the indicated CoAP resource and return the result to the client.

   This section specifies for any HTTP request the HTTP response that
   the proxy should return to the client.  Unless otherwise specified,
   all the statements made are RECOMMENDED behavior; some highly
   constrained implementations may need to resort to shortcuts.  How the
   proxy actually satisfies the request is an implementation detail,
   although the typical case is expected to be that the proxy translates
   and forwards the request to a CoAP origin server.  The meanings of
   the individual HTTP methods when performed on CoAP resources are
   explained in the subsections of this section.



Shelby, et al.               Standards Track                   [Page 77]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   If the proxy is unable or unwilling to service a request with a CoAP
   URI, a 501 (Not Implemented) response is returned to the client.  If
   the proxy services the request by interacting with a third party
   (such as the CoAP origin server) and is unable to obtain a result
   within a reasonable time frame, a 504 (Gateway Timeout) response is
   returned; if a result can be obtained but is not understood, a 502
   (Bad Gateway) response is returned.

10.2.1.  OPTIONS and TRACE

   As the OPTIONS and TRACE methods are not supported in CoAP, a 501
   (Not Implemented) error MUST be returned to the client.

10.2.2.  GET

   The GET method requests the proxy to return a representation of the
   CoAP resource identified by the Request-URI.

   Upon success, a 200 (OK) response is returned.  The payload of the
   response MUST be a representation of the target CoAP resource, and
   the Content-Type and Content-Encoding header fields MUST be set
   accordingly.  The response MUST indicate a max-age directive that
   indicates a value no greater than the remaining time the
   representation can be considered fresh.  If the CoAP response has an
   ETag option, the proxy should include an ETag header field in the
   response.

   A client can influence the processing of a GET request by including
   the following options:

   Accept:  The most-preferred media type of the HTTP Accept header
      field in a request is mapped to a CoAP Accept option.  HTTP Accept
      media-type ranges, parameters, and extensions are not supported by
      the CoAP Accept option.  If the proxy cannot send a response that
      is acceptable according to the combined Accept field value, then
      the proxy sends a 406 (Not Acceptable) response.  The proxy MAY
      then retry the request with further media types from the HTTP
      Accept header field.

   Conditional GETs:  Conditional HTTP GET requests that include an "If-
      Match" or "If-None-Match" request-header field can be mapped to a
      corresponding CoAP request.  The "If-Modified-Since" and "If-
      Unmodified-Since" request-header fields are not directly supported
      by CoAP but are implemented locally by a caching proxy.







Shelby, et al.               Standards Track                   [Page 78]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


10.2.3.  HEAD

   The HEAD method is identical to GET except that the server MUST NOT
   return a message-body in the response.

   Although there is no direct equivalent of HTTP's HEAD method in CoAP,
   an HTTP-CoAP proxy responds to HEAD requests for CoAP resources, and
   the HTTP headers are returned without a message-body.

   Implementation Note:  An HTTP-CoAP proxy may want to try using a
      block-wise transfer option [BLOCK] to minimize the amount of data
      actually transferred, but it needs to be prepared for the case
      that the origin server does not support block-wise transfers.

10.2.4.  POST

   The POST method requests the proxy to have the representation
   enclosed in the request be processed by the CoAP origin server.  The
   actual function performed by the POST method is determined by the
   origin server and dependent on the resource identified by the request
   URI.

   If the action performed by the POST method does not result in a
   resource that can be identified by a URI, a 200 (OK) or 204 (No
   Content) response MUST be returned to the client.  If a resource has
   been created on the origin server, a 201 (Created) response MUST be
   returned.

   If any of the Location-* Options are present in the CoAP response, a
   Location header field constructed from the values of these options is
   returned.

10.2.5.  PUT

   The PUT method requests the proxy to update or create the CoAP
   resource identified by the Request-URI with the enclosed
   representation.

   If a new resource is created at the Request-URI, a 201 (Created)
   response is returned to the client.  If an existing resource is
   modified, either the 200 (OK) or 204 (No Content) Response Codes is
   sent to indicate successful completion of the request.









Shelby, et al.               Standards Track                   [Page 79]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


10.2.6.  DELETE

   The DELETE method requests the proxy to delete the CoAP resource
   identified by the Request-URI at the CoAP origin server.

   A successful response is 200 (OK) if the response includes an entity
   describing the status or 204 (No Content) if the action has been
   enacted but the response does not include an entity.

10.2.7.  CONNECT

   This method cannot currently be satisfied by an HTTP-CoAP proxy
   function, as TLS to DTLS tunneling has not yet been specified.  For
   now, a 501 (Not Implemented) error is returned to the client.

11.  Security Considerations

   This section analyzes the possible threats to the protocol.  It is
   meant to inform protocol and application developers about the
   security limitations of CoAP as described in this document.  As CoAP
   realizes a subset of the features in HTTP/1.1, the security
   considerations in Section 15 of [RFC2616] are also pertinent to CoAP.
   This section concentrates on describing limitations specific to CoAP.

11.1.  Parsing the Protocol and Processing URIs

   A network-facing application can exhibit vulnerabilities in its
   processing logic for incoming packets.  Complex parsers are well-
   known as a likely source of such vulnerabilities, such as the ability
   to remotely crash a node, or even remotely execute arbitrary code on
   it.  CoAP attempts to narrow the opportunities for introducing such
   vulnerabilities by reducing parser complexity, by giving the entire
   range of encodable values a meaning where possible, and by
   aggressively reducing complexity that is often caused by unnecessary
   choice between multiple representations that mean the same thing.
   Much of the URI processing has been moved to the clients, further
   reducing the opportunities for introducing vulnerabilities into the
   servers.  Even so, the URI processing code in CoAP implementations is
   likely to be a large source of remaining vulnerabilities and should
   be implemented with special care.  CoAP access control
   implementations need to ensure they don't introduce vulnerabilities
   through discrepancies between the code deriving access control
   decisions from a URI and the code finally serving up the resource
   addressed by the URI.  The most complex parser remaining could be the
   one for the CoRE Link Format, although this also has been designed
   with a goal of reduced implementation complexity [RFC6690].  (See
   also Section 15.2 of [RFC2616].)




Shelby, et al.               Standards Track                   [Page 80]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


11.2.  Proxying and Caching

   As mentioned in Section 15.7 of [RFC2616], proxies are by their very
   nature men-in-the-middle, breaking any IPsec or DTLS protection that
   a direct CoAP message exchange might have.  They are therefore
   interesting targets for breaking confidentiality or integrity of CoAP
   message exchanges.  As noted in [RFC2616], they are also interesting
   targets for breaking availability.

   The threat to confidentiality and integrity of request/response data
   is amplified where proxies also cache.  Note that CoAP does not
   define any of the cache-suppressing Cache-Control options that
   HTTP/1.1 provides to better protect sensitive data.

   For a caching implementation, any access control considerations that
   would apply to making the request that generated the cache entry also
   need to be applied to the value in the cache.  This is relevant for
   clients that implement multiple security domains, as well as for
   proxies that may serve multiple clients.  Also, a caching proxy MUST
   NOT make cached values available to requests that have lesser
   transport-security properties than those the proxy would require to
   perform request forwarding in the first place.

   Unlike the "coap" scheme, responses to "coaps" identified requests
   are never "public" and thus MUST NOT be reused for shared caching,
   unless the cache is able to make equivalent access control decisions
   to the ones that led to the cached entry.  They can, however, be
   reused in a private cache if the message is cacheable by default in
   CoAP.

   Finally, a proxy that fans out Separate Responses (as opposed to
   piggybacked Responses) to multiple original requesters may provide
   additional amplification (see Section 11.3).

11.3.  Risk of Amplification

   CoAP servers generally reply to a request packet with a response
   packet.  This response packet may be significantly larger than the
   request packet.  An attacker might use CoAP nodes to turn a small
   attack packet into a larger attack packet, an approach known as
   amplification.  There is therefore a danger that CoAP nodes could
   become implicated in denial-of-service (DoS) attacks by using the
   amplifying properties of the protocol: an attacker that is attempting
   to overload a victim but is limited in the amount of traffic it can
   generate can use amplification to generate a larger amount of
   traffic.





Shelby, et al.               Standards Track                   [Page 81]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   This is particularly a problem in nodes that enable NoSec access, are
   accessible from an attacker, and can access potential victims (e.g.,
   on the general Internet), as the UDP protocol provides no way to
   verify the source address given in the request packet.  An attacker
   need only place the IP address of the victim in the source address of
   a suitable request packet to generate a larger packet directed at the
   victim.

   As a mitigating factor, many constrained networks will only be able
   to generate a small amount of traffic, which may make CoAP nodes less
   attractive for this attack.  However, the limited capacity of the
   constrained network makes the network itself a likely victim of an
   amplification attack.

   Therefore, large amplification factors SHOULD NOT be provided in the
   response if the request is not authenticated.  A CoAP server can
   reduce the amount of amplification it provides to an attacker by
   using slicing/blocking modes of CoAP [BLOCK] and offering large
   resource representations only in relatively small slices.  For
   example, for a 1000-byte resource, a 10-byte request might result in
   an 80-byte response (with a 64-byte block) instead of a 1016-byte
   response, considerably reducing the amplification provided.

   CoAP also supports the use of multicast IP addresses in requests, an
   important requirement for M2M.  Multicast CoAP requests may be the
   source of accidental or deliberate DoS attacks, especially over
   constrained networks.  This specification attempts to reduce the
   amplification effects of multicast requests by limiting when a
   response is returned.  To limit the possibility of malicious use,
   CoAP servers SHOULD NOT accept multicast requests that can not be
   authenticated in some way, cryptographically or by some multicast
   boundary limiting the potential sources.  If possible, a CoAP server
   SHOULD limit the support for multicast requests to the specific
   resources where the feature is required.

   On some general-purpose operating systems providing a POSIX-style API
   [IEEE1003.1], it is not straightforward to find out whether a packet
   received was addressed to a multicast address.  While many
   implementations will know whether they have joined a multicast group,
   this creates a problem for packets addressed to multicast addresses
   of the form FF0x::1, which are received by every IPv6 node.
   Implementations SHOULD make use of modern APIs such as
   IPV6_RECVPKTINFO [RFC3542], if available, to make this determination.








Shelby, et al.               Standards Track                   [Page 82]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


11.4.  IP Address Spoofing Attacks

   Due to the lack of a handshake in UDP, a rogue endpoint that is free
   to read and write messages carried by the constrained network (i.e.,
   NoSec or PreSharedKey deployments with a nodes/key ratio > 1:1), may
   easily attack a single endpoint, a group of endpoints, as well as the
   whole network, e.g., by:

   1.  spoofing a Reset message in response to a Confirmable message or
       Non-confirmable message, thus making an endpoint "deaf"; or

   2.  spoofing an ACK in response to a CON message, thus potentially
       preventing the sender of the CON message from retransmitting, and
       drowning out the actual response; or

   3.  spoofing the entire response with forged payload/options (this
       has different levels of impact: from single-response disruption,
       to much bolder attacks on the supporting infrastructure, e.g.,
       poisoning proxy caches, or tricking validation/lookup interfaces
       in resource directories and, more generally, any component that
       stores global network state and uses CoAP as the messaging
       facility to handle setting or updating state is a potential
       target.); or

   4.  spoofing a multicast request for a target node; this may result
       in network congestion/collapse, a DoS attack on the victim, or
       forced wake-up from sleeping; or

   5.  spoofing observe messages, etc.

   Response spoofing by off-path attackers can be detected and mitigated
   even without transport layer security by choosing a nontrivial,
   randomized token in the request (Section 5.3.1).  [RFC4086] discusses
   randomness requirements for security.

   In principle, other kinds of spoofing can be detected by CoAP only in
   case Confirmable message semantics is used, because of unexpected
   Acknowledgement or Reset messages coming from the deceived endpoint.
   But this imposes keeping track of the used Message IDs, which is not
   always possible, and moreover detection becomes available usually
   after the damage is already done.  This kind of attack can be
   prevented using security modes other than NoSec.

   With or without source address spoofing, a client can attempt to
   overload a server by sending requests, preferably complex ones, to a
   server; address spoofing makes tracing back, and blocking, this
   attack harder.  Given that the cost of a CON request is small, this
   attack can easily be executed.  Under this attack, a constrained node



Shelby, et al.               Standards Track                   [Page 83]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   with limited total energy available may exhaust that energy much more
   quickly than planned (battery depletion attack).  Also, if the client
   uses a Confirmable message and the server responds with a Confirmable
   separate response to a (possibly spoofed) address that does not
   respond, the server will have to allocate buffer and retransmission
   logic for each response up to the exhaustion of MAX_TRANSMIT_SPAN,
   making it more likely that it runs out of resources for processing
   legitimate traffic.  The latter problem can be mitigated somewhat by
   limiting the rate of responses as discussed in Section 4.7.  An
   attacker could also spoof the address of a legitimate client; this
   might cause the server, if it uses separate responses, to block
   legitimate responses to that client because of NSTART=1.  All these
   attacks can be prevented using a security mode other than NoSec, thus
   leaving only attacks on the security protocol.

11.5.  Cross-Protocol Attacks

   The ability to incite a CoAP endpoint to send packets to a fake
   source address can be used not only for amplification, but also for
   cross-protocol attacks against a victim listening to UDP packets at a
   given address (IP address and port).  This would occur as follows:

   o  The attacker sends a message to a CoAP endpoint with the given
      address as the fake source address.

   o  The CoAP endpoint replies with a message to the given source
      address.

   o  The victim at the given address receives a UDP packet that it
      interprets according to the rules of a different protocol.

   This may be used to circumvent firewall rules that prevent direct
   communication from the attacker to the victim but happen to allow
   communication from the CoAP endpoint (which may also host a valid
   role in the other protocol) to the victim.

   Also, CoAP endpoints may be the victim of a cross-protocol attack
   generated through an endpoint of another UDP-based protocol such as
   DNS.  In both cases, attacks are possible if the security properties
   of the endpoints rely on checking IP addresses (and firewalling off
   direct attacks sent from outside using fake IP addresses).  In
   general, because of their lack of context, UDP-based protocols are
   relatively easy targets for cross-protocol attacks.

   Finally, CoAP URIs transported by other means could be used to incite
   clients to send messages to endpoints of other protocols.





Shelby, et al.               Standards Track                   [Page 84]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   One mitigation against cross-protocol attacks is strict checking of
   the syntax of packets received, combined with sufficient difference
   in syntax.  As an example, it might help if it were difficult to
   incite a DNS server to send a DNS response that would pass the checks
   of a CoAP endpoint.  Unfortunately, the first two bytes of a DNS
   reply are an ID that can be chosen by the attacker and that map into
   the interesting part of the CoAP header, and the next two bytes are
   then interpreted as CoAP's Message ID (i.e., any value is
   acceptable).  The DNS count words may be interpreted as multiple
   instances of a (nonexistent but elective) CoAP option 0, or possibly
   as a Token.  The echoed query finally may be manufactured by the
   attacker to achieve a desired effect on the CoAP endpoint; the
   response added by the server (if any) might then just be interpreted
   as added payload.

                                   1  1  1  1  1  1
     0  1  2  3  4  5  6  7  8  9  0  1  2  3  4  5
   +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
   |                      ID                       | T, TKL, code
   +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
   |QR|   Opcode  |AA|TC|RD|RA|   Z    |   RCODE   | Message ID
   +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
   |                    QDCOUNT                    | (options 0)
   +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
   |                    ANCOUNT                    | (options 0)
   +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
   |                    NSCOUNT                    | (options 0)
   +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
   |                    ARCOUNT                    | (options 0)
   +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+

     Figure 15: DNS Header ([RFC1035], Section 4.1.1) vs. CoAP Message

   In general, for any pair of protocols, one of the protocols can very
   well have been designed in a way that enables an attacker to cause
   the generation of replies that look like messages of the other
   protocol.  It is often much harder to ensure or prove the absence of
   viable attacks than to generate examples that may not yet completely
   enable an attack but might be further developed by more creative
   minds.  Cross-protocol attacks can therefore only be completely
   mitigated if endpoints don't authorize actions desired by an attacker
   just based on trusting the source IP address of a packet.
   Conversely, a NoSec environment that completely relies on a firewall
   for CoAP security not only needs to firewall off the CoAP endpoints
   but also all other endpoints that might be incited to send UDP
   messages to CoAP endpoints using some other UDP-based protocol.





Shelby, et al.               Standards Track                   [Page 85]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   In addition to the considerations above, the security considerations
   for DTLS with respect to cross-protocol attacks apply.  For example,
   if the same DTLS security association ("connection") is used to carry
   data of multiple protocols, DTLS no longer provides protection
   against cross-protocol attacks between these protocols.

11.6.  Constrained-Node Considerations

   Implementers on constrained nodes often find themselves without a
   good source of entropy [RFC4086].  If that is the case, the node MUST
   NOT be used for processes that require good entropy, such as key
   generation.  Instead, keys should be generated externally and added
   to the device during manufacturing or commissioning.

   Due to their low processing power, constrained nodes are particularly
   susceptible to timing attacks.  Special care must be taken in
   implementation of cryptographic primitives.

   Large numbers of constrained nodes will be installed in exposed
   environments and will have little resistance to tampering, including
   recovery of keying materials.  This needs to be considered when
   defining the scope of credentials assigned to them.  In particular,
   assigning a shared key to a group of nodes may make any single
   constrained node a target for subverting the entire group.

12.  IANA Considerations

12.1.  CoAP Code Registries

   This document defines two sub-registries for the values of the Code
   field in the CoAP header within the "Constrained RESTful Environments
   (CoRE) Parameters" registry, hereafter referred to as the "CoRE
   Parameters" registry.

   Values in the two sub-registries are eight-bit values notated as
   three decimal digits c.dd separated by a period between the first and
   the second digit; the first digit c is between 0 and 7 and denotes
   the code class; the second and third digits dd denote a decimal
   number between 00 and 31 for the detail.












Shelby, et al.               Standards Track                   [Page 86]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   All Code values are assigned by sub-registries according to the
   following ranges:

   0.00      Indicates an Empty message (see Section 4.1).

   0.01-0.31 Indicates a request.  Values in this range are assigned by
             the "CoAP Method Codes" sub-registry (see Section 12.1.1).

   1.00-1.31 Reserved

   2.00-5.31 Indicates a response.  Values in this range are assigned by
             the "CoAP Response Codes" sub-registry (see
             Section 12.1.2).

   6.00-7.31 Reserved

12.1.1.  Method Codes

   The name of the sub-registry is "CoAP Method Codes".

   Each entry in the sub-registry must include the Method Code in the
   range 0.01-0.31, the name of the method, and a reference to the
   method's documentation.

   Initial entries in this sub-registry are as follows:

                       +------+--------+-----------+
                       | Code | Name   | Reference |
                       +------+--------+-----------+
                       | 0.01 | GET    | [RFC7252] |
                       | 0.02 | POST   | [RFC7252] |
                       | 0.03 | PUT    | [RFC7252] |
                       | 0.04 | DELETE | [RFC7252] |
                       +------+--------+-----------+

                        Table 5: CoAP Method Codes

   All other Method Codes are Unassigned.

   The IANA policy for future additions to this sub-registry is "IETF
   Review or IESG Approval" as described in [RFC5226].

   The documentation of a Method Code should specify the semantics of a
   request with that code, including the following properties:

   o  The Response Codes the method returns in the success case.

   o  Whether the method is idempotent, safe, or both.



Shelby, et al.               Standards Track                   [Page 87]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


12.1.2.  Response Codes

   The name of the sub-registry is "CoAP Response Codes".

   Each entry in the sub-registry must include the Response Code in the
   range 2.00-5.31, a description of the Response Code, and a reference
   to the Response Code's documentation.

   Initial entries in this sub-registry are as follows:

            +------+------------------------------+-----------+
            | Code | Description                  | Reference |
            +------+------------------------------+-----------+
            | 2.01 | Created                      | [RFC7252] |
            | 2.02 | Deleted                      | [RFC7252] |
            | 2.03 | Valid                        | [RFC7252] |
            | 2.04 | Changed                      | [RFC7252] |
            | 2.05 | Content                      | [RFC7252] |
            | 4.00 | Bad Request                  | [RFC7252] |
            | 4.01 | Unauthorized                 | [RFC7252] |
            | 4.02 | Bad Option                   | [RFC7252] |
            | 4.03 | Forbidden                    | [RFC7252] |
            | 4.04 | Not Found                    | [RFC7252] |
            | 4.05 | Method Not Allowed           | [RFC7252] |
            | 4.06 | Not Acceptable               | [RFC7252] |
            | 4.12 | Precondition Failed          | [RFC7252] |
            | 4.13 | Request Entity Too Large     | [RFC7252] |
            | 4.15 | Unsupported Content-Format   | [RFC7252] |
            | 5.00 | Internal Server Error        | [RFC7252] |
            | 5.01 | Not Implemented              | [RFC7252] |
            | 5.02 | Bad Gateway                  | [RFC7252] |
            | 5.03 | Service Unavailable          | [RFC7252] |
            | 5.04 | Gateway Timeout              | [RFC7252] |
            | 5.05 | Proxying Not Supported       | [RFC7252] |
            +------+------------------------------+-----------+

                       Table 6: CoAP Response Codes

   The Response Codes 3.00-3.31 are Reserved for future use.  All other
   Response Codes are Unassigned.

   The IANA policy for future additions to this sub-registry is "IETF
   Review or IESG Approval" as described in [RFC5226].








Shelby, et al.               Standards Track                   [Page 88]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   The documentation of a Response Code should specify the semantics of
   a response with that code, including the following properties:

   o  The methods the Response Code applies to.

   o  Whether payload is required, optional, or not allowed.

   o  The semantics of the payload.  For example, the payload of a 2.05
      (Content) response is a representation of the target resource; the
      payload in an error response is a human-readable diagnostic
      payload.

   o  The format of the payload.  For example, the format in a 2.05
      (Content) response is indicated by the Content-Format Option; the
      format of the payload in an error response is always Net-Unicode
      text.

   o  Whether the response is cacheable according to the freshness
      model.

   o  Whether the response is validatable according to the validation
      model.

   o  Whether the response causes a cache to mark responses stored for
      the request URI as not fresh.

12.2.  CoAP Option Numbers Registry

   This document defines a sub-registry for the Option Numbers used in
   CoAP options within the "CoRE Parameters" registry.  The name of the
   sub-registry is "CoAP Option Numbers".

   Each entry in the sub-registry must include the Option Number, the
   name of the option, and a reference to the option's documentation.

















Shelby, et al.               Standards Track                   [Page 89]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   Initial entries in this sub-registry are as follows:

                 +--------+------------------+-----------+
                 | Number | Name             | Reference |
                 +--------+------------------+-----------+
                 |      0 | (Reserved)       | [RFC7252] |
                 |      1 | If-Match         | [RFC7252] |
                 |      3 | Uri-Host         | [RFC7252] |
                 |      4 | ETag             | [RFC7252] |
                 |      5 | If-None-Match    | [RFC7252] |
                 |      7 | Uri-Port         | [RFC7252] |
                 |      8 | Location-Path    | [RFC7252] |
                 |     11 | Uri-Path         | [RFC7252] |
                 |     12 | Content-Format   | [RFC7252] |
                 |     14 | Max-Age          | [RFC7252] |
                 |     15 | Uri-Query        | [RFC7252] |
                 |     17 | Accept           | [RFC7252] |
                 |     20 | Location-Query   | [RFC7252] |
                 |     35 | Proxy-Uri        | [RFC7252] |
                 |     39 | Proxy-Scheme     | [RFC7252] |
                 |     60 | Size1            | [RFC7252] |
                 |    128 | (Reserved)       | [RFC7252] |
                 |    132 | (Reserved)       | [RFC7252] |
                 |    136 | (Reserved)       | [RFC7252] |
                 |    140 | (Reserved)       | [RFC7252] |
                 +--------+------------------+-----------+

                       Table 7: CoAP Option Numbers

   The IANA policy for future additions to this sub-registry is split
   into three tiers as follows.  The range of 0..255 is reserved for
   options defined by the IETF (IETF Review or IESG Approval).  The
   range of 256..2047 is reserved for commonly used options with public
   specifications (Specification Required).  The range of 2048..64999 is
   for all other options including private or vendor-specific ones,
   which undergo a Designated Expert review to help ensure that the
   option semantics are defined correctly.  The option numbers between
   65000 and 65535 inclusive are reserved for experiments.  They are not
   meant for vendor-specific use of any kind and MUST NOT be used in
   operational deployments.











Shelby, et al.               Standards Track                   [Page 90]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


          +-------------+---------------------------------------+
          |       Range | Registration Procedures               |
          +-------------+---------------------------------------+
          |       0-255 | IETF Review or IESG Approval          |
          |    256-2047 | Specification Required                |
          |  2048-64999 | Expert Review                         |
          | 65000-65535 | Experimental use (no operational use) |
          +-------------+---------------------------------------+

           Table 8: CoAP Option Numbers: Registration Procedures

   The documentation of an Option Number should specify the semantics of
   an option with that number, including the following properties:

   o  The meaning of the option in a request.

   o  The meaning of the option in a response.

   o  Whether the option is critical or elective, as determined by the
      Option Number.

   o  Whether the option is Safe-to-Forward, and, if yes, whether it is
      part of the Cache-Key, as determined by the Option Number (see
      Section 5.4.2).

   o  The format and length of the option's value.

   o  Whether the option must occur at most once or whether it can occur
      multiple times.

   o  The default value, if any.  For a critical option with a default
      value, a discussion on how the default value enables processing by
      implementations that do not support the critical option
      (Section 5.4.4).

12.3.  CoAP Content-Formats Registry

   Internet media types are identified by a string, such as
   "application/xml" [RFC2046].  In order to minimize the overhead of
   using these media types to indicate the format of payloads, this
   document defines a sub-registry for a subset of Internet media types
   to be used in CoAP and assigns each, in combination with a content-
   coding, a numeric identifier.  The name of the sub-registry is "CoAP
   Content-Formats", within the "CoRE Parameters" registry.







Shelby, et al.               Standards Track                   [Page 91]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   Each entry in the sub-registry must include the media type registered
   with IANA, the numeric identifier in the range 0-65535 to be used for
   that media type in CoAP, the content-coding associated with this
   identifier, and a reference to a document describing what a payload
   with that media type means semantically.

   CoAP does not include a separate way to convey content-encoding
   information with a request or response, and for that reason the
   content-encoding is also specified for each identifier (if any).  If
   multiple content-encodings will be used with a media type, then a
   separate Content-Format identifier for each is to be registered.
   Similarly, other parameters related to an Internet media type, such
   as level, can be defined for a CoAP Content-Format entry.

   Initial entries in this sub-registry are as follows:

   +--------------------------+----------+----+------------------------+
   | Media type               | Encoding | ID | Reference              |
   +--------------------------+----------+----+------------------------+
   | text/plain;              | -        |  0 | [RFC2046] [RFC3676]    |
   | charset=utf-8            |          |    | [RFC5147]              |
   | application/link-format  | -        | 40 | [RFC6690]              |
   | application/xml          | -        | 41 | [RFC3023]              |
   | application/octet-stream | -        | 42 | [RFC2045] [RFC2046]    |
   | application/exi          | -        | 47 | [REC-exi-20140211]     |
   | application/json         | -        | 50 | [RFC7159]              |
   +--------------------------+----------+----+------------------------+

                       Table 9: CoAP Content-Formats

   The identifiers between 65000 and 65535 inclusive are reserved for
   experiments.  They are not meant for vendor-specific use of any kind
   and MUST NOT be used in operational deployments.  The identifiers
   between 256 and 9999 are reserved for future use in IETF
   specifications (IETF Review or IESG Approval).  All other identifiers
   are Unassigned.

   Because the namespace of single-byte identifiers is so small, the
   IANA policy for future additions in the range 0-255 inclusive to the
   sub-registry is "Expert Review" as described in [RFC5226].  The IANA
   policy for additions in the range 10000-64999 inclusive is "First
   Come First Served" as described in [RFC5226].  This is summarized in
   the following table.








Shelby, et al.               Standards Track                   [Page 92]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


          +-------------+---------------------------------------+
          |       Range | Registration Procedures               |
          +-------------+---------------------------------------+
          |       0-255 | Expert Review                         |
          |    256-9999 | IETF Review or IESG Approval          |
          | 10000-64999 | First Come First Served               |
          | 65000-65535 | Experimental use (no operational use) |
          +-------------+---------------------------------------+

          Table 10: CoAP Content-Formats: Registration Procedures

   In machine-to-machine applications, it is not expected that generic
   Internet media types such as text/plain, application/xml or
   application/octet-stream are useful for real applications in the long
   term.  It is recommended that M2M applications making use of CoAP
   request new Internet media types from IANA indicating semantic
   information about how to create or parse a payload.  For example, a
   Smart Energy application payload carried as XML might request a more
   specific type like application/se+xml or application/se-exi.

12.4.  URI Scheme Registration

   This document contains the request for the registration of the
   Uniform Resource Identifier (URI) scheme "coap".  The registration
   request complies with [RFC4395].

   URI scheme name.
      coap

   Status.
      Permanent.

   URI scheme syntax.
      Defined in Section 6.1 of [RFC7252].

   URI scheme semantics.
      The "coap" URI scheme provides a way to identify resources that
      are potentially accessible over the Constrained Application
      Protocol (CoAP).  The resources can be located by contacting the
      governing CoAP server and operated on by sending CoAP requests to
      the server.  This scheme can thus be compared to the "http" URI
      scheme [RFC2616].  See Section 6 of [RFC7252] for the details of
      operation.

   Encoding considerations.
      The scheme encoding conforms to the encoding rules established for
      URIs in [RFC3986], i.e., internationalized and reserved characters
      are expressed using UTF-8-based percent-encoding.



Shelby, et al.               Standards Track                   [Page 93]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   Applications/protocols that use this URI scheme name.
      The scheme is used by CoAP endpoints to access CoAP resources.

   Interoperability considerations.
      None.

   Security considerations.
      See Section 11.1 of [RFC7252].

   Contact.
      IETF Chair <chair@ietf.org>

   Author/Change controller.
      IESG <iesg@ietf.org>

   References.
      [RFC7252]

12.5.  Secure URI Scheme Registration

   This document contains the request for the registration of the
   Uniform Resource Identifier (URI) scheme "coaps".  The registration
   request complies with [RFC4395].

   URI scheme name.
      coaps

   Status.
      Permanent.

   URI scheme syntax.
      Defined in Section 6.2 of [RFC7252].

   URI scheme semantics.
      The "coaps" URI scheme provides a way to identify resources that
      are potentially accessible over the Constrained Application
      Protocol (CoAP) using Datagram Transport Layer Security (DTLS) for
      transport security.  The resources can be located by contacting
      the governing CoAP server and operated on by sending CoAP requests
      to the server.  This scheme can thus be compared to the "https"
      URI scheme [RFC2616].  See Section 6 of [RFC7252] for the details
      of operation.

   Encoding considerations.
      The scheme encoding conforms to the encoding rules established for
      URIs in [RFC3986], i.e., internationalized and reserved characters
      are expressed using UTF-8-based percent-encoding.




Shelby, et al.               Standards Track                   [Page 94]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   Applications/protocols that use this URI scheme name.
      The scheme is used by CoAP endpoints to access CoAP resources
      using DTLS.

   Interoperability considerations.
      None.

   Security considerations.
      See Section 11.1 of [RFC7252].

   Contact.
      IETF Chair <chair@ietf.org>

   Author/Change controller.
      IESG <iesg@ietf.org>

   References.
      [RFC7252]

12.6.  Service Name and Port Number Registration

   One of the functions of CoAP is resource discovery: a CoAP client can
   ask a CoAP server about the resources offered by it (see Section 7).
   To enable resource discovery just based on the knowledge of an IP
   address, the CoAP port for resource discovery needs to be
   standardized.

   IANA has assigned the port number 5683 and the service name "coap",
   in accordance with [RFC6335].

   Besides unicast, CoAP can be used with both multicast and anycast.

   Service Name.
      coap

   Transport Protocol.
      udp

   Assignee.
      IESG <iesg@ietf.org>

   Contact.
      IETF Chair <chair@ietf.org>

   Description.
      Constrained Application Protocol (CoAP)





Shelby, et al.               Standards Track                   [Page 95]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   Reference.
      [RFC7252]

   Port Number.
      5683

12.7.  Secure Service Name and Port Number Registration

   CoAP resource discovery may also be provided using the DTLS-secured
   CoAP "coaps" scheme.  Thus, the CoAP port for secure resource
   discovery needs to be standardized.

   IANA has assigned the port number 5684 and the service name "coaps",
   in accordance with [RFC6335].

   Besides unicast, DTLS-secured CoAP can be used with anycast.

   Service Name.
      coaps

   Transport Protocol.
      udp

   Assignee.
      IESG <iesg@ietf.org>

   Contact.
      IETF Chair <chair@ietf.org>

   Description.
      DTLS-secured CoAP

   Reference.
      [RFC7252]

   Port Number.
      5684














Shelby, et al.               Standards Track                   [Page 96]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


12.8.  Multicast Address Registration

   Section 8, "Multicast CoAP", defines the use of multicast.  IANA has
   assigned the following multicast addresses for use by CoAP nodes:

   IPv4  -- "All CoAP Nodes" address 224.0.1.187, from the "IPv4
      Multicast Address Space Registry".  As the address is used for
      discovery that may span beyond a single network, it has come from
      the Internetwork Control Block (224.0.1.x, RFC 5771).

   IPv6  -- "All CoAP Nodes" address FF0X::FD, from the "IPv6 Multicast
      Address Space Registry", in the "Variable Scope Multicast
      Addresses" space (RFC 3307).  Note that there is a distinct
      multicast address for each scope that interested CoAP nodes should
      listen to; CoAP needs the Link-Local and Site-Local scopes only.

13.  Acknowledgements

   Brian Frank was a contributor to and coauthor of early versions of
   this specification.

   Special thanks to Peter Bigot, Esko Dijk, and Cullen Jennings for
   substantial contributions to the ideas and text in the document,
   along with countless detailed reviews and discussions.

   Thanks to Floris Van den Abeele, Anthony Baire, Ed Beroset, Berta
   Carballido, Angelo P. Castellani, Gilbert Clark, Robert Cragie,
   Pierre David, Esko Dijk, Lisa Dusseault, Mehmet Ersue, Thomas
   Fossati, Tobias Gondrom, Bert Greevenbosch, Tom Herbst, Jeroen
   Hoebeke, Richard Kelsey, Sye Loong Keoh, Ari Keranen, Matthias
   Kovatsch, Avi Lior, Stephan Lohse, Salvatore Loreto, Kerry Lynn,
   Andrew McGregor, Alexey Melnikov, Guido Moritz, Petri Mutka, Colin
   O'Flynn, Charles Palmer, Adriano Pezzuto, Thomas Poetsch, Robert
   Quattlebaum, Akbar Rahman, Eric Rescorla, Dan Romascanu, David Ryan,
   Peter Saint-Andre, Szymon Sasin, Michael Scharf, Dale Seed, Robby
   Simpson, Peter van der Stok, Michael Stuber, Linyi Tian, Gilman
   Tolle, Matthieu Vial, Maciej Wasilak, Fan Xianyou, and Alper Yegin
   for helpful comments and discussions that have shaped the document.
   Special thanks also to the responsible IETF area director at the time
   of completion, Barry Leiba, and the IESG reviewers, Adrian Farrel,
   Martin Stiemerling, Pete Resnick, Richard Barnes, Sean Turner,
   Spencer Dawkins, Stephen Farrell, and Ted Lemon, who contributed in-
   depth reviews.

   Some of the text has been borrowed from the working documents of the
   IETF HTTPBIS working group.





Shelby, et al.               Standards Track                   [Page 97]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


14.  References

14.1.  Normative References

   [RFC0768]  Postel, J., "User Datagram Protocol", STD 6, RFC 768,
              August 1980.

   [RFC2045]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
              Extensions (MIME) Part One: Format of Internet Message
              Bodies", RFC 2045, November 1996.

   [RFC2046]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
              Extensions (MIME) Part Two: Media Types", RFC 2046,
              November 1996.

   [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.

   [RFC3023]  Murata, M., St. Laurent, S., and D. Kohn, "XML Media
              Types", RFC 3023, January 2001.

   [RFC3629]  Yergeau, F., "UTF-8, a transformation format of ISO
              10646", STD 63, RFC 3629, November 2003.

   [RFC3676]  Gellens, R., "The Text/Plain Format and DelSp Parameters",
              RFC 3676, February 2004.

   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax", STD 66, RFC
              3986, January 2005.

   [RFC4279]  Eronen, P. and H. Tschofenig, "Pre-Shared Key Ciphersuites
              for Transport Layer Security (TLS)", RFC 4279, December
              2005.

   [RFC4395]  Hansen, T., Hardie, T., and L. Masinter, "Guidelines and
              Registration Procedures for New URI Schemes", BCP 35, RFC
              4395, February 2006.

   [RFC5147]  Wilde, E. and M. Duerst, "URI Fragment Identifiers for the
              text/plain Media Type", RFC 5147, April 2008.

   [RFC5198]  Klensin, J. and M. Padlipsky, "Unicode Format for Network
              Interchange", RFC 5198, March 2008.



Shelby, et al.               Standards Track                   [Page 98]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   [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.

   [RFC5246]  Dierks, T. and E. Rescorla, "The Transport Layer Security
              (TLS) Protocol Version 1.2", RFC 5246, August 2008.

   [RFC5280]  Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
              Housley, R., and W. Polk, "Internet X.509 Public Key
              Infrastructure Certificate and Certificate Revocation List
              (CRL) Profile", RFC 5280, May 2008.

   [RFC5480]  Turner, S., Brown, D., Yiu, K., Housley, R., and T. Polk,
              "Elliptic Curve Cryptography Subject Public Key
              Information", RFC 5480, March 2009.

   [RFC5785]  Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known
              Uniform Resource Identifiers (URIs)", RFC 5785, April
              2010.

   [RFC5952]  Kawamura, S. and M. Kawashima, "A Recommendation for IPv6
              Address Text Representation", RFC 5952, August 2010.

   [RFC5988]  Nottingham, M., "Web Linking", RFC 5988, October 2010.

   [RFC6066]  Eastlake, D., "Transport Layer Security (TLS) Extensions:
              Extension Definitions", RFC 6066, January 2011.

   [RFC6347]  Rescorla, E. and N. Modadugu, "Datagram Transport Layer
              Security Version 1.2", RFC 6347, January 2012.

   [RFC6690]  Shelby, Z., "Constrained RESTful Environments (CoRE) Link
              Format", RFC 6690, August 2012.

   [RFC6920]  Farrell, S., Kutscher, D., Dannewitz, C., Ohlman, B.,
              Keranen, A., and P. Hallam-Baker, "Naming Things with
              Hashes", RFC 6920, April 2013.

   [RFC7250]  Wouters, P., Tschofenig, H., Gilmore, J., Weiler, S., and
              T. Kivinen, "Using Raw Public Keys in Transport Layer
              Security (TLS) and Datagram Transport Layer Security
              (DTLS)", RFC 7250, June 2014.






Shelby, et al.               Standards Track                   [Page 99]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   [RFC7251]  McGrew, D., Bailey, D., Campagna, M., and R. Dugal, "AES-
              CCM Elliptic Curve Cryptography (ECC) Cipher Suites for
              Transport Layer Security (TLS)", RFC 7251, June 2014.

14.2.  Informative References

   [BLOCK]    Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP",
              Work in Progress, October 2013.

   [CoAP-MISC]
              Bormann, C. and K. Hartke, "Miscellaneous additions to
              CoAP", Work in Progress, December 2013.

   [EUI64]    IEEE Standards Association, "Guidelines for 64-bit Global
              Identifier (EUI-64 (TM))", Registration Authority
              Tutorials, April 2010, <http://standards.ieee.org/regauth/
              oui/tutorials/EUI64.html>.

   [GROUPCOMM]
              Rahman, A. and E. Dijk, "Group Communication for CoAP",
              Work in Progress, December 2013.

   [HHGTTG]   Adams, D., "The Hitchhiker's Guide to the Galaxy", Pan
              Books ISBN 3320258648, 1979.

   [IEEE1003.1]
              IEEE and The Open Group, "Portable Operating System
              Interface (POSIX)", The Open Group Base Specifications
              Issue 7, IEEE 1003.1, 2013 Edition,
              <http://pubs.opengroup.org/onlinepubs/9699919799/>.

   [IPsec-CoAP]
              Bormann, C., "Using CoAP with IPsec", Work in Progress,
              December 2012.

   [MAPPING]  Castellani, A., Loreto, S., Rahman, A., Fossati, T., and
              E. Dijk, "Guidelines for HTTP-CoAP Mapping
              Implementations", Work in Progress, February 2014.

   [OBSERVE]  Hartke, K., "Observing Resources in CoAP", Work in
              Progress, April 2014.

   [REC-exi-20140211]
              Schneider, J., Kamiya, T., Peintner, D., and R. Kyusakov,
              "Efficient XML Interchange (EXI) Format 1.0 (Second
              Edition)", W3C Recommendation REC-exi-20140211, February
              2014, <http://www.w3.org/TR/2014/REC-exi-20140211/>.




Shelby, et al.               Standards Track                  [Page 100]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   [REST]     Fielding, R., "Architectural Styles and the Design of
              Network-based Software Architectures", Ph.D. Dissertation,
              University of California, Irvine, 2000,
              <http://www.ics.uci.edu/~fielding/pubs/dissertation/
              fielding_dissertation.pdf>.

   [RFC0020]  Cerf, V., "ASCII format for network interchange", RFC 20,
              October 1969.

   [RFC0791]  Postel, J., "Internet Protocol", STD 5, RFC 791, September
              1981.

   [RFC0792]  Postel, J., "Internet Control Message Protocol", STD 5,
              RFC 792, September 1981.

   [RFC0793]  Postel, J., "Transmission Control Protocol", STD 7, RFC
              793, September 1981.

   [RFC1035]  Mockapetris, P., "Domain names - implementation and
              specification", STD 13, RFC 1035, November 1987.

   [RFC3264]  Rosenberg, J. and H. Schulzrinne, "An Offer/Answer Model
              with Session Description Protocol (SDP)", RFC 3264, June
              2002.

   [RFC3280]  Housley, R., Polk, W., Ford, W., and D. Solo, "Internet
              X.509 Public Key Infrastructure Certificate and
              Certificate Revocation List (CRL) Profile", RFC 3280,
              April 2002.

   [RFC3542]  Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei,
              "Advanced Sockets Application Program Interface (API) for
              IPv6", RFC 3542, May 2003.

   [RFC3828]  Larzon, L-A., Degermark, M., Pink, S., Jonsson, L-E., and
              G. Fairhurst, "The Lightweight User Datagram Protocol
              (UDP-Lite)", RFC 3828, July 2004.

   [RFC4086]  Eastlake, D., Schiller, J., and S. Crocker, "Randomness
              Requirements for Security", BCP 106, RFC 4086, June 2005.

   [RFC4443]  Conta, A., Deering, S., and M. Gupta, "Internet Control
              Message Protocol (ICMPv6) for the Internet Protocol
              Version 6 (IPv6) Specification", RFC 4443, March 2006.

   [RFC4492]  Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B.
              Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites
              for Transport Layer Security (TLS)", RFC 4492, May 2006.



Shelby, et al.               Standards Track                  [Page 101]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   [RFC4821]  Mathis, M. and J. Heffner, "Packetization Layer Path MTU
              Discovery", RFC 4821, March 2007.

   [RFC4944]  Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler,
              "Transmission of IPv6 Packets over IEEE 802.15.4
              Networks", RFC 4944, September 2007.

   [RFC5405]  Eggert, L. and G. Fairhurst, "Unicast UDP Usage Guidelines
              for Application Designers", BCP 145, RFC 5405, November
              2008.

   [RFC5489]  Badra, M. and I. Hajjeh, "ECDHE_PSK Cipher Suites for
              Transport Layer Security (TLS)", RFC 5489, March 2009.

   [RFC6090]  McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic
              Curve Cryptography Algorithms", RFC 6090, February 2011.

   [RFC6120]  Saint-Andre, P., "Extensible Messaging and Presence
              Protocol (XMPP): Core", RFC 6120, March 2011.

   [RFC6282]  Hui, J. and P. Thubert, "Compression Format for IPv6
              Datagrams over IEEE 802.15.4-Based Networks", RFC 6282,
              September 2011.

   [RFC6335]  Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S.
              Cheshire, "Internet Assigned Numbers Authority (IANA)
              Procedures for the Management of the Service Name and
              Transport Protocol Port Number Registry", BCP 165, RFC
              6335, August 2011.

   [RFC6655]  McGrew, D. and D. Bailey, "AES-CCM Cipher Suites for
              Transport Layer Security (TLS)", RFC 6655, July 2012.

   [RFC6936]  Fairhurst, G. and M. Westerlund, "Applicability Statement
              for the Use of IPv6 UDP Datagrams with Zero Checksums",
              RFC 6936, April 2013.

   [RFC6960]  Santesson, S., Myers, M., Ankney, R., Malpani, A.,
              Galperin, S., and C. Adams, "X.509 Internet Public Key
              Infrastructure Online Certificate Status Protocol - OCSP",
              RFC 6960, June 2013.

   [RFC6961]  Pettersen, Y., "The Transport Layer Security (TLS)
              Multiple Certificate Status Request Extension", RFC 6961,
              June 2013.

   [RFC7159]  Bray, T., "The JavaScript Object Notation (JSON) Data
              Interchange Format", RFC 7159, March 2014.



Shelby, et al.               Standards Track                  [Page 102]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   [RFC7228]  Bormann, C., Ersue, M., and A. Keranen, "Terminology for
              Constrained-Node Networks", RFC 7228, May 2014.

   [RTO-CONSIDER]
              Allman, M., "Retransmission Timeout Considerations", Work
              in Progress, May 2012.

   [W3CXMLSEC]
              Wenning, R., "Report of the XML Security PAG", W3C XML
              Security PAG, October 2012,
              <http://www.w3.org/2011/xmlsec-pag/pagreport.html>.








































Shelby, et al.               Standards Track                  [Page 103]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


Appendix A.  Examples

   This section gives a number of short examples with message flows for
   GET requests.  These examples demonstrate the basic operation, the
   operation in the presence of retransmissions, and multicast.

   Figure 16 shows a basic GET request causing a piggybacked response:
   The client sends a Confirmable GET request for the resource
   coap://server/temperature to the server with a Message ID of 0x7d34.
   The request includes one Uri-Path Option (Delta 0 + 11 = 11, Length
   11, Value "temperature"); the Token is left empty.  This request is a
   total of 16 bytes long.  A 2.05 (Content) response is returned in the
   Acknowledgement message that acknowledges the Confirmable request,
   echoing both the Message ID 0x7d34 and the empty Token value.  The
   response includes a Payload of "22.3 C" and is 11 bytes long.

   Client  Server
      |      |
      |      |
      +----->|     Header: GET (T=CON, Code=0.01, MID=0x7d34)
      | GET  |   Uri-Path: "temperature"
      |      |
      |      |
      |<-----+     Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d34)
      | 2.05 |    Payload: "22.3 C"
      |      |


    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | 1 | 0 |   0   |     GET=1     |          MID=0x7d34           |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  11   |  11   |      "temperature" (11 B) ...
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | 1 | 2 |   0   |    2.05=69    |          MID=0x7d34           |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |1 1 1 1 1 1 1 1|      "22.3 C" (6 B) ...
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

           Figure 16: Confirmable Request; Piggybacked Response






Shelby, et al.               Standards Track                  [Page 104]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   Figure 17 shows a similar example, but with the inclusion of an non-
   empty Token (Value 0x20) in the request and the response, increasing
   the sizes to 17 and 12 bytes, respectively.

   Client  Server
      |      |
      |      |
      +----->|     Header: GET (T=CON, Code=0.01, MID=0x7d35)
      | GET  |      Token: 0x20
      |      |   Uri-Path: "temperature"
      |      |
      |      |
      |<-----+     Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d35)
      | 2.05 |      Token: 0x20
      |      |    Payload: "22.3 C"
      |      |


    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | 1 | 0 |   1   |     GET=1     |          MID=0x7d35           |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     0x20      |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  11   |  11   |      "temperature" (11 B) ...
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+


    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | 1 | 2 |   1   |    2.05=69    |          MID=0x7d35           |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     0x20      |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |1 1 1 1 1 1 1 1| "22.3 C" (6 B) ...
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

           Figure 17: Confirmable Request; Piggybacked Response











Shelby, et al.               Standards Track                  [Page 105]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   In Figure 18, the Confirmable GET request is lost.  After ACK_TIMEOUT
   seconds, the client retransmits the request, resulting in a
   piggybacked response as in the previous example.

   Client  Server
      |      |
      |      |
      +----X |     Header: GET (T=CON, Code=0.01, MID=0x7d36)
      | GET  |      Token: 0x31
      |      |   Uri-Path: "temperature"
   TIMEOUT   |
      |      |
      +----->|     Header: GET (T=CON, Code=0.01, MID=0x7d36)
      | GET  |      Token: 0x31
      |      |   Uri-Path: "temperature"
      |      |
      |      |
      |<-----+     Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d36)
      | 2.05 |      Token: 0x31
      |      |    Payload: "22.3 C"
      |      |

   Figure 18: Confirmable Request (Retransmitted); Piggybacked Response




























Shelby, et al.               Standards Track                  [Page 106]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   In Figure 19, the first Acknowledgement message from the server to
   the client is lost.  After ACK_TIMEOUT seconds, the client
   retransmits the request.

   Client  Server
      |      |
      |      |
      +----->|     Header: GET (T=CON, Code=0.01, MID=0x7d37)
      | GET  |      Token: 0x42
      |      |   Uri-Path: "temperature"
      |      |
      |      |
      | X----+     Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d37)
      | 2.05 |      Token: 0x42
      |      |    Payload: "22.3 C"
   TIMEOUT   |
      |      |
      +----->|     Header: GET (T=CON, Code=0.01, MID=0x7d37)
      | GET  |      Token: 0x42
      |      |   Uri-Path: "temperature"
      |      |
      |      |
      |<-----+     Header: 2.05 Content (T=ACK, Code=2.05, MID=0x7d37)
      | 2.05 |      Token: 0x42
      |      |    Payload: "22.3 C"
      |      |

   Figure 19: Confirmable Request; Piggybacked Response (Retransmitted)























Shelby, et al.               Standards Track                  [Page 107]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   In Figure 20, the server acknowledges the Confirmable request and
   sends a 2.05 (Content) response separately in a Confirmable message.
   Note that the Acknowledgement message and the Confirmable response do
   not necessarily arrive in the same order as they were sent.  The
   client acknowledges the Confirmable response.

   Client  Server
      |      |
      |      |
      +----->|     Header: GET (T=CON, Code=0.01, MID=0x7d38)
      | GET  |      Token: 0x53
      |      |   Uri-Path: "temperature"
      |      |
      |      |
      |<- - -+     Header: (T=ACK, Code=0.00, MID=0x7d38)
      |      |
      |      |
      |<-----+     Header: 2.05 Content (T=CON, Code=2.05, MID=0xad7b)
      | 2.05 |      Token: 0x53
      |      |    Payload: "22.3 C"
      |      |
      |      |
      +- - ->|     Header: (T=ACK, Code=0.00, MID=0xad7b)
      |      |

             Figure 20: Confirmable Request; Separate Response

























Shelby, et al.               Standards Track                  [Page 108]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   Figure 21 shows an example where the client loses its state (e.g.,
   crashes and is rebooted) right after sending a Confirmable request,
   so the separate response arriving some time later comes unexpected.
   In this case, the client rejects the Confirmable response with a
   Reset message.  Note that the unexpected ACK is silently ignored.

   Client  Server
      |      |
      |      |
      +----->|     Header: GET (T=CON, Code=0.01, MID=0x7d39)
      | GET  |      Token: 0x64
      |      |   Uri-Path: "temperature"
    CRASH    |
      |      |
      |<- - -+     Header: (T=ACK, Code=0.00, MID=0x7d39)
      |      |
      |      |
      |<-----+     Header: 2.05 Content (T=CON, Code=2.05, MID=0xad7c)
      | 2.05 |      Token: 0x64
      |      |    Payload: "22.3 C"
      |      |
      |      |
      +- - ->|     Header: (T=RST, Code=0.00, MID=0xad7c)
      |      |

      Figure 21: Confirmable Request; Separate Response (Unexpected)

   Figure 22 shows a basic GET request where the request and the
   response are Non-confirmable, so both may be lost without notice.

   Client  Server
      |      |
      |      |
      +----->|     Header: GET (T=NON, Code=0.01, MID=0x7d40)
      | GET  |      Token: 0x75
      |      |   Uri-Path: "temperature"
      |      |
      |      |
      |<-----+     Header: 2.05 Content (T=NON, Code=2.05, MID=0xad7d)
      | 2.05 |      Token: 0x75
      |      |    Payload: "22.3 C"
      |      |

       Figure 22: Non-confirmable Request; Non-confirmable Response







Shelby, et al.               Standards Track                  [Page 109]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   In Figure 23, the client sends a Non-confirmable GET request to a
   multicast address: all nodes in link-local scope.  There are 3
   servers on the link: A, B and C.  Servers A and B have a matching
   resource, therefore they send back a Non-confirmable 2.05 (Content)
   response.  The response sent by B is lost.  C does not have matching
   response, therefore it sends a Non-confirmable 4.04 (Not Found)
   response.

   Client  ff02::1  A  B  C
      |       |     |  |  |
      |       |     |  |  |
      +------>|     |  |  |  Header: GET (T=NON, Code=0.01, MID=0x7d41)
      |  GET  |     |  |  |   Token: 0x86
      |             |  |  |   Uri-Path: "temperature"
      |             |  |  |
      |             |  |  |
      |<------------+  |  |  Header: 2.05 (T=NON, Code=2.05, MID=0x60b1)
      |      2.05   |  |  |   Token: 0x86
      |             |  |  |   Payload: "22.3 C"
      |             |  |  |
      |             |  |  |
      |   X------------+  |  Header: 2.05 (T=NON, Code=2.05, MID=0x01a0)
      |      2.05   |  |  |   Token: 0x86
      |             |  |  |   Payload: "20.9 C"
      |             |  |  |
      |             |  |  |
      |<------------------+  Header: 4.04 (T=NON, Code=4.04, MID=0x952a)
      |      4.04   |  |  |   Token: 0x86
      |             |  |  |

      Figure 23: Non-confirmable Request (Multicast); Non-confirmable
                                 Response

Appendix B.  URI Examples

   The following examples demonstrate different sets of Uri options, and
   the result after constructing an URI from them.  In addition to the
   options, Section 6.5 refers to the destination IP address and port,
   but not all paths of the algorithm cause the destination IP address
   and port to be included in the URI.

   o  Input:

         Destination IP Address = [2001:db8::2:1]
         Destination UDP Port = 5683






Shelby, et al.               Standards Track                  [Page 110]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


      Output:

         coap://[2001:db8::2:1]/

   o  Input:

         Destination IP Address = [2001:db8::2:1]
         Destination UDP Port = 5683
         Uri-Host = "example.net"

      Output:

         coap://example.net/

   o  Input:

         Destination IP Address = [2001:db8::2:1]
         Destination UDP Port = 5683
         Uri-Host = "example.net"
         Uri-Path = ".well-known"
         Uri-Path = "core"

      Output:

         coap://example.net/.well-known/core

   o  Input:

         Destination IP Address = [2001:db8::2:1]
         Destination UDP Port = 5683
         Uri-Host = "xn--18j4d.example"
         Uri-Path = the string composed of the Unicode characters U+3053
         U+3093 U+306b U+3061 U+306f, usually represented in UTF-8 as
         E38193E38293E381ABE381A1E381AF hexadecimal

      Output:

         coap://xn--18j4d.example/
         %E3%81%93%E3%82%93%E3%81%AB%E3%81%A1%E3%81%AF

         (The line break has been inserted for readability; it is not
         part of the URI.)









Shelby, et al.               Standards Track                  [Page 111]

 
RFC 7252       The Constrained Application Protocol (CoAP)     June 2014


   o  Input:

         Destination IP Address = 198.51.100.1
         Destination UDP Port = 61616
         Uri-Path = ""
         Uri-Path = "/"
         Uri-Path = ""
         Uri-Path = ""
         Uri-Query = "//"
         Uri-Query = "?&"

      Output:

         coap://198.51.100.1:61616//%2F//?%2F%2F&?%26

Authors' Addresses

   Zach Shelby
   ARM
   150 Rose Orchard
   San Jose, CA  95134
   USA

   Phone: +1-408-203-9434
   EMail: zach.shelby@arm.com


   Klaus Hartke
   Universitaet Bremen TZI
   Postfach 330440
   Bremen  D-28359
   Germany

   Phone: +49-421-218-63905
   EMail: hartke@tzi.org


   Carsten Bormann
   Universitaet Bremen TZI
   Postfach 330440
   Bremen  D-28359
   Germany

   Phone: +49-421-218-63921
   EMail: cabo@tzi.org






Shelby, et al.               Standards Track                  [Page 112]

Html markup produced by rfcmarkup 1.129b, available from https://tools.ietf.org/tools/rfcmarkup/

Welcome¶

Quickstart Guide¶

Preparation¶

Installation¶

Installation¶

Target Environment¶

Dashboard¶

Preparation¶

Installation¶

Dockerized Command Line¶

Preparation¶

Installation¶

Run Test Campaigns¶

Manual Installation¶

OPC-UA Test Suite¶

ETSI and Eclipse Foundation¶

Fuzzing¶

About Eclipse IoT-Testware¶

IoT-Testware Team¶

Objective¶

Conformance Test Methodology and Framework¶

Implementation¶

Glossary¶

References¶

2017¶

2018¶

2019¶

License¶

MQTT Specification¶

1.3 Normative references

1.5.3 UTF-8 encoded strings

Figure 1.1 Structure of UTF-8 encoded strings

Figure 1.2 UTF-8 encoded string non normative example

2 MQTT Control Packet format

Figure 2.1 � Structure of an MQTT Control Packet

2.2 Fixed header

Figure 2.2 - Fixed header format

Table 2.1 - Control packet types

2.2.3 Remaining Length

Table 2.4 Size of Remaining Length field

2.3.1 Packet Identifier

Figure 2.3 - Packet Identifier bytes

Table 2.5 - Control Packets that contain a Packet Identifier

Table 2.6 - Control Packets that contain a Payload

3 MQTT Control Packets

3.1 CONNECT � Client requests a connection to a Server

3.1.1 Fixed header

Figure 3.1 � CONNECT Packet fixed header

Figure 3.2 - Protocol Name bytes

Figure 3.3 - Protocol Level byte

Figure 3.4 - Connect Flag bits

3.1.2.5 Will Flag