idnits 2.17.1 draft-ietf-repute-media-type-09.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 (July 3, 2013) is 3944 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: January 4, 2014 July 3, 2013 7 A Media Type for Reputation Interchange 8 draft-ietf-repute-media-type-09 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 January 4, 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 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 well-behaved: The level of confidence that the rated identity is 157 typically well-behaved, expressed as a floating-point number 158 between 0.0 and 1.0 inclusive. "Well-behaved" here means the 159 identity being rated is unlikely to be associated with adverse 160 scores related to other assertions. One would, for example, have 161 a reasonable expectation that government agency or a popular bank 162 would be unlikely to develop a reputation for sending spam, so a 163 statement indicating a strong spam score for such an identity 164 would be unusual, and a client receiving such conflicting details 165 might decide to penalize such traffic less severely, or for a 166 shorter period of time. Note that this value might be entirely 167 subjective on the part of the reputation service provider; it need 168 not be based solely on aggregated data. 170 sample-size: The number of data points used to compute the rating, 171 possibly an approximation. Expressed as an unsigned 64-bit 172 integer. Consumers can assume that the count refers to distinct 173 data points rather than a count of aggregations (for example, 174 individual votes rather than aggregated vote counts) unless it is 175 specified out-of-band that some other interpretation is more 176 appropriate. The units are deliberately not normatively 177 specified, since not all reputation service providers will collect 178 data the same way. 180 generated: A timestamp indicating when this value was generated. 181 Expressed as the number of seconds since January 1, 1970 00:00 182 UTC. 184 expires: A timestamp indicating a time beyond which the score 185 reported is likely not to be valid. Expressed as the number of 186 seconds since January 1, 1970 00:00 UTC. See Section 5 for 187 discussion. 189 A particular application that registers itself with IANA (per 190 Section 7.2, below) can define additional application-specific 191 attribute/value pairs beyond these standard ones. 193 An application service provider might operate with an enhanced form 194 of common services, which might in turn prompt development and 195 reporting of specialized reputation information. The details of the 196 enhancements and specialized information are beyond the scope of this 197 document, except that the underlying JSON syntax is extensible for 198 encoding such provider-specific information. 200 4. Ratings 202 The score presented as the value in the rating attribute appears as a 203 floating point value between 0.0 and 1.0 inclusive. The intent is 204 that the definition of an assertion within an application will 205 declare what the anchor values 0.0 and 1.0 specifically mean. 206 Generally speaking, 1.0 implies full agreement with the assertion, 207 while 0.0 indicates no support for the assertion. 209 The definition will also specify the type of scale in use when 210 generating scores, to which all reputation service providers for that 211 application space must adhere. This will allow a client to change 212 which reputation service provider is being queried for a given 213 without having to learn through some out-of-band method what the new 214 provider's values mean. For example, a registration might state that 215 ratings are linear, which would mean a score of "x" is twice as 216 strong as a value of "x/2". It also allows easier aggregation of 217 ratings collected from multiple reputation service providers. 219 5. Caching 221 A reputon can contain an "expires" field indicating a timestamp after 222 which the client SHOULD NOT use the rating it contains, and SHOULD 223 issue a new query. 225 This specificaiton does not mandate any caching of ratings on the 226 part of the client, but there are obvious operational benefits to 227 doing so. In the context of reputation, a cached (and hence, stale) 228 rating can cause desirable traffic to be identified as undesirable, 229 or vice-versa. 231 Reputation data is typically most volatile when the subject of the 232 reputation is young. Accordingly, if a service chooses to include 233 expiration timestamps as part a reply, these values SHOULD be lower 234 for subjects about which little data has been collected. 236 6. Reputon Structure 238 6.1. Syntax 240 A reputon expressed in JSON consists of an object that itself 241 contains zero or more objects whose names are "reputon". Each 242 reputon object is a set of key-value pairs, where the keys are the 243 names of particular attributes that comprise a reputon (as listed 244 above, or as provided with specific applications), and values are the 245 content associated with those keys. The set of keys that make up a 246 reputon within a given application are known as that application's 247 "response set". 249 An empty reputon is an acknowledgement by the server that the request 250 has been received and serves as a positive indication that the server 251 does not have the information requested. This is semantically 252 equivalent to returning a reputon with a "sample-size" of zero. 254 6.1.1. Formal Definition 256 Using [ABNF], the syntax of a reputon is: 258 reputon = "{" [ reputon-object 259 *(value-separator reputon-object) ] "}" 261 reputon-object = "reputon" name-separator response-set 263 response-set = "{" reputon-element 264 *(value-separator reputon-element) "} 266 reputon-element = rater-value / assertion-value / rated-value 267 / rating-value / conf-value / auth-value 268 / sample-value / gen-value / expire-value 269 / ext-value 270 ; these can appear in any order, but MUST appear at most 271 ; once each 273 rater-value = %x22 "rater" %x22 name-separator string 275 assertion-value = %x22 "assertion" %x22 name-separator string 277 rated-value = %x22 "rated" %x22 name-separator string 279 rating-value = %x22 "rating" %x22 name-separator number 280 ; "number" MUST be between 0.0 and 1.0 inclusive 282 conf-value = %x22 "confidence" %x22 name-separator number 283 ; "number" MUST be between 0.0 and 1.0 inclusive 285 auth-value = %x22 "rater-authenticity" %x22 name-separator number 286 ; "number" MUST be between 0.0 and 1.0 inclusive 288 sample-value = %x22 "sample-size" %x22 name-separator int 289 ; "int" MUST NOT be negative 291 gen-value = %x22 "generated" %x22 name-separator int 292 ; "int" MUST NOT be negative 294 expire-value = %x22 "expires" %x22 name-separator int 295 ; "int" MUST NOT be negative 297 ext-value = member 298 ; specific syntax is specified in specific application 299 ; registrations 301 The tokens "value-separator", "name-separator", "string", "int", and 302 "member" are defined in [JSON]. 304 6.2. Examples 306 The following simple example: 308 Content-type: application/reputon+json 310 { 311 "reputon": 312 { 313 "rater": "RatingsRUs.example.com", 314 "rater-authenticity": 1.0, 315 "assertion": "is-good", 316 "rated": "Alex Rodriguez", 317 "rating": 0.99, 318 "sample-size": 50000 319 } 320 } 322 ...indicates we are absolutely sure (1.0) that the entity 323 "RatingsRUs.example.com" consolidated 50000 data points (perhaps from 324 everyone in Yankee Stadium) and concluded that Alex Rodriguez is very 325 very good (0.99) at something. It doesn't tell us what he's good at, 326 and while it might be playing baseball, it could just as well be 327 paying his taxes on time. 329 A more sophisticated usage would define a baseball application with a 330 response set of specific assertions, so that this example: 332 Content-type: application/reputon+json; context="baseball" 334 { 335 "reputon": 336 { 337 "rater": "baseball-reference.example.com", 338 "rater-authenticity": 1.0, 339 "assertion": "hits-for-power", 340 "rated": "Alex Rodriguez", 341 "rating": 0.99, 342 "sample-size": 50000 343 } 344 } 346 ...would indicate that 50000 fans polled by the entity baseball- 347 reference.example.com rate Alex Rodriguez very highly in hitting for 348 power, whereas this example: 350 Content-type: application/reputon+json; context="baseball" 352 { 353 "reputon": 354 { 355 "rater": "baseball-reference.example.com", 356 "rater-authenticity": 1.0, 357 "assertion": "clutch-hitter", 358 "rated": "Alex Rodriguez", 359 "rating": 0.4, 360 "confidence": 0.2, 361 "sample-size": 50000 362 } 363 } 365 ...would indicate that a similar poll indicated a somewhat weak 366 consensus that Alex Rodriguez tends to choke in critical baseball 367 situations. 369 In practice, it is expected that most reputons will have an "context" 370 parameter to target an application-specific set of assertions. 372 The following is an example reputon generated using this schema, 373 including the media type definition line that idenfities a specific 374 reputation application context. Here, reputation agent 375 "rep.example.net" is asserting within the context of the "email-id" 376 application (see [I-D.REPUTE-EMAIL-IDENTIFIERS]) that "example.com" 377 appears to be associated with spam 1.2% of the time, based on just 378 short of 17 million messages analyzed or reported to date. The 379 "email-id" application has declared the extension key "identity" to 380 indicate how the subject identifier was used in the observed data, 381 establishing some more specific semantics for the "rating" value. In 382 this case, the extension is used to show the identity "example.com", 383 the subject of the query, is extracted from the analyzed messages 384 using the [DKIM] "d=" parameter for messages where signatures 385 validate. The reputation agent is 95% confident of this result. 386 (See [I-D.REPUTE-EMAIL-IDENTIFIERS] for details about the registered 387 email identifiers application.) 388 Content-Type: application/reputon+json; context="email-id" 390 { 391 "reputon": 392 { 393 "rater": "rep.example.net", 394 "rater-authenticity": 0.95, 395 "assertion": "spam", 396 "identity": "dkim", 397 "rated": "example.com", 398 "rating": 0.012, 399 "sample-size": 16938213, 400 "updated": 1317795852 401 } 402 } 404 7. IANA Considerations 406 This document presents two actions for IANA, namely the creation of 407 the new media type "application/reputon+json" and the creation of a 408 registry for reputation application types. Another document in this 409 series creates an initial registry entry for the latter. 411 7.1. application/reputon+json Media Type Registration 413 This section provides the media type registration application from 414 [MIME-REG] for processing by IANA: 416 To: media-types@iana.org 418 Subject: Registration of media type application/reputon+json 420 Type name: application 422 Subtype name: reputon+json 424 Required parameters: none 426 Optional parameters: 428 context: Names the reputation application in use within the 429 reputon, which defines the valid assertions and any extensions 430 that may also be valid (i.e., the response set) for that 431 application. These are registered with IANA in the Reputation 432 Application Registry as described in Section 7.2. 434 Encoding considerations: "7bit" encoding is sufficient and is used 435 to maintain readability when viewed by non-MIME mail readers. 437 Security considerations: See Section 8 of [this document]. 439 Interoperability considerations: Implementers may encounter "app" 440 values, attribute/value pairs, or response set items that they do 441 not support, which are to be ignored. 443 Published specification: [this document] 445 Applications that use this media type: Any application that wishes 446 to query a service that provides reputation data using the "long 447 form" defined in [I-D.REPUTE-QUERY-HTTP]. The example application 448 is one that provides reputation expressions about DNS domain names 449 found in email messages. 451 Additional information: The value of the "app" parameter is 452 registered with IANA. 454 Person and email address to contact for further information: 456 Nathaniel Borenstein 458 Murray S. Kucherawy 460 Intended usage: COMMON 462 Author: 464 Nathaniel Borenstein 466 Murray S. Kucherawy 468 Change controller: IESG 470 7.2. Reputation Applications Registry 472 IANA is requested to create the "Reputation Applications" registry. 473 This registry will contain names of applications used with the 474 application/reputon+json media type (and other media types that carry 475 reputons), as defined by this document. 477 New registrations or updates are published in accordance with the 478 "Specification Required" guidelines as described in 479 [IANA-CONSIDERATIONS]. 481 New registrations and updates are to contain the following 482 information: 484 1. Name of the application being registered or updated 486 2. Short description of the application (i.e., the class of entity 487 about which it reports reputation data) 489 3. The document in which the application is defined 491 4. New or updated status, which is to be one of: 493 current: The application is in current use 495 deprecated: The application is in current use but its use is 496 discouraged 498 historic: The application is no longer in current use 500 5. A description of the subject of a query within this reputation, 501 and a legal syntax for the same 503 6. An optional table of query parameters that are specific to this 504 application; each table entry must include: 506 Name: Name of the query parameter 508 Status: (as above) 510 Description: A short description of the purpose of this 511 parameter 513 Syntax: A reference to a description of valid syntax for the 514 parameter's value 516 Required: "yes" if the parameter is mandatory, "no" otherwise 518 7. A list of one or more assertions registered within this 519 application; each table entry is to include: 521 Name: Name of the assertion 523 Description: A short description of the assertion, with specific 524 meanings for values of 0.0 and 1.0 526 Scale: A short description of the scale used in computing the 527 value (see Section 4 of this document) 529 8. An optional list of one or more response set extension keys for 530 use within this application; each table entry is to include: 532 Name: Name of the extension key 534 Description: A short description of the key's intended meaning 536 Syntax: A description of valid values that can appear associated 537 with the key 539 The names of attributes registered should be prefixed by the name of 540 the application itself (e.g., the "foo" application registering a 541 "bar" attribute should call it "foo-bar") to avoid namespace 542 collisions. 544 8. Security Considerations 546 This document is primarily an IANA action registering a media type. 547 It does not describe a new protocol that might introduce security 548 considerations. 550 Discussion of the security and operational impacts of using 551 reputation services in general can be found throughout 552 [I-D.REPUTE-CONSIDERATIONS]. 554 9. References 556 9.1. Normative References 558 [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax 559 Specifications: ABNF", STD 68, RFC 5234, January 2008. 561 [I-D.REPUTE-MODEL] 562 Borenstein, N. and M. Kucherawy, "A Model for Reputation 563 Interchange", draft-ietf-repute-model (work in progress), 564 November 2012. 566 [I-D.REPUTE-QUERY-HTTP] 567 Borenstein, N. and M. Kucherawy, "Reputation Data 568 Interchange using HTTP and XML", 569 draft-ietf-repute-query-http (work in progress), 570 November 2012. 572 [JSON] Crockford, D., "The application/json Media Type for 573 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 575 [KEYWORDS] 576 Bradner, S., "Key words for use in RFCs to Indicate 577 Requirement Levels", BCP 14, RFC 2119, March 1997. 579 9.2. Informative References 581 [DKIM] Crocker, D., Ed., Hansen, T., Ed., and M. Kucherawy, Ed., 582 "DomainKeys Identified Mail (DKIM) Signatures", RFC 6376, 583 September 2011. 585 [HTTP] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 586 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 587 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 589 [I-D.REPUTE-CONSIDERATIONS] 590 Kucherawy, M., "Operational Considerations Regarding 591 Reputation Services", draft-ietf-repute-model (work in 592 progress), November 2012. 594 [I-D.REPUTE-EMAIL-IDENTIFIERS] 595 Borenstein, N. and M. Kucherawy, "A Reputation Vocabulary 596 for Email Identifiers", 597 draft-ietf-repute-email-identifiers (work in progress), 598 November 2012. 600 [IANA-CONSIDERATIONS] 601 Narten, T. and H. Alvestrand, "Guidelines for Writing an 602 IANA Considerations Section in RFCs", RFC 5226, May 2008. 604 [MIME-REG] 605 Freed, N. and J. Klensin, "Media Type Specifications and 606 Registration Procedures", RFC 4288, December 2005. 608 Appendix A. Acknowledgments 610 The authors wish to acknowledge the contributions of the following to 611 this specification: Frank Ellermann, Tony Hansen, Jeff Hodges, Simon 612 Hunt, John Levine, David F. Skoll, and Mykyta Yevstifeyev. 614 Appendix B. Public Discussion 616 Public discussion of this suite of documents takes place on the 617 domainrep@ietf.org mailing list. See 618 https://www.ietf.org/mailman/listinfo/domainrep. 620 Authors' Addresses 622 Nathaniel Borenstein 623 Mimecast 624 203 Crescent St., Suite 303 625 Waltham, MA 02453 626 USA 628 Phone: +1 781 996 5340 629 Email: nsb@guppylake.com 631 Murray S. Kucherawy 632 270 Upland Drive 633 San Francisco, CA 94127 634 USA 636 Email: superuser@gmail.com