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

1 files changed, 61 insertions, 7 deletions

diff --git a/lib/libssl/man/SSL_get_ciphers.3 b/lib/libssl/man/SSL_get_ciphers.3
index cbbf62b35e7..07361da4610 100644
--- a/lib/libssl/man/SSL_get_ciphers.3
+++ b/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 .