oasis-tcs/openc2-impl-https

OASIS OpenC2 TC: Repository used by TC members to propose and track changes to the OpenC2 HTTPS implementation specification

openc2-impl-https's Issues

Authentication of OpenC2 Message

Myself and @jmgnc propose that the TCS consider expanding section 3.2.4 Authentication to include a subsection that defines a method for a consumer to digitally sign an OpenC2 request. For example, please see https://docs.aws.amazon.com/general/latest/gr/signing_aws_api_requests.html . This would allow for a consumer or actuator to know that the message it received was initiated by a trusted resource and was not tampered with in-flight. I think it would be useful to describe a preferred mechanism for handling authentication in the transport spec for HTTPS. I expect that this would be desired by orchestrators, such that they could implement a more standard way to authenticate to a consumer.

Clarify explanation of layering of security solutions (HTTPS-10)

Suggested Change: Reword sentence describing layering as notional for greater clarify. Suggestion: "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)."

Justification: Reword to be more general, with illustrative example

"To" message element data format mismatch (HTTPS-209)

Addresses HTTPS-209. In Section 4, page 22:

The “to” entry in the conformance Table 4-1 is not compliant with the Language Spec, since the Language Spec documents this field as an Array Of Strings, which cannot be included in an HTTP Host header.

Endpoint path ambiguity

There is not a definitive endpoint path within the specification other than the examples annex of /openc2 that should be receiving messages. This is likely to result in compatibility issues where varying implementers use differing paths for the same function.
The endpoint path should be defined for compatibility among implementations.

Examples:

• Implementation A, no path specified

POST / HTTP/1.1
Host: device_a.company.net
Content-type: application/openc2-cmd+json;version=1.0
Date: Wed, 19 Dec 2018 22:15:00 GMT
X-Request-ID: d1ac0489-ed51-4345-9175-f3078f30afe5
{	
	"action": ...
	"target": …
	"args": ...
}

• Implementation B, path specified

POST /openc2/cmd HTTP/1.1
Host: device_b.company.net
Content-type: application/openc2-cmd+json;version=1.0
Date: Wed, 19 Dec 2018 22:15:00 GMT
X-Request-ID: d1ac0489-ed51-4345-9175-f3078f30afe5
{	
	"action": ...
	"target": …
	"args": ...
}

X-Correlation-ID details (HTTPS-29)

Dave Lemire wrote:

The HTTPS Transfer Specification does not define an encoding value for the X-Correlation-ID that is used to convey the OpenC2 request_id.

The OpenC2 Language Specification

1. defines request-id as a binary value with a specific maximum size of 128 bits (Section 3.1.2),
   and
2. Specifies base64url encoding for binary values.
   HTTP headers are strings. In the absence of other constraints, the HTTPS Specification should specify base64url encoding for the request-id value carried in the X-Correlation-ID.
   Note: binary encoding is specified in Section 3.1.5 of the Language Specification.

Media Types and Request ID

The Content-type HTTP header in Section 1.5.2 and the content_type message element in section 3.3.1 list should be adjusted to align with the Message Structure of Section 3.3.2.

There are three content_type values:

1. the original application/openc2-cmd+json;version=1.0 when the HTTP body is OpenC2-Command
2. the original application/openc2-rsp+json;version=1.0 when the HTTP body is OpenC2-Response
3. the new application/openc2+json;version=1.0 when the HTTP body is OpenC2-Message, which contains the content OpenC2-Command, OpenC2-Response, or OpenC2-Notification.

So both the old examples in annex B.1 and the current message examples with headers/body are valid, but when the HTTP body is an OpenC2-Message, the Content-type should be application/openc2+json;version=1.0 without the -cmd or -rsp.

I don't have an opinion on if we should document both the old bare content format and the new message format, or just the new.

---

As we discussed with regard to the MQTT correlation value, I suggest that the examples in Annex B.1 include an HTTP X-Request-ID header with the same value as the Message "request_id" header. This ensures that standard web applications that know nothing about OpenC2 can still correlate requests and responses.

Producers SHOULD populate both the HTTP header and the Message header. (The SHOULD allows them to omit the Message request_id field if bandwidth is an issue and consumers are able to handle HTTP headers.)
Consumers MUST insert a copy of the HTTP X-Request-ID header into the Message header if present and the received Message does not contain a request_id field.

Change "specification describes" to "document specifies" in Abstract (HTTPS-6)

Proposed new wording: "This document specifies the use of HTTP over TLS as a transfer mechanism for OpenC2 messages."

Specifying is a stronger word that 'describe' and 'this specification describes ...' reads poorly

Reference to "head information" needs updating (HTTPS-5)

From Paul Knight: reference in first line of Annex B to the Language Spec refers to discussion of "head information", but in current CSD07/CSPRD01 of Language Spec, that discussion is no longer present (apparently changed between CSD05 and CSD07/CSPRD01).

Need to update the language use the "message elements" language, per CSD07/PDR01 of the Language Specification.

command-id vs. request-id (HTTPS-22)

Duncan Sparrell wrote:

Although I agree with the current wording (ie use of "command-id"), presuming I lose the argument in other comments, then "command-id" should change to "request-id"

"Cache-control" header no-cache

The specification in Section 3.2.2 "HTTP Usage" recommends the use of "Cache-control" http header with a value "no-cache" without giving an explanation as to why the no-cache value is preferred in relation to "no-store".

If the requirement is to avoid storing any request or response in any of the systems engaged at an OpenC2 transaction then the no-store value should be used. If the requirement is something else then maybe it needs to be specified.

According to: https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9.2

no-cache
If the no-cache directive does not specify a field-name, then a cache MUST NOT use the response to satisfy a subsequent request without successful revalidation with the origin server. This allows an origin server to prevent caching even by caches that have been configured to return stale responses to client requests.

If the no-cache directive does specify one or more field-names, then a cache MAY use the response to satisfy a subsequent request, subject to any other restrictions on caching. However, the specified field-name(s) MUST NOT be sent in the response to a subsequent request without successful revalidation with the origin server. This allows an origin server to prevent the re-use of certain header fields in a response, while still allowing caching of the rest of the response.
Note: Most HTTP/1.0 caches will not recognize or obey this directive.

no-store
The purpose of the no-store directive is to prevent the inadvertent release or retention of sensitive information (for example, on backup tapes). The no-store directive applies to the entire message, and MAY be sent either in a response or in a request. If sent in a request, a cache MUST NOT store any part of either this request or any response to it. If sent in a response, a cache MUST NOT store any part of either this response or the request that elicited it. This directive applies to both non- shared and shared caches. "MUST NOT store" in this context means that the cache MUST NOT intentionally store the information in non-volatile storage, and MUST make a best-effort attempt to remove the information from volatile storage as promptly as possible after forwarding it.
Even when this directive is associated with a response, users might explicitly store such a response outside of the caching system (e.g., with a "Save As" dialog). History buffers MAY store such responses as part of their normal operation.
The purpose of this directive is to meet the stated requirements of certain users and service authors who are concerned about accidental releases of information via unanticipated accesses to cache data structures. While the use of this directive might improve privacy in some cases, we caution that it is NOT in any way a reliable or sufficient mechanism for ensuring privacy. In particular, malicious or compromised caches might not recognize or obey this directive, and communications networks might be vulnerable to eavesdropping.

Other parts that may need an explanation (minor issue):
3.2.3 "OpenC2 endpoints supporting TLS 1.3 MUST NOT implement zero round trip time resumption (0-RTT)." --- because it has been proved to be vulnerable to replay attacks.

"The TLS session MUST use non-NULL ciphersuites for authentication, integrity, and confidentiality. Sessions MAY be renegotiated within these constraints." --- NULL ciphersuites do not provide confidentiality.

TLS 1.3 (HTTPS-24)

Duncan Sparrell wrote:

Since we are "new" and TLS 1.3 is current best practice and has been for years, shouldn't we require TLS 1.3? Some argue for 1.2 for backwards compatibility, but there are no OpenC2 instantiations operating 1.2 today so there are no devices to be backwards compatible. If the issue is that there are browsers not yet compatable with TLS1.2, note there are no usecases where either the openc2 producer or the openc2 consumer is a browser.

Note: See linked email for more discussion and proposed specific changes.

Remove "JSON" from message lines in Figures 2 and 3 (HTTPS-14)

Suggested Change: Remove "JSON" from description of command and response messages in Figures 2 and 3.

Justification: We should keep the diagram as general as practical and NOT preclude other serializations.

Removed GET from methods table (HTTPS-204)

Addresses HTTPS-204. In Section 3.2.2, page 18:

The spec does not use the HTTP “GET” verb, so the table needs to be corrected.

Remove references to the subcommittees in the layering figure (HTTPS-11)

Suggested Change: Remove references to the subcommittees in the figure

Justification: The section addresses scope of the different specifications, the organization of the TC is not relevant in that context.

"transport independent" (HTTPS-20)

Duncan Sparrell wrote:

"The message layer provides a content- and transport-independent mechanism" is incorrect if the correlation-id is necessary for the cancel command. Assuming the command-id is not added back in the language spec, then "transport-independent" should be removed in this spec

Ballot Comment - Restful API

The HTTPS CSD ballot spec states:
Note that this specification does not describe the use of HTTPS to access a RESTful application programming interface (API) for OpenC2.
Is the spec written such that it CAN NOT be used for a rest API?
Or is just the fact that transferring messages is independent of whether the producer/consumer API is restful? Ie I could make a restful API that complied with this spec, but complying with this spec doesn't make it restful.
Either way, I think the wording should clarify what is meant.
I am worried because the main use I see for this spec is to virtual security technology in the cloud, all of which to my knowledge use restful api's (AWS, Azure, Symantec, McAfee, Cisco, Juniper, etc ad infinitum). It would be a showstopper for me if this spec can not be used for rest api's.

There apparently is some debate on defining a rest API. My definition is whatever the vendors are using. Some example rest api's to current security technology:

• AWS - https://docs.aws.amazon.com/apigateway/api-reference/
• Azure - https://docs.microsoft.com/en-us/rest/api/azure/
• Openstack - https://developer.openstack.org/api-guide/quick-start/
• Palo Alto - http://www.csuc.cat/sites/default/files/docs/albertestevez_einamigracioregles.pdf
• Cisco - https://www.cisco.com/c/en/us/td/docs/switches/datacenter/aci/apic/sw/2-x/rest_cfg/2_1_x/b_Cisco_APIC_REST_API_Configuration_Guide.html
• Juniper - https://www.juniper.net/documentation/en_US/junos/information-products/pathway-pages/rest-api/rest-api.html
• Fortinet - https://docs.fortinet.com/d/fortiauthenticator-rest-api-solution-guide
• Symantc - https://support.symantec.com/en_US/article.DOC9447.html
• McAfee - https://kc.mcafee.com/corporate/index?page=content&id=PD24810

I am voting no unless this statement is removed and replaced with text showing that it's at least possible to use this spec to interface vendors claiming rest api's such as those listed above.

Remove "verbose" from "verbose JSON" (HTTPS-19)

Duncan Sparrell wrote:

I object to the use of the word "verbose". It is unnecessarily pejorative and comes from the previous long-settled arguments on having multiple flavors of json. Right now there is only one json serialization so the adjective adds zero value. It implies the "less verbose" JSON serializations would be standard and conforming, which they are not.

Add links for active cyber defense references (HTTPS-201,-202)

Addresses HTTPS-201 / -202. In Section 1.4, page 9:

Should have a link to the "Active Cyber Defense" paper, which is https://www.semanticscholar.org/paper/Active-Cyber-Defense-%3A-A-Vision-for-Real-Time-Cyber-Herring-Willett/7c128468ae42584f282578b86439dbe9e8c904a8

Should have a link to the "Integrated Adaptive Cyberspace Defense" paper, which is https://www.semanticscholar.org/paper/Integrated-Adaptive-Cyberspace-Defense-%3A-Secure-by-Willett/a22881b8a046e7eab11acf647d530c2a3b03b762

Goal subsection missing (HTTPS-4)

The other two specifications include a Goal subsection in Section 1. If the intent is for the front matter of the three specifications to be aligned and consistent, the Goal section should be added to the HTTPS transfer spec.

Reword sentence for broader audience (HTTPS-13)

Suggested Change: Reword sentence "This specification provides ..." to address audiences beyond implementers. Suggestion: "This specification provides guidance for selection of TLS versions and options when utilizing HTTPS for OpenC2 message transport." and delete subsequent sentence starting "It includes guidance ...".

Justification: More that just the implementation community, can also provide guidance to system integrator, even architects and acquisition community. Deleted sentence intent now covered in reworded sentence.

Use real target from Language Spec in Example (HTTPS-203)

Addresses HTTPS-203. In Section 1.5.2, page 14:

The first example shown for OpenC2 in the spec is not compliant with the spec as it refers to a "user_account" target, which is not part of the language. The very first example that readers see should accurately reflect a compliant command, like a "deny/file/hashes/sha256" command. I can supply an example if necessary, but using "user_account" definitely feels wrong to me at this spot in the document.

Change "transport" to "transfer" (HTTPS-12)

Suggested Change: Change "transport" to "transfer" in phrase "as a transport mechanism for"

Justification: Application layer protocols describe information transfer (ref: SMTP, FTP), whereas transport is a Layer 4 function.

Example messages should use UUIDs (HTTPS-210)

Addresses HTTPS-210. In Sections B.1.1 / B.1.2, pages 24-25:

The Example includes a X-Request-ID header that is acceptable but not aligned with the SHOULD part of the Language Spec, which says that the request_id SHOULD be a UUIDv4. I think our examples SHOULD follow the suggestions of the spec, so this header should be changed to be an actual UUIDv4 value.

Authentication Requirements (HTTPS-27)

Section 3.2.3 states
When mutual authentication is used, endpoints MUST perform full path validation on each certificate, as defined in [RFC5280]
Implicit in this statement is a particular way of doing mutual authentication (ie per RFC5280 certificates). There are other ways to do mutual authentication and I think they should be allowed. I think mutual authentication MUST be done (a different ballot comment) but I think the methods of mutual authentication should be optional, or we should specify several different ways not limited to REFC5280 but also including Single Packet Authentication (SPA) as defined in the Cloud Security Alliance (CSA) Software Defined Perimeter (SDP).

Handling Response = None

There is a conflict between the OpenC2 language concept of controlling the level of response, and the HTTP norm of always requiring a response. The HTTPS specification needs to clarify the proper way to handle the OpenC2 "response = none" case.

This is issue number 8 from the January 2020 Plug Fest / Hackathon

Update Message structure

The message structure in section 3.3.2 should be updated to reflect language spec PR #370 oasis-tcs/openc2-oc2ls#370. Interestingly the 370 structure is shown in the "fonts and colors" example but not in the body.

X-Request-ID should be optional (HTTPS-205)

Addresses HTTPS-205. In Section 3.2.2, page 19:

States that the X-Request-ID header MUST be included, though the language spec says that it is optional for commands that do not “expect” a response (like with “response_requested”: “none”). I think that X-Request-ID SHOULD be supplied but should not be required. That is what the Symantec implementation does, and it works well, as there is no way that the X-Request-ID value can be utilized by this specification (only command_id’s can be queried, not request_id’s currently). NOTE also that section 3.3 on Page 20 adds “if any” after the mention of the X-Request-ID field, so we are not consistent with our wording with respect to this header already.

Add targets as something an AP may define (HTTPS-9)

Suggested Change: Add "or targets" into phrase "may define command arguments [or targets] that are relevant"
Justification: Consistency of actuator profile description across OpenC2 specifications.

Delete "one or more" regarding selection of transfer specifications. (HTTPS-7)

Suggested Change: Delete "one or more" in phrase "should select one or more transfer specifications"

Justification: Running dual or multiple stacks is probably going to be an edge case, so no need to highlight it here when simply stating selecting transfer specifications concisely captures the thought.

Examples message dates should be illustrative (HTTPS-3)

Message examples should use example dates rather than a template, to match the other fields in the examples. Currently the Date field is the one with a template.

Suggest that the example command and response messages and should have representative date values rather than a date-time format template. This applies to all example messages in Annex B, i.e., P19, L35; P20, Ls 4, 13, 31, 46, 55.

Add RFC 7231 to Date reference (HTTPS-16)

Suggested Change: Add "... in HTTP-date format as defined by RFC 7231" to the phrase "Carried in the HTTP Date header"

Justification: Clarity and consistency with the requirements in Section 3.

NOTE: I consider this administrative because it isn't adding anything to the requirements already in the specification.

Unmatched brackets in example (HTTPS-17)

Dave Lemire wrote a suggested change: Add a closing brace to the example response.

Justification: Brackets are unbalanced in the PDF example.

Fix Conformance for Response Codes (HTTPS-208)

Addresses HTTPS-208. In Section 4, page 21:

The conformance sections requires usage of the response codes defined in Section 3.3, Page 20, but there are no response codes listed there. They are contained in the Language Spec itself and should be referenced there, I suppose.

ID / Cancel Command example (HTTPS-18)

Duncan Sparrell wrote:

As I've made clear in meetings and submitted in other comments, I am against using http correlation-ID for the command-id for Producer/Consumer communications at times beyond the message transfer - eg for cancelling a previously issued command. Assuming I lose that battle, I would like a cancel example in Appendix B to show the interaction of the transport and OpenC2 JSON data.

Ballot Comment WD02 - correlation_id

Section 4 (Conformance) contains a statement that conforming implementations must conform with the OpenC2 Language Specification and carry the correlation_id in the HTTP X-Correlation-ID header. There is still debate in the LSC about correlating content inside the message with HTTP header information. I am against crossing layer boundaries and making json content of the command dependent on information from the transport layer. However if I lost that argument, then I believe the transport should be dependent on the command, not the command dependent on the transport. That would require changes to this conformance statement and should also require some text in the body of this document stating the http header X-Correlation-ID is dependent on the command-id.

Remove notifications (HTTPS-21)

Duncan Sparrell wrote:

Section 3.1 - Notification should be removed. It is presumptuous to include and implies a solution not yet agreed to. I disagree with OpenC2 encroaching into Alerting where other specifications already exist.

Mix of links and unlinked text in conformance clauses (HTTPS-15)

Suggested Change: Make all section references in the conformance clause list live links.

Justification: Greater consistency of presentation and improved usability of the specification document.
Resolution:

Need "Accept" header requirement (HTTPS-206)

Addresses HTTPS-206. In Section 3.3, page 20:

An HTTP Request that expects a response needs to also include a “Accept” header with the value of “application/openc2-rsp+json;version=1.0”. The Accept header is standard practice for HTTP-based API’s.

Possible misconception in Section 1.8 Suitability

Section 1.8 in the HTTPS transfer spec elaborates on the requirements for operational environments that want to implement OpenC2 over HTTPS.

The third bullet point remarks that: "The overhead of HTTPS is acceptable (e.g., multiple OpenC2 Command / Response exchanges can be passed through a single HTTPS connection)."

The above sentence indicates that the overhead OF https is derived, among other, from multiple OpenC2 commands through a single HTTPS connection.

The overhead of HTTPS per se is derived from the introduction of TLS over HTTP. It requires more handshakes and as a result, there is an increase in the negotiation time and resources used for that.

Multiple OpenC2 commands over a single HTTPS connection - this is related to bandwidth and throughput.

Finally, the example mentions a single HTTPS connection. Basically that means that the negotiation happens once, reducing any overhead multiple connections and their negotiation would introduce.

A possible solution to the aforementioned would be to remove the example in the parenthesis.

Serialization should not be limited to JSON (HTTPS-1)

Currently, section 3.2.1 states that JSON serialization must be used. Suggest that the language be changed to say that JSON serialization must be supported, so that there are requirement to support JSON for conformance but other serializations aren't precluded.

Remove obsolete "id_ref" from example messages (HTTPS-28)

In an email David Lemire commented:

Several example response messages contain an obsolete "id_ref" field. This field should be deleted.

A search of the PRD01 version of the Language Specification indicates that field has been removed from the response message.

Add non-normative references to IACD documents (HTTPS-8)

IACD papers by Willette and Herring should be non-normative references in all OpenC2 specifications.

Remove "backward" scenario (AKA polling) (HTTPS-23)

Duncan Sparrell wrote:

I have several issues with the "backwards" scenarios where the OpenC2 Consumer (eg the IoT device) controls the communications instead of the OpenC2 Producer (eg the security orchestrator) and would propose to delete these in this initial version of OpenC2.

OpenC2 is new and I think we are making unnecessarily-complicated scenarios for version 1.0. This "backwards" scenario greatly complicates understanding this specification.

Note: Addition detail in the linked email.

Remove GET from conformance (HTTPS-207)

Addresses HTTPS-207. In Section 4, page 21:

The spec does not use the HTTP “GET” verb, so the conformance needs to be corrected.

HTTP header dates should not be required (HTTPS-2)

In Section 3.3, the HTTP request and response headers include dates which are required ("MUST"). Recommend that it be changed to a "SHOULD" to allow for the use-cases that do not need to send date information.

Normative / non-normative language (HTTPS-25)

The OASIS TAB wrote:

Set and then use language for distinguishing normative from non-normative content

Submitted in email.

Details in OASIS JIRA: TAB-1639.

Require Mutual Authentication (HTTPS-26)

Section 3.2.3 states
When deployed in an operational environment, OpenC2 endpoints MUST support basic authentication and SHOULD support mutual authentication.
I the the SHOULD should be a SHALL. I say should be because I won't vote no based on this but I do not know of documented use cases where a security device would accept commands from an unauthenticated openc2 command producer. Ie if the openc2 consumer is the server (preferred configuration) I believe it MUST authenticate the openc2 producer. If someone documents a use case where they can demonstrate the risks are worth saving the cost of mutual authentication, then I will stop bringing this up. But if we do leave it as SHOULD, then I think we need more words pointing out the security risks of not being mutually authenticated.