idnits 2.17.1 draft-ietf-repute-media-type-11.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 (August 29, 2013) is 3890 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) -- 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 (==), 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: March 2, 2014 August 29, 2013 7 A Media Type for Reputation Interchange 8 draft-ietf-repute-media-type-11 10 Abstract 12 This document defines the format of reputation response data 13 ("reputons"), the media-type for packaging it, and definition of a 14 registry for the names of reputation applications and response sets. 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 March 2, 2014. 33 Copyright Notice 35 Copyright (c) 2013 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. Reputon . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 2.2. Key Words . . . . . . . . . . . . . . . . . . . . . . . . 3 54 2.3. Other Definitions . . . . . . . . . . . . . . . . . . . . 3 55 3. Description . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 3.1. Reputon Attributes . . . . . . . . . . . . . . . . . . . . 4 57 4. Ratings . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 5. Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 59 6. Reputon Structure . . . . . . . . . . . . . . . . . . . . . . 6 60 6.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 6 61 6.1.1. Formal Definition . . . . . . . . . . . . . . . . . . 6 62 6.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 8 63 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 64 7.1. application/reputon+json Media Type Registration . . . . . 10 65 7.2. Reputation Applications Registry . . . . . . . . . . . . . 11 66 8. Security Considerations . . . . . . . . . . . . . . . . . . . 13 67 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 68 9.1. Normative References . . . . . . . . . . . . . . . . . . . 13 69 9.2. Informative References . . . . . . . . . . . . . . . . . . 14 70 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 14 71 Appendix B. Public Discussion . . . . . . . . . . . . . . . . . . 14 72 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 15 74 1. Introduction 76 This document defines a media type for use when answering a 77 reputation query via the query method described in 78 [I-D.REPUTE-QUERY-HTTP], which uses [HTTP]. 80 Also included is the specification for an IANA registry to contain 81 definitions and symbolic names for known reputation applications and 82 corresponding response sets. 84 2. Terminology and Definitions 86 This section defines terms used in the rest of the document. 88 2.1. Reputon 90 A "reputon" is a single independent object containing reputation 91 information. A particular query about a subject of interest will 92 receive one or more reputons in response, depending on the nature of 93 the data collected and reported by the server. 95 2.2. Key Words 97 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 98 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 99 document are to be interpreted as described in [KEYWORDS]. 101 2.3. Other Definitions 103 Other terms of importance in this document are defined in 104 [I-D.REPUTE-MODEL], the base document in this document series. 106 3. Description 108 The meta-format selected for the representaton of a reputon is 109 Javascript Object Notation (JSON), defined in [JSON]. Accordingly, a 110 new media type, "application/reputon+json", is defined for the JSON 111 representation of reputational data, typically in response to a 112 client making a request for such data about some subject. This media 113 type has one optional parameter, "context", which names the semantic 114 context (i.e., the specific sphere of reputation evaluation, or 115 application) in which context the query is made and the response 116 returned. If the parameter is absent, a generic reputation query 117 (i.e., one not associated with a specific reputation application) is 118 assumed for which only a simple reply is allowed. 120 The body of the media type consists of a JSON document that contains 121 the reputation information requested. A detailed description of the 122 expected structure of the reply is provided below. 124 3.1. Reputon Attributes 126 The key pieces of data found in a reputon for all reputation 127 applications are defined as follows: 129 rater: The identity of the entity providing the reputation 130 information, typically expressed as a DNS domain name. 132 assertion: A keyword indicating the specific assertion or claim 133 being rated. In the absence of an "context" parameter on the 134 media type, the reputon can only indicate generic goodness, with 135 the default assertion "is-good", but each application is expected 136 to define additional assertions. 138 rated: The identity of the entity being rated. The nature of this 139 field is application-specific; it could be domain names, email 140 addresses, driver's license numbers, or anything that uniquely 141 identifies the entity being rated. Documents that define specific 142 reputation applications are required to define syntax and 143 semantics for this field. 145 rating: The overall rating score for that entity, expressed as a 146 floating-point number between 0.0 and 1.0 inclusive. See 147 Section 4 for discussion. 149 The following are OPTIONAL for all applications, to be used in 150 contexts where they are appropriate: 152 confidence: the level of certainty the reputation provider has that 153 the value presented is appropriate, expressed as a floating-point 154 number between 0.0 and 1.0 inclusive. 156 normal-rating: An indication of what the reputation provider would 157 normally expect as a rating for the subject. This allows the 158 client to note that the current rating is or is not in line with 159 expectations. 161 sample-size: The number of data points used to compute the rating, 162 possibly an approximation. Expressed as an unsigned 64-bit 163 integer. Consumers can assume that the count refers to distinct 164 data points rather than a count of aggregations (for example, 165 individual votes rather than aggregated vote counts) unless it is 166 specified out-of-band that some other interpretation is more 167 appropriate. The units are deliberately not normatively 168 specified, since not all reputation service providers will collect 169 data the same way. 171 generated: A timestamp indicating when this value was generated. 172 Expressed as the number of seconds since January 1, 1970 00:00 173 UTC. 175 expires: A timestamp indicating a time beyond which the score 176 reported is likely not to be valid. Expressed as the number of 177 seconds since January 1, 1970 00:00 UTC. See Section 5 for 178 discussion. 180 A particular application that registers itself with IANA (per 181 Section 7.2, below) can define additional application-specific 182 attribute/value pairs beyond these standard ones. 184 An application service provider might operate with an enhanced form 185 of common services, which might in turn prompt development and 186 reporting of specialized reputation information. The details of the 187 enhancements and specialized information are beyond the scope of this 188 document, except that the underlying JSON syntax is extensible for 189 encoding such provider-specific information. 191 4. Ratings 193 The score presented as the value in the rating attribute appears as a 194 floating point value between 0.0 and 1.0 inclusive. The intent is 195 that the definition of an assertion within an application will 196 declare what the anchor values 0.0 and 1.0 specifically mean. 197 Generally speaking, 1.0 implies full agreement with the assertion, 198 while 0.0 indicates no support for the assertion. 200 The definition will also specify the type of scale in use when 201 generating scores, to which all reputation service providers for that 202 application space must adhere. This will allow a client to change 203 which reputation service provider is being queried for a given 204 without having to learn through some out-of-band method what the new 205 provider's values mean. For example, a registration might state that 206 ratings are linear, which would mean a score of "x" is twice as 207 strong as a value of "x/2". It also allows easier aggregation of 208 ratings collected from multiple reputation service providers. 210 5. Caching 212 A reputon can contain an "expires" field indicating a timestamp after 213 which the client SHOULD NOT use the rating it contains, and SHOULD 214 issue a new query. 216 This specificaiton does not mandate any caching of ratings on the 217 part of the client, but there are obvious operational benefits to 218 doing so. In the context of reputation, a cached (and hence, stale) 219 rating can cause desirable traffic to be identified as undesirable, 220 or vice-versa. 222 Reputation data is typically most volatile when the subject of the 223 reputation is young. Accordingly, if a service chooses to include 224 expiration timestamps as part a reply, these values SHOULD be lower 225 for subjects about which little data has been collected. 227 6. Reputon Structure 229 6.1. Syntax 231 A reputon expressed in JSON consists of an object that itself 232 contains zero or more objects whose names are "reputon". Each 233 reputon object is a set of key-value pairs, where the keys are the 234 names of particular attributes that comprise a reputon (as listed 235 above, or as provided with specific applications), and values are the 236 content associated with those keys. The set of keys that make up a 237 reputon within a given application are known as that application's 238 "response set". 240 A reputon object typically contains a reply corresponding to the 241 assertion for which a client made a specific request. For example, a 242 client asking for assertion "sends-spam" about domain "example.com" 243 would expect a reply consisting of a reputon making a "sends-spam" 244 assertion about "example.com" and nothing more. If a client makes a 245 request about a subject but does not specify an assertion of 246 interest, the server can return reputons about any assertion for 247 which it has data; in effect, the client has asked for any available 248 information about the subject. A client that receives an irrelevant 249 reputon simply ignores it. 251 An empty reputon is an acknowledgement by the server that the request 252 has been received, and serves as a positive indication that the 253 server does not have the information requested. This is semantically 254 equivalent to returning a reputon with a "sample-size" of zero. 256 6.1.1. Formal Definition 258 Using [ABNF], the syntax of a reputon is: 260 reputon = "{" [ reputon-object 261 *(value-separator reputon-object) ] "}" 263 reputon-object = "reputon" name-separator response-set 265 response-set = "{" reputon-element 266 *(value-separator reputon-element) "} 268 reputon-element = rater-value / assertion-value / rated-value 269 / rating-value / conf-value / auth-value 270 / sample-value / gen-value / expire-value 271 / ext-value 272 ; these can appear in any order, but MUST appear at most 273 ; once each 275 rater-value = %x22 "rater" %x22 name-separator string 277 assertion-value = %x22 "assertion" %x22 name-separator string 279 rated-value = %x22 "rated" %x22 name-separator string 281 rating-value = %x22 "rating" %x22 name-separator number 282 ; "number" MUST be between 0.0 and 1.0 inclusive 284 conf-value = %x22 "confidence" %x22 name-separator number 285 ; "number" MUST be between 0.0 and 1.0 inclusive 287 auth-value = %x22 "rater-authenticity" %x22 name-separator number 288 ; "number" MUST be between 0.0 and 1.0 inclusive 290 sample-value = %x22 "sample-size" %x22 name-separator int 291 ; "int" MUST NOT be negative 293 gen-value = %x22 "generated" %x22 name-separator int 294 ; "int" MUST NOT be negative 296 expire-value = %x22 "expires" %x22 name-separator int 297 ; "int" MUST NOT be negative 299 ext-value = member 300 ; specific syntax is specified in specific application 301 ; registrations 303 The tokens "value-separator", "name-separator", "string", "int", and 304 "member" are defined in [JSON]. 306 6.2. Examples 308 The following simple example: 310 Content-type: application/reputon+json 312 { 313 "reputon": 314 { 315 "rater": "RatingsRUs.example.com", 316 "rater-authenticity": 1.0, 317 "assertion": "is-good", 318 "rated": "Alex Rodriguez", 319 "rating": 0.99, 320 "sample-size": 50000 321 } 322 } 324 ...indicates we are absolutely sure (1.0) that the entity 325 "RatingsRUs.example.com" consolidated 50000 data points (perhaps from 326 everyone in Yankee Stadium) and concluded that Alex Rodriguez is very 327 very good (0.99) at something. It doesn't tell us what he's good at, 328 and while it might be playing baseball, it could just as well be 329 paying his taxes on time. 331 A more sophisticated usage would define a baseball application with a 332 response set of specific assertions, so that this example: 334 Content-type: application/reputon+json; context="baseball" 336 { 337 "reputon": 338 { 339 "rater": "baseball-reference.example.com", 340 "rater-authenticity": 1.0, 341 "assertion": "hits-for-power", 342 "rated": "Alex Rodriguez", 343 "rating": 0.99, 344 "sample-size": 50000 345 } 346 } 348 ...would indicate that 50000 fans polled by the entity baseball- 349 reference.example.com rate Alex Rodriguez very highly in hitting for 350 power, whereas this example: 352 Content-type: application/reputon+json; context="baseball" 354 { 355 "reputon": 356 { 357 "rater": "baseball-reference.example.com", 358 "rater-authenticity": 1.0, 359 "assertion": "clutch-hitter", 360 "rated": "Alex Rodriguez", 361 "rating": 0.4, 362 "confidence": 0.2, 363 "sample-size": 50000 364 } 365 } 367 ...would indicate that a similar poll indicated a somewhat weak 368 consensus that Alex Rodriguez tends to choke in critical baseball 369 situations. 371 In practice, it is expected that most reputons will have an "context" 372 parameter to target an application-specific set of assertions. 374 The following is an example reputon generated using this schema, 375 including the media type definition line that idenfities a specific 376 reputation application context. Here, reputation agent 377 "rep.example.net" is asserting within the context of the "email-id" 378 application (see [I-D.REPUTE-EMAIL-IDENTIFIERS]) that "example.com" 379 appears to be associated with spam 1.2% of the time, based on just 380 short of 17 million messages analyzed or reported to date. The 381 "email-id" application has declared the extension key "identity" to 382 indicate how the subject identifier was used in the observed data, 383 establishing some more specific semantics for the "rating" value. In 384 this case, the extension is used to show the identity "example.com", 385 the subject of the query, is extracted from the analyzed messages 386 using the [DKIM] "d=" parameter for messages where signatures 387 validate. The reputation agent is 95% confident of this result. 388 (See [I-D.REPUTE-EMAIL-IDENTIFIERS] for details about the registered 389 email identifiers application.) 390 Content-Type: application/reputon+json; context="email-id" 392 { 393 "reputon": 394 { 395 "rater": "rep.example.net", 396 "rater-authenticity": 0.95, 397 "assertion": "spam", 398 "identity": "dkim", 399 "rated": "example.com", 400 "rating": 0.012, 401 "sample-size": 16938213, 402 "updated": 1317795852 403 } 404 } 406 7. IANA Considerations 408 This document presents two actions for IANA, namely the creation of 409 the new media type "application/reputon+json" and the creation of a 410 registry for reputation application types. Another document in this 411 series creates an initial registry entry for the latter. 413 7.1. application/reputon+json Media Type Registration 415 This section provides the media type registration application from 416 [MIME-REG] for processing by IANA: 418 To: media-types@iana.org 420 Subject: Registration of media type application/reputon+json 422 Type name: application 424 Subtype name: reputon+json 426 Required parameters: none 428 Optional parameters: 430 context: Names the reputation application in use within the 431 reputon, which defines the valid assertions and any extensions 432 that may also be valid (i.e., the response set) for that 433 application. These are registered with IANA in the Reputation 434 Application Registry as described in Section 7.2. 436 Encoding considerations: "7bit" encoding is sufficient and is used 437 to maintain readability when viewed by non-MIME mail readers. 439 Security considerations: See Section 8 of [this document]. 441 Interoperability considerations: Implementers may encounter "app" 442 values, attribute/value pairs, or response set items that they do 443 not support, which are to be ignored. 445 Published specification: [this document] 447 Applications that use this media type: Any application that wishes 448 to query a service that provides reputation data using the "long 449 form" defined in [I-D.REPUTE-QUERY-HTTP]. The example application 450 is one that provides reputation expressions about DNS domain names 451 found in email messages. 453 Additional information: The value of the "app" parameter is 454 registered with IANA. 456 Person and email address to contact for further information: 458 Nathaniel Borenstein 460 Murray S. Kucherawy 462 Intended usage: COMMON 464 Author: 466 Nathaniel Borenstein 468 Murray S. Kucherawy 470 Change controller: IESG 472 7.2. Reputation Applications Registry 474 IANA is requested to create the "Reputation Applications" registry. 475 This registry will contain names of applications used with the 476 application/reputon+json media type (and other media types that carry 477 reputons), as defined by this document. 479 New registrations or updates are published in accordance with the 480 "Specification Required" guidelines as described in 481 [IANA-CONSIDERATIONS]. 483 New registrations and updates are to contain the following 484 information: 486 1. Name of the application being registered or updated 488 2. Short description of the application (i.e., the class of entity 489 about which it reports reputation data) 491 3. The document in which the application is defined 493 4. New or updated status, which is to be one of: 495 current: The application is in current use 497 deprecated: The application is in current use but its use is 498 discouraged 500 historic: The application is no longer in current use 502 5. A description of the subject of a query within this reputation, 503 and a legal syntax for the same 505 6. An optional table of query parameters that are specific to this 506 application; each table entry must include: 508 Name: Name of the query parameter 510 Status: (as above) 512 Description: A short description of the purpose of this 513 parameter 515 Syntax: A reference to a description of valid syntax for the 516 parameter's value 518 Required: "yes" if the parameter is mandatory, "no" otherwise 520 7. A list of one or more assertions registered within this 521 application; each table entry is to include: 523 Name: Name of the assertion 525 Description: A short description of the assertion, with specific 526 meanings for values of 0.0 and 1.0 528 Scale: A short description of the scale used in computing the 529 value (see Section 4 of this document) 531 8. An optional list of one or more response set extension keys for 532 use within this application; each table entry is to include: 534 Name: Name of the extension key 536 Description: A short description of the key's intended meaning 538 Syntax: A description of valid values that can appear associated 539 with the key 541 The names of attributes registered should be prefixed by the name of 542 the application itself (e.g., the "foo" application registering a 543 "bar" attribute should call it "foo-bar") to avoid namespace 544 collisions. 546 8. Security Considerations 548 This document is primarily an IANA action registering a media type. 549 It does not describe a new protocol that might introduce security 550 considerations. 552 Discussion of the security and operational impacts of using 553 reputation services in general can be found throughout 554 [I-D.REPUTE-CONSIDERATIONS]. 556 9. References 558 9.1. Normative References 560 [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax 561 Specifications: ABNF", STD 68, RFC 5234, January 2008. 563 [I-D.REPUTE-MODEL] 564 Borenstein, N. and M. Kucherawy, "A Model for Reputation 565 Interchange", draft-ietf-repute-model (work in progress), 566 November 2012. 568 [I-D.REPUTE-QUERY-HTTP] 569 Borenstein, N. and M. Kucherawy, "Reputation Data 570 Interchange using HTTP and XML", 571 draft-ietf-repute-query-http (work in progress), 572 November 2012. 574 [JSON] Crockford, D., "The application/json Media Type for 575 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 577 [KEYWORDS] 578 Bradner, S., "Key words for use in RFCs to Indicate 579 Requirement Levels", BCP 14, RFC 2119, March 1997. 581 9.2. Informative References 583 [DKIM] Crocker, D., Ed., Hansen, T., Ed., and M. Kucherawy, Ed., 584 "DomainKeys Identified Mail (DKIM) Signatures", RFC 6376, 585 September 2011. 587 [HTTP] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 588 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 589 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 591 [I-D.REPUTE-CONSIDERATIONS] 592 Kucherawy, M., "Operational Considerations Regarding 593 Reputation Services", draft-ietf-repute-considerations 594 (work in progress), November 2012. 596 [I-D.REPUTE-EMAIL-IDENTIFIERS] 597 Borenstein, N. and M. Kucherawy, "A Reputation Vocabulary 598 for Email Identifiers", 599 draft-ietf-repute-email-identifiers (work in progress), 600 November 2012. 602 [IANA-CONSIDERATIONS] 603 Narten, T. and H. Alvestrand, "Guidelines for Writing an 604 IANA Considerations Section in RFCs", RFC 5226, May 2008. 606 [MIME-REG] 607 Freed, N. and J. Klensin, "Media Type Specifications and 608 Registration Procedures", RFC 4288, December 2005. 610 Appendix A. Acknowledgments 612 The authors wish to acknowledge the contributions of the following to 613 this specification: Frank Ellermann, Tony Hansen, Jeff Hodges, Simon 614 Hunt, John Levine, David F. Skoll, and Mykyta Yevstifeyev. 616 Appendix B. Public Discussion 618 Public discussion of this suite of documents takes place on the 619 domainrep@ietf.org mailing list. See 620 https://www.ietf.org/mailman/listinfo/domainrep. 622 Authors' Addresses 624 Nathaniel Borenstein 625 Mimecast 626 203 Crescent St., Suite 303 627 Waltham, MA 02453 628 USA 630 Phone: +1 781 996 5340 631 Email: nsb@guppylake.com 633 Murray S. Kucherawy 634 270 Upland Drive 635 San Francisco, CA 94127 636 USA 638 Email: superuser@gmail.com