List and describe the recommended methods first and relegate the

deprecated methods to a separate table.  Simplify and shorten the
surrounding verbiage.
Joint work with tb@.

1 files changed, 26 insertions, 27 deletions

diff --git a/lib/libssl/man/SSL_CTX_new.3 b/lib/libssl/man/SSL_CTX_new.3
index 21f4cf08b2c..cb7ff67d60a 100644
--- a/lib/libssl/man/SSL_CTX_new.3
+++ b/lib/libssl/man/SSL_CTX_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: SSL_CTX_new.3,v 1.13 2020/10/11 16:14:38 schwarze Exp $
+.\" $OpenBSD: SSL_CTX_new.3,v 1.14 2020/10/12 09:18:33 schwarze Exp $
 .\" full merge up to: OpenSSL 21cd6e00 Oct 21 14:40:15 2015 +0100
 .\" selective merge up to: OpenSSL 8f75443f May 24 14:04:26 2019 +0200
 .\"
@@ -50,7 +50,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: October 11 2020 $
+.Dd $Mdocdate: October 12 2020 $
 .Dt SSL_CTX_NEW 3
 .Os
 .Sh NAME
@@ -156,31 +156,38 @@ The
 .Vt SSL_CTX
 object uses
 .Fa method
-as its connection method.
-The methods exist in a generic type (for client and server use),
-a server only type, and a client only type.
-.Fa method
-can be of the following types:
+as its connection method, which can be:
 .Bl -tag -width Ds
-.It Xo
-.Fn TLS_method ,
-.Fn TLS_server_method ,
-.Fn TLS_client_method
-.Xc
-These are the general-purpose version-flexible SSL/TLS methods.
-The actual protocol version used will be negotiated to the highest
+.It Fn TLS_method
+The general-purpose version-flexible TLS method.
+The protocol version used will be negotiated to the highest
 version mutually supported by the client and the server.
 The supported protocols are TLSv1, TLSv1.1, TLSv1.2, and TLSv1.3.
-Applications should use these methods and avoid the version-specific
-methods described below.
+.It Fn DTLS_method
+The version-flexible DTLS method.
+The currently supported protocol is DTLS 1.0.
+.El
+.Pp
+The following
+.Fa method
+arguments are deprecated:
+.Bl -tag -width Ds
 .It Xo
+.Fn TLS_server_method ,
+.Fn TLS_client_method ,
 .Fn SSLv23_method ,
 .Fn SSLv23_server_method ,
 .Fn SSLv23_client_method
 .Xc
-These are deprecated aliases for
+Deprecated aliases for
 .Fn TLS_method .
 .It Xo
+.Fn DTLS_server_method ,
+.Fn DTLS_client_method
+.Xc
+Deprecated aliases for
+.Fn DTLS_method .
+.It Xo
 .Fn TLSv1_method ,
 .Fn TLSv1_server_method ,
 .Fn TLSv1_client_method
@@ -202,13 +209,6 @@ understand the TLSv1.1 protocol.
 A TLS/SSL connection established with these methods will only
 understand the TLSv1.2 protocol.
 .It Xo
-.Fn DTLS_method ,
-.Fn DTLS_server_method ,
-.Fn DTLS_client_method
-.Xc
-These are the version-flexible DTLS methods.
-The currently supported protocol is DTLS 1.0.
-.It Xo
 .Fn DTLSv1_method ,
 .Fn DTLSv1_server_method ,
 .Fn DTLSv1_client_method
@@ -216,12 +216,11 @@ The currently supported protocol is DTLS 1.0.
 These are the version-specific methods for DTLSv1.
 .El
 .Pp
-The methods containing the substrings
+In LibreSSL, the methods containing the substrings
 .Dq _server
 or
 .Dq _client
-in their names are deprecated.
-In LibreSSL, they return the same objects
+in their names return the same objects
 as the methods without these substrings.
 .Pp
 The list of protocols available can also be limited using the