idnits 2.17.1 draft-ietf-repute-media-type-04.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 (November 13, 2012) is 4153 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) ** 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) -- Duplicate reference: draft-ietf-repute-model, mentioned in 'I-D.REPUTE-CONSIDERATIONS', was also mentioned in 'I-D.REPUTE-MODEL'. -- 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 (~~), 1 warning (==), 5 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: May 17, 2013 November 13, 2012 7 A Media Type for Reputation Interchange 8 draft-ietf-repute-media-type-04 10 Abstract 12 This document defines a media type for exchanging reputation 13 information about an arbitrary class of object. 15 Status of this Memo 17 This Internet-Draft is submitted in full conformance with the 18 provisions of BCP 78 and BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF). Note that other groups may also distribute 22 working documents as Internet-Drafts. The list of current Internet- 23 Drafts is at http://datatracker.ietf.org/drafts/current/. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 This Internet-Draft will expire on May 17, 2013. 32 Copyright Notice 34 Copyright (c) 2012 IETF Trust and the persons identified as the 35 document authors. All rights reserved. 37 This document is subject to BCP 78 and the IETF Trust's Legal 38 Provisions Relating to IETF Documents 39 (http://trustee.ietf.org/license-info) in effect on the date of 40 publication of this document. Please review these documents 41 carefully, as they describe your rights and restrictions with respect 42 to this document. Code Components extracted from this document must 43 include Simplified BSD License text as described in Section 4.e of 44 the Trust Legal Provisions and are provided without warranty as 45 described in the Simplified BSD License. 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 50 2. Terminology and Definitions . . . . . . . . . . . . . . . . . 3 51 2.1. Key Words . . . . . . . . . . . . . . . . . . . . . . . . 3 52 2.2. Other Definitions . . . . . . . . . . . . . . . . . . . . 3 53 3. Description . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 3.1. Reputon Keys . . . . . . . . . . . . . . . . . . . . . . . 4 55 3.2. Reputon Structure . . . . . . . . . . . . . . . . . . . . 5 56 3.3. Example Reply . . . . . . . . . . . . . . . . . . . . . . 6 57 4. Scores . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 58 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 59 5.1. application/reputon Media Type Registration . . . . . . . 8 60 5.2. Reputation Applications Registry . . . . . . . . . . . . . 9 61 6. Security Considerations . . . . . . . . . . . . . . . . . . . 10 62 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 63 7.1. Normative References . . . . . . . . . . . . . . . . . . . 11 64 7.2. Informative References . . . . . . . . . . . . . . . . . . 11 65 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 12 66 Appendix B. Public Discussion . . . . . . . . . . . . . . . . . . 12 67 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12 69 1. Introduction 71 This document defines a media type for use when answering a 72 reputation query using the "long form" query defined in 73 [I-D.REPUTE-QUERY-HTTP], which uses [HTTP]. 75 Also included is the specification for an IANA registry to contain 76 definitions and symbolic names for known reputation applications and 77 corresponding response sets. 79 2. Terminology and Definitions 81 This section defines terms used in the rest of the document. 83 2.1. Key Words 85 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 86 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 87 document are to be interpreted as described in [KEYWORDS]. 89 2.2. Other Definitions 91 Other terms of importance in this document are defined in 92 [I-D.REPUTE-MODEL], the base document in this document series. 94 3. Description 96 A "reputon" is a single independent object containing reputation 97 information. A particular query about a subject of interest will 98 receive one or more reputons in response, depending on the nature of 99 the data collected and reported by the server. 101 The format selected for the representaton of a reputon is Javascript 102 Object Notation (JSON), defined in [JSON]. Accordingly, a new media 103 type, "application/reputon+json", is defined for the JSON 104 representation of reputational data, typically in response to a 105 client making a request for such data about some subject. This media 106 type has one optional parameter, "app", which defines the specific 107 reputation application in whose context the query is made and the 108 response returned. If absent, a generic reputation query is assumed 109 for which only a simple reply is allowed. 111 The body of the media type consists of a JSON document that contains 112 the reputation information requested. A detailed description of the 113 expected structure of the reply is provided below. 115 3.1. Reputon Keys 117 The key pieces of data found in a reputon for all reputation 118 applications are defined as follows: 120 RATER: The identity of the entity providing the reputation 121 information, typically expressed as a DNS domain name. 123 ASSERTION: A keyword indicating the specific assertion or claim 124 being rated. In the absence of an "app" parameter on the media 125 type, the reputon can only indicate generic goodness, with the 126 default assertion "IS-GOOD," but each application is expected to 127 define additional ASSERTIONs. 129 RATED: The identity of the entity being rated. The nature of this 130 field is application-specific; it could be domain names, email 131 addresses, driver's license numbers, or anything that uniquely 132 identifies the entity being rated. Documents that define specific 133 reputation applications are required to define syntax and 134 semantics for this field. 136 RATING: The overall rating score for that entity, expressed as a 137 floating-point number between 0.0 and 1.0 inclusive. See 138 Section 4 for discussion. 140 The following are OPTIONAL for all applications, to be used in 141 contexts where they are appropriate: 143 CONFIDENCE: The level of confidence the reputation provider has in 144 the value presented being accurate, expressed as a floating-point 145 number between 0.0 and 1.0 inclusive. 147 RATER-AUTHENTICITY: The level of confidence in that identity being 148 genuine, expressed as a floating-point number between 0.0 and 1.0 149 inclusive. 151 SAMPLE-SIZE: The number of data points used to compute that score, 152 possibly an approximation. Expressed as an unsigned 64-bit 153 integer. The units are deliberately not specified, since not all 154 reputation service providers will collect data the same way. 155 Consumers will need to determine out-of-band the units being 156 reported and apply this value accordingly within their local 157 policies. 159 UPDATED: A timestamp indicating when this value was generated. 160 Expressed as the number of seconds since January 1, 1970 00:00 161 UTC. 163 A particular application that registers itself with IANA MAY also 164 define additional application-specific attribute/value pairs beyond 165 these standard ones. 167 Further, particular application service providers MAY provide local 168 extensions to registered applications. Syntax for these will need to 169 be specified and accommodated privately between clients and servers. 171 3.2. Reputon Structure 173 A reputon expressed in JSON consists of an object that itself 174 contains zero or more objects whose names are "reputon". Each 175 reputon object is a set of key-value pairs, where the keys are the 176 names of particular properties that comprise a reputon (as listed 177 above, or as provided with specific applications), and values are the 178 content associated with those keys. The set of keys that make up a 179 reputon within a given application are known as that application's 180 "response set". 182 Thus, the following simple example: 184 Content-type: application/reputon+json 186 { 187 "reputon": 188 { 189 "rater": "RatingsRUs.example.com", 190 "rater-authenticity": 1.0, 191 "assertion": "IS-GOOD", 192 "rated": "Alex Rodriguez", 193 "rating": 0.99, 194 "sample-size": 50000 195 } 196 } 198 ...indicates we are absolutely sure (1.0) that the entity 199 "RatingsRUs.example.com" consolidated 50000 data points (perhaps from 200 everyone in Yankee Stadium) and concluded that Alex Rodriguez is very 201 very good (0.99) at something. It doesn't tell us what he's good at, 202 and while it might be playing baseball, it could just as well be 203 paying his taxes on time. 205 A more sophisticated usage would define a baseball application with a 206 response set of specific assertions, so that this example: 208 Content-type: application/reputon+json; app="baseball" 210 { 211 "reputon": 212 { 213 "rater": "baseball-reference.example.com", 214 "rater-authenticity": 1.0, 215 "assertion": "HITS-FOR-POWER", 216 "rated": "Alex Rodriguez", 217 "rating": 0.99, 218 "sample-size": 50000 219 } 220 } 222 ...would indicate that 50000 fans polled by the entity baseball- 223 reference.example.com rate A-Rod very highly in hitting for power, 224 whereas this example: 226 Content-type: application/reputon+json; app="baseball" 228 { 229 "reputon": 230 { 231 "RATER": "baseball-reference.example.com", 232 "RATER-AUTHENTICITY": 1.0, 233 "ASSERTION": "CLUTCH-HITTER", 234 "RATED": "Alex Rodriguez", 235 "RATING": 0.4, 236 "SAMPLE-SIZE": 50000 237 } 238 } 240 ...would indicate that a similar poll indicated a somewhat weaker 241 consensus that A-Rod tends to choke in critical baseball situations. 243 In practice, most usage of reputons is expected to make use of the 244 "app" parameter to target an application-specific set of assertions. 246 3.3. Example Reply 248 The following is an example reputon generated using this schema, 249 including the media type definition line: 251 Content-Type: application/reputon+json; app="email-id" 253 { 254 "reputon": 255 { 256 "rater": "rep.example.net", 257 "rater-authenticity": 0.95, 258 "assertion": "SPAM", 259 "identity": "DKIM", 260 "rated": "example.com", 261 "rating": 0.012, 262 "sample-size": 16938213, 263 "updated": 1317795852 264 } 265 } 267 Here, reputation agent "rep.example.net" is asserting within the 268 context of the "email-id" application that "example.com" appears to 269 be associated with spam 1.2% of the time, based on just short of 17 270 million messages analyzed or reported to date. The "email-id" 271 application has declared the extension key "identity" to indicate how 272 the subject identifier was used in the observed data, establishing 273 some more specific semantics for the "rating" value. In this case, 274 the extension is used to show the identity "example.com", the subject 275 of the query, is extracted from the analyzed messages using the 276 [DKIM] "d=" parameter for messages where signatures validate. The 277 reputation agent is 95% confident of this result. (See 278 [I-D.REPUTE-EMAIL-IDENTIFIERS] for details about the registered email 279 identifiers application.) 281 4. Scores 283 The score presented as the value in the RATING parameter appears as a 284 floating point value between 0.0 and 1.0 inclusive. The intent is 285 that the definition of an assertion within an application will 286 declare what the anchor values 0.0 and 1.0 specifically mean. 287 Generally speaking, 1.0 implies full agreement with the assertion, 288 while 0.0 indicates no support for the assertion. 290 The definition will also specify the type of scale in use when 291 generating scores, to which all reputation service providers for that 292 application space must adhere. This will allow a client to change 293 which reputation service provider is being queried for a given 294 without having to learn through some out-of-band method what the new 295 provider's values mean. For example, a registration might state that 296 ratings are linear, which would mean a score of "x" is twice as 297 strong as a value of "x/2". 299 5. IANA Considerations 301 This document presents two actions for IANA, namely the creation of 302 the new media type "application/reputon+json" and the creation of a 303 registry for reputation application types. Another document in this 304 series creates an initial registry entry for the latter. 306 5.1. application/reputon Media Type Registration 308 This section provides the media type registration application from 309 [MIME-REG] for processing by IANA: 311 To: media-types@iana.org 313 Subject: Registration of media type application/reputon 315 Type name: application 317 Subtype name: reputon+json 319 Required parameters: none 321 Optional parameters: 323 app: Names the reputation application in use within the reputon, 324 which defines the valid assertions and any extensions that may 325 also be valid (i.e., the response set) for that application. 326 These MUST be registered with IANA. 328 Encoding considerations: "7bit" encoding is sufficient and MUST be 329 used to maintain readability when viewed by non-MIME mail readers. 331 Security considerations: See Section 6 of [this document]. 333 Interoperability considerations: Implementers MUST ignore any "app" 334 values, attribute/value pairs, or response set items they do not 335 support. 337 Published specification: [this document] 339 Applications that use this media type: Any application that wishes 340 to query a service that provides reputation data using the "long 341 form" defined in [I-D.REPUTE-QUERY-HTTP]. The example application 342 is one that provides reputation expressions about DNS domain names 343 found in email messages. 345 Additional information: The value of the "app" parameter MUST also 346 be registered with IANA. 348 Person and email address to contact for further information: 350 Nathaniel Borenstein 352 Murray S. Kucherawy 354 Intended usage: COMMON 356 Author: 358 Nathaniel Borenstein 360 Murray S. Kucherawy 362 Change controller: IESG 364 5.2. Reputation Applications Registry 366 IANA is requested to create the "Reputation Applications" registry. 367 This registry will contain names of applications used with the 368 application/reputon+json media type (and other media types that carry 369 reputons), as defined by this document. 371 New registrations or updates MUST be published in accordance with the 372 "Specification Required" guidelines as described in 373 [IANA-CONSIDERATIONS]. 375 New registrations and updates are to contain the following 376 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 is to 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 7. A list of one or more assertions registered within this 413 application; each table entry is to include: 415 Name: Name of the assertion 417 Description: A short description of the assertion, with specific 418 meanings for values of 0.0 and 1.0 420 Scale: A short description of the scale used in computing the 421 value (see Section 4 of this document) 423 8. An optional list of one or more response set extension keys for 424 use within this application; each table entry is to include: 426 Name: Name of the extension key 428 Description: A short description of the key's intended meaning 430 Syntax: A description of valid values that can appear associated 431 with the key 433 6. Security Considerations 435 This document is primarily an IANA action registering a media type. 436 It does not describe a new protocol that might introduce security 437 considerations. 439 Discussion of the security and operational impacts of using 440 reputation services in general can be found throughout 441 [I-D.REPUTE-CONSIDERATIONS]. 443 7. References 445 7.1. Normative References 447 [I-D.REPUTE-MODEL] 448 Borenstein, N. and M. Kucherawy, "A Model for Reputation 449 Interchange", draft-ietf-repute-model (work in progress), 450 November 2012. 452 [I-D.REPUTE-QUERY-HTTP] 453 Borenstein, N. and M. Kucherawy, "Reputation Data 454 Interchange using HTTP and XML", 455 draft-ietf-repute-query-http (work in progress), 456 November 2012. 458 [JSON] Crockford, D., "The application/json Media Type for 459 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 461 [KEYWORDS] 462 Bradner, S., "Key words for use in RFCs to Indicate 463 Requirement Levels", BCP 14, RFC 2119, March 1997. 465 7.2. Informative References 467 [DKIM] Crocker, D., Ed., Hansen, T., Ed., and M. Kucherawy, Ed., 468 "DomainKeys Identified Mail (DKIM) Signatures", RFC 6376, 469 September 2011. 471 [HTTP] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 472 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 473 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 475 [I-D.REPUTE-CONSIDERATIONS] 476 Kucherawy, M., "Operational Considerations Regarding 477 Reputation Services", draft-ietf-repute-model (work in 478 progress), November 2012. 480 [I-D.REPUTE-EMAIL-IDENTIFIERS] 481 Borenstein, N. and M. Kucherawy, "A Reputation Vocabulary 482 for Email Identifiers", 483 draft-ietf-repute-email-identifiers (work in progress), 484 November 2012. 486 [IANA-CONSIDERATIONS] 487 Narten, T. and H. Alvestrand, "Guidelines for Writing an 488 IANA Considerations Section in RFCs", RFC 5226, May 2008. 490 [MIME-REG] 491 Freed, N. and J. Klensin, "Media Type Specifications and 492 Registration Procedures", RFC 4288, December 2005. 494 Appendix A. Acknowledgments 496 The authors wish to acknowledge the contributions of the following to 497 this specification: Frank Ellermann, Tony Hansen, Jeff Hodges, John 498 Levine, David F. Skoll, and Mykyta Yevstifeyev. 500 Appendix B. Public Discussion 502 Public discussion of this suite of documents takes place on the 503 domainrep@ietf.org mailing list. See 504 https://www.ietf.org/mailman/listinfo/domainrep. 506 Authors' Addresses 508 Nathaniel Borenstein 509 Mimecast 510 203 Crescent St., Suite 303 511 Waltham, MA 02453 512 USA 514 Phone: +1 781 996 5340 515 Email: nsb@guppylake.com 517 Murray S. Kucherawy 518 2063 42nd Avenue 519 San Francisco, CA 94116 520 USA 522 Email: superuser@gmail.com