RFC 7072

A Reputation Query Protocol

📅 published November 2013, from ietf

A Reputation Query Protocol 🎀

Okay bestie, the header says this is RFC 7072, published by the Internet Engineering Task Force (IETF) in November 2013 🍓. The authors are N. Borenstein (from Mimecast) and M. Kucherawy. It's Standards Track (so it's real, official IETF stuff ✨), and its ISSN is 2070-1721. The header doesn't list anything it obsoletes or updates.

Abstract

Okay, so the abstract is basically the whole vibe 💌. This doc defines a way to ask for reputation info over the HyperText Transfer Protocol (HTTP), with JavaScript Object Notation (JSON) as the payload meta-format. Simple, clean, iconic.

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 (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, because 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 they are provided without warranty as described in the Simplified BSD License.

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 ✨

Okay so this doc defines a method to query a reputation data service for info about an entity 🦋. It uses HTTP as the transport mechanism and JSON as the payload meta-format.

The mechanism is a two-stage query, and it's giving very organized energy:

  1. A client retrieves a template from a server. The template describes how to build a Universal Resource Identifier (URI) that becomes 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 the terms used in the rest of the document, so bookmark it bestie 🧚.

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]. 🎯

2.2. Other Definitions

Other terms of importance in this document are defined in [RFC7070] and [RFC7071]. 📖

3. Description 🌸

3.1. Overview

Okay, here are the components of the question being asked 💭:

  • The subject of the query;
  • The name of the host, or the IP address, at which the reputation service is available;
  • The name of the reputation application, i.e., the context within which the subject is being evaluated;
  • 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 that receives a query about an application it does not recognize or explicitly support (for example, through 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 is set by retrieving a URI template from the reputation service, completing the template, and then issuing the query. It's like a little recipe 🍰.

3.2. URI Template

The template file is retrieved by requesting the [WELL-KNOWN-URI] "repute-template" from the host providing the 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 text/plain media type (see [MIME]). It SHOULD include an Expires field (see Section 14.21 of [HTTP]) that indicates how long clients can consider the template valid without re-querying it ⏳.

If an Expires field is present, the client SHOULD NOT send another query to the same server before the timestamp in that field. If no Expires field is present, the client SHOULD wait at least one day before sending another query to the same server. In other words, the client assumes a default expiration of one day 📅.

The template file might contain more than one template. When it does, each template MUST be separated by a carriage return (ASCII 0x0D) and newline (ASCII 0x0A) character, which 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 it 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, sent to a service run at "example.com", where that application declares a required "subject" parameter and requests 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 they conform to the ABNF "token" found in [MIME].
  • 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, the client substitutes the empty string into the template in place of that variable. Service providers crafting templates MUST do so in a way 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 (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 so 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 that is assumed to exist in any application that does not define its own assertion set.

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. These are private arrangements between client and server, and they 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 then be unable to get a fresh answer from the reputation server. That's a major mismatch, no cap 💀.

3.5. Protocol Support 🌸

okay so, bestie, a client has to speak HTTP to grab the query template from Section 3.2 💅 no way around it. That means a server can totally assume the client can handle a URI template that spits out a query URI using the http URI scheme 🔗✨. The template could also give back a query string with some other URI scheme, and if the client knows how to issue queries with that scheme, it can try that one too 🦋

A server SHOULD support providing service over HTTP and publish templates saying so 🫶 It's the baseline that keeps things interoperable with any random client who shows up 🌈

4. IANA Considerations ✨

okay the IANA part is lowkey simple 💜 this document registers the "repute-template" well-known URI in the "Well-Known URI" registry, as defined by [WELL-KNOWN-URI] 🎀 here's the entry:

   URI suffix:  repute-template

   Change controller:  IETF

   Specification document(s):  [RFC7072]

   Related information:  none

5. Security Considerations 💀

okay, this section is serious, so buckle up 😭 this document defines particular uses of existing protocols for one specific app. The base protocol for pulling a URI template from a well-known location is basic HTTP, and basic HTTP is NOT secure without certain extensions. Yikes 🙈 Security issues with URI templates are covered in [URI-TEMPLATE], and the stuff about well-known URI definitions and retrieval lives in [WELL-KNOWN-URI] 🔥

The reputation service itself uses HTTP or other transport methods to send queries and receive replies 🧚 Those protocols have registered URI schemes, so they presumably have their own documented security considerations. This protocol just runs on top of those URI schemes and doesn't bring any new security issues of its own 💖

Reputation mechanisms are an obvious security concern, periodt 👑 both for whether the reputation info is valid and for how it gets used. Those issues are beyond the scope of this spec ✨ If you want general info about using or providing reputation services, check out [CONSIDERATIONS] 🌸

The security considerations for HTTP (see Section 15 of [HTTP]) apply here, since this query mechanism uses that protocol 💅 If you want to hide the content of the query and its response, you can use encryption, like HTTP over TLS [HTTPS] 🔐🫶

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.

Appendix A. Acknowledgements 🎀

the authors wanted to shout out these legends 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

📦 where this page comes from