From 4ed49c06ac96d9c4a6e16aa7f6d37cdf1735a51c Mon Sep 17 00:00:00 2001
From: tb <>
Date: Tue, 22 Jan 2019 01:18:24 +0000
Subject: Document SSL_get1_supported_ciphers(3) and SSL_get_client_ciphers(3).
 The text comes from OpenSSL, where it was still published under a free
 license.

from schwarze
---
 src/lib/libssl/man/SSL_get_ciphers.3 | 68 ++++++++++++++++++++++++++++++++----
 1 file changed, 61 insertions(+), 7 deletions(-)

(limited to 'src')

diff --git a/src/lib/libssl/man/SSL_get_ciphers.3 b/src/lib/libssl/man/SSL_get_ciphers.3
index cbbf62b35e..07361da461 100644
--- a/src/lib/libssl/man/SSL_get_ciphers.3
+++ b/src/lib/libssl/man/SSL_get_ciphers.3
@@ -1,6 +1,6 @@
-.\" $OpenBSD: SSL_get_ciphers.3,v 1.6 2018/03/27 17:35:50 schwarze Exp $
+.\" $OpenBSD: SSL_get_ciphers.3,v 1.7 2019/01/22 01:18:24 tb Exp $
 .\" full merge up to: OpenSSL c3e64028 Mar 30 11:50:14 2005 +0000
-.\" selective merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
+.\" selective merge up to: OpenSSL 83cf7abf May 29 13:07:08 2018 +0100
 .\"
 .\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>,
 .\" Nick Mathewson <nickm@torproject.org>, and Kazuki Yamaguchi <k@rhe.jp>.
@@ -51,12 +51,14 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: March 27 2018 $
+.Dd $Mdocdate: January 22 2019 $
 .Dt SSL_GET_CIPHERS 3
 .Os
 .Sh NAME
 .Nm SSL_get_ciphers ,
 .Nm SSL_CTX_get_ciphers ,
+.Nm SSL_get1_supported_ciphers ,
+.Nm SSL_get_client_ciphers ,
 .Nm SSL_get_cipher_list
 .Nd get list of available SSL_CIPHERs
 .Sh SYNOPSIS
@@ -65,6 +67,10 @@
 .Fn SSL_get_ciphers "const SSL *ssl"
 .Ft STACK_OF(SSL_CIPHER) *
 .Fn SSL_CTX_get_ciphers "const SSL_CTX *ctx"
+.Ft STACK_OF(SSL_CIPHER) *
+.Fn SSL_get1_supported_ciphers "SSL *ssl"
+.Ft STACK_OF(SSL_CIPHER) *
+.Fn SSL_get_client_ciphers "const SSL *ssl"
 .Ft const char *
 .Fn SSL_get_cipher_list "const SSL *ssl" "int priority"
 .Sh DESCRIPTION
@@ -88,9 +94,49 @@ returns the stack of available
 for
 .Fa ctx .
 .Pp
-.Fn SSL_get_ciphers
+.Fn SSL_get1_supported_ciphers
+returns the stack of enabled
+.Vt SSL_CIPHER Ns s
+for
+.Fa ssl
+as it would be sent in a ClientHello, sorted by preference.
+The list depends on settings like the cipher list, the supported
+protocol versions, the security level, and the enabled signature
+algorithms.
+The list of ciphers that would be sent in a ClientHello can differ
+from the list of ciphers that would be acceptable when acting as a
+server.
+For example,
+additional ciphers may be usable by a server if there is a gap in the
+list of supported protocols, and some ciphers may not be usable by a
+server if there is not a suitable certificate configured.
+If
+.Fa ssl
+is
+.Dv NULL
+or no ciphers are available,
+.Dv NULL
+is returned.
+.Pp
+.Fn SSL_get_client_ciphers
+returns the stack of available
+.Vt SSL_CIPHER Ns s
+matching the list received from the client on
+.Fa ssl .
+If
+.Fa ssl
+is
+.Dv NULL ,
+no ciphers are available, or
+.Fa ssl
+is not operating in server mode,
+.Dv NULL
+is returned.
+.Pp
+.Fn SSL_get_ciphers ,
+.Fn SSL_CTX_get_ciphers ,
 and
-.Fn SSL_CTX_get_ciphers
+.Fn SSL_get_client_ciphers
 return pointers to internal cipher stacks, which will be freed
 later on when the
 .Vt SSL
@@ -100,9 +146,11 @@ object is freed.
 Therefore, the calling code must not free the return value itself.
 .Pp
 The details of the ciphers obtained by
-.Fn SSL_get_ciphers
+.Fn SSL_get_ciphers ,
+.Fn SSL_CTX_get_ciphers ,
+.Fn SSL_get1_supported_ciphers ,
 and
-.Fn SSL_CTX_get_ciphers
+.Fn SSL_get_client_ciphers
 can be obtained using the
 .Xr SSL_CIPHER_get_name 3
 family of functions.
@@ -146,3 +194,9 @@ Both functions have been available since
 .Fn SSL_CTX_get_ciphers
 first appeared in OpenSSL 1.1.0 and has been available since
 .Ox 6.3 .
+.Pp
+.Fn SSL_get1_supported_ciphers
+and
+.Fn SSL_get_client_ciphers
+first appeared in OpenSSL 1.1.0 and has been available since
+.Ox 6.5 .
-- 
cgit v1.2.3-55-g6feb