idnits 2.17.1 draft-ietf-mile-rolie-07.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 (May 24, 2017) is 2529 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 1507 -- Looks like a reference, but probably isn't: '2' on line 1510 -- Looks like a reference, but probably isn't: '3' on line 1513 ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) -- Obsolete informational reference (is this intentional?): RFC 2141 (Obsoleted by RFC 8141) Summary: 2 errors (**), 0 flaws (~~), 2 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: November 25, 2017 D. Waltermire 6 NIST 7 May 24, 2017 9 Resource-Oriented Lightweight Information Exchange 10 draft-ietf-mile-rolie-07 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 software descriptors, security incidents, attack 18 indicators, software vulnerabilities, configuration checklists, and 19 other security automation information as web-addressable resources. 20 Furthermore, consumers and other stakeholders may access and search 21 this security information as needed, establishing a rapid and on- 22 demand information exchange network for restricted internal use or 23 public access repositories. This specification extends the Atom 24 Publishing Protocol and Atom Syndication Format to transport and 25 share security 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 November 25, 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 5. ROLIE Requirements for the Atom Publishing Protocol . . . . . 6 75 5.1. AtomPub Service Documents . . . . . . . . . . . . . . . . 7 76 5.1.1. Use of the "app:workspace" Element . . . . . . . . . 7 77 5.1.2. Use of the "app:collection" Element . . . . . . . . . 8 78 5.1.3. Service Discovery . . . . . . . . . . . . . . . . . . 9 79 5.2. AtomPub Category Documents . . . . . . . . . . . . . . . 9 80 5.3. Transport Layer Security . . . . . . . . . . . . . . . . 10 81 5.4. User Authentication and Authorization . . . . . . . . . . 11 82 5.5. / (forward slash) Resource URL . . . . . . . . . . . . . 11 83 5.6. HTTP methods . . . . . . . . . . . . . . . . . . . . . . 11 84 6. ROLIE Requirements for the Atom Syndication Format . . . . . 12 85 6.1. Use of the "atom:feed" element . . . . . . . . . . . . . 12 86 6.1.1. Use of the "atom:category" Element . . . . . . . . . 13 87 6.1.2. Use of the "atom:link" Element . . . . . . . . . . . 14 88 6.1.3. Use of the "atom:updated" Element . . . . . . . . . . 15 89 6.2. Use of the "atom:entry" Element . . . . . . . . . . . . 15 90 6.2.1. Use of the "atom:content" Element . . . . . . . . . . 16 91 6.2.2. Use of the "atom:link" Element . . . . . . . . . . . 16 92 6.2.3. Use of the "rolie:format" Element . . . . . . . . . . 17 93 6.2.4. Use of the rolie:property Element . . . . . . . . . . 18 94 6.2.5. Requirements for a Standalone Entry . . . . . . . . . 19 95 7. Available Extension Points Provided by ROLIE . . . . . . . . 19 96 7.1. The Category Extension Point . . . . . . . . . . . . . . 20 97 7.1.1. General Use of the "atom:category" Element . . . . . 20 98 7.1.2. Identification of Security Automation Information 99 Types . . . . . . . . . . . . . . . . . . . . . . . . 21 100 7.2. The "rolie:format" Extension Point . . . . . . . . . . . 22 101 7.3. The Link Relation Extension Point . . . . . . . . . . . . 22 102 7.4. The "rolie:property" Extension Point . . . . . . . . . . 23 103 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 104 8.1. XML Namespaces and Schema URNs . . . . . . . . . . . . . 23 105 8.2. ROLIE URN Sub-namespace . . . . . . . . . . . . . . . . . 24 106 8.3. ROLIE URN Parameters . . . . . . . . . . . . . . . . . . 24 107 8.4. ROLIE Security Resource Information Type Sub-Registry . . 26 108 8.5. Well-Known URI Registrations . . . . . . . . . . . . . . 27 109 9. Security Considerations . . . . . . . . . . . . . . . . . . . 27 110 10. Privacy Considerations . . . . . . . . . . . . . . . . . . . 29 111 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 30 112 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 30 113 12.1. Normative References . . . . . . . . . . . . . . . . . . 30 114 12.2. Informative References . . . . . . . . . . . . . . . . . 32 115 12.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 33 116 Appendix A. Relax NG Compact Schema for ROLIE . . . . . . . . . 33 117 Appendix B. Examples of Use . . . . . . . . . . . . . . . . . . 34 118 B.1. Service Discovery . . . . . . . . . . . . . . . . . . . . 34 119 B.2. Feed Retrieval . . . . . . . . . . . . . . . . . . . . . 37 120 B.3. Entry Retrieval . . . . . . . . . . . . . . . . . . . . . 39 121 Appendix C. Change History . . . . . . . . . . . . . . . . . . . 40 122 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 42 124 1. Introduction 126 This document defines a resource-oriented approach to security 127 automation information sharing that follows the Representational 128 State Transfer (REST) architectural style [REST]. In this approach, 129 computer security resources are maintained in web-accessible 130 repositories structured as Atom Syndication Format [RFC4287] Feeds. 131 Within a given Feed, which may be requested by the consumer, 132 representations of specific types of security automation information 133 are organized, categorized, and described. Furthermore, all 134 collections available to a given user are discoverable, allowing the 135 consumer to search all available content they are authorized to view, 136 and to locate and request the desired information resources. Through 137 use of granular authentication and access controls, only authorized 138 consumers may be permitted the ability to read or write to a given 139 Feed. 141 The goal of this approach is to increase the communication and 142 sharing of security information between providers and consumers that 143 can be used to automate security processes (e.g., incident reports, 144 vulnerability assessments, configuration checklists, and other 145 security automation information). Such sharing allows human 146 operators and computer systems to leverage this standardized 147 communication system to gather information that supports the 148 automation of security processes. 150 In for new types of security automation information and associated 151 resource representations to be shared over time, this specification 152 defines extension points that can be used to add support for new 153 information types and associated resource representations by means of 154 additional supplementary specification documents. Sections 5 and 6 155 of this document define the core requirements of all implementations 156 of this specification, and is resource representation agnostic. An 157 overview of the extension system is provided in Section 7. 158 Implementers seeking to provide support for specific security 159 automation information types should refer to the specification for 160 that domain described by the IANA registry found in section 8.4. 162 2. Terminology 164 The key words "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT," 165 "SHOULD," "SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" in this 166 document are to be interpreted as described in [RFC2119]. 168 The previous key words are used in this document to define the 169 conformance requirements for implementations of this specification. 170 This document does not give any recommendations for the use of ROLIE, 171 it only provides conformance requirements for implementations of this 172 specification. 174 Definitions for some of the common computer security-related 175 terminology used in this document can be found in Section 2 of 176 [RFC7970]. 178 The following terms are unique to this specification: 180 Information Type A class of security automation information having 181 one or more associated data models. Often such security 182 automation information is used in the automation of a security 183 process. See section 7.1.2 for more information. 185 3. XML-related Conventions 187 3.1. XML Namespaces 189 This specification uses XML Namespaces [W3C.REC-xml-names-20091208] 190 to uniquely identify XML element names. It uses the following 191 namespace prefix mappings for the indicated namespace URI: 193 "app" is used for the "http://www.w3.org/2007/app" namespace 194 defined in [RFC5023]. 196 "atom" is used for the "http://www.w3.org/2005/Atom" namespace 197 defined in [RFC4287]. 199 "rolie" is used for the "urn:ietf:params:xml:ns:rolie:1.0" 200 namespace defined in section 8.1 of this specification. 202 3.2. RELAX NG Compact Schema 204 Some sections of this specification are illustrated with fragments of 205 a non-normative RELAX NG Compact schema [relax-NG]. The text of this 206 specification provides the definition of conformance. Schema for the 207 "http://www.w3.org/2007/app" and "http://www.w3.org/2005/Atom" 208 namespaces appear in RFC5023 appendix B [RFC5023] and RFC4287 209 appendix B [RFC4287] respectively. 211 A complete informative RELAX NG Compact Schema for the new elements 212 introduced by ROLIE is provided in Appendix A. 214 4. Background and Motivation 216 In order to automate security process, tools need access to 217 sufficient sources of structured, security information that can be 218 used to drive security processes. Thus, security information sharing 219 is one of the core components of automating security processes. 220 Vulnerabilities, configurations, software identification, security 221 incidents, and patch data are just a few of the classes of 222 information that are shared today to enable effective security on a 223 wide scale. However, as the scale of defense broadens as networks 224 become larger and more complex, and the volume of information to 225 process makes humans-in-the-loop difficult to scale, the need for 226 automation and machine-to-machine communication becomes increasingly 227 critical. 229 ROLIE seeks to address this need by providing three major information 230 sharing benefits: 232 Extensible information type categories and format agnosticism: ROLIE 233 is not bound to any given data format or category of information. 234 Instead, information categories are extensible, and entries 235 declare the format of the referenced data. In cases where several 236 formats or serializations are available, ROLIE can use link 237 relations to communicate how a consumer can access these formats. 238 For example, clients may request that a given resource 239 representation be returned as XML, JSON, or in some other format 240 or serialization. This approach allows the provider to support 241 multiple, compatible formats allowing the consumer to select the 242 most suitable version. 244 Open and distributed information sharing: Using the Atom Publishing 245 Protocol, ROLIE feeds can easily aggregate feeds and accept 246 information POSTed to them from other sources. Webs of 247 communicating ROLIE servers form ad-hoc sharing communities, 248 increasing data availability and the ability to correlate linked 249 data across sources for participating consumers. ROLIE servers 250 needn't be distributed however, as large ROLIE repositories can 251 function as a central or federated collections. 253 Stateless communication model: ROLIE, as a RESTful system, is 254 stateless. That is, the server doesn't keep track of client 255 sessions, but rather uses link relations for state transitions. 256 In practice, this means that any consumer can find and share 257 information at any organizational level and at any time without 258 needing to execute a long series of requests. 260 Information discovery and navigation: ROLIE provides a number of 261 mechanisms to allow clients to programmtically discover and 262 navigate collections of information in order to dynamically 263 discover new or revised content. Extensible information types and 264 other categories provide one way of determining content that is 265 desirable. Link elements, each with a target URI and an 266 established relationship type, provide a means for ROLIE providers 267 to link other information that is relevant to the current entry or 268 feed. 270 These benefits result in an information sharing protocol that is 271 lightweight, interactive, open, and most importantly, machine 272 readable. 274 The requirements in this specification are broken into two major 275 sections, extensions to the Atom Publishing Protocol (AtomPub) 276 [RFC5023], and extensions to the Atom Syndication Format [RFC4287]. 277 All normative requirements in AtomPub and Atom Syndication are 278 inherited from their respective specifications, and apply here unless 279 the requirement is explicitly overridden in this document. In this 280 way, this document may upgrade the requirement (e.g., make a SHOULD a 281 MUST), but will never downgrade a given requirement (e.g., make a 282 MUST a SHOULD). 284 5. ROLIE Requirements for the Atom Publishing Protocol 286 This section describes a number of restrictions of and extensions to 287 the Atom Publishing Protocol (AtomPub) [RFC5023] that define the use 288 of that protocol in the context of a ROLIE-based solution. The 289 normative requirements in this section are generally oriented towards 290 client and server implementations. An understanding of the Atom 291 Publishing Protocol specification [RFC5023] is helpful to understand 292 the requirements in this section. 294 5.1. AtomPub Service Documents 296 As described in RFC5023 section 8 [RFC5023], a Service Document is an 297 XML-based document format that allows a client to dynamically 298 discover the Collections provided by a publisher. A Service Document 299 consists of one or more app:workspace elements that may each contain 300 a number of app:collection elements. 302 The general structure of a service document is as follows (from 303 RFC5023 section 4.2 [RFC5023]): 305 Service 306 o- Workspace 307 | | 308 | o- Collection 309 | | | 310 | | o- IRI, categories, media types 311 | | 312 | o- ... 313 | 314 o- Workspace 315 | | 316 | o- Collection 317 | | | 318 | | o- IRI, categories, media types 319 | | 320 | o- ... 321 | 322 o- ... 324 5.1.1. Use of the "app:workspace" Element 326 In AtomPub, a Workspace, represented by the "app:workspace" element, 327 describes a group of one or more Collections. Building on the 328 AtomPub concept of a Workspace, in ROLIE a Workspace represents an 329 aggregation of Collections pertaining to security automation 330 information resources. This specification does not impose any 331 restrictions on the number of Workspaces that may be in a Service 332 Document or the specific Collections to be provided within a given 333 Workspace. 335 A ROLIE implementation can host Collections containing both public 336 and private information entries. It is RECOMMENDED that 337 implementations segregate public and private Collections into 338 different app:workspace elements. By doing this, Workspaces that 339 contain private information can be ignored by clients or can be 340 omitted from the Service Document provided to a client that lacks the 341 appropriate privilege to access the set of Collections associated 342 with the Workspace. 344 5.1.2. Use of the "app:collection" Element 346 In AtomPub, a Collection in a Service Document, represented by the 347 "app:collection" element, provides metadata that can be used to point 348 to a specific Atom Feed that contains information Entries that may be 349 of interest to a client. The association between a Collection and a 350 Feed is provided by the "href" attribute of the app:collection 351 element. Building on the AtomPub concept of a Collection, in ROLIE a 352 Collection represents a pointer to a group of security automation 353 information resources pertaining to a given type of security 354 automation information. Collections are represented as Atom Feeds as 355 per RFC 5023. Atom Feed specific requirements are defined in section 356 6.1. 358 The following restrictions are imposed on the use of the 359 app:collection element for ROLIE implementations: 361 o The atom:category elements contained in the app:categories element 362 MUST be the same set of atom:categories used in the Atom Feed 363 resource indicated by the app:collection "href" attribute value. 364 This ensures that the category metadata associated with the 365 Collection is discoverable in both the Feed and the corresponding 366 Collection in the Service Document. 368 o An app:collection pertaining to a security automation information 369 resource Feed MUST contain an app:categories element that 370 minimally contains a single atom:category element with the 371 "scheme" attribute value of 372 "urn:ietf:params:rolie:category:information-type". This category 373 MUST have an appropriate "term" attribute value as defined in 374 section 7.1.1. This ensures that a given Collection corresponds 375 to a specific type of security automation information. 377 o Any app:collection element that does not contain a descendant 378 atom:category element with the "scheme" attribute value of 379 "urn:ietf:params:rolie:category:information-type" MUST be 380 considered a non-ROLIE Collection. This allows Collections 381 pertaining to security automation information to co-exist 382 alongside Collections of other non-ROLIE information within the 383 same AtomPub instance. 385 o The app:categories element in an app:collection MAY include 386 additional atom:category elements using a scheme other than 387 "urn:ietf:params:rolie:category:information-type". This allows 388 other category metadata to be included. 390 5.1.3. Service Discovery 392 This specification requires that an implementation MUST publish an 393 Atom Service Document that describes the set of security information 394 Collections provided by the service. The Service Document MUST be 395 retrievable using the standardized URI template 396 "https://{host:port}/.well-known/rolie/servicedocument", where 397 {host:port} is the authority portion of the URI. Dereferencing this 398 URI MAY result in a redirect based on an appropriate HTTP 3xx status 399 code to direct the client to the actual Service Document. This 400 allows clients to have a well-known location to find a ROLIE service 401 document, while giving implementations flexibility over how the 402 service is deployed. 404 This document registers the "rolie/servicedocument" well-known URI as 405 per [RFC5785] in Section 8.5. 407 A mechanism to determine which host and port to use is not specified 408 in this document. Use of a mechanism such as DNS SRV Records 409 [RFC2782] can provide a secure and reliable discovery mechanism for 410 determining a specific host and port to use for retrieving a Service 411 Document for a given DNS domain. 413 5.2. AtomPub Category Documents 415 As described in RFC5023 section 7 [RFC5023], a Category Document is 416 an XML-based document format that allows a client to dynamically 417 discover the Categories used within AtomPub Service Documents, and 418 Atom Syndication Feed and Entry documents provided by a publisher. A 419 Category Document consists of one app:categories element that 420 contains a number of inline atom:category elements, or a URI 421 referencing a Category Document. 423 A ROLIE implementation MUST publish a Category Document that 424 describes the set of atom:category elements and associated terms 425 currently used by the service. 427 The Category Document MUST be retrievable using the standardized URI 428 template "https://{host:port}/.well-known/rolie/categorydocument", 429 where {host:port} is the authority portion of the URI. Dereferencing 430 this URI MAY result in a redirect based on an appropriate HTTP 3xx 431 status code to direct the client to the actual Category Document. 432 This allows clients to have a well-known location to find a ROLIE 433 category document, while giving implementations flexibility over how 434 the service is deployed. 436 This document registers the "rolie/categorydocument" well-known URI 437 as per [RFC5785] in Section 8.5. 439 5.3. Transport Layer Security 441 ROLIE is intended to be handled with TLS. The following requirements 442 have been derived from [RFC7589]. 444 The most recent published version of TLS MUST be supported, and any 445 mandatory-to-implement (MTI) cipher suites in that version MUST be 446 supported as well. 448 The server MUST support certificate-based client authentication. The 449 implementation MAY use any TLS cipher suite that supports mutual 450 authentication. 452 During the TLS negotiation, the client MUST carefully examine the 453 certificate presented by the server to determine if it meets the 454 client's expectations. Particularly, the client MUST check its 455 understanding of the server hostname against the server's identity as 456 presented in the server Certificate message, in order to prevent man- 457 in-the-middle attacks. Matching is performed according to the rules 458 laid out in the Security Considerations section of [RFC4642]. 460 If the match fails, the client MUST either ask for explicit user 461 confirmation or terminate the connection and indicate the server's 462 identity is suspect. Additionally, clients MUST verify the binding 463 between the identity of the servers to which they connect and the 464 public keys presented by those servers. Client implementations 465 SHOULD support an equivalent certificate validation approach to the 466 what is defined in Section 6 of [RFC5280], but MAY supplement that 467 algorithm with other validation methods that achieve equivalent 468 levels of verification (such as comparing the server certificate 469 against a local store of already-verified certificates and identity 470 bindings). If the client has external information as to the expected 471 identity of the server, the hostname check MAY be omitted. 473 The server MUST be capable of verifying the identity of the client 474 with certificate-based authentication according to local policy to 475 ensure that the incoming client request is legitimate before any 476 configuration or state data is sent to or received from the client. 478 5.4. User Authentication and Authorization 480 Implementations MUST support user authentication. However, a given 481 implementation MAY allow user authentication to be disabled on a feed 482 by feed basis. 484 Servers participating in an information sharing consortium and 485 supporting interactive user logins by members of the consortium 486 SHOULD support client authentication via a federated identity scheme 487 (e.g., SAML 2.0). 489 This document does not mandate the use of any specific user 490 authorization mechanisms. However, service implementers SHOULD 491 provide appropriate authorization checking for all resource accesses, 492 including individual Atom Entries, Atom Feeds, and Atom Service 493 Documents. 495 5.5. / (forward slash) Resource URL 497 The "/" resource MAY be provided for compatibility with existing 498 deployments that are using Transport of Real-time Inter-network 499 Defense (RID) Messages over HTTP/TLS [RFC6546]. If the "/" resource 500 is supported the following behavior MUST be also supported: 502 o Consistent with RFC6546 errata, a client requesting a GET on "/" 503 SHOULD receive an HTTP status code 405 Method Not Allowed. 505 o An implementation MAY provide full support for [RFC6546] such that 506 a POST to "/" containing a recognized RID message is handled 507 correctly as a RID request. Alternatively, a client requesting a 508 POST to "/" MAY receive an HTTP status code 307 Temporary 509 Redirect. In this case, the location header in the HTTP response 510 will provide the URL of the appropriate RID endpoint, and the 511 client may repeat the POST method at the indicated location. 513 If the "/" resource is unsupported, then a request for this resource 514 MUST provide a 404 HTTP status code. 516 5.6. HTTP methods 518 Servers MAY accept request methods beyond those specified in this 519 document. 521 Clients MUST be capable of recognizing and processing any standard 522 HTTP status code, as defined in [RFC5023] Section 5. 524 6. ROLIE Requirements for the Atom Syndication Format 526 This section describes a number of restrictions of and extensions to 527 the Atom Syndication Format [RFC4287] that define the use of that 528 format in the context of a ROLIE-based solution. The normative 529 requirements in this section are generally oriented towards any 530 content to be published to a ROLIE server. An understanding of the 531 Atom Syndication Format specification [RFC4287] is helpful to 532 understand the requirements in this section. 534 6.1. Use of the "atom:feed" element 536 As described in RFC4287 section 4.1.1 [RFC4287], an Atom Feed is an 537 XML-based document format that describes a list of related 538 information items. The list of Atom Feeds provided by a ROLIE 539 service instance are listed in the service's Service Document through 540 one or more app:collection elements. Each Feed document, represented 541 using the atom:feed element, contains a listing of zero or more 542 related information items individually called a "Member Entry" or 543 "Entry". 545 When applied to the problem domain of security automation information 546 sharing, an Atom Feed may be used to represent any meaningful 547 collection of security automation information resources. Each Entry 548 in an atom:feed represents an individual resource (e.g., a specific 549 checklist, a software vulnerability record). Additional Feeds can be 550 used to represent other collections of security automation resources. 552 The following Atom Feed definition represents a stricter definition 553 of the atom:feed element defined in RFC 4287 for use in a ROLIE 554 implementation. Any element not specified here inherits its 555 definition and requirements from [RFC4287]. 557 atomFeed = 558 element atom:feed { 559 atomCommonAttributes, 560 (atomAuthor* 561 & atomCategory+ 562 & atomContributor* 563 & atomGenerator? 564 & atomIcon? 565 & atomId 566 & atomLink+ 567 & atomLogo? 568 & atomRights? 569 & atomSubtitle? 570 & atomTitle 571 & atomUpdated 572 & extensionElement*), 573 atomEntry* 574 } 576 6.1.1. Use of the "atom:category" Element 578 An atom:feed can be categorized and can contain information from zero 579 or more categories. In Atom the naming scheme and the semantic 580 meaning of the terms used to identify an Atom category are 581 application-defined. 583 The following restrictions are imposed on the use of the 584 atom:category element when used in an atom:feed: 586 o An atom:feed element MUST minimally contain a single atom:category 587 element with the "scheme" attribute value of 588 "urn:ietf:params:rolie:category:information-type". This category 589 MUST have an appropriate "term" attribute value as defined in 590 section 7.1.1. This ensures that a given Feed corresponds to a 591 specific type of security automation information. All member 592 Entries in the Feed MUST represent security automation information 593 records of the provided information type category or categories. 595 o Any atom:feed element that does not contain a child atom:category 596 element with the "scheme" attribute value of 597 "urn:ietf:params:rolie:category:information-type" MUST NOT be 598 considered a ROLIE Collection. This allows Feeds pertaining to 599 security automation information to co-exist alongside Feeds of 600 other non-ROLIE information within the same AtomPub instance. 602 o An atom:feed MAY include additional atom:category elements using a 603 scheme other than "urn:ietf:params:rolie:category:information- 604 type". This allows other category metadata to be included. 606 6.1.2. Use of the "atom:link" Element 608 Link relations defined by the atom:link element are used to represent 609 state transitions using a stateless approach. In Atom a type of link 610 relationship can be defined using the "rel" attribute. 612 A ROLIE atom:feed MUST contain one or more atom:link elements with 613 rel="service" and href attribute whose value is a IRI that points to 614 an Atom Service Document associated with the atom:feed. If a client 615 accesses a Feed without first accessing the service's service 616 document, a link with the "service" relationship provides a means to 617 discover additional security automation information. The "service" 618 link relationship is defined in the IANA Link Relations Registry [1]. 620 An atom:feed can contain an arbitrary number of Entries. In some 621 cases, a complete Feed may consist of a large number of Entries. 622 Additionally, as new and updated Entries are ordered at the beginning 623 of a Feed, a client may only be interested in retrieving the first N 624 entries in a Feed to process only the Entries that have changed since 625 the last retrieval of the Feed. As a practical matter, a large set 626 of Entries will likely need to be divided into more manageable 627 portions. Based on RFC5005 section 3 [RFC5005], link elements SHOULD 628 be included in all Feeds to support paging using the following link 629 relation types: 631 o "first" - Indicates that the href attribute value of the link 632 identifies a resource IRI for the furthest preceding page of the 633 Feed. 635 o "last" - Indicates that the href attribute value of the link 636 identifies a resource IRI for the furthest following page of the 637 Feed. 639 o "previous" - Indicates that the href attribute value of the link 640 identifies a resource IRI for the immediately preceding page of 641 the Feed. 643 o "next" - Indicates that the href attribute value of the link 644 identifies a resource IRI for the immediately following page of 645 the Feed. 647 For example: 649 650 651 b7f65304-b63b-4246-88e2-c104049c5fd7 652 Paged Feed 653 654 655 656 657 658 2012-05-04T18:13:51.0Z 660 661 663 Example Paged Feed 665 A reference to a historical Feed may need to be stable, and/or a Feed 666 may need to be divided into a series of defined epochs. 667 Implementations SHOULD support the mechanisms described in RFC5005 668 section 4 [RFC5005] to provide link-based state transitions for 669 maintaining archiving of Feeds. 671 An atom:feed MAY include additional link relationships not specified 672 in this document. If a client encounters an unknown link 673 relationship type, the client MUST ignore the unrecognized link and 674 continue processing as if the unrecognized link element did not 675 appear. The definition of new Link relations that provide additional 676 state transition extensions is discussed in section 7.3. 678 6.1.3. Use of the "atom:updated" Element 680 The atom:updated element MUST be populated with the current time at 681 the instant the Feed representation was last updated by adding, 682 updating, or deleting an Entry; or changing any metadata for the 683 Feed. 685 6.2. Use of the "atom:entry" Element 687 Each Entry in an Atom Feed, represented by the atom:entry element, 688 describes a single referenced information record, along with 689 descriptive information about its format, media type, and other 690 publication metadata. The following atom:entry schema definition 691 represents a stricter representation of the atom:entry element 692 defined in [RFC4287] for use in a ROLIE-based Atom Feed. 694 atomEntry = 695 element atom:entry { 696 atomCommonAttributes, 697 (atomAuthor* 698 & atomCategory* 699 & atomContent 700 & atomContributor* 701 & atomId 702 & atomLink* 703 & atomPublished? 704 & atomRights? 705 & atomSource? 706 & atomSummary? 707 & atomTitle 708 & atomUpdated 709 & rolieFormat 710 & rolieProperty* 711 & extensionElement*) 712 } 714 6.2.1. Use of the "atom:content" Element 716 There MUST be exactly one atomContent element in the Entry. The 717 content element MUST adhere to this definition, which is a stricter 718 representation of the atom:content element defined in [RFC4287]: 720 atomContent = 721 element atom:content { 722 atomCommonAttributes, 723 attribute type { atomMediaType }, 724 attribute src { atomUri }, 725 empty 726 } 728 The type attribute MUST identify the serialization type of the 729 content, for example, application/xml or application/json. A 730 prefixed media type MAY be used to reflect a specific model used with 731 a given serialization approach (e.g., application/rdf+xml). The src 732 attribute MUST be an IRI that can be dereferenced to retrieve the 733 related content data. 735 6.2.2. Use of the "atom:link" Element 737 Link relations can be included in an atom:entry to represent state 738 transitions for the Entry. 740 If there is a need to provide the same information in different data 741 models and/or serialization formats, separate Entry instances can be 742 included in the same or a different Feed. Such an alternate content 743 representation can be indicated using an atom:link having a rel 744 attribute with the value "alternate". 746 An atom:feed MAY include additional link relationships not specified 747 in this document. If a client encounters an unknown link 748 relationship type, the client MUST ignore the unrecognized link and 749 continue processing as if the unrecognized link element did not 750 appear. The definition of new Link relations that provide additional 751 state transition extensions is discussed in section 7.3. 753 6.2.3. Use of the "rolie:format" Element 755 As mentioned earlier, a key goal of this specification is to allow a 756 consumer to review a set of published security automation information 757 resources, and then identify and retrieve any resources of interest. 758 The format of the data is a key criteria to consider when deciding 759 what information to retrieve. For a given type of security 760 automation information, it is expected that a number of different 761 formats may be used to represent this information. To support this 762 use case, both the serialization format and the specific data model 763 expressed in that format must be known by the consumer. 765 The rolie:format element is used to describe the data model used to 766 express the information referenced in the atom:content element of an 767 atom:entry. It also allows a schema to be identified that can be 768 used when parsing the content to verify or better understand the 769 structure of the content. 771 There MUST be exactly one rolie:format element in an atom:entry. The 772 element MUST adhere to this definition: 774 rolieFormat = 775 element rolie:format { 776 appCommonAttributes, 777 attribute ns { atomURI }, 778 attribute version { text } ?, 779 attribute schema-location { atomURI } ?, 780 attribute schema-type { atomMediaType } ?, 781 empty 782 } 784 The rolie:format element MUST provide a "ns" attribute that 785 identifies the data model of the resource referenced by the 786 atom:content element. For example, the namespace used may be an XML 787 namespace URI, or an identifier that represents a serialized JSON 788 model. The URI used for the "ns" attribute value MUST be an absolute 789 or opaque URI. The resource identified by the URI need not be 790 resolvable. 792 The rolie:format element MAY provide a "version" attribute that 793 identifies the version of the format used for the related 794 atom:content. 796 The rolie:format element MAY provide a "schema-location" attribute 797 that is a URI that identifies a schema resource that can be used to 798 validate the related atom:content. 800 The rolie:format element MAY provide a "schema-type" attribute, which 801 is a mime type identifying the format of the schema resource 802 identified by the "schema-location" attribute. 804 The following nominal example shows how these attributes describe the 805 format of the content: 807 813 The previous element provides an indication that the content of the 814 given entry is using the IODEF v2 format. 816 6.2.4. Use of the rolie:property Element 818 An atom:category element provides a way to associate a name/value 819 pair of categorical information using the scheme and term attributes 820 to represent the name, and the label attribute to represent the 821 value. When used in this way an atom:category allows a specific 822 label to be selected from a finite set of possible label values that 823 can be used to further classify a given atom:entry or atom:feed. 824 Within ROLIE, there may be a need to associate additional metadata 825 with an atom:entry. In such a case, use of an atom:category is not 826 practical to represent name/value data for which the allowed values 827 are unbounded. Instead, ROLIE has introduced a new rolie:property 828 element that can represent non-categorical metadata as name/value 829 pairs. Examples include content-specific identifiers, naming data, 830 and other properties that allow for unbounded values. 832 There MAY be zero or more rolie:property elements in an atom:entry. 834 The element MUST adhere to this definition: 836 rolieProperty = 837 element rolie:property { 838 app:appCommonAttributes, 839 attribute name { atom:atomURI }, 840 attribute value { text } 841 empty 842 } 844 The name attribute provides a URI that identifies the namespace and 845 name of the property as a URI. 847 The value attribute is text that provides a value for the property 848 identified by the name attribute. 850 For example, the nominal element 852 would expose an IODEF ID value contained in a given entry's content. 853 The name used in the example also demonstrates the use of a 854 registered ROLIE property extension, which is described in 855 Section 7.4. 857 Implementations MAY use locally defined and namespaced elements in an 858 Entry in order to provide additional information. Clients that do 859 not recognize a property with an unregistered name attribute MAY 860 ignore the rolie:property. 862 6.2.5. Requirements for a Standalone Entry 864 If an Entry is ever shared as a standalone resource, separate from 865 its containing Feed, then the following additional requirements 866 apply: 868 o The Entry MUST have an atom:link element with rel="collection" and 869 href="[IRI of the containing Collection]". This allows the Feed 870 or Feeds for which the Entry is a member to be discovered, along 871 with the related information the Feed may contain. In the case of 872 the Entry have multiple containing Feeds, the Entry MUST have one 873 atom:link for each related Feed. 875 o The Entry MUST declare the information type of the content 876 resource referenced by the Entry (see Section 7.1.2). 878 7. Available Extension Points Provided by ROLIE 880 This specification does not require particular information types or 881 data formats; rather, ROLIE is intended to be extended by additional 882 specifications that define the use of new categories and link 883 relations. The primary point of extension is through the definition 884 of new information type category terms. Additional specifications 885 can register new information type category terms with IANA that serve 886 as the main characterizing feature of a ROLIE Collection/Feed or 887 Resource/Entry. These additional specifications defining new 888 information type terms, can describe additional requirements for 889 including specific categories, link relations, as well as, use of 890 specific data formats supporting a given information type term. 892 7.1. The Category Extension Point 894 The atom:category element, defined in RFC 4287 section 4.2.2 895 [RFC4287], provides a mechanism to provide additional categorization 896 information for a content resource in ROLIE. The ability to define 897 new categories is one of the core extension points provided by Atom. 898 A Category Document, defined in RFC 5023 section 7 [RFC5023], 899 provides a mechanism for an Atom implementation to make discoverable 900 the atom:category terms and associated allowed values. 902 ROLIE further defines the use of the existing Atom extension category 903 mechanism by allowing ROLIE specific category extensions to be 904 registered with IANA, and additionally has assigned the 905 "urn:ietf:params:rolie:category:information-type" category scheme 906 that has special meaning for implementations of ROLIE. This allows 907 category scheme namespaces to be managed in a more consistent way, 908 allowing for greater interoperability between content producers and 909 consumers. 911 The namespace "urn:ietf:params:rolie:category:local" has been 912 reserved in the IANA ROLIE Parameters table for private use as 913 defined in [RFC5226]. Any category whose "scheme" attribute uses 914 this as a prefix MUST be considered private use. Implementations 915 encountering such a category MUST parse the content without error, 916 but MAY otherwise ignore the element. 918 Use of the "atom:category" element is discussed in the following 919 subsections. 921 7.1.1. General Use of the "atom:category" Element 923 The atom:category element can be used for characterizing a ROLIE 924 Resource. As discussed earlier in this document, an atom:category 925 element has a "term" attribute that indicates the assigned category 926 value, and a "scheme" attribute that provides an identifier for the 927 category type. The "scheme" provides a means to describe how a set 928 of category terms should be used and provides a namespace that can be 929 used to differentiate terms provided by multiple organizations with 930 different semantic meaning. 932 To further differentiate category types used in ROLIE, an IANA sub- 933 registry has been established for ROLIE protocol parameters to 934 support the registration of new category "scheme" attribute values by 935 ROLIE extension specifications. Use of this extension point is 936 discussed in section 8.3 using the name field with a type parameter 937 of "category" to indicate a category extension. 939 7.1.2. Identification of Security Automation Information Types 941 A ROLIE specific extension point is provided through the 942 atom:category "scheme" value 943 "urn:ietf:params:rolie:category:information-type". This value is a 944 Uniform Resource Name (URN) [RFC2141] that is registered with IANA as 945 described in section 8.3. When used as the "scheme" attribute in 946 this way, the "term" attribute is expected to be a registered value 947 as defined in section Section 8.4. Through this mechanism a given 948 security automation information type can be used to: 950 1. identify that an "app:collection" element in a Service Document 951 points to an Atom Feed that contains Entries pertaining to a 952 specific type of security automation information (see section 953 5.1.2), or 955 2. identify that an "atom:feed" element in an Atom Feed contains 956 Entries pertaining to a specific type of security automation 957 information (see section 6.1.1). 959 3. identify the information type of a standalone Resource (see 960 section 6.2.5). 962 For example, the notional security automation information type 963 "incident" would be identified as follows: 965 969 A security automation information type represents a class of 970 information that represents the same or similar information model 971 [RFC3444]. Notional examples of information types include: 973 indicator: Computing device- or network-related "observable features 974 and phenomenon that aid in the forensic or proactive detection of 975 malicious activity; and associated meta-data" (from [RFC7970]). 977 incident: Information pertaining to and "derived analysis from 978 security incidents" (from [RFC7970]). 980 vulnerability reports: Information identifying and describing a 981 vulnerability in hardware or software. 983 configuration checklists: Content that can be used to assess the 984 configuration settings related to installed software. 986 software tags: Metadata used to identify and characterize 987 installable software. 989 This is a short list to inspire new engineering of information type 990 extensions that support the automation of security processes. 992 This document does not specific any information types. Instead, 993 information types in ROLIE are expected to be registered in extension 994 documents that describe one or more new information types. This 995 allows the information types used by ROLIE implementations to grow 996 over time to support new security automation use cases. These 997 extension documents may also enhance ROLIE Service, Category, Feed, 998 and Entry documents by defining link relations, other categories, and 999 Format data model extensions to address the representational needs of 1000 these specific information types. New information types are added to 1001 ROLIE through registrations to the IANA ROLIE Security Resource 1002 Information Type registry defined in section 8.4. 1004 7.2. The "rolie:format" Extension Point 1006 Security automation data pertaining to a given information type may 1007 be expressed using a number of supported formats. As described in 1008 section 6.2.3, the rolie:format element is used to describe the 1009 specific data model used to represent the resource referenced by a 1010 given "atom:entry". The structure provided by the rolie:format 1011 element, provides a mechanism for extension within the atom:entry 1012 model. ROLIE extensions MAY further restrict which data models are 1013 allowed to be used for a given information type. 1015 By declaring the data model used for a given Resource, a consumer can 1016 choose to download or ignore the Resource, or look for alternate 1017 formats. This saves the consumer from downloading and parsing 1018 resources that the consumer is not interested in or resources 1019 expressed in formats that are not supported by the consumer. 1021 7.3. The Link Relation Extension Point 1023 This document uses several link relations defined in the IANA Link 1024 Relation Types registry [2]. Additional link relations can be 1025 registered in this registry to allow new relationships to be 1026 represented in ROLIE according to RFC 4287 section 4.2.7.2 [RFC4287]. 1027 Based on the preceding reference, if the link relation is too 1028 specific or limited in the intended use, an absolute IRI can be used 1029 in lieu of registering a new simple name with IANA. 1031 7.4. The "rolie:property" Extension Point 1033 As discussed previously in Section 6.2.4, many formats contain unique 1034 identifying and characterizing properties that are vital for sharing 1035 information. In order to provide a global reference for these 1036 properties, this document establishes an IANA registry in Section 8.3 1037 that allows ROLIE extensions to register named properties using the 1038 name field with a type parameter of "property" to indicate a property 1039 extension. Implementations SHOULD prefer the use of registered 1040 properties over implementation specific properties when possible. 1042 ROLIE extensions are expected to register new and use existing 1043 properties to provide valuable identifying and characterizing 1044 information for a given information type and/or format. 1046 The namespace "urn:ietf:params:rolie:property:local" has been 1047 reserved in the IANA ROLIE Parameters table for private use as 1048 defined in [RFC5226]. Any property whose "name" attribute uses this 1049 as a prefix MUST be considered private use. Implementations 1050 encountering such a property MUST parse the content without error, 1051 but MAY otherwise ignore the element. 1053 This document also registers the 1054 "urn:ietf:params:rolie:property:content-author-name" property name. 1055 This property provides an exposure point for the person or 1056 organization that authored the content linked to in the "src" 1057 attribute of the entry's atom:content element. 1059 8. IANA Considerations 1061 This document has a number of IANA considerations described in the 1062 following subsections. 1064 8.1. XML Namespaces and Schema URNs 1066 This document uses URNs to describe XML namespaces and XML schemas 1067 conforming to a registry mechanism described in [RFC3688]. 1069 ROLIE XML Namespace The ROLIE namespace (rolie-1.0) has been 1070 registered in the "ns" registry. 1072 URI: urn:ietf:params:xml:ns:rolie-1.0 1074 Registrant Contact: IESG 1075 XML: None. Namespace URIs do not represent an XML specification. 1077 ROLIE XML Schema The ROLIE schema (rolie-1.0) has been registered in 1078 the "schema" registry. 1080 URI: urn:ietf:params:xml:schema:rolie-1.0 1082 Registrant Contact: IESG 1084 XML: See section A of this document. 1086 8.2. ROLIE URN Sub-namespace 1088 IANA has added an entry to the "IETF URN Sub-namespace for Registered 1089 Protocol Parameter Identifiers" registry located at 1090 as per 1091 RFC3553 [RFC3553]. 1093 The entry is as follows: 1095 Registry name: rolie 1097 Specification: This document 1099 Repository: ROLIE URN Parameters. See Section 8.3 [TO BE REMOVED: 1100 This registration should take place at the following location: 1101 https://www.iana.org/assignments/rolie] 1103 Index value: See Section 8.3 1105 8.3. ROLIE URN Parameters 1107 A new top-level registry has been created, entitled "Resource 1108 Oriented Lightweight Information Exchange (ROLIE) Parameters". [TO 1109 BE REMOVED: This registration should take place at the following 1110 location: https://www.iana.org/assignments/rolie] 1112 In this top-level registry, a sub-registry entitled "ROLIE URN 1113 Parameters" has been created. Registration in this repository is via 1114 the Specification Required policy [RFC5226]. Designated Expert 1115 reviews should be routed through the MILE WG mailing list. Failing 1116 this, the Designated Expert will be assigned by the IESG. 1118 Each entry in this sub-registry must record the following fields: 1120 Name: A URN segment that adheres to the pattern {type}:{label}. 1121 The keywords are defined as follows: 1123 {type}: The parameter type. The allowed values are "category" 1124 or "property". "category" denotes a category extension as 1125 discussed in Section 7.1. "property" denotes a property 1126 extension as discussed in Section 7.4. 1128 {label}: A required US-ASCII string that conforms to the URN 1129 syntax requirements (see [RFC2141]). This string must be 1130 unique within the namespace defined by the {type} keyword. The 1131 "local" label for both the "category" and "property" types has 1132 been reserved for private use. 1134 Extension IRI: The identifier to use within ROLIE, which is the 1135 full URN using the form: urn:ietf:params:rolie:{name}, where 1136 {name} is the "name" field of this registration. 1138 Reference: A static link to the specification and section that the 1139 definition of the parameter can be found. 1141 Sub-registry: An optional field that links to an IANA sub-registry 1142 for this parameter. If the {type} is "category", the sub-registry 1143 must contain a "name" field whose registered values MUST be US- 1144 ASCII. The list of names are the allowed values of the "term" 1145 attribute in the atom:category element. (See Section 7.1.2). 1147 This repository has the following initial values: 1149 +------------+-------------------+-------+--------------------------+ 1150 | Name | Extension IRI | Refer | Sub-Registry | 1151 | | | ence | | 1152 +------------+-------------------+-------+--------------------------+ 1153 | category:i | urn:ietf:params:r | This | [TO BE REMOVED: This | 1154 | nformation | olie:category | docum | registration should take | 1155 | -type | :information-type | ent, | place at the following | 1156 | | | Secti | location: https://www.ia | 1157 | | | on | na.org/assignments/rolie | 1158 | | | 8.4 | /category/information- | 1159 | | | | type] | 1160 | property:l | urn:ietf:params:r | This | None | 1161 | ocal | olie:property:loc | docum | | 1162 | | al | ent, | | 1163 | | | Secti | | 1164 | | | on | | 1165 | | | 7.4 | | 1166 | category:l | urn:ietf:params:r | This | None | 1167 | ocal | olie:category:loc | docum | | 1168 | | al | ent, | | 1169 | | | Secti | | 1170 | | | on | | 1171 | | | 7.1 | | 1172 | property | urn:ietf:params:r | This | None | 1173 | :content- | olie:property | docum | | 1174 | author- | :content-author- | ent, | | 1175 | name | name | Secti | | 1176 | | | on | | 1177 | | | 7.4 | | 1178 +------------+-------------------+-------+--------------------------+ 1180 8.4. ROLIE Security Resource Information Type Sub-Registry 1182 A new sub-registry has been created to store ROLIE information type 1183 values. 1185 Name of Registry: "ROLIE Information Types" 1187 Location of Registry: 1188 https://www.iana.org/assignments/rolie/category/information-type 1190 Fields to record in the registry: 1192 name: The full name of the security resource information type 1193 as a string from the printable ASCII character set [RFC0020] 1194 with individual embedded spaces allowed. The ABNF [RFC5234] 1195 syntax for this field is: 1197 1*VCHAR *(SP 1*VCHAR) 1199 index: This is an IANA-assigned positive integer that 1200 identifies the registration. The first entry added to this 1201 registry uses the value 1, and this value is incremented for 1202 each subsequent entry added to the registry. 1204 reference: A list of one or more URIs [RFC3986] from which the 1205 registered specification can be obtained. The registered 1206 specification MUST be readily and publicly available from that 1207 URI. The URI SHOULD be a stable reference. 1209 Allocation Policy: Specification required as per [RFC5226] 1211 8.5. Well-Known URI Registrations 1213 This document makes the follow two registrations to the Well-Known 1214 URI Registry at https://www.iana.org/assignments/well-known-uris/ 1215 well-known-uris.xhtml. 1217 Service Document registration: 1219 URI suffix: rolie/servicedocument 1221 Change controller: IETF 1223 Specification document: This document, Section 5.1.3 1225 Related information: None 1227 Category Document registration: 1229 URI suffix: rolie/categorydocument 1231 Change controller: IETF 1233 Specification document: This document, Section 5.2 1235 Related information: None 1237 9. Security Considerations 1239 This document defines a resource-oriented approach for lightweight 1240 information exchange using HTTP over TLS, the Atom Syndication 1241 Format, and the Atom Publishing Protocol. As such, implementers must 1242 understand the security considerations described in those 1243 specifications. All that follows is guidance, more specific 1244 instruction is out of scope for this document. 1246 All security measures SHOULD be enforced at the source, that is, a 1247 provider SHOULD NOT return any Feed content or member Entry content 1248 for which the client identity has not been specifically 1249 authenticated, authorized, and audited. 1251 The approach described herein is based upon all policy enforcements 1252 being implemented at the point when a resource representation is 1253 created. As such, producers sharing cyber security information using 1254 this specification must take care to authenticate their HTTP clients 1255 using a suitably strong user authentication mechanism. Sharing 1256 communities that are exchanging information on well-known indicators 1257 and incidents for purposes of public education may choose to rely 1258 upon HTTP Authentication or similar. However, sharing communities 1259 that are engaged in sensitive collaborative analysis and/or 1260 operational response for indicators and incidents targeting high 1261 value information systems should adopt a suitably stronger user 1262 authentication solution, such as a risk-based or multi-factor 1263 approach. In general, trust in the sharing consortium will depend 1264 upon the members maintaining adequate user authentication mechanisms. 1266 Collaborating consortiums may benefit from the adoption of a 1267 federated identity solution, such as those based upon SAML-core 1268 [SAML-core], SAML-bind [SAML-bind], and SAML-prof [SAML-prof] for 1269 Web-based authentication and cross-organizational single sign-on. 1270 Dependency on a trusted third party identity provider implies that 1271 appropriate care must be exercised to sufficiently secure the 1272 Identity provider. Any attacks on the federated identity system 1273 would present a risk to the consortium, as a relying party. 1274 Potential mitigations include deployment of a federation-aware 1275 identity provider that is under the control of the information 1276 sharing consortium, with suitably stringent technical and management 1277 controls. 1279 Authorization of resource representations is the responsibility of 1280 the source system, i.e. based on the authenticated user identity 1281 associated with an HTTP(S) request. The required authorization 1282 policies that are to be enforced must therefore be managed by the 1283 security administrators of the source system. Various authorization 1284 architectures would be suitable for this purpose, such as RBAC [3] 1285 and/or ABAC, as embodied in XACML [XACML]. In particular, 1286 implementers adopting XACML may benefit from the capability to 1287 represent their authorization policies in a standardized, 1288 interoperable format. Note that implementers are free to choose any 1289 suitable authorization mechanism that is capable of fulfilling the 1290 policy enforcement requirements relevant to their consortium and/or 1291 organization. 1293 Additional security requirements such as enforcing message-level 1294 security at the destination system could supplement the security 1295 enforcements performed at the source system, however these 1296 destination-provided policy enforcements are out of scope for this 1297 specification. Implementers requiring this capability should 1298 consider leveraging, e.g. the element in the RID schema. 1299 Refer to RFC6545 section 9 for more information. 1301 When security policies relevant to the source system are to be 1302 enforced at both the source and destination systems, implementers 1303 must take care to avoid unintended interactions of the separately 1304 enforced policies. Potential risks will include unintended denial of 1305 service and/or unintended information leakage. These problems may be 1306 mitigated by avoiding any dependence upon enforcements performed at 1307 the destination system. When distributed enforcement is unavoidable, 1308 the usage of a standard language (e.g. XACML) for the expression of 1309 authorization policies will enable the source and destination systems 1310 to better coordinate and align their respective policy expressions. 1312 A service discovery mechanism is not explicitly specified in this 1313 document, and there are several approaches available for 1314 implementers. When selecting this mechanism, implementations need to 1315 ensure that their choice provides a means for authenticating the 1316 server. As described in the discovery section, DNS SRV Records are a 1317 possible secure solution to discovery. 1319 10. Privacy Considerations 1321 The optional author field may provide an identification privacy issue 1322 if populated without the author's consent. This information may 1323 become public if posted to a public feed. Special care should be 1324 taken when aggregating or sharing entries from other feeds, or when 1325 programmatically generating ROLIE entries from some data source that 1326 the author's personal info is not shared without their consent. 1328 When using the Atom Publishing Protocol to POST entries to a feed, 1329 attackers may use correlating techniques to profile the user. The 1330 request time can be compared to the generated "updated" field of the 1331 entry in order to build out information about a given user. This 1332 correlation attempt can be mitigated by not using HTTP requests to 1333 POST entries when profiling is a risk, and rather use backend control 1334 of the feeds. 1336 Adoption of the information sharing approach described in this 1337 document will enable users to more easily perform correlations across 1338 separate, and potentially unrelated, cyber security information 1339 providers. A client may succeed in assembling a data set that would 1340 not have been permitted within the context of the authorization 1341 policies of either provider when considered individually. Thus, 1342 providers may face a risk of an attacker obtaining an access that 1343 constitutes an undetected separation of duties (SOD) violation. It 1344 is important to note that this risk is not unique to this 1345 specification, and a similar potential for abuse exists with any 1346 other cyber security information sharing protocol. However, the wide 1347 availability of tools for HTTP clients and Atom Feed handling implies 1348 that the resources and technical skills required for a successful 1349 exploit may be less than it was previously. This risk can be best 1350 mitigated through appropriate vetting of the client at account 1351 provisioning time. In addition, any increase in the risk of this 1352 type of abuse should be offset by the corresponding increase in 1353 effectiveness that this specification affords to the defenders. 1355 Overall, ROLIE introduces few privacy concerns above and beyond those 1356 present in any other HTTP protocol. Those that exist can be 1357 mitigated by following security considerations and carefully using 1358 the optional identifying elements. 1360 11. Acknowledgements 1362 The authors gratefully acknowledge the valuable contributions of Tom 1363 Maguire, Kathleen Moriarty, and Vijayanand Bharadwaj. These 1364 individuals provided detailed review comments on earlier drafts, and 1365 made many suggestions that have helped to improve this document. 1367 12. References 1369 12.1. Normative References 1371 [RFC0020] Cerf, V., "ASCII format for network interchange", STD 80, 1372 RFC 20, DOI 10.17487/RFC0020, October 1969, 1373 . 1375 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1376 Requirement Levels", BCP 14, RFC 2119, 1377 DOI 10.17487/RFC2119, March 1997, 1378 . 1380 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1381 DOI 10.17487/RFC3688, January 2004, 1382 . 1384 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1385 Resource Identifier (URI): Generic Syntax", STD 66, 1386 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1387 . 1389 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 1390 Syndication Format", RFC 4287, DOI 10.17487/RFC4287, 1391 December 2005, . 1393 [RFC5005] Nottingham, M., "Feed Paging and Archiving", RFC 5005, 1394 DOI 10.17487/RFC5005, September 2007, 1395 . 1397 [RFC5023] Gregorio, J., Ed. and B. de hOra, Ed., "The Atom 1398 Publishing Protocol", RFC 5023, DOI 10.17487/RFC5023, 1399 October 2007, . 1401 [RFC7970] Danyliw, R., "The Incident Object Description Exchange 1402 Format Version 2", RFC 7970, DOI 10.17487/RFC7970, 1403 November 2016, . 1405 [RFC6546] Trammell, B., "Transport of Real-time Inter-network 1406 Defense (RID) Messages over HTTP/TLS", RFC 6546, 1407 DOI 10.17487/RFC6546, April 2012, 1408 . 1410 [RFC3553] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An 1411 IETF URN Sub-namespace for Registered Protocol 1412 Parameters", BCP 73, RFC 3553, DOI 10.17487/RFC3553, June 1413 2003, . 1415 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1416 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1417 DOI 10.17487/RFC5226, May 2008, 1418 . 1420 [W3C.REC-xml-names-20091208] 1421 Bray, T., Hollander, D., Layman, A., Tobin, R., and H. 1422 Thompson, "Namespaces in XML 1.0 (Third Edition)", World 1423 Wide Web Consortium Recommendation REC-xml-names-20091208, 1424 December 2009, 1425 . 1427 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 1428 NETCONF Protocol over Transport Layer Security (TLS) with 1429 Mutual X.509 Authentication", RFC 7589, 1430 DOI 10.17487/RFC7589, June 2015, 1431 . 1433 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1434 Housley, R., and W. Polk, "Internet X.509 Public Key 1435 Infrastructure Certificate and Certificate Revocation List 1436 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 1437 . 1439 [RFC4642] Murchison, K., Vinocur, J., and C. Newman, "Using 1440 Transport Layer Security (TLS) with Network News Transfer 1441 Protocol (NNTP)", RFC 4642, DOI 10.17487/RFC4642, October 1442 2006, . 1444 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 1445 Uniform Resource Identifiers (URIs)", RFC 5785, 1446 DOI 10.17487/RFC5785, April 2010, 1447 . 1449 [relax-NG] 1450 Clark, J., Ed., "RELAX NG Compact Syntax", 11 2002, 1451 . 1454 12.2. Informative References 1456 [RFC2141] Moats, R., "URN Syntax", RFC 2141, DOI 10.17487/RFC2141, 1457 May 1997, . 1459 [RFC2782] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for 1460 specifying the location of services (DNS SRV)", RFC 2782, 1461 DOI 10.17487/RFC2782, February 2000, 1462 . 1464 [RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between 1465 Information Models and Data Models", RFC 3444, 1466 DOI 10.17487/RFC3444, January 2003, 1467 . 1469 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1470 Specifications: ABNF", STD 68, RFC 5234, 1471 DOI 10.17487/RFC5234, January 2008, 1472 . 1474 [SAML-core] 1475 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 1476 "Assertions and Protocol for the OASIS Security Assertion 1477 Markup Language (SAML) V2.0", OASIS Standard saml-core- 1478 2.0-os, March 2005, . 1481 [SAML-prof] 1482 Hughes, J., Cantor, S., Hodges, J., Hirsch, F., Mishra, 1483 P., Philpott, R., and E. Maler, "Profiles for the OASIS 1484 Security Assertion Markup Language (SAML) V2.0", OASIS 1485 Standard OASIS.saml-profiles-2.0-os, March 2005, 1486 . 1489 [SAML-bind] 1490 Cantor, S., Hirsch, F., Kemp, J., Philpott, R., and E. 1491 Maler, "Bindings for the OASIS Security Assertion Markup 1492 Language (SAML) V2.0", OASIS Standard saml-bindings- 1493 2.0-os, March 2005, . 1496 [XACML] Rissanen, E., "eXtensible Access Control Markup Language 1497 (XACML) Version 3.0", August 2010, . 1500 [REST] Fielding, R., "Architectural Styles and the Design of 1501 Network-based Software Architectures", 2000, 1502 . 1505 12.3. URIs 1507 [1] https://www.iana.org/assignments/link-relations/link- 1508 relations.xhtml 1510 [2] https://www.iana.org/assignments/link-relations/link- 1511 relations.xhtml 1513 [3] http://csrc.nist.gov/groups/SNS/rbac/ 1515 Appendix A. Relax NG Compact Schema for ROLIE 1517 This appendix is informative. 1519 The Relax NG schema below defines the rolie:format element. 1521 # -*- rnc -*- 1522 # RELAX NG Compact Syntax Grammar for the rolie ns 1524 namespace rolie = "urn:ietf:params:xml:ns:rolie-1.0" 1525 namespace atom = "http://www.w3.org/2005/Atom" 1526 namespace app = "http://www.w3.org/2007/app" 1528 # rolie:format 1530 rolieFormat = 1531 element rolie:format { 1532 app:appCommonAttributes, 1533 attribute ns { atom:atomURI }, 1534 attribute version { text } ?, 1535 attribute schema-location { atom:atomURI } ?, 1536 attribute schema-type { atom:atomMediaType } ?, 1537 empty 1538 } 1540 # rolie:property 1542 rolieProperty = 1543 element rolie:property { 1544 app:appCommonAttributes, 1545 attribute name { atom:atomURI }, 1546 attribute value { text } 1547 empty 1548 } 1550 Appendix B. Examples of Use 1552 B.1. Service Discovery 1554 This section provides a non-normative example of a client doing 1555 service discovery. 1557 An Atom Service Document enables a client to dynamically discover 1558 what Feeds a particular publisher makes available. Thus, a provider 1559 uses an Atom Service Document to enable authorized clients to 1560 determine what specific information the provider makes available to 1561 the community. While the Service Document is accessible at a pre- 1562 determined location, the Service Document can also be made accessible 1563 from any well known location, such as via a link from the producer's 1564 home page. 1566 A client may format an HTTP GET request to retrieve the service 1567 document from the specified location: 1569 GET /.well-known/rolie/servicedocument 1570 Host: www.example.org 1571 Accept: application/atomsvc+xml 1573 Notice the use of the HTTP Accept: request header, indicating the 1574 MIME type for Atom service discovery. The response to this GET 1575 request will be an XML document that contains information on the 1576 specific Collections that are provided. 1578 Example HTTP GET response: 1580 HTTP/1.1 200 OK 1581 Date: Fri, 24 Aug 2016 17:09:11 GMT 1582 Content-Length: 570 1583 Content-Type: application/atomsvc+xml;charset="utf-8" 1585 1586 1588 1589 Vulnerabilities 1590 1591 Vulnerabilities Feed 1592 1593 1596 1597 1598 1599 1601 This simple Service Document example shows that the server provides 1602 one workspace, named "Vunerabilities". Within that workspace, the 1603 server makes one Collection available. 1605 A server may also offer a number of different Collections, each 1606 containing different types of security automation information. In 1607 the following example, a number of different Collections are 1608 provided, each with its own category and authorization scope. This 1609 categorization will help the clients to decide which Collections will 1610 meet their needs. 1612 HTTP/1.1 200 OK 1613 Date: Fri, 24 Aug 2016 17:10:11 GMT 1614 Content-Length: 1912 1615 Content-Type: application/atomsvc+xml;charset="utf-8" 1617 1618 1620 1621 Public Security Information Sharing 1622 1624 Public Vulnerabilities 1625 1627 1628 1631 1632 1633 1634 1635 Private Consortium Sharing 1636 1638 Incidents 1639 1641 1642 1645 1646 1647 1648 1650 In this example, the provider is making available a total of two 1651 Collections, organized into two different workspaces. The first 1652 workspace contains a Collection consisting of publicly available 1653 software vulnerabilities. The second workspace provides an incident 1654 Collection for use by a private sharing consortium. An appropriately 1655 authenticated and authorized client may then proceed to make HTTP 1656 requests for these Collections. The publicly provided vulnerability 1657 information may be accessible with or without authentication. 1658 However, users accessing the Collection restricted to authorized 1659 members of a private sharing consortium are expected to authenticate 1660 before access is allowed. 1662 B.2. Feed Retrieval 1664 This section provides a non-normative example of a client retrieving 1665 an vulnerability Feed. 1667 Having discovered the available security information sharing 1668 Collections, a client who is a member of the general public may be 1669 interested in receiving the Collection of public vulnerabilities. 1670 The client may retrieve the Feed for this Collection by performing an 1671 HTTP GET operation on the URL indicated by the Collection's "href" 1672 attribute. 1674 Example HTTP GET request for a Feed: 1676 GET /provider/public/vulns 1677 Host: www.example.org 1678 Accept: application/atom+xml 1680 The corresponding HTTP response would be an XML document containing 1681 the vulnerability Feed: 1683 Example HTTP GET response for a Feed: 1685 HTTP/1.1 200 OK 1686 Date: Fri, 24 Aug 2016 17:20:11 GMT 1687 Content-Length: 2882 1688 Content-Type: application/atom+xml;charset="utf-8" 1690 1691 1694 2a7e265a-39bc-43f2-b711-b8fd9264b5c9 1695 1696 Atom formatted representation of 1697 a feed of XML vulnerability documents 1698 1699 1702 2016-05-04T18:13:51.0Z 1703 1705 1707 1708 1709 dd786dba-88e6-440b-9158-b8fae67ef67c 1710 Sample Vulnerability 1711 2015-08-04T18:13:51.0Z 1712 2015-08-05T18:13:51.0Z 1713 A vulnerability issue identified by CVE-... 1714 1716 1718 1719 1720 1722 1724 This Feed document has two Atom Entries, one of which has been 1725 elided. The first Entry illustrates an atom:entry element that 1726 provides a summary of essential details about one particular 1727 vulnerability. Based upon this summary information and the provided 1728 category information, a client may choose to do an HTTP GET request, 1729 on the content "src" attribute, to retrieve the full details of the 1730 vulnerability. 1732 B.3. Entry Retrieval 1734 This section provides a non-normative example of a client retrieving 1735 an vulnerability as an Atom Entry. 1737 Having retrieved the Feed of interest, the client may then decide, 1738 based on the description and/or category information, that one of the 1739 entries in the Feed is of further interest. The client may retrieve 1740 this vulnerability Entry by performing an HTTP GET operation on the 1741 URL indicated by the "src" attribute of the atom:content element. 1743 Example HTTP GET request for an Entry: 1745 GET /provider/public/vulns/123456 1746 Host: www.example.org 1747 Accept: application/atom+xml;type=entry 1749 The corresponding HTTP response would be an XML document containing 1750 the Atom Entry for the vulnerability record: 1752 Example HTTP GET response for an Entry: 1754 HTTP/1.1 200 OK 1755 Date: Fri, 24 Aug 2016 17:30:11 GMT 1756 Content-Length: 713 1757 Content-Type: application/atom+xml;type=entry;charset="utf-8" 1759 1760 1763 f63aafa9-4082-48a3-9ce6-97a2d69d4a9b 1764 Sample Vulnerability 1765 2015-08-04T18:13:51.0Z 1766 2015-08-05T18:13:51.0Z 1767 1770 A vulnerability issue identified by CVE-... 1771 1772 1774 1775 1777 The example response above shows an XML document referenced by the 1778 "src" attribute of the atom:content element. The client may retrieve 1779 the document using this URL. 1781 Appendix C. Change History 1783 Changes in draft-ietf-mile-rolie-07 since draft-ietf-mile-rolie-06 1784 version, March 13, 2017 to TODO, 2017 1786 Added /.well-known/ registration and requirement to service 1787 discovery. 1789 Condensed and re-focused Sections 1 and 4 to be more concise. 1791 Added privacy considerations section. 1793 Made a number of editorial changes as per WGLC review. 1795 Changes in draft-ietf-mile-rolie-06 since draft-ietf-mile-rolie-05 1796 version, November 2, 2016 to March 13, 2017 1798 Changed to standards track 1800 Added the rolie:property element 1802 Fixed references (Normative vs Informative) 1804 Set Service and Category document URL template requirements 1806 Fixed XML snippets in examples 1808 Changes in draft-ietf-mile-rolie-05 since draft-ietf-mile-rolie-04 1809 version, October 21, 2016 to November 2, 2016 1811 Added ROLIE specific terminology to section 2 1813 Added AtomPub Category Document in section 5.2 1815 Edited document, improving consistency in terminology usage and 1816 capitalization of key terms, as well as enhancing clarity. 1818 Removed unused format parameter type in section 8.3 1820 Schema removed, the normative schema consists of the snippets in 1821 the requirements sections. 1823 Changes in draft-ietf-mile-rolie-04 since draft-ietf-mile-rolie-03 1824 version, July 8, 2016 to October 31, 2016 1826 o Further specification and clarification of requirements 1827 o IANA Considerations and extension system fleshed out and 1828 described. 1830 o Examples and References updated. 1832 o Schema created. 1834 o Fixed both internal section and external document referencing. 1836 o Removed XACML Guidance Appendix. This will be added to a future 1837 draft on ROLIE Authentication and Access Control. 1839 Changes made in draft-ietf-mile-rolie-03 since draft-ietf-mile- 1840 rolie-02 version, May 27, 2016 to July 8, 2015 1842 o Atom Syndication and Atom Pub requirements split and greatly 1843 expanded for increased justification and technical specification. 1845 o Reintroduction and reformatting of some use case examples in order 1846 to provide some guidance on use. 1848 o Established rough version of IANA table extension system along 1849 with explanations of said system. 1851 o Re-organized document to put non-vital information in appendices. 1853 Changes made in draft-ietf-mile-rolie-02 since draft-field-mile- 1854 rolie-01 version, December, 2015 to May 27, 2016: 1856 o All CSIRT and IODEF/RID material moved to companion CSIRT document 1858 o Recast document into a more general use perspective. The 1859 implication of CSIRTs as the defacto end-user has been removed 1860 where ever possible. All of the original CSIRT based use cases 1861 remain completely supported by this document, it has been opened 1862 up to support many other use cases. 1864 o Changed the content model to broaden support of representation 1866 o Edited and rewrote much of sections 1,2 and 3 in order to 1867 accomplish a broader scope and greater readability 1869 o Removed any requirements from the Background section and, if not 1870 already stated, placed them in the requirements section 1872 o Re-formatted the requirements section to make it clearer that it 1873 contains the lions-share of the requirements of the specification 1875 Changes made in draft-ietf-mile-rolie-01 since draft-field-mile- 1876 rolie-02 version, August 15, 2013 to December 2, 2015: 1878 o Added section specifying the use of RFC5005 for Archive and Paging 1879 of Feeds. 1881 o Added section describing use of atom categories that correspond to 1882 IODEF expectation class and impact classes. See: normative- 1883 expectation-impact 1885 o Dropped references to adoption of a MILE-specific HTTP media type 1886 parameter. 1888 o Updated IANA Considerations section to clarify that no IANA 1889 actions are required. 1891 Authors' Addresses 1893 John P. Field 1894 Pivotal Software, Inc. 1895 625 Avenue of the Americas 1896 New York, New York 1897 USA 1899 Phone: (646)792-5770 1900 Email: jfield@pivotal.io 1902 Stephen A. Banghart 1903 National Institute of Standards and Technology 1904 100 Bureau Drive 1905 Gaithersburg, Maryland 1906 USA 1908 Phone: (301)975-4288 1909 Email: sab3@nist.gov 1911 David Waltermire 1912 National Institute of Standards and Technology 1913 100 Bureau Drive 1914 Gaithersburg, Maryland 20877 1915 USA 1917 Email: david.waltermire@nist.gov