idnits 2.17.1 draft-ietf-repute-query-http-04.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 13, 2012) is 4182 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 2616 (ref. 'HTTP') (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- No information found for draft-iet-repute-model - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'I-D.REPUTE-MODEL' ** Obsolete normative reference: RFC 5785 (ref. 'WELL-KNOWN-URI') (Obsoleted by RFC 8615) Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 3 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: May 17, 2013 November 13, 2012 7 Reputation Data Interchange using HTTP and JSON 8 draft-ietf-repute-query-http-04 10 Abstract 12 This document defines a mechanism to conduct queries for reputation 13 information using the Hypertext Transfer Protocol. 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 May 17, 2013. 32 Copyright Notice 34 Copyright (c) 2012 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. Key Words . . . . . . . . . . . . . . . . . . . . . . . . . 3 52 2.2. Other Definitions . . . . . . . . . . . . . . . . . . . . . 3 53 3. Description . . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 3.1. Query . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 3.2. Response . . . . . . . . . . . . . . . . . . . . . . . . . 5 56 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 5 57 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 5 58 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 6 59 6.1. Normative References . . . . . . . . . . . . . . . . . . . 6 60 6.2. Informative References . . . . . . . . . . . . . . . . . . 6 61 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 6 62 Appendix B. Public Discussion . . . . . . . . . . . . . . . . . . 7 63 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 7 65 1. Introduction 67 This document defines a method to query a reputation data service for 68 information about an entity, using the HyperText Transfer Protocol 69 (HTTP) as the transport mechanism and JSON as the payload format. 71 2. Terminology and Definitions 73 This section defines terms used in the rest of the document. 75 2.1. Key Words 77 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 78 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 79 document are to be interpreted as described in [KEYWORDS]. 81 2.2. Other Definitions 83 Other terms of importance in this document are defined in 84 [I-D.REPUTE-MODEL] and [I-D.REPUTE-MEDIA-TYPE]. 86 3. Description 88 3.1. Query 90 A reputation query made via [HTTP] encodes the question being asked 91 in the GET instruction of the protocol. 93 The components to the question being asked comprise the following: 95 o The subject of the query; 97 o The name of the host, or the IP address, at which the reputation 98 service is available; 100 o The name of the reputation application, i.e., the context within 101 which the query is being made; 103 o Optionally, name(s) of the specific reputation assertions or 104 attributies that are being requested. 106 The name of the application, if given, MUST be one registered with 107 IANA. A server receiving a query about an unregistered application 108 or one it does not explicitly support MUST return a 404 error code. 110 The syntax for the [URI] portion of the query is constructed using a 111 template as per [URI-TEMPLATE]. The following variables MUST be 112 available during template expansion: 114 application: The name of the application reputation in whose context 115 the request is being made. 117 scheme: The transport scheme the client will be using for the query. 119 service: The hostname or IP address being queried. 121 subject: The subject of the query. 123 Which scheme(s) can be used depends on how the reputation service 124 provider offers its services. Thus, the template could include a 125 specific scheme as a fixed string in the template, or it might offer 126 it as a variable in the template. If it is a variable, it is up to 127 the client and server to negotiate out-of-band which schemes are 128 supported for client queries. Implementers need to be aware that the 129 template could include a fixed scheme not supported by the client. 131 The following variables are OPTIONAL, but might be required by the 132 template presented for a specific service: 134 assertion: A list of one or more specific assertions of interest to 135 the client. If absent, the server MUST infer that all available 136 assertion information is being requested. 138 Other required or optional query parameters might be defined by 139 documents that register new response sets with IANA. Further, other 140 required or optional query parameters might be defined by specific 141 reputation service providers, though these are private arrangements 142 between client and server and will not be registered with IANA. 144 Authentication between reputation client and server MAY be 145 accomplished using query extensions, or MAY rely on the capabilities 146 of the transport associated with the selected URI scheme. 148 The template is retrieved by requesting the [WELL-KNOWN-URI] "repute- 149 template" from the host providing reputation service using HTTP. The 150 server SHOULD return the template in a text/plain reply. If the 151 template cannot be retrieved, the reputation query SHOULD be aborted 152 and/or retried at a later time. The server responding to the 153 template request SHOULD include an Expires field indicating a 154 duration for which the template should be considered valid by clients 155 and not re-queried. Clients SHOULD adhere to the expiration time 156 thus provided or, if none is provided, assume that the template is 157 valid for no less than one day and SHOULD NOT repeat the query. 159 For example, given the following template: 161 {scheme}://{service}/{application}/{subject}/{assertion} 163 A query about the use of the domain "example.org" in the "email-id" 164 application context to a service run at "example.com", where that 165 application declares a required "subject" parameter, requesting the 166 "SPAM" reputation assertion using HTTP to conduct the query with no 167 specific client authentication information would be formed as 168 follows: 170 http://example.com/email-id/example.org/spam 172 Matching of the attribute name(s) MUST be case-insensitive. 174 3.2. Response 176 The response is expected to be contained in a media type designed to 177 deliver reputons. An media type designed for this purpose, 178 "application/reputon+json", is defined in [I-D.REPUTE-MEDIA-TYPE]. 180 4. IANA Considerations 182 This document registers the "repute-template" well-known URI in the 183 Well-Known URI registry as defined by [WELL-KNOWN-URI], as follows: 185 URI suffix: repute-template 187 Change controller: IETF 189 Specification document(s): [this document] 191 Related information: none 193 5. Security Considerations 195 This document defines particular uses of existing protocols for a 196 specific application. As such, it does not present new security 197 considerations. 199 Security considerations relevant to email and email authentication 200 can be found in most of the documents listed in the References 201 sections below. Information specific to use of reputation services 202 can be found in [I-D.REPUTE-CONSIDERATIONS]. 204 6. References 206 6.1. Normative References 208 [HTTP] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 209 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 210 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 212 [I-D.REPUTE-MEDIA-TYPE] 213 Borenstein, N. and M. Kucherawy, "A Media Type for 214 Reputation Interchange", draft-ietf-repute-media-type 215 (work in progress), November 2012. 217 [I-D.REPUTE-MODEL] 218 Borenstein, N. and M. Kucherawy, "A Model for Reputation 219 Interchange", draft-iet-repute-model (work in progress), 220 November 2012. 222 [KEYWORDS] 223 Bradner, S., "Key words for use in RFCs to Indicate 224 Requirement Levels", BCP 14, RFC 2119, March 1997. 226 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 227 Resource Identifier (URI): Generic Syntax", RFC 3986, 228 January 2005. 230 [URI-TEMPLATE] 231 Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 232 and D. Orchard, "URI Template", draft-gregorio-uritemplate 233 (work in progress), September 2011. 235 [WELL-KNOWN-URI] 236 Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 237 Uniform Resource Identifiers (URIs)", RFC 5785, 238 April 2010. 240 6.2. Informative References 242 [I-D.REPUTE-CONSIDERATIONS] 243 Kucherawy, M., "Operational Considerations Regarding 244 Reputation Services", draft-ietf-repute-considerations 245 (work in progress), November 2012. 247 Appendix A. Acknowledgements 249 The authors would like to thank the following for their contributions 250 to this work: Mark Nottingham, David F. Skoll, and Mykyta 251 Yevstifeyev. 253 Appendix B. Public Discussion 255 Public discussion of this set of documents takes place on the 256 domainrep@ietf.org mailing list. See 257 https://www.ietf.org/mailman/listinfo/domainrep. 259 Authors' Addresses 261 Nathaniel Borenstein 262 Mimecast 263 203 Crescent St., Suite 303 264 Waltham, MA 02453 265 USA 267 Phone: +1 781 996 5340 268 Email: nsb@guppylake.com 270 Murray S. Kucherawy 271 2063 42nd Avenue 272 San Francisco, CA 94116 273 USA 275 Email: superuser@gmail.com