A Reputation Query Protocol
Mimecast203 Crescent St., Suite 303WalthamMA02453USA+1 781 996 5340nsb@guppylake.com270 Upland DriveSan FranciscoCA94127USAsuperuser@gmail.com
Applications
REPUTE Working Groupreputationdomainsecuritymessagingdkimspfauthentication 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. 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:
A client retrieves a template from a server that describes
the construction of a Universal Resource Identifier (URI)
that will be the actual query; The client then uses the constructed URI to request
the reputation data from the server. This section defines terms used in the rest of the document.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
. Other terms of importance in this document are defined in
and
. The components to the question being asked are the following:
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 . The name of the application, if given, is expected to be one registered
with IANA in the "Reputation Applications" registry, which is defined in
. 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 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. The template file is retrieved by requesting the
"repute-template" from the
host providing reputation service, using HTTP. (The registration
for this well-known URI is in .)
The server returns the template file in a reply that MUST use the
text/plain media type (see ) and SHOULD include
an Expires field (see Section 14.21 of ) 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:
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:
The syntax for the of the query is
constructed using a template as per .
(See .) Clients MUST provide the following
values in the expansion of the template:
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 .
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.
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
. 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:
The name of the specific assertion of interest
to the client. Assertion names conform to the ABNF
"token" found in . 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:
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:
...or, even better, using URI template set expansions:
Every application space has a set of assertions applicable to its
own context. defines a single
assertion 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, 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. 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
. If the server generates responses that contain an Expires field
(see Section 14.21 of ), 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. A client has to implement HTTP in order to retrieve the query template
as described in . 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. This document registers the "repute-template" well-known URI in the
"Well-Known URI" registry as defined by
, as follows:
repute-template IETF [RFC7072] none 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
, and those relevant to well-known URI
definitions and retrieval are discussed in
. 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
. The security considerations applicable to HTTP (see Section 15 of
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 can be used. Hypertext Transfer Protocol -- HTTP/1.1Department of Information and Computer ScienceUniversity of California, IrvineIrvineCA92697-3425+1(949)824-1715fielding@ics.uci.eduWorld Wide Web ConsortiumMIT Laboratory for Computer Science, NE43-356545 Technology SquareCambridgeMA02139+1(617)258-8682jg@w3.orgCompaq Computer CorporationWestern Research Laboratory250 University AvenuePalo AltoCA94305mogul@wrl.dec.comWorld Wide Web ConsortiumMIT Laboratory for Computer Science, NE43-356545 Technology SquareCambridgeMA02139+1(617)258-8682frystyk@w3.orgXerox CorporationMIT Laboratory for Computer Science, NE43-3563333 Coyote Hill RoadPalo AltoCA94034masinter@parc.xerox.comMicrosoft Corporation1 Microsoft WayRedmondWA98052paulle@microsoft.comWorld Wide Web ConsortiumMIT Laboratory for Computer Science, NE43-356545 Technology SquareCambridgeMA02139+1(617)258-8682timbl@w3.org
The Hypertext Transfer Protocol (HTTP) is an application-level
protocol for distributed, collaborative, hypermedia information
systems. It is a generic, stateless, protocol which can be used for
many tasks beyond its use for hypertext, such as name servers and
distributed object management systems, through extension of its
request methods, error codes and headers . A feature of HTTP is
the typing and negotiation of data representation, allowing systems
to be built independently of the data being transferred.
HTTP has been in use by the World-Wide Web global information
initiative since 1990. This specification defines the protocol
referred to as "HTTP/1.1", and is an update to RFC 2068 .
Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message BodiesInnosoft International, Inc.1050 East Garvey Avenue SouthWest CovinaCA91790US+1 818 919 3600+1 818 919 3614ned@innosoft.comFirst Virtual Holdings25 Washington AvenueMorristownNJ07960US+1 201 540 8967+1 201 993 3032nsb@nsb.fv.comSTD 11, RFC 822, defines a message representation protocol specifying considerable detail about US-ASCII message headers, and leaves the message content, or message body, as flat US-ASCII text. This set of documents, collectively called the Multipurpose Internet Mail Extensions, or MIME, redefines the format of messages to allow for(1) textual message bodies in character sets other than US-ASCII,(2) an extensible set of different formats for non-textual message bodies,(3) multi-part message bodies, and(4) textual header information in character sets other than US-ASCII.These documents are based on earlier work documented in RFC 934, STD 11, and RFC 1049, but extends and revises them. Because RFC 822 said so little about message bodies, these documents are largely orthogonal to (rather than a revision of) RFC 822.This initial document specifies the various headers used to describe the structure of MIME messages. The second document, RFC 2046, defines the general structure of the MIME media typing system and defines an initial set of media types. The third document, RFC 2047, describes extensions to RFC 822 to allow non-US-ASCII text data in Internet mail header fields. The fourth document, RFC 2048, specifies various IANA registration procedures for MIME-related facilities. The fifth and final document, RFC 2049, describes MIME conformance
criteria as well as providing some illustrative examples of MIME message formats, acknowledgements, and the bibliography.These documents are revisions of RFCs 1521, 1522, and 1590, which themselves were revisions of RFCs 1341 and 1342. An appendix in RFC 2049 describes differences and changes from previous versions.A Media Type for Reputation InterchangeThis document defines the format of reputation response data ("reputons"), the media-type for packaging it, and definition of a registry for the names of reputation applications and response sets.An Architecture for Reputation ReportingThis document describes a general architecture for a reputation-based service, allowing one to request reputation-related data over the Internet, where "reputation" refers to predictions or expectations about an entity or an identifier such as a domain name. The document roughly follows the recommendations of RFC4101 for describing a protocol model.Key words for use in RFCs to Indicate Requirement LevelsHarvard University1350 Mass. Ave.CambridgeMA 02138- +1 617 495 3864sob@harvard.edu
General
keyword
In many standards track documents several words are used to signify
the requirements in the specification. These words are often
capitalized. This document defines these words as they should be
interpreted in IETF documents. Authors who follow these guidelines
should incorporate this phrase near the beginning of their document:
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
RFC 2119.
Note that the force of these words is modified by the requirement
level of the document in which they are used.
Uniform Resource Identifier (URI): Generic SyntaxWorld Wide Web ConsortiumMassachusetts Institute of Technology77 Massachusetts AvenueCambridgeMA02139USA+1-617-253-5702+1-617-258-5999timbl@w3.orghttp://www.w3.org/People/Berners-Lee/Day Software5251 California Ave., Suite 110IrvineCA92617USA+1-949-679-2960+1-949-679-2972fielding@gbiv.comhttp://roy.gbiv.com/Adobe Systems Incorporated345 Park AveSan JoseCA95110USA+1-408-536-3024LMM@acm.orghttp://larry.masinter.net/
Applications
uniform resource identifierURIURLURNWWWresource
A Uniform Resource Identifier (URI) is a compact sequence of characters
that identifies an abstract or physical resource. This specification
defines the generic URI syntax and a process for resolving URI references
that might be in relative form, along with guidelines and security
considerations for the use of URIs on the Internet.
The URI syntax defines a grammar that is a superset of all valid URIs,
allowing an implementation to parse the common components of a URI
reference without knowing the scheme-specific requirements of every
possible identifier. This specification does not define a generative
grammar for URIs; that task is performed by the individual
specifications of each URI scheme.
URI TemplateA URI Template is a compact sequence of characters for describing a range of Uniform Resource Identifiers through variable expansion. This specification defines the URI Template syntax and the process for expanding a URI Template into a URI reference, along with guidelines for the use of URI Templates on the Internet. [STANDARDS-TRACK]Defining Well-Known Uniform Resource Identifiers (URIs)This memo defines a path prefix for "well-known locations", "/.well-known/", in selected Uniform Resource Identifier (URI) schemes. [STANDARDS-TRACK]HTTP Over TLSThis memo describes how to use Transport Layer Security (TLS) to secure Hypertext Transfer Protocol (HTTP) connections over the Internet. This memo provides information for the Internet community.Operational Considerations Regarding Reputation ServicesThe use of reputation systems is has become a common tool in many applications that seek to apply collected intelligence about traffic sources. Often this is done because it is common or even expected operator practice. It is therefore important to be aware of a number of considerations for both operators and consumers of the data. This document includes a collection of the best advice available regarding providers and consumers of reputation data, based on experience to date. Much of this is based on experience with email reputation systems, but the concepts are generally applicable. The authors would like to thank the following for their contributions
to this work:
Simon Hunt,
Mark Nottingham,
David F. Skoll,
and
Mykyta Yevstifeyev.