idnits 2.17.1 draft-ietf-repute-query-http-02.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 (April 6, 2012) is 4396 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) == Missing Reference: 'TBD' is mentioned on line 197, but not defined ** 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 (~~), 2 warnings (==), 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: October 8, 2012 Cloudmark 6 April 6, 2012 8 Reputation Data Interchange using HTTP and JSON 9 draft-ietf-repute-query-http-02 11 Abstract 13 This document defines a mechanism to conduct queries for reputation 14 information using the Hypertext Transfer Protocol. 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 October 8, 2012. 33 Copyright Notice 35 Copyright (c) 2012 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. Query . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 3.2. Response . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 5 58 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 5 59 6. Normative References . . . . . . . . . . . . . . . . . . . . . 5 60 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 6 61 Appendix B. Public Discussion . . . . . . . . . . . . . . . . . . 6 62 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 6 64 1. Introduction 66 This document defines a method to query a reputation data service for 67 information about an entity, using the HyperText Transfer Protocol 68 (HTTP) as the transport mechanism and JSON as the payload format. 70 2. Terminology and Definitions 72 This section defines terms used in the rest of the document. 74 2.1. Key Words 76 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 77 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 78 document are to be interpreted as described in [KEYWORDS]. 80 2.2. Other Definitions 82 Other terms of importance in this document are defined in 83 [I-D.REPUTE-MODEL] and [I-D.REPUTE-MEDIA-TYPE]. 85 3. Description 87 3.1. Query 89 A reputation query made via [HTTP] encodes the question being asked 90 in the GET instruction of the protocol. 92 The components to the question being asked comprise the following: 94 o The subject of the query; 96 o The name of the host, or the IP address, at which the reputation 97 service is available; 99 o The name of the reputation application, i.e., the context within 100 which the query is being made; 102 o Optionally, name(s) of the specific reputation assertions or 103 attributies that are being requested. 105 The name of the application, if given, MUST be one registered with 106 IANA. A server receiving a query about an unregistered application 107 or one it does not explicitly support MUST return a 404 error code. 109 The syntax for the [URI] portion of the query is constructed using a 110 template as per [URI-TEMPLATE]. The following variables MUST be 111 available during template expansion: 113 application: The name of the application reputation in whose context 114 the request is being made. 116 scheme: The transport scheme the client will be using for the query. 118 service: The hostname or IP address being queried. 120 subject: The subject of the query. 122 Which scheme(s) can be used depends on how the reputation service 123 provider offers its services. Thus, the template could include a 124 specific scheme as a fixed string in the template, or it might offer 125 it as a variable in the template. If it is a variable, it is up to 126 the client and server to negotiate out-of-band which schemes are 127 supported for client queries. Implementers need to be aware that the 128 template could include a fixed scheme not supported by the client. 130 The following variables are OPTIONAL, but might be required by the 131 template presented for a specific service: 133 assertion: A list of one or more specific assertions of interest to 134 the client. If absent, the server MUST infer that all available 135 assertion information is being requested. 137 Other required or optional query parameters might be defined by 138 documents that register new response sets with IANA. Further, other 139 required or optional query parameters might be defined by specific 140 reputation service providers, though these are private arrangements 141 between client and server and will not be registered with IANA. 143 Authentication between reputation client and server MAY be 144 accomplished using query extensions, or MAY rely on the capabilities 145 of the transport associated with the selected URI scheme. 147 The template is retrieved by requesting the [WELL-KNOWN-URI] "repute- 148 template" from the host providing reputation service using HTTP. The 149 server SHOULD return the template in a text/plain reply. If the 150 template cannot be retrieved, the reputation query SHOULD be aborted 151 and/or retried at a later time. The server responding to the 152 template request SHOULD include an Expires field indicating a 153 duration for which the template should be considered valid by clients 154 and not re-queried. Clients SHOULD adhere to the expiration time 155 thus provided or, if none is provided, assume that the template is 156 valid for no less than one day and SHOULD NOT repeat the query. 158 For example, given the following template: 160 {scheme}://{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 using HTTP to conduct the query with no 166 specific client authentication information would be formed as 167 follows: 169 http://example.com/email-id/example.org/spam 171 Matching of the attribute name(s) MUST be case-insensitive. 173 3.2. Response 175 The response is expected to be contained in a media type designed to 176 deliver reputons. An media type designed for this purpose, 177 "application/reputon+json", is defined in [I-D.REPUTE-MEDIA-TYPE]. 179 4. IANA Considerations 181 This document registers the "repute-template" well-known URI in the 182 Well-Known URI registry as defined by [WELL-KNOWN-URI], as follows: 184 URI suffix: repute-template 186 Change controller: IETF 188 Specification document(s): [this document] 190 Related information: none 192 5. Security Considerations 194 This section describes security considerations introduced by the 195 query mechanism defined here. 197 [TBD] 199 6. Normative References 201 [HTTP] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 202 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 203 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 205 [I-D.REPUTE-MEDIA-TYPE] 206 Borenstein, N. and M. Kucherawy, "A Media Type for 207 Reputation Interchange", draft-ietf-repute-media-type 208 (work in progress), June 2011. 210 [I-D.REPUTE-MODEL] 211 Borenstein, N. and M. Kucherawy, "A Model for Reputation 212 Interchange", draft-iet-repute-model (work in progress), 213 June 2011. 215 [KEYWORDS] 216 Bradner, S., "Key words for use in RFCs to Indicate 217 Requirement Levels", BCP 14, RFC 2119, March 1997. 219 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 220 Resource Identifier (URI): Generic Syntax", RFC 3986, 221 January 2005. 223 [URI-TEMPLATE] 224 Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 225 and D. Orchard, "URI Template", draft-gregorio-uritemplate 226 (work in progress), September 2011. 228 [WELL-KNOWN-URI] 229 Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 230 Uniform Resource Identifiers (URIs)", RFC 5785, 231 April 2010. 233 Appendix A. Acknowledgements 235 The authors would like to thank the following for their contributions 236 to this work: Mark Nottingham, David F. Skoll, and Mykyta 237 Yevstifeyev. 239 Appendix B. Public Discussion 241 Public discussion of this set of documents takes place on the 242 domainrep@ietf.org mailing list. See 243 https://www.ietf.org/mailman/listinfo/domainrep. 245 Authors' Addresses 247 Nathaniel Borenstein 248 Mimecast 249 203 Crescent St., Suite 303 250 Waltham, MA 02453 251 USA 253 Phone: +1 781 996 5340 254 Email: nsb@guppylake.com 256 Murray S. Kucherawy 257 Cloudmark 258 128 King St., 2nd Floor 259 San Francisco, CA 94107 260 USA 262 Phone: +1 415 946 3800 263 Email: msk@cloudmark.com