idnits 2.17.1 draft-ietf-repute-media-type-12.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 (September 7, 2013) is 3883 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 11, 2014 September 7, 2013 7 A Media Type for Reputation Interchange 8 draft-ietf-repute-media-type-12 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 11, 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 representation 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 the query is made and the response returned. 116 If the parameter is absent, a generic reputation query (i.e., one not 117 associated with a specific reputation application) is assumed for 118 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 aggregating, computing, and 130 providing the reputation information, typically expressed as a DNS 131 domain name. 133 assertion: A keyword indicating the specific assertion or claim 134 being rated. In the absence of a "context" parameter on the media 135 type, the reputon can only indicate generic goodness, with the 136 default assertion "is-good", but each application is expected to 137 define additional assertions. 139 rated: The identity of the entity being rated. The nature of this 140 field is application-specific; it could be domain names, email 141 addresses, driver's license numbers, or anything that uniquely 142 identifies the entity being rated. Documents that define specific 143 reputation applications are required to define syntax and 144 semantics for this field. 146 rating: The overall rating score for that entity, expressed as a 147 floating-point number between 0.0 and 1.0 inclusive. See 148 Section 4 for discussion. 150 The following are OPTIONAL for all applications, to be used in 151 contexts where they are appropriate: 153 confidence: the level of certainty the reputation provider has that 154 the value presented is appropriate, expressed as a floating-point 155 number between 0.0 and 1.0 inclusive. 157 normal-rating: An indication of what the reputation provider would 158 normally expect as a rating for the subject. This allows the 159 client to note that the current rating is or is not in line with 160 expectations. 162 sample-size: The number of data points used to compute the rating, 163 possibly an approximation. Expressed as an unsigned 64-bit 164 integer. Consumers can assume that the count refers to distinct 165 data points rather than a count of aggregations (for example, 166 individual votes rather than aggregated vote counts) unless it is 167 specified out-of-band that some other interpretation is more 168 appropriate. The units are deliberately not normatively 169 specified, since not all reputation service providers will collect 170 data the same way. 172 generated: A timestamp indicating when this value was generated. 173 Expressed as the number of seconds since January 1, 1970 00:00 174 UTC. 176 expires: A timestamp indicating a time beyond which the score 177 reported is likely not to be valid. Expressed as the number of 178 seconds since January 1, 1970 00:00 UTC. See Section 5 for 179 discussion. 181 A particular application that registers itself with IANA (per 182 Section 7.2, below) can define additional application-specific 183 attribute/value pairs beyond these standard ones. 185 An application service provider might operate with an enhanced form 186 of common services, which might in turn prompt development and 187 reporting of specialized reputation information. The details of the 188 enhancements and specialized information are beyond the scope of this 189 document, except that the underlying JSON syntax is extensible for 190 encoding such provider-specific information. 192 4. Ratings 194 The score presented as the value in the rating attribute appears as a 195 floating point value between 0.0 and 1.0 inclusive. The intent is 196 that the definition of an assertion within an application will 197 declare what the anchor values 0.0 and 1.0 specifically mean. 198 Generally speaking, 1.0 implies full agreement with the assertion, 199 while 0.0 indicates no support for the assertion. 201 The definition will also specify the type of scale in use when 202 generating scores, to which all reputation service providers for that 203 application space must adhere. This will allow a client to change 204 which reputation service provider is being queried without having to 205 learn through some out-of-band method what the new provider's ratings 206 mean. For example, a registration might state that ratings are 207 linear, which would mean a score of "x" is twice as strong as a value 208 of "x/2". It also allows easier aggregation of ratings collected 209 from multiple reputation service providers. 211 5. Caching 213 A reputon can contain an "expires" field indicating a timestamp after 214 which the client SHOULD NOT use the rating it contains, and SHOULD 215 issue a new query. 217 This specification does not mandate any caching of ratings on the 218 part of the client, but there are obvious operational benefits to 219 doing so. In the context of reputation, a cached (and hence, stale) 220 rating can cause desirable traffic to be identified as undesirable, 221 or vice-versa. 223 Reputation data is typically most volatile when the subject of the 224 reputation is young. Accordingly, if a service chooses to include 225 expiration timestamps as part a reply, these values SHOULD be lower 226 for subjects about which little data has been collected. 228 6. Reputon Structure 230 6.1. Syntax 232 A reputon expressed in JSON consists of an object that itself 233 contains zero or more objects whose names are "reputon". Each 234 reputon object is a set of key-value pairs, where the keys are the 235 names of particular attributes that comprise a reputon (as listed 236 above, or as provided with specific applications), and values are the 237 content associated with those keys. The set of keys that make up a 238 reputon within a given application are known as that application's 239 "response set". 241 A reputon object typically contains a reply corresponding to the 242 assertion for which a client made a specific request. For example, a 243 client asking for assertion "sends-spam" about domain "example.com" 244 would expect a reply consisting of a reputon making a "sends-spam" 245 assertion about "example.com" and nothing more. If a client makes a 246 request about a subject but does not specify an assertion of 247 interest, the server can return reputons about any assertion for 248 which it has data; in effect, the client has asked for any available 249 information about the subject. A client that receives an irrelevant 250 reputon simply ignores it. 252 An empty reputon is an acknowledgement by the server that the request 253 has been received, and serves as a positive indication that the 254 server does not have the information requested. This is semantically 255 equivalent to returning a reputon with a "sample-size" of zero. 257 6.1.1. Formal Definition 259 Using [ABNF], the syntax of a reputon is: 261 reputon = "{" [ reputon-object 262 *(value-separator reputon-object) ] "}" 264 reputon-object = "reputon" name-separator response-set 266 response-set = "{" reputon-element 267 *(value-separator reputon-element) "} 269 reputon-element = rater-value / assertion-value / rated-value 270 / rating-value / conf-value / normal-value 271 / sample-value / gen-value / expire-value 272 / ext-value 273 ; these can appear in any order, but MUST appear at most 274 ; once each 276 rater-value = %x22 "rater" %x22 name-separator string 278 assertion-value = %x22 "assertion" %x22 name-separator string 280 rated-value = %x22 "rated" %x22 name-separator string 282 rating-value = %x22 "rating" %x22 name-separator number 283 ; "number" MUST be between 0.0 and 1.0 inclusive 285 conf-value = %x22 "confidence" %x22 name-separator number 286 ; "number" MUST be between 0.0 and 1.0 inclusive 288 normal-value = %x22 "normal-rating" %x22 name-separator number 289 ; "number" MUST be between 0.0 and 1.0 inclusive 291 sample-value = %x22 "sample-size" %x22 name-separator int 292 ; "int" MUST NOT be negative 294 gen-value = %x22 "generated" %x22 name-separator int 295 ; "int" MUST NOT be negative 297 expire-value = %x22 "expires" %x22 name-separator int 298 ; "int" MUST NOT be negative 300 ext-value = member 301 ; specific syntax is defined in separate application 302 ; registrations 304 The tokens "value-separator", "name-separator", "string", "int", and 305 "member" are defined in [JSON]. 307 6.2. Examples 309 The following simple example: 311 Content-type: application/reputon+json 313 { 314 "reputon": 315 { 316 "rater": "RatingsRUs.example.com", 317 "assertion": "is-good", 318 "rated": "Alex Rodriguez", 319 "rating": 0.99, 320 "sample-size": 50000 321 } 322 } 324 ...indicates to the client that "RatingsRUs.example.com" consolidated 325 50000 data points (perhaps from everyone in Yankee Stadium) and 326 concluded that Alex Rodriguez is very very good (0.99) at something. 327 It doesn't tell us what he's good at, and while it might be playing 328 baseball, it could just as well be paying his taxes on time. 330 A more sophisticated usage would define a baseball application with a 331 response set of specific assertions, so that this example: 333 Content-type: application/reputon+json; context="baseball" 335 { 336 "reputon": 337 { 338 "rater": "baseball-reference.example.com", 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 "assertion": "clutch-hitter", 357 "rated": "Alex Rodriguez", 358 "rating": 0.4, 359 "confidence": 0.2, 360 "sample-size": 50000 361 } 362 } 364 ...would indicate that a similar poll indicated a somewhat weak 365 consensus that Alex Rodriguez tends to choke in critical baseball 366 situations. 368 In practice, it is expected that most reputons will have an "context" 369 parameter to target an application-specific set of assertions. 371 The following is an example reputon generated using this schema, 372 including the media type definition line that identifies a specific 373 reputation application context. Here, reputation agent 374 "rep.example.net" is asserting within the context of the "email-id" 375 application (see [I-D.REPUTE-EMAIL-IDENTIFIERS]) that "example.com" 376 appears to be associated with spam 1.2% of the time, based on just 377 short of 17 million messages analyzed or reported to date. The 378 "email-id" application has declared the extension key "identity" to 379 indicate how the subject identifier was used in the observed data, 380 establishing some more specific semantics for the "rating" value. In 381 this case, the extension is used to show the identity "example.com", 382 the subject of the query, is extracted from the analyzed messages 383 using the [DKIM] "d=" parameter for messages where signatures 384 validate. The reputation agent is 95% confident of this result. 385 (See [I-D.REPUTE-EMAIL-IDENTIFIERS] for details about the registered 386 email identifiers application.) 387 Content-Type: application/reputon+json; context="email-id" 389 { 390 "reputon": 391 { 392 "rater": "rep.example.net", 393 "assertion": "spam", 394 "identity": "dkim", 395 "rated": "example.com", 396 "confidence": 0.95, 397 "rating": 0.012, 398 "sample-size": 16938213, 399 "updated": 1317795852 400 } 401 } 403 7. IANA Considerations 405 This document presents two actions for IANA, namely the creation of 406 the new media type "application/reputon+json" and the creation of a 407 registry for reputation application types. Another document in this 408 series creates an initial registry entry for the latter. 410 7.1. application/reputon+json Media Type Registration 412 This section provides the media type registration application from 413 [MIME-REG] for processing by IANA: 415 To: media-types@iana.org 417 Subject: Registration of media type application/reputon+json 419 Type name: application 421 Subtype name: reputon+json 423 Required parameters: none 425 Optional parameters: 427 context: Names the reputation application in use within the 428 reputon, which defines the valid assertions and any extensions 429 that may also be valid (i.e., the response set) for that 430 application. These are registered with IANA in the Reputation 431 Application Registry as described in Section 7.2. 433 Encoding considerations: "7bit" encoding is sufficient and is used 434 to maintain readability when viewed by non-MIME mail readers. 436 Security considerations: See Section 8 of [this document]. 438 Interoperability considerations: Implementers may encounter "app" 439 values, attribute/value pairs, or response set items that they do 440 not support, which are to be ignored. 442 Published specification: [this document] 444 Applications that use this media type: Any application that wishes 445 to query a service that provides reputation data using the "long 446 form" defined in [I-D.REPUTE-QUERY-HTTP]. The example application 447 is one that provides reputation expressions about DNS domain names 448 found in email messages. 450 Additional information: The value of the "app" parameter is 451 registered with IANA. 453 Person and email address to contact for further information: 455 Nathaniel Borenstein 457 Murray S. Kucherawy 459 Intended usage: COMMON 461 Author: 463 Nathaniel Borenstein 465 Murray S. Kucherawy 467 Change controller: IESG 469 7.2. Reputation Applications Registry 471 IANA is requested to create the "Reputation Applications" registry. 472 This registry will contain names of applications used with the 473 application/reputon+json media type (and other media types that carry 474 reputons), as defined by this document. 476 New registrations or updates are published in accordance with the 477 "Specification Required" guidelines as described in 478 [IANA-CONSIDERATIONS]. 480 New registrations and updates are to contain the following 481 information: 483 1. Name of the application being registered or updated 485 2. Short description of the application (i.e., the class of entity 486 about which it reports reputation data) 488 3. The document in which the application is defined 490 4. New or updated status, which is to be one of: 492 current: The application is in current use 494 deprecated: The application is in current use but its use is 495 discouraged 497 historic: The application is no longer in current use 499 5. A description of the subject of a query within this reputation, 500 and a legal syntax for the same 502 6. An optional table of query parameters that are specific to this 503 application; each table entry must include: 505 Name: Name of the query parameter 507 Status: (as above) 509 Description: A short description of the purpose of this 510 parameter 512 Syntax: A reference to a description of valid syntax for the 513 parameter's value 515 Required: "yes" if the parameter is mandatory, "no" otherwise 517 7. A list of one or more assertions registered within this 518 application; each table entry is to include: 520 Name: Name of the assertion 522 Description: A short description of the assertion, with specific 523 meanings for values of 0.0 and 1.0 525 Scale: A short description of the scale used in computing the 526 value (see Section 4 of this document) 528 8. An optional list of one or more response set extension keys for 529 use within this application; each table entry is to include: 531 Name: Name of the extension key 533 Description: A short description of the key's intended meaning 535 Syntax: A description of valid values that can appear associated 536 with the key 538 The names of attributes registered should be prefixed by the name of 539 the application itself (e.g., the "foo" application registering a 540 "bar" attribute should call it "foo-bar") to avoid namespace 541 collisions. 543 8. Security Considerations 545 This document is primarily an IANA action registering a media type. 546 It does not describe a new protocol that might introduce security 547 considerations. 549 Discussion of the security and operational impacts of using 550 reputation services in general can be found throughout 551 [I-D.REPUTE-CONSIDERATIONS]. 553 9. References 555 9.1. Normative References 557 [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax 558 Specifications: ABNF", STD 68, RFC 5234, January 2008. 560 [I-D.REPUTE-MODEL] 561 Borenstein, N. and M. Kucherawy, "A Model for Reputation 562 Interchange", draft-ietf-repute-model (work in progress), 563 November 2012. 565 [I-D.REPUTE-QUERY-HTTP] 566 Borenstein, N. and M. Kucherawy, "Reputation Data 567 Interchange using HTTP and XML", 568 draft-ietf-repute-query-http (work in progress), 569 November 2012. 571 [JSON] Crockford, D., "The application/json Media Type for 572 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 574 [KEYWORDS] 575 Bradner, S., "Key words for use in RFCs to Indicate 576 Requirement Levels", BCP 14, RFC 2119, March 1997. 578 9.2. Informative References 580 [DKIM] Crocker, D., Ed., Hansen, T., Ed., and M. Kucherawy, Ed., 581 "DomainKeys Identified Mail (DKIM) Signatures", RFC 6376, 582 September 2011. 584 [HTTP] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 585 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 586 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 588 [I-D.REPUTE-CONSIDERATIONS] 589 Kucherawy, M., "Operational Considerations Regarding 590 Reputation Services", draft-ietf-repute-considerations 591 (work in progress), November 2012. 593 [I-D.REPUTE-EMAIL-IDENTIFIERS] 594 Borenstein, N. and M. Kucherawy, "A Reputation Vocabulary 595 for Email Identifiers", 596 draft-ietf-repute-email-identifiers (work in progress), 597 November 2012. 599 [IANA-CONSIDERATIONS] 600 Narten, T. and H. Alvestrand, "Guidelines for Writing an 601 IANA Considerations Section in RFCs", RFC 5226, May 2008. 603 [MIME-REG] 604 Freed, N. and J. Klensin, "Media Type Specifications and 605 Registration Procedures", RFC 4288, December 2005. 607 Appendix A. Acknowledgments 609 The authors wish to acknowledge the contributions of the following to 610 this specification: Frank Ellermann, Tony Hansen, Jeff Hodges, Simon 611 Hunt, John Levine, David F. Skoll, and Mykyta Yevstifeyev. 613 Appendix B. Public Discussion 615 Public discussion of this suite of documents takes place on the 616 domainrep@ietf.org mailing list. See 617 https://www.ietf.org/mailman/listinfo/domainrep. 619 Authors' Addresses 621 Nathaniel Borenstein 622 Mimecast 623 203 Crescent St., Suite 303 624 Waltham, MA 02453 625 USA 627 Phone: +1 781 996 5340 628 Email: nsb@guppylake.com 630 Murray S. Kucherawy 631 270 Upland Drive 632 San Francisco, CA 94127 633 USA 635 Email: superuser@gmail.com