idnits 2.17.1 draft-ietf-mile-rolie-06.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == 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 (March 13, 2017) is 2595 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1' on line 1436 -- Looks like a reference, but probably isn't: '2' on line 1439 -- Looks like a reference, but probably isn't: '3' on line 1442 == Unused Reference: 'REST' is defined on line 1429, but no explicit reference was found in the text ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) -- Obsolete informational reference (is this intentional?): RFC 2141 (Obsoleted by RFC 8141) Summary: 1 error (**), 0 flaws (~~), 3 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: Standards Track S. Banghart 5 Expires: September 14, 2017 D. Waltermire 6 NIST 7 March 13, 2017 9 Resource-Oriented Lightweight Information Exchange 10 draft-ietf-mile-rolie-06 12 Abstract 14 This document defines a resource-oriented approach for security 15 automation information publication, discovery, and sharing. Using 16 this approach, producers may publish, share, and exchange 17 representations of security incidents, attack indicators, software 18 vulnerabilities, configuration checklists, and other security 19 automation information as Web-addressable resources. Furthermore, 20 consumers and other stakeholders may access and search this security 21 information as needed, establishing a rapid and on-demand information 22 exchange network for restricted internal use or public access 23 repositories. This specification extends the Atom Publishing 24 Protocol and Atom Syndication Format to transport and share security 25 automation resource representations. 27 Contributing to this document 29 The source for this draft is being maintained on GitHub. Suggested 30 changes should be submitted as pull requests at 31 . Instructions are on that page 32 as well. Editorial changes can be managed in GitHub, but any 33 substantial issues need to be discussed on the MILE mailing list. 35 Status of This Memo 37 This Internet-Draft is submitted in full conformance with the 38 provisions of BCP 78 and BCP 79. 40 Internet-Drafts are working documents of the Internet Engineering 41 Task Force (IETF). Note that other groups may also distribute 42 working documents as Internet-Drafts. The list of current Internet- 43 Drafts is at http://datatracker.ietf.org/drafts/current/. 45 Internet-Drafts are draft documents valid for a maximum of six months 46 and may be updated, replaced, or obsoleted by other documents at any 47 time. It is inappropriate to use Internet-Drafts as reference 48 material or to cite them other than as "work in progress." 49 This Internet-Draft will expire on September 14, 2017. 51 Copyright Notice 53 Copyright (c) 2017 IETF Trust and the persons identified as the 54 document authors. All rights reserved. 56 This document is subject to BCP 78 and the IETF Trust's Legal 57 Provisions Relating to IETF Documents 58 (http://trustee.ietf.org/license-info) in effect on the date of 59 publication of this document. Please review these documents 60 carefully, as they describe your rights and restrictions with respect 61 to this document. Code Components extracted from this document must 62 include Simplified BSD License text as described in Section 4.e of 63 the Trust Legal Provisions and are provided without warranty as 64 described in the Simplified BSD License. 66 Table of Contents 68 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 69 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 70 3. XML-related Conventions . . . . . . . . . . . . . . . . . . . 4 71 3.1. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 4 72 3.2. RELAX NG Compact Schema . . . . . . . . . . . . . . . . . 5 73 4. Background and Motivation . . . . . . . . . . . . . . . . . . 5 74 4.1. Proactive Sharing . . . . . . . . . . . . . . . . . . . . 5 75 4.2. Knowledge Aggregation . . . . . . . . . . . . . . . . . . 6 76 4.3. Resource-oriented Architecture . . . . . . . . . . . . . 6 77 5. ROLIE Requirements for the Atom Publishing Protocol . . . . . 7 78 5.1. AtomPub Service Documents . . . . . . . . . . . . . . . . 7 79 5.1.1. Use of the "app:workspace" Element . . . . . . . . . 8 80 5.1.2. Use of the "app:collection" Element . . . . . . . . . 8 81 5.1.3. Service Discovery . . . . . . . . . . . . . . . . . . 9 82 5.2. AtomPub Category Documents . . . . . . . . . . . . . . . 10 83 5.3. Transport Layer Security . . . . . . . . . . . . . . . . 10 84 5.4. User Authentication and Authorization . . . . . . . . . . 11 85 5.5. / (forward slash) Resource URL . . . . . . . . . . . . . 12 86 5.6. HTTP methods . . . . . . . . . . . . . . . . . . . . . . 12 87 6. ROLIE Requirements for the Atom Syndication Format . . . . . 12 88 6.1. Use of the "atom:feed" element . . . . . . . . . . . . . 12 89 6.1.1. Use of the "atom:category" Element . . . . . . . . . 13 90 6.1.2. Use of the "atom:link" Element . . . . . . . . . . . 14 91 6.1.3. Use of the "atom:updated" Element . . . . . . . . . . 15 92 6.2. Use of the "atom:entry" Element . . . . . . . . . . . . 16 93 6.2.1. Use of the "atom:content" Element . . . . . . . . . . 16 94 6.2.2. Use of the "atom:link" Element . . . . . . . . . . . 17 95 6.2.3. Use of the "rolie:format" Element . . . . . . . . . . 17 96 6.2.4. Use of the rolie:property Element . . . . . . . . . . 18 97 6.2.5. Requirements for a Standalone Entry . . . . . . . . . 19 98 7. Available Extension Points Provided by ROLIE . . . . . . . . 19 99 7.1. The Category Extension Point . . . . . . . . . . . . . . 20 100 7.1.1. General Use of the "atom:category" Element . . . . . 20 101 7.1.2. Identification of Security Automation Information 102 Types . . . . . . . . . . . . . . . . . . . . . . . . 21 103 7.2. The "rolie:format" Extension Point . . . . . . . . . . . 22 104 7.3. The Link Relation Extension Point . . . . . . . . . . . . 22 105 7.4. The "rolie:property" Extension Point . . . . . . . . . . 23 106 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 107 8.1. XML Namespaces and Schema URNs . . . . . . . . . . . . . 23 108 8.2. ROLIE URN Sub-namespace . . . . . . . . . . . . . . . . . 23 109 8.3. ROLIE URN Parameters . . . . . . . . . . . . . . . . . . 24 110 8.4. ROLIE Security Resource Information Type Sub-Registry . . 25 111 9. Security Considerations . . . . . . . . . . . . . . . . . . . 26 112 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 28 113 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 28 114 11.1. Normative References . . . . . . . . . . . . . . . . . . 28 115 11.2. Informative References . . . . . . . . . . . . . . . . . 30 116 11.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 31 117 Appendix A. Relax NG Compact Schema for ROLIE . . . . . . . . . 31 118 Appendix B. Examples of Use . . . . . . . . . . . . . . . . . . 32 119 B.1. Service Discovery . . . . . . . . . . . . . . . . . . . . 32 120 B.2. Feed Retrieval . . . . . . . . . . . . . . . . . . . . . 35 121 B.3. Entry Retrieval . . . . . . . . . . . . . . . . . . . . . 37 122 Appendix C. Change History . . . . . . . . . . . . . . . . . . . 38 123 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 40 125 1. Introduction 127 This document defines a resource-oriented approach to security 128 automation information sharing that follows the REST (Architectural S 129 tyles and the Design of Network-based Software Architectures) 130 architectural style. In this approach, computer security resources 131 are maintained in web-accessible repositories structured as Atom 132 Syndication Format [RFC4287] Feeds. Representations of specific 133 types of security automation information are categorized and 134 organized into indexed Collections which may be requested by the 135 consumer. As the set of resource Collections are forward facing, the 136 consumer may search all available content for which they are 137 authorized to view, and request the information resources which are 138 desired. Through use of granular authentication and access controls, 139 only authorized consumers may be permitted the ability to read or 140 write to a given Feed. This approach is in contrast to, and meant to 141 improve on, the traditional point-to-point messaging system, in which 142 consumers must request individual pieces of information from a server 143 following a triggering event. The point-to-point approach creates a 144 closed system of information sharing that encourages duplication of 145 effort and hinders automated security systems. 147 The goal of this document is to define a RESTful approach to security 148 information communication with two primary intents: 1) increasing 149 communication and sharing of incident reports, vulnerability 150 assessments, configuration checklists, and other security automation 151 information between providers and consumers; and 2) establishing a 152 standardized communication system to support automated computer 153 security systems. 155 In order to deal with the great variety in security automation 156 information types and associated resource representations, this 157 specification defines extension points that can be used to add 158 support for new information types and associated resource 159 representations by means of additional supplementary specification 160 documents. This primary document is resource representation 161 agnostic, and defines the core requirements of all implementations. 162 An overview of the extension system is provided in Section 7.Those 163 seeking to provide support for specific security automation 164 information types should refer to the specification for that domain 165 described by the IANA registry found in section 8.4. 167 2. Terminology 169 The key words "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT," 170 "SHOULD," "SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" in this 171 document are to be interpreted as described in [RFC2119]. 173 Definitions for some of the common computer security-related 174 terminology used in this document can be found in Section 2 of 175 [RFC7970]. 177 The following terms are unqiue to this specification: 179 Information Type A class of security automation information, having 180 an associated data model, that is the subject of a security 181 process that can be automated. See section 7.1.2 for more 182 information. 184 3. XML-related Conventions 186 3.1. XML Namespaces 188 This specification uses XML Namespaces [W3C.REC-xml-names-20091208] 189 to uniquely identify XML element names. It uses the following 190 namespace prefix mappings for the indicated namespace URI: 192 "app" is used for the "http://www.w3.org/2007/app" namespace 193 defined in [RFC5023]. 195 "atom" is used for the "http://www.w3.org/2005/Atom" namespace 196 defined in [RFC4287]. 198 "rolie" is used for the "urn:ietf:params:xml:ns:rolie:1.0" 199 namespace defined in section 8.1 of this specification. 201 3.2. RELAX NG Compact Schema 203 Some sections of this specification are illustrated with fragments of 204 a non-normative RELAX NG Compact schema [relax-NG]. However, the 205 text of this specification provides the definition of conformance. 206 Schema for the "http://www.w3.org/2007/app" and 207 "http://www.w3.org/2005/Atom" namespaces appear in RFC5023 appendix B 208 [RFC5023] and RFC4287 appendix B [RFC4287] respectively. 210 A complete RELAX NG Compact Schema for the new elements introduced by 211 ROLIE is provided in Appendix A. 213 4. Background and Motivation 215 Information sharing is one of the core components of automating 216 security processes. Vulnerabilities, configurations, software 217 identification, security incidents, and patching data are just a few 218 of the classes of information that are shared today to enable 219 effective security on a wide scale. However, as the scale of defense 220 broadens to sometimes global networks, and the inherent scaling 221 issues of human-in-the-loop sharing become apparent, the need for 222 automation and machine-to-machine communication becomes apparent. 224 4.1. Proactive Sharing 226 Existing approaches to computer security information sharing often 227 use message exchange patterns that are point-to-point. Sometimes, 228 information that may be useful to share with multiple peers is only 229 made available to peers after they have specifically requested it. 230 Unfortunately, a sharing peer may not know, a priori, what 231 information to request from another peer. Some existing systems 232 provide a mechanism for unsolicited information requests, however, 233 these reports are again sent point-to-point, and must be reviewed for 234 relevance and then prioritized for action by the recipient, 235 introducing additional latency. 237 In order to adequately combat evolving threats, computer security 238 information resource providers should be able to share selected 239 information proactively. Proactive sharing greatly aids knowledge 240 dissemination, and improves response times and usability by allowing 241 the consumer to choose which information is relevant to its needs. 243 For example, a security analyst can benefit by having the ability to 244 search a comprehensive collection of attack indicators that have been 245 published by a government agency, or by another member of a sharing 246 consortium. The representation of each indicator may include links 247 to the related resources, enabling an appropriately authenticated and 248 authorized analyst to freely navigate the information space of 249 indicators, incidents, vulnerabilities, and other computer security 250 domain concepts as needed. In this way, an analyst can more 251 effectively utilize the super set of information made publicly 252 available. 254 4.2. Knowledge Aggregation 256 Additionally, there is value in maintaining a repository of knowledge 257 that can be queried by a new consumer, allowing this consumer to 258 identify and retrieve any information that is relevant to its needs. 259 In this way, the consumer can gain access to meaningful current and 260 historic information, catching up to the knowledge level of its 261 peers. 263 Consider the case of an automated endpoint management system 264 attempting to proactively prevent software flaws and mis-configured 265 software from compromising the security of the affected systems. 266 During its full network sweep, the endpoint monitoring system would 267 check each endpoint for outdated, vulnerable, and mis-configured 268 software. This system would benefit from having access to not only 269 the software vendor's list of vulnerabilities and configuration 270 baselines, but also similar information discovered by other security 271 researchers. An advanced system could even give back to this sharing 272 consortium by sharing any relevant information discovered. 274 These capabilities support a federated collection of information 275 repositories that can be queried and contributed to by an 276 organization, further supporting automated security solutions. 278 4.3. Resource-oriented Architecture 280 Applying the REST architectural style to the problem domain of 281 security information sharing involves exposing information of any 282 relevant type as simple Web-addressable resources. Each provider 283 maintains their own repository of data, with public and private 284 sections as needed. Any producer or consumer can then discover these 285 repositories, search for relevant Feeds, and pull information from 286 them. By using this approach, an organization can more quickly and 287 easily share relevant data representations with a much larger and 288 potentially more diverse constituency. A consumer may leverage 289 virtually any available HTTP user agent in order to make requests of 290 the service provider. This improved ease of use enables more rapid 291 adoption and broader participation, thereby improving security for 292 everyone. 294 A key aspect of any RESTful Web service is the ability to provide 295 multiple resource representations. For example, clients may request 296 that a given resource representation be returned as XML, JSON, or in 297 some other format. In order to enable backwards-compatibility and 298 interoperability with existing implementations, the RESTful approach 299 allows the provider to make differing formats available proactively, 300 allowing the consumer to simply select the version that best suits 301 them. 303 Finally, an important principle of the REST architectural style is 304 the focus on hypermedia as the engine of application state (HATEOAS). 305 Rather than the server maintaining conversational state for each 306 client, the server will instead include a suitable set of hyperlinks 307 in the resource representation that is returned to the client. The 308 included hyperlinks provide the client with a specific set of 309 permitted state transitions. Using these links the client may 310 perform an operation, such as updating or deleting the resource 311 representation. The client may also be provided with hypertext links 312 that can be used to navigate to any related resource. For example, 313 the resource representation for an object may contain links to the 314 related resource(s). In this way, the server remains stateless with 315 respect to a series of client requests. 317 5. ROLIE Requirements for the Atom Publishing Protocol 319 This section describes a number of restrictions of and extensions to 320 the Atom Publishing Protocol (AtomPub) [RFC5023] that define the use 321 of that protocol in the context of a ROLIE-based solution. The 322 normative requirements in this section are generally oriented towards 323 client and server implementations. An understanding of the Atom 324 Publishing Protocol specification [RFC5023] is helpful to understand 325 the requirements in this section. 327 5.1. AtomPub Service Documents 329 As described in RFC5023 section 8 [RFC5023], a Service Document is an 330 XML-based document format that allows a client to dynamically 331 discover the Collections provided by a publisher. A Service Document 332 consists of one or more app:workspace elements that may each contain 333 a number of app:collection elements. 335 The general structure of a service document is as follows (from 336 RFC5023 section 4.2 [RFC5023]): 338 Service 339 o- Workspace 340 | | 341 | o- Collection 342 | | 343 | o- IRI, categories, media types 344 | 345 o- Workspace 346 | 347 o- Collection 348 | 349 o- IRI, categories, media types 351 5.1.1. Use of the "app:workspace" Element 353 In AtomPub, a Workspace, represented by the "app:workspace" element, 354 describes a group of one or more Collections. Building on the 355 AtomPub concept of a Workspace, in ROLIE a Workspace represents an 356 aggregation of Collections pertaining to security automation 357 information resources. This specification does not impose any 358 restrictions on the number of Workspaces that may be in a Service 359 Document or the specific Collections to be provided within a given 360 Workspace. 362 The following restrictions are imposed on the use of the 363 app:workspace element in ROLIE: 365 o A ROLIE repository can host Collections containing both public and 366 private information entries. It is RECOMMENDED that public and 367 private Collections be segregated into different Workspaces. By 368 doing this, Workspaces that contain private information can be 369 ignored by clients or can be omitted from the Service Document 370 provided to a client that lacks the appropriate privilege to 371 access the set of Collections associated with the Workspace. 373 o Appropriate descriptions and naming conventions SHOULD be used to 374 indicate the intended audience of each workspace. This helps to 375 facilitate the selection of appropriate Workspaces by users. 377 5.1.2. Use of the "app:collection" Element 379 In AtomPub, a Collection in a Service Document, represented by the 380 "app:collection" element, provides metadata that can be used to point 381 to a specific Atom Feed that contains information Entries that may be 382 of interest to a client. The association between a Collection and a 383 Feed is provided by the "href" attribute of the app:collection 384 element. Building on the AtomPub concept of a Collection, in ROLIE a 385 Collection represents a pointer to a group of security automation 386 information resources pertaining to a given type of security 387 automation information. Collections are represented as Atom Feeds as 388 per RFC 5023. Atom Feed specific requirements are defined in section 389 6.1. 391 The following restrictions are imposed on the use of the 392 app:collection element for ROLIE: 394 o The atom:category elements contained in the app:categories element 395 MUST be the same set of atom:categories used in the Atom Feed 396 resource indicated by the app:collection "href" attribute value. 397 This ensures that the category metadata associated with the 398 Collection is discoverable in both the Feed and the corresponding 399 Collection in the Service Document. 401 o An app:collection pertaining to a security automation information 402 resource Feed MUST contain an app:categories element that 403 minimally contains a single atom:category element with the 404 "scheme" attribute value of 405 "urn:ietf:params:rolie:category:information-type". This category 406 MUST have an appropriate "term" attribute value as defined in 407 section 7.1.1. This ensures that a given Collection corresponds 408 to a specific type of security automation information. 410 o Any app:collection element that does not contain a descendant 411 atom:category element with the "scheme" attribute value of 412 "urn:ietf:params:rolie:category:information-type" MUST be 413 considered a non-ROLIE Collection. This allows Collections 414 pertaining to security automation information to co-exist 415 alongside Collections of other non-ROLIE information within the 416 same AtomPub instance. 418 o The app:categories element in an app:collection MAY include 419 additional atom:category elements using a scheme other than 420 "urn:ietf:params:rolie:category:information-type". This allows 421 other category metadata to be included. 423 5.1.3. Service Discovery 425 This specification requires that an implementation MUST publish an 426 Atom Service Document that describes the set of security information 427 sharing Collections that are provided by the repository. 429 The Service Document SHOULD be discoverable via the organization's 430 Web home page or another well-known public resource. An example of 431 this can be found in appendix B.1. 433 The Service Document MUST be retrievable using the standardized URI 434 template "https://{host:port}/rolie/servicedocument", where 435 {host:port} is the authority portion of the URI. Dereferencing this 436 URI MAY result in a redirect based on an appropriate HTTP 3xx status 437 code to direct the client to the actual Service Document. This 438 allows clients to have a well-known location to find a ROLIE service 439 document, while giving implementations flexibility over how the 440 service is deployed. 442 The service document MAY also be digitally signed and/or encrypted 443 according to XML Signature Syntax and Processing [xmldsig] and XML 444 Encryption Syntax and Processing [xmlenc] respectively. 446 5.2. AtomPub Category Documents 448 As described in RFC5023 section 7 [RFC5023], a Category Document is 449 an XML-based document format that allows a client to dynamically 450 discover the Categories used within AtomPub Service Documents, and 451 Atom Syndication Feed and Entry documents provided by a publisher. A 452 Category Document consists of one app:categories element that 453 contains a number of inline atom:category elements, or a URI 454 referencing a Category Document that describes the repository. 456 A ROLIE implementation MUST publish an Category Document that 457 describes the set of atom:category elements and associated terms used 458 within the implemented repository. 460 The Category Document MUST be retrievable using the standardized URI 461 template "https://{host:port}/rolie/categorydocument", where 462 {host:port} is the authority portion of the URI. Dereferencing this 463 URI MAY result in a redirect based on an appropriate HTTP 3xx status 464 code to direct the client to the actual Category Document. This 465 allows clients to have a well-known location to find a ROLIE category 466 document, while giving implementations flexibility over how the 467 service is deployed. 469 5.3. Transport Layer Security 471 ROLIE is intended to be handled with TLS. The following requirements 472 have been derived from [RFC7589]. 474 The most recent published version of TLS MUST be supported, and any 475 mandatory-to-implement (MTI) cipher suites in that version MUST be 476 supported as well. 478 The server MUST support certificate-based client authentication. The 479 implementation MAY use any TLS cipher suite that supports mutual 480 authentication. 482 During the TLS negotiation, the client MUST carefully examine the 483 certificate presented by the server to determine if it meets the 484 client's expectations. Particularly, the client MUST check its 485 understanding of the server hostname against the server's identity as 486 presented in the server Certificate message, in order to prevent man- 487 in-the-middle attacks. Matching is performed according to the rules 488 laid out in the Security Considerations section of [RFC4642]. 490 If the match fails, the client MUST either ask for explicit user 491 confirmation or terminate the connection and indicate the server's 492 identity is suspect. Additionally, clients MUST verify the binding 493 between the identity of the servers to which they connect and the 494 public keys presented by those servers. Clients SHOULD implement the 495 algorithm in Section 6 of [RFC5280] for general certificate 496 validation, but MAY supplement that algorithm with other validation 497 methods that achieve equivalent levels of verification (such as 498 comparing the server certificate against a local store of already- 499 verified certificates and identity bindings). If the client has 500 external information as to the expected identity of the server, the 501 hostname check MAY be omitted. 503 The server MUST be capable of verifying the identity of the client 504 with certificate-based authentication according to local policy to 505 ensure that the incoming client request is legitimate before any 506 configuration or state data is sent to or received from the client. 508 5.4. User Authentication and Authorization 510 Implementations MUST support user authentication. User 511 authentication MAY be enabled for specific Feeds. 513 Servers participating in an information sharing consortium and 514 supporting interactive user logins by members of the consortium 515 SHOULD support client authentication via a federated identity scheme 516 (e.g., SAML 2.0). 518 This document does not mandate the use of any specific user 519 authorization mechanisms. However, service implementers SHOULD 520 provide appropriate authorization checking for all resource accesses, 521 including individual Atom Entries, Atom Feeds, and Atom Service 522 Documents. 524 5.5. / (forward slash) Resource URL 526 The "/" resource MAY be provided for compatibility with existing 527 deployments that are using Transport of Real-time Inter-network 528 Defense (RID) Messages over HTTP/TLS [RFC6546]. If the "/" resource 529 is supported the following behavior MUST be also supported: 531 o Consistent with RFC6546 errata, a client requesting a GET on "/" 532 SHOULD receive an HTTP status code 405 Method Not Allowed. 534 o An implementation MAY provide full support for [RFC6546] such that 535 a POST to "/" containing a recognized RID message is handled 536 correctly as a RID request. Alternatively, a client requesting a 537 POST to "/" MAY receive an HTTP status code 307 Temporary 538 Redirect. In this case, the location header in the HTTP response 539 will provide the URL of the appropriate RID endpoint, and the 540 client may repeat the POST method at the indicated location. 542 If the "/" resource is unsupported, then a request for this resource 543 MUST provide a 404 HTTP status code. 545 5.6. HTTP methods 547 Servers MAY accept request methods beyond those specified in this 548 document. 550 Clients MUST be capable of recognizing and processing any standard 551 HTTP status code, as defined in [RFC5023] Section 5. 553 6. ROLIE Requirements for the Atom Syndication Format 555 This section describes a number of restrictions of and extensions to 556 the Atom Syndication Format [RFC4287] that define the use of that 557 format in the context of a ROLIE-based solution. The normative 558 requirements in this section are generally oriented towards any 559 content to be published to a ROLIE repository. An understanding of 560 the Atom Syndication Format specification [RFC4287] is helpful to 561 understand the requirements in this section. 563 6.1. Use of the "atom:feed" element 565 As described in RFC4287 section 4.1.1 [RFC4287], an Atom Feed is an 566 XML-based document format that describes a list of related 567 information items. The list of Atom Feeds provided by a ROLIE 568 service instance are listed in the service's Service Document through 569 one or more app:collection elements. Each Feed document, represented 570 using the atom:feed element, contains a listing of zero or more 571 related information items individually called a "Member Entry" or 572 "Entry". 574 When applied to the problem domain of security automation information 575 sharing, an Atom Feed may be used to represent any meaningful 576 collection of security automation information resources. Each Entry 577 in an atom:feed represents an individual resource (e.g., a specific 578 checklist, a software vulnerability record). Additional Feeds can be 579 used to represent other collections of security automation resources. 581 The following Atom Feed definition represents a stricter definition 582 of the atom:feed element defined in RFC 4287 for use in a ROLIE Any 583 element not specified here inherits its definition and requirements 584 from [RFC4287]. 586 atomFeed = 587 element atom:feed { 588 atomCommonAttributes, 589 (atomAuthor* 590 & atomCategory+ 591 & atomContributor* 592 & atomGenerator? 593 & atomIcon? 594 & atomId 595 & atomLink+ 596 & atomLogo? 597 & atomRights? 598 & atomSubtitle? 599 & atomTitle 600 & atomUpdated 601 & extensionElement*), 602 atomEntry* 603 } 605 6.1.1. Use of the "atom:category" Element 607 An atom:feed can be categorized and can contain information from zero 608 or more categories. In Atom the naming scheme and the semantic 609 meaning of the terms used to identify an Atom category are 610 application-defined. 612 The following restrictions are imposed on the use of the 613 atom:category element when used in an atom:feed: 615 o An atom:feed element MUST minimally contain a single atom:category 616 element with the "scheme" attribute value of 617 "urn:ietf:params:rolie:category:information-type". This category 618 MUST have an appropriate "term" attribute value as defined in 619 section 7.1.1. This ensures that a given Feed corresponds to a 620 specific type of security automation information. All member 621 Entries in the Feed MUST represent security automation information 622 records of the provided information type category or categories. 624 o Any atom:feed element that does not contain a child atom:category 625 element with the "scheme" attribute value of 626 "urn:ietf:params:rolie:category:information-type" MUST NOT be 627 considered a ROLIE Collection. This allows Feeds pertaining to 628 security automation information to co-exist alongside Feeds of 629 other non-ROLIE information within the same AtomPub instance. 631 o An atom:feed may include additional atom:category elements using a 632 scheme other than "urn:ietf:params:rolie:category:information- 633 type". This allows other category metadata to be included. 635 6.1.2. Use of the "atom:link" Element 637 Link relations defined by the atom:link element are used to represent 638 state transitions using a stateless approach. In Atom a type of link 639 relationship can be defined using the "rel" attribute. 641 A ROLIE atom:feed MUST contain one or more atom:link elements with 642 rel="service" and href attribute whose value is a IRI that points to 643 an Atom Service Document associated with the atom:feed. When a 644 client is presented with a Feed as its initial view into a 645 repository, a link with the service relationship provides a means to 646 discover additional security automation information. The "service" 647 link relationship is defined in the IANA Link Relations Registry [1]. 649 An atom:feed can contain an arbitrary number of Entries. In some 650 cases, a complete Feed may consist of a large number of Entries. 651 Additionally, as new and updated Entries are ordered at the beginning 652 of a Feed, a client may only be interested in retrieving the first N 653 entries in a Feed to process only the Entries that have changed since 654 the last retrieval of the Feed. As a practical matter, a large set 655 of Entries will likely need to be divided into more manageable 656 portions. Based on RFC5005 section 3 [RFC5005], link elements SHOULD 657 be included in all Feeds to support paging using the following link 658 relation types: 660 o "first" - Indicates that the href attribute value of the link 661 identifies a resource IRI for the furthest preceding page of the 662 Feed. 664 o "last" - Indicates that the href attribute value of the link 665 identifies a resource IRI for the furthest following page of the 666 Feed. 668 o "previous" - Indicates that the href attribute value of the link 669 identifies a resource IRI for the immediately preceding page of 670 the Feed. 672 o "next" - Indicates that the href attribute value of the link 673 identifies a resource IRI for the immediately following page of 674 the Feed. 676 For example: 678 679 680 b7f65304-b63b-4246-88e2-c104049c5fd7 681 Paged Feed 682 683 684 685 686 687 2012-05-04T18:13:51.0Z 689 690 692 Example Paged Feed 694 A reference to a historical Feed may need to be stable, and/or a Feed 695 may need to be divided into a series of defined epochs. 696 Implementations SHOULD support the mechanisms described in RFC5005 697 section 4 [RFC5005] to provide link-based state transitions for 698 maintaining archiving of Feeds. 700 An atom:feed MAY include additional link relationships not specified 701 in this document. If a client encounters an unknown link 702 relationship type, the client MUST ignore the unrecognized link and 703 continue processing as if the unrecognized link element did not 704 appear. The definition of new Link relations that provide additional 705 state transition extensions is discussed in section 7.3. 707 6.1.3. Use of the "atom:updated" Element 709 The atom:updated element MUST be populated with the current time at 710 the instant the Feed representation was last updated by adding, 711 updating, or deleting an Entry; or changing any metadata for the 712 Feed. 714 6.2. Use of the "atom:entry" Element 716 Each Entry in an Atom Feed, represented by the atom:entry element, 717 describes a single information record, format, and type combination. 718 The following atom:entry schema definition represents a stricter 719 representation of the atom:entry element defined in [RFC4287] for use 720 in a ROLIE-based Atom Feed. 722 atomEntry = 723 element atom:entry { 724 atomCommonAttributes, 725 (atomAuthor* 726 & atomCategory* 727 & atomContent 728 & atomContributor* 729 & atomId 730 & atomLink* 731 & atomPublished? 732 & atomRights? 733 & atomSource? 734 & atomSummary? 735 & atomTitle 736 & atomUpdated 737 & rolieFormat 738 & rolieProperty 739 & extensionElement*) 740 } 742 6.2.1. Use of the "atom:content" Element 744 There MUST be exactly one atomContent element in the Entry. The 745 content element MUST adhere to this definition, which is a stricter 746 representation of the atom:content element defined in [RFC4287]: 748 atomContent = 749 element atom:content { 750 atomCommonAttributes, 751 attribute type { atomMediaType }, 752 attribute src { atomUri }, 753 empty 754 } 756 The type attribute MUST identify the serialization type of the 757 content, for example, application/xml or application/json. A 758 prefixed media type MAY be used to reflect a specific model used with 759 a given serialization approach (e.g., application/rdf+xml). The src 760 attribute MUST be an IRI that can be dereferenced to retrieve the 761 related content data. 763 6.2.2. Use of the "atom:link" Element 765 Link relations can be included in an atom:entry to represent state 766 transitions for the Entry. 768 If there is a need to provide the same information in different data 769 models and/or serialization formats, separate Entry instances can be 770 included in the same or a different Feed. Such an alternate content 771 representation can be indicated using an atom:link having a rel 772 attribute with the value "alternate". 774 An atom:feed MAY include additional link relationships not specified 775 in this document. If a client encounters an unknown link 776 relationship type, the client MUST ignore the unrecognized link and 777 continue processing as if the unrecognized link element did not 778 appear. The definition of new Link relations that provide additional 779 state transition extensions is discussed in section 7.3. 781 6.2.3. Use of the "rolie:format" Element 783 As mentioned earlier, a key goal of this specification is to allow a 784 consumer to review a set of published security automation information 785 resources, and then identify and retrieve any resources of interest. 786 The format of the data is a key criteria to consider when deciding 787 what information to retrieve. For a given type of security 788 automation information, it is expected that a number of different 789 formats may be used to represent this information. To support this 790 use case, both the serialization format and the specific data model 791 expressed in that format must be known by the consumer. 793 The rolie:format element is used to describe the data model used to 794 express the information referenced in the atom:content element of an 795 atom:entry. It also allows a schema to be identified that can be 796 used when parsing the content to verify or better understand the 797 structure of the content. 799 There MUST be exactly one rolie:format element in an atom:entry. The 800 element MUST adhere to this definition: 802 rolieFormat = 803 element rolie:format { 804 appCommonAttributes, 805 attribute ns { atomURI }, 806 attribute version { text } ?, 807 attribute schema-location { atomURI } ?, 808 attribute schema-type { atomMediaType } ?, 809 empty 810 } 812 The rolie:format element MUST provide a "ns" attribute that 813 identifies the data model of the resource referenced by the 814 atom:content element. For example, the namespace used may be an XML 815 namespace URI, or an identifier that represents a serialized JSON 816 model. The URI used for the "ns" attribute value MUST be an absolute 817 or opaque URI. The resource identified by the URI need not be 818 resolvable. 820 The rolie:format element MAY provide a "version" attribute that 821 identifies the version of the format used for the related 822 atom:content. 824 The rolie:format element MAY provide a "schema-location" element that 825 is a URI that identifies a schema resource that can be used to 826 validate the related atom:content. 828 The rolie:format element MAY provide a "schema-type" element, which 829 is a mime type identifying the format of the schema resource 830 identified by the "schema-location" attribute. 832 For example, the nominal element would provide an indication that the content of this entry 836 is using the IODEF v2 format. 838 6.2.4. Use of the rolie:property Element 840 An atom:category element provides a way to associate a name/value 841 pair of categorical information using the scheme and term attributes 842 to represent the name, and the label attribute to represent the 843 value. When used in this way an atom:category allows a specific 844 label to be selected from a finite set of possible label values that 845 can be used to further classify a given atom:entry or atom:feed. 846 Within ROLIE, there may be a need to associate additional metadata 847 with an atom:entry. In such a case, use of an atom:category is not 848 practical to represent name/value data for which the allowed values 849 are unbounded. Instead, ROLIE has introduced a new rolie:property 850 element that can represent non-categorical metadata as name/value 851 pairs. Examples include content-specific identifiers, naming data, 852 and other properties that allow for unbounded values. 854 There MAY be zero or more rolie:property elements in an atom:entry. 856 The element MUST adhere to this definition: 858 rolieProperty = 859 element rolie:property { 860 app:appCommonAttributes, 861 attribute name { atom:atomURI }, 862 attribute value { text } 863 empty 864 } 866 The name attribute provides a URI that identifies the namespace and 867 name of the property as a URI. 869 The value attribute is text that provides a value for the property 870 identified by the name attribute. 872 For example, the nominal element 874 would expose an IODEF ID value contained in a given entry's content. 875 The name used in the example also demonstrates the use of a 876 registered ROLIE property extension, which is described in 877 Section 7.4. 879 Implementations MAY use locally defined and namespaced elements in an 880 Entry in order to provide additional information. Clients that do 881 not recognize a property with an unregistered name attribute MAY 882 ignore the rolie:property. 884 6.2.5. Requirements for a Standalone Entry 886 If an Entry is ever shared as a standalone resource, separate from 887 its containing Feed, then the following additional requirements 888 apply: 890 o The Entry MUST have a atom:link element with rel="collection" and 891 href="[IRI of the containing Collection]". This allows the Feed 892 or Feeds for which the Entry is a member to be discovered, along 893 with the related information the Feed may contain. In the case of 894 the Entry have multiple containing Feeds, the Entry MUST have one 895 atom:link for each related Feed. 897 o The Entry MUST declare the information type of the content 898 resource referenced by the Entry (see Section 7.1.2). 900 7. Available Extension Points Provided by ROLIE 902 This specification does not require particular information types or 903 data formats; rather, ROLIE is intended to be extended by additional 904 specifications that define the use of new categories and link 905 relations. The primary point of extension is through the definition 906 of new information type category terms. Additional specifications 907 can register new information type category terms with IANA that serve 908 as the main characterizing feature of a ROLIE Collection/Feed or 909 Resource/Entry. These additional specifications defining new 910 information type terms, can describe additional requirements for 911 including specific categories, link relations, as well as, use of 912 specific data formats supporting a given information type term. 914 7.1. The Category Extension Point 916 The atom:category element, defined in RFC 4287 section 4.2.2 917 [RFC4287], provides a mechanism to provide additional categorization 918 information for a content resource in ROLIE. The ability to define 919 new categories is one of the core extension points provided by Atom. 920 A Category Document, defined in RFC 5023 section 7 [RFC5023], 921 provides a mechanism for an Atom repository to make discoverable the 922 atom:category terms and allowed values used by a given repository. 924 ROLIE further defines the use of the existing Atom extension category 925 mechanism by allowing ROLIE specific category extensions to be 926 registered with IANA, and additionally has assigned the 927 "urn:ietf:params:rolie:category:information-type" category scheme 928 that has special meaning for implementations of ROLIE. This allows 929 category scheme namespaces to be managed in a more consistent way, 930 allowing for greater interoperability between content producers and 931 consumers. 933 Use of the "atom:category" element is discussed in the following 934 subsections. 936 7.1.1. General Use of the "atom:category" Element 938 The atom:category element can be used for characterizing a ROLIE 939 Resource. As discussed earlier in this document, an atom:category 940 element has a "term" attribute that indicates the assigned category 941 value, and a "scheme" attribute that provides an identifier for the 942 category type. The "scheme" provides a means to describe how a set 943 of category terms should be used and provides a namespace that can be 944 used to differentiate terms provided by multiple organizations with 945 different semantic meaning. 947 To further differentiate category types used in ROLIE, an IANA sub- 948 registry has been established for ROLIE protocol parameters to 949 support the registration of new category "scheme" attribute values by 950 ROLIE extension specifications. Use of this extension point is 951 discussed in section 8.3 using the name field with a type parameter 952 of "category" to indicate a category extension. 954 7.1.2. Identification of Security Automation Information Types 956 A ROLIE specific extension point is provided through the 957 atom:category "scheme" value 958 "urn:ietf:params:rolie:category:information-type". This value is a 959 Uniform Resource Name (URN) [RFC2141] that is registered with IANA as 960 described in section 8.3. When used as the "scheme" attribute in 961 this way, the "term" attribute is expected to be a registered value 962 as defined in section Section 8.4. Through this mechanism a given 963 security automation information type can be used to: 965 1. identify that an "app:collection" element in a Service Document 966 points to an Atom Feed that contains Entries pertaining to a 967 specific type of security automation information (see section 968 5.1.2), or 970 2. identify that an "atom:feed" element in an Atom Feed contains 971 Entries pertaining to a specific type of security automation 972 information (see section 6.1.1). 974 3. identify the information type of a standalone Resource (see 975 section 6.2.5). 977 For example, the notional security automation information type 978 "incident" would be identified as follows: 980 984 A security automation information type represents a class of 985 information that represents the same or similar information model 986 [RFC3444]. Notional examples of information types include: 988 indicator: Computing device- or network-related "observable features 989 and phenomenon that aid in the forensic or proactive detection of 990 malicious activity; and associated meta-data" (from [RFC7970]). 992 incident: Information pertaining to and "derived analysis from 993 security incidents" (from [RFC7970]). 995 vulnerability reports: Information identifying and describing a 996 vulnerability in hardware or software. 998 configuration checklists: Content that can be used to assess the 999 configuration settings related to installed software. 1001 software tags: Metadata used to identify and characterize 1002 installable software. 1004 This is a short list to inspire new engineering of information type 1005 extensions that support the automation of security processes. 1007 This document does not specific any information types. Instead, 1008 information types in ROLIE are expected to be registered in extension 1009 documents that describe one or more new information types. This 1010 allows the information types used by ROLIE implementations to grow 1011 over time to support new security automation use cases. These 1012 extension documents may also enhance ROLIE Service, Category, Feed, 1013 and Entry documents by defining link relations, other categories, and 1014 Format data model extensions to address the representational needs of 1015 these specific information types. New information types are added to 1016 ROLIE through registrations to the IANA ROLIE Security Resource 1017 Information Type registry defined in section 8.4. 1019 7.2. The "rolie:format" Extension Point 1021 Security automation data pertaining to a given information type may 1022 be expressed using a number of supported formats. As described in 1023 section 6.2.3, the rolie:format element is used to describe the 1024 specific data model used to represent the resource referenced by a 1025 given "atom:entry". The structure provided by the rolie:format 1026 element, provides a mechanism for extension within the atom:entry 1027 model. ROLIE extensions MAY further restrict which data models are 1028 allowed to be used for a given information type. 1030 By declaring the data model used for a given Resource, a consumer can 1031 choose to download or ignore the Resource, or look for alternate 1032 formats. This saves the consumer from downloading and parsing 1033 resources that the consumer is not interested in or resources 1034 expressed in formats that are not supported by the consumer. 1036 7.3. The Link Relation Extension Point 1038 This document uses several link relations defined in the IANA Link 1039 Relation Types registry [2]. Additional link relations can be 1040 registered in this registry to allow new relationships to be 1041 represented in ROLIE according to RFC 4287 section 4.2.7.2 [RFC4287]. 1042 Based on the preceding reference, if the link relation is too 1043 specific or limited in the intended use, an absolute IRI can be used 1044 in lieu of registering a new simple name with IANA. 1046 7.4. The "rolie:property" Extension Point 1048 As discussed previously in Section 6.2.4, many formats contain unique 1049 identifying and characterizing properties that are vital for sharing 1050 information. In order to provide a global reference for these 1051 properties, this document establishes an IANA registry in Section 7.4 1052 that allows ROLIE extensions to register named properties using the 1053 name field with a type parameter of "property" to indicate a property 1054 extension. Implementations SHOULD prefer the use of registered 1055 properties over implementation specific properties when possible. 1057 ROLIE extensions are expected to register new and use existing 1058 properties to provide valuable identifying and characterizing 1059 information for a given information type and/or format. 1061 8. IANA Considerations 1063 This document has a number of IANA considerations described in the 1064 following subsections. 1066 8.1. XML Namespaces and Schema URNs 1068 This document uses URNs to describe XML namespaces and XML schemas 1069 conforming to a registry mechanism described in [RFC3688]. 1071 ROLIE XML Namespace The ROLIE namespace (rolie-1.0) has been 1072 registered in the "ns" registry. 1074 URI: urn:ietf:params:xml:ns:rolie-1.0 1076 Registrant Contact: IESG 1078 XML: None. Namespace URIs do not represent an XML specification. 1080 ROLIE XML Schema The ROLIE schema (rolie-1.0) has been registered in 1081 the "schema" registry. 1083 URI: urn:ietf:params:xml:schema:rolie-1.0 1085 Registrant Contact: IESG 1087 XML: See section A of this document. 1089 8.2. ROLIE URN Sub-namespace 1091 IANA has added an entry to the "IETF URN Sub-namespace for Registered 1092 Protocol Parameter Identifiers" registry located at 1093 as per 1094 RFC3553 [RFC3553]. 1096 The entry is as follows: 1098 Registry name: rolie 1100 Specification: This document 1102 Repository: ROLIE URN Parameters. See Section 8.3 [TO BE REMOVED: 1103 This registration should take place at the following location: 1104 https://www.iana.org/assignments/rolie] 1106 Index value: See Section 8.3 1108 8.3. ROLIE URN Parameters 1110 A new top-level registry has been created, entitled "Resource 1111 Oriented Lightweight Information Exchange (ROLIE) Parameters". [TO 1112 BE REMOVED: This registration should take place at the following 1113 location: https://www.iana.org/assignments/rolie] 1115 In this top-level registry, a sub-registry entitled "ROLIE URN 1116 Parameters" has been created. Registration in this repository is via 1117 the Specification Required policy [RFC5226]. Designated Expert 1118 reviews should be routed through the MILE WG mailing list. Failing 1119 this, the Designated Expert will be assigned by the IESG. 1121 Each entry in this sub-registry must record the following fields: 1123 Name: A URN segment that adheres to the pattern {type}:{label}. 1124 The keywords are defined as follows: 1126 {type}: The parameter type. The allowed values are "category" 1127 or "property". "category" denotes a category extension as 1128 discussed in Section 7.1. "property" denotes a property 1129 extension as discussed in Section 7.4. 1131 {label}: A required US-ASCII string that conforms to the URN 1132 syntax requirements (see [RFC2141]). This string must be 1133 unique within the namespace defined by the {type} keyword. 1135 Extension IRI: The identifier to use within ROLIE, which is the 1136 full URN using the form: urn:ietf:params:rolie:{name}, where 1137 {name} is the "name" field of this registration. 1139 Reference: A static link to the specification and section that the 1140 definition of the parameter can be found. 1142 Sub-registry: An optional field that links to an IANA sub-registry 1143 for this parameter. If the {type} is "category", the sub-registry 1144 must contain a "name" field whose registered values MUST be US- 1145 ASCII. The list of names are the allowed values of the "term" 1146 attribute in the atom:category element. (See Section 7.1.2). 1148 This repository has the following initial values: 1150 +-----------+--------------------+------+---------------------------+ 1151 | Name | Extension IRI | Refe | Sub-Registry | 1152 | | | renc | | 1153 | | | e | | 1154 +-----------+--------------------+------+---------------------------+ 1155 | category: | urn:ietf:params:ro | This | [TO BE REMOVED: This | 1156 | informati | lie:category | docu | registration should take | 1157 | on-type | :information-type | ment | place at the following | 1158 | | | , Se | location: https://www.ian | 1159 | | | ctio | a.org/assignments/rolie/c | 1160 | | | n | ategory/information-type] | 1161 | | | 9.4 | | 1162 +-----------+--------------------+------+---------------------------+ 1164 8.4. ROLIE Security Resource Information Type Sub-Registry 1166 A new sub-registry has been created to store ROLIE information type 1167 values. 1169 Name of Registry: "ROLIE Information Types" 1171 Location of Registry: 1172 https://www.iana.org/assignments/rolie/category/information-type 1174 Fields to record in the registry: 1176 name: The full name of the security resource information type 1177 as a string from the printable ASCII character set [RFC0020] 1178 with individual embedded spaces allowed. The ABNF [RFC5234] 1179 syntax for this field is: 1181 1*VCHAR *(SP 1*VCHAR) 1183 index: This is an IANA-assigned positive integer that 1184 identifies the registration. The first entry added to this 1185 registry uses the value 1, and this value is incremented for 1186 each subsequent entry added to the registry. 1188 reference: A list of one or more URIs [RFC3986] from which the 1189 registered specification can be obtained. The registered 1190 specification MUST be readily and publicly available from that 1191 URI. The URI SHOULD be a stable reference. 1193 Allocation Policy: Specification required as per [RFC5226] 1195 9. Security Considerations 1197 This document defines a resource-oriented approach for lightweight 1198 information exchange using HTTP over TLS, the Atom Syndication 1199 Format, and the Atom Publishing Protocol. As such, implementers must 1200 understand the security considerations described in those 1201 specifications. All that follows is guidance, more specific 1202 instruction is out of scope for this document and will be located in 1203 a dedicated informational document. 1205 All security measures SHOULD be enforced at the source, that is, a 1206 provider SHOULD NOT return any Feed content or member Entry content 1207 for which the client identity has not been specifically 1208 authenticated, authorized, and audited. 1210 The approach described herein is based upon all policy enforcements 1211 being implemented at the point when a resource representation is 1212 created. As such, producers sharing cyber security information using 1213 this specification must take care to authenticate their HTTP clients 1214 using a suitably strong user authentication mechanism. Sharing 1215 communities that are exchanging information on well-known indicators 1216 and incidents for purposes of public education may choose to rely 1217 upon HTTP Authentication or similar. However, sharing communities 1218 that are engaged in sensitive collaborative analysis and/or 1219 operational response for indicators and incidents targeting high 1220 value information systems should adopt a suitably stronger user 1221 authentication solution, such as a risk-based or multi-factor 1222 approach. In general, trust in the sharing consortium will depend 1223 upon the members maintaining adequate user authentication mechanisms. 1225 Collaborating consortiums may benefit from the adoption of a 1226 federated identity solution, such as those based upon SAML-core 1227 [SAML-core], SAML-bind [SAML-bind], and SAML-prof [SAML-prof] for 1228 Web-based authentication and cross-organizational single sign-on. 1229 Dependency on a trusted third party identity provider implies that 1230 appropriate care must be exercised to sufficiently secure the 1231 Identity provider. Any attacks on the federated identity system 1232 would present a risk to the CSIRT, as a relying party. Potential 1233 mitigations include deployment of a federation-aware identity 1234 provider that is under the control of the information sharing 1235 consortium, with suitably stringent technical and management 1236 controls. 1238 Authorization of resource representations is the responsibility of 1239 the source system, i.e. based on the authenticated user identity 1240 associated with an HTTP(S) request. The required authorization 1241 policies that are to be enforced must therefore be managed by the 1242 security administrators of the source system. Various authorization 1243 architectures would be suitable for this purpose, such as RBAC [3] 1244 and/or ABAC, as embodied in XACML [XACML]. In particular, 1245 implementers adopting XACML may benefit from the capability to 1246 represent their authorization policies in a standardized, 1247 interoperable format. Note that implementers are free to choose any 1248 suitable authorization mechanism that is capable of fulfilling the 1249 policy enforcement requirements relevant to their consortium and/or 1250 organization. 1252 Additional security requirements such as enforcing message-level 1253 security at the destination system could supplement the security 1254 enforcements performed at the source system, however these 1255 destination-provided policy enforcements are out of scope for this 1256 specification. Implementers requiring this capability should 1257 consider leveraging, e.g. the element in the RID schema. 1258 Refer to RFC6545 section 9 for more information. 1260 When security policies relevant to the source system are to be 1261 enforced at both the source and destination systems, implementers 1262 must take care to avoid unintended interactions of the separately 1263 enforced policies. Potential risks will include unintended denial of 1264 service and/or unintended information leakage. These problems may be 1265 mitigated by avoiding any dependence upon enforcements performed at 1266 the destination system. When distributed enforcement is unavoidable, 1267 the usage of a standard language (e.g. XACML) for the expression of 1268 authorization policies will enable the source and destination systems 1269 to better coordinate and align their respective policy expressions. 1271 Adoption of the information sharing approach described in this 1272 document will enable users to more easily perform correlations across 1273 separate, and potentially unrelated, cyber security information 1274 providers. A client may succeed in assembling a data set that would 1275 not have been permitted within the context of the authorization 1276 policies of either provider when considered individually. Thus, 1277 providers may face a risk of an attacker obtaining an access that 1278 constitutes an undetected separation of duties (SOD) violation. It 1279 is important to note that this risk is not unique to this 1280 specification, and a similar potential for abuse exists with any 1281 other cyber security information sharing protocol. However, the wide 1282 availability of tools for HTTP clients and Atom Feed handling implies 1283 that the resources and technical skills required for a successful 1284 exploit may be less than it was previously. This risk can be best 1285 mitigated through appropriate vetting of the client at account 1286 provisioning time. In addition, any increase in the risk of this 1287 type of abuse should be offset by the corresponding increase in 1288 effectiveness that this specification affords to the defenders. 1290 10. Acknowledgements 1292 The authors gratefully acknowledge the valuable contributions of Tom 1293 Maguire, Kathleen Moriarty, and Vijayanand Bharadwaj. These 1294 individuals provided detailed review comments on earlier drafts, and 1295 made many suggestions that have helped to improve this document. 1297 11. References 1299 11.1. Normative References 1301 [RFC0020] Cerf, V., "ASCII format for network interchange", STD 80, 1302 RFC 20, DOI 10.17487/RFC0020, October 1969, 1303 . 1305 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1306 Requirement Levels", BCP 14, RFC 2119, 1307 DOI 10.17487/RFC2119, March 1997, 1308 . 1310 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1311 DOI 10.17487/RFC3688, January 2004, 1312 . 1314 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1315 Resource Identifier (URI): Generic Syntax", STD 66, 1316 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1317 . 1319 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 1320 Syndication Format", RFC 4287, DOI 10.17487/RFC4287, 1321 December 2005, . 1323 [RFC5005] Nottingham, M., "Feed Paging and Archiving", RFC 5005, 1324 DOI 10.17487/RFC5005, September 2007, 1325 . 1327 [RFC5023] Gregorio, J., Ed. and B. de hOra, Ed., "The Atom 1328 Publishing Protocol", RFC 5023, DOI 10.17487/RFC5023, 1329 October 2007, . 1331 [RFC7970] Danyliw, R., "The Incident Object Description Exchange 1332 Format Version 2", RFC 7970, DOI 10.17487/RFC7970, 1333 November 2016, . 1335 [RFC6546] Trammell, B., "Transport of Real-time Inter-network 1336 Defense (RID) Messages over HTTP/TLS", RFC 6546, 1337 DOI 10.17487/RFC6546, April 2012, 1338 . 1340 [RFC3553] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An 1341 IETF URN Sub-namespace for Registered Protocol 1342 Parameters", BCP 73, RFC 3553, DOI 10.17487/RFC3553, June 1343 2003, . 1345 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1346 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1347 DOI 10.17487/RFC5226, May 2008, 1348 . 1350 [W3C.REC-xml-names-20091208] 1351 Bray, T., Hollander, D., Layman, A., Tobin, R., and H. 1352 Thompson, "Namespaces in XML 1.0 (Third Edition)", World 1353 Wide Web Consortium Recommendation REC-xml-names-20091208, 1354 December 2009, 1355 . 1357 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 1358 NETCONF Protocol over Transport Layer Security (TLS) with 1359 Mutual X.509 Authentication", RFC 7589, 1360 DOI 10.17487/RFC7589, June 2015, 1361 . 1363 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1364 Housley, R., and W. Polk, "Internet X.509 Public Key 1365 Infrastructure Certificate and Certificate Revocation List 1366 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 1367 . 1369 [RFC4642] Murchison, K., Vinocur, J., and C. Newman, "Using 1370 Transport Layer Security (TLS) with Network News Transfer 1371 Protocol (NNTP)", RFC 4642, DOI 10.17487/RFC4642, October 1372 2006, . 1374 [relax-NG] 1375 Clark, J., Ed., "RELAX NG Compact Syntax", 11 2002, 1376 . 1379 11.2. Informative References 1381 [RFC2141] Moats, R., "URN Syntax", RFC 2141, DOI 10.17487/RFC2141, 1382 May 1997, . 1384 [RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between 1385 Information Models and Data Models", RFC 3444, 1386 DOI 10.17487/RFC3444, January 2003, 1387 . 1389 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1390 Specifications: ABNF", STD 68, RFC 5234, 1391 DOI 10.17487/RFC5234, January 2008, 1392 . 1394 [SAML-core] 1395 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 1396 "Assertions and Protocol for the OASIS Security Assertion 1397 Markup Language (SAML) V2.0", OASIS Standard saml-core- 1398 2.0-os, March 2005, . 1401 [SAML-prof] 1402 Hughes, J., Cantor, S., Hodges, J., Hirsch, F., Mishra, 1403 P., Philpott, R., and E. Maler, "Profiles for the OASIS 1404 Security Assertion Markup Language (SAML) V2.0", OASIS 1405 Standard OASIS.saml-profiles-2.0-os, March 2005, 1406 . 1409 [SAML-bind] 1410 Cantor, S., Hirsch, F., Kemp, J., Philpott, R., and E. 1411 Maler, "Bindings for the OASIS Security Assertion Markup 1412 Language (SAML) V2.0", OASIS Standard saml-bindings- 1413 2.0-os, March 2005, . 1416 [xmldsig] Bartel, M., Boyer, J., Fox, B., LaMacchia, B., and E. 1417 Simon, "XML Signature Syntax and Processing (Second 1418 Edition)", June 2008, . 1421 [xmlenc] Imamura, T., Dillaway, B., and E. Simon, "XML Encryption 1422 Syntax and Processing", December 2002, 1423 . 1425 [XACML] Rissanen, E., "eXtensible Access Control Markup Language 1426 (XACML) Version 3.0", August 2010, . 1429 [REST] Fielding, R., "Architectural Styles and the Design of 1430 Network-based Software Architectures", 2000, 1431 . 1434 11.3. URIs 1436 [1] https://www.iana.org/assignments/link-relations/link- 1437 relations.xhtml 1439 [2] https://www.iana.org/assignments/link-relations/link- 1440 relations.xhtml 1442 [3] http://csrc.nist.gov/groups/SNS/rbac/ 1444 Appendix A. Relax NG Compact Schema for ROLIE 1446 This appendix is informative. 1448 The Relax NG schema below defines the rolie:format element. 1450 # -*- rnc -*- 1451 # RELAX NG Compact Syntax Grammar for the rolie ns 1453 namespace rolie = "urn:ietf:params:xml:ns:rolie-1.0" 1454 namespace atom = "http://www.w3.org/2005/Atom" 1455 namespace app = "http://www.w3.org/2007/app" 1457 # rolie:format 1459 rolieFormat = 1460 element rolie:format { 1461 app:appCommonAttributes, 1462 attribute ns { atom:atomURI }, 1463 attribute version { text } ?, 1464 attribute schema-location { atom:atomURI } ?, 1465 attribute schema-type { atom:atomMediaType } ?, 1466 empty 1467 } 1469 # rolie:property 1471 rolieProperty = 1472 element rolie:property { 1473 app:appCommonAttributes, 1474 attribute name { atom:atomURI }, 1475 attribute value { text } 1476 empty 1477 } 1479 Appendix B. Examples of Use 1481 B.1. Service Discovery 1483 This section provides a non-normative example of a client doing 1484 service discovery. 1486 An Atom Service Document enables a client to dynamically discover 1487 what Feeds a particular publisher makes available. Thus, a provider 1488 uses an Atom Service Document to enable authorized clients to 1489 determine what specific information the provider makes available to 1490 the community. While the Service Document is accessible at a pre- 1491 determined location, the Service Document can also be made accessible 1492 from any well known location, such as via a link from the producer's 1493 home page. 1495 A client may format an HTTP GET request to retrieve the service 1496 document from the specified location: 1498 GET /rolie/servicedocument 1499 Host: www.example.org 1500 Accept: application/atomsvc+xml 1502 Notice the use of the HTTP Accept: request header, indicating the 1503 MIME type for Atom service discovery. The response to this GET 1504 request will be an XML document that contains information on the 1505 specific Collections that are provided. 1507 Example HTTP GET response: 1509 HTTP/1.1 200 OK 1510 Date: Fri, 24 Aug 2016 17:09:11 GMT 1511 Content-Length: 570 1512 Content-Type: application/atomsvc+xml;charset="utf-8" 1514 1515 1517 1518 Vulnerabilities 1519 1520 Vulnerabilities Feed 1521 1522 1525 1526 1527 1528 1530 This simple Service Document example shows that the server provides 1531 one workspace, named "Vunerabilities". Within that workspace, the 1532 server makes one Collection available. 1534 A server may also offer a number of different Collections, each 1535 containing different types of security automation information. In 1536 the following example, a number of different Collections are 1537 provided, each with its own category and authorization scope. This 1538 categorization will help the clients to decide which Collections will 1539 meet their needs. 1541 HTTP/1.1 200 OK 1542 Date: Fri, 24 Aug 2016 17:10:11 GMT 1543 Content-Length: 1912 1544 Content-Type: application/atomsvc+xml;charset="utf-8" 1546 1547 1549 1550 Public Security Information Sharing 1551 1553 Public Vulnerabilities 1554 1556 1557 1560 1561 1562 1563 1564 Private Consortium Sharing 1565 1567 Incidents 1568 1570 1571 1574 1575 1576 1577 1579 In this example, the provider is making available a total of two 1580 Collections, organized into two different workspaces. The first 1581 workspace contains a Collection consisting of publicly available 1582 software vulnerabilities. The second workspace provides an incident 1583 Collection for use by a private sharing consortium. An appropriately 1584 authenticated and authorized client may then proceed to make HTTP 1585 requests for these Collections. The publicly provided vulnerability 1586 information may be accessible with or without authentication. 1587 However, users accessing the Collection restricted to authorized 1588 members of a private sharing consortium are expected to authenticate 1589 before access is allowed. 1591 B.2. Feed Retrieval 1593 This section provides a non-normative example of a client retrieving 1594 an vulnerability Feed. 1596 Having discovered the available security information sharing 1597 Collections, a client who is a member of the general public may be 1598 interested in receiving the Collection of public vulnerabilities. 1599 The client may retrieve the Feed for this Collection by performing an 1600 HTTP GET operation on the URL indicated by the Collection's "href" 1601 attribute. 1603 Example HTTP GET request for a Feed: 1605 GET /provider/public/vulns 1606 Host: www.example.org 1607 Accept: application/atom+xml 1609 The corresponding HTTP response would be an XML document containing 1610 the vulnerability Feed: 1612 Example HTTP GET response for a Feed: 1614 HTTP/1.1 200 OK 1615 Date: Fri, 24 Aug 2016 17:20:11 GMT 1616 Content-Length: 2882 1617 Content-Type: application/atom+xml;charset="utf-8" 1619 1620 1623 2a7e265a-39bc-43f2-b711-b8fd9264b5c9 1624 1625 Atom formatted representation of 1626 a feed of XML vulnerability documents 1627 1628 1631 2016-05-04T18:13:51.0Z 1632 1634 1636 1637 1638 dd786dba-88e6-440b-9158-b8fae67ef67c 1639 Sample Vulnerability 1640 2015-08-04T18:13:51.0Z 1641 2015-08-05T18:13:51.0Z 1642 A vulnerability issue identified by CVE-... 1643 1647 1648 1649 1651 1653 This Feed document has two Atom Entries, one of which has been 1654 elided. The first Entry illustrates an atom:entry element that 1655 provides a summary of essential details about one particular 1656 vulnerability. Based upon this summary information and the provided 1657 category information, a client may choose to do an HTTP GET request, 1658 on the content "src" attribute, to retrieve the full details of the 1659 vulnerability. 1661 B.3. Entry Retrieval 1663 This section provides a non-normative example of a client retrieving 1664 an vulnerability as an Atom Entry. 1666 Having retrieved the Feed of interest, the client may then decide, 1667 based on the description and/or category information, that one of the 1668 entries in the Feed is of further interest. The client may retrieve 1669 this vulnerability Entry by performing an HTTP GET operation on the 1670 URL indicated by the "src" attribute of the atom:content element. 1672 Example HTTP GET request for an Entry: 1674 GET /provider/public/vulns/123456 1675 Host: www.example.org 1676 Accept: application/atom+xml;type=entry 1678 The corresponding HTTP response would be an XML document containing 1679 the Atom Entry for the vulnerability record: 1681 Example HTTP GET response for an Entry: 1683 HTTP/1.1 200 OK 1684 Date: Fri, 24 Aug 2016 17:30:11 GMT 1685 Content-Length: 713 1686 Content-Type: application/atom+xml;type=entry;charset="utf-8" 1688 1689 1692 f63aafa9-4082-48a3-9ce6-97a2d69d4a9b 1693 Sample Vulnerability 1694 2015-08-04T18:13:51.0Z 1695 2015-08-05T18:13:51.0Z 1696 1699 A vulnerability issue identified by CVE-... 1700 1701 1703 1704 1706 The example response above shows an XML document referenced by the 1707 "src" attribute of the atom:content element. The client may retrieve 1708 the document using this URL. 1710 Appendix C. Change History 1712 Changes in draft-ietf-mile-rolie-06 since draft-ietf-mile-rolie-05 1713 version, November 2, 2016 to TODO, 2016 1715 Changed to standards track 1717 Added the rolie:property element 1719 Fixed references (Normative vs Informative) 1721 Set Service and Category document URL template requirements 1723 Fixed XML snippets in examples 1725 Changes in draft-ietf-mile-rolie-05 since draft-ietf-mile-rolie-04 1726 version, October 21, 2016 to November 2, 2016 1728 Added ROLIE specific terminology to section 2 1730 Added AtomPub Category Document in section 5.2 1732 Edited document, improving consistency in terminology usage and 1733 capitalization of key terms, as well as enhancing clarity. 1735 Removed unused format parameter type in section 8.3 1737 Schema removed, the normative schema consists of the snippets in 1738 the requirements sections. 1740 Changes in draft-ietf-mile-rolie-04 since draft-ietf-mile-rolie-03 1741 version, July 8, 2016 to October 31, 2016 1743 o Further specification and clarification of requirements 1745 o IANA Considerations and extension system fleshed out and 1746 described. 1748 o Examples and References updated. 1750 o Schema created. 1752 o Fixed both internal section and external document referencing. 1754 o Removed XACML Guidance Appendix. This will be added to a future 1755 draft on ROLIE Authentication and Access Control. 1757 Changes made in draft-ietf-mile-rolie-03 since draft-ietf-mile- 1758 rolie-02 version, May 27, 2016 to July 8, 2015 1760 o Atom Syndication and Atom Pub requirements split and greatly 1761 expanded for increased justification and technical specification. 1763 o Reintroduction and reformatting of some use case examples in order 1764 to provide some guidance on use. 1766 o Established rough version of IANA table extension system along 1767 with explanations of said system. 1769 o Re-organized document to put non-vital information in appendices. 1771 Changes made in draft-ietf-mile-rolie-02 since draft-field-mile- 1772 rolie-01 version, December, 2015 to May 27, 2016: 1774 o All CSIRT and IODEF/RID material moved to companion CSIRT document 1776 o Recast document into a more general use perspective. The 1777 implication of CSIRTs as the defacto end-user has been removed 1778 where ever possible. All of the original CSIRT based use cases 1779 remain completely supported by this document, it has been opened 1780 up to support many other use cases. 1782 o Changed the content model to broaden support of representation 1784 o Edited and rewrote much of sections 1,2 and 3 in order to 1785 accomplish a broader scope and greater readability 1787 o Removed any requirements from the Background section and, if not 1788 already stated, placed them in the requirements section 1790 o Re-formatted the requirements section to make it clearer that it 1791 contains the lions-share of the requirements of the specification 1793 Changes made in draft-ietf-mile-rolie-01 since draft-field-mile- 1794 rolie-02 version, August 15, 2013 to December 2, 2015: 1796 o Added section specifying the use of RFC5005 for Archive and Paging 1797 of Feeds. 1799 o Added section describing use of atom categories that correspond to 1800 IODEF expectation class and impact classes. See: normative- 1801 expectation-impact 1803 o Dropped references to adoption of a MILE-specific HTTP media type 1804 parameter. 1806 o Updated IANA Considerations section to clarify that no IANA 1807 actions are required. 1809 Authors' Addresses 1811 John P. Field 1812 Pivotal Software, Inc. 1813 625 Avenue of the Americas 1814 New York, New York 1815 USA 1817 Phone: (646)792-5770 1818 Email: jfield@pivotal.io 1820 Stephen A. Banghart 1821 National Institute of Standards and Technology 1822 100 Bureau Drive 1823 Gaithersburg, Maryland 1824 USA 1826 Phone: (301)975-4288 1827 Email: sab3@nist.gov 1829 David Waltermire 1830 National Institute of Standards and Technology 1831 100 Bureau Drive 1832 Gaithersburg, Maryland 20877 1833 USA 1835 Email: david.waltermire@nist.gov