Document SSL_get1_supported_ciphers

[openssl.git] / doc / ssl / SSL_get_ciphers.pod

diff --git a/doc/ssl/SSL_get_ciphers.pod b/doc/ssl/SSL_get_ciphers.pod
index f2a81037c04ae46f57347384ddccb6732ddf5b66..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,19 +43,28 @@ is returned.
 
 =head1 NOTES
 
-The details of the ciphers obtained by SSL_get_ciphers() can be obtained using
-the L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)> family of functions.
+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
 sorted list of available ciphers, until NULL is returned.
 
+Note: SSL_get_ciphers() and SSL_get_client_ciphers() return a pointer
+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
 
 =head1 SEE ALSO
 
-L<ssl(3)|ssl(3)>, L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>,
-L<SSL_CIPHER_get_name(3)|SSL_CIPHER_get_name(3)>
+L<ssl(3)>, L<SSL_CTX_set_cipher_list(3)>,
+L<SSL_CIPHER_get_name(3)>
 
 =cut