draft-ietf-repute-media-type-11.txt   draft-ietf-repute-media-type-12.txt 
REPUTE Working Group N. Borenstein REPUTE Working Group N. Borenstein
Internet-Draft Mimecast Internet-Draft Mimecast
Intended status: Standards Track M. Kucherawy Intended status: Standards Track M. Kucherawy
Expires: March 2, 2014 August 29, 2013 Expires: March 11, 2014 September 7, 2013
A Media Type for Reputation Interchange A Media Type for Reputation Interchange
draft-ietf-repute-media-type-11 draft-ietf-repute-media-type-12
Abstract Abstract
This document defines the format of reputation response data This document defines the format of reputation response data
("reputons"), the media-type for packaging it, and definition of a ("reputons"), the media-type for packaging it, and definition of a
registry for the names of reputation applications and response sets. registry for the names of reputation applications and response sets.
Status of this Memo Status of this Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
skipping to change at page 1, line 32 skipping to change at page 1, line 32
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on March 2, 2014. This Internet-Draft will expire on March 11, 2014.
Copyright Notice Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 3, line 39 skipping to change at page 3, line 39
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [KEYWORDS]. document are to be interpreted as described in [KEYWORDS].
2.3. Other Definitions 2.3. Other Definitions
Other terms of importance in this document are defined in Other terms of importance in this document are defined in
[I-D.REPUTE-MODEL], the base document in this document series. [I-D.REPUTE-MODEL], the base document in this document series.
3. Description 3. Description
The meta-format selected for the representaton of a reputon is The meta-format selected for the representation of a reputon is
Javascript Object Notation (JSON), defined in [JSON]. Accordingly, a JavaScript Object Notation (JSON), defined in [JSON]. Accordingly, a
new media type, "application/reputon+json", is defined for the JSON new media type, "application/reputon+json", is defined for the JSON
representation of reputational data, typically in response to a representation of reputational data, typically in response to a
client making a request for such data about some subject. This media client making a request for such data about some subject. This media
type has one optional parameter, "context", which names the semantic type has one optional parameter, "context", which names the semantic
context (i.e., the specific sphere of reputation evaluation, or context (i.e., the specific sphere of reputation evaluation, or
application) in which context the query is made and the response application) in which the query is made and the response returned.
returned. If the parameter is absent, a generic reputation query If the parameter is absent, a generic reputation query (i.e., one not
(i.e., one not associated with a specific reputation application) is associated with a specific reputation application) is assumed for
assumed for which only a simple reply is allowed. which only a simple reply is allowed.
The body of the media type consists of a JSON document that contains The body of the media type consists of a JSON document that contains
the reputation information requested. A detailed description of the the reputation information requested. A detailed description of the
expected structure of the reply is provided below. expected structure of the reply is provided below.
3.1. Reputon Attributes 3.1. Reputon Attributes
The key pieces of data found in a reputon for all reputation The key pieces of data found in a reputon for all reputation
applications are defined as follows: applications are defined as follows:
rater: The identity of the entity providing the reputation rater: The identity of the entity aggregating, computing, and
information, typically expressed as a DNS domain name. providing the reputation information, typically expressed as a DNS
domain name.
assertion: A keyword indicating the specific assertion or claim assertion: A keyword indicating the specific assertion or claim
being rated. In the absence of an "context" parameter on the being rated. In the absence of a "context" parameter on the media
media type, the reputon can only indicate generic goodness, with type, the reputon can only indicate generic goodness, with the
the default assertion "is-good", but each application is expected default assertion "is-good", but each application is expected to
to define additional assertions. define additional assertions.
rated: The identity of the entity being rated. The nature of this rated: The identity of the entity being rated. The nature of this
field is application-specific; it could be domain names, email field is application-specific; it could be domain names, email
addresses, driver's license numbers, or anything that uniquely addresses, driver's license numbers, or anything that uniquely
identifies the entity being rated. Documents that define specific identifies the entity being rated. Documents that define specific
reputation applications are required to define syntax and reputation applications are required to define syntax and
semantics for this field. semantics for this field.
rating: The overall rating score for that entity, expressed as a rating: The overall rating score for that entity, expressed as a
floating-point number between 0.0 and 1.0 inclusive. See floating-point number between 0.0 and 1.0 inclusive. See
skipping to change at page 5, line 39 skipping to change at page 5, line 40
The score presented as the value in the rating attribute appears as a The score presented as the value in the rating attribute appears as a
floating point value between 0.0 and 1.0 inclusive. The intent is floating point value between 0.0 and 1.0 inclusive. The intent is
that the definition of an assertion within an application will that the definition of an assertion within an application will
declare what the anchor values 0.0 and 1.0 specifically mean. declare what the anchor values 0.0 and 1.0 specifically mean.
Generally speaking, 1.0 implies full agreement with the assertion, Generally speaking, 1.0 implies full agreement with the assertion,
while 0.0 indicates no support for the assertion. while 0.0 indicates no support for the assertion.
The definition will also specify the type of scale in use when The definition will also specify the type of scale in use when
generating scores, to which all reputation service providers for that generating scores, to which all reputation service providers for that
application space must adhere. This will allow a client to change application space must adhere. This will allow a client to change
which reputation service provider is being queried for a given which reputation service provider is being queried without having to
without having to learn through some out-of-band method what the new learn through some out-of-band method what the new provider's ratings
provider's values mean. For example, a registration might state that mean. For example, a registration might state that ratings are
ratings are linear, which would mean a score of "x" is twice as linear, which would mean a score of "x" is twice as strong as a value
strong as a value of "x/2". It also allows easier aggregation of of "x/2". It also allows easier aggregation of ratings collected
ratings collected from multiple reputation service providers. from multiple reputation service providers.
5. Caching 5. Caching
A reputon can contain an "expires" field indicating a timestamp after A reputon can contain an "expires" field indicating a timestamp after
which the client SHOULD NOT use the rating it contains, and SHOULD which the client SHOULD NOT use the rating it contains, and SHOULD
issue a new query. issue a new query.
This specificaiton does not mandate any caching of ratings on the This specification does not mandate any caching of ratings on the
part of the client, but there are obvious operational benefits to part of the client, but there are obvious operational benefits to
doing so. In the context of reputation, a cached (and hence, stale) doing so. In the context of reputation, a cached (and hence, stale)
rating can cause desirable traffic to be identified as undesirable, rating can cause desirable traffic to be identified as undesirable,
or vice-versa. or vice-versa.
Reputation data is typically most volatile when the subject of the Reputation data is typically most volatile when the subject of the
reputation is young. Accordingly, if a service chooses to include reputation is young. Accordingly, if a service chooses to include
expiration timestamps as part a reply, these values SHOULD be lower expiration timestamps as part a reply, these values SHOULD be lower
for subjects about which little data has been collected. for subjects about which little data has been collected.
skipping to change at page 7, line 14 skipping to change at page 7, line 14
reputon = "{" [ reputon-object reputon = "{" [ reputon-object
*(value-separator reputon-object) ] "}" *(value-separator reputon-object) ] "}"
reputon-object = "reputon" name-separator response-set reputon-object = "reputon" name-separator response-set
response-set = "{" reputon-element response-set = "{" reputon-element
*(value-separator reputon-element) "} *(value-separator reputon-element) "}
reputon-element = rater-value / assertion-value / rated-value reputon-element = rater-value / assertion-value / rated-value
/ rating-value / conf-value / auth-value / rating-value / conf-value / normal-value
/ sample-value / gen-value / expire-value / sample-value / gen-value / expire-value
/ ext-value / ext-value
; these can appear in any order, but MUST appear at most ; these can appear in any order, but MUST appear at most
; once each ; once each
rater-value = %x22 "rater" %x22 name-separator string rater-value = %x22 "rater" %x22 name-separator string
assertion-value = %x22 "assertion" %x22 name-separator string assertion-value = %x22 "assertion" %x22 name-separator string
rated-value = %x22 "rated" %x22 name-separator string rated-value = %x22 "rated" %x22 name-separator string
rating-value = %x22 "rating" %x22 name-separator number rating-value = %x22 "rating" %x22 name-separator number
; "number" MUST be between 0.0 and 1.0 inclusive ; "number" MUST be between 0.0 and 1.0 inclusive
conf-value = %x22 "confidence" %x22 name-separator number conf-value = %x22 "confidence" %x22 name-separator number
; "number" MUST be between 0.0 and 1.0 inclusive ; "number" MUST be between 0.0 and 1.0 inclusive
auth-value = %x22 "rater-authenticity" %x22 name-separator number normal-value = %x22 "normal-rating" %x22 name-separator number
; "number" MUST be between 0.0 and 1.0 inclusive ; "number" MUST be between 0.0 and 1.0 inclusive
sample-value = %x22 "sample-size" %x22 name-separator int sample-value = %x22 "sample-size" %x22 name-separator int
; "int" MUST NOT be negative ; "int" MUST NOT be negative
gen-value = %x22 "generated" %x22 name-separator int gen-value = %x22 "generated" %x22 name-separator int
; "int" MUST NOT be negative ; "int" MUST NOT be negative
expire-value = %x22 "expires" %x22 name-separator int expire-value = %x22 "expires" %x22 name-separator int
; "int" MUST NOT be negative ; "int" MUST NOT be negative
ext-value = member ext-value = member
; specific syntax is specified in specific application ; specific syntax is defined in separate application
; registrations ; registrations
The tokens "value-separator", "name-separator", "string", "int", and The tokens "value-separator", "name-separator", "string", "int", and
"member" are defined in [JSON]. "member" are defined in [JSON].
6.2. Examples 6.2. Examples
The following simple example: The following simple example:
Content-type: application/reputon+json Content-type: application/reputon+json
{ {
"reputon": "reputon":
{ {
"rater": "RatingsRUs.example.com", "rater": "RatingsRUs.example.com",
"rater-authenticity": 1.0,
"assertion": "is-good", "assertion": "is-good",
"rated": "Alex Rodriguez", "rated": "Alex Rodriguez",
"rating": 0.99, "rating": 0.99,
"sample-size": 50000 "sample-size": 50000
} }
} }
...indicates we are absolutely sure (1.0) that the entity ...indicates to the client that "RatingsRUs.example.com" consolidated
"RatingsRUs.example.com" consolidated 50000 data points (perhaps from 50000 data points (perhaps from everyone in Yankee Stadium) and
everyone in Yankee Stadium) and concluded that Alex Rodriguez is very concluded that Alex Rodriguez is very very good (0.99) at something.
very good (0.99) at something. It doesn't tell us what he's good at, It doesn't tell us what he's good at, and while it might be playing
and while it might be playing baseball, it could just as well be baseball, it could just as well be paying his taxes on time.
paying his taxes on time.
A more sophisticated usage would define a baseball application with a A more sophisticated usage would define a baseball application with a
response set of specific assertions, so that this example: response set of specific assertions, so that this example:
Content-type: application/reputon+json; context="baseball" Content-type: application/reputon+json; context="baseball"
{ {
"reputon": "reputon":
{ {
"rater": "baseball-reference.example.com", "rater": "baseball-reference.example.com",
"rater-authenticity": 1.0,
"assertion": "hits-for-power", "assertion": "hits-for-power",
"rated": "Alex Rodriguez", "rated": "Alex Rodriguez",
"rating": 0.99, "rating": 0.99,
"sample-size": 50000 "sample-size": 50000
} }
} }
...would indicate that 50000 fans polled by the entity baseball- ...would indicate that 50000 fans polled by the entity baseball-
reference.example.com rate Alex Rodriguez very highly in hitting for reference.example.com rate Alex Rodriguez very highly in hitting for
power, whereas this example: power, whereas this example:
Content-type: application/reputon+json; context="baseball" Content-type: application/reputon+json; context="baseball"
{ {
"reputon": "reputon":
{ {
"rater": "baseball-reference.example.com", "rater": "baseball-reference.example.com",
"rater-authenticity": 1.0,
"assertion": "clutch-hitter", "assertion": "clutch-hitter",
"rated": "Alex Rodriguez", "rated": "Alex Rodriguez",
"rating": 0.4, "rating": 0.4,
"confidence": 0.2, "confidence": 0.2,
"sample-size": 50000 "sample-size": 50000
} }
} }
...would indicate that a similar poll indicated a somewhat weak ...would indicate that a similar poll indicated a somewhat weak
consensus that Alex Rodriguez tends to choke in critical baseball consensus that Alex Rodriguez tends to choke in critical baseball
situations. situations.
In practice, it is expected that most reputons will have an "context" In practice, it is expected that most reputons will have an "context"
parameter to target an application-specific set of assertions. parameter to target an application-specific set of assertions.
The following is an example reputon generated using this schema, The following is an example reputon generated using this schema,
including the media type definition line that idenfities a specific including the media type definition line that identifies a specific
reputation application context. Here, reputation agent reputation application context. Here, reputation agent
"rep.example.net" is asserting within the context of the "email-id" "rep.example.net" is asserting within the context of the "email-id"
application (see [I-D.REPUTE-EMAIL-IDENTIFIERS]) that "example.com" application (see [I-D.REPUTE-EMAIL-IDENTIFIERS]) that "example.com"
appears to be associated with spam 1.2% of the time, based on just appears to be associated with spam 1.2% of the time, based on just
short of 17 million messages analyzed or reported to date. The short of 17 million messages analyzed or reported to date. The
"email-id" application has declared the extension key "identity" to "email-id" application has declared the extension key "identity" to
indicate how the subject identifier was used in the observed data, indicate how the subject identifier was used in the observed data,
establishing some more specific semantics for the "rating" value. In establishing some more specific semantics for the "rating" value. In
this case, the extension is used to show the identity "example.com", this case, the extension is used to show the identity "example.com",
the subject of the query, is extracted from the analyzed messages the subject of the query, is extracted from the analyzed messages
using the [DKIM] "d=" parameter for messages where signatures using the [DKIM] "d=" parameter for messages where signatures
validate. The reputation agent is 95% confident of this result. validate. The reputation agent is 95% confident of this result.
(See [I-D.REPUTE-EMAIL-IDENTIFIERS] for details about the registered (See [I-D.REPUTE-EMAIL-IDENTIFIERS] for details about the registered
email identifiers application.) email identifiers application.)
Content-Type: application/reputon+json; context="email-id" Content-Type: application/reputon+json; context="email-id"
{ {
"reputon": "reputon":
{ {
"rater": "rep.example.net", "rater": "rep.example.net",
"rater-authenticity": 0.95,
"assertion": "spam", "assertion": "spam",
"identity": "dkim", "identity": "dkim",
"rated": "example.com", "rated": "example.com",
"confidence": 0.95,
"rating": 0.012, "rating": 0.012,
"sample-size": 16938213, "sample-size": 16938213,
"updated": 1317795852 "updated": 1317795852
} }
} }
7. IANA Considerations 7. IANA Considerations
This document presents two actions for IANA, namely the creation of This document presents two actions for IANA, namely the creation of
the new media type "application/reputon+json" and the creation of a the new media type "application/reputon+json" and the creation of a
 End of changes. 19 change blocks. 
36 lines changed or deleted 33 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/