Document SSL_get1_supported_ciphers

Reviewed-by: Viktor Dukhovni <viktor@openssl.org>
MR: #1595

diff --git a/doc/ssl/SSL_get_ciphers.pod b/doc/ssl/SSL_get_ciphers.pod
index 65781dae0bcdab8521156f9dbb360c59daa269ef..5e4bc08dcd6320314d2a23252810b92f46c8ba10 100644 (file)
--- a/doc/ssl/SSL_get_ciphers.pod
+++ b/doc/ssl/SSL_get_ciphers.pod
@@ -9,6 +9,7 @@ SSL_get_ciphers, SSL_get_cipher_list - get list of available SSL_CIPHERs
  #include <openssl/ssl.h>
 
  STACK_OF(SSL_CIPHER) *SSL_get_ciphers(const SSL *ssl);
+ STACK_OF(SSL_CIPHER) *SSL_get1_supported_ciphers(SSL *s);
  STACK_OF(SSL_CIPHER) *SSL_get_client_ciphers(const SSL *ssl);
  const char *SSL_get_cipher_list(const SSL *ssl, int priority);
 
@@ -18,8 +19,21 @@ SSL_get_ciphers() returns the stack of available SSL_CIPHERs for B<ssl>,
 sorted by preference. If B<ssl> is NULL or no ciphers are available, NULL
 is returned.
 
-SSL_get_client_ciphers() returns the stack of available SSL_CIPHERS matching the
-list sent by the client for B<ssl>. If B<ssl> is NULL, no ciphers are
+SSL_get1_supported_ciphers() returns the stack of enabled SSL_CIPHERs for
+B<ssl>, sorted by preference.
+The list depends on settings like the cipher list, the supported protocol
+versions, the security level, and the enabled signature algorithms.
+SRP and PSK ciphers are only enabled if the appropriate callbacks or settings
+have been applied.
+This is the list that will be sent by the client to the server.
+The list supported by the server might include more ciphers in case there is a
+hole in the list of supported protocols.
+The server will also not use ciphers from this list depending on the
+configured certificates and DH parameters.
+If B<ssl> is NULL or no ciphers are available, NULL is returned.
+
+SSL_get_client_ciphers() returns the stack of available SSL_CIPHERs matching the
+list received from the client on B<ssl>. If B<ssl> is NULL, no ciphers are
 available, or B<ssl> is not operating in server mode, NULL is returned.
 
 SSL_get_cipher_list() returns a pointer to the name of the SSL_CIPHER
@@ -29,7 +43,8 @@ is returned.
 
 =head1 NOTES
 
-The details of the ciphers obtained by SSL_get_ciphers() can be obtained using
+The details of the ciphers obtained by SSL_get_ciphers(),
+SSL_get1_supported_ciphers() and SSL_get_client_ciphers() can be obtained using
 the L<SSL_CIPHER_get_name(3)> family of functions.
 
 Call SSL_get_cipher_list() with B<priority> starting from 0 to obtain the
@@ -40,6 +55,9 @@ to an internal cipher stack, which will be freed later on when the SSL
 or SSL_SESSION object is freed.  Therefore, the calling code B<MUST
 NOT> free the return value itself.
 
+The stack returned by SSL_get1_supported_ciphers() should be freed using
+sk_SSL_CIPHER_free().
+
 =head1 RETURN VALUES
 
 See DESCRIPTION