Merge the documentation of SSL_CIPHER_get_id(3) and

the new RETURN VALUES section from OpenSSL, tweaked by me.
While here, correct the description of SSL_CIPHER_description(3).

1 files changed, 71 insertions, 42 deletions

diff --git a/lib/libssl/man/SSL_CIPHER_get_name.3 b/lib/libssl/man/SSL_CIPHER_get_name.3
index b85fdffe8d9..9a1446efbae 100644
--- a/lib/libssl/man/SSL_CIPHER_get_name.3
+++ b/lib/libssl/man/SSL_CIPHER_get_name.3
@@ -1,8 +1,10 @@
-.\"	$OpenBSD: SSL_CIPHER_get_name.3,v 1.3 2017/07/05 11:43:09 schwarze Exp $
-.\"	OpenSSL 45f55f6a Nov 30 15:35:22 2014 +0100
+.\" $OpenBSD: SSL_CIPHER_get_name.3,v 1.4 2018/02/27 14:13:52 schwarze Exp $
+.\" full merge up to: OpenSSL 45f55f6a Nov 30 15:35:22 2014 +0100
+.\" selective merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800
 .\"
-.\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>.
-.\" Copyright (c) 2000, 2001, 2005, 2009, 2013, 2014 The OpenSSL Project.
+.\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>
+.\" and Paul Yang <yang.yang@baishancloud.com>.
+.\" Copyright (c) 2000, 2005, 2009, 2013, 2014, 2017 The OpenSSL Project.
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -49,13 +51,14 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: July 5 2017 $
+.Dd $Mdocdate: February 27 2018 $
 .Dt SSL_CIPHER_GET_NAME 3
 .Os
 .Sh NAME
 .Nm SSL_CIPHER_get_name ,
 .Nm SSL_CIPHER_get_bits ,
 .Nm SSL_CIPHER_get_version ,
+.Nm SSL_CIPHER_get_id ,
 .Nm SSL_CIPHER_description
 .Nd get SSL_CIPHER properties
 .Sh SYNOPSIS
@@ -66,18 +69,14 @@
 .Fn SSL_CIPHER_get_bits "const SSL_CIPHER *cipher" "int *alg_bits"
 .Ft char *
 .Fn SSL_CIPHER_get_version "const SSL_CIPHER *cipher"
+.Ft unsigned long
+.Fn SSL_CIPHER_get_id "const SSL_CIPHER *cipher"
 .Ft char *
 .Fn SSL_CIPHER_description "const SSL_CIPHER *cipher" "char *buf" "int size"
 .Sh DESCRIPTION
 .Fn SSL_CIPHER_get_name
 returns a pointer to the name of
 .Fa cipher .
-If the
-.Fa cipher
-is
-.Dv NULL ,
-it returns
-.Qq (NONE) .
 .Pp
 .Fn SSL_CIPHER_get_bits
 returns the number of secret bits used for
@@ -86,13 +85,7 @@ If
 .Fa alg_bits
 is not
 .Dv NULL ,
-it contains the number of bits processed by the
-chosen algorithm.
-If
-.Fa cipher
-is
-.Dv NULL ,
-0 is returned.
+the number of bits processed by the chosen algorithm is stored into it.
 .Pp
 .Fn SSL_CIPHER_get_version
 returns a string which indicates the SSL/TLS protocol version that first
@@ -104,19 +97,32 @@ In some cases it should possibly return
 but the function does not; use
 .Fn SSL_CIPHER_description
 instead.
-If
-.Fa cipher
-is
-.Dv NULL ,
-.Qq (NONE)
-is returned.
+.Pp
+.Fn SSL_CIPHER_get_id
+returns the ID of the given
+.Fa cipher ,
+which must not be
+.Dv NULL .
+The ID here is an OpenSSL-specific concept, which stores a prefix
+of 0x0300 in the higher two bytes and the IANA-specified chipher
+suite ID in the lower two bytes.
+For instance, TLS_RSA_WITH_NULL_MD5 has IANA ID "0x00, 0x01", so
+.Fn SSL_CIPHER_get_id
+returns 0x03000001.
 .Pp
 .Fn SSL_CIPHER_description
-returns a textual description of the cipher used into the buffer
-.Fa buf
-of length
-.Fa len
-provided.
+copies a textual description of
+.Fa cipher
+into the buffer
+.Fa buf ,
+which must be at least
+.Fa size
+bytes long.
+The
+.Fa cipher
+argument must not be a
+.Dv NULL
+pointer.
 If
 .Fa buf
 is
@@ -128,13 +134,16 @@ that buffer should be freed using the
 function.
 If
 .Fa len
-is too small, or if
-.Fa buf
-is
-.Dv NULL
-and the allocation fails, a pointer to the string
+is too small to hold the description, a pointer to the static string
 .Qq Buffer too small
 is returned.
+If memory allocation fails, which can happen even if a
+.Fa buf
+of sufficient size is provided, a pointer to the static string
+.Qq OPENSSL_malloc Error
+is returned and the content of
+.Fa buf
+remains unchanged.
 .Pp
 The string returned by
 .Fn SSL_CIPHER_description
@@ -196,6 +205,34 @@ Message digest:
 .Sy STREEBOG256 ,
 .Sy STREEBOG512 .
 .El
+.Sh RETURN VALUES
+.Fn SSL_CIPHER_get_name
+returns an internal pointer to a NUL-terminated string.
+.Fn SSL_CIPHER_get_version
+returns a pointer to a static NUL-terminated string.
+If
+.Fa cipher
+is a
+.Dv NULL
+pointer, both functions return a pointer to the static string
+.Qq Pq NONE .
+.Pp
+.Fn SSL_CIPHER_get_bits
+returns a positive integer representing the number of secret bits
+or 0 if
+.Fa cipher
+is a
+.Dv NULL
+pointer.
+.Pp
+.Fn SSL_CIPHER_get_id
+returns a 32-bit unsigned integer.
+.Pp
+.Fn SSL_CIPHER_description
+returns
+.Fa buf
+or a newly allocated string on success or a pointer to a static
+string on error.
 .Sh EXAMPLES
 An example for the output of
 .Fn SSL_CIPHER_description :
@@ -214,14 +251,6 @@ A complete list can be retrieved by invoking the following command:
 .Sh BUGS
 If
 .Fn SSL_CIPHER_description
-is called with
-.Fa cipher
-being
-.Dv NULL ,
-the library crashes.
-.Pp
-If
-.Fn SSL_CIPHER_description
 cannot handle a built-in cipher,
 the according description of the cipher property is
 .Qq unknown .