NAME

SSL_get_ciphers, SSL_CTX_get_ciphers, SSL_get1_supported_ciphers, SSL_get_client_ciphers, SSL_get_cipher_list — get lists of available SSL_CIPHERs

SYNOPSIS

#include <openssl/ssl.h> STACK_OF(SSL_CIPHER) *
SSL_get_ciphers(const SSL *ssl); STACK_OF(SSL_CIPHER) *
SSL_CTX_get_ciphers(const SSL_CTX *ctx); STACK_OF(SSL_CIPHER) *
SSL_get1_supported_ciphers(SSL *ssl); STACK_OF(SSL_CIPHER) *
SSL_get_client_ciphers(const SSL *ssl); const char *
SSL_get_cipher_list(const SSL *ssl, int priority);

DESCRIPTION

SSL_get_ciphers() returns the stack of available SSL_CIPHERs for ssl, sorted by preference. SSL_CTX_get_ciphers() returns the stack of available SSL_CIPHERs for ctx. SSL_get1_supported_ciphers() returns a stack of enabled SSL_CIPHERs for ssl as it would be sent in a ClientHello, sorted by preference. The list depends on settings like the cipher list, the supported protocol versions, the security level, and the enabled signature algorithms. The list of ciphers that would be sent in a ClientHello can differ from the list of ciphers that would be acceptable when acting as a server. For example, additional ciphers may be usable by a server if there is a gap in the list of supported protocols, and some ciphers may not be usable by a server if there is not a suitable certificate configured. SSL_get_client_ciphers() returns the stack of available SSL_CIPHERs matching the list received from the client on ssl. The details of the ciphers obtained by SSL_get_ciphers(), SSL_CTX_get_ciphers(), SSL_get1_supported_ciphers(), and SSL_get_client_ciphers() can be obtained using the SSL_CIPHER_get_name(3) family of functions. SSL_get_cipher_list() is deprecated — use SSL_get_ciphers() instead — and badly misnamed; it does not return a list but the name of one element of the return value of SSL_get_ciphers(), with the index given by the priority argument. Passing 0 selects the cipher with the highest priority. To iterate over all available ciphers in decreasing priority, repeatedly increment the argument by 1 until NULL is returned.

RETURN VALUES

SSL_get_ciphers() returns an internal pointer to a list of ciphers or NULL if ssl is NULL or if no ciphers are available. The returned pointer may not only become invalid when ssl is destroyed or when SSL_set_cipher_list(3) is called on it, but also when the SSL_CTX object in use by ssl at the time of the call is freed or when SSL_CTX_set_cipher_list(3) is called on that context object. SSL_CTX_get_ciphers() returns an internal pointer to a list of ciphers or NULL if ctx is NULL or if no ciphers are available. The returned pointer becomes invalid when ctx is destroyed or when SSL_CTX_set_cipher_list(3) is called on it. SSL_get1_supported_ciphers() returns a newly allocated list of ciphers or NULL if ssl is NULL, if no ciphers are available, or if an error occurs. When the returned pointer is no longer needed, the caller is responsible for freeing it using sk_SSL_CIPHER_free(). SSL_get_client_ciphers() returns an internal pointer to a list of ciphers or NULL if ssl is NULL, has no active session, or is not operating in server mode. The returned pointer becomes invalid when the SSL_SESSION object is destroyed, even if the ssl object remains valid. It may also become invalid in other circumstances, for example when processing a new ClientHello. SSL_get_cipher_list() returns an internal pointer to a string or NULL if ssl is NULL, if no ciphers are available, or if priority is greater than or equal to the number of available ciphers.

SEE ALSO

ssl(3), SSL_CIPHER_get_name(3), SSL_CTX_set_cipher_list(3)

HISTORY

SSL_get_cipher_list() first appeared in SSLeay 0.5.2. SSL_get_ciphers() first appeared in SSLeay 0.8.0. Both functions have been available since OpenBSD 2.4. SSL_CTX_get_ciphers() first appeared in OpenSSL 1.1.0 and has been available since OpenBSD 6.3. SSL_get1_supported_ciphers() and SSL_get_client_ciphers() first appeared in OpenSSL 1.1.0 and has been available since OpenBSD 6.5.