Add SSL_get_pending_cipher()

[openssl.git] / doc / man3 / SSL_get_current_cipher.pod

diff --git a/doc/man3/SSL_get_current_cipher.pod b/doc/man3/SSL_get_current_cipher.pod
index cb7e9994a7efc1a315dbde109a464f6b7bc4535f..e5b249fd1e2bda6ef8af57359bbaf9acca37c9d7 100644 (file)
--- a/doc/man3/SSL_get_current_cipher.pod
+++ b/doc/man3/SSL_get_current_cipher.pod
@@ -3,13 +3,15 @@
 =head1 NAME
 
 SSL_get_current_cipher, SSL_get_cipher_name, SSL_get_cipher,
-SSL_get_cipher_bits, SSL_get_cipher_version - get SSL_CIPHER of a connection
+SSL_get_cipher_bits, SSL_get_cipher_version,
+SSL_get_pending_cipher - get SSL_CIPHER of a connection
 
 =head1 SYNOPSIS
 
  #include <openssl/ssl.h>
 
  SSL_CIPHER *SSL_get_current_cipher(const SSL *ssl);
+ SSL_CIPHER *SSL_get_pending_cipher(const SSL *ssl);
 
  const char *SSL_get_cipher_name(const SSL *s);
  const char *SSL_get_cipher(const SSL *s);
@@ -30,14 +32,28 @@ SSL_get_cipher_bits() is a
 macro to obtain the number of secret/algorithm bits used and
 SSL_get_cipher_version() returns the protocol name.
 
+SSL_get_pending_cipher() returns a pointer to an SSL_CIPHER object containing
+the description of the cipher (if any) that has been negotiated for future use
+on the connection established with the B<ssl> object, but is not yet in use.
+This may be the case during handshake processing, when control flow can be
+returned to the application via any of several callback methods.  The internal
+sequencing of handshake processing and callback invocation is not guaranteed
+to be stable from release to release, and at present only the callback set
+by SSL_CTX_set_alpn_select_cb() is guaranteed to have a non-NULL return value.
+Other callbacks may be added to this list over time.
+
 =head1 RETURN VALUES
 
 SSL_get_current_cipher() returns the cipher actually used, or NULL if
 no session has been established.
 
+SSL_get_pending_cipher() returns the cipher to be used at the next change
+of cipher suite, or NULL if no such cipher is known.
+
 =head1 NOTES
 
-These are implemented as macros.
+SSL_get_cipher, SSL_get_cipher_bits, SSL_get_cipher_version, and
+SSL_get_cipher_name are implemented as macros.
 
 =head1 SEE ALSO