idnits 2.17.1 draft-ietf-repute-media-type-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 6, 2012) is 4403 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'TBD' is mentioned on line 442, but not defined ** Obsolete normative reference: RFC 4627 (ref. 'JSON') (Obsoleted by RFC 7158, RFC 7159) -- Obsolete informational reference (is this intentional?): RFC 2616 (ref. 'HTTP') (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Obsolete informational reference (is this intentional?): RFC 5226 (ref. 'IANA-CONSIDERATIONS') (Obsoleted by RFC 8126) -- Obsolete informational reference (is this intentional?): RFC 4288 (ref. 'MIME-REG') (Obsoleted by RFC 6838) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 REPUTE Working Group N. Borenstein 3 Internet-Draft Mimecast 4 Intended status: Standards Track M. Kucherawy 5 Expires: October 8, 2012 Cloudmark 6 April 6, 2012 8 A Media Type for Reputation Interchange 9 draft-ietf-repute-media-type-02 11 Abstract 13 This document defines a media type for exchanging reputation 14 information about an arbitrary class of object. 16 Status of this Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on October 8, 2012. 33 Copyright Notice 35 Copyright (c) 2012 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 51 2. Terminology and Definitions . . . . . . . . . . . . . . . . . 3 52 2.1. Key Words . . . . . . . . . . . . . . . . . . . . . . . . 3 53 2.2. Other Definitions . . . . . . . . . . . . . . . . . . . . 3 54 3. Description . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 3.1. Reputon Keys . . . . . . . . . . . . . . . . . . . . . . . 4 56 3.2. Reputon Structure . . . . . . . . . . . . . . . . . . . . 5 57 3.3. Example Reply . . . . . . . . . . . . . . . . . . . . . . 6 58 4. Scores . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 59 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 60 5.1. application/reputon Media Type Registration . . . . . . . 8 61 5.2. Reputation Applications Registry . . . . . . . . . . . . . 9 62 6. Security Considerations . . . . . . . . . . . . . . . . . . . 11 63 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 64 7.1. Normative References . . . . . . . . . . . . . . . . . . . 11 65 7.2. Informative References . . . . . . . . . . . . . . . . . . 11 66 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 12 67 Appendix B. Public Discussion . . . . . . . . . . . . . . . . . . 12 68 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12 70 1. Introduction 72 This document defines a media type for use when answering a 73 reputation query using the "long form" query defined in 74 [I-D.REPUTE-QUERY-HTTP], which uses [HTTP]. 76 Also included is the specification for an IANA registry to contain 77 definitions and symbolic names for known reputation applications and 78 corresponding response sets. 80 2. Terminology and Definitions 82 This section defines terms used in the rest of the document. 84 2.1. Key Words 86 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 87 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 88 document are to be interpreted as described in [KEYWORDS]. 90 2.2. Other Definitions 92 Other terms of importance in this document are defined in 93 [I-D.REPUTE-MODEL], the base document in this document series. 95 3. Description 97 A "reputon" is a single independent object containing reputation 98 information. A particular query about a subject of interest will 99 receive one or more reputons in response, depending on the nature of 100 the data collected and reported by the server. 102 The format selected for the representaton of a reputon is Javascript 103 Object Notation (JSON), defined in [JSON]. Accordingly, a new media 104 type, "application/reputon+json", is defined for the JSON 105 representation of reputational data, typically in response to a 106 client making a request for such data about some subject. This media 107 type has one optional parameter, "app", which defines the specific 108 reputation application in whose context the query is made and the 109 response returned. If absent, a generic reputation query is assumed 110 for which only a simple reply is allowed. 112 The body of the media type consists of a JSON document that contains 113 the reputation information requested. A detailed description of the 114 expected structure of the reply is provided below. 116 3.1. Reputon Keys 118 The key pieces of data found in a reputon for all reputation 119 applications are defined as follows: 121 RATER: The identity of the entity providing the reputation 122 information, typically expressed as a DNS domain name. 124 ASSERTION: A keyword indicating the specific assertion or claim 125 being rated. In the absence of an "app" parameter on the media 126 type, the reputon can only indicate generic goodness, with the 127 default assertion "IS-GOOD," but each application is expected to 128 define additional ASSERTIONs. 130 RATED: The identity of the entity being rated. The nature of this 131 field is application-specific; it could be domain names, email 132 addresses, driver's license numbers, or anything that uniquely 133 identifies the entity being rated. Documents that define specific 134 reputation applications are required to define syntax and 135 semantics for this field. 137 RATING: The overall rating score for that entity, expressed as a 138 floating-point number between 0.0 and 1.0 inclusive. See 139 Section 4 for discussion. 141 The following are OPTIONAL for all applications, to be used in 142 contexts where they are appropriate: 144 CONFIDENCE: The level of confidence the reputation provider has in 145 the value presented being accurate, expressed as a floating-point 146 number between 0.0 and 1.0 inclusive. 148 RATER-AUTHENTICITY: The level of confidence in that identity being 149 genuine, expressed as a floating-point number between 0.0 and 1.0 150 inclusive. 152 SAMPLE-SIZE: The number of data points used to compute that score, 153 possibly an approximation. Expressed as an unsigned 64-bit 154 integer. The units are deliberately not specified, since not all 155 reputation service providers will collect data the same way. 156 Consumers will need to determine out-of-band the units being 157 reported and apply this value accordingly within their local 158 policies. 160 UPDATED: A timestamp indicating when this value was generated. 161 Expressed as the number of seconds since January 1, 1970 00:00 162 UTC. 164 A particular application that registers itself with IANA MAY also 165 define additional application-specific attribute/value pairs beyond 166 these standard ones. 168 Further, particular application service providers MAY provide local 169 extensions to registered applications. Syntax for these will need to 170 be specified and accommodated privately between clients and servers. 172 3.2. Reputon Structure 174 A reputon expressed in JSON consists of an object that itself 175 contains zero or more objects whose names are "reputon". Each 176 reputon object is a set of key-value pairs, where the keys are the 177 names of particular properties that comprise a reputon (as listed 178 above, or as provided with specific applications), and values are the 179 content associated with those keys. The set of keys that make up a 180 reputon within a given application are known as that application's 181 "response set". 183 Thus, the following simple example: 185 Content-type: application/reputon+json 187 { 188 "reputon": 189 { 190 "rater": "RatingsRUs.example.com", 191 "rater-authenticity": 1.0, 192 "assertion": "IS-GOOD", 193 "rated": "Alex Rodriguez", 194 "rating": 0.99, 195 "sample-size": 50000 196 } 197 } 199 ...indicates we are absolutely sure (1.0) that the entity 200 "RatingsRUs.example.com" consolidated 50000 data points (perhaps from 201 everyone in Yankee Stadium) and concluded that Alex Rodriguez is very 202 very good (0.99) at something. It doesn't tell us what he's good at, 203 and while it might be playing baseball, it could just as well be 204 paying his taxes on time. 206 A more sophisticated usage would define a baseball application with a 207 response set of specific assertions, so that this example: 209 Content-type: application/reputon+json; app="baseball" 211 { 212 "reputon": 213 { 214 "rater": "baseball-reference.example.com", 215 "rater-authenticity": 1.0, 216 "assertion": "HITS-FOR-POWER", 217 "rated": "Alex Rodriguez", 218 "rating": 0.99, 219 "sample-size": 50000 220 } 221 } 223 ...would indicate that 50000 fans polled by the entity baseball- 224 reference.example.com rate A-Rod very highly in hitting for power, 225 whereas this example: 227 Content-type: application/reputon+json; app="baseball" 229 { 230 "reputon": 231 { 232 "RATER": "baseball-reference.example.com", 233 "RATER-AUTHENTICITY": 1.0, 234 "ASSERTION": "CLUTCH-HITTER", 235 "RATED": "Alex Rodriguez", 236 "RATING": 0.4, 237 "SAMPLE-SIZE": 50000 238 } 239 } 241 ...would indicate that a similar poll indicated a somewhat weaker 242 consensus that A-Rod tends to choke in critical baseball situations. 244 In practice, most usage of reputons is expected to make use of the 245 "app" parameter to target an application-specific set of assertions. 247 3.3. Example Reply 249 The following is an example reputon generated using this schema, 250 including the media type definition line: 252 Content-Type: application/reputon+json; app="email-id" 254 { 255 "reputon": 256 { 257 "rater": "rep.example.net", 258 "rater-authenticity": 0.95, 259 "assertion": "SPAM", 260 "identity": "DKIM", 261 "rated": "example.com", 262 "rating": 0.012, 263 "sample-size": 16938213, 264 "updated": 1317795852 265 } 266 } 268 Here, reputation agent "rep.example.net" is asserting within the 269 context of the "email-id" application that "example.com" appears to 270 be associated with spam 1.2% of the time, based on just short of 17 271 million messages analyzed or reported to date. The "email-id" 272 application has declared the extension key "identity" to indicate how 273 the subject identifier was used in the observed data, establishing 274 some more specific semantics for the "rating" value. In this case, 275 the extension is used to show the identity "example.com", the subject 276 of the query, is extracted from the analyzed messages using the 277 [DKIM] "d=" parameter for messages where signatures validate. The 278 reputation agent is 95% confident of this result. (See 279 [I-D.REPUTE-EMAIL-IDENTIFIERS] for details about the registered email 280 identifiers application.) 282 4. Scores 284 The score presented as the value in the RATING parameter appears as a 285 floating point value between 0.0 and 1.0 inclusive. The intent is 286 that the definition of an assertion within an application will 287 declare what the anchor values 0.0 and 1.0 specifically mean. 288 Generally speaking, 1.0 implies full agreement with the assertion, 289 while 0.0 indicates no support for the assertion. 291 The definition will also specify the type of scale in use when 292 generating scores, to which all reputation service providers for that 293 application space must adhere. This will allow a client to change 294 which reputation service provider is being queried for a given 295 without having to learn through some out-of-band method what the new 296 provider's values mean. For example, a registration might state that 297 ratings are linear, which would mean a score of "x" is twice as 298 strong as a value of "x/2". 300 5. IANA Considerations 302 This document presents two actions for IANA, namely the creation of 303 the new media type "application/reputon+json" and the creation of a 304 registry for reputation application types. Another document in this 305 series creates an initial registry entry for the latter. 307 5.1. application/reputon Media Type Registration 309 This section provides the media type registration application from 310 [MIME-REG] for processing by IANA: 312 To: ietf-types@iana.org 314 Subject: Registration of media type application/reputon 316 Type name: application 318 Subtype name: reputon+json 320 Required parameters: none 322 Optional parameters: 324 app: Names the reputation application in use within the reputon, 325 which defines the valid assertions and any extensions that may 326 also be valid (i.e., the response set) for that application. 327 These MUST be registered with IANA. 329 Encoding considerations: "7bit" encoding is sufficient and MUST be 330 used to maintain readability when viewed by non-MIME mail readers. 332 Security considerations: See Section 6 of [this document]. 334 Interoperability considerations: Implementers MUST ignore any "app" 335 values, attribute/value pairs, or response set items they do not 336 support. 338 Published specification: [this document] 340 Applications that use this media type: Any application that wishes 341 to query a service that provides reputation data using the "long 342 form" defined in [I-D.REPUTE-QUERY-HTTP]. The example application 343 is one that provides reputation expressions about DNS domain names 344 found in email messages. 346 Additional information: The value of the "app" parameter MUST also 347 be registered with IANA. 349 Person and email address to contact for further information: 351 Nathaniel Borenstein 353 Murray S. Kucherawy 355 Intended usage: COMMON 357 Author: 359 Nathaniel Borenstein 361 Murray S. Kucherawy 363 Change controller: IESG 365 5.2. Reputation Applications Registry 367 IANA is requested to create the "Reputation Applications" registry. 368 This registry will contain names of applications used with the 369 application/reputon+json media type (and other media types that carry 370 reputons), as defined by this document. 372 New registrations or updates MUST be published in accordance with the 373 "Specification Required" guidelines as described in 374 [IANA-CONSIDERATIONS]. 376 New registrations and updates MUST contain the following information: 378 1. Name of the application being registered or updated 380 2. Short description of the application (i.e., the class of entity 381 about which it reports reputation data) 383 3. The document in which the application is defined 385 4. New or updated status, which MUST be one of: 387 current: The application is in current use 389 deprecated: The application is in current use but its use is 390 discouraged 392 historic: The application is no longer in current use 394 5. A description of the subject of a query within this reputation, 395 and a legal syntax for the same 397 6. An optional table of query parameters that are specific to this 398 application; each table entry must include: 400 Name: Name of the query parameter 402 Status: (as above) 404 Description: A short description of the purpose of this 405 parameter 407 Syntax: A reference to a description of valid syntax for the 408 parameter's value 410 Required: "yes" if the parameter is mandatory, "no" otherwise 412 A document creating a reputation application MUST include: 414 1. A list of one or more assertions registered within this 415 application; each table entry must include: 417 Name: Name of the assertion 419 Description: A short description of the assertion, with specific 420 meanings for values of 0.0 and 1.0 422 Scale: A short description of the scale used in computing the 423 value (see Section 4 of this document) 425 A document creating a reputation application MAY include: 427 1. A list of one or more response set extension keys for use within 428 this application; each table entry must include: 430 Name: Name of the extension key 432 Description: A short description of the key's intended meaning 434 Syntax: A description of valid values that can appear associated 435 with the key 437 6. Security Considerations 439 This section describes security considerations introduced by the 440 media type and content syntax defined here. 442 [TBD] 444 7. References 446 7.1. Normative References 448 [I-D.REPUTE-MODEL] 449 Borenstein, N. and M. Kucherawy, "A Model for Reputation 450 Interchange", draft-ietf-repute-model (work in progress), 451 June 2011. 453 [I-D.REPUTE-QUERY-HTTP] 454 Borenstein, N. and M. Kucherawy, "Reputation Data 455 Interchange using HTTP and XML", 456 draft-ietf-repute-query-http (work in progress), 457 November 2011. 459 [JSON] Crockford, D., "The application/json Media Type for 460 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 462 [KEYWORDS] 463 Bradner, S., "Key words for use in RFCs to Indicate 464 Requirement Levels", BCP 14, RFC 2119, March 1997. 466 7.2. Informative References 468 [DKIM] Crocker, D., Ed., Hansen, T., Ed., and M. Kucherawy, Ed., 469 "DomainKeys Identified Mail (DKIM) Signatures", RFC 6376, 470 September 2011. 472 [HTTP] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 473 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 474 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 476 [I-D.REPUTE-EMAIL-IDENTIFIERS] 477 Borenstein, N. and M. Kucherawy, "A Reputation Vocabulary 478 for Email Identifiers", 479 draft-ietf-repute-email-identifiers (work in progress), 480 November 2011. 482 [IANA-CONSIDERATIONS] 483 Narten, T. and H. Alvestrand, "Guidelines for Writing an 484 IANA Considerations Section in RFCs", RFC 5226, May 2008. 486 [MIME-REG] 487 Freed, N. and J. Klensin, "Media Type Specifications and 488 Registration Procedures", RFC 4288, December 2005. 490 Appendix A. Acknowledgments 492 The authors wish to acknowledge the contributions of the following to 493 this specification: Frank Ellermann, Tony Hansen, Jeff Hodges, John 494 Levine, David F. Skoll, and Mykyta Yevstifeyev. 496 Appendix B. Public Discussion 498 Public discussion of this suite of documents takes place on the 499 domainrep@ietf.org mailing list. See 500 https://www.ietf.org/mailman/listinfo/domainrep. 502 Authors' Addresses 504 Nathaniel Borenstein 505 Mimecast 506 203 Crescent St., Suite 303 507 Waltham, MA 02453 508 USA 510 Phone: +1 781 996 5340 511 Email: nsb@guppylake.com 513 Murray S. Kucherawy 514 Cloudmark 515 128 King St., 2nd Floor 516 San Francisco, CA 94107 517 USA 519 Phone: +1 415 946 3800 520 Email: msk@cloudmark.com