From 4bfd864f10b68b71482b35c818559068ef8d5797 Mon Sep 17 00:00:00 2001 From: Thomas Voss Date: Wed, 27 Nov 2024 20:54:24 +0100 Subject: doc: Add RFC documents --- doc/rfc/rfc7072.txt | 507 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 507 insertions(+) create mode 100644 doc/rfc/rfc7072.txt (limited to 'doc/rfc/rfc7072.txt') diff --git a/doc/rfc/rfc7072.txt b/doc/rfc/rfc7072.txt new file mode 100644 index 0000000..c93bfd4 --- /dev/null +++ b/doc/rfc/rfc7072.txt @@ -0,0 +1,507 @@ + + + + + + +Internet Engineering Task Force (IETF) N. Borenstein +Request for Comments: 7072 Mimecast +Category: Standards Track M. Kucherawy +ISSN: 2070-1721 November 2013 + + + A Reputation Query Protocol + +Abstract + + This document defines a mechanism to conduct queries for reputation + information over the HyperText Transfer Protocol (HTTP) using + JavaScript Object Notation (JSON) as the payload meta-format. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc7072. + +Copyright Notice + + Copyright (c) 2013 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + + + + + + + + +Borenstein & Kucherawy Standards Track [Page 1] + +RFC 7072 A Reputation Query Protocol November 2013 + + +Table of Contents + + 1. Introduction ....................................................2 + 2. Terminology and Definitions .....................................2 + 2.1. Key Words ..................................................2 + 2.2. Other Definitions ..........................................3 + 3. Description .....................................................3 + 3.1. Overview ...................................................3 + 3.2. URI Template ...............................................3 + 3.3. Syntax .....................................................4 + 3.4. Response ...................................................6 + 3.5. Protocol Support ...........................................6 + 4. IANA Considerations .............................................7 + 5. Security Considerations .........................................7 + 6. References ......................................................8 + 6.1. Normative References .......................................8 + 6.2. Informative References .....................................8 + Appendix A. Acknowledgements .......................................9 + +1. Introduction + + This document defines a method to query a reputation data service for + information about an entity, using the HyperText Transfer Protocol + (HTTP) as the transport mechanism and JSON as the payload meta- + format. + + The mechanism is a two-stage query: + + 1. A client retrieves a template from a server that describes the + construction of a Universal Resource Identifier (URI) that will + be the actual query; + + 2. The client then uses the constructed URI to request the + reputation data from the server. + +2. Terminology and Definitions + + This section defines terms used in the rest of the document. + +2.1. Key Words + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [KEYWORDS]. + + + + + + + +Borenstein & Kucherawy Standards Track [Page 2] + +RFC 7072 A Reputation Query Protocol November 2013 + + +2.2. Other Definitions + + Other terms of importance in this document are defined in [RFC7070] + and [RFC7071]. + +3. Description + +3.1. Overview + + The components to the question being asked are the following: + + o The subject of the query; + + o The name of the host, or the IP address, at which the reputation + service is available; + + o The name of the reputation application, i.e., the context within + which the subject is being evaluated; + + o Optionally, names of the specific reputation assertions or + attributes that are being requested. + + There is no discovery protocol for finding reputation services. + These are typically subscription services, negotiated between + operators through some out-of-band method. + + Assertions are discussed in [RFC7071]. + + The name of the application, if given, is expected to be one + registered with IANA in the "Reputation Applications" registry, which + is defined in [RFC7071]. A server receiving a query about an + application it does not recognize or explicitly support (e.g., by + virtue of private agreements or experimental extensions) MUST return + a 404 error code. + + A reputation query made via [HTTP] encodes the question being asked + in an HTTP GET method. The specific syntax of the query itself is + specified by retrieving a URI template from the reputation service, + completing the template, and then issuing the query. + +3.2. URI Template + + The template file is retrieved by requesting the [WELL-KNOWN-URI] + "repute-template" from the host providing reputation service, using + HTTP. (The registration for this well-known URI is in Section 4.) + The server returns the template file in a reply that MUST use the + + + + + +Borenstein & Kucherawy Standards Track [Page 3] + +RFC 7072 A Reputation Query Protocol November 2013 + + + text/plain media type (see [MIME]) and SHOULD include an Expires + field (see Section 14.21 of [HTTP]) indicating a duration for which + the template is to be considered valid by clients and not re-queried. + + If an Expires field is present, the client SHOULD NOT send another + query to the same server prior to the timestamp in the field. If no + Expires field is present, the client SHOULD wait at least one day + before sending another query to the same server (i.e., the client + assumes a default expiration of one day). + + The template file might contain more than one template. Such a file + MUST have each template separated by a carriage return (ASCII 0x0D) + and newline (ASCII 0x0A) character, as is typical for most text-based + Internet protocols. + + Each template in the file is expanded using the variables that are + the parameters to the query. These parameters are either the subject + about which reputation information is sought (or details associated + with it) or other parameters that are established out-of-band with + the reputation service; they are not established by any automated + discovery described here. The client then attempts to query each + expanded template that uses a URI scheme it is capable of querying, + in the order presented in the file, until the client finds one to + which it can establish a usable connection and issue the query. + + For example, given the following template: + + http://{service}/{application}/{subject}/{assertion} + + A query about the use of the domain "example.org" in the "email-id" + application context to a service run at "example.com", where that + application declares a required "subject" parameter, requesting the + "SPAM" reputation assertion, would be formed as follows: + + http://example.com/email-id/example.org/spam + +3.3. Syntax + + The syntax for the [URI] of the query is constructed using a template + as per [URI-TEMPLATE]. (See Section 3.2.) Clients MUST provide the + following values in the expansion of the template: + + application: The name of the application reputation in whose context + the request is being made. These names are registered with IANA, + and conform to the ABNF "token" found in [MIME]. + + + + + + +Borenstein & Kucherawy Standards Track [Page 4] + +RFC 7072 A Reputation Query Protocol November 2013 + + + service: The hostname or IP address to which the query is being + sent. This MUST be the same as the host to which the template + query was issued. + + subject: The subject of the query, extracted from some content to be + evaluated. The subject portion of the template conforms to the + ABNF "value" found in [MIME]. + + The following variable can also be provided. It is not mandatory in + this model, but a specific application (defined in its own extension + document) might declare it mandatory in a specific context: + + assertion: The name of the specific assertion of interest to the + client. Assertion names conform to the ABNF "token" found in + [MIME]. If absent, the client is indicating that it requests all + available assertion information. + + If a template contains a variable that is not required and the client + does not have a value to insert, it substitutes the empty string into + the template in place of that variable. Service providers crafting + templates MUST do so such that a client doing an empty variable + expansion will still produce a syntactically and semantically valid + and unambiguous URI. For example, given this template: + + http://{service}/{application}/{subject}/{assertion}/{a}/{b} + + If "{a}" and "{b}" are optional and "{a}" expands to the empty + string, then the resulting URI will have adjacent backslash ("/", + ASCII 0x2F) characters and one path component after the assertion. + If the server interpreting the URI's path component removes or + ignores adjacent backslash characters (such as is done with the UNIX + filesystem), the server will be unable to distinguish an empty "{a}" + from an empty "{b}", and it could serve the wrong response. Where + possible, the template needs to be constructed such that expansion of + optional variables yields an unambiguous result. For example, an + unambiguous version of the above would be: + + http://{service}/{application}/{subject}/{assertion}/a={a}/b={b} + + ...or, even better, using URI template set expansions: + + http://{service}/{application}/{subject}/{assertion}{?a,b} + + Every application space has a set of assertions applicable to its own + context. [RFC7071] defines a single assertion assumed to exist in + any application that does not define its own assertion set. + + + + + +Borenstein & Kucherawy Standards Track [Page 5] + +RFC 7072 A Reputation Query Protocol November 2013 + + + Reputation applications can extend the set of optional or required + query parameters as part of their IANA registration actions. The set + enumerated above establishes the base set common to all of them. + Further, additional required or optional extension query parameters + might be defined by specific reputation service providers, though + these are private arrangements between client and server and will not + be registered with IANA. + + Authentication between reputation client and server is outside the + scope of this specification. It could be provided through a variety + of available transport-based or object-based mechanisms, including a + later extension of this specification. + +3.4. Response + + The response is expected to be contained in a media type designed to + deliver reputons. A media type designed for this purpose, + "application/reputon+json", is defined in [RFC7071]. + + If the server generates responses that contain an Expires field (see + Section 14.21 of [HTTP]), that timestamp MUST align with the + "expires" field within the response, if any. Failing to do so can + result in a state where the response has expired, but the HTTP reply + has not, and the client would in that case be unable to get a fresh + answer from the reputation server. + +3.5. Protocol Support + + A client has to implement HTTP in order to retrieve the query + template as described in Section 3.2. Accordingly, a server can + assume the client will be able to handle a URI template that produces + a URI for the query using the "http" URI scheme. The template could + yield a query string that uses some other URI scheme, in which case + the client could try that URI as well if it supports issuing queries + with that URI scheme. + + A server SHOULD include support for providing service over HTTP, and + publish templates indicating support for this, as a baseline for + interoperability with arbitrary clients. + + + + + + + + + + + + +Borenstein & Kucherawy Standards Track [Page 6] + +RFC 7072 A Reputation Query Protocol November 2013 + + +4. IANA Considerations + + This document registers the "repute-template" well-known URI in the + "Well-Known URI" registry as defined by [WELL-KNOWN-URI], as follows: + + URI suffix: repute-template + + Change controller: IETF + + Specification document(s): [RFC7072] + + Related information: none + +5. Security Considerations + + This document defines particular uses of existing protocols for a + specific application. In particular, the basic protocol used for + this service to retrieve a URI template from a well-known location is + basic HTTP, which is not secure without certain extensions. Security + issues relevant to use of URI templates are discussed in + [URI-TEMPLATE], and those relevant to well-known URI definitions and + retrieval are discussed in [WELL-KNOWN-URI]. + + The reputation service itself will use HTTP or other transport + methods to issue queries and receive replies. Those protocols have + registered URI schemes and, as such, presumably have documented + security considerations. The protocol described here operates atop + those URI schemes, and does not itself present new security + considerations. + + Reputation mechanisms represent an obvious security concern, in terms + of the validity and use of the reputation information. These issues + are beyond the scope of this specification. General information + pertaining to using or providing reputation services can be found in + [CONSIDERATIONS]. + + The security considerations applicable to HTTP (see Section 15 of + [HTTP] apply, since this query mechanism for reputation uses that + protocol. If it is desirable to conceal the content of the query and + its response, use of encryption techniques such as HTTP over TLS + [HTTPS] can be used. + + + + + + + + + + +Borenstein & Kucherawy Standards Track [Page 7] + +RFC 7072 A Reputation Query Protocol November 2013 + + +6. References + +6.1. Normative References + + [HTTP] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., + Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext + Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. + + [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [MIME] Freed, N. and N. Borenstein, "Multipurpose Internet Mail + Extensions (MIME) Part One: Format of Internet Message + Bodies", RFC 2045, November 1996. + + [RFC7070] Borenstein, N., Kucherawy, M., and A. Sullivan, "An + Architecture for Reputation Reporting", RFC 7070, November + 2013. + + [RFC7071] Borenstein, N. and M. Kucherawy, "A Media Type for + Reputation Interchange", RFC 7071, November 2013. + + [URI-TEMPLATE] + Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., + and D. Orchard, "URI Template", RFC 6570, March 2012. + + [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform + Resource Identifier (URI): Generic Syntax", STD 66, RFC + 3986, January 2005. + + [WELL-KNOWN-URI] + Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known + Uniform Resource Identifiers (URIs)", RFC 5785, April + 2010. + +6.2. Informative References + + [CONSIDERATIONS] + Kucherawy, M., "Operational Considerations Regarding + Reputation Services", Work in Progress, May 2013. + + [HTTPS] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. + + + + + + + + + +Borenstein & Kucherawy Standards Track [Page 8] + +RFC 7072 A Reputation Query Protocol November 2013 + + +Appendix A. Acknowledgements + + The authors would like to thank the following for their contributions + to this work: Simon Hunt, Mark Nottingham, David F. Skoll, and Mykyta + Yevstifeyev. + +Authors' Addresses + + Nathaniel Borenstein + Mimecast + 203 Crescent St., Suite 303 + Waltham, MA 02453 + USA + + Phone: +1 781 996 5340 + EMail: nsb@guppylake.com + + + Murray S. Kucherawy + 270 Upland Drive + San Francisco, CA 94127 + USA + + EMail: superuser@gmail.com + + + + + + + + + + + + + + + + + + + + + + + + + + + +Borenstein & Kucherawy Standards Track [Page 9] + -- cgit v1.2.3