Summary
-------

Implement the W3C [Cross Origin Resource Sharing (CORS) protocol][cors]
in order to align Java's HTTP stack with HTML5 and current web browsers.


Motivation
----------

Java code running under a security manager is currently restricted by the
[same origin policy][sop]: Network connections can only be made to the
code's origin unless explicit permissions are granted.

The World-Wide Web is moving towards a less-restrictive policy based on
an open standard called [Cross Origin Resource Sharing (CORS)][cors].
CORS defines a protocol by which a web client can interact with a server
to authorize specific cross-origin requests.


Description
-----------

The CORS protocol adds some extra headers, processing steps, and possibly
an additional request/response round-trip when interacting with a
resource named by a URL.  CORS defines certain HTTP requests as _simple_
requests.  Simple requests are always allowed without prior authorization
from the server.  A non-simple request must be preceded by a special
_pre-flight_ request to ask the server if the non-simple request will be
allowed.  Authorization results are cached.

The CORS protocol is largely transparent to application code.  A small
API may be defined whose principal function is to enable CORS on a
per-connection basis, but a system property may also be defined to enable
it globally on all connections, so that existing code can leverage CORS
without needing to be modified.  The API would also cover the use cases
where the following flags need to be specified:

  - Whether credentials (_i.e._, cookies or HTTP authentication) are to
    be used in this potentially cross-origin request; and

  - Whether a pre-flight request should be forced, even if a (pre-flight)
    result has already been cached.

The API might look like this:

    public class java.net.HttpURLConnection {
        :
        public void setCORSParameters(
            boolean enable,
            boolean omitCredentials,
            boolean forcePreflight
        ) { ... }
    }

Code example:

     URL url = new URL("http://www.server.com/cross-origin-request/");
     HttpURLConnection urlc = (HttpURLConnection)url.openConnection();
     urlc.setCORSParameters(true, false, false);
     urlc.setRequestMethod("POST");
     urlc.setRequestProperty("Content-Type", "application/xml");
     urlc.setDoOutput(true);
     OutputStream os = urlc.getOutputStream();
     os.write(... request body ...);
     ...

The [CORS protocol definition][cors] is stable but not yet final, so this
feature might not initially be implemented as a public API in the
`java.net` package.  If not then it will be implemented as a JDK-specific
API or system property, which could evolve as needed along with the
protocol.


Testing
-------

This feature introduces a new protocol mechanism that needs to be tested,
either against real third party HTTP servers or using tests implemented
on top of the JDK's built-in HTTP server.

A simple unit-test framework has been developed using the JDK's HTTP
server.  A test is specified as a set comprising a client API call,
expected HTTP requests and responses as seen by the server, and an API
response as seen by the client.  The development work for this feature
will include a set of such unit tests.


Risks and Assumptions
---------------------

The [CORS protocol definition][cors] is a W3C "Candidate Recommendation"
as of January 2013.  It was intended to become a "Proposed
Recommendation" by the beginning of March, but that did not happen. If
the CORS protocol definition changes then this feature will have to be
revised accordingly.


Dependences
-----------

This feature depends on [JEP 140: Limited doPrivileged](JDK-8046130).


Impact
------

  - Compatibility: New behavior will be enabled through a new API or a
    system property.

  - Security: Will need to be reviewed carefully since this feature does
    relax the network security model in two ways:

      1. No explicit network permission will be required for certain
         (simple) cross-origin HTTP requests, as defined by CORS.

      2. Permissions for other (non simple) requests will be delegated to
         the server hosting the target resource.

  - TCK: One new method added to the existing `HttpURLConnection` class,
    plus some minor changes to existing `java.security` classes.


[cors]: http://www.w3.org/TR/cors/
[sop]: http://en.wikipedia.org/wiki/Same_origin_policy