Specification for Transfer of OpenC2 Messages via MQTT Version 1.0

Committee Specification Draft 02

24 September 2020

This version:

https://docs.oasis-open.org/openc2/transf-mqtt/v1.0/csd02/transf-mqtt-v1.0-csd02.md (Authoritative)

Previous version:

https://docs.oasis-open.org/openc2/transf-mqtt/v1.0/csd01/transf-mqtt-v1.0-csd01.md (Authoritative)

Latest version:

https://docs.oasis-open.org/openc2/transf-mqtt/v1.0/transf-mqtt-v1.0.md (Authoritative)

Technical Committee:

OASIS Open Command and Control (OpenC2) TC


Joe Brule (jmbrule@radium.ncsc.mil), National Security Agency
Duncan Sparrell (duncan@sfractal.com), sFractal Consulting


Joe Brule (jmbrule@radium.ncsc.mil), National Security Agency
Danny Martinez (danny.martinez@hii-tsd.com), G2, Inc.
David Lemire (david.lemire@hii-tsd.com), National Security Agency

This specification is related to:


Open Command and Control (OpenC2) is a concise and extensible language to enable the command and control of cyber defense components, subsystems and/or systems in a manner that is agnostic of the underlying products, technologies, transport mechanisms or other aspects of the implementation. Message Queuing Telemetry Transport (MQTT) is a widely used publish / subscribe (pub/sub) transfer protocol. This specification describes the use of MQTT as a transfer mechanism for OpenC2 messages.


This document was last revised or approved by the OASIS Open Command and Control (OpenC2) TC 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=openc2#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/openc2/.

This specification is provided under the Non-Assertion Mode of the OASIS IPR Policy, the mode chosen when the Technical Committee was established. 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 TC's web page (https://www.oasis-open.org/committees/openc2/ipr.php).

Note that any machine-readable content (Computer Language Definitions) declared Normative for this Work Product is provided in separate plain text files. In the event of a discrepancy between any such plain text file and display content in the Work Product's prose narrative document(s), the content in the separate plain text file prevails.

Citation format:

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


Specification for Transfer of OpenC2 Messages via MQTT Version 1.0. Edited by Joe Brule, Danny Martinez, and David Lemire. 24 September 2020. OASIS Committee Specification Draft 02. https://docs.oasis-open.org/openc2/transf-mqtt/v1.0/csd02/transf-mqtt-v1.0-csd02.html. Latest version: https://docs.oasis-open.org/openc2/transf-mqtt/v1.0/transf-mqtt-v1.0.html.


Copyright © OASIS Open 2020. All Rights Reserved.

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.


As stated in the OASIS IPR Policy, the following three paragraphs in brackets apply to OASIS Standards Final Deliverable documents (Committee Specification, Candidate OASIS Standard, OASIS Standard, or Approved Errata).

[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 Standards Final Deliverable, 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 deliverable.]

[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 OASIS Standards Final Deliverable 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 OASIS Standards Final Deliverable. 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 OASIS Standards Final Deliverable 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 Standards Final Deliverable, 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

This section is non-normative.

NOTE: The content of Section 1 is currently a direct copy-and-paste from previous OpenC2 specifications. It is anticipated that this section will be greatly abbreviated once the relevant material is captured in the OpenC2 Architecture Specification. Relevant content for reviewer is currently in Section 2 and Appendix A.

OpenC2 is a suite of specifications that enables command and control of cyber defense systems and components. OpenC2 typically uses a request-response paradigm where a command is encoded by an OpenC2 Producer (managing application) and transferred to an OpenC2 Consumer (managed device or virtualized function) using a secure transport protocol, and the Consumer can respond with status and any requested information.

OpenC2 allows the application producing the commands to discover the set of capabilities supported by the managed devices. These capabilities permit the managing application to adjust its behavior to take advantage of the features exposed by the managed device. The capability definitions can be easily extended in a noncentralized manner, allowing standard and non-standard capabilities to be defined with semantic and syntactic rigor.

1.1 IPR Policy

This specification is provided under the Non-Assertion Mode of the OASIS IPR Policy, the mode chosen when the Technical Committee was established. 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 TC's web page (https://www.oasis-open.org/committees/openc2/ipr.php).

1.2 Normative References


Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, http://www.rfc-editor.org/info/rfc2119.


Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, http://www.rfc-editor.org/info/rfc8174.


Bray, T., ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, http://www.rfc-editor.org/info/rfc8259


Open Command and Control (OpenC2) Language Specification Version 1.0. Edited by Jason Romano and Duncan Sparrell. Latest version: http://docs.oasis-open.org/openc2/oc2ls/v1.0/oc2ls-v1.0.html.


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.

1.3 Non-Normative References


Rescorla, E. and B. Korver, "Guidelines for Writing RFC Text on Security Considerations", BCP 72, RFC 3552, DOI 10.17487/RFC3552, July 2003, https://www.rfc-editor.org/info/rfc3552.


M. J. Herring, K. D. Willett, "Active Cyber Defense: A Vision for Real-Time Cyber Defense," Journal of Information Warfare, vol. 13, Issue 2, p. 80, April 2014.
Willett, Keith D., "Integrated Adaptive Cyberspace Defense: Secure Orchestration", International Command and Control Research and Technology Symposium, June 2015.


Eclipse Foundation, "Sparkplug (TM) MQTT Topic & Payload Definition", Version 2.2, October 2019, https://www.eclipse.org/tahu/spec/Sparkplug%20Topic%20Namespace%20and%20State%20ManagementV2.2-with%20appendix%20B%20format%20-%20Eclipse.pdf

1.4 Terminology

The terms defined in Section 1.2, Terminology of the MQTT v3.1.1 specification [MQTT-V3.1.1] are applicable to this specification.

The following terms defined in [OpenC2-Lang-v1.0] are applicable to this specification:

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] [RFC8174] when, and only when, they appear in all capitals, as shown here.

A list of acronyms is provided in Appendix X.

1.5 Document Conventions

1.5.1 Naming Conventions

1.5.2 Font Colors and Style

The following color, font and font style conventions are used in this document:



1.6 Overview

OpenC2 is a suite of specifications to command actuators that execute cyber defense functions. These specifications include the OpenC2 Language Specification, Actuator Profiles (APs), and Transfer Specifications. The OpenC2 Language Specification and Actuator Profile specifications focus on the language content and meaning at the producer and consumer of the command and response while the transfer specifications focus on the protocols for their exchange.
In general, there are two types of participants involved in the exchange of OpenC2 messages, as depicted in Figure 1-1:

  1. OpenC2 Producers: An OpenC2 Producer is an entity that creates commands to provide instruction to one or more systems to act in accordance with the content of the command. An OpenC2 Producer may receive and process responses in conjunction with a command.
  2. OpenC2 Consumers: An OpenC2 Consumer is an entity that receives and may act upon an OpenC2 command. An OpenC2 Consumer may create responses that provide any information captured or necessary to send back to the OpenC2 Producer.

The OpenC2 Language Specification defines a language used to compose messages for command and control of cyber defense systems and components. A message consists of a header and a payload (defined as a message body in the OpenC2 Language Specification Version 1.0 and specified in one or more actuator profiles).

The language defines two payload structures:

  1. Command: An instruction from one system known as the OpenC2 "Producer", to one or more systems, the OpenC2 "Consumer(s)", to act on the content of the command.
  2. Response: Any information sent back to the OpenC2 Producer as a result of the command.

no alt title

Figure 1-1. OpenC2 Message Exchange

OpenC2 implementations integrate the related OpenC2 specifications described above with related industry specifications, protocols, and standards. Figure 1-2 depicts the relationships among OpenC2 specifications, and their relationships to other industry standards and environment-specific implementations of OpenC2. Note that the layering of implementation aspects in the diagram is notional, and not intended to preclude any particular approach to implementing the needed functionality (for example, the use of an application-layer message signature function to provide message source authentication and integrity).

no alt title

Figure 1-2. OpenC2 Documentation and Layering Model

OpenC2 is conceptually partitioned into four layers as shown in Table 1-1.

Table 1-1. OpenC2 Protocol Layers

Layer Examples
Function-Specific Content Actuator Profiles
(standard and extensions)
Common Content OpenC2 Language Specification
Message Transfer Specifications
(OpenC2-over-HTTPS, OpenC2-over-CoAP, …)
Secure Transport HTTPS, CoAP, MQTT, OpenDXL, ...

The components of an OpenC2 Command are an action (what is to be done), a target (what is being acted upon), an optional actuator (what is performing the command), and command arguments, which influence how the command is to be performed. An action coupled with a target is sufficient to describe a complete OpenC2 Command. Though optional, the inclusion of an actuator and/or command arguments provides additional precision to a command, when needed.

The components of an OpenC2 Response are a numerical status code, an optional status text string, and optional results. The format of the results, if included, depend on the type or response being transferred.

1.7 Goal

The goal of the OpenC2 Language Specification is to provide a language for interoperating between functional elements of cyber defense systems. This language used in conjunction with OpenC2 Actuator Profiles and OpenC2 Transfer Specifications allows for vendor-agnostic cybertime response to attacks.

The Integrated Adaptive Cyber Defense (IACD) framework defines a collection of activities, based on the traditional OODA (Observe–Orient–Decide–Act) Loop [IACD]:

The goal of OpenC2 is to enable coordinated defense in cyber-relevant time between decoupled blocks that perform cyber defense functions. OpenC2 focuses on the Acting portion of the IACD framework; the assumption that underlies the design of OpenC2 is that the sensing/analytics have been provisioned and the decision to act has been made. This goal and these assumptions guides the design of OpenC2:

2 Operating Model

This section is non-normative. Normative content developed while developing the operating model will eventually be migrated to Section 3.

This section provides an overview of the approach to employing MQTT as a message transfer protocol for OpenC2 messages.

NOTE: Tentative list of Qs the MQTT Transfer Spec should answer; feedback on additional questions or questions that might be out-of-scope / SEP (someone else's problem) is welcome. As consensus is developed on each aspect of the operating model, the corresponding question(s) should be deleted.



The above two questions have an element of registration (making Consumers known to the Producer) vs. discovery (enabling the Producer to know what Consumers are currently active in the Producer's sphere of control).

2.1 Publishers, Subscribers, and Brokers

When transferring OpenC2 Request (AKA command) and Response messages via MQTT, both Producers and Consumers act as both publishers and subscribers:

The MQTT broker and MQTT client software used by Producers and Consumers are beyond the scope of this specification, but are assumed to be conformant with the MQTT v3.1.1 specification [MQTT-V3.1.1]. In the context of OpenC2, and in accordance with the Terminology section (1.2) of [MQTT-V3.1.1]:

2.2 Default Topic Structure

NOTE: a brief Slack discussion on this proposed topic structure can be found here.

The MQTT topic structure below is used to exchange OpenC2 messages. The "oc2" prefix on the topic names segregates OpenC2-related topics from other topics that might exist on the same broker. Topic name components in brackets (e.g., [actuator_profile]) are placeholders for specific values that would be used in implementation. For example, a device that implements the Stateless Packeting Filter AP would subscribe to oc2/cmd/ap/slpf. In addition, each Consumer subscribes to its own device-specific topic using a device identifier, annotated as [device_id], that is known to the OpenC2 Producer(s) that can command that Consumer. The determination of device identifiers is beyond the scope of this specification.

Table DTS: Default Topic Structure

Topic Purpose Producer Consumer
oc2/cmd/all Used to send OpenC2 commands to all devices connected to this MQTT fabric. Pub Sub
oc2/cmd/ap/[actuator_profile] Used to send OpenC2 commands to all instances of specified Actuator Profile. Pub Sub
oc2/cmd/device/[device_id] Used to send OpenC2 commands to all APs within a specific device. Pub Sub
oc2/rsp Used to return OpenC2 response messages. Sub Pub

In order to receive commands intended for its security functions, a Consumer device connected to the broker would subscribe using the following topic filters:

In order to receive responses to the commands is sends, a Producer connected to the broker would subscribe using the following topic filter:

Non-normative Subscription Example

A notional OpenC2 Consumer that implemented actuator profiles alpha and iota and had a device identifier of zulu would subscribe using the following topic filters:

Non-normative Publishing Examples

A notional OpenC2 Producer wishing to command all Consumers that implement actuator profile iota would publish the command to:

A notional OpenC2 Producer wishing to command the individual Consumer with identity zulu would publish the command to:

NOTE (from Duncan Sparrell on Slack): I think a lot of this depends on our model of APs within a ‘device’ (which may be in a ‘device’) and what operates at which level (AP/ inner device/outer device) which we haven’t discussed much. And I think that discussion depend on the ‘lots of little atomic APs’ or ‘fewer compound APs with optional pieceparts’ (which BTW I’ll argue is just the lots of little atomic with an added layer). I think the pub/sub discussion “informs” the atomic/compound AP discussion but I also think reality of todays tech informs the discussion and we should look at how real world products work today

2.3 Message Format

NOTE: The format proposed by Dave Kemp in Language Spec issue #353, or similar, seems appropriate for use with pub/sub protocols. It encapsulates all of the needed information. This draft MQTT Transfer Specification anticipates the adoption of this message format and utilizes its structure.

2.3.1 Content Type and Serialization

NOTE: Implementer fFeedback on this proposed approach to conveying the format of the PUBLISH packet payload is strongly desired. Alternative proposals are welome.

OpenC2 messages are conveyed in the payload of MQTT PUBLISH control packets. As described in the MQTT-V3.1.1, "the content and format of the data is application specific" and therefore meaningless to the broker. This specification allocates the intial two bytes of the payload to inform the PUBLISH packet recipient of the format of the remaining payload. These bytes are structured as shown in Table PFD.

Table PFD: Payload Format Description

Bit 7 6 5 4 3 2 1 0
Byte 1 Fixed Message Type
1 0 0 1 x x x x
Byte 2 Serialization (see list)
x x x x x x x x
Byte 3 First byte of OpenC2 message
x x x x x x x x
Byte 4 ...

The OpenC2 message types in the first byte are assigned as follows:

The second byte identifies the serialization used for the OpenC2 messages. The following serialization values are assigned; all other values are reserved for future use:

The specifics of serializing OpenC2 messages are defined in other OpenC2 specifications.

2.3.2 OpenC2 Message Structure

OpenC2 messages transferred using MQTT utilize the OpenC2-Message structure containing the message elements listed in Section 3.2 of OpenC2-Lang-v1.0.

OpenC2-Message = Record {
    1 content         Content,                  // Message body as specified by msg_type (the ID/Name of Content)
    2 request_id      String optional,          // A unique identifier created by Producer and copied by Consumer into responses
    3 created         Date-Time optional,       // Creation date/time of the content
    4 from            String optional,          // Authenticated identifier of the creator of / authority for a request
    5 to              ArrayOf(String) optional  // Authenticated identifier(s) of the authorized recipient(s) of a message

Content = Choice {
    1 request         OpenC2-Command,           // The initiator of a two-way message exchange.
    2 response        OpenC2-Response,          // A response linked to a request in a two-way message exchange.
    3 notification    OpenC2-Notification       // A (one-way) message that is not a request or response.  (Placeholder)

A Producer sending an OpenC2 request includes its identifier in the message from field, allowing Consumers receiving the request to know its origin. A Consumer sending a response to an OpenC2 request includes its identifier in the message from field, allowing responses from different actuators to be identified by the Producer receiving the response.

When publishing an OpenC2 request, the Producer can use the to field as a filter to provide finer-grained control than is provided by the MQTT Topic Structure and Client topic subscriptions over which Consumers should process any particular message.

2.4 Quality of Service

mqtt-v3.1.1 Section 4.3, Quality of Service Levels and Protocol Flows defines three quality of service (QoS) levels:

QoS 1 is appropriate for most OpenC2 applications and should be specified as the default. Implementers have the option of electing to use QoS 2 where the additional overhead is justified by application requirements. QoS 0 is not recommended for use in OpenC2 messaging.

In accordance with the above, the requirements of mqtt-v3.1.1 Section 4.3.2, QoS1: At least once delivery apply to OpenC2 Producers and Consumers when publishing messages to the MQTT broker.

2.5 MQTT Client Identifier

As described in mqtt-v3.1.1 Section 3.1, CONNECT – Client requests a connection to a Server, the Client Identifier (ClientId) is a required field in the CONNECT control packet. Further requirements are contained in Section, Client Identifier, which defines the ClientId as a UTF-8 string between 1 and 23 bytes long containing only letters and numbers (MQTT servers may accept longer ClientIds). The MQTT specification also permits brokers to accept CONNECT control packets without a ClientId, in which case the broker assigns its own ClientId to the connection. mqtt-v3.1.1 provides no further definition regarding the format or assignment of ClientIds.

The ClientId serves to identify the client to the broker so that the broker can maintain state information about the client. The ClientId has no meaning in the context of OpenC2, it is only meaningful to the MQTT client and broker involved in the connection.

OpenC2 Producers and Consumers using MQTT for message transfer should generate and store a random clientId value that meets the constraints specified in mqtt-v3.1.1 Section, and retain that value for use when establishing a connection to a broker. This clientId should be generated prior to any connection to an MQTT broker, potentially as part of a Consumer initialization process. The clientId for an OpenC2 Consumer is not required to have any meaningful relationship to any identity by which a Producer identifies that consumer in OpenC2 messages.

2.6 Keep-Alive Interval

mqtt-v3.1.1 section provides a keep alive feature where a Client connected to a Broker must send either a Control Packet or a PINGREQ to the broker before a specified time interval has elapsed to prevent the Broker from disconnecting from the Client. The specification notes that "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."

This transfer specification leaves the selection of a keep alive interval to the implementer but defines a value of 5 minutes (300 seconds) as the maximum value for conformant implementations. For reliability, an OpenC2 client should send an MQTT PINGREQ when 95% of the Keep Alive interval has expired without any other control packets being exchanged.

2.7 Will Message

The CONNECT control packet, described in mqtt-v3.1.1, Section 3.1, provides a last will feature that enables connected clients to store a message on the broker to be published to a client-specified topic when the client's network connection is closed. OpenC2 does not use the MQTT last will message feature.

2.8 Clean Session Flag

The MQTT CONNECT control packet includes a flag, "Clean Session" that tells the broker whether the client, identified by its clientId as described in Section 2.5 desires a new session (Clean Session equals true). In MQTT the setting of the "Clean Session" flag for both the previous and the current session is relevant to how the broker handles client state. The behavior is summarized in the following table.

Previous Clean Session Flag
True False
  • No prior state to discard
  • New subscriptions required
  • State discarded on DISCONNECT
  • Prior state discarded
  • New subscriptions required
  • State discarded on DISCONNECT
  • No prior state to discard
  • New subscriptions required
  • State retained on DISCONNECT
  • Prior state retained
  • Buffered messages delivered
  • State retained on DISCONNECT

OpenC2 clients should not request a clean session when connecting to the broker. The use of "Clean Session = false" allows the broker to retain the client's subscriptions, and deliver buffered messages that have accumulated while the client was disconnected. However, OpenC2 implementers using MQTT should be aware that MQTT broker resource constraints may necessitate discarding older traffic if clients are disconnected for extended periods.

A flowchart depicting the broker's logic handling the Clean Session flag is included in Appendix B.

3 Protocol Mapping

TBSL The protocol mapping should be considered tentative until consensus has been achieved on the operating model.

3.1 MQTT Control Packet Usage


OpenC2 Producers and Consumers MUST create and transmit the CONNECT control packet, as specified in in the mqtt-v3.1.1 specification, to establish a connection to the MQTT Broker.

The fields of the CONNECT control packet SHALL be populated as follows:

Region Field Value
FH Remaining Length <computed>
VH Protocol Name - Length 4
VH Protocol Name - Value MQTT
VH Protocol Level 4
VH Connect Flags (bitmap)
Clean Session 0
Will Flag 0
Will QoS 0
Will Retain 0
User Name Flag TBD
Password Flag TBD
VH Keep Alive Number < 300 (seconds)
PL Client Identifier TBD
PL Username TBD
PL Password TBD

In the above table:


OpenC2 Producers and Consumers MUST receive and process the CONNACK control packet, as specified in in the mqtt-v3.1.1 specification, after requesting a connection to the MQTT Broker.


OpenC2 Producers and Consumers MUST create and transmit the PUBLISH control packet, as specified in in the mqtt-v3.1.1 specification, to publish messages using the MQTT broker. Topic selection for publishing OpenC2 request and response messages MUST apply the default topic structure principles described in Section 2.2.

The PUBLISH packet parameters SHALL be set as follows:

3.1.4 PUBACK

OpenC2 Producers and Consumers MUST receive and process the PUBACK control packet, as specified in in the mqtt-v3.1.1 specification, after publishing a message to the MQTT Broker.

3.1.5 PUBREC

Consistent with the guidance in Section 2.4 of this specification to use QoS Level 1, the PUBREC control packet is not normally utilized for OpenC2. Implementers who elect to use QoS Level 2 should implement the PUBREC packet as specified in the mqtt-v3.1.1 specification.

3.1.6 PUBREL

Consistent with the guidance in Section 2.4 of this specification to use QoS Level 1, the PUBREL control packet is not normally utilized for OpenC2 . Implementers who elect to use QoS Level 2 should implement the PUBREL packet as specified in the mqtt-v3.1.1 specification.


Consistent with the guidance in Section 2.4 of this specification to use QoS Level 1, the PUBCOMP control packet is not normally utilized for OpenC2. Implementers who elect to use QoS Level 2 should implement the PUBCOMP packet as specified in the mqtt-v3.1.1 specification.


Producers and Consumers MUST use the SUBSCRIBE control packet, as specified in in the mqtt-v3.1.1 specification to subscribe to a set of topics consistent with the default topic structure defined in Section 2.2. This means that:

Topic wildcards are not normally utilized for OpenC2. However, implementers of OpenC2 Consumers MAY elect to use a wildcard to subscribe to the command topics for all actuator profiles (`oc2/cmd/ap/#) and filter received messages at the Consumer to identify relevant messages.

As defined in Section 2.4, subscribers MUST specify at least QoS level 1 when subscribing to topics. Implementers MAY elect to use QoS level 2 if appropriate for their implementation.

3.1.9 SUBACK

OpenC2 Producers and Consumers MUST receive and process the SUBACK control packet, as specified in in the mqtt-v3.1.1 specification, after transmitting a SUBSCRIBE control packet to the MQTT Broker.


Under normal operating circumstances OpenC2 Producers and Consumers are not expected to unsubscribe from their respective default topic selections, as described in Section 2.2. If a reason arises to unsubscribe from one or more topics, the OpenC2 Producer or Consumer shall use the UNSUBSUBSCRIBE control packet as specified in mqtt-v3.1.1, Section 3.10.


MQTT brokers receiving an UNSUBSCRIBE control packet from an OpenC2 Producer or Consumer shall send an UNSUBACK packet as specified in mqtt-v3.1.1, Section 3.11.

3.1.12 PINGREQ

OpenC2 Producers and Consumers MUST send a PINGREQ control packet to all MQTT brokers with which they are connected if they have not processed any other control packets with 95% of the keep-alive interval defined by the implementer. If the implementer has not otherwise specified a keep-alive interval, 95% of the value specified in Section 2.6 shall be used.


MQTT brokers receiving a PINGREQ control packet from an OpenC2 Producer or Consumer shall send a PINGRESP packet as specified in mqtt-v3.1.1, Section 3.13.


4 Security Considerations

(Note: OASIS strongly recommends that Technical Committees consider issues that could affect security when implementing their specification and document them for implementers and adopters. For some purposes, you may find it required, e.g. if you apply for IANA registration.

While it may not be immediately obvious how your specification might make systems vulnerable to attack, most specifications, because they involve communications between systems, message formats, or system settings, open potential channels for exploit. For example, IETF [RFC3552] lists “eavesdropping, replay, message insertion, deletion, modification, and man-in-the-middle” as well as potential denial of service attacks as threats that must be considered and, if appropriate, addressed in IETF RFCs.

In addition to considering and describing foreseeable risks, this section should include guidance on how implementers and adopters can protect against these risks.

We encourage editors and TC members concerned with this subject to read Guidelines for Writing RFC Text on Security Considerations, IETF [RFC3552], for more information.

Remove this note before submitting for publication.)

5 Conformance

TBSL Conformance requirements will be developed once the protocol mappings have been developed.

(Note: The OASIS TC Process requires that a specification approved by the TC at the Committee Specification Public Review Draft, Committee Specification or OASIS Standard level must include a separate section, listing a set of numbered conformance clauses, to which any implementation of the specification must adhere in order to claim conformance to the specification (or any optional portion thereof). This is done by listing the conformance clauses here. For the definition of "conformance clause," see OASIS Defined Terms.

See "Guidelines to Writing Conformance Clauses":

Remove this note before submitting for publication.)

Appendix A: Message Examples

NOTE: Example message creation and presentation format are work-in-progress and two alternative representations as currently provided. The editors would welcome suggestions for the most useful presentation format.

A.1 Example 1: Connect and Subscribe

Figure A-CAS illustrates the process of the Orchestrator and a Consumer each connecting to the MQTT broker and subscribing to relevant channels. The Consumer supports the notional actuator profiles alpha and iota, and is assigned the identifier abc123.

Figure A-CAS: Connect and Subscribe

Connect and Subscribe Sequence

The Producer and Consumer CONNECT packets for this example are as follows:

Producer and Consumer Connect Cackets

The Consumer SUBSCRIBE and Broker SUBACK packets for this example are as follows:


A.2 Example 2: Command / Response Exchange

The example messages below illustrate the process of an OpenC2 Producer publishing a command to the channel for a specific actuator profile. The examples assume the existence of two notional Consumers identified as Xray and Zulu that both implement the iota AP, and that both such Consumers are subscribed to the corresponding command topic oc2/cmd/ap/iota. The example messages show the exchange between the Producer publishing the Openc2 request and the MQTT broker. A similar exchange then occurs between the broker and every Consumer device subscribed to oc2/cmd/ap/iota to distribute the command to the intended recipients.

The command and response messages in the sequence diagram shown in Figure A-PRR are published with a QoS of 1, which requires the recipient to respond to the PUBLISH packet with a PUBACK packet. If the messages were sent with QoS of 0 no reply from the recipient would be required.

Figure A-PRR: Publish Request and Response

Basic Interaction Sequence

The PUBLISH and PUBACK control packets for this example are as follows; note that the packetId is the only field that changes for each of the publishing exchanges in Figure A-PRR, as that value is assigned by the initiator of each exchange:


Appendix B: Clean Session Flag Handling

The broker's actions in processing the CleanSession flag and ClientId are illustrated in the following flowchart.

Clean Session Flag Handling

Appendix X: Acronyms

Acronym Meaning
AKA Also Known As
AP Actuator Profile
JSON JavaScript Object Notation
TBD To Be Determined
TBSL To Be Specified Later

Appendix Y: Acknowledgments

The following individuals have participated in the creation of this specification and are gratefully acknowledged:

OpenC2 TC Members:

First Name Last Name Company

Appendix Z: Revision History

Revision Date Editor Changes Made
WD01 2020-05-14 David Lemire Initial working draft
WD02 2020-06-02 David Lemire Updates Operating Model section (2.0) and list of questions to be resolved.
WD03 2020-06-15 David Lemire Further updates Operating Model section (2.0) and list of questions to be resolved. Initial presentation of example operating sequences and message. Will be presented as a CSD candidate at the 17 June 2020 TC meeting.
WD03 / CSD01 2020-07-07 David Lemire WD03 approved by OpenC2 TC as CSD01