< draft-ietf-repute-query-http-06.txt   draft-ietf-repute-query-http-07.txt >
REPUTE Working Group N. Borenstein REPUTE Working Group N. Borenstein
Internet-Draft Mimecast Internet-Draft Mimecast
Intended status: Standards Track M. Kucherawy Intended status: Standards Track M. Kucherawy
Expires: November 17, 2013 May 16, 2013 Expires: December 8, 2013 June 6, 2013
A Reputation Query Protocol A Reputation Query Protocol
draft-ietf-repute-query-http-06 draft-ietf-repute-query-http-07
Abstract Abstract
This document defines a mechanism to conduct queries for reputation This document defines a mechanism to conduct queries for reputation
information over the Hypertext Transfer Protocol using JSON as the information over the Hypertext Transfer Protocol using JSON as the
payload meta-format. payload meta-format.
Status of this Memo Status of this Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
skipping to change at page 1, line 32 skipping to change at page 1, line 32
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 17, 2013. This Internet-Draft will expire on December 8, 2013.
Copyright Notice Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 13 skipping to change at page 2, line 13
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology and Definitions . . . . . . . . . . . . . . . . . . 3 2. Terminology and Definitions . . . . . . . . . . . . . . . . . . 3
2.1. Key Words . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.1. Key Words . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2. Other Definitions . . . . . . . . . . . . . . . . . . . . . 3 2.2. Other Definitions . . . . . . . . . . . . . . . . . . . . . 3
3. Description . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Description . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 3 3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 3
3.2. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.2. URI Template . . . . . . . . . . . . . . . . . . . . . . . 4
3.3. URI Template . . . . . . . . . . . . . . . . . . . . . . . 5 3.3. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.4. Response . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.4. Response . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.5. Protocol Support . . . . . . . . . . . . . . . . . . . . . 6 3.5. Protocol Support . . . . . . . . . . . . . . . . . . . . . 6
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 6 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 6
5. Security Considerations . . . . . . . . . . . . . . . . . . . . 6 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 7
6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7
6.1. Normative References . . . . . . . . . . . . . . . . . . . 7 6.1. Normative References . . . . . . . . . . . . . . . . . . . 7
6.2. Informative References . . . . . . . . . . . . . . . . . . 7 6.2. Informative References . . . . . . . . . . . . . . . . . . 8
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 8 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 8
Appendix B. Public Discussion . . . . . . . . . . . . . . . . . . 8 Appendix B. Public Discussion . . . . . . . . . . . . . . . . . . 8
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 8 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 8
1. Introduction 1. Introduction
This document defines a method to query a reputation data service for This document defines a method to query a reputation data service for
information about an entity, using the HyperText Transfer Protocol information about an entity, using the HyperText Transfer Protocol
(HTTP) as the transport mechanism and JSON as the payload meta- (HTTP) as the transport mechanism and JSON as the payload meta-
format. format.
skipping to change at page 3, line 44 skipping to change at page 3, line 44
o The name of the host, or the IP address, at which the reputation o The name of the host, or the IP address, at which the reputation
service is available; service is available;
o The name of the reputation application, i.e., the context within o The name of the reputation application, i.e., the context within
which the subject is being evaluated; which the subject is being evaluated;
o Optionally, name(s) of the specific reputation assertions or o Optionally, name(s) of the specific reputation assertions or
attributies that are being requested. attributies that are being requested.
The name of the application, if given, MUST be one registered with Assertions are discussed in [I-D.REPUTE-MEDIA-TYPE].
IANA in the Reputation Applications Registry, which is defined in
[I-D.REPUTE-MEDIA-TYPE]. A server receiving a query about an The name of the application, if given, is expected to be one
unregistered application or one it does not explicitly support (e.g., registered with IANA in the Reputation Applications Registry, which
by virtue of private agreements or experimental extensions) MUST is defined in [I-D.REPUTE-MEDIA-TYPE]. A server receiving a query
return a 404 error code. about an application it does not recognize or explicitly support
support (e.g., by virtue of private agreements or experimental
extensions) MUST return a 404 error code.
A reputation query made via [HTTP] encodes the question being asked A reputation query made via [HTTP] encodes the question being asked
in an HTTP GET method. in an HTTP GET method. The specific syntax of the query itself is
specified by retrieving a URI template from the reputation service,
completing the template, and then issuing the query.
3.2. Syntax 3.2. URI Template
The template file is retrieved by requesting the [WELL-KNOWN-URI]
"repute-template" from the host providing reputation service, using
HTTP. (The registration for this well-known URI is in Section 4.)
The server returns the template file in a reply that MUST use the
text/plain media type (see [MIME]), and SHOULD include an Expires
field (see Section 14.21 of [HTTP]) indicating a duration for which
the template is to be considered valid by clients and not re-queried.
Clients SHOULD NOT repeat the query prior to the timestamp in the
Expires field, or wait no less than one day if the Expires field is
not present.
The template file might contain more than one template. Such a file
MUST have each template separated by a newline (ASCII 0x0D)
character.
Each template in the file is expanded using the variables that are
the parameters to the query. The client then selects any expanded
template it is able to use (i.e., using a scheme the client
supports), and then uses the expanded template as the target for the
query itself. This allows for discovery of alternatives to HTTP that
the client might be able to use.
For example, given the following template:
{scheme}://{service}/{application}/{subject}/{assertion}
A query about the use of the domain "example.org" in the "email-id"
application context to a service run at "example.com", where that
application declares a required "subject" parameter, requesting the
"SPAM" reputation assertion, using HTTP to conduct the query with no
specific client authentication information, would be formed as
follows:
http://example.com/email-id/example.org/spam
3.3. Syntax
The syntax for the [URI] of the query is constructed using a template The syntax for the [URI] of the query is constructed using a template
as per [URI-TEMPLATE]. (See Section 3.3.) The following variables as per [URI-TEMPLATE]. (See Section 3.2.) Clients MUST have the
MUST be available during template expansion: following available for template expansion:
application: The name of the application reputation in whose context application: The name of the application reputation in whose context
the request is being made. the request is being made.
scheme: The transport scheme the client will be using for the query. scheme: The transport scheme the client will be using for the query.
service: The hostname or IP address to which the query is being service: The hostname or IP address to which the query is being
sent. sent.
subject: The subject of the query. subject: The subject of the query.
Which scheme(s) can be used depends on how the reputation service Which scheme(s) can be used depends on how the reputation service
provider offers its services. Thus, the template could include a provider offers its services. Thus, the template could include a
specific scheme as a fixed string in the template, or it might offer specific scheme as a fixed string in the template, or it might offer
it as a variable in the template. If it is a variable, it is up to it as a variable in the template. Note that a template could specify
the client and server to negotiate out-of-band which schemes are a scheme the client is not equipped to use.
supported for client queries. Implementers need to be aware that the
template could include a fixed scheme not supported by the client.
For example, the following query template includes a fixed scheme, For example, the following query template includes a fixed scheme,
forcing clients to use the "http" URI scheme only: forcing clients to use the "http" URI scheme only:
http://{service}/repute.php{?subject,application,assertion} http://{service}/repute.php{?subject,application,assertion}
However, this template allows the client to select the scheme to be However, this template allows the client to select the scheme to be
used if, for example, the service is also available over the "https" used if, for example, the service is also available over the "https"
URI scheme: URI scheme:
{scheme}://{service}/repute.php{?subject,application,assertion} {scheme}://{service}/repute.php{?subject,application,assertion}
The following variables are OPTIONAL to this base specification, but The following variable is OPTIONAL to this base specification, but
might be required by the template presented for a specific service: might be required by the template presented for a specific service:
assertion: A list of one or more specific assertions of interest to assertion: A list of one or more specific assertions of interest to
the client. If absent, the server MUST infer that all available the client. If absent, the client is indicating that it requests
assertion information is being requested. all available assertion information.
Every application space has a set of assertions applicable to its own Every application space has a set of assertions applicable to its own
context. [I-D.REPUTE-MEDIA-TYPE] defines a single assertion assumed context. [I-D.REPUTE-MEDIA-TYPE] defines a single assertion assumed
to exist in any application that does not define its own assertion to exist in any application that does not define its own assertion
set. set.
Other required or optional query parameters might be defined by Reputation applications can extend the set of optional or required
documents that register new response sets with IANA. Further, other query parameters as part of their IANA registration actions. The set
required or optional query parameters might be defined by specific enumerated above establishes the base set common to all of them.
reputation service providers, though these are private arrangements
between client and server and will not be registered with IANA. Further, additional required or optional extension query parameters
might be defined by specific reputation service providers, though
these are private arrangements between client and server and will not
be registered with IANA.
Authentication between reputation client and server is outside the Authentication between reputation client and server is outside the
scope of this specificatin. It could be provided through a variety scope of this specification. It could be provided through a variety
of available transport-based or object-based mechanisms, including a of available transport-based or object-based mechanisms, including a
later extension of this specification. later extension of this specification.
3.3. URI Template
The template is retrieved by requesting the [WELL-KNOWN-URI] "repute-
template" from the host providing reputation service using HTTP.
(The registration for this well-known URI is in Section 4.) The
server MUST return the template in a reply using the text/plain media
type (see [MIME]), and SHOULD include an Expires field (see Section
14.21 of [HTTP]) indicating a duration for which the template is to
be considered valid by clients and not re-queried.
If the template cannot be retrieved (i.e., any HTTP error is
returned), the reputation query SHOULD be aborted and/or retried at a
later time. Clients SHOULD adhere to the expiration time presented
in an Expires field, if present, or otherwise assume that the
template is valid for no less than one day and SHOULD NOT repeat the
query.
The template is expanded, using the variables that are the parameters
to the query, and then used as the target for the query itself. For
example, given the following template:
{scheme}://{service}/{application}/{subject}/{assertion}
A query about the use of the domain "example.org" in the "email-id"
application context to a service run at "example.com", where that
application declares a required "subject" parameter, requesting the
"SPAM" reputation assertion, using HTTP to conduct the query with no
specific client authentication information, would be formed as
follows:
http://example.com/email-id/example.org/spam
Matching of the attribute name(s) in the template MUST be case-
insensitive.
3.4. Response 3.4. Response
The response is expected to be contained in a media type designed to The response is expected to be contained in a media type designed to
deliver reputons. An media type designed for this purpose, deliver reputons. An media type designed for this purpose,
"application/reputon+json", is defined in [I-D.REPUTE-MEDIA-TYPE]. "application/reputon+json", is defined in [I-D.REPUTE-MEDIA-TYPE].
3.5. Protocol Support 3.5. Protocol Support
A client has to implement HTTP in order to retrieve the query A client has to implement HTTP in order to retrieve the query
template as described in Section 3.3. Accordingly, a server can template as described in Section 3.2. Accordingly, a server can
assume the client will be able to handle a URI template that produces assume the client will be able to handle a URI template that produces
a URI for the query using the "http" scheme. If the template can a URI for the query using the "http" scheme. If the template can
yield a query string that uses some other URI scheme, there will need yield a query string that uses some other URI scheme, there will need
to be some out-of-band negotiation of which scheme(s) are supported to be some out-of-band negotiation of which scheme(s) are supported
by the service, and appropriate protocol support in the client. by the service, and appropriate protocol support in the client.
A server SHOULD include support for providing service over HTTP, and
publish templates indicating support for this, as a baseline for
interoperability with arbitrary clients.
4. IANA Considerations 4. IANA Considerations
This document registers the "repute-template" well-known URI in the This document registers the "repute-template" well-known URI in the
Well-Known URI registry as defined by [WELL-KNOWN-URI], as follows: Well-Known URI registry as defined by [WELL-KNOWN-URI], as follows:
URI suffix: repute-template URI suffix: repute-template
Change controller: IETF Change controller: IETF
Specification document(s): [this document] Specification document(s): [this document]
Related information: none Related information: none
5. Security Considerations 5. Security Considerations
This document defines particular uses of existing protocols for a This document defines particular uses of existing protocols for a
specific application. In particular, the basic protocol used for specific application. In particular, the basic protocol used for
this service is basic HTTP which is not secure without certain this service to retrieve a URI template from a well-known location is
extensions. As such, the protocol described here does not itself basic HTTP, which is not secure without certain extensions. Security
present new security considerations. issues relevant to use of URI templates are discussed in
[URI-TEMPLATE], and those relevant to well-known URI definitions and
retrieval are discussed in [WELL-KNOWN-URI].
Security considerations relevant to email and email authentication The reputation service itself will use HTTP or other transport
can be found in most of the documents listed in the References methods to issue queries and receive replies. Those protocols have
sections below. Information specific to use of reputation services registered URI schemes and, as such, presumably have documented
can be found in [I-D.REPUTE-CONSIDERATIONS]. security considerations. The protocol described here operates atop
those schemes, and does not itself present new security
considerations.
Reputation mechanisms represent an obvious security concern, in terms Reputation mechanisms represent an obvious security concern, in terms
of the validity and use of the reputation information. These issues of the validity and use of the reputation information. These issues
are beyond the scope of this specification. are beyond the scope of this specification. General information
pertaining to using or providing reputation services can be found in
[I-D.REPUTE-CONSIDERATIONS].
6. References 6. References
6.1. Normative References 6.1. Normative References
[HTTP] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., [HTTP] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[I-D.REPUTE-MEDIA-TYPE] [I-D.REPUTE-MEDIA-TYPE]
skipping to change at page 7, line 37 skipping to change at page 8, line 12
[MIME] Freed, N. and N. Borenstein, "Multipurpose Internet Mail [MIME] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part One: Format of Internet Message Extensions (MIME) Part One: Format of Internet Message
Bodies", RFC 2045, November 1996. Bodies", RFC 2045, November 1996.
[URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", RFC 3986, Resource Identifier (URI): Generic Syntax", RFC 3986,
January 2005. January 2005.
[URI-TEMPLATE] [URI-TEMPLATE]
Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
and D. Orchard, "URI Template", draft-gregorio-uritemplate and D. Orchard, "URI Template", RFC 6570, March 2012.
(work in progress), September 2011.
[WELL-KNOWN-URI] [WELL-KNOWN-URI]
Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known
Uniform Resource Identifiers (URIs)", RFC 5785, Uniform Resource Identifiers (URIs)", RFC 5785,
April 2010. April 2010.
6.2. Informative References 6.2. Informative References
[I-D.REPUTE-CONSIDERATIONS] [I-D.REPUTE-CONSIDERATIONS]
Kucherawy, M., "Operational Considerations Regarding Kucherawy, M., "Operational Considerations Regarding
Reputation Services", draft-ietf-repute-considerations Reputation Services", draft-ietf-repute-considerations
(work in progress), November 2012. (work in progress), November 2012.
Appendix A. Acknowledgements Appendix A. Acknowledgements
The authors would like to thank the following for their contributions The authors would like to thank the following for their contributions
to this work: Mark Nottingham, David F. Skoll, and Mykyta to this work: Simon Hunt, Mark Nottingham, David F. Skoll, and Mykyta
Yevstifeyev. Yevstifeyev.
Appendix B. Public Discussion Appendix B. Public Discussion
Public discussion of this set of documents takes place on the Public discussion of this set of documents takes place on the
domainrep@ietf.org mailing list. See domainrep@ietf.org mailing list. See
https://www.ietf.org/mailman/listinfo/domainrep. https://www.ietf.org/mailman/listinfo/domainrep.
Authors' Addresses Authors' Addresses
 End of changes. 23 change blocks. 
77 lines changed or deleted 94 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/