idnits 2.17.1 draft-ietf-repute-query-http-11.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 (September 12, 2013) is 3878 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) -- Obsolete informational reference (is this intentional?): RFC 2818 (ref. 'HTTPS') (Obsoleted by RFC 9110) Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 4 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: March 16, 2014 September 12, 2013 7 A Reputation Query Protocol 8 draft-ietf-repute-query-http-11 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 March 16, 2014. 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. URI Template . . . . . . . . . . . . . . . . . . . . . . . 4 57 3.3. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 3.4. Response . . . . . . . . . . . . . . . . . . . . . . . . . 6 59 3.5. Protocol Support . . . . . . . . . . . . . . . . . . . . . 7 60 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7 61 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 7 62 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 63 6.1. Normative References . . . . . . . . . . . . . . . . . . . 8 64 6.2. Informative References . . . . . . . . . . . . . . . . . . 9 65 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 9 66 Appendix B. Public Discussion . . . . . . . . . . . . . . . . . . 9 67 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 9 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 The mechanism is a two-stage query: 78 1. A client retrieves a template from a server that describes the 79 construction of a Universal Resource Identifier (URI) which will 80 be the actual query; 82 2. The client then uses the constructed URI to request the 83 reputation data from the server. 85 2. Terminology and Definitions 87 This section defines terms used in the rest of the document. 89 2.1. Key Words 91 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 92 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 93 document are to be interpreted as described in [KEYWORDS]. 95 2.2. Other Definitions 97 Other terms of importance in this document are defined in 98 [I-D.REPUTE-MODEL] and [I-D.REPUTE-MEDIA-TYPE]. 100 3. Description 102 3.1. Overview 104 The components to the question being asked comprise the following: 106 o The subject of the query; 108 o The name of the host, or the IP address, at which the reputation 109 service is available; 111 o The name of the reputation application, i.e., the context within 112 which the subject is being evaluated; 114 o Optionally, name(s) of the specific reputation assertions or 115 attributes that are being requested. 117 There is no discovery protocol for finding reputation services. 118 These are typically subscription services, negotiated between 119 operators through some out-of-band method. 121 Assertions are discussed in [I-D.REPUTE-MEDIA-TYPE]. 123 The name of the application, if given, is expected to be one 124 registered with IANA in the Reputation Applications Registry, which 125 is defined in [I-D.REPUTE-MEDIA-TYPE]. A server receiving a query 126 about an application it does not recognize or explicitly support 127 (e.g., by virtue of private agreements or experimental extensions) 128 MUST return a 404 error code. 130 A reputation query made via [HTTP] encodes the question being asked 131 in an HTTP GET method. The specific syntax of the query itself is 132 specified by retrieving a URI template from the reputation service, 133 completing the template, and then issuing the query. 135 3.2. URI Template 137 The template file is retrieved by requesting the [WELL-KNOWN-URI] 138 "repute-template" from the host providing reputation service, using 139 HTTP. (The registration for this well-known URI is in Section 4.) 140 The server returns the template file in a reply that MUST use the 141 text/plain media type (see [MIME]), and SHOULD include an Expires 142 field (see Section 14.21 of [HTTP]) indicating a duration for which 143 the template is to be considered valid by clients and not re-queried. 145 If an Expires field is present, the client SHOULD NOT send another 146 query to the same server prior to the timestamp in the field. If no 147 Expires field is present, the client SHOULD wait at least one day 148 before sending another query to the same server (i.e., the client 149 assumes a default expiration of one day). 151 The template file might contain more than one template. Such a file 152 MUST have each template separated by a carriage return (ASCII 0x0D) 153 and newline (ASCII 0x0A) character, as is typical for most text-based 154 Internet protocols. 156 Each template in the file is expanded using the variables that are 157 the parameters to the query. These parameters are either the subject 158 about which reputation information is sought (or details associated 159 with it), or other parameters that are established out-of-band with 160 the reputation service; they are not established by any automated 161 discovery described here. The client then attempts to query each 162 expanded template that uses a URI scheme it is capable of querying, 163 in the order presented in the file, until the client finds one to 164 which it can establish a usable connection and issue the query. 166 For example, given the following template: 168 http://{service}/{application}/{subject}/{assertion} 170 A query about the use of the domain "example.org" in the "email-id" 171 application context to a service run at "example.com", where that 172 application declares a required "subject" parameter, requesting the 173 "SPAM" reputation assertion, would be formed as follows: 175 http://example.com/email-id/example.org/spam 177 3.3. Syntax 179 The syntax for the [URI] of the query is constructed using a template 180 as per [URI-TEMPLATE]. (See Section 3.2.) Clients MUST provide the 181 following values in the expansion of the template: 183 application: The name of the application reputation in whose context 184 the request is being made. These names are registered with IANA, 185 and conform to the ABNF "token" found in [MIME]. 187 service: The hostname or IP address to which the query is being 188 sent. This MUST be the same as the host to which the template 189 query was issued. 191 subject: The subject of the query, extracted from some content to be 192 evaluated. The subject portion of the template conforms to the 193 ABNF "value" found in [MIME]. 195 The following variable can also be provided. It is not mandatory in 196 this model, but a specific application (defined in its own extension 197 document) might declare it mandatory in a specific context: 199 assertion: The name of the specific assertion of interest to the 200 client. Assertion names conform to the ABNF "token" found in 201 [MIME]. If absent, the client is indicating that it requests all 202 available assertion information. 204 If a template contains a variable that is not required and the client 205 does not have a value to insert, it substitutes the empty string into 206 the template in place of that variable. Service providers crafting 207 templates MUST do so such that a client doing an empty variable 208 expansion will still produce a syntactically and semantically valid 209 and non-ambiguous URI. For example, given this template: 211 http://{service}/{application}/{subject}/{assertion}/{a}/{b} 213 If "{a}" and "{b}" are optional and "{a}" expands to the empty 214 string, then the resulting URI will have adjacent backslash ("/", 215 ASCII 0x2F) characters and one path component after the assertion. 216 If the server interpreting the URI's path component removes or 217 ignores adjacent backslash characters (such as is done with the UNIX 218 filesystem), the server will be unable to distinguish an empty "{a}" 219 from an empty "{b}", and it could serve the wrong response. Where 220 possible, the template needs to be constructed such that expansion of 221 optional variables yields an unambiguous result. For example, non- 222 ambiguous version of the above would be: 224 http://{service}/{application}/{subject}/{assertion}/a={a}/b={b} 226 ...or, even better, using URI template set expansions: 228 http://{service}/{application}/{subject}/{assertion}{?a,b} 230 Every application space has a set of assertions applicable to its own 231 context. [I-D.REPUTE-MEDIA-TYPE] defines a single assertion assumed 232 to exist in any application that does not define its own assertion 233 set. 235 Reputation applications can extend the set of optional or required 236 query parameters as part of their IANA registration actions. The set 237 enumerated above establishes the base set common to all of them. 238 Further, additional required or optional extension query parameters 239 might be defined by specific reputation service providers, though 240 these are private arrangements between client and server and will not 241 be registered with IANA. 243 Authentication between reputation client and server is outside the 244 scope of this specification. It could be provided through a variety 245 of available transport-based or object-based mechanisms, including a 246 later extension of this specification. 248 3.4. Response 250 The response is expected to be contained in a media type designed to 251 deliver reputons. An media type designed for this purpose, 252 "application/reputon+json", is defined in [I-D.REPUTE-MEDIA-TYPE]. 254 If the server generates responses that contain an Expires field (see 255 Section 14.21 of [HTTP]), that timestamp MUST align with the 256 "expires" field within the response, if any. Failing to do so can 257 result in a state where the response has expired, but the HTTP reply 258 has not, and the client would in that case be unable to get a fresh 259 answer from the reputation server. 261 3.5. Protocol Support 263 A client has to implement HTTP in order to retrieve the query 264 template as described in Section 3.2. Accordingly, a server can 265 assume the client will be able to handle a URI template that produces 266 a URI for the query using the "http" URI scheme. The template could 267 yield a query string that uses some other URI scheme, in which case 268 the client could try that URI as well if it supports issuing queries 269 with that URI scheme. 271 A server SHOULD include support for providing service over HTTP, and 272 publish templates indicating support for this, as a baseline for 273 interoperability with arbitrary clients. 275 4. IANA Considerations 277 This document registers the "repute-template" well-known URI in the 278 Well-Known URI registry as defined by [WELL-KNOWN-URI], as follows: 280 URI suffix: repute-template 282 Change controller: IETF 284 Specification document(s): [this document] 286 Related information: none 288 5. Security Considerations 290 This document defines particular uses of existing protocols for a 291 specific application. In particular, the basic protocol used for 292 this service to retrieve a URI template from a well-known location is 293 basic HTTP, which is not secure without certain extensions. Security 294 issues relevant to use of URI templates are discussed in 295 [URI-TEMPLATE], and those relevant to well-known URI definitions and 296 retrieval are discussed in [WELL-KNOWN-URI]. 298 The reputation service itself will use HTTP or other transport 299 methods to issue queries and receive replies. Those protocols have 300 registered URI schemes and, as such, presumably have documented 301 security considerations. The protocol described here operates atop 302 those URI schemes, and does not itself present new security 303 considerations. 305 Reputation mechanisms represent an obvious security concern, in terms 306 of the validity and use of the reputation information. These issues 307 are beyond the scope of this specification. General information 308 pertaining to using or providing reputation services can be found in 309 [I-D.REPUTE-CONSIDERATIONS]. 311 The security considerations applicable to HTTP (see Section 15 of 312 [HTTP] apply, since this query mechanism for reputation uses that 313 protocol. If it is desirable to conceal the content of the query and 314 its response, use of encryption techniques such as HTTP over TLS 315 [HTTPS] can be used. 317 6. References 319 6.1. Normative References 321 [HTTP] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 322 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 323 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 325 [I-D.REPUTE-MEDIA-TYPE] 326 Borenstein, N. and M. Kucherawy, "A Media Type for 327 Reputation Interchange", draft-ietf-repute-media-type 328 (work in progress), November 2012. 330 [I-D.REPUTE-MODEL] 331 Borenstein, N. and M. Kucherawy, "A Model for Reputation 332 Interchange", draft-iet-repute-model (work in progress), 333 November 2012. 335 [KEYWORDS] 336 Bradner, S., "Key words for use in RFCs to Indicate 337 Requirement Levels", BCP 14, RFC 2119, March 1997. 339 [MIME] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 340 Extensions (MIME) Part One: Format of Internet Message 341 Bodies", RFC 2045, November 1996. 343 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 344 Resource Identifier (URI): Generic Syntax", RFC 3986, 345 January 2005. 347 [URI-TEMPLATE] 348 Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 349 and D. Orchard, "URI Template", RFC 6570, March 2012. 351 [WELL-KNOWN-URI] 352 Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 353 Uniform Resource Identifiers (URIs)", RFC 5785, 354 April 2010. 356 6.2. Informative References 358 [HTTPS] Rescorla, E., "HTTP over TLS", RFC 2818, May 2000. 360 [I-D.REPUTE-CONSIDERATIONS] 361 Kucherawy, M., "Operational Considerations Regarding 362 Reputation Services", draft-ietf-repute-considerations 363 (work in progress), November 2012. 365 Appendix A. Acknowledgements 367 The authors would like to thank the following for their contributions 368 to this work: Simon Hunt, Mark Nottingham, David F. Skoll, and Mykyta 369 Yevstifeyev. 371 Appendix B. Public Discussion 373 [RFC Editor: Please delete before publication] 375 Public discussion of this set of documents takes place on the 376 domainrep@ietf.org mailing list. See 377 https://www.ietf.org/mailman/listinfo/domainrep. 379 Authors' Addresses 381 Nathaniel Borenstein 382 Mimecast 383 203 Crescent St., Suite 303 384 Waltham, MA 02453 385 USA 387 Phone: +1 781 996 5340 388 Email: nsb@guppylake.com 389 Murray S. Kucherawy 390 270 Upland Drive 391 San Francisco, CA 94127 392 USA 394 Email: superuser@gmail.com