idnits 2.17.1 draft-kucherawy-reputation-query-http-03.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 (October 21, 2011) is 4565 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 2616 (ref. 'HTTP') (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 5785 (ref. 'WELL-KNOWN-URI') (Obsoleted by RFC 8615) Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group N. Borenstein 3 Internet-Draft Mimecast 4 Intended status: Informational M. Kucherawy 5 Expires: April 23, 2012 Cloudmark 6 October 21, 2011 8 Reputation Data Interchange using HTTP and XML 9 draft-kucherawy-reputation-query-http-03 11 Abstract 13 This document defines a mechanism to conduct queries for reputation 14 information using the Domain Name System. 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 April 23, 2012. 33 Copyright Notice 35 Copyright (c) 2011 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. Document Series . . . . . . . . . . . . . . . . . . . . . . . . 3 52 3. Terminology and Definitions . . . . . . . . . . . . . . . . . . 3 53 3.1. Keywords . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 3.2. Other Definitions . . . . . . . . . . . . . . . . . . . . . 3 55 4. Description . . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 4.1. Query . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 4.2. Response . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 4.2.1. XML Schema . . . . . . . . . . . . . . . . . . . . . . 5 59 4.2.2. Example Reply . . . . . . . . . . . . . . . . . . . . . 7 60 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 8 61 6. Security Considerations . . . . . . . . . . . . . . . . . . . . 8 62 6.1. General . . . . . . . . . . . . . . . . . . . . . . . . . . 8 63 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 64 7.1. Normative References . . . . . . . . . . . . . . . . . . . 8 65 7.2. Informative References . . . . . . . . . . . . . . . . . . 9 66 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 9 67 Appendix B. Public Discussion . . . . . . . . . . . . . . . . . . 9 68 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 9 70 1. Introduction 72 This memo defines a method to query a reputation data service for 73 information about an entity, using the HyperText Transfer Protocol 74 (HTTP) as the transport mechanism and XML as the payload format. It 75 is part of a series defining the overall reputation query/response 76 structure as well as the concept of reputation "vocabularies" for 77 particular applications. 79 2. Document Series 81 This memo represents the media type registration, part of a series of 82 documents that define the overall service and introduce the initial 83 exemplary applications. The series is as follows: 85 1. RFCxxxx: A Model for Reputation Interchange 87 2. RFCxxxx+1: A Media Type for Reputation Information 89 3. RFCxxxx+2: Using UDP for Reputation Interchange 91 4. RFCxxxx+3: Using the DNS for Reputation Interchange 93 5. RFCxxxx+4: Using HTTP/XML for Reputation Interchange (this memo) 95 6. RFCxxxx+5: A Reputation Vocabulary for Email Identity Reputation 97 7. RFCxxxx+6: A Reputation Vocabulary for Email Property Reputation 99 3. Terminology and Definitions 101 This section defines terms used in the rest of the document. 103 3.1. Keywords 105 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 106 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 107 document are to be interpreted as described in [KEYWORDS]. 109 3.2. Other Definitions 111 Other terms of importance in this memo are defined in RFCxxxx, the 112 base memo in this document series. 114 4. Description 116 4.1. Query 118 A reputation query made via [HTTP] encodes the question being asked 119 partly in the [URI] and partly within the GET instruction of the 120 protocol. 122 The components to the question being asked comprise the following: 124 o The subject of the query; 126 o The name of the host, or the IP address, at which the reputation 127 service is available; 129 o The name of the reputation application, i.e., the context within 130 which the query is being made; 132 o Optionally, name(s) of the specific reputation assertions or 133 attributies that are being requested. 135 The name of the application MUST be one registered with IANA. A 136 server receiving a query about an unregistered application or one it 137 does not explicitly support MUST return a 404 error code. 139 The syntax for the URI portion of the query is constructed using a 140 template as per [URI-TEMPLATE]. The following variables MUST be 141 available during template expansion: 143 application: The name of the application reputation in whose context 144 the request is being made. 146 scheme: The transport scheme the client will be using for the query. 148 service: The hostname or IP address being queried. 150 Which scheme(s) can be used depends on how the reputation service 151 provider offers its services. Thus, the template could include a 152 specific schema as a fixed string in the template, or it might offer 153 it as a variable in the template. If it is a variable, it is up to 154 the client and server to negotiate out-of-band which schemes are 155 supported for client queries. Implementers should be aware that the 156 template could include a fixed scheme not supported by the client. 158 The following variables are OPTIONAL, but might be required by the 159 template presented for a specific service: 161 assertion: A list of one or more specific assertions of interest to 162 the client. If absent, the server MUST infer that all available 163 assertion information is being requested. 165 passwd: The "password" portion of a client credential. 167 user: The "user" portion of a client credential. 169 Other required or optional query parameters might be defined by 170 documents that register new vocabularies with IANA. 172 The template is retrieved by requesting the [WELL-KNOWN-URI] 173 "repute_template" from the host providing reputation service using 174 HTTP. If the template cannot be retrieved, the query should be 175 aborted and/or retried at a later time. 177 For example, given the following template: 179 {scheme}://{service}/{application}/{subject}/{assertion} 181 A query about the use of the domain "example.org" in the "email-id" 182 application context to a service run at "example.com", where that 183 application declares a required "subject" parameter, requesting the 184 "SENDS-SPAM" reputation assertion using HTTP to conduct the query 185 with no specific client authentication information would be formed as 186 follows: 188 http://example.com/email-id/example.org/sends-spam 190 Matching of the attribute name(s) MUST be case-insensitive. 192 4.2. Response 194 The response is expected to be an XML document. The "format" 195 parameter of the "application/reputon" media type MUST be "xml" when 196 used in this mode. 198 The XML schema definition describing the format of that response is 199 included below. 201 4.2.1. XML Schema 203 The following XML schema describes the format of the reply: 205 208 209 210 211 212 213 215 216 217 218 219 220 221 222 223 225 226 227 228 229 230 231 232 233 234 235 236 237 239 240 241 243 244 246 247 249 The elements that comprise an "assertion" are used as follows: 251 rater: The identity of the agent making the assertion. 253 rater-authenticity: An expression by the rater of its confidence in 254 the report it is giving. Expressed as a decimal value between 0 255 and 1 inclusive. 257 assertion: The assertion being made. This MUST be an assertion 258 registered within the specified application by IANA. 260 extension: (OPTIONAL) One or more application-specific vocabulary 261 extensions and their corresponding values. If present, each of 262 these MUST be a vocabulary extension registered with IANA. 264 rated: The identity about which an assertion is being made. 266 rating: The value of the assertion. This is a decimal number from 0 267 to 1, with 0 meaning the assertion is completely false (according 268 to the agent making the assertion) and 1 meaning the assertion is 269 completely true. 271 sample-size: The count of data points the asserting agent used to 272 produce the value provided in the previous element. 274 updated: The time at which the current rating was computed. 275 Expressed in number of seconds since 00:00:00 UTC, January 1, 276 1970. 278 4.2.2. Example Reply 280 The following is an example reputon generated using the above schema, 281 including the media type definition line: 283 Content-Type: application/reputon; app="email"; format="xml" 285 287 288 289 rep.example.net 290 0.95 291 SENDS-SPAM 292 IDENTITY: DKIM 293 example.com 294 0.0012 295 16938213 296 1317795852 297 298 300 Here, reputation agent "rep.example.net" is asserting within the 301 context of email that "example.com" appears to send spam 1.2% of the 302 time, based on just short of 17 million messages analyzed or reported 303 to date. The identity "example.com", the subject of the query, is 304 extracted from the analyzed messages using the [DKIM] "d=" parameter 305 for messages where signatures validate. The reputation agent is 95% 306 confident of this result. (See [RFCxxxx+5] for details about the 307 registered email vocabulary.) 309 5. IANA Considerations 311 This memo presents no actions for IANA. Registration of the well- 312 known URI "repute_template" will be done as defined in 313 [WELL-KNOWN-URI] which is not a function of IANA. 315 6. Security Considerations 317 This memo describes security considerations introduced by the media 318 type defined here. 320 6.1. General 322 This memo is part of a series introducing a reputation query and 323 response system (see Section 2). The Security Considerations 324 sections of the other memos should also be consulted. 326 7. References 328 7.1. Normative References 330 [HTTP] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 331 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 332 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 334 [KEYWORDS] 335 Bradner, S., "Key words for use in RFCs to Indicate 336 Requirement Levels", BCP 14, RFC 2119, March 1997. 338 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 339 Resource Identifier (URI): Generic Syntax", RFC 3986, 340 January 2005. 342 [URI-TEMPLATE] 343 Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 344 and D. Orchard, "URI Template", 345 I-D draft-gregorio-uritemplate, September 2011. 347 [WELL-KNOWN-URI] 348 Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 349 Uniform Resource Identifiers (URIs)", RFC 5785, 350 April 2010. 352 7.2. Informative References 354 [DKIM] Crocker, D., Ed., Hansen, T., Ed., and M. Kucherawy, Ed., 355 "DomainKeys Identified Mail (DKIM) Signatures", RFC 6376, 356 September 2011. 358 Appendix A. Acknowledgements 360 The authors would like to thank the following for their contributions 361 to this work: Mark Nottingham. 363 Appendix B. Public Discussion 365 Public discussion of this suite of memos takes place on the 366 domainrep@ietf.org mailing list. See 367 https://www.ietf.org/mailman/listinfo/domainrep. 369 Authors' Addresses 371 Nathaniel Borenstein 372 Mimecast 373 203 Crescent St., Suite 303 374 Waltham, MA 02453 375 USA 377 Phone: +1 781 996 5340 378 Email: nsb@guppylake.com 380 Murray S. Kucherawy 381 Cloudmark 382 128 King St., 2nd Floor 383 San Francisco, CA 94107 384 USA 386 Phone: +1 415 946 3800 387 Email: msk@cloudmark.com