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