OpenSSL TLS bindings.

c++/src/kj/compat/make-test-certs.sh

+#! /bin/bash
+# Copyright (c) 2016 Sandstorm Development Group, Inc. and contributors
+# Licensed under the MIT License:
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+# This script generates the test keys and certificates used in tls-test.c++.
+
+set -euxo pipefail
+
+mkdir -p tmp/test-certs
+cd tmp/test-certs
+
+# Clean up from previous runs.
+rm -rf demoCA *.key *.csr *.crt
+
+# Function to fake out OpenSSL CA configuration. Pass base name of files as parameter.
+setup_ca_dir() {
+  rm -rf demoCA
+  mkdir -p demoCA/private demoCA/newcerts
+  ln -s ../../$1.key demoCA/private/cakey.pem
+  ln -s ../$1.crt demoCA/cacert.pem
+  touch demoCA/index.txt
+  echo 1000 > demoCA/serial
+}
+
+# Create CA key and root cert
+openssl genrsa -out ca.key 4096
+openssl req -key ca.key -new -x509 -days 36500 -sha256 -extensions v3_ca -out ca.crt << EOF
+US
+California
+Palo Alto
+Sandstorm.io
+Testing Department
+ca.example.com
+garply@sandstorm.io
+EOF
+echo
+
+# Create intermediate certificate and CSR.
+openssl genrsa -out int.key 4096
+openssl req -new -sha256 -key int.key -out int.csr << EOF
+US
+California
+Palo Alto
+Sandstorm.io
+Testing Department
+int-ca.example.com
+garply@sandstorm.io
+
+
+EOF
+echo
+
+# Sign the intermediate cert with the CA key.
+setup_ca_dir ca
+openssl ca -extensions v3_ca -days 36500 -notext -md sha256 -in int.csr -out int.crt << EOF
+y
+y
+EOF
+cat ca.crt int.crt > ca-chain.crt
+
+# Create host key and CSR
+openssl genrsa -out example.key 4096
+openssl req -new -sha256 -key example.key -out example.csr << EOF
+US
+California
+Palo Alto
+Sandstorm.io
+Testing Department
+example.com
+garply@sandstorm.io
+
+
+EOF
+echo
+
+# Sign valid host certificate with intermediate CA.
+setup_ca_dir int
+openssl ca -extensions v3_ca -days 36524 -notext -md sha256 -in example.csr -out valid.crt << EOF
+y
+y
+EOF
+
+# Sign expired host certificate with intermediate CA.
+setup_ca_dir int
+openssl ca -extensions v3_ca -startdate 160101000000Z -enddate 160101000000Z -notext -md sha256 -in example.csr -out expired.crt << EOF
+y
+y
+EOF
+
+# Create self-signed host certificate.
+openssl req -key example.key -new -x509 -days 36524 -sha256 -out self.crt << EOF
+US
+California
+Palo Alto
+Sandstorm.io
+Testing Department
+example.com
+garply@sandstorm.io
+EOF
+echo
+
+# Cleanup
+rm -rf demoCA
+
+# Output code.
+write_constant() {
+  echo "static constexpr char $1[] ="
+  sed -e 's/^.*$/    "\0\\n"/g;s/--END .*$/\0;/g' $2
+  echo
+}
+
+echo "Writing code to: tmp/test-certs/test-keys.h"
+
+exec 1> test-keys.h
+write_constant CA_CERT ca.crt
+write_constant INTERMEDIATE_CERT int.crt
+write_constant HOST_KEY example.key
+write_constant VALID_CERT valid.crt
+write_constant EXPIRED_CERT expired.crt
+write_constant SELF_SIGNED_CERT self.crt

c++/src/kj/compat/tls.h

+// Copyright (c) 2016 Sandstorm Development Group, Inc. and contributors
+// Licensed under the MIT License:
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
+#ifndef KJ_COMPAT_TLS_H_
+#define KJ_COMPAT_TLS_H_
+// This file implements TLS (aka SSL) encrypted networking. It is actually a wrapper, currently
+// around OpenSSL / BoringSSL / LibreSSL, but the interface is intended to remain
+// implementation-agnostic.
+//
+// Unlike OpenSSL's API, the API defined in this file is intended to be hard to use wrong. Good
+// ciphers and settings are used by default. Certificates validation is performed automatically
+// and cannot be bypassed.
+
+#include <kj/async-io.h>
+
+namespace kj {
+
+class TlsPrivateKey;
+class TlsCertificate;
+struct TlsKeypair;
+class TlsSniCallback;
+
+enum class TlsVersion {
+  SSL_3,     // avoid; cryptographically broken
+  TLS_1_0,
+  TLS_1_1,
+  TLS_1_2
+};
+
+class TlsContext {
+  // TLS system. Allocate one of these, configure it with the proper keys and certificates (or
+  // use the defaults), and then use it to wrap the standard KJ network interfaces in
+  // implementations that transparently use TLS.
+
+public:
+  struct Options {
+    Options();
+    // Initializes all values to reasonable defaults.
+
+    bool useSystemTrustStore;
+    // Whether or not to trust the system's default trust store. Default: true.
+
+    kj::ArrayPtr<const TlsCertificate> trustedCertificates;
+    // Additional certificates which should be trusted. Default: none.
+
+    TlsVersion minVersion;
+    // Minimum version. Defaults to minimum version that hasn't been cryptographically broken.
+    // If you override this, consider doing:
+    //
+    //     options.minVersion = kj::max(myVersion, options.minVersion);
+
+    kj::StringPtr cipherList;
+    // OpenSSL cipher list string. The default is a curated list designed to be compatible with
+    // almost all software in curent use (specifically, based on Mozilla's "intermediate"
+    // recommendations). The defaults will change in future versions of this library to account
+    // for the latest cryptanalysis.
+    //
+    // Generally you should only specify your own `cipherList` if:
+    // - You have extreme backwards-compatibility needs and wish to enable obsolete and/or broken
+    //   algorithms.
+    // - You need quickly to disable an algorithm recently discovered to be broken.
+
+    kj::Maybe<const TlsKeypair&> defaultKeypair;
+    // Default keypair to use for all connections. Required for servers; optional for clients.
+
+    kj::Maybe<TlsSniCallback&> sniCallback;
+    // Callback that can be used to choose a different key/certificate based on the specific
+    // hostname requested by the client.
+  };
+
+  TlsContext(Options options = Options());
+  ~TlsContext() noexcept(false);
+  KJ_DISALLOW_COPY(TlsContext);
+
+  kj::Promise<kj::Own<kj::AsyncIoStream>> wrapServer(kj::Own<kj::AsyncIoStream> stream);
+  // Upgrade a regular network stream to TLS and begin the initial handshake as the server. The
+  // returned promise resolves when the handshake has completed successfully.
+
+  kj::Promise<kj::Own<kj::AsyncIoStream>> wrapClient(
+      kj::Own<kj::AsyncIoStream> stream, kj::StringPtr expectedServerHostname);
+  // Upgrade a regular network stream to TLS and begin the initial handshake as a client. The
+  // returned promise resolves when the handshake has completed successfully, including validating
+  // the server's certificate.
+  //
+  // You must specify the server's hostname. This is used for two purposes:
+  // 1. It is sent to the server in the initial handshake via the TLS SNI extension, so that a
+  //    server serving multiple hosts knows which certificate to use.
+  // 2. The server's certificate is validated against this hostname. If validation fails, the
+  //    promise returned by wrapClient() will be broken; you'll never get a stream.
+
+  kj::Own<kj::ConnectionReceiver> wrapPort(kj::Own<kj::ConnectionReceiver> port);
+  // Upgrade a ConnectionReceiver to one that automatically upgrades all accepted connections to
+  // TLS (acting as the server).
+
+  kj::Own<kj::Network> wrapNetwork(kj::Network& network);
+  // Upgrade a Network to one that automatically upgrades all connections to TLS. The network will
+  // only accept addresses of the form "hostname" and "hostname:port" (it does not accept raw IP
+  // addresses). It will automatically use SNI and verify certificates based on these hostnames.
+
+private:
+  void* ctx;  // actually type SSL_CTX, but we don't want to #include the OpenSSL headers here
+
+  static int sniCallback(void* ssl, int* ad, void* arg);
+};
+
+class TlsPrivateKey {
+  // A private key suitable for use in a TLS server.
+
+public:
+  TlsPrivateKey(kj::ArrayPtr<const byte> asn1);
+  // Parse a single binary (ASN1) private key. Supports PKCS8 keys as well as "traditional format"
+  // RSA and DSA keys. Does not accept encrypted keys; it is the caller's responsibility to
+  // decrypt.
+
+  TlsPrivateKey(kj::StringPtr pem);
+  // Parse a single PEM-encoded private key. Supports PKCS8 keys as well as "traditional format"
+  // RSA and DSA keys. Does not accept encrypted keys; it is the caller's responsibility to
+  // decrypt.
+
+  ~TlsPrivateKey() noexcept(false);
+
+  TlsPrivateKey(const TlsPrivateKey& other);
+  TlsPrivateKey& operator=(const TlsPrivateKey& other);
+  // Copy-by-refcount.
+
+  inline TlsPrivateKey(TlsPrivateKey&& other): pkey(other.pkey) { other.pkey = nullptr; }
+  inline TlsPrivateKey& operator=(TlsPrivateKey&& other) {
+    pkey = other.pkey; other.pkey = nullptr;
+    return *this;
+  }
+
+private:
+  void* pkey;  // actually type EVP_PKEY*
+
+  friend class TlsContext;
+};
+
+class TlsCertificate {
+  // A TLS certificate, possibly with chained intermediate certificates.
+
+public:
+  TlsCertificate(kj::ArrayPtr<const byte> asn1);
+  // Parse a single binary (ASN1) X509 certificate.
+
+  TlsCertificate(kj::ArrayPtr<const kj::ArrayPtr<const byte>> asn1);
+  // Parse a chain of binary (ASN1) X509 certificates.
+
+  TlsCertificate(kj::StringPtr pem);
+  // Parse a PEM-encode X509 certificate or certificate chain. A chain can be constructed by
+  // concatenating multiple PEM-encoded certificates, starting with the leaf certificate.
+
+  ~TlsCertificate() noexcept(false);
+
+  TlsCertificate(const TlsCertificate& other);
+  TlsCertificate& operator=(const TlsCertificate& other);
+  // Copy-by-refcount.
+
+  inline TlsCertificate(TlsCertificate&& other) {
+    memcpy(chain, other.chain, sizeof(chain));
+    memset(other.chain, 0, sizeof(chain));
+  }
+  inline TlsCertificate& operator=(TlsCertificate&& other) {
+    memcpy(chain, other.chain, sizeof(chain));
+    memset(other.chain, 0, sizeof(chain));
+    return *this;
+  }
+
+private:
+  void* chain[10];
+  // Actually type X509*[10].
+  //
+  // Note that OpenSSL has a default maximum cert chain length of 10. Although configurable at
+  // runtime, you'd actually have to convince the _peer_ to reconfigure, which is unlikely except
+  // in specific use cases. So to avoid excess allocations we just assume a max of 10 certs.
+  //
+  // If this proves to be a problem, we should maybe use STACK_OF(X509) here, but stacks are not
+  // refcounted -- the X509_chain_up_ref() function actually allocates a new stack and uprefs all
+  // the certs.
+
+  friend class TlsContext;
+};
+
+struct TlsKeypair {
+  // A pair of a private key and a certificate, for use by a server.
+
+  TlsPrivateKey privateKey;
+  TlsCertificate certificate;
+};
+
+class TlsSniCallback {
+  // Callback object to implement Server Name Indication, in which the server is able to decide
+  // what key and certificate to use based on the hostname that the client is requesting.
+  //
+  // TODO(someday): Currently this callback is synchronous, because the OpenSSL API seems to be
+  //   synchronous. Other people (e.g. Node) have figured out how to do it asynchronously, but
+  //   it's unclear to me if and how this is possible while using the OpenSSL APIs. It looks like
+  //   Node may be manually parsing the ClientHello message rather than relying on OpenSSL. We
+  //   could do that but it's too much work for today.
+
+public:
+  virtual kj::Maybe<TlsKeypair> getKey(kj::StringPtr hostname) = 0;
+  // Get the key to use for `hostname`. Null return means use the default from
+  // TlsContext::Options::defaultKeypair.
+};
+
+} // namespace kj
+
+#endif // KJ_COMPAT_TLS_H_