idnits 2.17.1 draft-ietf-repute-media-type-07.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 (May 19, 2013) is 3988 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: November 20, 2013 May 19, 2013 7 A Media Type for Reputation Interchange 8 draft-ietf-repute-media-type-07 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 November 20, 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. Scores . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 5. Reputon Structure . . . . . . . . . . . . . . . . . . . . . . 5 59 5.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 6 60 5.1.1. Formal Definition . . . . . . . . . . . . . . . . . . 6 61 5.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 7 62 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 63 6.1. application/reputon+json Media Type Registration . . . . . 10 64 6.2. Reputation Applications Registry . . . . . . . . . . . . . 11 65 7. Security Considerations . . . . . . . . . . . . . . . . . . . 13 66 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 67 8.1. Normative References . . . . . . . . . . . . . . . . . . . 13 68 8.2. Informative References . . . . . . . . . . . . . . . . . . 14 69 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 14 70 Appendix B. Public Discussion . . . . . . . . . . . . . . . . . . 14 71 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 15 73 1. Introduction 75 This document defines a media type for use when answering a 76 reputation query using the "long form" query defined in 77 [I-D.REPUTE-QUERY-HTTP], which uses [HTTP]. 79 Also included is the specification for an IANA registry to contain 80 definitions and symbolic names for known reputation applications and 81 corresponding response sets. 83 2. Terminology and Definitions 85 This section defines terms used in the rest of the document. 87 2.1. Reputon 89 A "reputon" is a single independent object containing reputation 90 information. A particular query about a subject of interest will 91 receive one or more reputons in response, depending on the nature of 92 the data collected and reported by the server. 94 2.2. Key Words 96 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 97 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 98 document are to be interpreted as described in [KEYWORDS]. 100 2.3. Other Definitions 102 Other terms of importance in this document are defined in 103 [I-D.REPUTE-MODEL], the base document in this document series. 105 3. Description 107 The meta-format selected for the representaton of a reputon is 108 Javascript Object Notation (JSON), defined in [JSON]. Accordingly, a 109 new media type, "application/reputon+json", is defined for the JSON 110 representation of reputational data, typically in response to a 111 client making a request for such data about some subject. This media 112 type has one optional parameter, "context", which names the semantic 113 context (i.e., the specific sphere of reputation evaluation, or 114 application) in which context the query is made and the response 115 returned. If the parameter is absent, a generic reputation query 116 (i.e., one not associated with a specific reputation application) is 117 assumed for which only a simple reply is allowed. 119 The body of the media type consists of a JSON document that contains 120 the reputation information requested. A detailed description of the 121 expected structure of the reply is provided below. 123 3.1. Reputon Attributes 125 The key pieces of data found in a reputon for all reputation 126 applications are defined as follows: 128 rater: The identity of the entity providing the reputation 129 information, typically expressed as a DNS domain name. 131 assertion: A keyword indicating the specific assertion or claim 132 being rated. In the absence of an "context" parameter on the 133 media type, the reputon can only indicate generic goodness, with 134 the default assertion "is-good", but each application is expected 135 to define additional assertions. 137 rated: The identity of the entity being rated. The nature of this 138 field is application-specific; it could be domain names, email 139 addresses, driver's license numbers, or anything that uniquely 140 identifies the entity being rated. Documents that define specific 141 reputation applications are required to define syntax and 142 semantics for this field. 144 rating: The overall rating score for that entity, expressed as a 145 floating-point number between 0.0 and 1.0 inclusive. See 146 Section 4 for discussion. 148 The following are OPTIONAL for all applications, to be used in 149 contexts where they are appropriate: 151 confidence: the level of certainty the reputation provider has that 152 the value presented is appropriate, expressed as a floating-point 153 number between 0.0 and 1.0 inclusive. 155 rater-authenticity: The level of confidence that the rated identity 156 is genuine, expressed as a floating-point number between 0.0 and 157 1.0 inclusive. "Genuine" here means the identity being rated is 158 legitimately associated with the real-world entity it represents. 159 For example, a rater might claim a value of 1.0 here if it is 160 certain the rated identity "example.com" is associated with The 161 Example Widget Co, Inc., because it is used in a context where 162 both authentication and authorization on the use of that domain 163 name are assured; the binding between the rated identity and the 164 real-world identity is well established. 166 sample-size: The number of data points used to compute that score, 167 possibly an approximation. Expressed as an unsigned 64-bit 168 integer. Consumers can assume that the count refers to distinct 169 data points rather than a count of aggregations (for example, 170 individual votes rather than aggregated vote counts) unless it is 171 specified out-of-band that some other interpretation is more 172 appropriate. The units are deliberately not normatively 173 specified, since not all reputation service providers will collect 174 data the same way. 176 generated: A timestamp indicating when this value was generated. 177 Expressed as the number of seconds since January 1, 1970 00:00 178 UTC. 180 A particular application that registers itself with IANA (per 181 Section 6.2, below) MAY 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. Scores 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". 209 5. Reputon Structure 210 5.1. Syntax 212 A reputon expressed in JSON consists of an object that itself 213 contains zero or more objects whose names are "reputon". Each 214 reputon object is a set of key-value pairs, where the keys are the 215 names of particular attributes that comprise a reputon (as listed 216 above, or as provided with specific applications), and values are the 217 content associated with those keys. The set of keys that make up a 218 reputon within a given application are known as that application's 219 "response set". 221 An empty reputon is an acknowledgement by the server that the request 222 has been received and serves as a positive indication that the server 223 does not have the information requested. This is semantically 224 equivalent to returning a reputon with a "sample-size" of zero. 226 5.1.1. Formal Definition 228 Using [ABNF], the syntax of a reputon is: 230 reputon = "{" [ reputon-object 231 *(value-separator reputon-object) ] "}" 233 reputon-object = "reputon" name-separator response-set 235 response-set = "{" reputon-element 236 *(value-separator reputon-element) "} 238 reputon-element = rater-value / assertion-value / rated-value 239 / rating-value / conf-value / auth-value 240 / sample-value / gen-value / ext-value 241 ; these can appear in any order 243 rater-value = %x22 "rater" %x22 name-separator string 245 assertion-value = %x22 "assertion" %x22 name-separator string 247 rated-value = %x22 "rated" %x22 name-separator string 249 rating-value = %x22 "rating" %x22 name-separator number 250 ; "number" MUST be between 0.0 and 1.0 inclusive 252 conf-value = %x22 "confidence" %x22 name-separator number 253 ; "number" MUST be between 0.0 and 1.0 inclusive 255 auth-value = %x22 "rater-authenticity" %x22 name-separator number 256 ; "number" MUST be between 0.0 and 1.0 inclusive 258 sample-value = %x22 "sample-size" %x22 name-separator int 259 ; "int" MUST NOT be negative 261 gen-value = %x22 "generated" %x22 name-separator int 262 ; "int" MUST NOT be negative 264 ext-value = member 265 ; specific syntax is specified in specific application 266 ; registrations 268 The tokens "value-separator", "name-separator", "string", "int", and 269 "member" are defined in [JSON]. 271 5.2. Examples 273 The following simple example: 275 Content-type: application/reputon+json 277 { 278 "reputon": 279 { 280 "rater": "RatingsRUs.example.com", 281 "rater-authenticity": 1.0, 282 "assertion": "is-good", 283 "rated": "Alex Rodriguez", 284 "rating": 0.99, 285 "sample-size": 50000 286 } 287 } 289 ...indicates we are absolutely sure (1.0) that the entity 290 "RatingsRUs.example.com" consolidated 50000 data points (perhaps from 291 everyone in Yankee Stadium) and concluded that Alex Rodriguez is very 292 very good (0.99) at something. It doesn't tell us what he's good at, 293 and while it might be playing baseball, it could just as well be 294 paying his taxes on time. 296 A more sophisticated usage would define a baseball application with a 297 response set of specific assertions, so that this example: 299 Content-type: application/reputon+json; context="baseball" 301 { 302 "reputon": 303 { 304 "rater": "baseball-reference.example.com", 305 "rater-authenticity": 1.0, 306 "assertion": "hits-for-power", 307 "rated": "Alex Rodriguez", 308 "rating": 0.99, 309 "sample-size": 50000 310 } 311 } 313 ...would indicate that 50000 fans polled by the entity baseball- 314 reference.example.com rate Alex Rodriguez very highly in hitting for 315 power, whereas this example: 317 Content-type: application/reputon+json; context="baseball" 319 { 320 "reputon": 321 { 322 "rater": "baseball-reference.example.com", 323 "rater-authenticity": 1.0, 324 "assertion": "clutch-hitter", 325 "rated": "Alex Rodriguez", 326 "rating": 0.4, 327 "confidence": 0.2, 328 "sample-size": 50000 329 } 330 } 332 ...would indicate that a similar poll indicated a somewhat weak 333 consensus that Alex Rodriguez tends to choke in critical baseball 334 situations. 336 In practice, it is expected that most reputons will have an "context" 337 parameter to target an application-specific set of assertions. 339 The following is an example reputon generated using this schema, 340 including the media type definition line that idenfities a specific 341 reputation application context. Here, reputation agent 342 "rep.example.net" is asserting within the context of the "email-id" 343 application (see [I-D.REPUTE-EMAIL-IDENTIFIERS]) that "example.com" 344 appears to be associated with spam 1.2% of the time, based on just 345 short of 17 million messages analyzed or reported to date. The 346 "email-id" application has declared the extension key "identity" to 347 indicate how the subject identifier was used in the observed data, 348 establishing some more specific semantics for the "rating" value. In 349 this case, the extension is used to show the identity "example.com", 350 the subject of the query, is extracted from the analyzed messages 351 using the [DKIM] "d=" parameter for messages where signatures 352 validate. The reputation agent is 95% confident of this result. 353 (See [I-D.REPUTE-EMAIL-IDENTIFIERS] for details about the registered 354 email identifiers application.) 355 Content-Type: application/reputon+json; context="email-id" 357 { 358 "reputon": 359 { 360 "rater": "rep.example.net", 361 "rater-authenticity": 0.95, 362 "assertion": "spam", 363 "identity": "dkim", 364 "rated": "example.com", 365 "rating": 0.012, 366 "sample-size": 16938213, 367 "updated": 1317795852 368 } 369 } 371 6. IANA Considerations 373 This document presents two actions for IANA, namely the creation of 374 the new media type "application/reputon+json" and the creation of a 375 registry for reputation application types. Another document in this 376 series creates an initial registry entry for the latter. 378 6.1. application/reputon+json Media Type Registration 380 This section provides the media type registration application from 381 [MIME-REG] for processing by IANA: 383 To: media-types@iana.org 385 Subject: Registration of media type application/reputon+json 387 Type name: application 389 Subtype name: reputon+json 391 Required parameters: none 393 Optional parameters: 395 context: Names the reputation application in use within the 396 reputon, which defines the valid assertions and any extensions 397 that may also be valid (i.e., the response set) for that 398 application. These MUST be registered with IANA in the 399 Reputation Application Registry as described in Section 6.2. 401 Encoding considerations: "7bit" encoding is sufficient and MUST be 402 used to maintain readability when viewed by non-MIME mail readers. 404 Security considerations: See Section 7 of [this document]. 406 Interoperability considerations: Implementers MUST ignore any "app" 407 values, attribute/value pairs, or response set items they do not 408 support. 410 Published specification: [this document] 412 Applications that use this media type: Any application that wishes 413 to query a service that provides reputation data using the "long 414 form" defined in [I-D.REPUTE-QUERY-HTTP]. The example application 415 is one that provides reputation expressions about DNS domain names 416 found in email messages. 418 Additional information: The value of the "app" parameter MUST also 419 be registered with IANA. 421 Person and email address to contact for further information: 423 Nathaniel Borenstein 425 Murray S. Kucherawy 427 Intended usage: COMMON 429 Author: 431 Nathaniel Borenstein 433 Murray S. Kucherawy 435 Change controller: IESG 437 6.2. Reputation Applications Registry 439 IANA is requested to create the "Reputation Applications" registry. 440 This registry will contain names of applications used with the 441 application/reputon+json media type (and other media types that carry 442 reputons), as defined by this document. 444 New registrations or updates MUST be published in accordance with the 445 "Specification Required" guidelines as described in 446 [IANA-CONSIDERATIONS]. 448 New registrations and updates are to contain the following 449 information: 451 1. Name of the application being registered or updated 453 2. Short description of the application (i.e., the class of entity 454 about which it reports reputation data) 456 3. The document in which the application is defined 458 4. New or updated status, which is to be one of: 460 current: The application is in current use 462 deprecated: The application is in current use but its use is 463 discouraged 465 historic: The application is no longer in current use 467 5. A description of the subject of a query within this reputation, 468 and a legal syntax for the same 470 6. An optional table of query parameters that are specific to this 471 application; each table entry must include: 473 Name: Name of the query parameter 475 Status: (as above) 477 Description: A short description of the purpose of this 478 parameter 480 Syntax: A reference to a description of valid syntax for the 481 parameter's value 483 Required: "yes" if the parameter is mandatory, "no" otherwise 485 7. A list of one or more assertions registered within this 486 application; each table entry is to include: 488 Name: Name of the assertion 490 Description: A short description of the assertion, with specific 491 meanings for values of 0.0 and 1.0 493 Scale: A short description of the scale used in computing the 494 value (see Section 4 of this document) 496 8. An optional list of one or more response set extension keys for 497 use within this application; each table entry is to include: 499 Name: Name of the extension key 501 Description: A short description of the key's intended meaning 503 Syntax: A description of valid values that can appear associated 504 with the key 506 The names of attributes registered should be prefixed by the name of 507 the application itself (e.g., the "foo" application registering a 508 "bar" attribute should call it "foo-bar") to avoid namespace 509 collisions. 511 7. Security Considerations 513 This document is primarily an IANA action registering a media type. 514 It does not describe a new protocol that might introduce security 515 considerations. 517 Discussion of the security and operational impacts of using 518 reputation services in general can be found throughout 519 [I-D.REPUTE-CONSIDERATIONS]. 521 8. References 523 8.1. Normative References 525 [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax 526 Specifications: ABNF", STD 68, RFC 5234, January 2008. 528 [I-D.REPUTE-MODEL] 529 Borenstein, N. and M. Kucherawy, "A Model for Reputation 530 Interchange", draft-ietf-repute-model (work in progress), 531 November 2012. 533 [I-D.REPUTE-QUERY-HTTP] 534 Borenstein, N. and M. Kucherawy, "Reputation Data 535 Interchange using HTTP and XML", 536 draft-ietf-repute-query-http (work in progress), 537 November 2012. 539 [JSON] Crockford, D., "The application/json Media Type for 540 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 542 [KEYWORDS] 543 Bradner, S., "Key words for use in RFCs to Indicate 544 Requirement Levels", BCP 14, RFC 2119, March 1997. 546 8.2. Informative References 548 [DKIM] Crocker, D., Ed., Hansen, T., Ed., and M. Kucherawy, Ed., 549 "DomainKeys Identified Mail (DKIM) Signatures", RFC 6376, 550 September 2011. 552 [HTTP] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 553 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 554 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 556 [I-D.REPUTE-CONSIDERATIONS] 557 Kucherawy, M., "Operational Considerations Regarding 558 Reputation Services", draft-ietf-repute-model (work in 559 progress), November 2012. 561 [I-D.REPUTE-EMAIL-IDENTIFIERS] 562 Borenstein, N. and M. Kucherawy, "A Reputation Vocabulary 563 for Email Identifiers", 564 draft-ietf-repute-email-identifiers (work in progress), 565 November 2012. 567 [IANA-CONSIDERATIONS] 568 Narten, T. and H. Alvestrand, "Guidelines for Writing an 569 IANA Considerations Section in RFCs", RFC 5226, May 2008. 571 [MIME-REG] 572 Freed, N. and J. Klensin, "Media Type Specifications and 573 Registration Procedures", RFC 4288, December 2005. 575 Appendix A. Acknowledgments 577 The authors wish to acknowledge the contributions of the following to 578 this specification: Frank Ellermann, Tony Hansen, Jeff Hodges, John 579 Levine, David F. Skoll, and Mykyta Yevstifeyev. 581 Appendix B. Public Discussion 583 Public discussion of this suite of documents takes place on the 584 domainrep@ietf.org mailing list. See 585 https://www.ietf.org/mailman/listinfo/domainrep. 587 Authors' Addresses 589 Nathaniel Borenstein 590 Mimecast 591 203 Crescent St., Suite 303 592 Waltham, MA 02453 593 USA 595 Phone: +1 781 996 5340 596 Email: nsb@guppylake.com 598 Murray S. Kucherawy 599 270 Upland Drive 600 San Francisco, CA 94127 601 USA 603 Email: superuser@gmail.com