(3rd Round) Proposed API Changes for JEP 114: TLS Server Name Indication (SNI) Extension

[Weijun Wang]

ExtendedSSLSession.java:

+     * @return a non-null immutable map of requested server name types and
+     *        values of the SNI capability, may be empty if the capability
+     *        is not available. The iteration ordering of the map is the same
+     *        as that in the requested server name indication.

Does "capability is not available" mean the client has not sent the extension?

SSLParameters.java:

Do you want to explicitly point out that the vendor-defined value will not show in the map?

289      * whenever the server can be located by a supported name type.

Maybe "determined for a supported name type"?

291      * For example, in the following exampless,

How about simply "In the following examples,"?

 459      * <pre>
 460      *     sslParameters.setServerNamePattern("host_name",
 461      *         Pattern.compile("*\\.example\\.com"));
 462      * </pre>
 463      * means that the server can serve as any hostname in the example.com
 464      * domain.
 
Do you mean ".*\\.example\\.com"?

 511      * If a server name type is not contained in the returned <code>Map</code>,
 512      * an SSL/TLS handshaking should not be interrupted for reasons of
 513      * unrecognized server name of that type.

Is this only Oracle JSSE behavior? Or every vendor should do that? Of course, I have no good idea how a server can get a default pattern.

SSLSocketFactory.java:

 191      * This constructor is normally used to enable SSL/TLS transactions over
 192      * an existing server acceped socket. The returned socket was set to use
 193      * server mode when handshaking (see
 194      * {@link SSLSocket#setUseClientMode(boolean)}).

s/acceped/accepted/. And, what does "was" mean here?

 196      * The <code>consumed</code> data may be used for inspection of inbound
 197      * network data, for example, inspection of Server Name Indication (SNI)
 198      * (See section 3 of <A HREF="http://www.ietf.org/rfc/rfc6066.txt">TLS
 199      * Extensions (RFC6066)</A>).  In this contruction, the
 200      * <code>consumed</code> inbound network data is provided to the returned
 201      * socket's normal I/O streams.

s/contruction/constructor/. I know what you mean but the words are a little strange. Also, maybe you need to mention consumed right in the first line of the method spec. That's why this method is special.

 202      * <P>
 203      * Please NOTE that the application is responsible for ensuring that this
 204      * method must be called before any handshaking occurs, and all
 205      * consumed network data must be resumable from the <code>consumed</code>
 206      * parameter.  Otherwise, the behavior of the returned socket is not
 207      * defined.

I think the precise meaning of "any handshaking occurs" is "any bytes is sent back to client"?

Thanks
Max


----- Original Message -----
From: xuelei.fan at oracle.com
To: security-dev at openjdk.java.net
Sent: Sunday, August 12, 2012 8:51:39 PM GMT +08:00 Beijing / Chongqing / Hong Kong / Urumqi
Subject: (3rd Round) Proposed API Changes for JEP 114: TLS Server Name Indication (SNI) Extension

Hi,

Please review the spec of JEP 114, TLS Server Name Indication (SNI)
Extension.

    http://cr.openjdk.java.net./~xuelei/7068321/webrev_spec.04/

Please read the README to help you understanding the the specification:

   http://cr.openjdk.java.net./~xuelei/7068321/README_04.txt

The major differences comparing with previous webrev are:
1. client mode and server mode will use separated API set.
   For client, the related APIs are:
     setServerName(String type, String value)
     clearServerName(String type)
     disableServerName(String type)
     enableServerName(String type)
     isDisabledServerName(String type)
     getServerNames()

   For server side, the related APIs are:
     setServerNamePattern(String type, Pattern pattern)
     clearServerNamePattern(String type)
     getServerNamePatterns()

2. close the door to use the generated socket in client mode.

   SSLSocketFactory.createSocket(Socket s,
       InputStream consumed, boolean autoClose)

   The returned socket was set in server mode.

Regards,
Xuelei