Update SSL_get_shared_ciphers() documentation for ssl_lib.c r1.240

From schwarze, who explains:

 * Even though i wrote the original version of our documentation
   for this function, i now think the design of this function is so
   atrocious that it is better to call out the main limitations
   up front (server side only and silent truncation) rather than
   first giving the impression that it achieves something it
   actually doesn't and then later try to row back in a piece-meal
   manner.

 * Using a .Bl list for failure conditions in the RETURN VALUES
   section is no doubt unusual, but the conditions are so numerous
   and some of them are so surprising that i think it makes sense
   in this case.  If a function is badly designed and has surprising
   properties, precision and clarity in the description are even
   more important than usual, and conciseness is better sacrificed.

 * Adding .Xr SSL_get_ciphers 3 seems helpful.

ok beck inoguchi jsing tb

1 files changed, 47 insertions, 17 deletions

diff --git a/lib/libssl/man/SSL_get_shared_ciphers.3 b/lib/libssl/man/SSL_get_shared_ciphers.3
index 6b75439f868..207e8c42eb2 100644
--- a/lib/libssl/man/SSL_get_shared_ciphers.3
+++ b/lib/libssl/man/SSL_get_shared_ciphers.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: SSL_get_shared_ciphers.3,v 1.4 2019/06/12 09:36:30 schwarze Exp $
+.\" $OpenBSD: SSL_get_shared_ciphers.3,v 1.5 2021/01/09 10:50:02 tb Exp $
 .\"
 .\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: June 12 2019 $
+.Dd $Mdocdate: January 9 2021 $
 .Dt SSL_GET_SHARED_CIPHERS 3
 .Os
 .Sh NAME
@@ -29,12 +29,14 @@
 .Fa "int len"
 .Fc
 .Sh DESCRIPTION
-.Fn SSL_get_shared_ciphers
-puts the names of the ciphers that are supported by both the client
-and the server of
+If
 .Fa ssl
-into the buffer
-.Fa buf .
+contains a session in server mode,
+.Fn SSL_get_shared_ciphers
+puts as many names of ciphers that are supported by both the client
+and the server into the buffer
+.Fa buf
+as the buffer is long enough to contain.
 Names are separated by colons.
 At most
 .Fa len
@@ -42,19 +44,47 @@ bytes are written to
 .Fa buf
 including the terminating NUL character.
 .Sh RETURN VALUES
-If
-.Fa ssl
-contains no session, if the session contains no shared ciphers,
-or if
-.Fa len
-is less than 2,
 .Fn SSL_get_shared_ciphers
 returns
-.Dv NULL .
-Otherwise, it returns
-.Fa buf .
+.Fa buf
+on success or
+.Dv NULL
+on failure.
+The following situations cause failure:
+.Bl -bullet
+.It
+.Xr SSL_is_server 3
+is false, i.e.,
+.Ar ssl
+is not set to server mode.
+.It
+.Xr SSL_get_ciphers 3
+is
+.Dv NULL
+or empty, i.e., no ciphers are available for use by the server.
+.It
+.Xr SSL_get_session 3
+is
+.Dv NULL ,
+i.e.,
+.Ar ssl
+contains no session.
+.It
+.Xr SSL_get_client_ciphers 3
+is
+.Dv NULL
+or empty, i.e.,
+.Ar ssl
+contains no information about ciphers supported by the client,
+or the client does not support any ciphers.
+.It
+The
+.Fa len
+argument is less than 2.
+.El
 .Sh SEE ALSO
-.Xr ssl 3
+.Xr ssl 3 ,
+.Xr SSL_get_ciphers 3
 .Sh HISTORY
 .Fn SSL_get_shared_ciphers
 first appeared in SSLeay 0.4.5b and has been available since