<?xml version="1.0" encoding="UTF-8"?>
  <?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
  <!-- generated by https://github.com/cabo/kramdown-rfc2629 version 1.0.29 -->

<!DOCTYPE rfc SYSTEM "../Tools/rfc2629xslt/rfc2629.dtd" [
]>

<?rfc toc="yes"?>
<?rfc tocindent="yes"?>
<?rfc sortrefs="yes"?>
<?rfc symrefs="yes"?>
<?rfc strict="yes"?>
<?rfc compact="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>

<rfc ipr="trust200902" docName="draft-nottingham-proxy-explanation-00" category="info">

  <front>
    <title abbrev="Proxy Explanations">The application/proxy-explanation+json media type</title>

    <author initials="M." surname="Nottingham" fullname="Mark Nottingham">
      <organization></organization>
      <address>
        <email>mnot@mnot.net</email>
        <uri>https://www.mnot.net/</uri>
      </address>
    </author>

    <date year="2016"/>

    <area>General</area>
    
    <keyword>Internet-Draft</keyword>

    <abstract>


<t>This specification defines the application/proxy-explanation+json media type, to allow HTTP proxies to explain to clients why a request is unsuccessful.</t>



    </abstract>


    <note title="Note to Readers">


<t>The issues list for this draft can be found at <eref target="https://github.com/mnot/I-D/labels/proxy-explanation">https://github.com/mnot/I-D/labels/proxy-explanation</eref>.</t>

<t>The most recent (often, unpublished) draft is at <eref target="https://mnot.github.io/I-D/proxy-explanation/">https://mnot.github.io/I-D/proxy-explanation/</eref>.</t>

<t>Recent changes are listed at <eref target="https://github.com/mnot/I-D/commits/gh-pages/proxy-explanation">https://github.com/mnot/I-D/commits/gh-pages/proxy-explanation</eref>.</t>


    </note>


  </front>

  <middle>


<section anchor="introduction" title="Introduction">

<t>HTTP requests <xref target="RFC7230"/> to a proxy might not succeed variety of reasons; the request itself might violate a policy, or the requested content might be deemed unacceptable (e.g., it contains a virus, or itself violate a policy being imposed by the proxy).</t>

<t>For HTTP URLs, information about the reason is often injected into the HTTP response, so that the user understands what has happened, even if the message is only an HTML “Access Denied.” This practice is problematic, because both users and non-browser clients can become confused about the source of the information, mistaking content from the proxy as being from the origin.</t>

<t>Furthermore, for HTTPS URLs, there is no way for the proxy to inform the end user about its actions. Proxies could provide HTML content in a 403 (Forbidden) response, but browsers are unwilling to show this to end users, since doing so would subject them to a potential man-in-the-middle attack.</t>

<t>This specification defines a new response format with a constrained vocabulary, so that proxies can communicate basic information about why a request has not succeeded, and browsers can provide that information to users without risking it being mistaken for an authoritative response from the origin server.</t>

<section anchor="notational-conventions" title="Notational Conventions">

<t>The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”,
“RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in
<xref target="RFC2119"/>.</t>

</section>
</section>
<section anchor="the-applicationproxy-explanationjson-media-type" title="The application/proxy-explanation+json Media Type">

<t>The “application/proxy-explanation+json” media type denotes a JSON <xref target="RFC7159"/> format whose root is an object containing the following members:</t>

<t><list style="symbols">
  <t><spanx style="strong">name</spanx> - A short string identifying the party operating the proxy</t>
  <t><spanx style="strong">title</spanx> - A short string title for the explanation</t>
  <t><spanx style="strong">description</spanx> - A string explaining why the request wasn’t successful</t>
  <t><spanx style="strong">moreinfo</spanx> - A string containing an absolute URL <xref target="RFC3986"/> which the user can find relevant information.</t>
</list></t>

<t>The “name” and “title” members MUST be present; all other members are OPTIONAL.</t>

<t>This media type MUST NOT be generated by origin servers and gateway servers (i.e., “reverse proxies” and “content delivery networks”); it is only intended to be generated by proxies. It MAY be generated by interception proxies (so-called “transparent proxies”), although as per below, it might be ignored by clients in this case.</t>

<t>It MUST NOT be used with a 2xx or 3xx status code, and clients MUST ignore its presence on them. Typical status codes that it will be used with include 403 (Forbidden), 451 (Unavailable For Legal Reasons), 502 (Bad Gateway), and 504 (Gateway Timeout).</t>

<t>Proxies SHOULD carefully consider what caching metadata <xref target="RFC7234"/> is appropriate to include in such responses.</t>

<t>Clients MAY selectively support this media type. For example, an implementation might deem it only useful (or safe) in CONNECT requests.</t>

<t>Clients SHOULD indicate that they support this media type by including it in the field-value of the Accept request header field <xref target="RFC7231"/> of all supported requests.</t>

<section anchor="example" title="Example">

<t>For example:</t>

<figure><artwork type="example"><![CDATA[
    CONNECT www.example.net:80 HTTP/1.1
    Host: www.example.net
    Accept: application/proxy-explanation+json
    Accept-Language: en-us

    HTTP/1.1 403 Forbidden
    Content-Type: application/proxy-explanation+json
    Cache-Control: no-cache
    
    {
      "name": "Acme Networks"
      "title": "Policy Violation"
      "description": "This content is above your pay grade."
      "moreinfo": "https://acme.example.com/why"
    }
]]></artwork></figure>

<t>A browser might display this to the end user in a manner similar to this:</t>

<figure><artwork type="example"><![CDATA[
    Policy Violation
    
    The proxy "Acme Networks" says:
    
      This content is above your pay grade.
    
    For more information, see: 
      "https://acme.example.com/why?https://www.example.net"
]]></artwork></figure>

</section>
</section>
<section anchor="iana-considerations" title="IANA Considerations">

<t>This specification defines a new Internet Media Type <xref target="RFC6838"/>:</t>

<t><list style="symbols">
  <t>Type name: application</t>
  <t>Subtype name: proxy-explanation+json</t>
  <t>Required parameters: None</t>
  <t>Optional parameters: None; unrecognised parameters should be ignored</t>
  <t>Encoding considerations: Same as <xref target="RFC7159"/></t>
  <t>Security considerations: See <xref target="security"/></t>
  <t>Interoperability considerations: None</t>
  <t>Published specification: [this document]</t>
  <t>Applications that use this media type: HTTP</t>
  <t>Fragment identifier considerations: Same as <xref target="RFC7159"/></t>
  <t>Additional information:
  <list style="symbols">
      <t>Deprecated alias names for this type: N/A</t>
      <t>Magic number(s): N/A</t>
      <t>File extension(s): N/A</t>
      <t>Macintosh file type code(s): N/A</t>
    </list></t>
  <t>Person &amp; email address to contact for further information: Mark Nottingham <eref target="mailto:mnot@mnot.net">mnot@mnot.net</eref></t>
  <t>Intended usage: COMMON</t>
  <t>Restrictions on usage: N/A</t>
  <t>Author: Mark Nottingham <eref target="mailto:mnot@mnot.net">mnot@mnot.net</eref></t>
  <t>Change controller: IESG</t>
</list></t>

</section>
<section anchor="security" title="Security Considerations">

<t>The approach taken in this specification precludes a proxy presenting itself as the origin, provided that, when presented to the user, the information is sufficiently contextualised as being from the proxy.</t>

<t>This approach does not preclude an origin server presenting itself as a the proxy, in cases where the client supports the media type on requests other than CONNECT.</t>

<t>Likewise, it does not prevent a man-in-the-middle from presenting itself as a proxy, in cases where the connection is unencrypted.</t>

<t>Because the payload can contain a URL, it could be used by an attacker (either a hostile origin or MitM, as above) to direct users to an origin under their control. For example, an attacker could convince users that they need to provide payment before the network is available.</t>

<t>An attacker could also include a URL in the textual content of its message (e.g., in the <spanx style="verb">description</spanx> member), to encourage the user to copy the link and follow it.</t>

<t>However, both origins and cleartext MitMs can misrepresent their identities on the Web currently, without the benefit of this mechanism. These risks are introduced only when users trust the “proxy” interface more than they would trust a “normal” Web site.</t>

<t>They can be mitigated in a few ways:</t>

<t><list style="symbols">
  <t>Not displaying the <spanx style="verb">moreinfo</spanx> member in situations when this is possible (i.e., on any response other than that to a CONNECT on an encrypted connection).</t>
  <t>Not supporting the <spanx style="verb">application/proxy-connection+json</spanx> media type when the method is not CONNECT and the connection is not encrypted.</t>
  <t>Cautioning the user that the content might not be trustworthy.</t>
</list></t>

</section>


  </middle>

  <back>

    <references title='Normative References'>





<reference  anchor='RFC2119' target='http://www.rfc-editor.org/info/rfc2119'>
<front>
<title>Key words for use in RFCs to Indicate Requirement Levels</title>
<author initials='S.' surname='Bradner' fullname='S. Bradner'><organization /></author>
<date year='1997' month='March' />
<abstract><t>In many standards track documents several words are used to signify the requirements in the specification.  These words are often capitalized. This document defines these words as they should be interpreted in IETF documents.  This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.</t></abstract>
</front>
<seriesInfo name='BCP' value='14'/>
<seriesInfo name='RFC' value='2119'/>
<seriesInfo name='DOI' value='10.17487/RFC2119'/>
</reference>



<reference  anchor='RFC3986' target='http://www.rfc-editor.org/info/rfc3986'>
<front>
<title>Uniform Resource Identifier (URI): Generic Syntax</title>
<author initials='T.' surname='Berners-Lee' fullname='T. Berners-Lee'><organization /></author>
<author initials='R.' surname='Fielding' fullname='R. Fielding'><organization /></author>
<author initials='L.' surname='Masinter' fullname='L. Masinter'><organization /></author>
<date year='2005' month='January' />
<abstract><t>A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource.  This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet.  The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier.  This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme.  [STANDARDS-TRACK]</t></abstract>
</front>
<seriesInfo name='STD' value='66'/>
<seriesInfo name='RFC' value='3986'/>
<seriesInfo name='DOI' value='10.17487/RFC3986'/>
</reference>



<reference  anchor='RFC6838' target='http://www.rfc-editor.org/info/rfc6838'>
<front>
<title>Media Type Specifications and Registration Procedures</title>
<author initials='N.' surname='Freed' fullname='N. Freed'><organization /></author>
<author initials='J.' surname='Klensin' fullname='J. Klensin'><organization /></author>
<author initials='T.' surname='Hansen' fullname='T. Hansen'><organization /></author>
<date year='2013' month='January' />
<abstract><t>This document defines procedures for the specification and registration of media types for use in HTTP, MIME, and other Internet protocols.  This memo documents an Internet Best Current Practice.</t></abstract>
</front>
<seriesInfo name='BCP' value='13'/>
<seriesInfo name='RFC' value='6838'/>
<seriesInfo name='DOI' value='10.17487/RFC6838'/>
</reference>



<reference  anchor='RFC7159' target='http://www.rfc-editor.org/info/rfc7159'>
<front>
<title>The JavaScript Object Notation (JSON) Data Interchange Format</title>
<author initials='T.' surname='Bray' fullname='T. Bray' role='editor'><organization /></author>
<date year='2014' month='March' />
<abstract><t>JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format.  It was derived from the ECMAScript Programming Language Standard.  JSON defines a small set of formatting rules for the portable representation of structured data.</t><t>This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance.</t></abstract>
</front>
<seriesInfo name='RFC' value='7159'/>
<seriesInfo name='DOI' value='10.17487/RFC7159'/>
</reference>



<reference  anchor='RFC7230' target='http://www.rfc-editor.org/info/rfc7230'>
<front>
<title>Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing</title>
<author initials='R.' surname='Fielding' fullname='R. Fielding' role='editor'><organization /></author>
<author initials='J.' surname='Reschke' fullname='J. Reschke' role='editor'><organization /></author>
<date year='2014' month='June' />
<abstract><t>The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems.  This document provides an overview of HTTP architecture and its associated terminology, defines the &quot;http&quot; and &quot;https&quot; Uniform Resource Identifier (URI) schemes, defines the HTTP/1.1 message syntax and parsing requirements, and describes related security concerns for implementations.</t></abstract>
</front>
<seriesInfo name='RFC' value='7230'/>
<seriesInfo name='DOI' value='10.17487/RFC7230'/>
</reference>



<reference  anchor='RFC7231' target='http://www.rfc-editor.org/info/rfc7231'>
<front>
<title>Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content</title>
<author initials='R.' surname='Fielding' fullname='R. Fielding' role='editor'><organization /></author>
<author initials='J.' surname='Reschke' fullname='J. Reschke' role='editor'><organization /></author>
<date year='2014' month='June' />
<abstract><t>The Hypertext Transfer Protocol (HTTP) is a stateless \%application- level protocol for distributed, collaborative, hypertext information systems.  This document defines the semantics of HTTP/1.1 messages, as expressed by request methods, request header fields, response status codes, and response header fields, along with the payload of messages (metadata and body content) and mechanisms for content negotiation.</t></abstract>
</front>
<seriesInfo name='RFC' value='7231'/>
<seriesInfo name='DOI' value='10.17487/RFC7231'/>
</reference>



<reference  anchor='RFC7234' target='http://www.rfc-editor.org/info/rfc7234'>
<front>
<title>Hypertext Transfer Protocol (HTTP/1.1): Caching</title>
<author initials='R.' surname='Fielding' fullname='R. Fielding' role='editor'><organization /></author>
<author initials='M.' surname='Nottingham' fullname='M. Nottingham' role='editor'><organization /></author>
<author initials='J.' surname='Reschke' fullname='J. Reschke' role='editor'><organization /></author>
<date year='2014' month='June' />
<abstract><t>The Hypertext Transfer Protocol (HTTP) is a stateless \%application- level protocol for distributed, collaborative, hypertext information systems.  This document defines HTTP caches and the associated header fields that control cache behavior or indicate cacheable response messages.</t></abstract>
</front>
<seriesInfo name='RFC' value='7234'/>
<seriesInfo name='DOI' value='10.17487/RFC7234'/>
</reference>




    </references>



<section anchor="acknowledgements" title="Acknowledgements">

<t>Thanks to Thomas Mangin for his suggestions.</t>

</section>


  </back>
</rfc>

