idnits 2.17.1 draft-ietf-repute-query-http-09.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 (July 12, 2013) is 3938 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: January 13, 2014 July 12, 2013 7 A Reputation Query Protocol 8 draft-ietf-repute-query-http-09 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 January 13, 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 . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . 8 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 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 attributies that are being requested. 117 Assertions are discussed in [I-D.REPUTE-MEDIA-TYPE]. 119 The name of the application, if given, is expected to be one 120 registered with IANA in the Reputation Applications Registry, which 121 is defined in [I-D.REPUTE-MEDIA-TYPE]. A server receiving a query 122 about an application it does not recognize or explicitly support 123 support (e.g., by virtue of private agreements or experimental 124 extensions) MUST return a 404 error code. 126 A reputation query made via [HTTP] encodes the question being asked 127 in an HTTP GET method. The specific syntax of the query itself is 128 specified by retrieving a URI template from the reputation service, 129 completing the template, and then issuing the query. 131 3.2. URI Template 133 The template file is retrieved by requesting the [WELL-KNOWN-URI] 134 "repute-template" from the host providing reputation service, using 135 HTTP. (The registration for this well-known URI is in Section 4.) 136 The server returns the template file in a reply that MUST use the 137 text/plain media type (see [MIME]), and SHOULD include an Expires 138 field (see Section 14.21 of [HTTP]) indicating a duration for which 139 the template is to be considered valid by clients and not re-queried. 141 Clients SHOULD NOT repeat the query prior to the timestamp in the 142 Expires field, or wait no less than one day if the Expires field is 143 not present. 145 The template file might contain more than one template. Such a file 146 MUST have each template separated by a newline (ASCII 0x0D) 147 character. 149 Each template in the file is expanded using the variables that are 150 the parameters to the query. These parameters are either the subject 151 about which reputation information is sought (or details associated 152 with it), or other parameters that are established out-of-band with 153 the reputation service; they are not established by any automated 154 discovery described here. The client then attempts to query each 155 expanded template that uses a scheme it is cable of querying, in the 156 order presented in the file, until finds one to which it can 157 establish a usable connection and issue the query. 159 For example, given the following template: 161 http://{service}/{application}/{subject}/{assertion} 162 A query about the use of the domain "example.org" in the "email-id" 163 application context to a service run at "example.com", where that 164 application declares a required "subject" parameter, requesting the 165 "SPAM" reputation assertion, would be formed as follows: 167 http://example.com/email-id/example.org/spam 169 3.3. Syntax 171 The syntax for the [URI] of the query is constructed using a template 172 as per [URI-TEMPLATE]. (See Section 3.2.) Clients MUST provide the 173 following values in the expansion of the template: 175 application: The name of the application reputation in whose context 176 the request is being made. 178 service: The hostname or IP address to which the query is being 179 sent. This MUST be the same as the host to which the template 180 query was issued. 182 subject: The subject of the query, extracted from some content to be 183 evaluated. 185 The following variable can also be provided. It is not mandatory in 186 this model, but a specific application (defined in its own extension 187 document) might declare it mandatory in a specific context: 189 assertion: The name of the specific assertion of interest to the 190 client. If absent, the client is indicating that it requests all 191 available assertion information. 193 Every application space has a set of assertions applicable to its own 194 context. [I-D.REPUTE-MEDIA-TYPE] defines a single assertion assumed 195 to exist in any application that does not define its own assertion 196 set. 198 Reputation applications can extend the set of optional or required 199 query parameters as part of their IANA registration actions. The set 200 enumerated above establishes the base set common to all of them. 201 Further, additional required or optional extension query parameters 202 might be defined by specific reputation service providers, though 203 these are private arrangements between client and server and will not 204 be registered with IANA. 206 Authentication between reputation client and server is outside the 207 scope of this specification. It could be provided through a variety 208 of available transport-based or object-based mechanisms, including a 209 later extension of this specification. 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.2. 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. The template could 223 yield a query string that uses some other URI scheme, in which case 224 the client could try that URI as well if it supports issuing queries 225 with that scheme. 227 A server SHOULD include support for providing service over HTTP, and 228 publish templates indicating support for this, as a baseline for 229 interoperability with arbitrary clients. 231 4. IANA Considerations 233 This document registers the "repute-template" well-known URI in the 234 Well-Known URI registry as defined by [WELL-KNOWN-URI], as follows: 236 URI suffix: repute-template 238 Change controller: IETF 240 Specification document(s): [this document] 242 Related information: none 244 5. Security Considerations 246 This document defines particular uses of existing protocols for a 247 specific application. In particular, the basic protocol used for 248 this service to retrieve a URI template from a well-known location is 249 basic HTTP, which is not secure without certain extensions. Security 250 issues relevant to use of URI templates are discussed in 251 [URI-TEMPLATE], and those relevant to well-known URI definitions and 252 retrieval are discussed in [WELL-KNOWN-URI]. 254 The reputation service itself will use HTTP or other transport 255 methods to issue queries and receive replies. Those protocols have 256 registered URI schemes and, as such, presumably have documented 257 security considerations. The protocol described here operates atop 258 those schemes, and does not itself present new security 259 considerations. 261 Reputation mechanisms represent an obvious security concern, in terms 262 of the validity and use of the reputation information. These issues 263 are beyond the scope of this specification. General information 264 pertaining to using or providing reputation services can be found in 265 [I-D.REPUTE-CONSIDERATIONS]. 267 6. References 269 6.1. Normative References 271 [HTTP] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 272 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 273 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 275 [I-D.REPUTE-MEDIA-TYPE] 276 Borenstein, N. and M. Kucherawy, "A Media Type for 277 Reputation Interchange", draft-ietf-repute-media-type 278 (work in progress), November 2012. 280 [I-D.REPUTE-MODEL] 281 Borenstein, N. and M. Kucherawy, "A Model for Reputation 282 Interchange", draft-iet-repute-model (work in progress), 283 November 2012. 285 [KEYWORDS] 286 Bradner, S., "Key words for use in RFCs to Indicate 287 Requirement Levels", BCP 14, RFC 2119, March 1997. 289 [MIME] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 290 Extensions (MIME) Part One: Format of Internet Message 291 Bodies", RFC 2045, November 1996. 293 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 294 Resource Identifier (URI): Generic Syntax", RFC 3986, 295 January 2005. 297 [URI-TEMPLATE] 298 Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 299 and D. Orchard, "URI Template", RFC 6570, March 2012. 301 [WELL-KNOWN-URI] 302 Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 303 Uniform Resource Identifiers (URIs)", RFC 5785, 304 April 2010. 306 6.2. Informative References 308 [I-D.REPUTE-CONSIDERATIONS] 309 Kucherawy, M., "Operational Considerations Regarding 310 Reputation Services", draft-ietf-repute-considerations 311 (work in progress), November 2012. 313 Appendix A. Acknowledgements 315 The authors would like to thank the following for their contributions 316 to this work: Simon Hunt, Mark Nottingham, David F. Skoll, and Mykyta 317 Yevstifeyev. 319 Appendix B. Public Discussion 321 Public discussion of this set of documents takes place on the 322 domainrep@ietf.org mailing list. See 323 https://www.ietf.org/mailman/listinfo/domainrep. 325 Authors' Addresses 327 Nathaniel Borenstein 328 Mimecast 329 203 Crescent St., Suite 303 330 Waltham, MA 02453 331 USA 333 Phone: +1 781 996 5340 334 Email: nsb@guppylake.com 336 Murray S. Kucherawy 337 270 Upland Drive 338 San Francisco, CA 94127 339 USA 341 Email: superuser@gmail.com