draft-ietf-repute-media-type-06.txt   draft-ietf-repute-media-type-07.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: September 14, 2013 March 13, 2013 Expires: November 20, 2013 May 19, 2013
A Media Type for Reputation Interchange A Media Type for Reputation Interchange
draft-ietf-repute-media-type-06 draft-ietf-repute-media-type-07
Abstract Abstract
This document defines a media type for exchanging reputation This document defines the format of reputation response data
information about an arbitrary class of object. ("reputons"), the media-type for packaging it, and definition of a
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
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
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 September 14, 2013. This Internet-Draft will expire on November 20, 2013.
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 2, line 16 skipping to change at page 2, line 16
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology and Definitions . . . . . . . . . . . . . . . . . 3 2. Terminology and Definitions . . . . . . . . . . . . . . . . . 3
2.1. Reputon . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.1. Reputon . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2. Key Words . . . . . . . . . . . . . . . . . . . . . . . . 3 2.2. Key Words . . . . . . . . . . . . . . . . . . . . . . . . 3
2.3. Other Definitions . . . . . . . . . . . . . . . . . . . . 3 2.3. Other Definitions . . . . . . . . . . . . . . . . . . . . 3
3. Description . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Description . . . . . . . . . . . . . . . . . . . . . . . . . 3
3.1. Reputon Attributes . . . . . . . . . . . . . . . . . . . . 4 3.1. Reputon Attributes . . . . . . . . . . . . . . . . . . . . 4
4. Scores . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 4. Scores . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
5. Reputon Structure . . . . . . . . . . . . . . . . . . . . . . 5 5. Reputon Structure . . . . . . . . . . . . . . . . . . . . . . 5
5.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 5 5.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 6
5.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 6 5.1.1. Formal Definition . . . . . . . . . . . . . . . . . . 6
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 5.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 7
6.1. application/reputon Media Type Registration . . . . . . . 8 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
6.2. Reputation Applications Registry . . . . . . . . . . . . . 9 6.1. application/reputon+json Media Type Registration . . . . . 10
7. Security Considerations . . . . . . . . . . . . . . . . . . . 11 6.2. Reputation Applications Registry . . . . . . . . . . . . . 11
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 7. Security Considerations . . . . . . . . . . . . . . . . . . . 13
8.1. Normative References . . . . . . . . . . . . . . . . . . . 11 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13
8.2. Informative References . . . . . . . . . . . . . . . . . . 12 8.1. Normative References . . . . . . . . . . . . . . . . . . . 13
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 12 8.2. Informative References . . . . . . . . . . . . . . . . . . 14
Appendix B. Public Discussion . . . . . . . . . . . . . . . . . . 12 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 14
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12 Appendix B. Public Discussion . . . . . . . . . . . . . . . . . . 14
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 15
1. Introduction 1. Introduction
This document defines a media type for use when answering a This document defines a media type for use when answering a
reputation query using the "long form" query defined in reputation query using the "long form" query defined in
[I-D.REPUTE-QUERY-HTTP], which uses [HTTP]. [I-D.REPUTE-QUERY-HTTP], which uses [HTTP].
Also included is the specification for an IANA registry to contain Also included is the specification for an IANA registry to contain
definitions and symbolic names for known reputation applications and definitions and symbolic names for known reputation applications and
corresponding response sets. corresponding response sets.
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 format selected for the representaton of a reputon is Javascript The meta-format selected for the representaton of a reputon is
Object Notation (JSON), defined in [JSON]. Accordingly, a new media Javascript Object Notation (JSON), defined in [JSON]. Accordingly, a
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, "subject", which defines the type has one optional parameter, "context", which names the semantic
specific reputation application in whose context the query is made context (i.e., the specific sphere of reputation evaluation, or
and the response returned. If the parameter is absent, a generic application) in which context the query is made and the response
reputation query (i.e., one not associated with a specific reputation returned. If the parameter is absent, a generic reputation query
application) is assumed for which only a simple reply is allowed. (i.e., one not associated with a specific reputation application) is
assumed for 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 providing the reputation
information, typically expressed as a DNS domain name. 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 "subject" parameter on the being rated. In the absence of an "context" parameter on the
media type, the reputon can only indicate generic goodness, with media type, the reputon can only indicate generic goodness, with
the default assertion "is-good", but each application is expected the default assertion "is-good", but each application is expected
to define additional assertions. to 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.
skipping to change at page 4, line 41 skipping to change at page 4, line 43
The following are OPTIONAL for all applications, to be used in The following are OPTIONAL for all applications, to be used in
contexts where they are appropriate: contexts where they are appropriate:
confidence: the level of certainty the reputation provider has that confidence: the level of certainty the reputation provider has that
the value presented is appropriate, expressed as a floating-point the value presented is appropriate, expressed as a floating-point
number between 0.0 and 1.0 inclusive. number between 0.0 and 1.0 inclusive.
rater-authenticity: The level of confidence that the rated identity rater-authenticity: The level of confidence that the rated identity
is genuine, expressed as a floating-point number between 0.0 and is genuine, expressed as a floating-point number between 0.0 and
1.0 inclusive. 1.0 inclusive. "Genuine" here means the identity being rated is
legitimately associated with the real-world entity it represents.
For example, a rater might claim a value of 1.0 here if it is
certain the rated identity "example.com" is associated with The
Example Widget Co, Inc., because it is used in a context where
both authentication and authorization on the use of that domain
name are assured; the binding between the rated identity and the
real-world identity is well established.
sample-size: The number of data points used to compute that score, sample-size: The number of data points used to compute that score,
possibly an approximation. Expressed as an unsigned 64-bit possibly an approximation. Expressed as an unsigned 64-bit
integer. Consumers can assume that the count refers to distinct integer. Consumers can assume that the count refers to distinct
data points rather than a count of aggregations (for example, data points rather than a count of aggregations (for example,
individual votes rather than aggregated vote counts) unless it is individual votes rather than aggregated vote counts) unless it is
specified out-of-band that some other interpretation is more specified out-of-band that some other interpretation is more
appropriate. The units are deliberately not normatively appropriate. The units are deliberately not normatively
specified, since not all reputation service providers will collect specified, since not all reputation service providers will collect
data the same way. data the same way.
updated: A timestamp indicating when this value was generated. generated: A timestamp indicating when this value was generated.
Expressed as the number of seconds since January 1, 1970 00:00 Expressed as the number of seconds since January 1, 1970 00:00
UTC. UTC.
A particular application that registers itself with IANA MAY define A particular application that registers itself with IANA (per
additional application-specific attribute/value pairs beyond these Section 6.2, below) MAY define additional application-specific
standard ones. attribute/value pairs beyond these standard ones.
An application service provider might operate an enhanced service, An application service provider might operate with an enhanced form
which might in turn prompt development and reporting of specialized of common services, which might in turn prompt development and
reputation information. The details of the enhancements and reporting of specialized reputation information. The details of the
specialized information are beyond the scope of this document, except enhancements and specialized information are beyond the scope of this
that the underlying JSON syntax is extensible for encoding such document, except that the underlying JSON syntax is extensible for
provider-specific information. encoding such provider-specific information.
4. Scores 4. Scores
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.
skipping to change at page 6, line 5 skipping to change at page 6, line 15
A reputon expressed in JSON consists of an object that itself A reputon expressed in JSON consists of an object that itself
contains zero or more objects whose names are "reputon". Each contains zero or more objects whose names are "reputon". Each
reputon object is a set of key-value pairs, where the keys are the reputon object is a set of key-value pairs, where the keys are the
names of particular attributes that comprise a reputon (as listed names of particular attributes that comprise a reputon (as listed
above, or as provided with specific applications), and values are the above, or as provided with specific applications), and values are the
content associated with those keys. The set of keys that make up a content associated with those keys. The set of keys that make up a
reputon within a given application are known as that application's reputon within a given application are known as that application's
"response set". "response set".
An empty reputon can be interpreted by the recipient as An empty reputon is an acknowledgement by the server that the request
acknowledgement of the request by the server, and a positive has been received and serves as a positive indication that the server
indication that the server does not have the information requested. does not have the information requested. This is semantically
This is semantically equivalent to returning a reputon with a equivalent to returning a reputon with a "sample-size" of zero.
"sample-size" of zero.
5.1.1. Formal Definition
Using [ABNF], the syntax of a reputon is:
reputon = "{" [ reputon-object
*(value-separator reputon-object) ] "}"
reputon-object = "reputon" name-separator response-set
response-set = "{" reputon-element
*(value-separator reputon-element) "}
reputon-element = rater-value / assertion-value / rated-value
/ rating-value / conf-value / auth-value
/ sample-value / gen-value / ext-value
; these can appear in any order
rater-value = %x22 "rater" %x22 name-separator string
assertion-value = %x22 "assertion" %x22 name-separator string
rated-value = %x22 "rated" %x22 name-separator string
rating-value = %x22 "rating" %x22 name-separator number
; "number" MUST be between 0.0 and 1.0 inclusive
conf-value = %x22 "confidence" %x22 name-separator number
; "number" MUST be between 0.0 and 1.0 inclusive
auth-value = %x22 "rater-authenticity" %x22 name-separator number
; "number" MUST be between 0.0 and 1.0 inclusive
sample-value = %x22 "sample-size" %x22 name-separator int
; "int" MUST NOT be negative
gen-value = %x22 "generated" %x22 name-separator int
; "int" MUST NOT be negative
ext-value = member
; specific syntax is specified in specific application
; registrations
The tokens "value-separator", "name-separator", "string", "int", and
"member" are defined in [JSON].
5.2. Examples 5.2. Examples
The following simple example: The following simple example:
Content-type: application/reputon+json Content-type: application/reputon+json
{ {
"reputon": "reputon":
{ {
skipping to change at page 6, line 39 skipping to change at page 8, line 29
...indicates we are absolutely sure (1.0) that the entity ...indicates we are absolutely sure (1.0) that the entity
"RatingsRUs.example.com" consolidated 50000 data points (perhaps from "RatingsRUs.example.com" consolidated 50000 data points (perhaps from
everyone in Yankee Stadium) and concluded that Alex Rodriguez is very everyone in Yankee Stadium) and concluded that Alex Rodriguez is very
very good (0.99) at something. It doesn't tell us what he's good at, very good (0.99) at something. It doesn't tell us what he's good at,
and while it might be playing baseball, it could just as well be and while it might be playing 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; subject="baseball" Content-type: application/reputon+json; context="baseball"
{ {
"reputon": "reputon":
{ {
"rater": "baseball-reference.example.com", "rater": "baseball-reference.example.com",
"rater-authenticity": 1.0, "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; subject="baseball" Content-type: application/reputon+json; context="baseball"
{ {
"reputon": "reputon":
{ {
"rater": "baseball-reference.example.com", "rater": "baseball-reference.example.com",
"rater-authenticity": 1.0, "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, most usage of reputons is expected to make use of the In practice, it is expected that most reputons will have an "context"
"subject" parameter to target an application-specific set of parameter to target an application-specific set of assertions.
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 idenfities 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; subject="email-id" Content-Type: application/reputon+json; context="email-id"
{ {
"reputon": "reputon":
{ {
"rater": "rep.example.net", "rater": "rep.example.net",
"rater-authenticity": 0.95, "rater-authenticity": 0.95,
"assertion": "spam", "assertion": "spam",
"identity": "dkim", "identity": "dkim",
"rated": "example.com", "rated": "example.com",
"rating": 0.012, "rating": 0.012,
skipping to change at page 8, line 27 skipping to change at page 10, line 27
} }
} }
6. IANA Considerations 6. 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
registry for reputation application types. Another document in this registry for reputation application types. Another document in this
series creates an initial registry entry for the latter. series creates an initial registry entry for the latter.
6.1. application/reputon Media Type Registration 6.1. application/reputon+json Media Type Registration
This section provides the media type registration application from This section provides the media type registration application from
[MIME-REG] for processing by IANA: [MIME-REG] for processing by IANA:
To: media-types@iana.org To: media-types@iana.org
Subject: Registration of media type application/reputon Subject: Registration of media type application/reputon+json
Type name: application Type name: application
Subtype name: reputon+json Subtype name: reputon+json
Required parameters: none Required parameters: none
Optional parameters: Optional parameters:
subject: Names the reputation application in use within the context: Names the reputation application in use within the
reputon, which defines the valid assertions and any extensions reputon, which defines the valid assertions and any extensions
that may also be valid (i.e., the response set) for that that may also be valid (i.e., the response set) for that
application. These MUST be registered with IANA in the application. These MUST be registered with IANA in the
Reputation Application Registry as described in Section 6.2. Reputation Application Registry as described in Section 6.2.
Encoding considerations: "7bit" encoding is sufficient and MUST be Encoding considerations: "7bit" encoding is sufficient and MUST be
used to maintain readability when viewed by non-MIME mail readers. used to maintain readability when viewed by non-MIME mail readers.
Security considerations: See Section 7 of [this document]. Security considerations: See Section 7 of [this document].
skipping to change at page 11, line 34 skipping to change at page 13, line 34
considerations. considerations.
Discussion of the security and operational impacts of using Discussion of the security and operational impacts of using
reputation services in general can be found throughout reputation services in general can be found throughout
[I-D.REPUTE-CONSIDERATIONS]. [I-D.REPUTE-CONSIDERATIONS].
8. References 8. References
8.1. Normative References 8.1. Normative References
[ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008.
[I-D.REPUTE-MODEL] [I-D.REPUTE-MODEL]
Borenstein, N. and M. Kucherawy, "A Model for Reputation Borenstein, N. and M. Kucherawy, "A Model for Reputation
Interchange", draft-ietf-repute-model (work in progress), Interchange", draft-ietf-repute-model (work in progress),
November 2012. November 2012.
[I-D.REPUTE-QUERY-HTTP] [I-D.REPUTE-QUERY-HTTP]
Borenstein, N. and M. Kucherawy, "Reputation Data Borenstein, N. and M. Kucherawy, "Reputation Data
Interchange using HTTP and XML", Interchange using HTTP and XML",
draft-ietf-repute-query-http (work in progress), draft-ietf-repute-query-http (work in progress),
November 2012. November 2012.
skipping to change at page 13, line 17 skipping to change at page 15, line 17
Nathaniel Borenstein Nathaniel Borenstein
Mimecast Mimecast
203 Crescent St., Suite 303 203 Crescent St., Suite 303
Waltham, MA 02453 Waltham, MA 02453
USA USA
Phone: +1 781 996 5340 Phone: +1 781 996 5340
Email: nsb@guppylake.com Email: nsb@guppylake.com
Murray S. Kucherawy Murray S. Kucherawy
2063 42nd Avenue 270 Upland Drive
San Francisco, CA 94116 San Francisco, CA 94127
USA USA
Email: superuser@gmail.com Email: superuser@gmail.com
 End of changes. 22 change blocks. 
53 lines changed or deleted 109 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/