tls: Add PSK support

Stéphan Kochen · Stéphan Kochen · commit ceae0bc27d12 · 2017-03-02T08:35:07.000+01:00
Add the `pskCallback` client/server option, which resolves an identity
or identity (hint) to a pre-shared key. The function signature on client
and server is compatible.

Add the `pskIdentity` server option to set the identity hint for the
ServerKeyExchange message.

Based on work by: Chris Osborn &lt;chris.osborn@sitelier.com&gt;
diff --git a/doc/api/tls.md b/doc/api/tls.md
@@ -12,8 +12,8 @@ const tls = require('tls');
 
 ## TLS/SSL Concepts
 
-The TLS/SSL is a public/private key infrastructure (PKI). For most common
-cases, each client and server must have a *private key*.
+In most common cases, TLS/SSL uses a public/private key infrastructure (PKI).
+Each client and server must have a *private key*.
 
 Private keys can be generated in multiple ways. The example below illustrates
 use of the OpenSSL command-line interface to generate a 2048-bit RSA private
@@ -118,6 +118,26 @@ handshake extensions:
 *Note*: Use of ALPN is recommended over NPN. The NPN extension has never been
 formally defined or documented and generally not recommended for use.
 
+### Pre-shared keys
+
+<!-- type=misc -->
+
+TLS-PSK support is also available as an alternative to normal certificate-based
+authentication. TLS-PSK uses a pre-shared key instead of certificates to
+authenticate a TLS connection, providing mutual authentication.
+
+TLS-PSK and public key infrastructure are not mutually exclusive; clients and
+servers can accommodate both, with the variety determined by the normal cipher
+negotiation step.
+
+Note that TLS-PSK is only a good choice where means exist to securely share a
+key with every connecting machine, so it does not replace PKI for the majority
+of TLS uses.
+
+The TLS-PSK implementation in OpenSSL has also seen many security flaws in
+recent years, mostly because it is used only by a minority of applications.
+Please consider all alternative solutions before switching to PSK ciphers.
+
 ### Client-initiated renegotiation attack mitigation
 
 <!-- type=misc -->
@@ -773,6 +793,14 @@ changes:
     against the list of supplied CAs. An `'error'` event is emitted if
     verification fails; `err.code` contains the OpenSSL error code. Defaults to
     `true`.
+  * `pskCallback(hint)` {Function} When negotiating TLS-PSK, this optional
+    function is called with the identity hint provided by the server. If the
+    client should continue to negotiate PSK ciphers, the return value of this
+    function must be an object in the form `{psk: <string|buffer>, identity:
+    <string>}`. Note that PSK ciphers are disabled by default, and using
+    TLS-PSK thus requires explicitly specifying a cipher suite with the
+    `ciphers` option. Additionally, it may be necessary to disable
+    `rejectUnauthorized` when not intending to use certificates.
   * `NPNProtocols` {string[]|Buffer[]} An array of strings or `Buffer`s
     containing supported NPN protocols. `Buffer`s should have the format
     `[len][name][len][name]...` e.g. `0x05hello0x05world`, where the first
@@ -1036,7 +1064,8 @@ changes:
     session tickets on multiple instances of the TLS server. *Note* that this is
     automatically shared between `cluster` module workers.
   * ...: Any [`tls.createSecureContext()`][] options can be provided. For
-    servers, the identity options (`pfx` or `key`/`cert`) are usually required.
+    servers, the identity options (`pfx`, `key`/`cert` or `pskCallback`) are
+    usually required.
 * `secureConnectionListener` {Function}
 
 Creates a new [tls.Server][].  The `secureConnectionListener`, if provided, is
@@ -1193,6 +1222,14 @@ changes:
 * `rejectUnauthorized` {boolean} `true` to specify whether a server should
   automatically reject clients with invalid certificates. Only applies when
   `isServer` is `true`.
+* `pskCallback(identity)` {Function} When negotiating TLS-PSK, this optional
+  function is called with the identity provided by the client. If the server
+  should continue to negotiate PSK ciphers, the return value of this function
+  must be an object in the form `{psk: <string|buffer>}`. Note that PSK ciphers
+  are disabled by default, and using TLS-PSK thus requires explicitly
+  specifying a cipher suite with the `ciphers` option.
+* `pskIdentity`: {string} The identity hint to send to clients when
+  negotiating TLS-PSK.
 * `options`
   * `secureContext`: An optional TLS context object from
      [`tls.createSecureContext()`][]
diff --git a/lib/_tls_common.js b/lib/_tls_common.js
@@ -111,6 +111,46 @@ exports.createSecureContext = function createSecureContext(options, context) {
     }
   }
 
+  if (options.pskCallback && c.context.enablePskCallback) {
+    c.context.onpskexchange = (identity, maxPskLen, maxIdentLen) => {
+      let ret = options.pskCallback(identity);
+      if (typeof ret !== 'object') {
+        ret = undefined;
+      }
+
+      if (ret) {
+        ret = { psk: ret.psk, identity: ret.identity };
+
+        if (typeof ret.psk === 'string') {
+          ret.psk = Buffer.from(ret.psk);
+        } else if (!Buffer.isBuffer(ret.psk)) {
+          throw new TypeError('Pre-shared key is not a string or buffer');
+        }
+        if (ret.psk.length > maxPskLen) {
+          throw new TypeError(`Pre-shared key exceed ${maxPskLen} bytes`);
+        }
+
+        // Only set for the client callback, which must provide an identity.
+        if (maxIdentLen) {
+          if (typeof ret.identity === 'string') {
+            ret.identity = Buffer.from(ret.identity + '\0');
+          } else {
+            throw new TypeError('PSK identity is not a string');
+          }
+          if (ret.identity.length > maxIdentLen) {
+            throw new TypeError(`PSK identity exceeds ${maxIdentLen} bytes`);
+          }
+        }
+      }
+
+      return ret;
+    };
+    c.context.enablePskCallback();
+
+    if (options.pskIdentity)
+      c.context.setPskIdentity(options.pskIdentity);
+  }
+
   if (options.sessionIdContext) {
     c.context.setSessionIdContext(options.sessionIdContext);
   }
diff --git a/lib/_tls_wrap.js b/lib/_tls_wrap.js
@@ -681,7 +681,7 @@ TLSSocket.prototype.getProtocol = function() {
   return null;
 };
 
-// TODO: support anonymous (nocert) and PSK
+// TODO: support anonymous (nocert)
 
 
 // AUTHENTICATION MODES
@@ -780,6 +780,8 @@ function Server(options, listener) {
     dhparam: self.dhparam,
     secureProtocol: self.secureProtocol,
     secureOptions: self.secureOptions,
+    pskCallback: self.pskCallback,
+    pskIdentity: self.pskIdentity,
     honorCipherOrder: self.honorCipherOrder,
     crl: self.crl,
     sessionIdContext: self.sessionIdContext
@@ -920,6 +922,8 @@ Server.prototype.setOptions = function(options) {
   else
     this.honorCipherOrder = true;
   if (secureOptions) this.secureOptions = secureOptions;
+  if (options.pskIdentity) this.pskIdentity = options.pskIdentity;
+  if (options.pskCallback) this.pskCallback = options.pskCallback;
   if (options.NPNProtocols) tls.convertNPNProtocols(options.NPNProtocols, this);
   if (options.ALPNProtocols)
     tls.convertALPNProtocols(options.ALPNProtocols, this);
diff --git a/src/env.h b/src/env.h
@@ -91,6 +91,7 @@ namespace node {
   V(emitting_top_level_domain_error_string, "_emittingTopLevelDomainError")   \
   V(exchange_string, "exchange")                                              \
   V(enumerable_string, "enumerable")                                          \
+  V(identity_string, "identity")                                              \
   V(idle_string, "idle")                                                      \
   V(irq_string, "irq")                                                        \
   V(encoding_string, "encoding")                                              \
@@ -155,6 +156,7 @@ namespace node {
   V(onnewsession_string, "onnewsession")                                      \
   V(onnewsessiondone_string, "onnewsessiondone")                              \
   V(onocspresponse_string, "onocspresponse")                                  \
+  V(onpskexchange_string, "onpskexchange")                                    \
   V(onread_string, "onread")                                                  \
   V(onreadstart_string, "onreadstart")                                        \
   V(onreadstop_string, "onreadstop")                                          \
@@ -175,6 +177,7 @@ namespace node {
   V(preference_string, "preference")                                          \
   V(priority_string, "priority")                                              \
   V(produce_cached_data_string, "produceCachedData")                          \
+  V(psk_string, "psk")                                                        \
   V(raw_string, "raw")                                                        \
   V(readable_string, "readable")                                              \
   V(received_shutdown_string, "receivedShutdown")                             \
diff --git a/src/node_crypto.cc b/src/node_crypto.cc
@@ -305,6 +305,13 @@ void SecureContext::Initialize(Environment* env, Local<Object> target) {
   env->SetProtoMethod(t, "getCertificate", SecureContext::GetCertificate<true>);
   env->SetProtoMethod(t, "getIssuer", SecureContext::GetCertificate<false>);
 
+#ifdef OPENSSL_PSK_SUPPORT
+  env->SetProtoMethod(t, "setPskIdentity", SecureContext::SetPskIdentity);
+  env->SetProtoMethod(t,
+                      "enablePskCallback",
+                      SecureContext::EnablePskCallback);
+#endif
+
   t->Set(FIXED_ONE_BYTE_STRING(env->isolate(), "kTicketKeyReturnIndex"),
          Integer::NewFromUnsigned(env->isolate(), kTicketKeyReturnIndex));
   t->Set(FIXED_ONE_BYTE_STRING(env->isolate(), "kTicketKeyHMACIndex"),
@@ -1287,6 +1294,120 @@ void SecureContext::GetCertificate(const FunctionCallbackInfo<Value>& args) {
 }
 
 
+#ifdef OPENSSL_PSK_SUPPORT
+
+void SecureContext::SetPskIdentity(const FunctionCallbackInfo<Value>& args) {
+  SecureContext* wrap = Unwrap<SecureContext>(args.Holder());
+
+  if (args.Length() != 1 || !args[0]->IsString()) {
+    return wrap->env()->ThrowTypeError("Argument must be a string");
+  }
+
+  String::Utf8Value identity(args[0]);
+  if (!SSL_CTX_use_psk_identity_hint(wrap->ctx_, *identity)) {
+    return wrap->env()->ThrowError("Failed to set PSK identity hint");
+  }
+}
+
+void SecureContext::EnablePskCallback(
+    const FunctionCallbackInfo<Value>& args) {
+  SecureContext* wrap = Unwrap<SecureContext>(args.Holder());
+
+  SSL_CTX_set_psk_server_callback(wrap->ctx_,
+                                  SecureContext::PskServerCallback);
+  SSL_CTX_set_psk_client_callback(wrap->ctx_,
+                                  SecureContext::PskClientCallback);
+}
+
+unsigned int SecureContext::PskServerCallback(SSL *ssl,
+                                              const char *identity,
+                                              unsigned char *psk,
+                                              unsigned int max_psk_len) {
+  SecureContext* sc = static_cast<SecureContext*>(
+      SSL_CTX_get_app_data(ssl->ctx));
+
+  Environment* env = sc->env();
+  Isolate* isolate = env->isolate();
+
+  Local<Value> argv[] = {
+    String::NewFromUtf8(isolate, identity),
+    Integer::NewFromUnsigned(isolate, max_psk_len),
+    Integer::NewFromUnsigned(isolate, 0)
+  };
+  Local<Value> ret = node::MakeCallback(env,
+                                        sc->object(),
+                                        env->onpskexchange_string(),
+                                        arraysize(argv),
+                                        argv);
+
+  // The result is expected to be an object. If it isn't, then return 0,
+  // indicating the identity wasn't found.
+  if (!ret->IsObject()) {
+    return 0;
+  }
+  Local<Object> obj = ret.As<Object>();
+
+  Local<Value> psk_buf = obj->Get(env->psk_string());
+  assert(Buffer::HasInstance(psk_buf));
+  size_t psk_len = Buffer::Length(psk_buf);
+  assert(psk_len <= max_psk_len);
+  memcpy(psk, Buffer::Data(psk_buf), max_psk_len);
+
+  return psk_len;
+}
+
+unsigned int SecureContext::PskClientCallback(SSL *ssl,
+                                              const char *hint,
+                                              char *identity,
+                                              unsigned int max_identity_len,
+                                              unsigned char *psk,
+                                              unsigned int max_psk_len) {
+  SecureContext* sc = static_cast<SecureContext*>(
+      SSL_CTX_get_app_data(ssl->ctx));
+
+  Environment* env = sc->env();
+  Isolate* isolate = env->isolate();
+
+  Local<Value> argv[] = {
+    Null(isolate),
+    Integer::NewFromUnsigned(isolate, max_psk_len),
+    Integer::NewFromUnsigned(isolate, max_identity_len)
+  };
+  if (hint != nullptr) {
+    argv[0] = String::NewFromUtf8(isolate, hint);
+  }
+  Local<Value> ret = node::MakeCallback(env,
+                                        sc->object(),
+                                        env->onpskexchange_string(),
+                                        arraysize(argv),
+                                        argv);
+
+  // The result is expected to be an object. If it isn't, then return 0,
+  // indicating the identity wasn't found.
+  if (!ret->IsObject()) {
+    return 0;
+  }
+  Local<Object> obj = ret.As<Object>();
+
+  Local<Value> psk_buf = obj->Get(env->psk_string());
+  assert(Buffer::HasInstance(psk_buf));
+  size_t psk_len = Buffer::Length(psk_buf);
+  assert(psk_len <= max_psk_len);
+  memcpy(psk, Buffer::Data(psk_buf), psk_len);
+
+  Local<Value> identity_buf = obj->Get(env->identity_string());
+  assert(Buffer::HasInstance(identity_buf));
+  size_t identity_len = Buffer::Length(identity_buf);
+  assert(identity_len <= max_identity_len);
+  memcpy(identity, Buffer::Data(identity_buf), identity_len);
+  assert(identity[identity_len - 1] == '\0');
+
+  return psk_len;
+}
+
+#endif
+
+
 template <class Base>
 void SSLWrap<Base>::AddMethods(Environment* env, Local<FunctionTemplate> t) {
   HandleScope scope(env->isolate());
diff --git a/src/node_crypto.h b/src/node_crypto.h
@@ -38,6 +38,13 @@
 # define NODE__HAVE_TLSEXT_STATUS_CB
 #endif  // !defined(OPENSSL_NO_TLSEXT) && defined(SSL_CTX_set_tlsext_status_cb)
 
+// TLS-PSK support requires OpenSSL v1.0.0 or later built with PSK enabled
+#if OPENSSL_VERSION_NUMBER >= 0x10000000L
+#ifndef OPENSSL_NO_PSK
+#define OPENSSL_PSK_SUPPORT
+#endif
+#endif
+
 namespace node {
 namespace crypto {
 
@@ -123,6 +130,23 @@ class SecureContext : public BaseObject {
   template <bool primary>
   static void GetCertificate(const v8::FunctionCallbackInfo<v8::Value>& args);
 
+#ifdef OPENSSL_PSK_SUPPORT
+  static void SetPskIdentity(const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void EnablePskCallback(
+      const v8::FunctionCallbackInfo<v8::Value>& args);
+
+  static unsigned int PskServerCallback(SSL *ssl,
+                                        const char *identity,
+                                        unsigned char *psk,
+                                        unsigned int max_psk_len);
+  static unsigned int PskClientCallback(SSL *ssl,
+                                        const char *hint,
+                                        char *identity,
+                                        unsigned int max_identity_len,
+                                        unsigned char *psk,
+                                        unsigned int max_psk_len);
+#endif
+
   static int TicketKeyCallback(SSL* ssl,
                                unsigned char* name,
                                unsigned char* iv,
diff --git a/test/parallel/test-tls-psk-circuit.js b/test/parallel/test-tls-psk-circuit.js
diff --git a/test/parallel/test-tls-psk-client.js b/test/parallel/test-tls-psk-client.js
diff --git a/test/parallel/test-tls-psk-server.js b/test/parallel/test-tls-psk-server.js
