ssl: Polish doc

lib/ssl/doc/guides/ssl_distribution.md

@@ -169,18 +169,19 @@ itself. Other raw socket options such as `packet_size` may interfere severely,
 so beware\!
 
 For TLS to work, at least a public key and a certificate must be specified for
-the server side. In the following example, the PEM file
-`"/home/me/ssl/erlserver.pem"` contains both the server certificate and its
-private key.
+the server side and the client needs to specify CAs that it trusts (client certification
+is optional and requires more configuration).
+
+In the following example (to keep it simple), the PEM file `"/home/me/ssl/erlserver.pem"`
+contains both the server certificate and its private key .
 
 Create a file named for example `"/home/me/ssl/[email protected]"`:
 
 ```erlang
 [{server,
-  [{certfile, "/home/me/ssl/erlserver.pem"},
-   {secure_renegotiate, true}]},
+  [{certfile, "/home/me/ssl/erlserver.pem"}]},
  {client,
-  [{secure_renegotiate, true}]}].
+  [{cacertfile, "/home/me/ssl/client_trusted.pem"}]}].
 ```
 
 And then start the node like this (line breaks in the command are for
@@ -213,8 +214,33 @@ present any certificate.
 A node started in this way is fully functional, using TLS as the distribution
 protocol.
 
+
+## Using TLS distribution over IPv6
+
+It is possible to use TLS distribution over IPv6 instead of IPv4. To do this,
+pass the option `-proto_dist inet6_tls` instead of `-proto_dist inet_tls` when
+starting Erlang, either on the command line or in the `ERL_FLAGS` environment
+variable.
+
+An example command line with this option would look like this:
+
+```text
+$ erl -boot /home/me/ssl/start_ssl -proto_dist inet6_tls
+  -ssl_dist_optfile "/home/me/ssl/[email protected]"
+  -sname ssl_test
+```
+
+A node started in this way will only be able to communicate with other nodes
+using TLS distribution over IPv6.
+
+
 ## Specifying TLS Options (Legacy)
 
+> #### Note {: .info }
+> The following section describes TLS Option handling prior to OTP 20.2
+> and can only handle a small subset of the actual available options.
+> It is here only for the sake of backwards compatibility .
+
 As in the previous section the PEM file `"/home/me/ssl/erlserver.pem"` contains
 both the server certificate and its private key.
 
@@ -270,7 +296,7 @@ Eshell V5.0  (abort with ^G)
 (ssl_test@myhost)1>
 ```
 
-## Setting up Environment to Always Use TLS (Legacy)
+### Setting up Environment to Always Use TLS
 
 A convenient way to specify arguments to Erlang is to use environment variable
 `ERL_FLAGS`. All the flags needed to use the TLS distribution can be specified
@@ -304,20 +330,3 @@ Eshell V5.0  (abort with ^G)
 The `init:get_arguments()` call verifies that the correct arguments are supplied
 to the emulator.
 
-## Using TLS distribution over IPv6
-
-It is possible to use TLS distribution over IPv6 instead of IPv4. To do this,
-pass the option `-proto_dist inet6_tls` instead of `-proto_dist inet_tls` when
-starting Erlang, either on the command line or in the `ERL_FLAGS` environment
-variable.
-
-An example command line with this option would look like this:
-
-```text
-$ erl -boot /home/me/ssl/start_ssl -proto_dist inet6_tls
-  -ssl_dist_optfile "/home/me/ssl/[email protected]"
-  -sname ssl_test
-```
-
-A node started in this way will only be able to communicate with other nodes
-using TLS distribution over IPv6.

lib/ssl/doc/guides/ssl_protocol.md

@@ -108,7 +108,7 @@ server, if it requests a certificate, does however not accept any path
 validation errors. It is configurable if the server is to accept or reject an
 "empty" certificate as response to a certificate request.
 
-## TLS Sessions - PRE TLS-1.3
+## TLS Sessions - Prior to TLS-1.3
 
 From the TLS RFC: "A TLS session is an association between a client and a
 server. Sessions are created by the handshake protocol. Sessions define a set of
@@ -126,11 +126,11 @@ configured.
 
 By default the TLS/DTLS clients try to reuse an available session and by default
 the TLS/DTLS servers agree to reuse sessions when clients ask for it. See also
-[Session Reuse Pre TLS-1.3](using_ssl.md#session-reuse-pre-tls-1-3)
+[Session Reuse Prior to TLS-1.3](using_ssl.md#session-reuse-pre-tls-1-3)
 
 ## TLS-1.3 session tickets
 
 In TLS 1.3 the session reuse is replaced by a new session tickets mechanism
-based on the pre shared key concept. This mechanism also obsoletes the session
+based on the prior to shared key concept. This mechanism also obsoletes the session
 tickets from RFC5077, not implemented by this application. See also
 [Session Tickets and Session Resumption in TLS-1.3](using_ssl.md#session-tickets-and-session-resumption-in-tls-1-3)

lib/ssl/doc/guides/standards_compliance.md

@@ -24,7 +24,7 @@ limitations under the License.
 This section describes the current state of standards compliance of the ssl
 application.
 
-## Common (pre TLS 1.3)
+## Common (prior to TLS 1.3)
 
 - For security reasons RSA key exchange cipher suites are no longer supported by
   default, but can be configured. (OTP 21)