idnits 2.17.1 draft-ietf-repute-media-type-06.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 (March 13, 2013) is 4061 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: September 14, 2013 March 13, 2013 7 A Media Type for Reputation Interchange 8 draft-ietf-repute-media-type-06 10 Abstract 12 This document defines a media type for exchanging reputation 13 information about an arbitrary class of object. 15 Status of this Memo 17 This Internet-Draft is submitted in full conformance with the 18 provisions of BCP 78 and BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF). Note that other groups may also distribute 22 working documents as Internet-Drafts. The list of current Internet- 23 Drafts is at http://datatracker.ietf.org/drafts/current/. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 This Internet-Draft will expire on September 14, 2013. 32 Copyright Notice 34 Copyright (c) 2013 IETF Trust and the persons identified as the 35 document authors. All rights reserved. 37 This document is subject to BCP 78 and the IETF Trust's Legal 38 Provisions Relating to IETF Documents 39 (http://trustee.ietf.org/license-info) in effect on the date of 40 publication of this document. Please review these documents 41 carefully, as they describe your rights and restrictions with respect 42 to this document. Code Components extracted from this document must 43 include Simplified BSD License text as described in Section 4.e of 44 the Trust Legal Provisions and are provided without warranty as 45 described in the Simplified BSD License. 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 50 2. Terminology and Definitions . . . . . . . . . . . . . . . . . 3 51 2.1. Reputon . . . . . . . . . . . . . . . . . . . . . . . . . 3 52 2.2. Key Words . . . . . . . . . . . . . . . . . . . . . . . . 3 53 2.3. Other Definitions . . . . . . . . . . . . . . . . . . . . 3 54 3. Description . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 3.1. Reputon Attributes . . . . . . . . . . . . . . . . . . . . 4 56 4. Scores . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 5. Reputon Structure . . . . . . . . . . . . . . . . . . . . . . 5 58 5.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 5 59 5.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 6 60 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 61 6.1. application/reputon Media Type Registration . . . . . . . 8 62 6.2. Reputation Applications Registry . . . . . . . . . . . . . 9 63 7. Security Considerations . . . . . . . . . . . . . . . . . . . 11 64 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 65 8.1. Normative References . . . . . . . . . . . . . . . . . . . 11 66 8.2. Informative References . . . . . . . . . . . . . . . . . . 12 67 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 12 68 Appendix B. Public Discussion . . . . . . . . . . . . . . . . . . 12 69 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12 71 1. Introduction 73 This document defines a media type for use when answering a 74 reputation query using the "long form" query defined in 75 [I-D.REPUTE-QUERY-HTTP], which uses [HTTP]. 77 Also included is the specification for an IANA registry to contain 78 definitions and symbolic names for known reputation applications and 79 corresponding response sets. 81 2. Terminology and Definitions 83 This section defines terms used in the rest of the document. 85 2.1. Reputon 87 A "reputon" is a single independent object containing reputation 88 information. A particular query about a subject of interest will 89 receive one or more reputons in response, depending on the nature of 90 the data collected and reported by the server. 92 2.2. Key Words 94 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 95 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 96 document are to be interpreted as described in [KEYWORDS]. 98 2.3. Other Definitions 100 Other terms of importance in this document are defined in 101 [I-D.REPUTE-MODEL], the base document in this document series. 103 3. Description 105 The format selected for the representaton of a reputon is Javascript 106 Object Notation (JSON), defined in [JSON]. Accordingly, a new media 107 type, "application/reputon+json", is defined for the JSON 108 representation of reputational data, typically in response to a 109 client making a request for such data about some subject. This media 110 type has one optional parameter, "subject", which defines the 111 specific reputation application in whose context the query is made 112 and the response returned. If the parameter is absent, a generic 113 reputation query (i.e., one not associated with a specific reputation 114 application) is assumed for which only a simple reply is allowed. 116 The body of the media type consists of a JSON document that contains 117 the reputation information requested. A detailed description of the 118 expected structure of the reply is provided below. 120 3.1. Reputon Attributes 122 The key pieces of data found in a reputon for all reputation 123 applications are defined as follows: 125 rater: The identity of the entity providing the reputation 126 information, typically expressed as a DNS domain name. 128 assertion: A keyword indicating the specific assertion or claim 129 being rated. In the absence of an "subject" parameter on the 130 media type, the reputon can only indicate generic goodness, with 131 the default assertion "is-good", but each application is expected 132 to define additional assertions. 134 rated: The identity of the entity being rated. The nature of this 135 field is application-specific; it could be domain names, email 136 addresses, driver's license numbers, or anything that uniquely 137 identifies the entity being rated. Documents that define specific 138 reputation applications are required to define syntax and 139 semantics for this field. 141 rating: The overall rating score for that entity, expressed as a 142 floating-point number between 0.0 and 1.0 inclusive. See 143 Section 4 for discussion. 145 The following are OPTIONAL for all applications, to be used in 146 contexts where they are appropriate: 148 confidence: the level of certainty the reputation provider has that 149 the value presented is appropriate, expressed as a floating-point 150 number between 0.0 and 1.0 inclusive. 152 rater-authenticity: The level of confidence that the rated identity 153 is genuine, expressed as a floating-point number between 0.0 and 154 1.0 inclusive. 156 sample-size: The number of data points used to compute that score, 157 possibly an approximation. Expressed as an unsigned 64-bit 158 integer. Consumers can assume that the count refers to distinct 159 data points rather than a count of aggregations (for example, 160 individual votes rather than aggregated vote counts) unless it is 161 specified out-of-band that some other interpretation is more 162 appropriate. The units are deliberately not normatively 163 specified, since not all reputation service providers will collect 164 data the same way. 166 updated: A timestamp indicating when this value was generated. 167 Expressed as the number of seconds since January 1, 1970 00:00 168 UTC. 170 A particular application that registers itself with IANA MAY define 171 additional application-specific attribute/value pairs beyond these 172 standard ones. 174 An application service provider might operate an enhanced service, 175 which might in turn prompt development and reporting of specialized 176 reputation information. The details of the enhancements and 177 specialized information are beyond the scope of this document, except 178 that the underlying JSON syntax is extensible for encoding such 179 provider-specific information. 181 4. Scores 183 The score presented as the value in the rating attribute appears as a 184 floating point value between 0.0 and 1.0 inclusive. The intent is 185 that the definition of an assertion within an application will 186 declare what the anchor values 0.0 and 1.0 specifically mean. 187 Generally speaking, 1.0 implies full agreement with the assertion, 188 while 0.0 indicates no support for the assertion. 190 The definition will also specify the type of scale in use when 191 generating scores, to which all reputation service providers for that 192 application space must adhere. This will allow a client to change 193 which reputation service provider is being queried for a given 194 without having to learn through some out-of-band method what the new 195 provider's values mean. For example, a registration might state that 196 ratings are linear, which would mean a score of "x" is twice as 197 strong as a value of "x/2". 199 5. Reputon Structure 201 5.1. Syntax 203 A reputon expressed in JSON consists of an object that itself 204 contains zero or more objects whose names are "reputon". Each 205 reputon object is a set of key-value pairs, where the keys are the 206 names of particular attributes that comprise a reputon (as listed 207 above, or as provided with specific applications), and values are the 208 content associated with those keys. The set of keys that make up a 209 reputon within a given application are known as that application's 210 "response set". 212 An empty reputon can be interpreted by the recipient as 213 acknowledgement of the request by the server, and a positive 214 indication that the server does not have the information requested. 215 This is semantically equivalent to returning a reputon with a 216 "sample-size" of zero. 218 5.2. Examples 220 The following simple example: 222 Content-type: application/reputon+json 224 { 225 "reputon": 226 { 227 "rater": "RatingsRUs.example.com", 228 "rater-authenticity": 1.0, 229 "assertion": "is-good", 230 "rated": "Alex Rodriguez", 231 "rating": 0.99, 232 "sample-size": 50000 233 } 234 } 236 ...indicates we are absolutely sure (1.0) that the entity 237 "RatingsRUs.example.com" consolidated 50000 data points (perhaps from 238 everyone in Yankee Stadium) and concluded that Alex Rodriguez is very 239 very good (0.99) at something. It doesn't tell us what he's good at, 240 and while it might be playing baseball, it could just as well be 241 paying his taxes on time. 243 A more sophisticated usage would define a baseball application with a 244 response set of specific assertions, so that this example: 246 Content-type: application/reputon+json; subject="baseball" 248 { 249 "reputon": 250 { 251 "rater": "baseball-reference.example.com", 252 "rater-authenticity": 1.0, 253 "assertion": "hits-for-power", 254 "rated": "Alex Rodriguez", 255 "rating": 0.99, 256 "sample-size": 50000 257 } 258 } 260 ...would indicate that 50000 fans polled by the entity baseball- 261 reference.example.com rate Alex Rodriguez very highly in hitting for 262 power, whereas this example: 264 Content-type: application/reputon+json; subject="baseball" 266 { 267 "reputon": 268 { 269 "rater": "baseball-reference.example.com", 270 "rater-authenticity": 1.0, 271 "assertion": "clutch-hitter", 272 "rated": "Alex Rodriguez", 273 "rating": 0.4, 274 "confidence": 0.2, 275 "sample-size": 50000 276 } 277 } 279 ...would indicate that a similar poll indicated a somewhat weak 280 consensus that Alex Rodriguez tends to choke in critical baseball 281 situations. 283 In practice, most usage of reputons is expected to make use of the 284 "subject" parameter to target an application-specific set of 285 assertions. 287 The following is an example reputon generated using this schema, 288 including the media type definition line that idenfities a specific 289 reputation application context. Here, reputation agent 290 "rep.example.net" is asserting within the context of the "email-id" 291 application (see [I-D.REPUTE-EMAIL-IDENTIFIERS]) that "example.com" 292 appears to be associated with spam 1.2% of the time, based on just 293 short of 17 million messages analyzed or reported to date. The 294 "email-id" application has declared the extension key "identity" to 295 indicate how the subject identifier was used in the observed data, 296 establishing some more specific semantics for the "rating" value. In 297 this case, the extension is used to show the identity "example.com", 298 the subject of the query, is extracted from the analyzed messages 299 using the [DKIM] "d=" parameter for messages where signatures 300 validate. The reputation agent is 95% confident of this result. 301 (See [I-D.REPUTE-EMAIL-IDENTIFIERS] for details about the registered 302 email identifiers application.) 303 Content-Type: application/reputon+json; subject="email-id" 305 { 306 "reputon": 307 { 308 "rater": "rep.example.net", 309 "rater-authenticity": 0.95, 310 "assertion": "spam", 311 "identity": "dkim", 312 "rated": "example.com", 313 "rating": 0.012, 314 "sample-size": 16938213, 315 "updated": 1317795852 316 } 317 } 319 6. IANA Considerations 321 This document presents two actions for IANA, namely the creation of 322 the new media type "application/reputon+json" and the creation of a 323 registry for reputation application types. Another document in this 324 series creates an initial registry entry for the latter. 326 6.1. application/reputon Media Type Registration 328 This section provides the media type registration application from 329 [MIME-REG] for processing by IANA: 331 To: media-types@iana.org 333 Subject: Registration of media type application/reputon 335 Type name: application 337 Subtype name: reputon+json 339 Required parameters: none 341 Optional parameters: 343 subject: Names the reputation application in use within the 344 reputon, which defines the valid assertions and any extensions 345 that may also be valid (i.e., the response set) for that 346 application. These MUST be registered with IANA in the 347 Reputation Application Registry as described in Section 6.2. 349 Encoding considerations: "7bit" encoding is sufficient and MUST be 350 used to maintain readability when viewed by non-MIME mail readers. 352 Security considerations: See Section 7 of [this document]. 354 Interoperability considerations: Implementers MUST ignore any "app" 355 values, attribute/value pairs, or response set items they do not 356 support. 358 Published specification: [this document] 360 Applications that use this media type: Any application that wishes 361 to query a service that provides reputation data using the "long 362 form" defined in [I-D.REPUTE-QUERY-HTTP]. The example application 363 is one that provides reputation expressions about DNS domain names 364 found in email messages. 366 Additional information: The value of the "app" parameter MUST also 367 be registered with IANA. 369 Person and email address to contact for further information: 371 Nathaniel Borenstein 373 Murray S. Kucherawy 375 Intended usage: COMMON 377 Author: 379 Nathaniel Borenstein 381 Murray S. Kucherawy 383 Change controller: IESG 385 6.2. Reputation Applications Registry 387 IANA is requested to create the "Reputation Applications" registry. 388 This registry will contain names of applications used with the 389 application/reputon+json media type (and other media types that carry 390 reputons), as defined by this document. 392 New registrations or updates MUST be published in accordance with the 393 "Specification Required" guidelines as described in 394 [IANA-CONSIDERATIONS]. 396 New registrations and updates are to contain the following 397 information: 399 1. Name of the application being registered or updated 401 2. Short description of the application (i.e., the class of entity 402 about which it reports reputation data) 404 3. The document in which the application is defined 406 4. New or updated status, which is to be one of: 408 current: The application is in current use 410 deprecated: The application is in current use but its use is 411 discouraged 413 historic: The application is no longer in current use 415 5. A description of the subject of a query within this reputation, 416 and a legal syntax for the same 418 6. An optional table of query parameters that are specific to this 419 application; each table entry must include: 421 Name: Name of the query parameter 423 Status: (as above) 425 Description: A short description of the purpose of this 426 parameter 428 Syntax: A reference to a description of valid syntax for the 429 parameter's value 431 Required: "yes" if the parameter is mandatory, "no" otherwise 433 7. A list of one or more assertions registered within this 434 application; each table entry is to include: 436 Name: Name of the assertion 438 Description: A short description of the assertion, with specific 439 meanings for values of 0.0 and 1.0 441 Scale: A short description of the scale used in computing the 442 value (see Section 4 of this document) 444 8. An optional list of one or more response set extension keys for 445 use within this application; each table entry is to include: 447 Name: Name of the extension key 449 Description: A short description of the key's intended meaning 451 Syntax: A description of valid values that can appear associated 452 with the key 454 The names of attributes registered should be prefixed by the name of 455 the application itself (e.g., the "foo" application registering a 456 "bar" attribute should call it "foo-bar") to avoid namespace 457 collisions. 459 7. Security Considerations 461 This document is primarily an IANA action registering a media type. 462 It does not describe a new protocol that might introduce security 463 considerations. 465 Discussion of the security and operational impacts of using 466 reputation services in general can be found throughout 467 [I-D.REPUTE-CONSIDERATIONS]. 469 8. References 471 8.1. Normative References 473 [I-D.REPUTE-MODEL] 474 Borenstein, N. and M. Kucherawy, "A Model for Reputation 475 Interchange", draft-ietf-repute-model (work in progress), 476 November 2012. 478 [I-D.REPUTE-QUERY-HTTP] 479 Borenstein, N. and M. Kucherawy, "Reputation Data 480 Interchange using HTTP and XML", 481 draft-ietf-repute-query-http (work in progress), 482 November 2012. 484 [JSON] Crockford, D., "The application/json Media Type for 485 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 487 [KEYWORDS] 488 Bradner, S., "Key words for use in RFCs to Indicate 489 Requirement Levels", BCP 14, RFC 2119, March 1997. 491 8.2. Informative References 493 [DKIM] Crocker, D., Ed., Hansen, T., Ed., and M. Kucherawy, Ed., 494 "DomainKeys Identified Mail (DKIM) Signatures", RFC 6376, 495 September 2011. 497 [HTTP] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 498 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 499 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 501 [I-D.REPUTE-CONSIDERATIONS] 502 Kucherawy, M., "Operational Considerations Regarding 503 Reputation Services", draft-ietf-repute-model (work in 504 progress), November 2012. 506 [I-D.REPUTE-EMAIL-IDENTIFIERS] 507 Borenstein, N. and M. Kucherawy, "A Reputation Vocabulary 508 for Email Identifiers", 509 draft-ietf-repute-email-identifiers (work in progress), 510 November 2012. 512 [IANA-CONSIDERATIONS] 513 Narten, T. and H. Alvestrand, "Guidelines for Writing an 514 IANA Considerations Section in RFCs", RFC 5226, May 2008. 516 [MIME-REG] 517 Freed, N. and J. Klensin, "Media Type Specifications and 518 Registration Procedures", RFC 4288, December 2005. 520 Appendix A. Acknowledgments 522 The authors wish to acknowledge the contributions of the following to 523 this specification: Frank Ellermann, Tony Hansen, Jeff Hodges, John 524 Levine, David F. Skoll, and Mykyta Yevstifeyev. 526 Appendix B. Public Discussion 528 Public discussion of this suite of documents takes place on the 529 domainrep@ietf.org mailing list. See 530 https://www.ietf.org/mailman/listinfo/domainrep. 532 Authors' Addresses 534 Nathaniel Borenstein 535 Mimecast 536 203 Crescent St., Suite 303 537 Waltham, MA 02453 538 USA 540 Phone: +1 781 996 5340 541 Email: nsb@guppylake.com 543 Murray S. Kucherawy 544 2063 42nd Avenue 545 San Francisco, CA 94116 546 USA 548 Email: superuser@gmail.com