docs: document version of crustls dependency

This also pins a specific release in the Travis test so future
API-breaking changins in crustls won't break curl builds.

Add RUSTLS documentation to release tarball.

Enable running tests for rustls, minus FTP tests (require
connect_blocking, which rustls doesn't implement) and 313 (requires CRL
handling).

Closes #6763

.travis.yml

@@ -125,7 +125,7 @@ jobs:
         - libbrotli-dev
         - libzstd-dev
   - env:
-    - T=debug RUSTLS="yes" C="--with-rustls=$HOME/crust --without-ssl" NOTESTS=1
+    - T=debug-rustls RUSTLS_VERSION="v0.4.0" C="--with-rustls=$HOME/crust --without-ssl"
     addons:
       apt:
         <<: *common_apt

docs/Makefile.am

@@ -80,6 +80,7 @@ EXTRA_DIST =                                    \
  PARALLEL-TRANSFERS.md                          \
  README.md                                      \
  RELEASE-PROCEDURE.md                           \
+ RUSTLS.md                                      \
  ROADMAP.md                                     \
  SECURITY-PROCESS.md                            \
  SSL-PROBLEMS.md                                \

docs/RUSTLS.md

@@ -0,0 +1,26 @@
+# Rustls
+
+[Rustls is a TLS backend written in Rust.](https://docs.rs/rustls/). Curl can
+be built to use it as an alternative to OpenSSL or other TLS backends. We use
+the [crustls C bindings](https://github.com/abetterinternet/crustls/). This
+version of curl depends on version v0.4.0 of crustls.
+
+# Building with rustls
+
+First, [install Rust](https://rustup.rs/).
+
+Next, check out, build, and install the appropriate version of crustls:
+
+    % cargo install cbindgen
+    % git clone https://github.com/abetterinternet/crustls/ -b v0.4.0
+    % cd crustls
+    % make
+    % make DESTDIR=${HOME}/crustls-built/ install
+
+Now configure and build curl with rustls:
+
+    % git clone https://github.com/curl/curl
+    % cd curl
+    % ./buildconf
+    % ./configure --without-ssl --with-rustls=${HOME}/crustls-built
+    % make

scripts/travis/before_script.sh

@@ -126,9 +126,9 @@ if [ "$TRAVIS_OS_NAME" = linux -a "$QUICHE" ]; then
   ln -vnf $(find target/release -name libcrypto.a -o -name libssl.a) deps/boringssl/src/lib/
 fi
 
-if [ "$TRAVIS_OS_NAME" = linux -a "$RUSTLS" ]; then
+if [ "$TRAVIS_OS_NAME" = linux -a "$RUSTLS_VERSION" ]; then
   cd $HOME
-  git clone --depth=1 --recursive https://github.com/abetterinternet/crustls.git
+  git clone --depth=1 --recursive https://github.com/abetterinternet/crustls.git -b "$RUSTLS_VERSION"
   curl https://sh.rustup.rs -sSf | sh -s -- -y
   source $HOME/.cargo/env
   cargo install cbindgen

scripts/travis/script.sh

@@ -70,6 +70,12 @@ if [ "$T" = "debug-mesalink" ]; then
   make "TFLAGS=-n !313 !410 !3001" test-nonflaky
 fi
 
+if [ "$T" = "debug-rustls" ]; then
+  ./configure --enable-debug --enable-werror $C
+  make
+  make "TFLAGS=HTTPS !313" test-nonflaky
+fi
+
 if [ "$T" = "novalgrind" ]; then
   ./configure --enable-werror $C
   make