A Reputation Query Protocol

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:

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

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:

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