diff --git a/images/MessageFlow.png b/images/MessageFlow.png new file mode 100644 index 0000000..1c86050 Binary files /dev/null and b/images/MessageFlow.png differ diff --git a/images/OC2LayeringModel.png b/images/OC2LayeringModel.png new file mode 100644 index 0000000..5706027 Binary files /dev/null and b/images/OC2LayeringModel.png differ diff --git a/openc2-impl-https-v1.0.md b/openc2-impl-https-v1.0.md index 978cbbc..ce489c2 100644 --- a/openc2-impl-https-v1.0.md +++ b/openc2-impl-https-v1.0.md @@ -88,16 +88,26 @@ The name "OASIS" is a trademark of [OASIS](https://www.oasis-open.org/), the own _This section is non-normative._ -OpenC2 is a suite of specifications to achieve command and control of cyber defense functions. These specifications include the OpenC2 Language Specification, Actuator Profiles, and Transfer Specifications. This transfer specification defines the procedures and conventions used when employing Hypertext Transfer Protocol (HTTP) and Transport Layer Security (TLS) for the transfer of OpenC2 command and response messages between OpenC2 Producers and Consumers. This specification is one of an expected portfolio of transfer specifications; implementers of OpenC2 should select one or more transfer specifications, consistent with the characteristics and requirements of their cyber ecosystem. +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](https://www.oasis-open.org/policies-guidelines/ipr#Non-Assertion-Mode) Mode of the [OASIS IPR Policy](https://www.oasis-open.org/policies-guidelines/ipr), 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). +This specification is provided under the [Non-Assertion](https://www.oasis-open.org/policies-guidelines/ipr#Non-Assertion-Mode) 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 Terminology +* **Action**: The task or activity to be performed (e.g., 'deny'). +* **Actuator**: The entity that performs the action (e.g., 'Stateless Packet Filtering'). +* **Command**: A message defined by an action-target pair that is sent from a producer and received by a consumer. +* **Consumer**: A managed device / application that receives Commands. Note that a single device / application can have both consumer and producer capabilities. +* **Producer**: A manager application that sends Commands. +* **Response**: A message from a consumer to a producer acknowledging a command or returning the requested resources or status to a previously received request. +* **Target**: The object of the action, i.e., the action is performed on the target (e.g., IP Address). + +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 [[BCP 14, RFC2119](#rfc2119)] [[RFC8174](#rfc8174)] when, and only when, they appear in all capitals, as shown here. + A list of acronyms is provided in [Annex A](#annex-a-acronyms). -### 1.2.1 Requirement Keywords -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [[RFC2119](#RFC2119)] and [[RFC8174](#RFC8174)] when, and only when, they appear in all capitals, as shown here. ## 1.3 Normative References ###### [RFC2119] @@ -132,10 +142,24 @@ _Open Command and Control (OpenC2) Profile for Stateless Packet Filtering Versio 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. ## 1.5 Document Conventions + +### 1.5.1 Naming Conventions +* RFC2119/RFC8174 key words (see section 1.2) are in all uppercase. +* All property names and literals are in lowercase, except when referencing canonical names defined in another standard (e.g., literal values from an IANA registry). +* All words in structure component names are capitalized and are separated with a hyphen, e.g., ACTION, TARGET, TARGET-SPECIFIER. +* Words in property names are separated with an underscore (_), while words in string enumerations and type names are separated with a hyphen (-). +* The term "hyphen" used here refers to the ASCII hyphen or minus character, which in Unicode is "hyphen-minus", U+002D. +* All type names, property names, object names, and vocabulary terms are between three and 40 characters long. + +### 1.5.2 Font Colors and Style The following color, font and font style conventions are used in this document: -* All examples in this document are formatted in fixed font, with straight quotes, black text, a light grey background, and 4-space indentation. -* Parts of the example may be omitted for conciseness and clarity. These omitted parts are denoted with an ellipse (...). +* A fixed width font is used for all type names, property names, and literals. + +* Property names are in bold style – **'created_at'**. + +* All examples in this document are expressed in JSON. They are in fixed width font, with straight quotes, black text and a light shaded background, and 4-space indentation. JSON examples in this document are representations of JSON Objects. They should not be interpreted as string literals. The ordering of object keys is insignificant. Whitespace before or after JSON structural characters in the examples are insignificant [[RFC8259](#rfc8259)]. +* Parts of the example may be omitted for conciseness and clarity. These omitted parts are denoted with the ellipses (...). Example: @@ -144,56 +168,92 @@ HTTP/1.1 200 OK Date: Wed, 19 Dec 2018 22:15:00 GMT Content-type: application/openc2-cmd+json;version=1.0 X-Request-ID: id_1234 - -{ - "action": "query" - "target": "command" +{ + "action": "contain", + "target": { + "user_account": { + "user_id": "fjbloggs", + "account_type": "windows-local" + } + } } ``` ## 1.6 Overview -OpenC2 is a set of specifications to achieve command and control of cyber defense functions. These specifications include the OpenC2 Language Specification, Actuator Profiles, and Transfer Specifications. The OpenC2 Language Specification and Actuator Profile(s) specifications focus on the standard at the origin and destination of the command while the transfer specifications focus on the protocols for the commands and responses in transit. +OpenC2 is a suite of specifications to command actuators that execute cyber defense functions. These specifications include the OpenC2 Language Specification, Actuator Profiles, 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 [[OpenC2-Lang-v1.0](#openc2-lang-v10)] provides the semantics for the essential elements of the language, the structure for commands and responses, and the schema that defines the proper syntax for the language elements that represents the command or response. -* OpenC2 Actuator Profiles specify the subset of the OpenC2 language relevant in the context of specific actuator functions. Cyber defense components, devices, systems and/or instances may (in fact are likely) to implement multiple actuator profiles, such as Stateless Packet Filtering. Actuator profiles extend the language by defining specifiers that identify the actuator to the required level of precision and may define command arguments that are relevant and/or unique to those actuator functions. +* OpenC2 Actuator Profiles specify the subset of the OpenC2 language relevant in the context of specific actuator functions. Cyber defense components, devices, systems and/or instances may (in fact are likely) to implement multiple actuator profiles. Actuator profiles extend the language by defining specifiers that identify the actuator to the required level of precision. Actuator Profiles may define command arguments and targets that are relevant and/or unique to those actuator functions. * OpenC2 Transfer Specifications utilize existing protocols and standards to implement OpenC2 in specific environments. These standards are used for communications and security functions beyond the scope of the language, such as message transfer encoding, authentication, and end-to-end transport of OpenC2 messages. -[OpenC2-Lang-v1.0] defines a language used to compose messages for command and control of cyber defense systems and components. A message consists of a header (defined in this specification) 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: +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 captured or necessary to send back to the OpenC2 Producer that issued the Command i.e., the OpenC2 Consumer’s response to the OpenC2 Producer. +2. **Response**: Any information sent back to the OpenC2 Producer as a result of the command. -In general, there are two types of participants involved in the exchange of OpenC2 messages: +![no alt title](./images/MessageFlow.png) -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 acts on an OpenC2 command. An OpenC2 Consumer may create responses that provide any information captured or necessary to send back to the OpenC2 Producer. +**Figure 1-1. OpenC2 Message Exchange** -OpenC2 implementations integrate the related OpenC2 specifications described above with related industry specifications, protocols, and standards. Figure 1 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, e.g., the use of an application-layer message signature function to provide message source authentication and integrity. +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](./images/image_1.png) +![no alt title](./images/OC2LayeringModel.png ) -**Figure 1 -- OpenC2 Documentation and Layering Model** +**Figure 1-2. OpenC2 Documentation and Layering Model** -This document specifies the use of Hypertext Transfer Protocol (HTTP) over Transport Layer Security (TLS) as a transport mechanism for OpenC2 messages; this HTTP/TLS layering is typically referred to as HTTPS [[RFC2818](#rfc2818)]. As described in [[RFC3205](#rfc3205)], HTTP has become a common "substrate" for information transfer for other application-level protocols. The broad availability of HTTP makes it a useful option for OpenC2 message transport in support of prototyping, interoperability testing, and for operational use in environments where appropriate security protections can be provided. Similarly, TLS is a mature and widely-used protocol for securing information transfers in TCP/IP network environments. This specification provides guidance for the selection of TLS versions and options when utilizing HTTPS for OpenC2 message transport. +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](http://docs.oasis-open.org/openc2/oc2ls/v1.0/oc2ls-v1.0.html) | +| Message | Transfer Specifications
(OpenC2-over-HTTPS, OpenC2-over-CoAP, …) | +| Secure Transport | HTTPS, CoAP, MQTT, OpenDXL, ... | + +* The **Secure Transport** layer provides a communication path between the producer and the consumer. OpenC2 can be layered over any standard transport protocol. +* The **Message** layer provides a transport- and content-independent mechanism for conveying requests, responses, and notifications. A transfer specification maps transport-specific protocol elements to a transport-independent set of message elements consisting of content and associated metadata. +* The **Common Content** layer defines the structure of OpenC2 commands and responses and a set of common language elements used to construct them. +* The **Function-specific Content** layer defines the language elements used to support a particular cyber defense function. An actuator profile defines the implementation conformance requirements for that function. OpenC2 Producers and Consumers will support one or more profiles. + + +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](#iacd)]: +The Integrated Adaptive Cyber Defense (IACD) framework defines a collection of activities, based on the traditional OODA (Observe–Orient–Decide–Act) Loop [IACD]: * Sensing: gathering of data regarding system activities * Sense Making: evaluating data using analytics to understand what's happening * Decision Making: determining a course-of-action to respond to system events * Acting: Executing the course-of-action -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: +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: -* **Technology Agnostic:** The OpenC2 language defines a set of abstract atomic cyber defense actions in a platform and product agnostic manner +* **Technology Agnostic:** The OpenC2 language defines a set of abstract atomic cyber defense actions in a platform and implementation agnostic manner * **Concise:** An OpenC2 command is intended to convey only the essential information required to describe the action required and can be represented in a very compact form for communications-constrained environments * **Abstract:** OpenC2 commands and responses are defined abstractly and can be encoded and transferred via multiple schemes as dictated by the needs of different implementation environments * **Extensible:** While OpenC2 defines a core set of actions and targets for cyber defense, the language is expected to evolve with cyber defense technologies, and permits extensions to accommodate new cyber defense technologies. ## 1.8 Suitability +This document specifies the use of Hypertext Transfer Protocol (HTTP) over Transport Layer Security (TLS) as a transfer mechanism for OpenC2 messages; +this HTTP/TLS layering is typically referred to as HTTPS [[RFC2818](#rfc2818)]. +As described in [[RFC3205](#rfc3205)], HTTP has become a common "substrate" for information transfer for other application-level protocols. +The broad availability of HTTP makes it a useful option for OpenC2 message transport in support of prototyping, interoperability testing, and for operational use in environments where appropriate security protections can be provided. +Similarly, TLS is a mature and widely-used protocol for securing information transfers in TCP/IP network environments. +This specification provides guidance to the OpenC2 implementation community when utilizing HTTPS for OpenC2 message transport. +It includes guidance for selection of TLS versions and options suitable for use with OpenC2. + This OpenC2 over HTTPS transfer specification is suitable for operational environments where: * Connectivity between OpenC2 producers and OpenC2 consumers is: @@ -206,10 +266,10 @@ An additional application for this transfer specification is interoperability te --- # 2 Operating Model -This section describes the operating model used when transferring OpenC2 command and responses using HTTPS. - _This section is non-normative._ +This section describes the operating model used when transferring OpenC2 command and responses using HTTPS. + Each endpoint of an OpenC2-over-HTTPS interaction has both an OpenC2 role and an HTTP function. OpenC2 Consumers will be HTTP listeners so that they can accept connections and receive unsolicited commands from OpenC2 Producers. OpenC2 Producers act as 'HTTP clients' and transmit commands to Consumers.