Switching to netty-tcnative-boringssl-static

nmittler · nmittler · commit 1dce8df07766 · 2016-02-16T13:11:45.000-08:00
diff --git a/.travis.yml b/.travis.yml
@@ -5,10 +5,9 @@ language: java
 env:
   global:
     - PROTOBUF_VERSION=3.0.0-beta-2
-    - OPENSSL_VERSION=1.0.2d
     - LDFLAGS=-L/tmp/protobuf-${PROTOBUF_VERSION}/lib
     - CXXFLAGS=-I/tmp/protobuf-${PROTOBUF_VERSION}/include
-    - LD_LIBRARY_PATH=/tmp/protobuf-${PROTOBUF_VERSION}/lib:/tmp/openssl-${OPENSSL_VERSION}/lib
+    - LD_LIBRARY_PATH=/tmp/protobuf-${PROTOBUF_VERSION}/lib
 
 before_install:
     # Work around https://github.com/travis-ci/travis-ci/issues/2317
@@ -42,7 +41,6 @@ notifications:
 cache:
   directories:
     - /tmp/protobuf-${PROTOBUF_VERSION}
-    - /tmp/openssl-${OPENSSL_VERSION}
     - $HOME/.m2/repository/io/netty
     - $HOME/.gradle/caches/modules-2
     - $HOME/.gradle/wrapper
diff --git a/SECURITY.md b/SECURITY.md
@@ -16,29 +16,101 @@ You may need to [update the security provider](https://developer.android.com/tra
 
 ## TLS with OpenSSL
 
-This is currently the recommended approach for using gRPC over TLS (on non-Android systems). 
+This is currently the recommended approach for using gRPC over TLS (on non-Android systems).
 
-### Benefits of using OpenSSL
+The main benefits of using OpenSSL are:
 
 1. **Speed**: In local testing, we've seen performance improvements of 3x over the JDK. GCM, which is used by the only cipher suite required by the HTTP/2 spec, is 10-500x faster.
 2. **Ciphers**: OpenSSL has its own ciphers and is not dependent on the limitations of the JDK. This allows supporting GCM on Java 7.
 3. **ALPN to NPN Fallback**: if the remote endpoint doesn't support ALPN.
 4. **Version Independence**: does not require using a different library version depending on the JDK update.
 
-### Requirements for using OpenSSL
+Support for OpenSSL is only provided for the Netty transport via [netty-tcnative](https://github.com/netty/netty-tcnative), which is a fork of
+[Apache Tomcat's tcnative](http://tomcat.apache.org/native-doc/), a JNI wrapper around OpenSSL.
 
-1. Currently only supported by the Netty transport (via netty-tcnative).
-2. [OpenSSL](https://www.openssl.org/) version >= 1.0.2 for ALPN support, or version >= 1.0.1 for NPN.
-3. [netty-tcnative](https://github.com/netty/netty-tcnative) version >= 1.1.33.Fork7 must be on classpath.
-4. Supported platforms (for netty-tcnative): `linux-x86_64`, `mac-x86_64`, `windows-x86_64`. Supporting other platforms will require manually building netty-tcnative.
+### OpenSSL: Dynamic vs Static (which to use?)
 
-If the above requirements met, the Netty transport will automatically select OpenSSL as the default TLS provider.
+As of version `1.1.33.Fork13`, netty-tcnative provides two options for usage: statically or dynamically linked. For simplification of initial setup,
+we recommend that users first look at `netty-tcnative-boringssl-static`, which is statically linked against BoringSSL and Apache APR. Using this artifact requires no extra installation and guarantees that ALPN and the ciphers required for
+HTTP/2 are available.
 
-### Configuring netty-tcnative
+Production systems, however, may require an easy upgrade path for OpenSSL security patches. In this case, relying on the statically linked artifact also implies waiting for the Netty team
+to release the new artifact to Maven Central, which can take some time. A better solution in this case is to use the dynamically linked `netty-tcnative` artifact, which allows the site administrator
+to easily upgrade OpenSSL in the standard way (e.g. apt-get) without relying on any new builds from Netty.
 
-[Netty-tcnative](https://github.com/netty/netty-tcnative) is a fork of [Apache Tomcat's tcnative](http://tomcat.apache.org/native-doc/), a JNI wrapper around OpenSSL.
+### OpenSSL: Statically Linked (netty-tcnative-boringssl-static)
 
-Netty uses classifiers when deploying to [Maven Central](http://repo1.maven.org/maven2/io/netty/netty-tcnative/) to provide distributions for the various platforms. On Linux it should be noted that OpenSSL uses a different soname for Fedora derivatives than other Linux releases. To work around this limitation, netty-tcnative deploys two separate versions for linux.
+This is the simplest way to configure the Netty transport for OpenSSL. You just need to add the appropriate `netty-tcnative-boringssl-static` artifact to your application's classpath.
+
+Artifacts are available on [Maven Central](http://repo1.maven.org/maven2/io/netty/netty-tcnative-boringssl-static/) for the following platforms:
+
+Maven Classifier | Description
+---------------- | -----------
+windows-x86_64 | Windows distribution
+osx-x86_64 | Mac distribution
+linux-x86_64 | Linux distribution
+
+##### Getting netty-tcnative-boringssl-static from Maven
+
+In Maven, you can use the [os-maven-plugin](https://github.com/trustin/os-maven-plugin) to help simplify the dependency.
+
+```xml
+<project>
+  <dependencies>
+    <dependency>
+      <groupId>io.netty</groupId>
+      <artifactId>netty-tcnative-boringssl-static</artifactId>
+      <version>1.1.33.Fork13</version>
+      <classifier>${os.detected.classifier}</classifier>
+    </dependency>
+  </dependencies>
+
+  <build>
+    <extensions>
+      <!-- Use os-maven-plugin to initialize the "os.detected" properties -->
+      <extension>
+        <groupId>kr.motd.maven</groupId>
+        <artifactId>os-maven-plugin</artifactId>
+        <version>1.4.0.Final</version>
+      </extension>
+    </extensions>
+  </build>
+</project>
+```
+
+##### Getting netty-tcnative-boringssl-static from Gradle
+
+Gradle you can use the [osdetector-gradle-plugin](https://github.com/google/osdetector-gradle-plugin), which is a wrapper around the os-maven-plugin.
+
+```gradle
+buildscript {
+  repositories {
+    mavenCentral()
+  }
+  dependencies {
+    classpath 'com.google.gradle:osdetector-gradle-plugin:1.4.0'
+  }
+}
+
+// Use the osdetector-gradle-plugin
+apply plugin: "com.google.osdetector"
+
+dependencies {
+    compile 'io.netty:netty-tcnative-boringssl-static:1.1.33.Fork13:' + osdetector.classifier
+}
+```
+
+### OpenSSL: Dynamically Linked (netty-tcnative)
+
+If for any reason you need to dynamically link against OpenSSL (e.g. you need control over the version of OpenSSL), you can instead use the `netty-tcnative` artifact.
+
+Requirements:
+
+1. [OpenSSL](https://www.openssl.org/) version >= 1.0.2 for ALPN support, or version >= 1.0.1 for NPN.
+2. [Apache APR library (libapr-1)](https://apr.apache.org/) version >= 1.5.2.
+3. [netty-tcnative](https://github.com/netty/netty-tcnative) version >= 1.1.33.Fork7 must be on classpath. Prior versions only supported NPN and only Fedora-derivatives were supported for Linux.
+
+Artifacts are available on [Maven Central](http://repo1.maven.org/maven2/io/netty/netty-tcnative/) for the following platforms:
 
 Classifier | Description
 ---------------- | -----------
@@ -47,9 +119,9 @@ osx-x86_64 | Mac distribution
 linux-x86_64 | Used for non-Fedora derivatives of Linux
 linux-x86_64-fedora | Used for Fedora derivatives
 
-*NOTE: Make sure you use a version of netty-tcnative >= 1.1.33.Fork7.  Prior versions only supported NPN and only Fedora-derivatives were supported for Linux.*
+On Linux it should be noted that OpenSSL uses a different soname for Fedora derivatives than other Linux releases. To work around this limitation, netty-tcnative deploys two separate versions for linux.
 
-#### Getting netty-tcnative from Maven
+##### Getting netty-tcnative from Maven
 
 In Maven, you can use the [os-maven-plugin](https://github.com/trustin/os-maven-plugin) to help simplify the dependency.
 
@@ -59,7 +131,7 @@ In Maven, you can use the [os-maven-plugin](https://github.com/trustin/os-maven-
     <dependency>
       <groupId>io.netty</groupId>
       <artifactId>netty-tcnative</artifactId>
-      <version>1.1.33.Fork11</version>
+      <version>1.1.33.Fork13</version>
       <classifier>${tcnative.classifier}</classifier>
     </dependency>
   </dependencies>
@@ -102,7 +174,7 @@ In Maven, you can use the [os-maven-plugin](https://github.com/trustin/os-maven-
 </project>
 ```
 
-#### Getting netty-tcnative from Gradle
+##### Getting netty-tcnative from Gradle
 
 Gradle you can use the [osdetector-gradle-plugin](https://github.com/google/osdetector-gradle-plugin), which is a wrapper around the os-maven-plugin.
 
@@ -127,7 +199,7 @@ if (osdetector.os == "linux" && osdetector.release.isLike("fedora")) {
 }
 
 dependencies {
-    compile 'io.netty:netty-tcnative:1.1.33.Fork11:' + tcnative_classifier
+    compile 'io.netty:netty-tcnative:1.1.33.Fork13:' + tcnative_classifier
 }
 ```
 
diff --git a/build.gradle b/build.gradle
@@ -118,13 +118,6 @@ subprojects {
           }
         }
 
-        def tcnative_suffix = osdetector.classifier;
-        // Fedora variants use a different soname for OpenSSL than other linux distributions
-        // (see http://netty.io/wiki/forked-tomcat-native.html).
-        if (osdetector.os == "linux" && osdetector.release.isLike("fedora")) {
-            tcnative_suffix += "-fedora";
-        }
-
         def epoll_suffix = "";
         if (osdetector.classifier in ["linux-x86_64"]) {
             // The native code is only pre-compiled on certain platforms.
@@ -145,7 +138,7 @@ subprojects {
 
                 netty: 'io.netty:netty-codec-http2:4.1.0.CR1',
                 netty_epoll: 'io.netty:netty-transport-native-epoll:4.1.0.CR1' + epoll_suffix,
-                netty_tcnative: 'io.netty:netty-tcnative:1.1.33.Fork11:' + tcnative_suffix,
+                netty_tcnative: 'io.netty:netty-tcnative-boringssl-static:1.1.33.Fork13:' + osdetector.classifier,
 
                 // Test dependencies.
                 junit: 'junit:junit:4.11',
diff --git a/buildscripts/make_dependencies.bat b/buildscripts/make_dependencies.bat
@@ -3,7 +3,6 @@ REM 7za is in http://www.7-zip.org/a/7z1507-extra.7z
 
 REM Prerequisite:
 REM   7za.exe in current directory or PATH
-REM   Install http://slproweb.com/download/Win64OpenSSL_Light-1_0_2d.exe
 
 set PROTOBUF_VER=3.0.0-beta-2
 set CMAKE_NAME=cmake-3.3.2-win32-x86
diff --git a/buildscripts/make_dependencies.sh b/buildscripts/make_dependencies.sh
@@ -1,17 +1,12 @@
 #!/bin/bash
 #
-# Build protoc & openssl
+# Build protoc
 set -ev
 
 DOWNLOAD_DIR=/tmp/source
 INSTALL_DIR=/tmp/protobuf-${PROTOBUF_VERSION}
 mkdir -p $DOWNLOAD_DIR
 
-# We may have set this elsewhere in order to allow gRPC find our custom
-# built openssl to run ALPN, but it may be incompatible with wget which
-# uses the system openssl. We unset this variable for this script.
-export -n LD_LIBRARY_PATH
-
 # Make protoc
 # Can't check for presence of directory as cache auto-creates it.
 if [ -f ${INSTALL_DIR}/bin/protoc ]; then
@@ -28,20 +23,3 @@ else
   popd
 fi
 
-INSTALL_DIR=/tmp/openssl-${OPENSSL_VERSION}
-
-if [ -f ${INSTALL_DIR}/lib/libssl.so ]; then
-  echo "Not building openssl. Already built"
-elif [ "$(uname)" = Darwin ]; then
-  brew install openssl
-else
-  # The version without the patch letter (e.g., 1.0.2 provided 1.0.2d)
-  VERSION_BASE=${OPENSSL_VERSION%%[a-z]*}
-  wget -O - https://www.openssl.org/source/old/$VERSION_BASE/openssl-${OPENSSL_VERSION}.tar.gz \
-    | tar xz -C $DOWNLOAD_DIR
-  pushd $DOWNLOAD_DIR/openssl-${OPENSSL_VERSION}
-  ./Configure linux-x86_64 shared no-ssl2 no-comp --prefix=${INSTALL_DIR}
-  make -j$(nproc)
-  make install
-  popd
-fi
diff --git a/interop-testing/src/test/java/io/grpc/testing/integration/Http2NettyTest.java b/interop-testing/src/test/java/io/grpc/testing/integration/Http2NettyTest.java
@@ -36,6 +36,7 @@
 import io.grpc.netty.NettyChannelBuilder;
 import io.grpc.netty.NettyServerBuilder;
 import io.grpc.testing.TestUtils;
+import io.netty.handler.ssl.SslProvider;
 import io.netty.handler.ssl.SupportedCipherSuiteFilter;
 
 import org.junit.AfterClass;
@@ -61,6 +62,7 @@ public static void startServer() {
           .sslContext(GrpcSslContexts
               .forServer(TestUtils.loadCert("server1.pem"), TestUtils.loadCert("server1.key"))
               .ciphers(TestUtils.preferredTestCiphers(), SupportedCipherSuiteFilter.INSTANCE)
+              .sslProvider(SslProvider.OPENSSL)
               .build()));
     } catch (IOException ex) {
       throw new RuntimeException(ex);
@@ -80,6 +82,7 @@ protected ManagedChannel createChannel() {
           .sslContext(GrpcSslContexts.forClient()
               .trustManager(TestUtils.loadCert("ca.pem"))
               .ciphers(TestUtils.preferredTestCiphers(), SupportedCipherSuiteFilter.INSTANCE)
+              .sslProvider(SslProvider.OPENSSL)
               .build())
           .build();
     } catch (Exception ex) {
