-
Notifications
You must be signed in to change notification settings - Fork 8
/
Copy pathopen-impl-https-v1.1-cs01.html
752 lines (747 loc) · 58.2 KB
/
open-impl-https-v1.1-cs01.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
<meta name="description" content="This specification describes the use of HTTP over TLS as a transfer mechanism for OpenC2 messages.">
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
<title>Specification for Transfer of OpenC2 Messages via HTTPS Version 1.1</title>
<link rel="stylesheet" href="https://docs.oasis-open.org/templates/css/markdown-styles-v1.7.3a.css" />
</head>
<body>
<p><img src="https://docs.oasis-open.org/templates/OASISLogo-v3.0.png" alt="OASIS Logo" /></p>
<hr style="page-break-before: avoid" />
<h1big id="specification-for-transfer-of-openc2-messages-via-https-version-11">Specification for Transfer of OpenC2 Messages via HTTPS Version 1.1</h1big>
<h2 id="committee-specification-01">Committee Specification 01</h2>
<h2 id="30-november-2021">30 November 2021</h2>
<p> </p>
<h4 id="this-stage">This stage:</h4>
<p><a href="https://docs.oasis-open.org/openc2/open-impl-https/v1.1/cs01/open-impl-https-v1.1-cs01.md">https://docs.oasis-open.org/openc2/open-impl-https/v1.1/cs01/open-impl-https-v1.1-cs01.md</a> (Authoritative) <br />
<a href="https://docs.oasis-open.org/openc2/open-impl-https/v1.1/cs01/open-impl-https-v1.1-cs01.html">https://docs.oasis-open.org/openc2/open-impl-https/v1.1/cs01/open-impl-https-v1.1-cs01.html</a> <br />
<a href="https://docs.oasis-open.org/openc2/open-impl-https/v1.1/cs01/open-impl-https-v1.1-cs01.pdf">https://docs.oasis-open.org/openc2/open-impl-https/v1.1/cs01/open-impl-https-v1.1-cs01.pdf</a></p>
<h4 id="previous-stage">Previous stage:</h4>
<p><a href="https://docs.oasis-open.org/openc2/open-impl-https/v1.1/csd01/open-impl-https-v1.1-csd01.md">https://docs.oasis-open.org/openc2/open-impl-https/v1.1/csd01/open-impl-https-v1.1-csd01.md</a> (Authoritative) <br />
<a href="https://docs.oasis-open.org/openc2/open-impl-https/v1.1/csd01/open-impl-https-v1.1-csd01.html">https://docs.oasis-open.org/openc2/open-impl-https/v1.1/csd01/open-impl-https-v1.1-csd01.html</a> <br />
<a href="https://docs.oasis-open.org/openc2/open-impl-https/v1.1/csd01/open-impl-https-v1.1-csd01.pdf">https://docs.oasis-open.org/openc2/open-impl-https/v1.1/csd01/open-impl-https-v1.1-csd01.pdf</a></p>
<h4 id="latest-stage">Latest stage:</h4>
<p><a href="https://docs.oasis-open.org/openc2/open-impl-https/v1.1/open-impl-https-v1.1.md">https://docs.oasis-open.org/openc2/open-impl-https/v1.1/open-impl-https-v1.1.md</a> (Authoritative) <br />
<a href="https://docs.oasis-open.org/openc2/open-impl-https/v1.1/open-impl-https-v1.1.html">https://docs.oasis-open.org/openc2/open-impl-https/v1.1/open-impl-https-v1.1.html</a> <br />
<a href="https://docs.oasis-open.org/openc2/open-impl-https/v1.1/open-impl-https-v1.1.pdf">https://docs.oasis-open.org/openc2/open-impl-https/v1.1/open-impl-https-v1.1.pdf</a></p>
<h4 id="technical-committee">Technical Committee:</h4>
<p><a href="https://www.oasis-open.org/committees/openc2/">OASIS Open Command and Control (OpenC2) TC</a></p>
<h4 id="chair">Chair:</h4>
<p>Duncan Sparrell (<a href="mailto:[email protected]">[email protected]</a>), <a href="http://www.sfractal.com/">sFractal Consulting LLC</a></p>
<h4 id="editor">Editor:</h4>
<p>David Lemire (<a href="mailto:[email protected]">[email protected]</a>), <a href="http://www.nsa.gov/">National Security Agency</a></p>
<h4 id="related-work">Related work:</h4>
<p>This specification is related to:</p>
<p><em>Open Command and Control (OpenC2) Language Specification Version 1.0</em>. Edited by Jason Romano and Duncan Sparrell. Latest stage: <a href="https://docs.oasis-open.org/openc2/oc2ls/v1.0/oc2ls-v1.0.html">https://docs.oasis-open.org/openc2/oc2ls/v1.0/oc2ls-v1.0.html</a>.</p>
<p><em>Open Command and Control (OpenC2) Profile for Stateless Packet Filtering Version 1.0</em>. Edited by Joe Brule, Duncan Sparrell and Alex Everett. Latest stage: <a href="https://docs.oasis-open.org/openc2/oc2slpf/v1.0/oc2slpf-v1.0.html">https://docs.oasis-open.org/openc2/oc2slpf/v1.0/oc2slpf-v1.0.html</a>.</p>
<h4 id="abstract">Abstract:</h4>
<p>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. HTTP over TLS is a widely deployed transfer protocol that provides an authenticated, ordered, lossless delivery of uniquely-identified messages. This document specifies the use of HTTP over TLS as a transfer mechanism for OpenC2 Messages. A Testing conformance target is provided to support interoperability testing without security mechanisms.</p>
<h4 id="status">Status:</h4>
<p>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 stage" 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 <a href="https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=openc2#technical">https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=openc2#technical</a>.</p>
<p>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 <a href="https://www.oasis-open.org/committees/openc2/">https://www.oasis-open.org/committees/openc2/</a>.</p>
<p>This specification is provided under the <a href="https://www.oasis-open.org/policies-guidelines/ipr/#Non-Assertion-Mode">Non-Assertion</a> 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 (<a href="https://www.oasis-open.org/committees/openc2/ipr.php">https://www.oasis-open.org/committees/openc2/ipr.php</a>).</p>
<p>Note that any machine-readable content (<a href="https://www.oasis-open.org/policies-guidelines/tc-process#wpComponentsCompLang">Computer Language Definitions</a>) 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.</p>
<h4 id="key-words">Key words:</h4>
<p>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 [<a href="#rfc2119">RFC2119</a>] and [<a href="#rfc8174">RFC8174</a>] when, and only when, they appear in all capitals, as shown here.</p>
<h4 id="citation-format">Citation format:</h4>
<p>When referencing this specification the following citation format should be used:</p>
<p><strong>[OpenC2-HTTPS-v1.1]</strong></p>
<p><em>Specification for Transfer of OpenC2 Messages via HTTPS Version 1.1</em>. Edited by David Lemire. 30 November 2021. OASIS Committee Specification 01. <a href="https://docs.oasis-open.org/openc2/open-impl-https/v1.1/cs01/open-impl-https-v1.1-cs01.html">https://docs.oasis-open.org/openc2/open-impl-https/v1.1/cs01/open-impl-https-v1.1-cs01.html</a>. Latest stage: <a href="https://docs.oasis-open.org/openc2/open-impl-https/v1.1/open-impl-https-v1.1.html">https://docs.oasis-open.org/openc2/open-impl-https/v1.1/open-impl-https-v1.1.html</a>.</p>
<h4 id="notices">Notices</h4>
<p>Copyright © OASIS Open 2021. All Rights Reserved.</p>
<p>Distributed under the terms of the OASIS <a href="https://www.oasis-open.org/policies-guidelines/ipr/">IPR Policy</a>.</p>
<p>The name "OASIS" is a trademark of <a href="https://www.oasis-open.org/">OASIS</a>, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs.</p>
<p>For complete copyright information please see the Notices section in an Appendix below.</p>
<hr />
<h2>Table of Contents</h2>
<ul type="none">
<li><a href="#1-introduction">1 Introduction</a>
<ul type="none">
<li><a href="#11-changes-from-earlier-versions">1.1 Changes from Earlier Versions</a></li>
<li><a href="#12-glossary">1.2 Glossary</a>
<ul type="none">
<li><a href="#121-definition-of-terms">1.2.1 Definition of Terms</a></li>
<li><a href="#122-acronyms-and-abbreviations">1.2.2 Acronyms and Abbreviations</a></li>
<li><a href="#123-document-conventions">1.2.3 Document Conventions</a>
<ul type="none">
<li><a href="#1231-naming-conventions">1.2.3.1 Naming Conventions</a></li>
<li><a href="#1232-font-colors-and-style">1.2.3.2 Font Colors and Style</a></li>
</ul></li>
</ul></li>
</ul></li>
<li><a href="#2-operating-model">2 Operating Model</a></li>
<li><a href="#3-protocol-mappings">3 Protocol Mappings</a>
<ul type="none">
<li><a href="#31-layering-overview">3.1 Layering Overview</a></li>
<li><a href="#32-general-requirements">3.2 General Requirements</a>
<ul type="none">
<li><a href="#321-http-usage">3.2.1 HTTP Usage</a></li>
<li><a href="#322-uri-scheme">3.2.2 URI Scheme</a></li>
<li><a href="#323-tls-usage">3.2.3 TLS Usage</a></li>
<li><a href="#324-authentication">3.2.4 Authentication</a></li>
</ul></li>
<li><a href="#33-openc2-message-format">3.3 OpenC2 Message Format</a>
<ul type="none">
<li><a href="#331-content-type-and-serialization">3.3.1 Content Type and Serialization</a></li>
<li><a href="#332-openc2-message-structure">3.3.2 OpenC2 Message Structure</a></li>
<li><a href="#333-message-identification">3.3.3 Message Identification</a></li>
</ul></li>
<li><a href="#34-openc2-consumer-as-httptls-server">3.4 OpenC2 Consumer as HTTP/TLS Server</a></li>
</ul></li>
<li><a href="#4-conformance">4 Conformance</a>
<ul type="none">
<li><a href="#41-conformance-targets">4.1 Conformance Targets</a></li>
<li><a href="#42-conformance-requirements">4.2 Conformance Requirements</a>
<ul type="none">
<li><a href="#421-testing-target-conformance-requirements">4.2.1 Testing Target Conformance Requirements</a></li>
<li><a href="#422-operations-target-conformance-requirements">4.2.2 Operations Target Conformance Requirements</a></li>
</ul></li>
</ul></li>
<li><a href="#appendix-a-references">Appendix A. References</a>
<ul type="none">
<li><a href="#a1-normative-references">A.1 Normative References</a></li>
<li><a href="#a2-informative-references">A.2 Informative References</a></li>
</ul></li>
<li><a href="#appendix-b-safety-security-and-privacy-considerations">Appendix B. Safety, Security and Privacy Considerations</a></li>
<li><a href="#appendix-c-acknowledgements">Appendix C. Acknowledgements</a>
<ul type="none">
<li><a href="#c1-special-thanks">C.1 Special Thanks</a></li>
<li><a href="#c2-participants">C.2 Participants</a></li>
</ul></li>
<li><a href="#appendix-d-revision-history">Appendix D. Revision History</a></li>
<li><a href="#appendix-e-examples">Appendix E. Examples</a>
<ul type="none">
<li><a href="#e1-http-request--response-examples-consumer-as-http-server">E.1 HTTP Request / Response Examples: Consumer as HTTP Server</a>
<ul type="none">
<li><a href="#e11-producer-http-post-with-openc2-command">E.1.1 Producer HTTP POST with OpenC2 Command</a></li>
<li><a href="#e12-consumer-http-response-with-openc2-response">E.1.2 Consumer HTTP Response with OpenC2 Response</a></li>
</ul></li>
</ul></li>
<li><a href="#appendix-f-notices">Appendix F. Notices</a>
</li>
</ul>
<hr />
<h1 id="1-introduction">1 Introduction</h1>
<p><em>The content in this section is non-normative, except where it is marked normative.</em></p>
<p>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 <em>Command</em> is encoded by a <em>Producer</em> (managing application) and transferred to a <em>Consumer</em> (managed device or virtualized function) using a secure transfer protocol, and the Consumer can respond with status and any requested information.</p>
<p>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 [<a href="#rfc2818">RFC2818</a>]. As described in [<a href="#rfc3205">RFC3205</a>], 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.</p>
<p>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. In addition, a Testing conformance target is defined to support interoperability testing without security mechanisms.</p>
<p>This OpenC2 over HTTPS transfer specification is suitable for operational environments where:</p>
<ul>
<li>Connectivity between OpenC2 Producers and OpenC2 Consumers is:
<ul>
<li>Highly available, with infrequent network outages</li>
<li>Of sufficient bandwidth that no appreciable message delays or dropped packets are experienced</li>
</ul></li>
<li>In-band negotiation of a connection initiated by either Producer or Consumer is possible without requiring an out-of-band signaling network.</li>
<li>The overhead of HTTPS is acceptable.</li>
</ul>
<p>An additional application for this transfer specification is interoperability test environments.</p>
<h2 id="11-changes-from-earlier-versions">1.1 Changes from Earlier Versions</h2>
<p>Changes since v1.0, CS01:</p>
<ul>
<li>Defined a standard Uniform Resource Identifier (URI) scheme and added a corresponding conformance requirement.</li>
<li>Specified the use of the atomic OpenC2 message structure, updated content-type accordingly, and adjusted examples to match</li>
<li>Testing and Operations conformance targets and requirements have been defined to support both secure (HTTPS) and non-secure (HTTP) message transfers with a single specification</li>
<li>Added new section with requirements for message correlation</li>
<li>Restructured to use the updated OASIS work products outline</li>
<li>Other minor changes and corrections have been incorporated based on plug fest and interoperability testing experiences</li>
</ul>
<h2 id="12-glossary">1.2 Glossary</h2>
<h3 id="121-definition-of-terms">1.2.1 Definition of Terms</h3>
<p><em>This section is normative.</em></p>
<ul>
<li><strong>Action</strong>: The task or activity to be performed (e.g., 'deny').</li>
<li><strong>Actuator</strong>: The function performed by the Consumer that executes the Command (e.g., 'Stateless Packet Filtering').</li>
<li><strong>Argument</strong>: A property of a Command that provides additional information on how to perform the Command, such as date/time, periodicity, duration, etc.</li>
<li><strong>Command</strong>: A Message defined by an Action-Target pair that is sent from a Producer and received by a Consumer.</li>
<li><strong>Consumer</strong>: A managed device / application that receives Commands. Note that a single device / application can have both Consumer and Producer capabilities.</li>
<li><strong>Message</strong>: A content- and transport-independent set of elements conveyed between Consumers and Producers.</li>
<li><strong>Producer</strong>: A manager application that sends Commands.</li>
<li><strong>Response</strong>: A Message from a Consumer to a Producer acknowledging a Command or returning the requested resources or status to a previously received Command.</li>
<li><strong>Specifier</strong>: A property or field that identifies a Target or Actuator to some level of precision.</li>
<li><strong>Target</strong>: The object of the Action, i.e., the Action is performed on the Target (e.g., IP Address).</li>
</ul>
<h3 id="122-acronyms-and-abbreviations">1.2.2 Acronyms and Abbreviations</h3>
<p><em>This section is non-normative.</em></p>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Term</th>
<th style="text-align: left;">Expansion</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">0-RTT</td>
<td style="text-align: left;">Zero Round Trip Time</td>
</tr>
<tr class="even">
<td style="text-align: left;">API</td>
<td style="text-align: left;">Application Programming Interface</td>
</tr>
<tr class="odd">
<td style="text-align: left;">HTTP</td>
<td style="text-align: left;">Hypertext Transfer Protocol</td>
</tr>
<tr class="even">
<td style="text-align: left;">HTTPS</td>
<td style="text-align: left;">HTTP over TLS</td>
</tr>
<tr class="odd">
<td style="text-align: left;">IETF</td>
<td style="text-align: left;">Internet Engineering Task Force</td>
</tr>
<tr class="even">
<td style="text-align: left;">IPR</td>
<td style="text-align: left;">Intellectual Property Rights</td>
</tr>
<tr class="odd">
<td style="text-align: left;">JSON</td>
<td style="text-align: left;">JavaScript Object Notation</td>
</tr>
<tr class="even">
<td style="text-align: left;">RFC</td>
<td style="text-align: left;">Request For Comment</td>
</tr>
<tr class="odd">
<td style="text-align: left;">TC</td>
<td style="text-align: left;">Technical Committee</td>
</tr>
<tr class="even">
<td style="text-align: left;">TCP</td>
<td style="text-align: left;">Transmission Control Protocol</td>
</tr>
<tr class="odd">
<td style="text-align: left;">TLS</td>
<td style="text-align: left;">Transport Layer Security</td>
</tr>
</tbody>
</table>
<h3 id="123-document-conventions">1.2.3 Document Conventions</h3>
<h4 id="1231-naming-conventions">1.2.3.1 Naming Conventions</h4>
<ul>
<li><a href="#rfc2119">[RFC2119]</a>/<a href="#rfc8174">[RFC8174]</a> key words (see <a href="#12-terminology">Section 1.2</a>) are in all uppercase.</li>
<li>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).</li>
<li>Words in property names are separated with an underscore (_), while words in string enumerations and type names are separated with a hyphen (-).</li>
<li>The term "hyphen" used here refers to the ASCII hyphen or minus character, which in Unicode is "hyphen-minus", U+002D.</li>
</ul>
<h4 id="1232-font-colors-and-style">1.2.3.2 Font Colors and Style</h4>
<p>The following color, font and font style conventions are used in this document:</p>
<ul>
<li>A fixed width font is used for all type names, property names, and literals.</li>
<li>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 2-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 <a href="#rfc8259">[RFC8259]</a>.</li>
<li>Parts of the example may be omitted for conciseness and clarity. These omitted parts are denoted with the ellipses ("...").</li>
</ul>
<p>Example:</p>
<pre><code>HTTP/1.1 200 OK
Date: Wed, 19 Dec 2018 22:15:00 GMT
Content-type: application/openc2+json;version=1.0
{
"headers": {
"request_id": "0e3d8fa8-0bae-4055-a341-9c97b4f328f7",
"created": 1545257700000,
"from": "...",
"to": [
"..."
]
},
"body": {
"openc2": {
"request": {
"action": "deny",
"target": {
"file": {
"hashes": {
"sha256": "22fe72a34f006ea67d26bb7004e2b6941b5c3953d43ae7ec24d41b1a928a6973"
}
}
}
}
}
}
}
</code></pre>
<hr />
<h1 id="2-operating-model">2 Operating Model</h1>
<p><em>This section is non-normative.</em></p>
<p>This section describes the operating model used when transferring OpenC2 Commands and Responses using HTTPS.</p>
<blockquote>
<p>NOTE: This specification provides for both HTTP and HTTPS message transfer. For convenience HTTPS is used as the general term for the transfer protocol throughout this specification. For non-secure operations using the Testing coformance target "HTTPS" should be read as equivalent to "HTTP".</p>
</blockquote>
<p>Each endpoint of an OpenC2-over-HTTPS interaction has both an OpenC2 role and an HTTP function. OpenC2 Consumers will be HTTP listeners (i.e., servers) so that they can accept connections and receive unsolicited Commands from OpenC2 Producers. OpenC2 Producers act as HTTP clients and transmit Commands to Consumers.</p>
<p>Figure 2 illustrates the Producer / Consumer interactions. A Producer that needs to send OpenC2 Commands initiates a TCP connection to the Consumer. Once the TCP connection is created, a TLS session is initiated to authenticate the endpoints and provide connection confidentiality. The Producer can then issue OpenC2 Commands by sending HTTP requests using the POST method through the TLS connection, with Consumer OpenC2 Responses returned in the HTTP response.</p>
<p><img src="./images/image_2.png" alt="Figure 2 -- OpenC2 Producer / Consumer Interactions" /></p>
<p><strong>Figure 2 -- OpenC2 Producer / Consumer Interactions</strong></p>
<hr />
<h1 id="3-protocol-mappings">3 Protocol Mappings</h1>
<p>The section defines the requirements for using HTTP and TLS with OpenC2, including general requirements and protocol mappings for the operating configuration described in Section 2.</p>
<h2 id="31-layering-overview">3.1 Layering Overview</h2>
<p>When using HTTPS for OpenC2 Message transfer, the layering model is:</p>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Layer</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">OpenC2 Content</td>
<td style="text-align: left;">The <em>OpenC2 Language Specification</em> defines the overall OpenC2 language, and the <em>Actuator Profile(s)</em> implemented by any particular endpoint scopes the OpenC2 actions, targets, arguments, and specifiers that apply when commanding that type of Actuator.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Serialization</td>
<td style="text-align: left;">Serialization converts internal representations of OpenC2 content into a form that can be transmitted and received. The OpenC2 default serialization is JSON.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Message</td>
<td style="text-align: left;">The message layer provides a content- and transport-independent mechanism for conveying requests and responses. A Message consists of serialized content plus a set of metadata items such as content type and version, sender, timestamp, and correlation id. This layer maps the transport-independent definition of each message element to its transport-specific on-the-wire representation.</td>
</tr>
<tr class="even">
<td style="text-align: left;">HTTP</td>
<td style="text-align: left;">The HTTP layer is responsible for conveying request and response Messages, as described in this specification.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">TLS</td>
<td style="text-align: left;">The TLS layer is responsible for authentication of connection endpoints and confidentiality and integrity of transferred Messages.</td>
</tr>
<tr class="even">
<td style="text-align: left;">Lower Layer Transport</td>
<td style="text-align: left;">The lower protocol layers are responsible for end-to-end delivery of Messages. TCP/IP is the most common suite of lower layer protocols used with HTTPS.</td>
</tr>
</tbody>
</table>
<h2 id="32-general-requirements">3.2 General Requirements</h2>
<p>This section defines general requirements for using HTTPS to transfer OpenC2 messages, including HTTP method, message serialization, and TLS requirements.</p>
<h3 id="321-http-usage">3.2.1 HTTP Usage</h3>
<p>OpenC2 Consumers MUST be HTTP listeners to implement the operating model described in <a href="#2-operating-model">Section 2</a>. OpenC2 Consumers acting as HTTP listeners SHOULD listen on:</p>
<ul>
<li>port 80, the registered port for HTTP, when used for testing.</li>
<li>port 443, the registered port for HTTPS, when used for operations.</li>
</ul>
<p>OpenC2 endpoints MUST implement all HTTP functionality required by this specification in accordance with HTTP/1.1 ([<a href="#rfc7230">RFC7230</a>], <em>et. al.</em>). As described in Table 3-1, the only HTTP request method utilized is POST.</p>
<table>
<thead>
<tr class="header">
<th style="text-align: center;">Utilized?</th>
<th style="text-align: left;">HTTP Methods</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: center;">Yes</td>
<td style="text-align: left;">POST</td>
</tr>
<tr class="even">
<td style="text-align: center;">No</td>
<td style="text-align: left;">GET, HEAD, PUT, DELETE, CONNECT, OPTIONS, TRACE</td>
</tr>
</tbody>
</table>
<p><strong>Table 3-1: HTTP Method Use</strong></p>
<p>Each HTTP message body MUST contain only a single OpenC2 Command or Response message. This does not preclude a Producer and Consumer exchanging multiple OpenC2 Command and Response Messages over time during a single HTTPS session. Depending on the set-up, a server and client can have multiple connections, but a sequence of OpenC2 interactions can spread over multiple connections. In some cases the connection may drop, but the session remains open (in an idle state).</p>
<p>All HTTP request and response messages containing OpenC2 payloads SHOULD include the "Cache-control:" header with a value of "no-cache".</p>
<h3 id="322-uri-scheme">3.2.2 URI Scheme</h3>
<p>When transferring OpenC2 Command messages over HTTPS, the Uniform Resource Identifier (URI) structure in Table 3-2 MUST be employed:</p>
<table>
<thead>
<tr class="header">
<th style="text-align: center;">Scheme</th>
<th style="text-align: center;">Address</th>
<th style="text-align: center;">Path</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: center;"><code>https://</code></td>
<td style="text-align: center;"><code>[Consumer Address]</code></td>
<td style="text-align: center;"><code>/.well-known/openc2</code></td>
</tr>
</tbody>
</table>
<p><strong>Table 3-2: OpenC2 HTTPS URI Structure</strong></p>
<p>This path format conforms to the the IETF's "<code>/.well-known/</code>" path prefix for well-known locations, as defined in [<a href="#rfc8615">RFC8615</a>]</p>
<p>OpenC2 Producers sending Command messages MUST POST those messages to the URI defined in Table 3-2.</p>
<p>OpenC2 Consumers acting as HTTP listeners MUST accept Command messages POSTed to the URI defined in Table 3-2.</p>
<h3 id="323-tls-usage">3.2.3 TLS Usage</h3>
<p>HTTPS, the transmission of HTTP over TLS, is specified in Section 2 of [<a href="#rfc2818">RFC2818</a>]. OpenC2 endpoints MUST accept TLS version 1.2 [<a href="#rfc5246">RFC5246</a>] connections or higher for confidentiality, identification, and authentication when sending OpenC2 Messages over HTTPS, and SHOULD accept TLS Version 1.3 [<a href="#rfc8446">RFC8446</a>] or higher connections.</p>
<p>OpenC2 endpoints MUST NOT support any version of TLS prior to v1.2 and MUST NOT support any version of Secure Sockets Layer (SSL).</p>
<p>The implementation and use of TLS SHOULD align with the best currently available security guidance, such as that provided in [<a href="#rfc7525">RFC7525</a>]/BCP 195.</p>
<p>The TLS session MUST use non-NULL ciphersuites for authentication, integrity, and confidentiality. Sessions MAY be renegotiated within these constraints.</p>
<p>OpenC2 endpoints supporting TLS v1.2 MUST NOT use any of the deprecated ciphersuites identified in Appendix A of [<a href="#rfc7540">RFC7540</a>].</p>
<p>OpenC2 endpoints supporting TLS 1.3 MUST NOT implement zero round trip time resumption (0-RTT).</p>
<h3 id="324-authentication">3.2.4 Authentication</h3>
<p>Each participant in an OpenC2 communication MUST authenticate the other participant.</p>
<h2 id="33-openc2-message-format">3.3 OpenC2 Message Format</h2>
<p>This section describes how OpenC2 messages are represented in HTTP requests.</p>
<h3 id="331-content-type-and-serialization">3.3.1 Content Type and Serialization</h3>
<p>While the OpenC2 language is agnostic of serialization, when transferring OpenC2 Messages over HTTP/TLS as described in this specification, the default JSON serialization described in [<a href="#openc2-lang-v10">OpenC2-Lang-v1.0</a>] MUST be supported.</p>
<p>When OpenC2 Messages are sent over HTTPS using the default JSON serialization the message MUST specify the content type <code>"application/openc2+json;version=1.0"</code>.</p>
<h3 id="332-openc2-message-structure">3.3.2 OpenC2 Message Structure</h3>
<p>OpenC2 messages transferred using HTTPS utilize the <code>OpenC2-Message</code> structure defined in Section 3.2 of <a href="#openc2-lang-v10">OpenC2-Lang-v1.0</a>.</p>
<pre><code>Message = Record
1 headers Headers optional
2 body Body
3 signature String optional
Headers = Map{1..*}
1 request_id String optional
2 created ls:Date-Time optional
3 from String optional
4 to String [0..*]
Body = Choice
1 openc2 OpenC2-Content
OpenC2-Content = Choice
1 request OpenC2-Command
2 response OpenC2-Response
3 notification OpenC2-Event
</code></pre>
<p>Since HTTPS provides a point-to-point connection between an OpenC2 Producer and Consumer, the message <code>from</code> and <code>to</code> fields are not needed for addressing. However, OpenC2 Producers and Consumers MAY populate the message headers <code>from</code> and <code>to</code> fields.</p>
<h3 id="333-message-identification">3.3.3 Message Identification</h3>
<p>OpenC2 Producers and Consumers need the ability to identify requests and corresponding responses in order to correlate activity. In addition, it is common for network monitoring tools to similarly track HTTP requests and responses. The OpenC2 message format includes a header field, <code>request_id</code> that is the OpenC2 mechanism for message correlation. The extension header <code>X-Request-ID</code> is commonly used in HTTP traffic for the same purpose. This specification supports the use of these mechanisms in parallel, with the following requirements:</p>
<ul>
<li><p>OpenC2 Producers MUST generate a unique identifying value for OpenC2 Command (i.e., request) messages, and SHOULD use an [<a href="#rfc4122">RFC4122</a>] UUID_v4 identifier for that purpose.</p></li>
<li><p>OpenC2 Producers MUST populate either the HTTP <code>X-Request-ID</code> header or the OpenC2 message header <code>request_id</code> field with the Command message's unique identifying value, and SHOULD populate both locations.</p></li>
<li><p>OpenC2 Consumers MUST return the Command message's unique identifying value in corresponding Response messages.</p></li>
<li><p>When responding to a Command message that did not contain an OpenC2 <code>request_id</code>, the OpenC2 Consumer MUST populate the Response message <code>request_id</code> header field with the unique identifying value from the Command message's <code>X-Request-ID</code> header.</p></li>
</ul>
<h2 id="34-openc2-consumer-as-httptls-server">3.4 OpenC2 Consumer as HTTP/TLS Server</h2>
<p>This section defines HTTP requirements that apply to the OpenC2 Consumer operating as the HTTP server.</p>
<p>As the OpenC2 Consumer is the HTTP server, the Producer initiates a connection to a specific Consumer and directly transmits OpenC2 Messages containing Commands; the HTTP POST method is used, with the OpenC2 Command body contained in the POST body.</p>
<p>The following HTTP request headers MUST be populated when transferring OpenC2 Commands:</p>
<ul>
<li>Host: host name of HTTP server:listening port number (if other than port 80 [testing] / 443 [operations])</li>
<li>Content-type: <code>application/openc2+json;version=1.0</code> (when using the default JSON serialization)</li>
<li>Accept: <code>application/openc2+json;version=1.0</code> (when using the default JSON serialization)</li>
</ul>
<p>The following HTTP response headers MUST be populated when transferring OpenC2 Responses:</p>
<ul>
<li>Content-type: <code>application/openc2+json;version=1.0</code> (when using the default JSON serialization)</li>
</ul>
<p>The following HTTP request and response headers SHOULD be populated when transferring OpenC2 Commands and Responses when the Consumer is the HTTP/TLS server:</p>
<ul>
<li>Date: date-time in the preferred IMF-fixdate format as defined by Section 7.1.1.1 of <a href="#rfc7231">RFC 7231</a>; the conditions for populating the <code>Date:</code> header specified in Section 7.1.1.2 of RFC 7231 SHALL be followed</li>
</ul>
<p>Example messages can be found in Appendix E, section E.1.</p>
<hr />
<h1 id="4-conformance">4 Conformance</h1>
<p>This specification defines conformance targets and requirements for</p>
<ol>
<li>Testing: HTTP without TLS, using port 80</li>
<li>Operations: HTTP with TLS, using port 443</li>
</ol>
<h2 id="41-conformance-targets">4.1 Conformance Targets</h2>
<p>The conformance targets for this specification are:</p>
<ul>
<li><p><strong>Testing</strong>: this conformance target applies to the transfer of OpenC2 messages over HTTP in environments where interoperability is a primary concern and security protections are optional. For example, the Testing conformance target is appropriate for prototyping and "plug fest" interoperability demonstration situations.</p></li>
<li><p><strong>Operations</strong>: this conformance target applies to the transfer of OpenC2 messages over HTTPS in environments where security or the demonstration of secure interoperability is a primary concern.</p></li>
</ul>
<p>The Testing and Operations targets MUST NOT be concurrently available; an OpenC2 Consumer MUST reject non-secure connections when conforming to the Operations target.</p>
<h2 id="42-conformance-requirements">4.2 Conformance Requirements</h2>
<p>This section defines the conformance requirements for the two conformance targets identified in <a href="#41-conformance-targets">Section 4.1</a>.</p>
<h3 id="421-testing-target-conformance-requirements">4.2.1 Testing Target Conformance Requirements</h3>
<p>A conformant implementation of this transfer specification for the <strong>Testing</strong> conformance target MUST:</p>
<ol>
<li>Support JSON serialization as specified in <a href="#331-serialization-and-content-types">Section 3.3.1</a>.</li>
<li>Transfer OpenC2 Messages using the content type defined in <a href="#331-serialization-and-content-types">Section 3.3.1</a>.</li>
<li>Listen for HTTP connections on port 80 as specified in <a href="#321-http-usage">Section 3.2.1</a>.</li>
<li>Use HTTP POST method as specified in Sections <a href="#321-http-usage">3.2.1</a>, and <a href="#34-openc2-consumer-as-httptls-server">3.4</a>, and no other HTTP methods.</li>
<li>Transfer OpenC2 command messages to the HTTP listener using the URI scheme specified in <a href="#322-uri-scheme">Section 3.2.2</a>.</li>
<li>Ensure HTTP request and response messages only contain a single OpenC2 message, as specified in <a href="#321-http-usage">Section 3.2.1</a>.</li>
<li>Employ HTTP methods to send and receive OpenC2 Messages as specified in <a href="#34-openc2-consumer-as-httptls-server">Section 3.4</a>.</li>
<li>Employ only the HTTP response codes specified in [<a href="#openc2-lang-v10">OpenC2-Lang-v1.0</a>], Section 3.3.2.1.</li>
<li>Utilize the OpenC2 message format specified in <a href="#332-openc2-message-structure">Section 3.3.2</a>.</li>
<li>Support the handling of unique message identifiers as specified in <a href="#333-message-identification">Section 3.3.3</a></li>
</ol>
<h3 id="422-operations-target-conformance-requirements">4.2.2 Operations Target Conformance Requirements</h3>
<p>A conformant implementation of this transfer specification for the <strong>Operations</strong> conformance target MUST:</p>
<ol>
<li>Satisfy all of the requirements for the <strong>Testing</strong> conformance target as specified in <a href="#421-testing-target-conformance-requirements">Section 4.2.1</a>.</li>
<li>Listen for HTTPS connections on port 443 as specified in <a href="#321-http-usage">Section 3.2.1</a>, and ignore HTTP connection requests on port 80. <br>NOTE: This requirement supercedes conformance requirement #3 in the Testing conformance list in <a href="#421-testing-target-conformance-requirements">Section 4.2.1</a>.</li>
<li>Implement TLS in accordance with the requirements and restrictions specified in <a href="#323-tls-usage">Section 3.2.2</a>.</li>
<li>Support authentication of remote parties as specified in <a href="#324-authentication">Section 3.2.4</a>.</li>
</ol>
<hr />
<h1 id="appendix-a-references">Appendix A. References</h1>
<h2 id="a1-normative-references">A.1 Normative References</h2>
<h6 id="rfc2119">[RFC2119]</h6>
<p>Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <<a href="http://www.rfc-editor.org/info/rfc2119">http://www.rfc-editor.org/info/rfc2119</a>>.</p>
<h6 id="rfc2818">[RFC2818]</h6>
<p>Rescorla, E., "HTTP Over TLS", RFC 2818, DOI 10.17487/RFC2818, May 2000, <<a href="https://www.rfc-editor.org/info/rfc2818">https://www.rfc-editor.org/info/rfc2818</a>>.</p>
<h6 id="rfc4122">[RFC4122]</h6>
<p>Leach, P., Mealling, M., and R. Salz, "A Universally Unique IDentifier (UUID) URN Namespace", RFC 4122, DOI 10.17487/RFC4122, July 2005, <a href="https://www.rfc-editor.org/info/rfc4122">https://www.rfc-editor.org/info/rfc4122</a>.</p>
<h6 id="rfc5246">[RFC5246]</h6>
<p>Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/RFC5246, August 2008, <<a href="https://www.rfc-editor.org/info/rfc5246">https://www.rfc-editor.org/info/rfc5246</a>>.</p>
<h6 id="rfc7230">[RFC7230]</h6>
<p>Fielding, R., Ed., and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing", RFC 7230, DOI 10.17487/RFC7230, June 2014, <a href="https://www.rfc-editor.org/info/rfc7230">https://www.rfc-editor.org/info/rfc7230</a>.</p>
<h6 id="rfc7231">[RFC7231]</h6>
<p>Fielding, R., Ed., and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 10.17487/RFC7231, June 2014, <a href="https://www.rfc-editor.org/info/rfc7231">https://www.rfc-editor.org/info/rfc7231</a>.</p>
<h6 id="rfc7235">[RFC7235]</h6>
<p>Fielding, R., Ed., and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Authentication", RFC 7235, DOI 10.17487/RFC7235, June 2014, <a href="https://www.rfc-editor.org/info/rfc7235">https://www.rfc-editor.org/info/rfc7235</a>.</p>
<h6 id="rfc7540">[RFC7540]</h6>
<p>Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext Transfer Protocol Version 2 (HTTP/2)", RFC 7540, DOI 10.17487/RFC7540, May 2015, <a href="https://www.rfc-editor.org/info/rfc7540">https://www.rfc-editor.org/info/rfc7540</a>.</p>
<h6 id="rfc8174">[RFC8174]</h6>
<p>Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <<a href="http://www.rfc-editor.org/info/rfc8174">http://www.rfc-editor.org/info/rfc8174</a>>.</p>
<h6 id="rfc8446">[RFC8446]</h6>
<p>Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, <<a href="http://www.rfc-editor.org/info/rfc8446">http://www.rfc-editor.org/info/rfc8446</a>></p>
<h6 id="rfc8615">[RFC8615]</h6>
<p>Nottingham, M., "Well-Known Uniform Resource Identifiers (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, <a href="https://www.rfc-editor.org/info/rfc8615">https://www.rfc-editor.org/info/rfc8615</a></p>
<h6 id="openc2-lang-v10">[OpenC2-Lang-v1.0]</h6>
<p><em>Open Command and Control (OpenC2) Language Specification Version 1.0</em>. Edited by Jason Romano and Duncan Sparrell. Latest version: <a href="http://docs.oasis-open.org/openc2/oc2ls/v1.0/oc2ls-v1.0.html">http://docs.oasis-open.org/openc2/oc2ls/v1.0/oc2ls-v1.0.html</a>.</p>
<h2 id="a2-informative-references">A.2 Informative References</h2>
<h6 id="rfc3205">[RFC3205]</h6>
<p>Moore, K., "On the use of HTTP as a Substrate", BCP 56, RFC 3205, DOI 10.17487/RFC3205, February 2002, <a href="https://www.rfc-editor.org/info/rfc3205">https://www.rfc-editor.org/info/rfc3205</a>.</p>
<h6 id="rfc7525">[RFC7525]</h6>
<p>Sheffer, Y., Holz, R., and P. Saint-Andre, "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 2015, <a href="https://www.rfc-editor.org/info/rfc7525">https://www.rfc-editor.org/info/rfc7525</a>.</p>
<h6 id="rfc8259">[RFC8259]</h6>
<p>Bray, T., ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, <a href="http://www.rfc-editor.org/info/rfc8259">http://www.rfc-editor.org/info/rfc8259</a></p>
<h6 id="slpf">[SLPF]</h6>
<p><em>Open Command and Control (OpenC2) Profile for Stateless Packet Filtering Version 1.0</em>. Edited by Joe Brule, Duncan Sparrell and Alex Everett. Latest version: <a href="http://docs.oasis-open.org/openc2/oc2slpf/v1.0/oc2slpf-v1.0.html">http://docs.oasis-open.org/openc2/oc2slpf/v1.0/oc2slpf-v1.0.html</a></p>
<h6 id="iacd">[IACD]</h6>
<p>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.<a href="https://www.semanticscholar.org/paper/Active-Cyber-Defense-%3A-A-Vision-for-Real-Time-Cyber-Herring-Willett/7c128468ae42584f282578b86439dbe9e8c904a8">https://www.semanticscholar.org/paper/Active-Cyber-Defense-%3A-A-Vision-for-Real-Time-Cyber-Herring-Willett/7c128468ae42584f282578b86439dbe9e8c904a8</a>.<br><br>Willett, Keith D., "Integrated Adaptive Cyberspace Defense: Secure Orchestration", International Command and Control Research and Technology Symposium, June 2015 <a href="https://www.semanticscholar.org/paper/Integrated-Adaptive-Cyberspace-Defense-%3A-Secure-by-Willett/a22881b8a046e7eab11acf647d530c2a3b03b762">https://www.semanticscholar.org/paper/Integrated-Adaptive-Cyberspace-Defense-%3A-Secure-by-Willett/a22881b8a046e7eab11acf647d530c2a3b03b762</a>.</p>
<hr />
<h1 id="appendix-b-safety-security-and-privacy-considerations">Appendix B. Safety, Security and Privacy Considerations</h1>
<p>Security considerations are addressed in <a href="#323-tls-usage">Section 3.2.3 TLS Usage</a>.</p>
<hr />
<h1 id="appendix-c-acknowledgements">Appendix C. Acknowledgements</h1>
<p>The Implementation Considerations Subcommittee was tasked by the OASIS Open Command and Control Technical Committee (OpenC2 TC) which at the time of this submission, had 79 members. The editor wishes to express their gratitude to the members of the OpenC2 TC.</p>
<h2 id="c1-special-thanks">C.1 Special Thanks</h2>
<p>The editor also thanks Jerome Czachor, of Huntington-Ingalls Industries, for assistance with incorporating the new <code>OpenC2-Message</code> structure into this specification.</p>
<h2 id="c2-participants">C.2 Participants</h2>
<p>The following individuals are acknowledged for providing comments, suggested text, and/or participation in CSD ballots or face-to-face meetings:</p>
<ul>
<li>Michelle Barry, AT&T</li>
<li>Toby Considine, University of North Carolina at Chapel Hill</li>
<li>Martin Evandt, University of Oslo</li>
<li>Alex Everett, University of North Carolina at Chapel Hill</li>
<li>John-Mark Gurney, Copado</li>
<li>Christian Hunt, Copado</li>
<li>Dan Johnson, sFractal Consulting LLC</li>
<li>Takahiro Kakumaru, NEC Corporation</li>
<li>David Kemp, National Security Agency</li>
<li>Lauri Korts-Pärn, NECAM</li>
<li>Anthony Librera, AT&T</li>
<li>Patrick Maroney, AT&T</li>
<li>Vasileios Mavroeidis, University of Oslo</li>
<li>Chris Ricard, FS-ISAC</li>
<li>Daniel Riedel, New Context Services, Inc.</li>
<li>Michael Rosa, National Security Agency</li>
<li>Duane Skeen, Northrop Grumman</li>
<li>Duncan Sparrell, sFractal Consulting LLC</li>
<li>Michael Stair, AT&T</li>
<li>Andrew Storms, New Context Services, Inc.</li>
<li>Gerald Stueve, Fornetix</li>
<li>Takayuki Tachihara, Trend Micro</li>
<li>Bill Trost, AT&T</li>
<li>Drew Varner, NineFX</li>
</ul>
<hr />
<h1 id="appendix-d-revision-history">Appendix D. Revision History</h1>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Revision</th>
<th style="text-align: left;">Date</th>
<th style="text-align: left;">Editor</th>
<th style="text-align: left;">Changes Made</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">v1.0-wd01-wip</td>
<td style="text-align: left;">6/15/2018</td>
<td style="text-align: left;">Lemire</td>
<td style="text-align: left;">Initial working draft</td>
</tr>
<tr class="even">
<td style="text-align: left;">v1.0-wd01-wip</td>
<td style="text-align: left;">6/29/2018</td>
<td style="text-align: left;">Lemire</td>
<td style="text-align: left;">1) Added Suitability section (1.6)<br>2) Responded to SC member comments</td>
</tr>
<tr class="odd">
<td style="text-align: left;">v1.0-wd01-wip</td>
<td style="text-align: left;">7/20/2018</td>
<td style="text-align: left;">Lemire</td>
<td style="text-align: left;">1) Additional responses to member comments<br>2) Formatting clean-up for easier conversion to Markdown</td>
</tr>
<tr class="even">
<td style="text-align: left;">v1.0-wd01-wip</td>
<td style="text-align: left;">8/9/2018</td>
<td style="text-align: left;">Lemire</td>
<td style="text-align: left;">Implementing feedback from the July 2018 face-to-face meeting and resolving other comments to reach WD01 version to submit for CSD ballot</td>
</tr>
<tr class="odd">
<td style="text-align: left;">v1.0-wd02-wip</td>
<td style="text-align: left;">8/24/2018</td>
<td style="text-align: left;">Lemire</td>
<td style="text-align: left;">1) Various edits to clarify interactions when the producer is HTTP listener<br>2) Other edits and cleanup in response to document comments and Slack forum discussions</td>
</tr>
<tr class="even">
<td style="text-align: left;">v1.0-wd02-wip</td>
<td style="text-align: left;">8/29/2018</td>
<td style="text-align: left;">Lemire</td>
<td style="text-align: left;">1) Adjustments to content type definitions to distinguish commands and responses<br>2) Made corresponding adjustments to message flow descriptions and sample messages<br>3) Added acknowledgements</td>
</tr>
<tr class="odd">
<td style="text-align: left;">v1.0-wd02-wip</td>
<td style="text-align: left;">8/30/2018</td>
<td style="text-align: left;">Lemire</td>
<td style="text-align: left;">Inserted proposed replacements for sequence diagrams (Figures 2 and 3)</td>
</tr>
<tr class="even">
<td style="text-align: left;">v1.0-wd02-wip</td>
<td style="text-align: left;">8/31/2018</td>
<td style="text-align: left;">Lemire</td>
<td style="text-align: left;">1) Inserted initial draft conformance language (section 4)<br>2) Revised Section 1 content for greater consistency with related OpenC2 specifications<br>3) Revised section 2.1 to merge proposed endpoint role descriptions<br>4) General edit for formatting, readability, consistency, etc.</td>
</tr>
<tr class="odd">
<td style="text-align: left;">v1.0-wd02-wip</td>
<td style="text-align: left;">9/11/2018</td>
<td style="text-align: left;">Lemire</td>
<td style="text-align: left;">1) Reviewed and accepted / rejected comments<br>2) Added placeholders for addressing use of "From" field<br>3) Added statements about using Cache-control</td>
</tr>
<tr class="even">
<td style="text-align: left;">v1.0-wd02-wip</td>
<td style="text-align: left;">9/17/2018</td>
<td style="text-align: left;">Lemire</td>
<td style="text-align: left;">1) Added table to conformance section specifying mapping of Language Spec message elements.<br>2) Clarified certificate mutual authentication requirement.<br>3) Removed language about unsolicited responses from Consumers<br>4) Numbered the conformance items</td>
</tr>
<tr class="odd">
<td style="text-align: left;">v1.0-wd02-wip</td>
<td style="text-align: left;">9/17/2018</td>
<td style="text-align: left;">Lemire</td>
<td style="text-align: left;">1) Removed used of the HTTP "From:" field, and mapped the OpenC2 "from" message element to the authenticated identity of the peer entity<br>2) Updated examples to remove HTTP From:</td>
</tr>
<tr class="even">
<td style="text-align: left;">v1.0-wd02-wip</td>
<td style="text-align: left;">9/19/2018</td>
<td style="text-align: left;">Lemire</td>
<td style="text-align: left;">1) Final clean-up of residual comments and edits to create WD02 package for CSD ballot<br>2) Renamed document to WD03-wip</td>
</tr>
<tr class="odd">
<td style="text-align: left;">v1.0-wd03-wip</td>
<td style="text-align: left;">10/15/2018</td>
<td style="text-align: left;">Lemire</td>
<td style="text-align: left;">1) Reorganized section 1 to align with other OpenC2 specifications<br>2) Reworded section 3.3.1 to properly use MUST / SHALL language<br>3) Clarified requirements wording section 3.2.2 to better indicate TLS version requirements and preferences, and authentication requirements<br>4) Updated Table 4-1 to align with changes to Language Specification Table 3-1</td>
</tr>
<tr class="even">
<td style="text-align: left;">v1.0-wd03-wip</td>
<td style="text-align: left;">10/16/2018</td>
<td style="text-align: left;">Lemire</td>
<td style="text-align: left;">Final clean-up of residual edits to create WD03 package for CSD approval and release for public review</td>
</tr>
<tr class="odd">
<td style="text-align: left;">v1.0-wd03-wip</td>
<td style="text-align: left;">3/27/2019</td>
<td style="text-align: left;">Lemire</td>
<td style="text-align: left;">Resolution of issues from public review 1</td>
</tr>
<tr class="even">
<td style="text-align: left;">v1.0-wd03-wip</td>
<td style="text-align: left;">3/28/2019</td>
<td style="text-align: left;">Lemire</td>
<td style="text-align: left;">Incremented WD version number to 05 prior to CSD ballot to eliminate ambiguity</td>
</tr>
<tr class="odd">
<td style="text-align: left;">v1.0-wd06-wip</td>
<td style="text-align: left;">5/14/2019</td>
<td style="text-align: left;">Lemire</td>
<td style="text-align: left;">Resolution of issues from public review 2 and adjustments for consistency across the suite of specifications</td>
</tr>
<tr class="even">
<td style="text-align: left;">v1.0-wd07</td>
<td style="text-align: left;">6/23/2021</td>
<td style="text-align: left;">Lemire</td>
<td style="text-align: left;">Minor corrections and changes from January 2020 Plug Fest experience and other miscellaneous updates; captures state of working draft prior to reorganization against new OASIS template</td>
</tr>
<tr class="odd">
<td style="text-align: left;">v1.0-wd08</td>
<td style="text-align: left;">7/15/2021</td>
<td style="text-align: left;">Lemire</td>
<td style="text-align: left;">Reorganizes specification to use the new OASIS template</td>
</tr>
<tr class="even">
<td style="text-align: left;">v1.1-wd01</td>
<td style="text-align: left;">9/08/2021</td>
<td style="text-align: left;">Lemire</td>
<td style="text-align: left;">1) Defines a standard Uniform Resource Identifier (URI) scheme and added a corresponding conformance requirement<br>2) Specifies the use of the atomic OpenC2 message structure, updated content-type accordingly, and adjusted examples to match<br>3) Defines Testing and Operations conformance targets and requirements to support both secure (HTTPS) and non-secure (HTTP) message transfers with a single specification<br>4) Restructured document using the updated OASIS work products outline<br>5) Added new section with requirements for message correlation<br>6) Other minor changes and corrections based on plug fest and interoperability testing experiences</td>
</tr>
</tbody>
</table>
<hr />
<h1 id="appendix-e-examples">Appendix E. Examples</h1>
<p><em>This section is non-normative.</em></p>
<p>OpenC2 Messages consist of a set of "message elements" defined in Section 3.2 of [<a href="#openc2-lang-v10">OpenC2-Lang-v1.0</a>]. The example messages below illustrate how this is handled in practice.</p>
<p>A Request-URI ending in <code>/.well-known/openc2</code> is used in all example HTTP requests.</p>
<h2 id="e1-http-request--response-examples-consumer-as-http-server">E.1 HTTP Request / Response Examples: Consumer as HTTP Server</h2>
<p>This section presents the HTTP message structures used when the OpenC2 Consumer acts as the HTTP listener.</p>
<h3 id="e11-producer-http-post-with-openc2-command">E.1.1 Producer HTTP POST with OpenC2 Command</h3>
<p>Example message:</p>
<pre><code>POST /.well-known/openc2 HTTP/1.1
Content-type: application/openc2+json;version=1.0
Date: Wed, 19 Dec 2018 22:15:00 GMT
X-Request-ID: d1ac0489-ed51-4345-9175-f3078f30afe5
{
"headers": {
"request_id": "d1ac0489-ed51-4345-9175-f3078f30afe5",
"created": 1545257700000,
"from": "oc2producer.company.net",
"to": [
"oc2consumer.company.net"
]
},
"body": {
"openc2": {
"request": {
"action": "...",
"target": "...",
"args": "..."
}
}
}
}
</code></pre>
<h3 id="e12-consumer-http-response-with-openc2-response">E.1.2 Consumer HTTP Response with OpenC2 Response</h3>
<p>Example message:</p>
<pre><code>HTTP/1.1 200 OK
Date: Wed, 19 Dec 2018 22:15:10 GMT
Content-type: application/openc2+json;version=1.0
X-Request-ID: d1ac0489-ed51-4345-9175-f3078f30afe5
{
"headers": {
"request_id": "d1ac0489-ed51-4345-9175-f3078f30afe5",
"created": 1545257710000,
"from": "oc2consumer.company.net",
"to": [
"oc2producer.company.net"
]
},
"body": {
"openc2": {
"response": {
"status": 200,
"status_text": "...",
"results": "..."
}
}
}
}
</code></pre>
<hr />
<h1 id="appendix-f-notices">Appendix F. Notices</h1>
<p>Copyright © OASIS Open 2021. All Rights Reserved.</p>
<p>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 <a href="https://www.oasis-open.org/policies-guidelines/ipr/">Policy</a> may be found at the OASIS website.</p>
<p>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.</p>
<p>The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.</p>
<p>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.</p>
<p>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).</p>
<p>[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.]</p>
<p>[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.]</p>
<p>[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.]</p>
<p>The name "OASIS" is a trademark of <a href="https://www.oasis-open.org/">OASIS</a>, 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 <a href="https://www.oasis-open.org/policies-guidelines/trademark/">https://www.oasis-open.org/policies-guidelines/trademark/</a> for above guidance.</p>
</body>
</html>