idnits 2.17.1 draft-field-mile-rolie-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 109 instances of too long lines in the document, the longest one being 94 characters in excess of 72. ** The abstract seems to contain references ([RFC6545], [RFC6546], [RFC5070]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. -- The document has examples using IPv4 documentation addresses according to RFC6890, but does not use any IPv6 documentation addresses. Maybe there should be IPv6 examples, too? Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 528 has weird spacing: '...lection href=...' == Line 936 has weird spacing: '...lection href=...' == Line 940 has weird spacing: '...lection href=...' == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (August 15, 2013) is 3905 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 1642 == Unused Reference: 'XMLencrypt' is defined on line 1798, but no explicit reference was found in the text == Unused Reference: 'XMLsig' is defined on line 1803, but no explicit reference was found in the text == Unused Reference: 'SWID' is defined on line 1816, but no explicit reference was found in the text == Unused Reference: 'RFC2396' is defined on line 1822, but no explicit reference was found in the text == Unused Reference: 'RFC2822' is defined on line 1826, but no explicit reference was found in the text == Unused Reference: 'RFC3339' is defined on line 1829, but no explicit reference was found in the text == Unused Reference: 'RFC3552' is defined on line 1832, but no explicit reference was found in the text == Unused Reference: 'RFC5226' is defined on line 1836, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 5070 (Obsoleted by RFC 7970) -- Obsolete informational reference (is this intentional?): RFC 2396 (Obsoleted by RFC 3986) -- Obsolete informational reference (is this intentional?): RFC 2822 (Obsoleted by RFC 5322) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) Summary: 4 errors (**), 0 flaws (~~), 13 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 MILE Working Group J. Field 3 Internet-Draft Pivotal 4 Intended status: Informational August 15, 2013 5 Expires: February 16, 2014 7 Resource-Oriented Lightweight Indicator Exchange 8 draft-field-mile-rolie-02.txt 10 Abstract 12 This document defines a resource-oriented approach to cyber security 13 information sharing. Using this approach, a CSIRT or other 14 stakeholder may share and exchange representations of cyber security 15 incidents, indicators, and other related information as Web- 16 addressable resources. The transport protocol binding is specified 17 as HTTP(S) with a MIME media type of Atom+XML. An appropriate set of 18 link relation types specific to cyber security information sharing is 19 defined. The resource representations leverage the existing IODEF 20 [RFC5070] and RID [RFC6545] specifications as appropriate. 21 Coexistence with deployments that conform to existing specifications 22 including RID [RFC6545] and Transport of Real-time Inter-network 23 Defense (RID) Messages over HTTP/TLS [RFC6546] is supported via 24 appropriate use of HTTP status codes. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on February 16, 2014. 43 Copyright Notice 45 Copyright (c) 2013 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 61 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 62 3. Background and Motivation . . . . . . . . . . . . . . . . . . 4 63 3.1. Message-oriented versus Resource-oriented Architecture . 5 64 3.1.1. Message-oriented Architecture . . . . . . . . . . . . 5 65 3.1.2. Resource-Oriented Architecture . . . . . . . . . . . 5 66 3.2. Authentication of Users . . . . . . . . . . . . . . . . . 7 67 3.3. Authorization Policy Enforcement . . . . . . . . . . . . 7 68 3.3.1. Enforcement at Destination System . . . . . . . . . . 7 69 3.3.2. Enforcement at Source System . . . . . . . . . . . . 8 70 4. RESTful Usage Model . . . . . . . . . . . . . . . . . . . . . 9 71 4.1. Dynamic Service Discovery versus Static URL Template . . 10 72 4.2. Non-Normative Examples . . . . . . . . . . . . . . . . . 11 73 4.2.1. Service Discovery . . . . . . . . . . . . . . . . . . 11 74 4.2.2. Feed Retrieval . . . . . . . . . . . . . . . . . . . 14 75 4.2.3. Entry Retrieval . . . . . . . . . . . . . . . . . . . 16 76 4.2.4. Use of Link Relations . . . . . . . . . . . . . . . . 19 77 5. Requirements for RESTful (Atom+xml) Binding . . . . . . . . 29 78 5.1. Transport Layer Security . . . . . . . . . . . . . . . . 29 79 5.2. User Authentication . . . . . . . . . . . . . . . . . . . 29 80 5.3. User Authorization . . . . . . . . . . . . . . . . . . . 30 81 5.4. Content Model . . . . . . . . . . . . . . . . . . . . . . 30 82 5.5. HTTP methods . . . . . . . . . . . . . . . . . . . . . . 31 83 5.6. Service Discovery . . . . . . . . . . . . . . . . . . . . 31 84 5.6.1. Workspaces . . . . . . . . . . . . . . . . . . . . . 32 85 5.6.2. Collections . . . . . . . . . . . . . . . . . . . . . 32 86 5.6.3. Service Document Security . . . . . . . . . . . . . . 32 87 5.7. Category Mapping . . . . . . . . . . . . . . . . . . . . 32 88 5.7.1. Collection Category . . . . . . . . . . . . . . . . . 32 89 5.7.2. Entry Category . . . . . . . . . . . . . . . . . . . 33 90 5.8. Entry ID . . . . . . . . . . . . . . . . . . . . . . . . 33 91 5.9. Entry Content . . . . . . . . . . . . . . . . . . . . . . 33 92 5.10. Link Relations . . . . . . . . . . . . . . . . . . . . . 33 93 5.10.1. Additional Link Relation Requirements . . . . . . . 35 94 5.11. Member Entry Forward Security . . . . . . . . . . . . . . 36 95 5.12. Date Mapping . . . . . . . . . . . . . . . . . . . . . . 36 96 5.13. Search . . . . . . . . . . . . . . . . . . . . . . . . . 37 97 5.14. / (forward slash) Resource URL . . . . . . . . . . . . . 37 98 6. Security Considerations . . . . . . . . . . . . . . . . . . . 38 99 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 40 100 8. ToDo and Open Issues . . . . . . . . . . . . . . . . . . . . 40 101 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 41 102 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 41 103 10.1. Normative References . . . . . . . . . . . . . . . . . . 41 104 10.2. Informative References . . . . . . . . . . . . . . . . . 42 105 Appendix A. Change Tracking . . . . . . . . . . . . . . . . . . 43 106 Appendix B. Resource Authorization Model . . . . . . . . . . . . 43 107 B.1. Example XACML Profile . . . . . . . . . . . . . . . . . . 44 108 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 44 110 1. Introduction 112 This document defines a resource-oriented approach to cyber security 113 information sharing that follows the REST (Architectural Styles and 114 the Design of Network-based Software Architectures) architectural 115 style. The resource representations leverage the existing IODEF 116 [RFC5070] and RID [RFC6545] specifications as appropriate. The 117 transport protocol binding is specified as HTTP(S) with a media type 118 of Atom+XML. An appropriate set of link relation types specific to 119 cyber security information sharing is defined. Using this approach, 120 a CSIRT or other stakeholder may exchange cyber security incident and 121 /or indicator information as Web-addressable resources. 123 The goal of this specification is to define a loosely-coupled, agile 124 approach to cyber security situational awareness. This approach has 125 architectural advantages for some use case scenarios, such as when a 126 CSIRT or other stakeholder is required to share cyber security 127 information broadly (e.g., at internet scale), or when an information 128 sharing consortium requires support for asymmetric interactions 129 amongst their stakeholders. 131 Coexistence with deployments that conform to existing specifications 132 including RID [RFC6545] and Transport of Real-time Inter-network 133 Defense (RID) Messages over HTTP/TLS [RFC6546] is supported via 134 appropriate use of HTTP status codes. 136 2. Terminology 138 The key words "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT," 139 "SHOULD," "SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" in this 140 document are to be interpreted as described in [RFC2119]. 141 Definitions for some of the common computer security-related 142 terminology used in this document can be found in Section 2 of 143 [RFC5070]. 145 3. Background and Motivation 147 It is well known that Internet security threats are evolving ever 148 more rapidly, and are becoming ever more sophisticated than before. 149 The threat actors are frequently distributed and are not constrained 150 to operating within a fixed, closed consortium. The technical skills 151 needed to perform effective analysis of a security incident, or to 152 even recognize an indicator of compromise are already specialized and 153 relatively scarce. As threats continue to evolve, even an 154 established network of CSIRT may find that it does not always have 155 all of the skills and knowledge required to immediately identify and 156 respond to every new incident. Effective identification of and 157 response to a sophisticated, multi-stage attack frequently depends 158 upon cooperation and collaboration, not only amongst the defending 159 CSIRTs, but also amongst other stakeholders, including, potentially, 160 individual end users. 162 Existing approaches to cyber security information sharing are based 163 upon message exchange patterns that are point-to-point, and event- 164 driven. Sometimes, information that may be useful to, and sharable 165 with multiple peers is only made available to peers after they have 166 specifically requested it. Unfortunately, a sharing peer may not 167 know, a priori, what information to request from another peer. 168 Sending unsolicited RID reports does provide a mechanism for 169 alerting, however these reports are again sent point-to-point, and 170 must be reviewed for relevance and then prioritized for action by the 171 recipient. Thus, distribution of some relevant incident and 172 indicator information may exhibit significant latency. 174 In order to appropriately combat the evolving threats, the defending 175 CSIRTs should be enabled to operate in a more agile manner, sharing 176 selected cyber security information proactively, if and as 177 appropriate. 179 For example, a CSIRT analyst would benefit by having the ability to 180 search a comprehensive collection of indicators that has been 181 published by a government agency, or by another member of a sharing 182 consortium. The representation of each indicator may include links 183 to the related resources, enabling an appropriately authenticated and 184 authorized analyst to freely navigate the information space of 185 indicators, incidents, and other cyber security domain concepts, as 186 needed. In general, a more Web-centric sharing approach will enable 187 a more dynamic and agile collaboration amongst a broader, and varying 188 constituency. 190 The following sections discuss additional specific technical issues 191 that motivate the development of an alternative approach. 193 3.1. Message-oriented versus Resource-oriented Architecture 195 The existing approaches to cyber security information sharing are 196 based upon message-oriented interactions. The following paragraphs 197 explore some of the architectural constraints associated with 198 message-oriented interactions and consider the relative merits of an 199 alternative model based on a Resource-oriented architecture for use 200 in some use case scenarios. 202 3.1.1. Message-oriented Architecture 204 In general, message-based integration architectures may be based upon 205 either an RPC-style or a document-style binding. The message types 206 defined by RID represent an example of an RPC-style request. This 207 approach imposes implied requirements for conversational state 208 management on both of the communicating RID endpoint(s). Experience 209 has shown that this state management frequently becomes the limiting 210 factor with respect to the runtime scalability of an RPC-style 211 architecture. 213 In addition, the practical scalability of a peer-to-peer message- 214 based approach will be limited by the administrative procedures 215 required to manage O(N^2) trust relationships and at least O(N) 216 policy groups. 218 As long as the number of CSIRTs participating in an information 219 sharing consortium is limited to a relatively smaller number of nodes 220 (i.e., O(2^N), where N < 5), these scalability constraints may not 221 represent a critical concern. However, when there is a requirement 222 to support a significantly larger number of participating peers, a 223 different architectural approach will be required. One alternative 224 to the message-based approach that has demonstrated scalability is 225 the REST [REST] architectural style. 227 3.1.2. Resource-Oriented Architecture 229 Applying the REST architectural style to the problem domain of cyber 230 security information sharing would take the approach of exposing 231 incidents, indicators, and any other relevant types as simple Web- 232 addressable resources. By using this approach, a CSIRT or other 233 organization can more quickly and easily share relevant incident and 234 indicator information with a much larger and potentially more diverse 235 constituency. A client may leverage virtually any available HTTP 236 user agent in order to make requests of the service provider. This 237 improved ease of use could enable more rapid adoption and broader 238 participation, thereby improving security for everyone. 240 A key interoperability aspect of any RESTful Web service will be the 241 choices regarding the available resource representations. For 242 example, clients may request that a given resource representation be 243 returned as either XML or JSON. In order to enable back- 244 compatibility and interoperability with existing CSIRT 245 implementations, IODEF [RFC5070] is specified for this transport 246 binding as a mandatory to implement (MTI) data representation for 247 incident and indicator resources. In addition to the REQUIRED 248 representation, an implementation MAY support additional 249 representations if and as needed such as IODEF extensions, the RID 250 schema, or other schemas. For example, an implementation may choose 251 to provide support for returning a JSON representation of an incident 252 resource. 254 Finally, an important principle of the REST architectural style is 255 the use of hypertext links as the embodiment of application state 256 (HATEOAS). Rather than the server maintaining conversational state 257 for each client context, the server will instead include a suitable 258 set of hyperlinks in the resource representation that is returned to 259 the client. In this way, the server remains stateless with respect 260 to a series of client requests. The included hyperlinks provide the 261 client with a specific set of permitted state transitions. Using 262 these links the client may perform an operation, such as updating or 263 deleting the resource representation. The client may also be 264 provided with hypertext links that can be used to navigate to any 265 related resource. For example, the resource representation for an 266 incident object may contain links to the related indicator 267 resource(s). 269 This document specifies the use of Atom Syndication Format [RFC4287] 270 and Atom Publishing Protocol [RFC5023] as the mechanism for 271 representing the required hypertext links. 273 3.1.2.1. A Resource-Oriented Use Case: "Mashup" 275 In this section we consider a non-normative example use case scenario 276 for creating a cyber security "mashup". 278 Any CSIRT can enable any authenticated and authorized client that is 279 a member of the sharing community to quickly and easily navigate 280 through any of the cyber security information that that provider is 281 willing to share. An authenticated and authorized analyst may then 282 make HTTP(S) requests to collect incident and indicator information 283 known at one CSIRT with threat actor data being made available from 284 another CSIRT. The resulting correlations may yield new insights 285 that enable a more timely and effective defensive response. Of 286 course, this report may, in turn, be made available to others as a 287 new Web-addressable resource, reachable via another URL. By 288 employing the RESTful Web service approach the effectiveness of the 289 collaboration amongst a consortium of CSIRTs and their stakeholders 290 can be greatly improved. 292 3.2. Authentication of Users 294 In the store-and-forward, message-based model for information sharing 295 client authentication is provided via a Public Key Infrastructure 296 (PKI) -based trust and mutually authenticated TLS between the 297 messaging system endpoints. There is no provision to support 298 authentication of a client by another means. As a result, 299 participation in the sharing community is limited to those 300 organizations that have sufficient resources and capabilities to 301 manage a PKI. 303 A CSIRT may apply XML Security to the content of a message, however 304 the contact information provided within the message body represents a 305 self-asserted identity, and there is no guarantee that the contact 306 information will be recognized by the peer. As a result, the audit 307 trail and the granularity of any authorization policies is limited to 308 the identity of the peer CSIRT organization. 310 A CSIRT implementing this specification MUST implement server- 311 authenticated TLS. The CSIRT may choose to authenticate its client 312 users via any suitable authentication scheme that can be implemented 313 via HTTP(S). A participating CSIRT MAY choose to support more than 314 one authentication method. Support for use of a Federated Identity 315 approach is RECOMMENDED. Establishing a specific end user identity 316 prior to processing a request is RECOMMENDED. Doing so will enable 317 the source system to maintain a more complete audit trail of exactly 318 what cyber security incident and indicator information has been 319 shared, when, and with whom. 321 3.3. Authorization Policy Enforcement 323 A key aspect of any cyber security information sharing arrangement is 324 assigning the responsibility for authorization policy enforcement. 325 The authorization policy must be enforced either at the destination 326 system, or the source system, or both. The following sections 327 discuss these alternatives in greater detail. 329 3.3.1. Enforcement at Destination System 331 The store-and-forward, message-based approach to cyber security 332 information sharing requires that the origin system delegate 333 authorization policy enforcement to the destination system. The 334 origin system may leverage XML Encryption and DigitalSignature to 335 protect the message content. In addition, the origin system assigns 336 a number of policy-related attribute values, including a 337 "restriction" attribute, before the message is sent. These labels 338 indicate the sender's expectation for confidentiality enforcement and 339 appropriate handling at the destination. Section 9.1 of RFC6545 340 provides specific guidance to implementers on use of the XML security 341 standards in order to achieve the required levels of security for the 342 exchange of incident information. 344 Once the message has been received at the destination system, the XML 345 encryption and digital signature protections on the message will be 346 processed, and based upon the pre-established PKI-based trust 347 relationships, the message content is validated and decrypted. 348 Typical implementations will then pass the cleartext data to an 349 internal Incident Handling System (IHS) for further review and/or 350 action by a human operator or analyst. Regardless of where in the 351 deployment architecture the XML message-level security is being 352 handled, eventually the message content will be made available as 353 cleartext for handling by human systems analysts and other 354 operational staff. 356 The authorization policy enforcement of the message contents must 357 then be provided by the destination IHS. It is the responsibility of 358 the destination system to honor the intent of the policy restriction 359 labels assigned by the origin system. Ideally, these policy labels 360 would serve as part of a distributed Mandatory Access Control scheme. 361 However, in practice a typical IHS will employ a Discretionary Access 362 Control (DAC) model rather than a MAC model and so the policy related 363 attributes are defined to represent handling "hints" and provide no 364 guarantee of enforcement at the destination. 366 As a result, ensuring that the destination system or counterparty 367 will in fact correctly enforce the intended authorization policies 368 becomes a key issue when entering into any information sharing 369 agreements. The origin CSIRT must accept a non-zero risk of 370 information leakage, and therefore must rely upon legal recourse as a 371 compensating control. Establishing such legal sharing agreements can 372 be a slow and difficult process, as it assumes a high level of trust 373 in the peer, with respect to both intent and also technical 374 capabilities. 376 3.3.2. Enforcement at Source System 378 In this model, the required authorization policy enforcements are 379 implemented entirely within the source system. Enforcing the 380 required authorization policy controls at the source system 381 eliminates the risk of subsequent information leakage at the 382 destination system due to inadequate or incomplete implementation of 383 the expected controls. The destination system is not expected to 384 perform any additional authorization enforcements. Authorization 385 enforcement at the source system may be based on, e.g. Role-based 386 Access Controls applied in the context of an established user 387 identity. The source system may use any appropriate authentication 388 mechanism in order to determine the user identity of the requestor, 389 including, e.g. federated identity. An analyst or operator at a 390 CSIRT may request specific information on a given incident or 391 indicator from a peer CSIRT, and the source system will return a 392 suitable representation of that resource based upon the specific role 393 of the requestor. A different authenticated user (perhaps from the 394 same destination CSIRT) may receive a different representation of the 395 same resource, based upon the source system applying suitable Role- 396 based Access Control policy enforcements for the second user 397 identity. 399 Consistent with HTTP [RFC2616] a user's request MAY be denied with a 400 resulting HTTP status code value of 4xx such as 401 Unauthorized, 403 401 Forbidden, or 404 Not Found, or 405 Method Not Allowed, if and as 402 appropriate. 404 4. RESTful Usage Model 406 This section describes the basic use of Atom Syndication Format 407 [RFC4287] and Atom Publishing Protocol [RFC5023] as a RESTful 408 transport binding and dynamic discovery protocol, respectively, for 409 cyber security information sharing. 411 As described in Atom Publishing Protocol [RFC5023], an Atom Service 412 Document is an XML-based document format that allows a client to 413 dynamically discover the collections provided by a publisher. 415 As described in Atom Syndication Format [RFC4287], Atom is an XML- 416 based document format that describes lists of related information 417 items known as collections, or "feeds". Each feed document contains 418 a collection of zero or more related information items called "member 419 entries" or "entries". 421 When applied to the problem domain of cyber security information 422 sharing, an Atom feed may be used to represent any meaningful 423 collection of information resources such as a set of incidents, or 424 indicators. Each entry in a feed could then represent an individual 425 incident, or indicator, or some other resource, as appropriate. 426 Additional feeds could be used to represent other meaningful and 427 useful collections of cyber security resources. A feed may be 428 categorized, and any feed may contain information from zero or more 429 categories. The naming scheme and the semantic meaning of the terms 430 used to identify an Atom category are application-defined. 432 4.1. Dynamic Service Discovery versus Static URL Template 434 In order to specify a protocol for cyber security information sharing 435 using the REST architectural style it is necessary to define the set 436 of resources to be modeled, and how these resources are related. 437 Based on this interface contract, clients will then interact with the 438 REST service by navigating the modeled entities, and their 439 relationships. The interface contract between the client and the 440 server may either be statically bound or dynamically bound. 442 In the statically bound case, the clients have a priori knowledge of 443 the resources that are supported. In the REST architectural style 444 this static interface contract takes the form of a URL template. 445 This approach is not appropriate for the cyber security information 446 sharing domain for at least two reasons. 448 First, there is no standard for a cyber security domain model. While 449 information security practitioners can generally agree on some of the 450 basic concepts that are important to modeling the cyber security 451 domain -- such as "indicator," "incident," or "attacker," -- there is 452 no single domain model that can been referenced as the basis for 453 specifying a standardized RESTful URI Template. Second, the use of 454 static URL templates creates a tighter coupling between the client 455 implementation and the server implementation. Security threats on 456 the internet are evolving ever more rapidly, and it will never be 457 possible to establish a statically defined resource model and URL 458 Template. Even if there were an initial agreement on an appropriate 459 URL template, it would eventually need to change. If and when a 460 CSIRT finds that it needs to change the URL template, then any 461 existing deployed clients would need to be upgraded. 463 Thus, rather than attempting to define a fixed set of resources via a 464 URI Template, this document has instead specified an approach based 465 on dynamic discovery of resources via an Atom Publishing Protocol 466 Service Document. By using this approach, it is possible to 467 standardize the RESTful usage model, without needing to standardize 468 on the definitions of specific, strongly-typed resources. A client 469 can dynamically discover what resources are provided by a given 470 CSIRT, and then navigate that domain model accordingly A specific 471 server implementation may still embody a particular URL template, 472 however the client does not need a priori knowledge of the format of 473 the links, and the URL itself is effectively opaque to the client. 474 Clients are not bound to any particular server's interface. 476 The following paragraphs provide a number of non-normative examples 477 to illustrate the use of Atom Publishing Protocol for basic cyber 478 security information sharing service discovery, as well as the use of 479 Atom Syndication Format as a mechanism to publish cyber security 480 information feeds. 482 Normative requirements are defined below, in Section 5. 484 4.2. Non-Normative Examples 486 4.2.1. Service Discovery 488 This section provides a non-normative example of a client doing 489 service discovery. 491 An Atom service document enables a client to dynamically discover 492 what feeds a particular publisher makes available. Thus, a CSIRT may 493 use an Atom service document to enable clients of the CSIRT to 494 determine what specific cyber security information the CSIRT makes 495 available to the community. The service document could be made 496 available at any well known location, such as via a link from the 497 CSIRT's home page. One common technique is to include a link in the 498 section of the organization's home page, as shown below: 500 Example of bootstrapping Service Document discovery: 502 504 A client may then format an HTTP GET request to retrieve the service 505 document: 507 GET /csirt/svcdoc.xml 508 Host: www.example.org 509 Accept: application/atomsvc+xml 511 Notice the use of the HTTP Accept: request header, indicating the 512 MIME type for Atom service discovery. The response to this GET 513 request will be an XML document that contains information on the 514 specific feed collections that are provided by the CSIRT. 516 Example HTTP GET response: 518 HTTP/1.1 200 OK 519 Date: Fri, 24 Aug 2012 17:09:11 GMT 520 Content-Length: 570 521 Content-Type: application/atomsvc+xml;charset="utf-8" 523 524 526 527 Incidents 528 529 Incidents Feed 530 application/atom+xml; type=entry 531 532 533 535 This simple Service Document example shows that this CSIRT provides 536 one workspace, named "Incidents." Within that workspace, the CSIRT 537 makes one feed collection available. When attempting to GET or POST 538 entries to that feed collection, the client must indicate a content 539 type of application/atom+xml. 541 A CSIRT may also offer a number of different feeds, each containing 542 different types of cyber security information. In the following 543 example, the feeds have been categorized. This categorization will 544 help the clients to decide which feeds will meet their needs. 546 HTTP/1.1 200 OK 547 Date: Fri, 24 Aug 2012 17:10:11 GMT 548 Content-Length: 1912 549 Content-Type: application/atomsvc+xml;charset="utf-8" 551 552 554 555 Cyber Security Information Sharing 556 557 Public Indicators 558 559 560 561 562 application/atom+xml; type=entry 563 564 565 Public Incidents 566 567 568 569 570 application/atom+xml; type=entry 571 572 573 574 Private Consortium Sharing 575 576 Incidents 577 application/atom+xml;type=entry 578 579 580 581 582 583 584 586 In this example, the CSIRT is providing a total of three feed 587 collections, organized into two different workspaces. The first 588 workspace contains two feeds, consisting of publicly available 589 indicators and publicly available incidents, respectively. The 590 second workspace provides one additional feed, for use by a sharing 591 consortium. The feed contains incident information containing 592 entries related to three purposes: traceback, mitigation, and 593 reporting. The entries in this feed are categorized with a 594 restriction of either "Need-to-Know" or "private". An appropriately 595 authenticated and authorized client may then proceed to make GET 596 requests for one or more of these feeds. The publicly provided 597 incident information may be accessible with or without 598 authentication. However, users accessing the feed targeted to the 599 private sharing consortium would be expected to authenticate, and 600 appropriate authorization policies would subsequently be enforced by 601 the feed provider. 603 4.2.2. Feed Retrieval 605 This section provides a non-normative example of a client retrieving 606 an incident feed. 608 Having discovered the available cyber security information sharing 609 feeds, an authenticated and authorized client who is a member of the 610 private sharing consortium may be interested in receiving the feed of 611 known incidents. The client may retrieve this feed by performing an 612 HTTP GET operation on the indicated URL. 614 Example HTTP GET request for a Feed: 616 GET /csirt/private/incidents 617 Host: www.example.org 618 Accept: application/atom+xml 620 The corresponding HTTP response would be an XML document containing 621 the incidents feed: 623 Example HTTP GET response for a Feed: 625 HTTP/1.1 200 OK 626 Date: Fri, 24 Aug 2012 17:20:11 GMT 627 Content-Length: 2882 628 Content-Type: application/atom+xml;type=feed;charset="utf-8" 630 631 637 emc-csirt-iodef-feed-service 638 http://www.example.org/csirt/private/incidents 639 Atom formatted representation of a feed of IODEF documents 640 2012-05-04T18:13:51.0Z 641 642 csirt@example.org 643 EMC CSIRT 644 646 647 649 650 http://www.example.org/csirt/private/incidents/123456 651 Sample Incident 652 653 654 2012-08-04T18:13:51.0Z 655 2012-08-05T18:13:51.0Z 656 657 658 659 A short description of this incident, extracted from the IODEF Incident class, element. 660 662 663 664 666 668 This feed document has two atom entries, one of which has been 669 elided. The completed entry illustrates an Atom element that 670 provides a summary of essential details about one particular 671 incident. Based upon this summary information and the provided 672 category information, a client may choose to do an HTTP GET operation 673 to retrieve the full details of the incident. This example provides 674 a RESTful alterntive to the RID investigation request messaage, as 675 described in sections 6.1 and 7.2 of RFC6545. 677 4.2.3. Entry Retrieval 679 This section provides a non-normative example of a client retrieving 680 an incident as an Atom entry. 682 Having retrieved the feed of interest, the client may then decide 683 based on the description and/or category information that one of the 684 entries in the feed is of further interest. The client may retrieve 685 this incident Entry by performing an HTTP GET operation on the 686 indicated URL. 688 Example HTTP GET request for an Entry: 690 GET /csirt/private/incidents/123456 691 Host: www.example.org 692 Accept: application/atom+xml 694 The corresponding HTTP response would be an XML document containing 695 the incident: 697 Example HTTP GET response for an Entry: 699 HTTP/1.1 200 OK 700 Date: Fri, 24 Aug 2012 17:30:11 GMT 701 Content-Length: 4965 702 Content-Type: application/atom+xml;type=entry;charset="utf-8" 704 705 706 http://www.example.org/csirt/private/incidents/123456 707 Sample Incident 708 709 710 2012-08-04T18:13:51.0Z 711 2012-08-05T18:13:51.0Z 712 713 714 715 A short description of this incident, extracted from the IODEF Incident class, element. 717 718 719 721 722 723 725 726 728 729 730 732 733 123456 735 2004-02-02T22:49:24+00:00 736 2004-02-02T22:19:24+00:00 737 2004-02-02T23:20:24+00:00 738 739 Host involved in DoS attack 740 741 742 743 744 745 Constituency-contact for 192.0.2.35 746 747 Constituency-contact@192.0.2.35 748 749 750 751 752 753 192.0.2.35 754 755 756 757 38765 758 759 760 761 762 192.0.2.67 763 764 765 766 80 767 768 769 770 771 772 Rate-limit traffic close to source 773 774 775 776 777 778 The IPv4 packet included was used in the described attack 779 780 450000522ad9 781 0000ff06c41fc0a801020a010102976d0050103e020810d9 782 4a1350021000ad6700005468616e6b20796f7520666f7220 783 6361726566756c6c792072656164696e6720746869732052 784 46432e0a 785 786 787 788 789 790 791 792 794 As can be seen in the example response, above, an IODEF document is 795 contained within the Atom element. The client may now 796 process the IODEF document as needed. 798 Note also that, as described previously, the content of the Atom 799 element is application-defined. In the present context, 800 the Atom categories have been assigned based on a mapping of the 801 and attributes, as defined in the IODEF 802 schema. In addition, the IODEF element has been 803 judiciously chosen so that the associated name attribute, as well as 804 the corresponding incidentID value, can be concatenated in order to 805 easily create the corresponding element for the Atom entry. 806 These and other mappings are normatively defined in Section 5, below. 808 Finally, it should be noted that in order to optimize the client 809 experience, and avoid an additional round trip, a feed provider may 810 choose to include the entry content inline, as part of the feed 811 document. That is, an Atom element within a Feed document 812 may contain an Atom element as a child. In this case, the 813 client will receive the full content of the entries within the feed. 814 The decision of whether to include the entry content inline or to 815 include it as a link is a design choice left to the feed provider 816 (e.g. based upon local environmental factors such as the number of 817 entries contained in a feed, the available network bandwidth, the 818 available server compute cycles, the expected client usage patterns, 819 etc.). 821 4.2.4. Use of Link Relations 823 As noted previously, a key benefit of using the RESTful architectural 824 style is the ability to enable the client to navigate to related 825 resources through the use of hypermedia links. In the Atom 826 Syndication Format, the type of the related resource identified in a 827 element is indicated via the "rel" attribute, where the value 828 of this attribute identifies the kind of related resource available 829 at the corresponding "href" attribute. Thus, in lieu of a well-known 830 URI template the URI itself is effectively opaque to the client, and 831 therefore the client must understand the semantic meaning of the 832 "rel" attribute in order to successfully navigate. Broad 833 interoperability may be based upon a sharing consortium defining a 834 well-known set of Atom Link Relation types. These Link Relation 835 types may either be registered with IANA, or held in a private 836 registry. 838 Individual CSIRTs may always define their own link relation types in 839 order to support specific use cases, however support for a core set 840 of well-known link relation types is encouraged as this will maximize 841 interoperability. 843 In addition, it may be beneficial to define use case profiles that 844 correspond to specific groupings of supported link relationship 845 types. In this way, a CSIRT may unambiguously specify the classes of 846 use cases for which a client can expect to find support. 848 The following sections provide NON-NORMATIVE examples of link 849 relation usage. Four distinct cyber security information sharing use 850 case scenarios are described. In each use case, the unique benefits 851 of adopting a resource-oriented approach to information sharing are 852 illustrated. It is important to note that these use cases are 853 intended to be a small representative set and is by no means meant to 854 be an exhaustive list. The intent is to illustrate how the use of 855 link relationship types will enable this resource-oriented approach 856 to cyber security information sharing to successfully support the 857 complete range of existing use cases, and also to motivate an initial 858 list of well-defined link relationship types. 860 4.2.4.1. Use Case: Incident Sharing 862 This section provides a non-normative example of an incident sharing 863 use case. 865 In this use case, a member CSIRT shares incident information with 866 another member CSIRT in the same consortium. The client CSIRT 867 retreives a feed of incidents, and is able to identify one particular 868 entry of interest. The client then does an HTTP GET on that entry, 869 and the representation of that resource contains link relationships 870 for both the associated "indicators" and the incident "history", and 871 so on. The client CSIRT recognizes that some of the indicator and 872 history may be relevant within her local environment, and can respond 873 proactively. 875 Example HTTP GET response for an incident entry: 877 878 879 http://www.example.org/csirt/private/incidents/123456 880 Sample Incident 881 882 883 2012-08-04T18:13:51.0Z 884 2012-08-05T18:13:51.0Z 886 888 889 890 891 893 894 896 897 898 899 123456 900 901 902 903 904 906 As can be seen in the example response, the Atom elements 907 enable the client to navigate to the related indicator resources, and 908 /or the history entries associated with this incident. 910 4.2.4.2. Use Case: Collaborative Investigation 912 This section provides a non-normative example of a collaborative 913 investigation use case. 915 In this use case, two member CSIRTs that belong to a closed sharing 916 consortium are collaborating on an incident investigation. The 917 initiating CSIRT performs an HTTP GET to retrieve the service 918 document of the peer CSIRT, and determines the collection name to be 919 used for creating a new investigation request. The initiating CSIRT 920 then POSTs a new incident entry to the appropriate collection URL. 921 The target CSIRT acknowledges the request by responding with an HTTP 922 status code 201 Created. 924 Example HTTP GET response for the service document: 926 HTTP/1.1 200 OK 927 Date: Fri, 24 Aug 2012 17:09:11 GMT 928 Content-Length: 934 929 Content-Type: application/atomsvc+xml;charset="utf-8" 931 932 934 935 RID Use Case Requests 936 937 Investigation Requests 938 application/atom+xml; type=entry 939 940 941 Trace Requests 942 application/atom+xml; type=entry 943 944 945 946 948 As can be seen in the example response, the Atom 949 elements enable the client to determine the appropriate collection 950 URL to request an investigation or a trace. 952 The client CSIRT then POSTs a new entry to the appropriate feed 953 collection. Note that the element of the new entry may 954 contain a RID message of type "InvestigationRequest" if desired, 955 however this would NOT be required. The entry content itself need 956 only be an IODEF document, with the choice of the target collection 957 resource URL indicating the callers intent. A CSIRT would be free to 958 use any URI template to accept investigationRequests. 960 POST /csirt/RID/InvestigationRequests HTTP/1.1 961 Host: www.example.org 962 Content-Type: application/atom+xml;type=entry 963 Content-Length: 852 965 966 967 New Investigation Request 968 http://www.example2.org/csirt/private/incidents/123456 969 2012-08-12T11:08:22Z 970 Name of peer CSIRT 971 972 973 974 123 975 976 977 978 979 981 The receiving CSIRT acknowledges the request with HTTP return code 982 201 Created. 984 HTTP/1.1 201 Created 985 Date: Fri, 24 Aug 2012 19:17:11 GMT 986 Content-Length: 906 987 Content-Type: application/atom+xml;type=entry 988 Location: http://www.example.org/csirt/RID/InvestigationRequests/823 989 ETag: "8a9h9he4qphqh" 991 992 993 New Investigation Request 994 http://www.example.org/csirt/RID/InvestigationRequests/823 995 2012-08-12T11:08:30Z 996 2012-08-12T11:08:30Z 997 Name of peer CSIRT 998 999 1000 1001 123 1002 1003 1004 1006 1007 1009 Consistent with HTTP/1.1 RFC, the location header indicates the URL 1010 of the newly created InvestigationRequest. If for some reason the 1011 request were not authorized, the client would receive an HTTP status 1012 code 403 Unauthorized. In this case the HTTP response body may 1013 contain additional details, if an as appropriate. 1015 4.2.4.3. Use Case: Search (Query) 1017 This section provides a non-normative example of a search use case. 1019 The following example provides a RESTful alternative to the RID Query 1020 messaage, as described in sections 6.5 and 7.4 of RFC6545. Note that 1021 in the RESTful approach described herein there is no requirement to 1022 define a query language specific to RID queries. Instead, CSIRTs may 1023 provide support for search operations via existing search facilities, 1024 and advertise these capabilities via an appropriate URL template. 1025 Clients dynamically retrieve the search description document, and 1026 invoke specific searches via an instantiated URL template. 1028 An HTTP response body may include a link relationship of type 1029 "search." This link provides a reference to an OpenSearch 1030 description document. 1032 Example HTTP response that includes a "search" link: 1034 HTTP/1.1 200 OK 1035 Date: Fri, 24 Aug 2012 17:20:11 GMT 1036 Content-Length: nnnn 1037 Content-Type: application/atom+xml;type=feed;charset="utf-8" 1039 1040 1046 1050 1052 1053 1054 1056 1058 The OpenSearch Description document contains the information needed 1059 by a client to request a search. An example of an Open Search 1060 description document is shown below: 1062 Example HTTP response that includes a "search" link: 1064 1065 1066 CSIRT search example 1067 Cyber security information sharing consortium search interface 1068 example csirt indicator search 1069 admin@example.org 1070 1071 1072 1073 www.example.org CSIRT search 1074 1075 en-us 1076 UTF-8 1077 UTF-8 1078 1080 The OpenSearch Description document shown above contains two 1081 elements that contain parameterized URL templates. These templates 1082 provide a representation of how the client should make search 1083 requests. The exact format of the query string, including the 1084 parameterization is specified by the feed provider. 1086 This OpenSearch Description Document also contains an example of a 1087 element. Each element describes a specific search 1088 request that can be made by the client. Note that the parameters of 1089 the element correspond to the URL template parameters. In 1090 this way, a provider may fully describe the search interface 1091 available to the clients. Section 5.12, below, provides specific 1092 NORMATIVE requirements for the use of Open Search. 1094 4.2.4.4. Use Case: Cyber Data Repository 1096 This section provides a non-normative example of a cyber security 1097 data repository use case. 1099 In this use case a client accesses a persistent repository of cyber 1100 security data via a RESTful usage model. Retrieving a feed 1101 collection is analogous to an SQL SELECT statement producing a result 1102 set. Retrieving an individual Atom Entry is analogous to a SQL 1103 SELECT statement based upon a primary key producing a unique record. 1104 The cyber security data contained in the repository may include 1105 different data types, including indicators, incidents, becnmarks, or 1106 any other related resources. In this use case, the repository is 1107 queried via HTTP GET, and the results that are returned to the client 1108 may optionally contain URL references to other cyber security 1109 resources that are known to be related. These related resources may 1110 also be persisted locally, or they may exist at another (remote) 1111 cyber data respository. 1113 Example HTTP GET request to a persistent repository for any resources 1114 representing Distributed Denial of Service (DDOS) attacks: 1116 GET /csirt/repository/ddos 1117 Host: www.example.org 1118 Accept: application/atom+xml 1120 The corresponding HTTP response would be an XML document containing 1121 the DDOS feed. 1123 Example HTTP GET response for a DDOS feed: 1125 HTTP/1.1 200 OK 1126 Date: Fri, 24 Aug 2012 17:20:11 GMT 1127 Content-Length: nnnn 1128 Content-Type: application/atom+xml;type=feed;charset="utf-8" 1130 1131 1137 emc-csirt-iodef-feed-service 1138 http://www.example.org/csirt/repository/ddos 1139 Atom formatted representation of a feed of known ddos resources. 1140 2012-05-04T18:13:51.0Z 1141 1142 csirt@example.org 1143 EMC CSIRT 1144 1146 1147 1149 1150 http://www.example.org/csirt/repository/ddos/123456 1151 Sample DDOS Incident 1152 1153 1154 1155 1156 2012-08-04T18:13:51.0Z 1157 2012-08-05T18:13:51.0Z 1158 1159 1160 1161 1162 A short description of this DDOS attack, extracted from the IODEF Incident class, element. 1163 1165 1166 1167 1169 1171 This feed document has two atom entries, one of which has been 1172 elided. The completed entry illustrates an Atom element that 1173 provides a summary of essential details about one particular DDOS 1174 incident. Based upon this summary information and the provided 1175 category information, a client may choose to do an HTTP GET operation 1176 to retrieve the full details of the DDOS incident. This example 1177 shows how a persistent repository may provide links to additional 1178 resources, both local and remote. 1180 Note that the provider of a persistent repostory is not obligated to 1181 follow any particular URL template scheme. The repository available 1182 at the hypothetical provider "www.example.com" uses a different URL 1183 pattern than the hypothetical repository available at "www.cyber- 1184 agency.gov". When a client de-references a link to resource that is 1185 located in a remote repository the client may be challenged for 1186 authentication credentials acceptable to that provider. If the two 1187 repository providers choose to support a federated identity scheme or 1188 some other form of single-sign-on technology, then the user 1189 experience can be improved for interactive clients (e.g., a human 1190 user at a browser). However, this is not required and is an 1191 implementation choice that is out of scope for this specification. 1193 5. Requirements for RESTful (Atom+xml) Binding 1195 This section provides the NORMATIVE requirements for using Atom 1196 format and Atom Pub as a RESTful binding for cyber security 1197 information sharing. 1199 5.1. Transport Layer Security 1201 Servers implementing this specification MUST support server- 1202 authenticated TLS. 1204 Servers MAY support mutually authenticated TLS. 1206 5.2. User Authentication 1208 Servers MUST require user authentication. 1210 Servers MAY support more than one client authentication method. 1212 Servers participating in an information sharing consotium and 1213 supporting interactive user logins by members of the consortium 1214 SHOULD support client authentication via a federated identity scheme 1215 as per SAML 2.0. 1217 Servers MAY support client authenticated TLS. 1219 5.3. User Authorization 1221 This document does not mandate the use of any specific user 1222 authorization mechanisms. However, service implementers SHOULD 1223 provide appropriate authorization checking for all resource accesses, 1224 including individual Atom Entries, Atom Feeds, and Atom Service 1225 Documents. 1227 Authorization for a resource MAY be adjudicated based on the value(s) 1228 of the associated Atom element(s). 1230 When the content model for the Atom element of an Atom 1231 Entry contains an , then authorization MUST be 1232 adjudicated based upon the Atom element(s), whose values 1233 have been mapped as per Section 5.7. 1235 Any use of the element(s) as an input to an authorization 1236 policy decision MUST include both the "scheme" and "term" attributes 1237 contained therein. As described in Section 5.7 below, the namespace 1238 of the "term" attribute is scoped by the associated "scheme" 1239 attribute. 1241 5.4. Content Model 1243 Member entry resources providing a representation of an incident 1244 resource (e.g., as specified in the link relation type) MUST use the 1245 IODEF schema as the content model for the Atom Entry 1246 element. 1248 Member Entry resources providing a representation of an indicator 1249 resource (e.g., as specified in the link relation type) MUST use the 1250 IODEF schema as the content model for the Atom Entry 1251 element. 1253 The resource representation MAY include an appropriate indicator 1254 schema type within the element of the IODEF Incident 1255 class. Supported indicator schema types SHALL be registered via an 1256 IANA table (todo: IANA registration/review). 1258 Member Entry resources providing a representation of a RID report 1259 resource (e.g., as specified in the link relation type) MUST use the 1260 RID schema as the content model for the Atom Entry element. 1262 Member Entry resources providing representation of other types, 1263 SHOULD use the IODEF schema as the content model for the Atom Entry 1264 element. 1266 If the member entry content model is not IODEF, then the 1267 element of the Atom entry MUST contain an appropriate XML namespace 1268 declaration. 1270 5.5. HTTP methods 1272 The following table defines the HTTP [RFC2616] uniform interface 1273 methods supported by this specification: 1275 +------------+------------------------------------------------------+ 1276 | HTTP | Description | 1277 | method | | 1278 +------------+------------------------------------------------------+ 1279 | GET | Returns a representation of an individual member | 1280 | | entry resource, or a feed collection. | 1281 | PUT | Replaces the current representation of the specified | 1282 | | member entry resource with the representation | 1283 | | provided in the HTTP request body. | 1284 | POST | Creates a new instance of a member entry resource. | 1285 | | The representation of the new resource is provided | 1286 | | in the HTTP request body. | 1287 | DELETE | Removes the indicated member entry resource, or feed | 1288 | | collection. | 1289 | HEAD | Returns metadata about the member entry resource, or | 1290 | | feed collection, contained in HTTP response headers. | 1291 | PATCH | Support TBD. | 1292 +------------+------------------------------------------------------+ 1294 Table 1: Uniform Interface for Resource-Oriented Lightweight 1295 Indicator Exchange 1297 Clients MUST be capable of recognizing and prepared to process any 1298 standard HTTP status code, as defined in [RFC2616] 1300 5.6. Service Discovery 1302 This specification requires that a CSIRT MUST publish an Atom Service 1303 Document that describes the set of cyber security information sharing 1304 feeds that are provided. 1306 The service document SHOULD be discoverable via the CSIRT 1307 organization's Web home page or another well-known public resource. 1309 5.6.1. Workspaces 1311 The service document MAY include multiple workspaces. Any CSIRT 1312 providing both public feeds and private consortium feeds MUST place 1313 these different classes of feeds into different workspaces, and 1314 provide appropriate descriptions and naming conventions to indicate 1315 the intended audience of each workspace. 1317 5.6.2. Collections 1319 A CSIRT MAY provide any number of collections within a given 1320 Workspace. It is RECOMMENDED that each collection appear in only a 1321 single Workspace. It is RECOMMENDED that at least one collection be 1322 provided that accepts new incident reports from users. At least one 1323 collection MUST provide a feed of incident information for which the 1324 content model for the entries uses the IODEF schema. The title of 1325 this collection SHOULD be "Incidents". 1327 5.6.3. Service Document Security 1329 Access to the service document MUST be protected via server- 1330 authenticated TLS and a server-side certificate. 1332 When deploying a service document for use by a closed consortium, the 1333 service document MAY also be digitally signed and/or encrypted, using 1334 XML DigSig and/or XML Encryption, respectively. 1336 5.7. Category Mapping 1338 This section defines normative requirements for mapping IODEF 1339 metadata to corresponding Atom category elements. (todo: decide 1340 between IANA registration of scheme, or use a full URI). 1342 5.7.1. Collection Category 1344 An Atom collection MAY hold entries from one or more categories. The 1345 collection category set MUST contain at least the union of all the 1346 member entry categories. A collection MAY have additional category 1347 metadata that are unique to the collection, and not applicable to any 1348 individual member entry. A collection containing IODEF incident 1349 content MUST contain at least two elements. One category 1350 MUST be specified with the value of the "scheme" attribute as 1351 "restriction". One category MUST be specified with the value of the 1352 "scheme" attribute as "purpose". The value of the "fixed" attribute 1353 for both of these category elements MUST be "yes". When the category 1354 scheme="restriction", the allowable values for the "term" attribute 1355 are constrained as per section 3.2 of IODEF, e.g. public, need-to- 1356 know, private, default. When the category scheme="purpose", the 1357 allowable values for the "term" attribute are constrained as per 1358 section 3.2 of IODEF, e.g. traceback, mitigation, reporting, other. 1360 5.7.2. Entry Category 1362 An Atom entry containing IODEF content MUST contain at least two 1363 elements. One category MUST be specified with the value 1364 of the "scheme" attribute as "restriction". One category MUST be 1365 specified with the value of the "scheme" attribute as "purpose". 1366 When the category scheme="restriction", the value of the "term" 1367 attribute must be exactly one of ( public, need-to-know, private, 1368 default). When the category scheme="purpose", the value of the 1369 "term" attribute must be exactly one of (traceback, mitigation, 1370 reporting, other). When the purpose is "other".... 1372 Any member entry MAY have any number of additional categories. 1374 5.8. Entry ID 1376 The ID element for an Atom entry SHOULD be established via the 1377 concatenation of the value of the name attribute from the IODEF 1378 element and the corresponding value of the 1379 element. This requirement ensures a simple and direct one-to-one 1380 relationship between an IODEF incident ID and a corresponding Feed 1381 entry ID and avoids the need for any system to maintain a persistent 1382 store of these identity mappings. 1384 (todo: Note that this implies a constraint on the IODEF document that 1385 is more restrictive than the current IODEF schema. IODEF section 3.3 1386 requires only that the name be a STRING type. Here we are stating 1387 that name must be an IRI. Possible request to update IODEF to 1388 constrain, or to support a new element or attribute). 1390 5.9. Entry Content 1392 The element of an Atom SHOULD include an IODEF 1393 document. The element SHOULD include an appropriate XML 1394 namespace declaration for the IODEF schema. If the content model of 1395 the element does not follow the IODEF schema, then the 1396 element MUST include an appropriate XML namespace 1397 declaration. 1399 A client MAY ignore content that is not using the IODEF schema. 1401 5.10. Link Relations 1403 In addition to the standard Link Relations defined by the Atom 1404 specification, this specification defines the following additional 1405 Link Relation terms, which are introduced specifically in support of 1406 the Resource-Oriented Lightweight Indicator Exchange protocol. 1408 +-----------------------+----------------------------+--------------+ 1409 | Name | Description | Conformance | 1410 +-----------------------+----------------------------+--------------+ 1411 | service | Provides a link to an atom | MUST | 1412 | | service document | | 1413 | | associated with the | | 1414 | | collection feed. | | 1415 | search | Provides a link to an | MUST | 1416 | | associated Open Search | | 1417 | | document that describes a | | 1418 | | URL template for search | | 1419 | | queries. | | 1420 | history | Provides a link to a | MUST | 1421 | | collection of zero or more | | 1422 | | historical entries that | | 1423 | | are associated with the | | 1424 | | resource. | | 1425 | incidents | Provides a link to a | MUST | 1426 | | collection of zero or more | | 1427 | | instances of actual cyber | | 1428 | | security event(s) that are | | 1429 | | associated with the | | 1430 | | resource. | | 1431 | indicators | Provides a link to a | MUST | 1432 | | collection of zero or more | | 1433 | | instances of cyber | | 1434 | | security indicators that | | 1435 | | are associated with the | | 1436 | | resource. | | 1437 | evidence | Provides a link to a | SHOULD | 1438 | | collection of zero or more | | 1439 | | resources that provides | | 1440 | | some proof of attribution | | 1441 | | for an incident. The | | 1442 | | evidence may or may not | | 1443 | | have any identified chain | | 1444 | | of custody. | | 1445 | campaign | Provides a link to a | SHOULD | 1446 | | collection of zero or more | | 1447 | | resources that provides a | | 1448 | | representation of the | | 1449 | | associated cyber attack | | 1450 | | campaign. | | 1451 | attacker | Provides a link to a | SHOULD | 1452 | | collection of zero or more | | 1453 | | resources that provides a | | 1454 | | representation of the | | 1455 | | attacker. | | 1456 | vector | Provides a link to a | SHOULD | 1457 | | collection of zero or more | | 1458 | | resources that provides a | | 1459 | | representation of the | | 1460 | | method used by the | | 1461 | | attacker. | | 1462 | assessments | Provides a link to a | SHOULD | 1463 | | collection of zero or more | | 1464 | | resources that represent | | 1465 | | the results of executing a | | 1466 | | benchmark. | | 1467 | reports | Provides a link to a | SHOULD | 1468 | | collection of zero or more | | 1469 | | resources that represent | | 1470 | | RID reports. | | 1471 | traceRequests | Provides a link to a | SHOULD | 1472 | | collection of zero or more | | 1473 | | resources that represent | | 1474 | | RID traceRequests. | | 1475 | investigationRequests | Provides a link to a | SHOULD | 1476 | | collection of zero or more | | 1477 | | resources that represent | | 1478 | | RID investigationRequests. | | 1479 | swid | Provides a link to a | SHOULD | 1480 | | collection of zero or more | | 1481 | | resources that represent | | 1482 | | related Software ID tags. | | 1483 +-----------------------+----------------------------+--------------+ 1485 Table 2: Link Relations for Resource-Oriented Lightweight Indicator 1486 Exchange 1488 Unless specifically registered with IANA these short names MUST be 1489 fully qualified via concatenation with a base-uri. An appropriate 1490 base-uri could be established via agreement amongst the members of an 1491 information sharing consortium. For example, the rel="indicators" 1492 relationship would become rel="http://www.example.org/csirt/incidents 1493 /relationships/indicators." 1495 5.10.1. Additional Link Relation Requirements 1497 An IODEF document that is carried in an Atom Entry SHOULD NOT contain 1498 a element. Instead, the related activity SHOULD be 1499 available via a link rel=related. 1501 An IODEF document that is carried in an Atom Entry SHOULD NOT contain 1502 a element. Instead, the related history SHOULD be 1503 available via a link rel="history" (todo: or a fully qualified link 1504 rel name). The associated href MAY leverage OpenSearch to specify 1505 the required query. 1507 An Atom Entry MAY include additional link relationships not specified 1508 here. If a client encounters a link relationship of an unknown type 1509 the client MUST ignore the offending link and continue processing the 1510 remaining resource representation as if the offending link element 1511 did not appear. 1513 The link relationship "swid" may be used for a collection of zero or 1514 more software identification tags that are related to the current 1515 indicator. The representation of the resources available via this 1516 link relationship MAY follow an appropriate standard, such as ISO/IEC 1517 19770-2:2009 Information technology -- Software asset management -- 1518 Part 2: Software identification tag. 1520 5.11. Member Entry Forward Security 1522 As described in Authorization Policy Enforcement (Authorization 1523 Policy Enforcement) a RESTful model for cyber security information 1524 sharing requires that all of the required security enforcement for 1525 feeds and entries MUST be enforced at the source system, at the point 1526 the representation of the given resource(s) is created. A CSIRT 1527 provider SHALL NOT return any feed content or member entry content 1528 for which the client identity has not been specifically 1529 authenticated, authorized, and audited. 1531 Sharing communities that have a requirement for forward message 1532 security (such that client systems are required to participate in 1533 providing message level security and/or distributed authorization 1534 policy enforcement), MUST use the RID schema as the content model for 1535 the member entry element. 1537 5.12. Date Mapping 1539 The Atom feed element MUST be populated with the current 1540 time at the instant the feed representation was generated. The Atom 1541 entry element MUST be populated with the same time value 1542 as the element from the IODEF document. 1544 5.13. Search 1546 Implementers MUST support OpenSearch 1.1 [opensearch] as the 1547 mechanism for describing how clients may form search requests. 1549 Implementers MUST provide a link with a relationship type of 1550 "search". This link SHALL return an Open Search Description Document 1551 as defined in OpenSearch 1.1. 1553 Implementers MUST support an OpenSearch 1.1 compliant search URL 1554 template that enables a search query via Atom Category, including the 1555 scheme attribute and terms attribute as search parameters. 1557 Implementers SHOULD support search based upon the IODEF AlternativeID 1558 class as a search parameter. 1560 Implementers SHOULD support search based upon the four timestamp 1561 elements of the IODEF Incident class: , , 1562 , and . 1564 Implementers MAY support additional search capabilities based upon 1565 any of the remaining elements of the IODEF Incident class, including 1566 the element. 1568 Collections that support use of the RID schema as a content model in 1569 the Atom member entry element (e.g. in a report resource 1570 representation reachable via the "report" link relationship) MUST 1571 support search operations that include the RID MessageType as a 1572 search parameter, in addition to the aforementioned IODEF schema 1573 elements, as contained within the element. 1575 Implementers MUST fully qualify all OpenSearch URL template parameter 1576 names using the defined IODEF or RID XML namespaces, as appropriate. 1578 5.14. / (forward slash) Resource URL 1580 The "/" resource MAY be provided for compatibility with existing 1581 deployments that are using Transport of Real-time Inter-network 1582 Defense (RID) Messages over HTTP/TLS [RFC6546]. Consistent with 1583 RFC6546 errata, a client requesting a GET on "/" MUST receive an HTTP 1584 status code 405 Method Not Allowed. An implementation MAY provide 1585 full support for RFC6546 such that a POST to "/" containing a 1586 recognized RID message type just works. Alternatively, a client 1587 requesting a POST to "/" MAY receive an HTTP status code 307 1588 Temporary Redirect. In this case, the location header in the HTTP 1589 response will provide the URL of the appropriate RID endpoint, and 1590 the client may repeat the POST method at the indicated location. 1591 This resource could also leverage the new draft by reschke that 1592 proposes HTTP status code 308 (cf: draft-reschke-http- 1593 status-308-07.txt). 1595 6. Security Considerations 1597 This document defines a resource-oriented approach to lightweight 1598 indicator exchange using HTTP, TLS, Atom Syndicate Format, and Atom 1599 Publishing Protocol. As such, implementers must understand the 1600 security considerations described in those specifications. 1602 In addition, there are a number of additional security considerations 1603 that are unique to this specification. 1605 As described above in the section Authentication of Users 1606 (Section 3.2), the approach described herein is based upon all policy 1607 enforcements being implemented at the point when a resource 1608 representation is created. As such, CSIRTS sharing cyber security 1609 information using this specification must take care to authenticate 1610 their HTTP clients using a suitably strong user authentication 1611 mechanism. Sharing communities that are exchanging information on 1612 well-known indicators and incidents for purposes of public education 1613 may choose to rely upon, e.g. HTTP Authentication, or similar. 1614 However, sharing communities that are engaged in sensitive 1615 collaborative analysis and/or operational response for indicators and 1616 incidents targeting high value information systems should adopt a 1617 suitably stronger user authentication solution, such as TLS client 1618 certificates, or a risk-based or multi-factor approach. In general, 1619 trust in the sharing consortium will depend upon the members 1620 maintaining adequate user authentication mechanisms. 1622 Collaborating consortiums may benefit from the adoption of a 1623 federated identity solution, such as those based upon SAML-core 1624 [SAML-core] and SAML-bind [SAML-bind] and SAML-prof [SAML-prof] for 1625 Web-based authentication and cross-organizational single sign-on. 1626 Dependency on a trusted third party identity provider implies that 1627 appropriate care must be exercised to sufficiently secure the 1628 Identity provider. Any attacks on the federated identity system 1629 would present a risk to the CISRT, as a relying party. Potential 1630 mitigations include deployment of a federation-aware identity 1631 provider that is under the control of the information sharing 1632 consortium, with suitably stringent technical and management 1633 controls. 1635 As discussed above in the section Authorization Policy Enforcement 1636 (Section 3.3), authorization of resource representations is the 1637 responsibility of the source system, i.e. based on the authenticated 1638 user identity associated with an HTTP(S) request. The required 1639 authorization policies that are to be enforced must therefore be 1640 managed by the security administrators of the source system. Various 1641 authorization architectures would be suitable for this purpose, such 1642 as RBAC [1] and/or ABAC, as embodied in XACML [XACML]. In 1643 particular, implementers adopting XACML may benefit from the 1644 capability to represent their authorization policies in a 1645 standardized, interoperable format. 1647 Additional security requirements such as enforcing message-level 1648 security at the destination system could supplement the security 1649 enforcements performed at the source system, however these 1650 destination-provided policy enforcements are out of scope for this 1651 specification. Implementers requiring this capability should 1652 consider leveraging, e.g. the element in the RID schema. 1653 Refer to RFC6545 section 9 for more information. 1655 When security policies relevant to the source system are to be 1656 enforced at both the source and destination systems, implementers 1657 must take care to avoid unintended interactions of the separately 1658 enforced policies. Potential risks will include unintended denial of 1659 service and/or unintended information leakage. These problems may be 1660 mitigated by avoiding any dependence upon enforcements performed at 1661 the destination system. When distributed enforcement is unavoidable, 1662 the usage of a standard language (e.g. XACML) for the expression of 1663 authorization policies will enable the source and destination systems 1664 to better coordinate and align their respective policy expressions. 1666 Adoption of the information sharing approach described in this 1667 document will enable users to more easily perform correlations across 1668 separate, and potentially unrelated, cyber security information 1669 providers. A client may succeed in assembling a data set that would 1670 not have been permitted within the context of the authorization 1671 policies of either provider when considered individually. Thus, 1672 providers may face a risk of an attacker obtaining an access that 1673 constitutes an undetected separation of duties (SOD) violation. It 1674 is important to note that this risk is not unique to this 1675 specification, and a similar potential for abuse exists with any 1676 other cyber security information sharing protocol. However, the wide 1677 availability of tools for HTTP clients and Atom feed handling implies 1678 that the resources and technical skills required for a successful 1679 exploit may be less than it was previously. This risk can be best 1680 mitigated through appropriate vetting of the client at account 1681 provisioning time. In addition, any increase in the risk of this 1682 type of abuse should be offset by the corresponding increase in 1683 effectiveness that that this specification affords to the defenders. 1685 While it is a goal of this specification to enable more agile cyber 1686 security information sharing across a broader and varying 1687 constituency, there is nothing in this specification that necessarily 1688 requires this type of deployment. A cyber security information 1689 sharing consortium may chose to adopt this specification while 1690 continuing to operate as a gated community with strictly limited 1691 membership. 1693 7. IANA Considerations 1695 If the values of the newly defined link relations are not fully 1696 qualified URIs then we need to register these link types with IANA 1697 (e.g. rel="history") It is possible to adjust this document so that 1698 it has no actions for IANA. 1700 8. ToDo and Open Issues 1702 The following is the "todo" and open issues list: 1704 1. Need to make a decision on whether new IANA link registrations 1705 are required, or whether fully qualified (private) link types are 1706 sufficient. 1708 2. Should we require Atom categories that correspond to IODEF 1709 Expectation class and/or IODEF Impact class? 1711 3. Should we include specific requirements for Archive and Paging? 1712 Perhaps just reference RFC 5005? 1714 4. We need more requirements input on use cases involving RID schema 1715 in the Atom member entry content model for link rel=report. 1717 5. An Atom service document will have categories, but this is still 1718 coarse-grained, and not visible at the transport protocol level. 1719 Should we include a MIME media type parameter to support 1720 negotiation and better document the content model schema 1721 contained in a collection, i.e.: 1723 Accept: application/atom+xml;type=entry;content=iodef 1725 Accept: application/atom+xml;type=entry;content=rid 1727 Accept: application/atom+xml;type=entry;content=iodef+openioc 1729 6. If so, I think these parameters may require media type 1730 registration as per RFC4288? 1732 7. Further work is needed to investigate the use of a link 1733 relationship for SWID tags, as related resources. 1735 8. It has been suggested that a RESTful binding approach similar to 1736 ROLIE may be relevant to certain related use cases being 1737 considered in SACM. This requires further discussion to explore 1738 the requirements in more detail. 1740 9. Acknowledgements 1742 The author gratefully acknowledges the valuable contributions of Tom 1743 Maguire, Kathleen Moriarty, and Vijayanand Bharadwaj. These 1744 individuals provided detailed review comments on earlier drafts, and 1745 many suggestions that have helped to improve this document . 1747 10. References 1749 10.1. Normative References 1751 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1752 Requirement Levels", BCP 14, RFC 2119, March 1997. 1754 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1755 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1756 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1758 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 1759 Syndication Format", RFC 4287, December 2005. 1761 [RFC5023] Gregorio, J. and B. de hOra, "The Atom Publishing 1762 Protocol", RFC 5023, October 2007. 1764 [RFC5070] Danyliw, R., Meijer, J., and Y. Demchenko, "The Incident 1765 Object Description Exchange Format", RFC 5070, December 1766 2007. 1768 [RFC6545] Moriarty, K., "Real-time Inter-network Defense (RID)", RFC 1769 6545, April 2012. 1771 [opensearch] 1772 Clinton, D., "OpenSearch 1.1 draft 5 specification", 2011, 1773 . 1775 [SAML-core] 1776 Cantor, S., Kemp, J., Philpott, R., and E. Mahler, 1777 "Assertions and Protocols for the OASIS Security Assertion 1778 Markup Language (SAML) V2.0 ", OASIS Standard , March 1779 2005, . 1782 [SAML-prof] 1783 Hughes, J., Cantor, S., Hodges, J., Hirsch, F., Mishra, 1784 P., Philpott, R., and E. Mahler, "Profiles for the OASIS 1785 Security Assertion Markup Language (SAML) V2.0", OASIS 1786 Standard , March 2005, . 1789 [SAML-bind] 1790 Cantor, S., Hirsch, F., Kemp, J., Philpott, R., and E. 1791 Mahler, "Bindings for the OASIS Security Assertion Markup 1792 Language (SAML) V2.0 ", OASIS Standard , March 2005, 1793 . 1796 10.2. Informative References 1798 [XMLencrypt] 1799 Imaura, T., Dillaway, B., and E. Simon, "XML Encryption 1800 Syntax and Processing", W3C Recommendation , December 1801 2002, . 1803 [XMLsig] Bartel, M., Boyer, J., Fox, B., LaMaccia, B., and E. 1804 Simon, "XML-Signature Syntax and Processing", W3C 1805 Recommendation Second Edition, June 2008, 1806 . 1808 [XACML] Rissanen, E., "eXtensible Access Control Markup Language 1809 (XACML) Version 3.0", August 2010, . 1812 [REST] Fielding, R., "Architectural Styles and the Design of 1813 Network-based Software Architectures", 2000, . 1816 [SWID] Suryn, W., "ISO/IEC 19770-2:2009 Information technology - 1817 Software asset management - Part 2: Software 1818 identification tag", 2009, . 1822 [RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1823 Resource Identifiers (URI): Generic Syntax", RFC 2396, 1824 August 1998. 1826 [RFC2822] Resnick, P., "Internet Message Format", RFC 2822, April 1827 2001. 1829 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 1830 Internet: Timestamps", RFC 3339, July 2002. 1832 [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC 1833 Text on Security Considerations", BCP 72, RFC 3552, July 1834 2003. 1836 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1837 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1838 May 2008. 1840 [RFC6546] Trammell, B., "Transport of Real-time Inter-network 1841 Defense (RID) Messages over HTTP/TLS", RFC 6546, April 1842 2012. 1844 Appendix A. Change Tracking 1846 Changes since -01 version, Feb 15, 2013: 1848 o Updated author's contact information. 1850 o Added a new link relationship definition to Table 2, for Software 1851 Identification tag (SWID) as another potential related resource. 1853 o Included a non-normative reference to the related ISO/IEC standard 1854 in this section, Additional Link Relation Requirements. See: 1855 Section 5.10.1 1857 o Corrected a small number of spelling errors and/or typos 1858 throughout. 1860 Appendix B. Resource Authorization Model 1862 As described in Section 3.3.2 above, ROLIE assumes that all 1863 authorization policy enforcement is provided at the source server. 1864 The implementation details of the authorization scheme chosen by a 1865 ROLIE-compliant provider are out of scope for this specification. 1866 Implementers are free to choose any suitable authorization mechanism 1867 that is capable of fulfilling the policy enforcement requirements 1868 relevant to their consortium and/or organization. 1870 It is well known that one of the major barriers to information 1871 sharing is ensuring acceptable use of the information shared. In the 1872 case of ROLIE, one way to lower that barrier may be to develop a 1873 XACML profile. Use of XACML would allow a ROLIE-compliant provider 1874 to express their information sharing authorization policies in a 1875 standards-compliant, and machine-readable format. 1877 This improved interoperability may, in turn, enable more agile 1878 interactions in the cyber security sharing community. For example, a 1879 peer CSIRT, or another interested stakeholder such as an auditor, 1880 would be able to review and compare CSIRT sharing policies using 1881 appropriate tooling. 1883 The XACML 3.0 standard is based upon the notion that authorization 1884 policies are defined in terms of predicate logic expressions written 1885 against the attributes associated with one or more of the following 1886 four entities: 1888 o SUBJECT 1890 o ACTION 1892 o RESOURCE 1894 o ENVIRONMENT 1896 Thus, a suitable approach to a XACML 3.0 profile for ROLIE 1897 authorization policies could begin by using the 3-tuple of [SUBJECT, 1898 ACTION, RESOURCE] where: 1900 o SUBJECT is the suitably authenticated identity of the requestor. 1902 o ACTION is the associated HTTP method, GET, PUT, POST, DELETE, 1903 HEAD, (PATCH). 1905 o RESOURCE is an XPath expression that uniquely identifies the 1906 instance or type of the ROLIE resource being requested. 1908 Implementers who have a need may also choose to evaluate based upon 1909 the additional ENVIRONMENT factors, such as current threat level, and 1910 so on. One could also write policy to consider the CVSS score 1911 associated with the resource, or the lifecycle phase of the resource 1912 (vulnerability unverified, confirmed, patch available, etc.), and so 1913 on. 1915 Having these policies expressed in a standards-compliant and machine- 1916 readable format could improve the agility and effectiveness of a 1917 cyber security information sharing group or consortium, and enable 1918 better cyber defenses. 1920 B.1. Example XACML Profile 1922 Work-in-Progress. If this aproach finds support in the community 1923 then this section (or a new draft, as a seperate document) could 1924 provide a more complete XACML 3.0 compliant example. 1926 Author's Address 1927 John P. Field 1928 Pivotal 1929 841 Broadway 1930 8th Floor 1931 New York, New York 1932 USA 1934 Phone: 973-635-0228 1935 Email: jfield@gopivotal.com