draft-ietf-repute-media-type-07.txt   draft-ietf-repute-media-type-08.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: November 20, 2013 May 19, 2013 Expires: December 8, 2013 June 6, 2013
A Media Type for Reputation Interchange A Media Type for Reputation Interchange
draft-ietf-repute-media-type-07 draft-ietf-repute-media-type-08
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 November 20, 2013. This Internet-Draft will expire on December 8, 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 14 skipping to change at page 2, line 14
Table of Contents Table of Contents
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. Ratings . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
5. Reputon Structure . . . . . . . . . . . . . . . . . . . . . . 5 5. Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
5.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 6 6. Reputon Structure . . . . . . . . . . . . . . . . . . . . . . 6
5.1.1. Formal Definition . . . . . . . . . . . . . . . . . . 6 6.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 6
5.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 7 6.1.1. Formal Definition . . . . . . . . . . . . . . . . . . 6
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 6.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 8
6.1. application/reputon+json Media Type Registration . . . . . 10 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
6.2. Reputation Applications Registry . . . . . . . . . . . . . 11 7.1. application/reputon+json Media Type Registration . . . . . 10
7. Security Considerations . . . . . . . . . . . . . . . . . . . 13 7.2. Reputation Applications Registry . . . . . . . . . . . . . 11
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 8. Security Considerations . . . . . . . . . . . . . . . . . . . 13
8.1. Normative References . . . . . . . . . . . . . . . . . . . 13 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13
8.2. Informative References . . . . . . . . . . . . . . . . . . 14 9.1. Normative References . . . . . . . . . . . . . . . . . . . 13
9.2. Informative References . . . . . . . . . . . . . . . . . . 14
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 14 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 14
Appendix B. Public Discussion . . . . . . . . . . . . . . . . . . 14 Appendix B. Public Discussion . . . . . . . . . . . . . . . . . . 14
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 15 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 via the query method described 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.
2. Terminology and Definitions 2. Terminology and Definitions
This section defines terms used in the rest of the document. This section defines terms used in the rest of the document.
skipping to change at page 5, line 19 skipping to change at page 5, line 19
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.
generated: 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.
expires: A timestamp indicating a time beyond which the score
reported is likely not to be valid. Expressed as the number of
seconds since January 1, 1970 00:00 UTC. See Section 5 for
discussion.
A particular application that registers itself with IANA (per A particular application that registers itself with IANA (per
Section 6.2, below) MAY define additional application-specific Section 7.2, below) can define additional application-specific
attribute/value pairs beyond these standard ones. attribute/value pairs beyond these standard ones.
An application service provider might operate with an enhanced form An application service provider might operate with an enhanced form
of common services, which might in turn prompt development and of common services, which might in turn prompt development and
reporting of specialized reputation information. The details of the reporting of specialized reputation information. The details of the
enhancements and specialized information are beyond the scope of this enhancements and specialized information are beyond the scope of this
document, except that the underlying JSON syntax is extensible for document, except that the underlying JSON syntax is extensible for
encoding such provider-specific information. encoding such provider-specific information.
4. Scores 4. Ratings
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 for a given
without having to learn through some out-of-band method what the new without having to learn through some out-of-band method what the new
provider's values mean. For example, a registration might state that provider's values mean. For example, a registration might state that
ratings are linear, which would mean a score of "x" is twice as ratings are linear, which would mean a score of "x" is twice as
strong as a value of "x/2". strong as a value of "x/2". It also allows easier aggregation of
ratings collected from multiple reputation service providers.
5. Reputon Structure 5. Caching
5.1. Syntax
A reputon can contain an "expires" field indicating a timestamp after
which the client SHOULD NOT use the rating it contains, and SHOULD
issue a new query.
This specificaiton does not mandate any caching of ratings on the
part of the client, but there are obvious operational benefits to
doing so. In the context of reputation, a cached (and hence, stale)
rating can cause desirable traffic to be identified as undesirable,
or vice-versa.
Reputation data is typically most volatile when the subject of the
reputation is young. Accordingly, if a service chooses to include
expiration timestamps as part a reply, these values SHOULD be lower
for subjects about which little data has been collected.
6. Reputon Structure
6.1. Syntax
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 is an acknowledgement by the server that the request An empty reputon is an acknowledgement by the server that the request
has been received and serves as a positive indication that the server has been received and serves as a positive indication that the server
does not have the information requested. This is semantically does not have the information requested. This is semantically
equivalent to returning a reputon with a "sample-size" of zero. equivalent to returning a reputon with a "sample-size" of zero.
5.1.1. Formal Definition 6.1.1. Formal Definition
Using [ABNF], the syntax of a reputon is: Using [ABNF], the syntax of a reputon is:
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 / auth-value
/ sample-value / gen-value / ext-value / sample-value / gen-value / expire-value
; these can appear in any order / ext-value
; these can appear in any order, but MUST appear at most
; 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
skipping to change at page 7, line 39 skipping to change at page 7, line 41
auth-value = %x22 "rater-authenticity" %x22 name-separator number auth-value = %x22 "rater-authenticity" %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
; "int" MUST NOT be negative
ext-value = member ext-value = member
; specific syntax is specified in specific application ; specific syntax is specified in specific 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].
5.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, "rater-authenticity": 1.0,
skipping to change at page 10, line 20 skipping to change at page 10, line 20
"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,
"sample-size": 16938213, "sample-size": 16938213,
"updated": 1317795852 "updated": 1317795852
} }
} }
6. 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
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+json Media Type Registration 7.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+json 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:
context: 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 are registered with IANA in the Reputation
Reputation Application Registry as described in Section 6.2. Application Registry as described in Section 7.2.
Encoding considerations: "7bit" encoding is sufficient and MUST be Encoding considerations: "7bit" encoding is sufficient and is used
used to maintain readability when viewed by non-MIME mail readers. to maintain readability when viewed by non-MIME mail readers.
Security considerations: See Section 7 of [this document]. Security considerations: See Section 8 of [this document].
Interoperability considerations: Implementers MUST ignore any "app" Interoperability considerations: Implementers may encounter "app"
values, attribute/value pairs, or response set items they do not values, attribute/value pairs, or response set items that they do
support. not support, which are to be ignored.
Published specification: [this document] Published specification: [this document]
Applications that use this media type: Any application that wishes Applications that use this media type: Any application that wishes
to query a service that provides reputation data using the "long to query a service that provides reputation data using the "long
form" defined in [I-D.REPUTE-QUERY-HTTP]. The example application form" defined in [I-D.REPUTE-QUERY-HTTP]. The example application
is one that provides reputation expressions about DNS domain names is one that provides reputation expressions about DNS domain names
found in email messages. found in email messages.
Additional information: The value of the "app" parameter MUST also Additional information: The value of the "app" parameter is
be registered with IANA. registered with IANA.
Person and email address to contact for further information: Person and email address to contact for further information:
Nathaniel Borenstein <nps@guppylake.com> Nathaniel Borenstein <nps@guppylake.com>
Murray S. Kucherawy <msk@cloudmark.com> Murray S. Kucherawy <msk@cloudmark.com>
Intended usage: COMMON Intended usage: COMMON
Author: Author:
Nathaniel Borenstein Nathaniel Borenstein
Murray S. Kucherawy Murray S. Kucherawy
Change controller: IESG Change controller: IESG
6.2. Reputation Applications Registry 7.2. Reputation Applications Registry
IANA is requested to create the "Reputation Applications" registry. IANA is requested to create the "Reputation Applications" registry.
This registry will contain names of applications used with the This registry will contain names of applications used with the
application/reputon+json media type (and other media types that carry application/reputon+json media type (and other media types that carry
reputons), as defined by this document. reputons), as defined by this document.
New registrations or updates MUST be published in accordance with the New registrations or updates are published in accordance with the
"Specification Required" guidelines as described in "Specification Required" guidelines as described in
[IANA-CONSIDERATIONS]. [IANA-CONSIDERATIONS].
New registrations and updates are to contain the following New registrations and updates are to contain the following
information: information:
1. Name of the application being registered or updated 1. Name of the application being registered or updated
2. Short description of the application (i.e., the class of entity 2. Short description of the application (i.e., the class of entity
about which it reports reputation data) about which it reports reputation data)
skipping to change at page 13, line 20 skipping to change at page 13, line 20
Description: A short description of the key's intended meaning Description: A short description of the key's intended meaning
Syntax: A description of valid values that can appear associated Syntax: A description of valid values that can appear associated
with the key with the key
The names of attributes registered should be prefixed by the name of The names of attributes registered should be prefixed by the name of
the application itself (e.g., the "foo" application registering a the application itself (e.g., the "foo" application registering a
"bar" attribute should call it "foo-bar") to avoid namespace "bar" attribute should call it "foo-bar") to avoid namespace
collisions. collisions.
7. Security Considerations 8. Security Considerations
This document is primarily an IANA action registering a media type. This document is primarily an IANA action registering a media type.
It does not describe a new protocol that might introduce security It does not describe a new protocol that might introduce security
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 9. References
8.1. Normative References 9.1. Normative References
[ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008. 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]
skipping to change at page 14, line 9 skipping to change at page 14, line 9
draft-ietf-repute-query-http (work in progress), draft-ietf-repute-query-http (work in progress),
November 2012. November 2012.
[JSON] Crockford, D., "The application/json Media Type for [JSON] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006. JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[KEYWORDS] [KEYWORDS]
Bradner, S., "Key words for use in RFCs to Indicate Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
8.2. Informative References 9.2. Informative References
[DKIM] Crocker, D., Ed., Hansen, T., Ed., and M. Kucherawy, Ed., [DKIM] Crocker, D., Ed., Hansen, T., Ed., and M. Kucherawy, Ed.,
"DomainKeys Identified Mail (DKIM) Signatures", RFC 6376, "DomainKeys Identified Mail (DKIM) Signatures", RFC 6376,
September 2011. September 2011.
[HTTP] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., [HTTP] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[I-D.REPUTE-CONSIDERATIONS] [I-D.REPUTE-CONSIDERATIONS]
skipping to change at page 14, line 41 skipping to change at page 14, line 41
Narten, T. and H. Alvestrand, "Guidelines for Writing an Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", RFC 5226, May 2008. IANA Considerations Section in RFCs", RFC 5226, May 2008.
[MIME-REG] [MIME-REG]
Freed, N. and J. Klensin, "Media Type Specifications and Freed, N. and J. Klensin, "Media Type Specifications and
Registration Procedures", RFC 4288, December 2005. Registration Procedures", RFC 4288, December 2005.
Appendix A. Acknowledgments Appendix A. Acknowledgments
The authors wish to acknowledge the contributions of the following to The authors wish to acknowledge the contributions of the following to
this specification: Frank Ellermann, Tony Hansen, Jeff Hodges, John this specification: Frank Ellermann, Tony Hansen, Jeff Hodges, Simon
Levine, David F. Skoll, and Mykyta Yevstifeyev. Hunt, John Levine, David F. Skoll, and Mykyta Yevstifeyev.
Appendix B. Public Discussion Appendix B. Public Discussion
Public discussion of this suite of documents takes place on the Public discussion of this suite of documents takes place on the
domainrep@ietf.org mailing list. See domainrep@ietf.org mailing list. See
https://www.ietf.org/mailman/listinfo/domainrep. https://www.ietf.org/mailman/listinfo/domainrep.
Authors' Addresses Authors' Addresses
Nathaniel Borenstein Nathaniel Borenstein
 End of changes. 28 change blocks. 
45 lines changed or deleted 75 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/