idnits 2.17.1 draft-ietf-repute-query-http-07.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 (June 6, 2013) is 3970 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: December 8, 2013 June 6, 2013 7 A Reputation Query Protocol 8 draft-ietf-repute-query-http-07 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 December 8, 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. 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 . . . . . . . . . . . . . . . . . . . . 7 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 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 Assertions are discussed in [I-D.REPUTE-MEDIA-TYPE]. 110 The name of the application, if given, is expected to be one 111 registered with IANA in the Reputation Applications Registry, which 112 is defined in [I-D.REPUTE-MEDIA-TYPE]. A server receiving a query 113 about an application it does not recognize or explicitly support 114 support (e.g., by virtue of private agreements or experimental 115 extensions) MUST return a 404 error code. 117 A reputation query made via [HTTP] encodes the question being asked 118 in an HTTP GET method. The specific syntax of the query itself is 119 specified by retrieving a URI template from the reputation service, 120 completing the template, and then issuing the query. 122 3.2. URI Template 124 The template file is retrieved by requesting the [WELL-KNOWN-URI] 125 "repute-template" from the host providing reputation service, using 126 HTTP. (The registration for this well-known URI is in Section 4.) 127 The server returns the template file in a reply that MUST use the 128 text/plain media type (see [MIME]), and SHOULD include an Expires 129 field (see Section 14.21 of [HTTP]) indicating a duration for which 130 the template is to be considered valid by clients and not re-queried. 132 Clients SHOULD NOT repeat the query prior to the timestamp in the 133 Expires field, or wait no less than one day if the Expires field is 134 not present. 136 The template file might contain more than one template. Such a file 137 MUST have each template separated by a newline (ASCII 0x0D) 138 character. 140 Each template in the file is expanded using the variables that are 141 the parameters to the query. The client then selects any expanded 142 template it is able to use (i.e., using a scheme the client 143 supports), and then uses the expanded template as the target for the 144 query itself. This allows for discovery of alternatives to HTTP that 145 the client might be able to use. 147 For example, given the following template: 149 {scheme}://{service}/{application}/{subject}/{assertion} 151 A query about the use of the domain "example.org" in the "email-id" 152 application context to a service run at "example.com", where that 153 application declares a required "subject" parameter, requesting the 154 "SPAM" reputation assertion, using HTTP to conduct the query with no 155 specific client authentication information, would be formed as 156 follows: 158 http://example.com/email-id/example.org/spam 160 3.3. Syntax 162 The syntax for the [URI] of the query is constructed using a template 163 as per [URI-TEMPLATE]. (See Section 3.2.) Clients MUST have the 164 following available for template expansion: 166 application: The name of the application reputation in whose context 167 the request is being made. 169 scheme: The transport scheme the client will be using for the query. 171 service: The hostname or IP address to which the query is being 172 sent. 174 subject: The subject of the query. 176 Which scheme(s) can be used depends on how the reputation service 177 provider offers its services. Thus, the template could include a 178 specific scheme as a fixed string in the template, or it might offer 179 it as a variable in the template. Note that a template could specify 180 a scheme the client is not equipped to use. 182 For example, the following query template includes a fixed scheme, 183 forcing clients to use the "http" URI scheme only: 185 http://{service}/repute.php{?subject,application,assertion} 187 However, this template allows the client to select the scheme to be 188 used if, for example, the service is also available over the "https" 189 URI scheme: 191 {scheme}://{service}/repute.php{?subject,application,assertion} 193 The following variable is OPTIONAL to this base specification, but 194 might be required by the template presented for a specific service: 196 assertion: A list of one or more specific assertions of interest to 197 the client. If absent, the client is indicating that it requests 198 all available assertion information. 200 Every application space has a set of assertions applicable to its own 201 context. [I-D.REPUTE-MEDIA-TYPE] defines a single assertion assumed 202 to exist in any application that does not define its own assertion 203 set. 205 Reputation applications can extend the set of optional or required 206 query parameters as part of their IANA registration actions. The set 207 enumerated above establishes the base set common to all of them. 209 Further, additional required or optional extension query parameters 210 might be defined by specific reputation service providers, though 211 these are private arrangements between client and server and will not 212 be registered with IANA. 214 Authentication between reputation client and server is outside the 215 scope of this specification. It could be provided through a variety 216 of available transport-based or object-based mechanisms, including a 217 later extension of this specification. 219 3.4. Response 221 The response is expected to be contained in a media type designed to 222 deliver reputons. An media type designed for this purpose, 223 "application/reputon+json", is defined in [I-D.REPUTE-MEDIA-TYPE]. 225 3.5. Protocol Support 227 A client has to implement HTTP in order to retrieve the query 228 template as described in Section 3.2. Accordingly, a server can 229 assume the client will be able to handle a URI template that produces 230 a URI for the query using the "http" scheme. If the template can 231 yield a query string that uses some other URI scheme, there will need 232 to be some out-of-band negotiation of which scheme(s) are supported 233 by the service, and appropriate protocol support in the client. 235 A server SHOULD include support for providing service over HTTP, and 236 publish templates indicating support for this, as a baseline for 237 interoperability with arbitrary clients. 239 4. IANA Considerations 241 This document registers the "repute-template" well-known URI in the 242 Well-Known URI registry as defined by [WELL-KNOWN-URI], as follows: 244 URI suffix: repute-template 246 Change controller: IETF 248 Specification document(s): [this document] 250 Related information: none 252 5. Security Considerations 254 This document defines particular uses of existing protocols for a 255 specific application. In particular, the basic protocol used for 256 this service to retrieve a URI template from a well-known location is 257 basic HTTP, which is not secure without certain extensions. Security 258 issues relevant to use of URI templates are discussed in 259 [URI-TEMPLATE], and those relevant to well-known URI definitions and 260 retrieval are discussed in [WELL-KNOWN-URI]. 262 The reputation service itself will use HTTP or other transport 263 methods to issue queries and receive replies. Those protocols have 264 registered URI schemes and, as such, presumably have documented 265 security considerations. The protocol described here operates atop 266 those schemes, and does not itself present new security 267 considerations. 269 Reputation mechanisms represent an obvious security concern, in terms 270 of the validity and use of the reputation information. These issues 271 are beyond the scope of this specification. General information 272 pertaining to using or providing reputation services can be found in 273 [I-D.REPUTE-CONSIDERATIONS]. 275 6. References 277 6.1. Normative References 279 [HTTP] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 280 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 281 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 283 [I-D.REPUTE-MEDIA-TYPE] 284 Borenstein, N. and M. Kucherawy, "A Media Type for 285 Reputation Interchange", draft-ietf-repute-media-type 286 (work in progress), November 2012. 288 [I-D.REPUTE-MODEL] 289 Borenstein, N. and M. Kucherawy, "A Model for Reputation 290 Interchange", draft-iet-repute-model (work in progress), 291 November 2012. 293 [KEYWORDS] 294 Bradner, S., "Key words for use in RFCs to Indicate 295 Requirement Levels", BCP 14, RFC 2119, March 1997. 297 [MIME] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 298 Extensions (MIME) Part One: Format of Internet Message 299 Bodies", RFC 2045, November 1996. 301 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 302 Resource Identifier (URI): Generic Syntax", RFC 3986, 303 January 2005. 305 [URI-TEMPLATE] 306 Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 307 and D. Orchard, "URI Template", RFC 6570, March 2012. 309 [WELL-KNOWN-URI] 310 Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 311 Uniform Resource Identifiers (URIs)", RFC 5785, 312 April 2010. 314 6.2. Informative References 316 [I-D.REPUTE-CONSIDERATIONS] 317 Kucherawy, M., "Operational Considerations Regarding 318 Reputation Services", draft-ietf-repute-considerations 319 (work in progress), November 2012. 321 Appendix A. Acknowledgements 323 The authors would like to thank the following for their contributions 324 to this work: Simon Hunt, Mark Nottingham, David F. Skoll, and Mykyta 325 Yevstifeyev. 327 Appendix B. Public Discussion 329 Public discussion of this set of documents takes place on the 330 domainrep@ietf.org mailing list. See 331 https://www.ietf.org/mailman/listinfo/domainrep. 333 Authors' Addresses 335 Nathaniel Borenstein 336 Mimecast 337 203 Crescent St., Suite 303 338 Waltham, MA 02453 339 USA 341 Phone: +1 781 996 5340 342 Email: nsb@guppylake.com 343 Murray S. Kucherawy 344 270 Upland Drive 345 San Francisco, CA 94127 346 USA 348 Email: superuser@gmail.com