From 1032db1f3ee72be2f4acc27f9092ae4934881008 Mon Sep 17 00:00:00 2001
From: Sam Roberts <vieuxtech@gmail.com>
Date: Thu, 15 Nov 2018 15:51:55 -0800
Subject: [PATCH] doc: describe secureProtocol and CLI interaction

Cross-reference the secureProtocol docs and the CLI docs for --tls-v1.0
and --tls-v1.1 and describe relationship. Make clear that --tls-v1.0
enables TLSv1.0 and TLSv1.1.
---
 doc/api/cli.md      |  9 +++++----
 doc/api/tls.md      | 13 +++++++++----
 doc/node.1          |  8 ++++----
 src/node_options.cc |  4 ++--
 4 files changed, 20 insertions(+), 14 deletions(-)

diff --git a/doc/api/cli.md b/doc/api/cli.md
index 209f8bf05a5235..2a3debd1b9661e 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -347,16 +347,16 @@ with crypto support (default).
 added: REPLACEME
 -->
 
-Enable TLSv1.0. This should only be used for compatibility with old TLS
-clients or servers.
+Enable TLSv1.0 and greater in default [secureProtocol][]. Use for compatibility
+with old TLS clients or servers.
 
 ### `--tls-v1.1`
 <!-- YAML
 added: REPLACEME
 -->
 
-Enable TLSv1.1. This should only be used for compatibility with old TLS
-clients or servers.
+Enable TLSv1.1 and greater in default [secureProtocol][]. Use for compatibility
+with old TLS clients or servers.
 
 ### `--trace-deprecation`
 <!-- YAML
@@ -787,3 +787,4 @@ greater than `4` (its current default value). For more information, see the
 [experimental ECMAScript Module]: esm.html#esm_loader_hooks
 [libuv threadpool documentation]: http://docs.libuv.org/en/latest/threadpool.html
 [remote code execution]: https://www.owasp.org/index.php/Code_Injection
+[secureProtocol]: tls.html#tls_tls_createsecurecontext_options
diff --git a/doc/api/tls.md b/doc/api/tls.md
index 82dfbe20196832..5655f21bd6f0cc 100644
--- a/doc/api/tls.md
+++ b/doc/api/tls.md
@@ -1118,10 +1118,15 @@ changes:
     which is not usually necessary. This should be used carefully if at all!
     Value is a numeric bitmask of the `SSL_OP_*` options from
     [OpenSSL Options][].
-  * `secureProtocol` {string} SSL method to use. The possible values are listed
-    as [SSL_METHODS][], use the function names as strings. For example,
-    `'TLSv1_2_method'` to force TLS version 1.2.
-    **Default:** `'TLSv1_2_method'`.
+  * `secureProtocol` {string} The TLS protocol version to use. The possible
+    values are listed as [SSL_METHODS][], use the function names as strings. For
+    example, use `'TLSv1_1_method'` to force TLS version 1.1, or `'TLS_method'`
+    to allow any TLS protocol version. It is not recommended to use TLS versions
+    less than 1.2, but it may be required for interoperability.  **Default:**
+    `'TLSv1_2_method'`, unless changed using CLI options. Using the `--tlsv1.0`
+    CLI option is like `'TLS_method'` except protocols earlier than TLSv1.0 are
+    not allowed, and using the `--tlsv1.1` CLI option is like `'TLS_method'`
+    except that protocols earlier than TLSv1.1 are not allowed.
   * `sessionIdContext` {string} Opaque identifier used by servers to ensure
     session state is not shared between applications. Unused by clients.
 
diff --git a/doc/node.1 b/doc/node.1
index 52e307a6d6c163..d3c66d08cf3448 100644
--- a/doc/node.1
+++ b/doc/node.1
@@ -184,12 +184,12 @@ Specify an alternative default TLS cipher list.
 Requires Node.js to be built with crypto support. (Default)
 .
 .It Fl -tls-v1.0
-Enable TLSv1.0. This should only be used for compatibility with old TLS
-clients or servers.
+Enable TLSv1.0 and greater in default secureProtocol. Use for compatibility
+with old TLS clients or servers.
 .
 .It Fl -tls-v1.1
-Enable TLSv1.1. This should only be used for compatibility with old TLS
-clients or servers.
+Enable TLSv1.1 and greater in default secureProtocol. Use for compatibility
+with old TLS clients or servers.
 .
 .It Fl -trace-deprecation
 Print stack traces for deprecations.
diff --git a/src/node_options.cc b/src/node_options.cc
index 5dc6779bc41a0c..5f0d0e5cf7106b 100644
--- a/src/node_options.cc
+++ b/src/node_options.cc
@@ -191,11 +191,11 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
 
 #if HAVE_OPENSSL
   AddOption("--tls-v1.0",
-            "enable TLSv1.0",
+            "enable TLSv1.0 and greater by default",
             &EnvironmentOptions::tls_v1_0,
             kAllowedInEnvironment);
   AddOption("--tls-v1.1",
-            "enable TLSv1.1",
+            "enable TLSv1.1 and greater by default",
             &EnvironmentOptions::tls_v1_1,
             kAllowedInEnvironment);
 #endif