Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 8322

Resource-Oriented Lightweight Information Exchange (ROLIE)

Pages: 43
Proposed Standard
Part 2 of 2 – Pages 21 to 43
First   Prev   None

Top   ToC   RFC8322 - Page 21   prevText

7. Available Extension Points Provided by ROLIE

This specification does not require particular information types or data formats; rather, ROLIE is intended to be extended by additional specifications that define the use of new categories and link relations. The primary point of extension is through the definition of new information type category terms. Additional specifications can register new information type category terms with IANA that serve as the main characterizing feature of a ROLIE Collection/Feed or resource/Entry. These additional specifications defining new information type terms can describe additional requirements for including specific categories and link relations, as well as the use of specific data formats supporting a given information type term.

7.1. The Category Extension Point

The "atom:category" element, defined in Section 4.2.2 of [RFC4287], provides a mechanism to provide additional categorization information for a content resource in ROLIE. The ability to define new categories is one of the core extension points provided by Atom. A Category Document, defined in Section 7 of [RFC5023], provides a mechanism for an Atom implementation to make discoverable the "atom:category" terms and associated allowed values. ROLIE further defines the use of the existing Atom extension category mechanism by allowing ROLIE-specific category extensions to be registered with IANA. The "urn:ietf:params:rolie:category:information-type" category scheme, which has special meaning for implementations of ROLIE, has been assigned (see Section 8.3). This allows category scheme namespaces to be managed in a more consistent way, allowing for greater interoperability between content producers and consumers. Any "atom:category" element whose "scheme" attribute uses an unregistered scheme MUST be considered "Private Use" as defined in [RFC8126]. Implementations encountering such a category MUST parse the content without error but MAY otherwise ignore the element. The use of the "atom:category" element is discussed in the following subsections.
Top   ToC   RFC8322 - Page 22

7.1.1. General Use of the "atom:category" Element

The "atom:category" element can be used for characterizing a ROLIE resource. An "atom:category" element has a "term" attribute that indicates the assigned category value and a "scheme" attribute that provides an identifier for the category type. The "scheme" provides a means to describe how a set of category terms should be used and provides a namespace that can be used to differentiate terms that are provided by multiple organizations and that have different semantic meaning. To further differentiate category types used in ROLIE, an IANA subregistry has been established for ROLIE protocol parameters to support the registration of new category "scheme" attribute values by ROLIE extension specifications. The use of this extension point is discussed in Section 8.3, using the "name" field with a type parameter of "category" to indicate a category extension.

7.1.2. Identification of Security Automation Information Types

A ROLIE-specific extension point is provided through the "atom:category" element's "scheme" attribute value "urn:ietf:params:rolie:category:information-type". This value is a Uniform Resource Name (URN) [RFC8141] that is registered with IANA as described in Section 8.3. When used as the "scheme" attribute in this way, the "term" attribute is expected to be a registered value as defined in Section 8.4. Through this mechanism, a given security automation information type can be used to: 1. identify that an "app:collection" element in a Service Document points to an Atom Feed that contains Entries pertaining to a specific type of security automation information (see Section 5.1.2), 2. identify that an "atom:feed" element in an Atom Feed contains Entries pertaining to a specific type of security automation information (see Section 6.1.1), or 3. identify the information type of a standalone resource (see Section 6.2.5).
Top   ToC   RFC8322 - Page 23
   For example, the notional security automation information type
   "incident" would be identified as follows:

      <atom:category
          scheme="urn:ietf:params:rolie:category:information-type"
          term="incident"/>

   A security automation information type represents a class of
   information that represents the same or similar information model
   [RFC3444].  Note that this document does not register any information
   types but offers the following as examples of potential information
   types:

   indicator:  Computing device- or network-related "observable features
      and phenomenon that aid in the forensic or proactive detection of
      malicious activity and associated metadata" (from [RFC7970]).

   incident:  Information pertaining to or derived from security
      incidents.

   vulnerability reports:  Information identifying and describing a
      vulnerability in hardware or software.

   configuration checklists:  Content that can be used to assess the
      configuration settings related to installed software.

   software tags:  Metadata used to identify and characterize
      installable software.

   This is a short list to inspire new engineering of information type
   extensions that support the automation of security processes.

   This document does not specify any information types.  Instead,
   information types in ROLIE are expected to be registered in extension
   documents that describe one or more new information types.  This
   allows the information types used by ROLIE implementations to grow
   over time to support new security automation use cases.  These
   extension documents may also enhance ROLIE Service, Category, Feed,
   and Entry Documents by defining link relations, other categories, and
   Format data model extensions to address the representational needs of
   these specific information types.  New information types are added to
   ROLIE through registrations to the IANA "ROLIE Information Types"
   registry defined in Section 8.4.
Top   ToC   RFC8322 - Page 24

7.2. The "rolie:format" Extension Point

Security automation data pertaining to a given information type may be expressed using a number of supported formats. As described in Section 6.2.3, the "rolie:format" element is used to describe the specific data model used to represent the resource referenced by a given "atom:entry". The structure provided by the "rolie:format" element provides a mechanism for extension within the "atom:entry" model. ROLIE extensions MAY further restrict which data models are allowed to be used for a given information type. By declaring the data model used for a given resource, a consumer can choose to download or ignore the resource, or look for alternate formats. This saves the consumer from downloading and parsing resources that the consumer is not interested in or resources expressed in formats that are not supported by the consumer.

7.3. The Link Relation Extension Point

This document uses several link relations defined in the IANA "Link Relation Types" registry at <https://www.iana.org/assignments/link-relations/>. Additional link relations can be registered in this registry to allow new relationships to be represented in ROLIE according to Section 4.2.7.2 of [RFC4287]. Based on the preceding reference, if the link relation is too specific or limited in its intended use, an absolute URI can be used in lieu of registering a new simple name with IANA.

7.4. The "rolie:property" Extension Point

As discussed previously in Section 6.2.3, many formats contain unique identifying and characterizing properties that are vital for sharing information. In order to provide a global reference for these properties, this document establishes an IANA registry that allows ROLIE extensions to register named properties using the "name" field with a type parameter of "property" to indicate a property extension; see Section 8.3. Implementations SHOULD prefer the use of registered properties over implementation-specific properties when possible. ROLIE extensions are expected to register new properties and use existing properties to provide valuable identifying and characterizing information for a given information type and/or format.
Top   ToC   RFC8322 - Page 25
   Any "rolie:property" element whose "name" attribute has
   "urn:ietf:params:rolie:property:local" as a prefix MUST be considered
   "Private Use" as defined in [RFC8126].  Implementations encountering
   such a property MUST parse the content without error but MAY
   otherwise ignore the element.

   This document also registers a number of general-use properties that
   can be used to expose content information in any ROLIE use case.  The
   following are descriptions of how to use these registered properties:

   urn:ietf:params:rolie:property:content-author-name
      The "value" attribute of this property is a text representation
      indicating the individual or organization that authored the
      content referenced by the "src" attribute of the Entry's
      "atom:content" element.  This author may differ from the
      "atom:author" element when the author of the content and the
      author of the Entry are different people or entities.

   urn:ietf:params:rolie:property:content-id
      The "value" attribute of this property is a text representation of
      an identifier pertaining to or extracted from the content
      referenced by the "src" attribute of the Entry's "atom:content"
      element.  For example, if the "atom:entry"'s "atom:content"
      element links to an IODEF document, the "content-id" value would
      be an identifier of that IODEF document.

   urn:ietf:params:rolie:property:content-published-date
      The "value" attribute of this property is a text representation
      indicating the original publication date of the content referenced
      by the "src" attribute of the Entry's "atom:content" element.
      This date may differ from the published date of the ROLIE Entry
      because publication of the content and publication of the ROLIE
      Entry represent different events.  The date MUST be formatted as
      specified in [RFC3339].

   urn:ietf:params:rolie:property:content-updated-date
      The "value" attribute of this property is a text representation
      indicating the date that the content, referenced by the "src"
      attribute of the Entry's "atom:content" element, was last updated.
      This date may differ from the updated date of the ROLIE Entry
      because updates made to the content and to the ROLIE Entry are
      different events.  The date MUST be formatted as specified in
      [RFC3339].
Top   ToC   RFC8322 - Page 26

8. IANA Considerations

This document has a number of IANA considerations, as described in the following subsections.

8.1. XML Namespaces and Schema URNs

This document uses URNs to describe XML namespaces and XML schemas conforming to the registry mechanism described in [RFC3688]. ROLIE XML Namespace: The ROLIE namespace (rolie-1.0) has been registered in the "ns" registry. URI: urn:ietf:params:xml:ns:rolie-1.0 Registrant Contact: IESG XML: None. Namespace URIs do not represent an XML specification. ROLIE XML Schema: The ROLIE schema (rolie-1.0) has been registered in the "schema" registry. URI: urn:ietf:params:xml:schema:rolie-1.0 Registrant Contact: IESG XML: See Appendix A of this document.

8.2. ROLIE URN Sub-namespace

IANA has added an entry to the "IETF URN Sub-namespace for Registered Protocol Parameter Identifiers" registry located at <https://www.iana.org/assignments/params/> as per [RFC3553]. The entry is as follows: Registered Parameter Identifier: rolie Specification: This document Repository: ROLIE URN Parameters. See Section 8.3. Index value: See Section 8.4.
Top   ToC   RFC8322 - Page 27

8.3. ROLIE URN Parameters

A new top-level registry has been created, titled "Resource-Oriented Lightweight Information Exchange (ROLIE) URN Parameters". Registration in the "ROLIE URN Parameters" subregistry is via the Specification Required policy [RFC8126]. Registration requests must be sent to both the MILE Working Group mailing list (mile@ietf.org) and IANA. IANA will forward registration requests to the Designated Expert. Each entry in this subregistry must record the following fields: Name: A URN segment that adheres to the pattern {type}:{label}. The keywords are defined as follows: {type}: The parameter type. The allowed values are "category" or "property". "category" denotes a category extension as discussed in Section 7.1. "property" denotes a property extension as discussed in Section 7.4. {label}: A required US-ASCII string that conforms to the URN syntax requirements (see [RFC8141]). This string must be unique within the namespace defined by the {type} keyword. The "local" label for both the "category" and "property" types has been reserved for private use. Extension URI: The identifier to use within ROLIE, which is the full URN using the form "urn:ietf:params:rolie:{name}", where {name} is the "name" field of this registration. Reference: A static link to the specification and section where the definition of the parameter can be found. Subregistry: An optional field that links to an IANA subregistry for this parameter. If the {type} is "category", the subregistry must contain a "name" field whose registered values MUST be US-ASCII. The list of names are the allowed values of the "term" attribute in the "atom:category" element (see Section 7.1.2).
Top   ToC   RFC8322 - Page 28
   This repository has the following initial values:

   +--------------+------------------------+-------------+-------------+
   | Name         | Extension URI          | Reference   | Subregistry |
   |              |                        | (This       |             |
   |              |                        | Document)   |             |
   +--------------+------------------------+-------------+-------------+
   | category:    | urn:ietf:params:rolie: | Section 8.4 | See         |
   | information- | category:              |             | Section 8.4 |
   | type         | information-type       |             |             |
   |              |                        |             |             |
   |              |                        |             |             |
   |              |                        |             |             |
   | property:    | urn:ietf:params:rolie: | Section 7.4 | None        |
   | content-     | property:content-      |             |             |
   | author-name  | author-name            |             |             |
   |              |                        |             |             |
   | property:    | urn:ietf:params:rolie: | Section 7.4 | None        |
   | content-id   | property:content-id    |             |             |
   |              |                        |             |             |
   | property:    | urn:ietf:params:rolie: | Section 7.4 | None        |
   | content-     | property:content-      |             |             |
   | published-   | published-date         |             |             |
   | date         |                        |             |             |
   |              |                        |             |             |
   | property:    | urn:ietf:params:rolie: | Section 7.4 | None        |
   | content-     | property:content-      |             |             |
   | updated-date | updated-date           |             |             |
   +--------------+------------------------+-------------+-------------+
Top   ToC   RFC8322 - Page 29

8.4. ROLIE Information Types Registry

A new subregistry has been created to store ROLIE information type values. Name of Registry: "ROLIE Information Types" Location of Registry: <https://www.iana.org/assignments/rolie/> Fields to record in the registry: Name: The full name of the security resource information type as a string from the printable ASCII character set [RFC20] with individual embedded spaces allowed. This value must be unique in the context of this table. The ABNF [RFC5234] syntax for this field is: 1*VCHAR *(SP 1*VCHAR) Index: An IANA-assigned positive integer that identifies the registration. The first entry added to this registry uses the value 1, and this value is incremented for each subsequent entry added to the registry. Reference: A list of one or more URIs [RFC3986] from which the registered specification can be obtained. The registered specification MUST be readily and publicly available from that URI. The URI SHOULD be a stable reference. Allocation Policy: Specification Required, as per [RFC8126]

9. Security Considerations

This document defines a resource-oriented approach for lightweight information exchange using HTTP over TLS, the Atom Syndication Format, and AtomPub. As such, implementers must understand the security considerations described in those specifications. All that follows is guidance; instructions that are more specific are out of scope for this document. To protect the confidentiality of a given resource provided by a ROLIE implementation, requests for retrieval of the resource need to be authenticated to prevent unauthorized users from accessing the resource (see Section 5.4). It can also be useful to log and audit access to sensitive resources to verify that proper access controls remain in place over time.
Top   ToC   RFC8322 - Page 30
   Access control to information published using ROLIE should use
   mechanisms that are appropriate to the sensitivity of the
   information.  Primitive authentication mechanisms like HTTP Basic
   Authentication [RFC7617] are rarely appropriate for sensitive
   information.  A number of authentication schemes are defined in the
   "HTTP Authentication Schemes" registry at
   <https://www.iana.org/assignments/http-authschemes/>.  Of these, HTTP
   Origin-Bound Authentication (HOBA) [RFC7486] and SCRAM-SHA-256
   [RFC7804] ("SCRAM" stands for "Salted Challenge Response
   Authentication Mechanism") provide improved security properties over
   HTTP Basic [RFC7617]and Digest [RFC7616] authentication schemes.
   However, sharing communities that are engaged in sensitive
   collaborative analysis and/or operational response for indicators and
   incidents targeting high-value information systems should adopt a
   suitably stronger user authentication solution, such as a risk-based
   or multi-factor approach.

   Collaborating consortiums may benefit from the adoption of a
   federated identity solution, such as those based upon OAuth [RFC6749]
   with the JSON Web Token (JWT) [RFC7797], or SAML-core [SAML-core]
   ("SAML" stands for "Security Assertion Markup Language"), SAML-bind
   [SAML-bind], and SAML-prof [SAML-prof] for web-based authentication
   and cross-organizational single sign-on.  Dependency on a trusted
   third-party identity provider implies that appropriate care must be
   exercised to sufficiently secure the identity provider.  Any attacks
   on the federated identity system would present a risk to the
   consortium, as a relying party.  Potential mitigations include
   deployment of a federation-aware identity provider that is under the
   control of the information-sharing consortium, with suitably
   stringent technical and management controls.

   Authorization of resource representations is the responsibility of
   the source system, i.e., based on the authenticated user identity
   associated with an HTTP(S) request.  The required authorization
   policies that are to be enforced must therefore be managed by the
   security administrators of the source system.  Various authorization
   architectures would be suitable for this purpose, such as Role-Based
   Access Control (RBAC) <https://csrc.nist.gov/projects/
   role-based-access-control> and/or Attribute-Based Access Control
   (ABAC), as embodied in the eXtensible Access Control Markup Language
   (XACML) [XACML].  In particular, implementers adopting XACML may
   benefit from the capability to represent their authorization policies
   in a standardized, interoperable format.  Note that implementers are
   free to choose any suitable authorization mechanism that is capable
   of fulfilling the policy enforcement requirements relevant to their
   consortium and/or organization.
Top   ToC   RFC8322 - Page 31
   Additional security requirements such as enforcing message-level
   security at the destination system could supplement the security
   enforcements performed at the source system; however, these
   destination-provided policy enforcements are out of scope for this
   specification.  Implementers requiring this capability should
   consider leveraging, for example, the <RIDPolicy> element in the RID
   schema.  Refer to Section 9 of [RFC6545] for more information.
   Additionally, the underlying serialization approach used in the
   representation (e.g., XML, JSON) can offer encryption and message
   authentication capabilities.  For example, XML Digital Signatures
   (XMLDSIG) [RFC3275] for XML, as well as JSON Web Encryption [RFC7516]
   and JSON Web Signature [RFC7515] for JSON, can provide such
   mechanisms.

   When security policies relevant to the source system are to be
   enforced at both the source and destination systems, implementers
   must take care to avoid unintended interactions of the separately
   enforced policies.  Potential risks will include unintended denial of
   service and/or unintended information leakage.  These problems may be
   mitigated by avoiding any dependence upon enforcements performed at
   the destination system.  When distributed enforcement is unavoidable,
   the usage of a standard language (e.g., XACML) for the expression of
   authorization policies will enable the source and destination systems
   to better coordinate and align their respective policy expressions.

   A service discovery mechanism is not explicitly specified in this
   document, but there are several approaches available for
   implementers.  When selecting this mechanism, implementations need to
   ensure that their choice provides a means for authenticating the
   server.  DNS SRV records [RFC2782] are a possible solution to the
   discovery problem described in Section 5.1.3.

10. Privacy Considerations

The optional "author" field may provide an identification privacy issue if populated without the author's consent. This information may become public if posted to a public Feed. When aggregating or sharing Entries from other Feeds or when programmatically generating ROLIE Entries from some data source, special care should be taken to ensure that the author's personal information is not shared without the author's consent. When using AtomPub to POST Entries to a Feed, attackers may use correlating techniques to profile the user. The request time can be compared to the generated "updated" field of the Entry in order to build out information about a given user. This correlation attempt can be mitigated by not using HTTP requests to POST Entries when profiling is a risk and instead using backend control of the Feeds.
Top   ToC   RFC8322 - Page 32
   Adoption of the information-sharing approach described in this
   document will enable users to more easily perform correlations across
   separate, and potentially unrelated, cybersecurity information
   providers.  A client may succeed in assembling a data set that would
   not have been permitted within the context of the authorization
   policies of either provider when considered individually.  Thus,
   providers may face a risk of an attacker obtaining an access that
   constitutes an undetected separation of duties (SOD) violation.  It
   is important to note that this risk is not unique to this
   specification, and a similar potential for abuse exists with any
   other cybersecurity information-sharing protocol.  However, the wide
   availability of tools for HTTP clients and Atom Feed handling implies
   that the resources and technical skills required for a successful
   exploit may be less than it was previously.  This risk can be best
   mitigated through appropriate vetting of the client at the time of
   account provisioning.  In addition, any increase in the risk of this
   type of abuse should be offset by the corresponding increase in
   effectiveness that this specification affords to the defenders.

   Overall, privacy concerns in ROLIE can be mitigated by following
   security considerations and by the careful use of the optional
   personally identifying elements (e.g., author) provided by Atom
   Syndication and ROLIE.

11. References

11.1. Normative References

[RELAX-NG] Clark, J., Ed., "RELAX NG Compact Syntax", November 2002, <https://www.oasis-open.org/committees/relax-ng/ compact-20021121.html>. [RFC20] Cerf, V., "ASCII format for network interchange", STD 80, RFC 20, DOI 10.17487/RFC0020, October 1969, <https://www.rfc-editor.org/info/rfc20>. [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996, <https://www.rfc-editor.org/info/rfc2045>. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>.
Top   ToC   RFC8322 - Page 33
   [RFC3339]  Klyne, G. and C. Newman, "Date and Time on the Internet:
              Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
              <https://www.rfc-editor.org/info/rfc3339>.

   [RFC3553]  Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An
              IETF URN Sub-namespace for Registered Protocol
              Parameters", BCP 73, RFC 3553, DOI 10.17487/RFC3553,
              June 2003, <https://www.rfc-editor.org/info/rfc3553>.

   [RFC3688]  Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
              DOI 10.17487/RFC3688, January 2004,
              <https://www.rfc-editor.org/info/rfc3688>.

   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax", STD 66,
              RFC 3986, DOI 10.17487/RFC3986, January 2005,
              <https://www.rfc-editor.org/info/rfc3986>.

   [RFC4287]  Nottingham, M., Ed., and R. Sayre, Ed., "The Atom
              Syndication Format", RFC 4287, DOI 10.17487/RFC4287,
              December 2005, <https://www.rfc-editor.org/info/rfc4287>.

   [RFC5005]  Nottingham, M., "Feed Paging and Archiving", RFC 5005,
              DOI 10.17487/RFC5005, September 2007,
              <https://www.rfc-editor.org/info/rfc5005>.

   [RFC5023]  Gregorio, J., Ed., and B. de hOra, Ed., "The Atom
              Publishing Protocol", RFC 5023, DOI 10.17487/RFC5023,
              October 2007, <https://www.rfc-editor.org/info/rfc5023>.

   [RFC5234]  Crocker, D., Ed., and P. Overell, "Augmented BNF for
              Syntax Specifications: ABNF", STD 68, RFC 5234,
              DOI 10.17487/RFC5234, January 2008,
              <https://www.rfc-editor.org/info/rfc5234>.

   [RFC6546]  Trammell, B., "Transport of Real-time Inter-network
              Defense (RID) Messages over HTTP/TLS", RFC 6546,
              DOI 10.17487/RFC6546, April 2012,
              <https://www.rfc-editor.org/info/rfc6546>.

   [RFC7525]  Sheffer, Y., Holz, R., and P. Saint-Andre,
              "Recommendations for Secure Use of Transport Layer
              Security (TLS) and Datagram Transport Layer Security
              (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525,
              May 2015, <https://www.rfc-editor.org/info/rfc7525>.
Top   ToC   RFC8322 - Page 34
   [RFC7970]  Danyliw, R., "The Incident Object Description Exchange
              Format Version 2", RFC 7970, DOI 10.17487/RFC7970,
              November 2016, <https://www.rfc-editor.org/info/rfc7970>.

   [RFC8126]  Cotton, M., Leiba, B., and T. Narten, "Guidelines for
              Writing an IANA Considerations Section in RFCs", BCP 26,
              RFC 8126, DOI 10.17487/RFC8126, June 2017,
              <https://www.rfc-editor.org/info/rfc8126>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in
              RFC 2119 Key Words", BCP 14, RFC 8174,
              DOI 10.17487/RFC8174, May 2017,
              <https://www.rfc-editor.org/info/rfc8174>.

   [W3C.REC-xml-names-20091208]
              Bray, T., Hollander, D., Layman, A., Tobin, R., and H.
              Thompson, "Namespaces in XML 1.0 (Third Edition)", World
              Wide Web Consortium Recommendation REC-xml-names-20091208,
              December 2009, <https://www.w3.org/TR/2009/
              REC-xml-names-20091208>.

11.2. Informative References

[Err3267] RFC Errata, Erratum ID 3267, RFC 6546, <https://www.rfc-editor.org/errata/eid3267>. [REST] Fielding, R., "Architectural Styles and the Design of Network-based Software Architectures", 2000, <http://www.ics.uci.edu/~fielding/pubs/ dissertation/top.htm>. [RFC2782] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for specifying the location of services (DNS SRV)", RFC 2782, DOI 10.17487/RFC2782, February 2000, <https://www.rfc-editor.org/info/rfc2782>. [RFC3275] Eastlake 3rd, D., Reagle, J., and D. Solo, "(Extensible Markup Language) XML-Signature Syntax and Processing", RFC 3275, DOI 10.17487/RFC3275, March 2002, <https://www.rfc-editor.org/info/rfc3275>. [RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between Information Models and Data Models", RFC 3444, DOI 10.17487/RFC3444, January 2003, <https://www.rfc-editor.org/info/rfc3444>.
Top   ToC   RFC8322 - Page 35
   [RFC6545]  Moriarty, K., "Real-time Inter-network Defense (RID)",
              RFC 6545, DOI 10.17487/RFC6545, April 2012,
              <https://www.rfc-editor.org/info/rfc6545>.

   [RFC6749]  Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
              RFC 6749, DOI 10.17487/RFC6749, October 2012,
              <https://www.rfc-editor.org/info/rfc6749>.

   [RFC7486]  Farrell, S., Hoffman, P., and M. Thomas, "HTTP
              Origin-Bound Authentication (HOBA)", RFC 7486,
              DOI 10.17487/RFC7486, March 2015,
              <https://www.rfc-editor.org/info/rfc7486>.

   [RFC7515]  Jones, M., Bradley, J., and N. Sakimura, "JSON Web
              Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515,
              May 2015, <https://www.rfc-editor.org/info/rfc7515>.

   [RFC7516]  Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
              RFC 7516, DOI 10.17487/RFC7516, May 2015,
              <https://www.rfc-editor.org/info/rfc7516>.

   [RFC7616]  Shekh-Yusef, R., Ed., Ahrens, D., and S. Bremer, "HTTP
              Digest Access Authentication", RFC 7616,
              DOI 10.17487/RFC7616, September 2015,
              <https://www.rfc-editor.org/info/rfc7616>.

   [RFC7617]  Reschke, J., "The 'Basic' HTTP Authentication Scheme",
              RFC 7617, DOI 10.17487/RFC7617, September 2015,
              <https://www.rfc-editor.org/info/rfc7617>.

   [RFC7797]  Jones, M., "JSON Web Signature (JWS) Unencoded Payload
              Option", RFC 7797, DOI 10.17487/RFC7797, February 2016,
              <https://www.rfc-editor.org/info/rfc7797>.

   [RFC7804]  Melnikov, A., "Salted Challenge Response HTTP
              Authentication Mechanism", RFC 7804, DOI 10.17487/RFC7804,
              March 2016, <https://www.rfc-editor.org/info/rfc7804>.

   [RFC8141]  Saint-Andre, P. and J. Klensin, "Uniform Resource Names
              (URNs)", RFC 8141, DOI 10.17487/RFC8141, April 2017,
              <https://www.rfc-editor.org/info/rfc8141>.

   [SAML-bind]
              Cantor, S., Hirsch, F., Kemp, J., Philpott, R., and E.
              Maler, "Bindings for the OASIS Security Assertion Markup
              Language (SAML) V2.0", OASIS Standard saml-bindings-
              2.0-os, March 2005, <http://docs.oasis-open.org/
              security/saml/v2.0/saml-bindings-2.0-os.pdf>.
Top   ToC   RFC8322 - Page 36
   [SAML-core]
              Cantor, S., Kemp, J., Philpott, R., and E. Maler,
              "Assertions and Protocols for the OASIS Security Assertion
              Markup Language (SAML) V2.0", OASIS Standard saml-core-
              2.0-os, March 2005, <http://docs.oasis-open.org/
              security/saml/v2.0/saml-core-2.0-os.pdf>.

   [SAML-prof]
              Hughes, J., Cantor, S., Hodges, J., Hirsch, F., Mishra,
              P., Philpott, R., and E. Maler, "Profiles for the OASIS
              Security Assertion Markup Language (SAML) V2.0", OASIS
              Standard saml-profiles-2.0-os, March 2005,
              <http://docs.oasis-open.org/security/saml/v2.0/
              saml-profiles-2.0-os.pdf>.

   [TLS-1.3]  Rescorla, E., "The Transport Layer Security (TLS) Protocol
              Version 1.3", Work in Progress, draft-ietf-tls-tls13-23,
              January 2018.

   [XACML]    Rissanen, E., "eXtensible Access Control Markup Language
              (XACML) Version 3.0 Plus Errata 01", July 2017,
              <http://docs.oasis-open.org/xacml/3.0/
              xacml-3.0-core-spec-en.pdf>.
Top   ToC   RFC8322 - Page 37

Appendix A. RELAX NG Compact Schema for ROLIE

This appendix is informative. The RELAX NG schema below defines the "rolie:format" element. # -*- rnc -*- # RELAX NG Compact Syntax Grammar for the rolie ns namespace rolie = "urn:ietf:params:xml:ns:rolie-1.0" # import the ATOM Syndication RELAX NG Compact Syntax Grammar include "atomsynd.rnc" # rolie:format rolieFormat = element rolie:format { atomCommonAttributes, attribute ns { atomUri }, attribute version { text } ?, attribute schema-location { atomUri } ?, attribute schema-type { atomMediaType } ?, empty } # rolie:property rolieProperty = element rolie:property { atomCommonAttributes, attribute name { atomUri }, attribute value { text }, empty }

Appendix B. Examples of Use

B.1. Service Discovery

This appendix provides a non-normative example of a client doing service discovery. An Atom Service Document enables a client to dynamically discover what Feeds a particular publisher makes available. Thus, a provider uses an Atom Service Document to enable authorized clients to determine what specific information the provider makes available to
Top   ToC   RFC8322 - Page 38
   the community.  The Service Document should be made accessible from
   an easily found location, such as a link from the producer's
   home page.

   A client may format an HTTP GET request to retrieve the Service
   Document from the specified location:

     GET /rolie/servicedocument
     Host: www.example.org
     Accept: application/atomsvc+xml

   Notice the use of the HTTP Accept: request header, indicating the
   MIME type for Atom service discovery.  The response to this GET
   request will be an XML document that contains information on the
   specific Collections that are provided.

   Example HTTP GET response:

    HTTP/1.1 200 OK
    Date: Fri, 24 Aug 2016 17:09:11 GMT
    Content-Length: 570
    Content-Type: application/atomsvc+xml;charset="utf-8"

    <?xml version="1.0" encoding="UTF-8"?>
    <service xmlns="https://www.w3.org/2007/app"
        xmlns:atom="https://www.w3.org/2005/Atom">
      <workspace>
        <atom:title type="text">Vulnerabilities</atom:title>
        <collection href="https://example.org/provider/vulns">
          <atom:title type="text">Vulnerabilities Feed</atom:title>
          <categories fixed="yes">
            <atom:category
                scheme="urn:ietf:params:rolie:category:information-type"
                term="vulnerability"/>
          </categories>
        </collection>
      </workspace>
    </service>

   This simple Service Document example shows that the server provides
   one workspace, named "Vulnerabilities".  Within that workspace, the
   server makes one Collection available.
Top   ToC   RFC8322 - Page 39
   A server may also offer a number of different Collections, each
   containing different types of security automation information.  In
   the following example, a number of different Collections are
   provided, each with its own category and authorization scope.  This
   categorization will help the clients to decide which Collections will
   meet their needs.

    HTTP/1.1 200 OK
    Date: Fri, 24 Aug 2016 17:10:11 GMT
    Content-Length: 1912
    Content-Type: application/atomsvc+xml;charset="utf-8"

    <?xml version="1.0" encoding='utf-8'?>
    <service xmlns="https://www.w3.org/2007/app"
        xmlns:atom="https://www.w3.org/2005/Atom">
      <workspace>
        <atom:title>Public Security Information Sharing</atom:title>
        <collection
            href="https://example.org/provider/public/vulns">
          <atom:title>Public Vulnerabilities</atom:title>
          <atom:link rel="service"
            href="https://example.org/rolie/servicedocument"/>
          <categories fixed="yes">
            <atom:category
                scheme="urn:ietf:params:rolie:category:information-type"
                term="vulnerability"/>
          </categories>
        </collection>
      </workspace>
      <workspace>
        <atom:title>Private Consortium Sharing</atom:title>
        <collection
            href="https://example.org/provider/private/incidents">
          <atom:title>Incidents</atom:title>
          <atom:link rel="service"
            href="https://example.org/rolie/servicedocument"/>
          <categories fixed="yes">
            <atom:category
                scheme="urn:ietf:params:rolie:category:information-type"
                term="incident"/>
          </categories>
        </collection>
      </workspace>
    </service>
Top   ToC   RFC8322 - Page 40
   In this example, the provider is making available a total of two
   Collections, organized into two different workspaces.  The first
   workspace contains a Collection consisting of publicly available
   software vulnerabilities.  The second workspace provides an incident
   Collection for use by a private sharing consortium.  An appropriately
   authenticated and authorized client may then proceed to make HTTP
   requests for these Collections.  The publicly provided vulnerability
   information may be accessible with or without authentication.
   However, users accessing the Collection restricted to authorized
   members of a private sharing consortium are expected to authenticate
   before access is allowed.

B.2. Feed Retrieval

This appendix provides a non-normative example of a client retrieving a vulnerability Feed. Having discovered the available Collections that share security information, a client who is a member of the general public may be interested in receiving the Collection of public vulnerabilities, expressed as Common Vulnerabilities and Exposures (CVEs). The client may retrieve the Feed for this Collection by performing an HTTP GET operation on the URL indicated by the Collection's "href" attribute. Example HTTP GET request for a Feed: GET /provider/public/vulns Host: www.example.org Accept: application/atom+xml
Top   ToC   RFC8322 - Page 41
   The corresponding HTTP response would be an XML document containing
   the vulnerability Feed:

   Example HTTP GET response for a Feed:

     HTTP/1.1 200 OK
     Date: Fri, 24 Aug 2016 17:20:11 GMT
     Content-Length: 2882
     Content-Type: application/atom+xml;charset="utf-8"

     <?xml version="1.0" encoding="UTF-8"?>
     <feed xmlns="https://www.w3.org/2005/Atom"
         xmlns:rolie="urn:ietf:params:xml:ns:rolie-1.0"
         xml:lang="en-US">
       <id>2a7e265a-39bc-43f2-b711-b8fd9264b5c9</id>
       <title type="text">
           Atom-formatted representation of
           a Feed of XML vulnerability documents
       </title>
       <category
           scheme="urn:ietf:params:rolie:category:information-type"
           term="vulnerability"/>
       <updated>2016-05-04T18:13:51.0Z</updated>
       <link rel="self"
           href="https://example.org/provider/public/vulns"/>
       <link rel="service"
           href="https://example.org/rolie/servicedocument"/>
       <entry>
         <rolie:format ns="urn:ietf:params:xml:ns:exampleformat"/>
         <id>dd786dba-88e6-440b-9158-b8fae67ef67c</id>
         <title>Sample Vulnerability</title>
         <published>2015-08-04T18:13:51.0Z</published>
         <updated>2015-08-05T18:13:51.0Z</updated>
         <summary>A vulnerability issue identified by CVE-...</summary>
         <content type="application/xml"
             src="https://example.org/provider/vulns/123456/data"/>
       </entry>
       <entry>
           <!-- ...another entry... -->
       </entry>
     </feed>

   This Feed Document has two Atom Entries, one of which has been
   elided.  The first Entry illustrates an "atom:entry" element that
   provides a summary of essential details about one particular
   vulnerability.  Based upon this summary information and the provided
Top   ToC   RFC8322 - Page 42
   category information, a client may choose to do an HTTP GET request
   on the content "src" attribute to retrieve the full details of the
   vulnerability.

B.3. Entry Retrieval

This appendix provides a non-normative example of a client retrieving a vulnerability as an Atom Entry. Having retrieved the Feed of interest, the client may then decide, based on the description and/or category information, that one of the Entries in the Feed is of further interest. The client may retrieve this vulnerability Entry by performing an HTTP GET operation on the URL indicated by the "src" attribute of the "atom:content" element. Example HTTP GET request for an Entry: GET /provider/public/vulns/123456 Host: www.example.org Accept: application/atom+xml;type=entry The corresponding HTTP response would be an XML document containing the Atom Entry for the vulnerability record: Example HTTP GET response for an Entry: HTTP/1.1 200 OK Date: Fri, 24 Aug 2016 17:30:11 GMT Content-Length: 713 Content-Type: application/atom+xml;type=entry;charset="utf-8" <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="https://www.w3.org/2005/Atom" xmlns:rolie="urn:ietf:params:xml:ns:rolie-1.0" xml:lang="en-US"> <id>f63aafa9-4082-48a3-9ce6-97a2d69d4a9b</id> <title>Sample Vulnerability</title> <published>2015-08-04T18:13:51.0Z</published> <updated>2015-08-05T18:13:51.0Z</updated> <category scheme="urn:ietf:params:rolie:category:information-type" term="vulnerability"/> <summary>A vulnerability issue identified by CVE-...</summary> <rolie:format ns="urn:ietf:params:xml:ns:exampleformat"/> <content type="application/xml" src="https://example.org/provider/vulns/123456/data"> </content> </entry>
Top   ToC   RFC8322 - Page 43
   The example response above shows an XML document referenced by the
   "src" attribute of the "atom:content" element.  The client may
   retrieve the document using this URL.

Acknowledgements

The authors gratefully acknowledge the valuable contributions of Tom Maguire, Kathleen Moriarty, and Vijayanand Bharadwaj. These individuals provided detailed review comments on earlier draft versions of this document and made many suggestions that have helped to improve this document. The authors would also like to thank the MILE Working Group, the SACM Working Group, and countless other people from both within the IETF community and outside of it for their excellent review and effort towards constructing this document.

Authors' Addresses

John P. Field Pivotal Software, Inc. 625 Avenue of the Americas New York, New York 10011 United States of America Phone: (646)792-5770 Email: jfield@pivotal.io Stephen A. Banghart National Institute of Standards and Technology 100 Bureau Drive Gaithersburg, Maryland 20877 United States of America Phone: (301)975-4288 Email: stephen.banghart@nist.gov David Waltermire National Institute of Standards and Technology 100 Bureau Drive Gaithersburg, Maryland 20877 United States of America Email: david.waltermire@nist.gov