1e71b7053SJung-uk Kim=pod 2e71b7053SJung-uk Kim 3e71b7053SJung-uk Kim=head1 NAME 4e71b7053SJung-uk Kim 5e71b7053SJung-uk KimSSL_get1_supported_ciphers, 6e71b7053SJung-uk KimSSL_get_client_ciphers, 7e71b7053SJung-uk KimSSL_get_ciphers, 8e71b7053SJung-uk KimSSL_CTX_get_ciphers, 9e71b7053SJung-uk KimSSL_bytes_to_cipher_list, 10e71b7053SJung-uk KimSSL_get_cipher_list, 11e71b7053SJung-uk KimSSL_get_shared_ciphers 12e71b7053SJung-uk Kim- get list of available SSL_CIPHERs 13e71b7053SJung-uk Kim 14e71b7053SJung-uk Kim=head1 SYNOPSIS 15e71b7053SJung-uk Kim 16e71b7053SJung-uk Kim #include <openssl/ssl.h> 17e71b7053SJung-uk Kim 18e71b7053SJung-uk Kim STACK_OF(SSL_CIPHER) *SSL_get_ciphers(const SSL *ssl); 19e71b7053SJung-uk Kim STACK_OF(SSL_CIPHER) *SSL_CTX_get_ciphers(const SSL_CTX *ctx); 20e71b7053SJung-uk Kim STACK_OF(SSL_CIPHER) *SSL_get1_supported_ciphers(SSL *s); 21e71b7053SJung-uk Kim STACK_OF(SSL_CIPHER) *SSL_get_client_ciphers(const SSL *ssl); 22e71b7053SJung-uk Kim int SSL_bytes_to_cipher_list(SSL *s, const unsigned char *bytes, size_t len, 23e71b7053SJung-uk Kim int isv2format, STACK_OF(SSL_CIPHER) **sk, 24e71b7053SJung-uk Kim STACK_OF(SSL_CIPHER) **scsvs); 25e71b7053SJung-uk Kim const char *SSL_get_cipher_list(const SSL *ssl, int priority); 26e71b7053SJung-uk Kim char *SSL_get_shared_ciphers(const SSL *s, char *buf, int size); 27e71b7053SJung-uk Kim 28e71b7053SJung-uk Kim=head1 DESCRIPTION 29e71b7053SJung-uk Kim 30e71b7053SJung-uk KimSSL_get_ciphers() returns the stack of available SSL_CIPHERs for B<ssl>, 31e71b7053SJung-uk Kimsorted by preference. If B<ssl> is NULL or no ciphers are available, NULL 32e71b7053SJung-uk Kimis returned. 33e71b7053SJung-uk Kim 34e71b7053SJung-uk KimSSL_CTX_get_ciphers() returns the stack of available SSL_CIPHERs for B<ctx>. 35e71b7053SJung-uk Kim 36e71b7053SJung-uk KimSSL_get1_supported_ciphers() returns the stack of enabled SSL_CIPHERs for 37e71b7053SJung-uk KimB<ssl> as would be sent in a ClientHello (that is, sorted by preference). 38e71b7053SJung-uk KimThe list depends on settings like the cipher list, the supported protocol 39e71b7053SJung-uk Kimversions, the security level, and the enabled signature algorithms. 40e71b7053SJung-uk KimSRP and PSK ciphers are only enabled if the appropriate callbacks or settings 41e71b7053SJung-uk Kimhave been applied. 42e71b7053SJung-uk KimThe list of ciphers that would be sent in a ClientHello can differ from 43e71b7053SJung-uk Kimthe list of ciphers that would be acceptable when acting as a server. 44e71b7053SJung-uk KimFor example, additional ciphers may be usable by a server if there is 45e71b7053SJung-uk Kima gap in the list of supported protocols, and some ciphers may not be 46e71b7053SJung-uk Kimusable by a server if there is not a suitable certificate configured. 47e71b7053SJung-uk KimIf B<ssl> is NULL or no ciphers are available, NULL is returned. 48e71b7053SJung-uk Kim 49e71b7053SJung-uk KimSSL_get_client_ciphers() returns the stack of available SSL_CIPHERs matching the 50e71b7053SJung-uk Kimlist received from the client on B<ssl>. If B<ssl> is NULL, no ciphers are 51e71b7053SJung-uk Kimavailable, or B<ssl> is not operating in server mode, NULL is returned. 52e71b7053SJung-uk Kim 53e71b7053SJung-uk KimSSL_bytes_to_cipher_list() treats the supplied B<len> octets in B<bytes> 54e71b7053SJung-uk Kimas a wire-protocol cipher suite specification (in the three-octet-per-cipher 55e71b7053SJung-uk KimSSLv2 wire format if B<isv2format> is nonzero; otherwise the two-octet 56e71b7053SJung-uk KimSSLv3/TLS wire format), and parses the cipher suites supported by the library 57e71b7053SJung-uk Kiminto the returned stacks of SSL_CIPHER objects sk and Signalling Cipher-Suite 58e71b7053SJung-uk KimValues scsvs. Unsupported cipher suites are ignored. Returns 1 on success 59e71b7053SJung-uk Kimand 0 on failure. 60e71b7053SJung-uk Kim 61e71b7053SJung-uk KimSSL_get_cipher_list() returns a pointer to the name of the SSL_CIPHER 62e71b7053SJung-uk Kimlisted for B<ssl> with B<priority>. If B<ssl> is NULL, no ciphers are 63e71b7053SJung-uk Kimavailable, or there are less ciphers than B<priority> available, NULL 64e71b7053SJung-uk Kimis returned. 65e71b7053SJung-uk Kim 66e71b7053SJung-uk KimSSL_get_shared_ciphers() creates a colon separated and NUL terminated list of 67e71b7053SJung-uk KimSSL_CIPHER names that are available in both the client and the server. B<buf> is 68e71b7053SJung-uk Kimthe buffer that should be populated with the list of names and B<size> is the 69e71b7053SJung-uk Kimsize of that buffer. A pointer to B<buf> is returned on success or NULL on 70e71b7053SJung-uk Kimerror. If the supplied buffer is not large enough to contain the complete list 71e71b7053SJung-uk Kimof names then a truncated list of names will be returned. Note that just because 72e71b7053SJung-uk Kima ciphersuite is available (i.e. it is configured in the cipher list) and shared 73e71b7053SJung-uk Kimby both the client and the server it does not mean that it is enabled (see the 74e71b7053SJung-uk Kimdescription of SSL_get1_supported_ciphers() above). This function will return 75e71b7053SJung-uk Kimavailable shared ciphersuites whether or not they are enabled. This is a server 76e71b7053SJung-uk Kimside function only and must only be called after the completion of the initial 77e71b7053SJung-uk Kimhandshake. 78e71b7053SJung-uk Kim 79e71b7053SJung-uk Kim=head1 NOTES 80e71b7053SJung-uk Kim 81e71b7053SJung-uk KimThe details of the ciphers obtained by SSL_get_ciphers(), SSL_CTX_get_ciphers() 82e71b7053SJung-uk KimSSL_get1_supported_ciphers() and SSL_get_client_ciphers() can be obtained using 83e71b7053SJung-uk Kimthe L<SSL_CIPHER_get_name(3)> family of functions. 84e71b7053SJung-uk Kim 85e71b7053SJung-uk KimCall SSL_get_cipher_list() with B<priority> starting from 0 to obtain the 86e71b7053SJung-uk Kimsorted list of available ciphers, until NULL is returned. 87e71b7053SJung-uk Kim 88e71b7053SJung-uk KimNote: SSL_get_ciphers(), SSL_CTX_get_ciphers() and SSL_get_client_ciphers() 89e71b7053SJung-uk Kimreturn a pointer to an internal cipher stack, which will be freed later on when 90e71b7053SJung-uk Kimthe SSL or SSL_SESSION object is freed. Therefore, the calling code B<MUST NOT> 91e71b7053SJung-uk Kimfree the return value itself. 92e71b7053SJung-uk Kim 93e71b7053SJung-uk KimThe stack returned by SSL_get1_supported_ciphers() should be freed using 94e71b7053SJung-uk Kimsk_SSL_CIPHER_free(). 95e71b7053SJung-uk Kim 96e71b7053SJung-uk KimThe stacks returned by SSL_bytes_to_cipher_list() should be freed using 97e71b7053SJung-uk Kimsk_SSL_CIPHER_free(). 98e71b7053SJung-uk Kim 99e71b7053SJung-uk Kim=head1 RETURN VALUES 100e71b7053SJung-uk Kim 101e71b7053SJung-uk KimSee DESCRIPTION 102e71b7053SJung-uk Kim 103e71b7053SJung-uk Kim=head1 SEE ALSO 104e71b7053SJung-uk Kim 105e71b7053SJung-uk KimL<ssl(7)>, L<SSL_CTX_set_cipher_list(3)>, 106e71b7053SJung-uk KimL<SSL_CIPHER_get_name(3)> 107e71b7053SJung-uk Kim 108e71b7053SJung-uk Kim=head1 COPYRIGHT 109e71b7053SJung-uk Kim 110e71b7053SJung-uk KimCopyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. 111e71b7053SJung-uk Kim 112*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 113e71b7053SJung-uk Kimthis file except in compliance with the License. You can obtain a copy 114e71b7053SJung-uk Kimin the file LICENSE in the source distribution or at 115e71b7053SJung-uk KimL<https://www.openssl.org/source/license.html>. 116e71b7053SJung-uk Kim 117e71b7053SJung-uk Kim=cut 118