idnits 2.17.1 draft-ietf-repute-query-http-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 (May 16, 2013) is 3998 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: November 17, 2013 May 16, 2013 7 A Reputation Query Protocol 8 draft-ietf-repute-query-http-06 10 Abstract 12 This document defines a mechanism to conduct queries for reputation 13 information over the Hypertext Transfer Protocol using JSON as the 14 payload meta-format. 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 17, 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. Key Words . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 2.2. Other Definitions . . . . . . . . . . . . . . . . . . . . . 3 54 3. Description . . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 3.2. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 3.3. URI Template . . . . . . . . . . . . . . . . . . . . . . . 5 58 3.4. Response . . . . . . . . . . . . . . . . . . . . . . . . . 6 59 3.5. Protocol Support . . . . . . . . . . . . . . . . . . . . . 6 60 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 6 61 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 6 62 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7 63 6.1. Normative References . . . . . . . . . . . . . . . . . . . 7 64 6.2. Informative References . . . . . . . . . . . . . . . . . . 7 65 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 8 66 Appendix B. Public Discussion . . . . . . . . . . . . . . . . . . 8 67 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 8 69 1. Introduction 71 This document defines a method to query a reputation data service for 72 information about an entity, using the HyperText Transfer Protocol 73 (HTTP) as the transport mechanism and JSON as the payload meta- 74 format. 76 2. Terminology and Definitions 78 This section defines terms used in the rest of the document. 80 2.1. Key Words 82 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 83 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 84 document are to be interpreted as described in [KEYWORDS]. 86 2.2. Other Definitions 88 Other terms of importance in this document are defined in 89 [I-D.REPUTE-MODEL] and [I-D.REPUTE-MEDIA-TYPE]. 91 3. Description 93 3.1. Overview 95 The components to the question being asked comprise the following: 97 o The subject of the query; 99 o The name of the host, or the IP address, at which the reputation 100 service is available; 102 o The name of the reputation application, i.e., the context within 103 which the subject is being evaluated; 105 o Optionally, name(s) of the specific reputation assertions or 106 attributies that are being requested. 108 The name of the application, if given, MUST be one registered with 109 IANA in the Reputation Applications Registry, which is defined in 110 [I-D.REPUTE-MEDIA-TYPE]. A server receiving a query about an 111 unregistered application or one it does not explicitly support (e.g., 112 by virtue of private agreements or experimental extensions) MUST 113 return a 404 error code. 115 A reputation query made via [HTTP] encodes the question being asked 116 in an HTTP GET method. 118 3.2. Syntax 120 The syntax for the [URI] of the query is constructed using a template 121 as per [URI-TEMPLATE]. (See Section 3.3.) The following variables 122 MUST be available during template expansion: 124 application: The name of the application reputation in whose context 125 the request is being made. 127 scheme: The transport scheme the client will be using for the query. 129 service: The hostname or IP address to which the query is being 130 sent. 132 subject: The subject of the query. 134 Which scheme(s) can be used depends on how the reputation service 135 provider offers its services. Thus, the template could include a 136 specific scheme as a fixed string in the template, or it might offer 137 it as a variable in the template. If it is a variable, it is up to 138 the client and server to negotiate out-of-band which schemes are 139 supported for client queries. Implementers need to be aware that the 140 template could include a fixed scheme not supported by the client. 142 For example, the following query template includes a fixed scheme, 143 forcing clients to use the "http" URI scheme only: 145 http://{service}/repute.php{?subject,application,assertion} 147 However, this template allows the client to select the scheme to be 148 used if, for example, the service is also available over the "https" 149 URI scheme: 151 {scheme}://{service}/repute.php{?subject,application,assertion} 153 The following variables are OPTIONAL to this base specification, but 154 might be required by the template presented for a specific service: 156 assertion: A list of one or more specific assertions of interest to 157 the client. If absent, the server MUST infer that all available 158 assertion information is being requested. 160 Every application space has a set of assertions applicable to its own 161 context. [I-D.REPUTE-MEDIA-TYPE] defines a single assertion assumed 162 to exist in any application that does not define its own assertion 163 set. 165 Other required or optional query parameters might be defined by 166 documents that register new response sets with IANA. Further, other 167 required or optional query parameters might be defined by specific 168 reputation service providers, though these are private arrangements 169 between client and server and will not be registered with IANA. 171 Authentication between reputation client and server is outside the 172 scope of this specificatin. It could be provided through a variety 173 of available transport-based or object-based mechanisms, including a 174 later extension of this specification. 176 3.3. URI Template 178 The template is retrieved by requesting the [WELL-KNOWN-URI] "repute- 179 template" from the host providing reputation service using HTTP. 180 (The registration for this well-known URI is in Section 4.) The 181 server MUST return the template in a reply using the text/plain media 182 type (see [MIME]), and SHOULD include an Expires field (see Section 183 14.21 of [HTTP]) indicating a duration for which the template is to 184 be considered valid by clients and not re-queried. 186 If the template cannot be retrieved (i.e., any HTTP error is 187 returned), the reputation query SHOULD be aborted and/or retried at a 188 later time. Clients SHOULD adhere to the expiration time presented 189 in an Expires field, if present, or otherwise assume that the 190 template is valid for no less than one day and SHOULD NOT repeat the 191 query. 193 The template is expanded, using the variables that are the parameters 194 to the query, and then used as the target for the query itself. For 195 example, given the following template: 197 {scheme}://{service}/{application}/{subject}/{assertion} 199 A query about the use of the domain "example.org" in the "email-id" 200 application context to a service run at "example.com", where that 201 application declares a required "subject" parameter, requesting the 202 "SPAM" reputation assertion, using HTTP to conduct the query with no 203 specific client authentication information, would be formed as 204 follows: 206 http://example.com/email-id/example.org/spam 208 Matching of the attribute name(s) in the template MUST be case- 209 insensitive. 211 3.4. Response 213 The response is expected to be contained in a media type designed to 214 deliver reputons. An media type designed for this purpose, 215 "application/reputon+json", is defined in [I-D.REPUTE-MEDIA-TYPE]. 217 3.5. Protocol Support 219 A client has to implement HTTP in order to retrieve the query 220 template as described in Section 3.3. Accordingly, a server can 221 assume the client will be able to handle a URI template that produces 222 a URI for the query using the "http" scheme. If the template can 223 yield a query string that uses some other URI scheme, there will need 224 to be some out-of-band negotiation of which scheme(s) are supported 225 by the service, and appropriate protocol support in the client. 227 4. IANA Considerations 229 This document registers the "repute-template" well-known URI in the 230 Well-Known URI registry as defined by [WELL-KNOWN-URI], as follows: 232 URI suffix: repute-template 234 Change controller: IETF 236 Specification document(s): [this document] 238 Related information: none 240 5. Security Considerations 242 This document defines particular uses of existing protocols for a 243 specific application. In particular, the basic protocol used for 244 this service is basic HTTP which is not secure without certain 245 extensions. As such, the protocol described here does not itself 246 present new security considerations. 248 Security considerations relevant to email and email authentication 249 can be found in most of the documents listed in the References 250 sections below. Information specific to use of reputation services 251 can be found in [I-D.REPUTE-CONSIDERATIONS]. 253 Reputation mechanisms represent an obvious security concern, in terms 254 of the validity and use of the reputation information. These issues 255 are beyond the scope of this specification. 257 6. References 259 6.1. Normative References 261 [HTTP] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 262 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 263 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 265 [I-D.REPUTE-MEDIA-TYPE] 266 Borenstein, N. and M. Kucherawy, "A Media Type for 267 Reputation Interchange", draft-ietf-repute-media-type 268 (work in progress), November 2012. 270 [I-D.REPUTE-MODEL] 271 Borenstein, N. and M. Kucherawy, "A Model for Reputation 272 Interchange", draft-iet-repute-model (work in progress), 273 November 2012. 275 [KEYWORDS] 276 Bradner, S., "Key words for use in RFCs to Indicate 277 Requirement Levels", BCP 14, RFC 2119, March 1997. 279 [MIME] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 280 Extensions (MIME) Part One: Format of Internet Message 281 Bodies", RFC 2045, November 1996. 283 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 284 Resource Identifier (URI): Generic Syntax", RFC 3986, 285 January 2005. 287 [URI-TEMPLATE] 288 Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 289 and D. Orchard, "URI Template", draft-gregorio-uritemplate 290 (work in progress), September 2011. 292 [WELL-KNOWN-URI] 293 Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 294 Uniform Resource Identifiers (URIs)", RFC 5785, 295 April 2010. 297 6.2. Informative References 299 [I-D.REPUTE-CONSIDERATIONS] 300 Kucherawy, M., "Operational Considerations Regarding 301 Reputation Services", draft-ietf-repute-considerations 302 (work in progress), November 2012. 304 Appendix A. Acknowledgements 306 The authors would like to thank the following for their contributions 307 to this work: Mark Nottingham, David F. Skoll, and Mykyta 308 Yevstifeyev. 310 Appendix B. Public Discussion 312 Public discussion of this set of documents takes place on the 313 domainrep@ietf.org mailing list. See 314 https://www.ietf.org/mailman/listinfo/domainrep. 316 Authors' Addresses 318 Nathaniel Borenstein 319 Mimecast 320 203 Crescent St., Suite 303 321 Waltham, MA 02453 322 USA 324 Phone: +1 781 996 5340 325 Email: nsb@guppylake.com 327 Murray S. Kucherawy 328 270 Upland Drive 329 San Francisco, CA 94127 330 USA 332 Email: superuser@gmail.com