idnits 2.17.1 draft-ietf-repute-query-http-00.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 (November 19, 2011) is 4541 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) == Missing Reference: 'TBD' is mentioned on line 303, but not defined ** 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 (~~), 2 warnings (==), 1 comment (--). 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: May 22, 2012 Cloudmark 6 November 19, 2011 8 Reputation Data Interchange using HTTP and XML 9 draft-ietf-repute-query-http-00 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 May 22, 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. Terminology and Definitions . . . . . . . . . . . . . . . . . . 3 52 2.1. Keywords . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 2.2. Other Definitions . . . . . . . . . . . . . . . . . . . . . 3 54 3. Description . . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 3.1. Query . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 3.2. Response . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 3.2.1. XML Schema . . . . . . . . . . . . . . . . . . . . . . 5 58 3.2.2. Example Reply . . . . . . . . . . . . . . . . . . . . . 7 59 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 8 60 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 8 61 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 62 6.1. Normative References . . . . . . . . . . . . . . . . . . . 8 63 6.2. Informative References . . . . . . . . . . . . . . . . . . 9 64 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 9 65 Appendix B. Public Discussion . . . . . . . . . . . . . . . . . . 9 66 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 9 68 1. Introduction 70 This memo defines a method to query a reputation data service for 71 information about an entity, using the HyperText Transfer Protocol 72 (HTTP) as the transport mechanism and XML as the payload format. It 73 is part of a series defining the overall reputation query/response 74 structure as well as the concept of reputation "vocabularies" for 75 particular applications. 77 2. Terminology and Definitions 79 This section defines terms used in the rest of the document. 81 2.1. Keywords 83 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 84 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 85 document are to be interpreted as described in [KEYWORDS]. 87 2.2. Other Definitions 89 Other terms of importance in this memo are defined in RFCxxxx, the 90 base memo in this document series. 92 3. Description 94 3.1. Query 96 A reputation query made via [HTTP] encodes the question being asked 97 partly in the [URI] and partly within the GET instruction of the 98 protocol. 100 The components to the question being asked comprise the following: 102 o The subject of the query; 104 o The name of the host, or the IP address, at which the reputation 105 service is available; 107 o The name of the reputation application, i.e., the context within 108 which the query is being made; 110 o Optionally, name(s) of the specific reputation assertions or 111 attributies that are being requested. 113 The name of the application MUST be one registered with IANA. A 114 server receiving a query about an unregistered application or one it 115 does not explicitly support MUST return a 404 error code. 117 The syntax for the URI portion of the query is constructed using a 118 template as per [URI-TEMPLATE]. The following variables MUST be 119 available during template expansion: 121 application: The name of the application reputation in whose context 122 the request is being made. 124 scheme: The transport scheme the client will be using for the query. 126 service: The hostname or IP address being queried. 128 Which scheme(s) can be used depends on how the reputation service 129 provider offers its services. Thus, the template could include a 130 specific schema as a fixed string in the template, or it might offer 131 it as a variable in the template. If it is a variable, it is up to 132 the client and server to negotiate out-of-band which schemes are 133 supported for client queries. Implementers should be aware that the 134 template could include a fixed scheme not supported by the client. 136 The following variables are OPTIONAL, but might be required by the 137 template presented for a specific service: 139 assertion: A list of one or more specific assertions of interest to 140 the client. If absent, the server MUST infer that all available 141 assertion information is being requested. 143 passwd: The "password" portion of a client credential. 145 user: The "user" portion of a client credential. 147 Other required or optional query parameters might be defined by 148 documents that register new vocabularies with IANA. 150 The template is retrieved by requesting the [WELL-KNOWN-URI] 151 "repute_template" from the host providing reputation service using 152 HTTP. If the template cannot be retrieved, the query should be 153 aborted and/or retried at a later time. The server responding to the 154 template request SHOULD include an Expires field indicating a 155 duration for which the template should be considered valid by clients 156 and not re-queried. Clients SHOULD adhere to the expiration time 157 thus provided or, if none is provided, assume that the template is 158 valid for no less than one day and not repeat the query. 160 For example, given the following template: 162 {scheme}://{service}/{application}/{subject}/{assertion} 164 A query about the use of the domain "example.org" in the "email-id" 165 application context to a service run at "example.com", where that 166 application declares a required "subject" parameter, requesting the 167 "SENDS-SPAM" reputation assertion using HTTP to conduct the query 168 with no specific client authentication information would be formed as 169 follows: 171 http://example.com/email-id/example.org/sends-spam 173 Matching of the attribute name(s) MUST be case-insensitive. 175 3.2. Response 177 The response is expected to be an XML document. The "format" 178 parameter of the "application/reputon" media type MUST be "xml" when 179 used in this mode. 181 The XML schema definition describing the format of that response is 182 included below. 184 3.2.1. XML Schema 186 The following XML schema describes the format of the reply: 188 191 192 193 194 195 196 198 199 200 201 202 203 204 205 206 208 209 210 211 212 213 214 215 216 217 218 219 220 222 223 224 226 227 229 230 232 The elements that comprise an "assertion" are used as follows: 234 rater: The identity of the agent making the assertion. 236 rater-authenticity: An expression by the rater of its confidence in 237 the report it is giving. Expressed as a decimal value between 0 238 and 1 inclusive. 240 assertion: The assertion being made. This MUST be an assertion 241 registered within the specified application by IANA. 243 extension: (OPTIONAL) One or more application-specific vocabulary 244 extensions and their corresponding values. If present, each of 245 these MUST be a vocabulary extension registered with IANA. 247 rated: The identity about which an assertion is being made. 249 rating: The value of the assertion. This is a decimal number from 0 250 to 1, with 0 meaning the assertion is completely false (according 251 to the agent making the assertion) and 1 meaning the assertion is 252 completely true. 254 sample-size: The count of data points the asserting agent used to 255 produce the value provided in the previous element. 257 updated: The time at which the current rating was computed. 258 Expressed in number of seconds since 00:00:00 UTC, January 1, 259 1970. 261 3.2.2. Example Reply 263 The following is an example reputon generated using the above schema, 264 including the media type definition line: 266 Content-Type: application/reputon; app="email"; format="xml" 268 270 271 272 rep.example.net 273 0.95 274 SENDS-SPAM 275 IDENTITY: DKIM 276 example.com 277 0.0012 278 16938213 279 1317795852 280 281 283 Here, reputation agent "rep.example.net" is asserting within the 284 context of email that "example.com" appears to send spam 1.2% of the 285 time, based on just short of 17 million messages analyzed or reported 286 to date. The identity "example.com", the subject of the query, is 287 extracted from the analyzed messages using the [DKIM] "d=" parameter 288 for messages where signatures validate. The reputation agent is 95% 289 confident of this result. (See [RFCxxxx+5] for details about the 290 registered email vocabulary.) 292 4. IANA Considerations 294 This memo presents no actions for IANA. Registration of the well- 295 known URI "repute_template" will be done as defined in 296 [WELL-KNOWN-URI] which is not a function of IANA. 298 5. Security Considerations 300 This memo describes security considerations introduced by the query 301 mechanism defined here. 303 [TBD] 305 6. References 307 6.1. Normative References 309 [HTTP] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 310 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 311 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 313 [KEYWORDS] 314 Bradner, S., "Key words for use in RFCs to Indicate 315 Requirement Levels", BCP 14, RFC 2119, March 1997. 317 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 318 Resource Identifier (URI): Generic Syntax", RFC 3986, 319 January 2005. 321 [URI-TEMPLATE] 322 Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 323 and D. Orchard, "URI Template", 324 I-D draft-gregorio-uritemplate, September 2011. 326 [WELL-KNOWN-URI] 327 Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 328 Uniform Resource Identifiers (URIs)", RFC 5785, 329 April 2010. 331 6.2. Informative References 333 [DKIM] Crocker, D., Ed., Hansen, T., Ed., and M. Kucherawy, Ed., 334 "DomainKeys Identified Mail (DKIM) Signatures", RFC 6376, 335 September 2011. 337 Appendix A. Acknowledgements 339 The authors would like to thank the following for their contributions 340 to this work: Mark Nottingham, and David F. Skoll. 342 Appendix B. Public Discussion 344 Public discussion of this suite of memos takes place on the 345 domainrep@ietf.org mailing list. See 346 https://www.ietf.org/mailman/listinfo/domainrep. 348 Authors' Addresses 350 Nathaniel Borenstein 351 Mimecast 352 203 Crescent St., Suite 303 353 Waltham, MA 02453 354 USA 356 Phone: +1 781 996 5340 357 Email: nsb@guppylake.com 359 Murray S. Kucherawy 360 Cloudmark 361 128 King St., 2nd Floor 362 San Francisco, CA 94107 363 USA 365 Phone: +1 415 946 3800 366 Email: msk@cloudmark.com