tls, crypto: add ALPN Support

ALPN is added to tls according to RFC7301, which supersedes NPN.
When the server receives both NPN and ALPN extensions from the client,
ALPN takes precedence over NPN and the server does not send NPN
extension to the client. alpnProtocol in TLSSocket always returns
false when no selected protocol exists by ALPN.
In https server, http/1.1 token is always set when no
options.ALPNProtocols exists.

PR-URL: #2564
Reviewed-By: Fedor Indutny <[email protected]>
Reviewed-By: Ben Noordhuis <[email protected]>

Author: Shigeki Ohtsu

doc/api/tls.markdown

@@ -66,14 +66,15 @@ and tap `R<CR>` (that's the letter `R` followed by a carriage return) a few
 times.
 
 
-## NPN and SNI
+## ALPN, NPN and SNI
 
 <!-- type=misc -->
 
-NPN (Next Protocol Negotiation) and SNI (Server Name Indication) are TLS
+ALPN (Application-Layer Protocol Negotiation Extension), NPN (Next
+Protocol Negotiation) and SNI (Server Name Indication) are TLS
 handshake extensions allowing you:
 
-  * NPN - to use one TLS server for multiple protocols (HTTP, SPDY)
+  * ALPN/NPN - to use one TLS server for multiple protocols (HTTP, SPDY, HTTP/2)
   * SNI - to use one TLS server for multiple hostnames with different SSL
     certificates.
 
@@ -249,6 +250,12 @@ automatically set as a listener for the [secureConnection][] event.  The
   - `NPNProtocols`: An array or `Buffer` of possible NPN protocols. (Protocols
     should be ordered by their priority).
 
+  - `ALPNProtocols`: An array or `Buffer` of possible ALPN
+    protocols. (Protocols should be ordered by their priority). When
+    the server receives both NPN and ALPN extensions from the client,
+    ALPN takes precedence over NPN and the server does not send an NPN
+    extension to the client.
+
   - `SNICallback(servername, cb)`: A function that will be called if client
     supports SNI TLS extension. Two argument will be passed to it: `servername`,
     and `cb`. `SNICallback` should invoke `cb(null, ctx)`, where `ctx` is a
@@ -372,9 +379,16 @@ Creates a new client connection to the given `port` and `host` (old API) or
     fails; `err.code` contains the OpenSSL error code. Default: `true`.
 
   - `NPNProtocols`: An array of strings or `Buffer`s containing supported NPN
-    protocols. `Buffer`s should have following format: `0x05hello0x05world`,
-    where first byte is next protocol name's length. (Passing array should
-    usually be much simpler: `['hello', 'world']`.)
+    protocols. `Buffer`s should have the following format:
+    `0x05hello0x05world`, where first byte is next protocol name's
+    length. (Passing array should usually be much simpler:
+    `['hello', 'world']`.)
+
+  - `ALPNProtocols`: An array of strings or `Buffer`s containing
+    supported ALPN protocols. `Buffer`s should have following format:
+    `0x05hello0x05world`, where the first byte is the next protocol
+    name's length. (Passing array should usually be much simpler:
+    `['hello', 'world']`.)
 
   - `servername`: Servername for SNI (Server Name Indication) TLS extension.
 
@@ -476,6 +490,8 @@ Construct a new TLSSocket object from existing TCP socket.
 
   - `NPNProtocols`: Optional, see [tls.createServer][]
 
+  - `ALPNProtocols`: Optional, see [tls.createServer][]
+
   - `SNICallback`: Optional, see [tls.createServer][]
 
   - `session`: Optional, a `Buffer` instance, containing TLS session
@@ -571,7 +587,13 @@ server. If `socket.authorized` is false, then
 `socket.authorizationError` is set to describe how authorization
 failed. Implied but worth mentioning: depending on the settings of the TLS
 server, you unauthorized connections may be accepted.
-`socket.npnProtocol` is a string containing selected NPN protocol.
+
+`socket.npnProtocol` is a string containing the selected NPN protocol
+and `socket.alpnProtocol` is a string containing the selected ALPN
+protocol, When both NPN and ALPN extensions are received, ALPN takes
+precedence over NPN and the next protocol is selected by ALPN. When
+ALPN has no selected protocol, this returns false.
+
 `socket.servername` is a string containing servername requested with
 SNI.
 
@@ -744,8 +766,9 @@ The listener will be called no matter if the server's certificate was
 authorized or not. It is up to the user to test `tlsSocket.authorized`
 to see if the server certificate was signed by one of the specified CAs.
 If `tlsSocket.authorized === false` then the error can be found in
-`tlsSocket.authorizationError`. Also if NPN was used - you can check
-`tlsSocket.npnProtocol` for negotiated protocol.
+`tlsSocket.authorizationError`. Also if ALPN or NPN was used - you can
+check `tlsSocket.alpnProtocol` or `tlsSocket.npnProtocol` for the
+negotiated protocol.
 
 ### Event: 'OCSPResponse'
 

lib/_tls_legacy.js

@@ -177,7 +177,7 @@ CryptoStream.prototype._write = function write(data, encoding, cb) {
     if (this.pair.encrypted._internallyPendingBytes())
       this.pair.encrypted.read(0);
 
-    // Get NPN and Server name when ready
+    // Get ALPN, NPN and Server name when ready
     this.pair.maybeInitFinished();
 
     // Whole buffer was written
@@ -273,7 +273,7 @@ CryptoStream.prototype._read = function read(size) {
            bytesRead < size &&
            this.pair.ssl !== null);
 
-  // Get NPN and Server name when ready
+  // Get ALPN, NPN and Server name when ready
   this.pair.maybeInitFinished();
 
   // Create new buffer if previous was filled up
@@ -726,6 +726,13 @@ function SecurePair(context, isServer, requestCert, rejectUnauthorized,
     this.npnProtocol = null;
   }
 
+  if (process.features.tls_alpn && options.ALPNProtocols) {
+    // keep reference in secureContext not to be GC-ed
+    this.ssl._secureContext.alpnBuffer = options.ALPNProtocols;
+    this.ssl.setALPNrotocols(this.ssl._secureContext.alpnBuffer);
+    this.alpnProtocol = null;
+  }
+
   /* Acts as a r/w stream to the cleartext side of the stream. */
   this.cleartext = new CleartextStream(this, options.cleartext);
 
@@ -778,6 +785,10 @@ SecurePair.prototype.maybeInitFinished = function() {
       this.npnProtocol = this.ssl.getNegotiatedProtocol();
     }
 
+    if (process.features.tls_alpn) {
+      this.alpnProtocol = this.ssl.getALPNNegotiatedProtocol();
+    }
+
     if (process.features.tls_sni) {
       this.servername = this.ssl.getServername();
     }

lib/_tls_wrap.js

@@ -239,6 +239,7 @@ function TLSSocket(socket, options) {
   this._SNICallback = null;
   this.servername = null;
   this.npnProtocol = null;
+  this.alpnProtocol = null;
   this.authorized = false;
   this.authorizationError = null;
 
@@ -453,6 +454,12 @@ TLSSocket.prototype._init = function(socket, wrap) {
   if (process.features.tls_npn && options.NPNProtocols)
     ssl.setNPNProtocols(options.NPNProtocols);
 
+  if (process.features.tls_alpn && options.ALPNProtocols) {
+    // keep reference in secureContext not to be GC-ed
+    ssl._secureContext.alpnBuffer = options.ALPNProtocols;
+    ssl.setALPNProtocols(ssl._secureContext.alpnBuffer);
+  }
+
   if (options.handshakeTimeout > 0)
     this.setTimeout(options.handshakeTimeout, this._handleTimeout);
 
@@ -559,6 +566,10 @@ TLSSocket.prototype._finishInit = function() {
     this.npnProtocol = this._handle.getNegotiatedProtocol();
   }
 
+  if (process.features.tls_alpn) {
+    this.alpnProtocol = this.ssl.getALPNNegotiatedProtocol();
+  }
+
   if (process.features.tls_sni && this._tlsOptions.isServer) {
     this.servername = this._handle.getServername();
   }
@@ -766,6 +777,7 @@ function Server(/* [options], listener */) {
       rejectUnauthorized: self.rejectUnauthorized,
       handshakeTimeout: timeout,
       NPNProtocols: self.NPNProtocols,
+      ALPNProtocols: self.ALPNProtocols,
       SNICallback: options.SNICallback || SNICallback
     });
 
@@ -876,6 +888,8 @@ Server.prototype.setOptions = function(options) {
     this.honorCipherOrder = true;
   if (secureOptions) this.secureOptions = secureOptions;
   if (options.NPNProtocols) tls.convertNPNProtocols(options.NPNProtocols, this);
+  if (options.ALPNProtocols)
+    tls.convertALPNProtocols(options.ALPNProtocols, this);
   if (options.sessionIdContext) {
     this.sessionIdContext = options.sessionIdContext;
   } else {
@@ -968,8 +982,10 @@ exports.connect = function(/* [port, host], options, cb */) {
                  (options.socket && options.socket._host) ||
                  'localhost',
       NPN = {},
+      ALPN = {},
       context = tls.createSecureContext(options);
   tls.convertNPNProtocols(options.NPNProtocols, NPN);
+  tls.convertALPNProtocols(options.ALPNProtocols, ALPN);
 
   var socket = new TLSSocket(options.socket, {
     pipe: options.path && !options.port,
@@ -979,6 +995,7 @@ exports.connect = function(/* [port, host], options, cb */) {
     rejectUnauthorized: options.rejectUnauthorized,
     session: options.session,
     NPNProtocols: NPN.NPNProtocols,
+    ALPNProtocols: ALPN.ALPNProtocols,
     requestOCSP: options.requestOCSP
   });
 

lib/https.js

@@ -14,6 +14,13 @@ function Server(opts, requestListener) {
     opts.NPNProtocols = ['http/1.1', 'http/1.0'];
   }
 
+  if (process.features.tls_alpn && !opts.ALPNProtocols) {
+    // http/1.0 is not defined as Protocol IDs in IANA
+    // http://www.iana.org/assignments/tls-extensiontype-values
+    //       /tls-extensiontype-values.xhtml#alpn-protocol-ids
+    opts.ALPNProtocols = ['http/1.1'];
+  }
+
   tls.Server.call(this, opts, http._connectionListener);
 
   this.httpAllowHalfOpen = false;

lib/tls.js

@@ -33,27 +33,42 @@ exports.getCiphers = function() {
 
 // Convert protocols array into valid OpenSSL protocols list
 // ("\x06spdy/2\x08http/1.1\x08http/1.0")
-exports.convertNPNProtocols = function convertNPNProtocols(NPNProtocols, out) {
-  // If NPNProtocols is Array - translate it into buffer
-  if (Array.isArray(NPNProtocols)) {
-    var buff = new Buffer(NPNProtocols.reduce(function(p, c) {
-      return p + 1 + Buffer.byteLength(c);
-    }, 0));
-
-    NPNProtocols.reduce(function(offset, c) {
-      var clen = Buffer.byteLength(c);
-      buff[offset] = clen;
-      buff.write(c, offset + 1);
-
-      return offset + 1 + clen;
-    }, 0);
-
-    NPNProtocols = buff;
+function convertProtocols(protocols) {
+  var buff = new Buffer(protocols.reduce(function(p, c) {
+    return p + 1 + Buffer.byteLength(c);
+  }, 0));
+
+  protocols.reduce(function(offset, c) {
+    var clen = Buffer.byteLength(c);
+    buff[offset] = clen;
+    buff.write(c, offset + 1);
+
+    return offset + 1 + clen;
+  }, 0);
+
+  return buff;
+};
+
+exports.convertNPNProtocols  = function(protocols, out) {
+  // If protocols is Array - translate it into buffer
+  if (Array.isArray(protocols)) {
+    protocols = convertProtocols(protocols);
   }
+  // If it's already a Buffer - store it
+  if (protocols instanceof Buffer) {
+    out.NPNProtocols = protocols;
+  }
+};
 
+exports.convertALPNProtocols = function(protocols, out) {
+  // If protocols is Array - translate it into buffer
+  if (Array.isArray(protocols)) {
+    protocols = convertProtocols(protocols);
+  }
   // If it's already a Buffer - store it
-  if (NPNProtocols instanceof Buffer) {
-    out.NPNProtocols = NPNProtocols;
+  if (protocols instanceof Buffer) {
+    // copy new buffer not to be modified by user
+    out.ALPNProtocols = new Buffer(protocols);
   }
 };
 

src/env.h

@@ -42,6 +42,7 @@ namespace node {
 // for the sake of convenience.  Strings should be ASCII-only.
 #define PER_ISOLATE_STRING_PROPERTIES(V)                                      \
   V(address_string, "address")                                                \
+  V(alpn_buffer_string, "alpnBuffer")                                         \
   V(args_string, "args")                                                      \
   V(argv_string, "argv")                                                      \
   V(arrow_message_string, "arrowMessage")                                     \
@@ -205,6 +206,7 @@ namespace node {
   V(timestamp_string, "timestamp")                                            \
   V(title_string, "title")                                                    \
   V(tls_npn_string, "tls_npn")                                                \
+  V(tls_alpn_string, "tls_alpn")                                              \
   V(tls_ocsp_string, "tls_ocsp")                                              \
   V(tls_sni_string, "tls_sni")                                                \
   V(tls_string, "tls")                                                        \

src/node.cc

@@ -2582,6 +2582,13 @@ static Local<Object> GetFeatures(Environment* env) {
 #endif
   obj->Set(env->tls_npn_string(), tls_npn);
 
+#ifdef TLSEXT_TYPE_application_layer_protocol_negotiation
+  Local<Boolean> tls_alpn = True(env->isolate());
+#else
+  Local<Boolean> tls_alpn = False(env->isolate());
+#endif
+  obj->Set(env->tls_alpn_string(), tls_alpn);
+
 #ifdef SSL_CTRL_SET_TLSEXT_SERVERNAME_CB
   Local<Boolean> tls_sni = True(env->isolate());
 #else

src/node_constants.cc

@@ -935,6 +935,11 @@ void DefineOpenSSLConstants(Local<Object> target) {
     NODE_DEFINE_CONSTANT(target, NPN_ENABLED);
 #endif
 
+#ifdef TLSEXT_TYPE_application_layer_protocol_negotiation
+#define ALPN_ENABLED 1
+    NODE_DEFINE_CONSTANT(target, ALPN_ENABLED);
+#endif
+
 #ifdef RSA_PKCS1_PADDING
     NODE_DEFINE_CONSTANT(target, RSA_PKCS1_PADDING);
 #endif