1.\" $OpenBSD: SSL_get_ciphers.3,v 1.7 2019/01/22 01:18:24 tb Exp $ 2.\" full merge up to: OpenSSL c3e64028 Mar 30 11:50:14 2005 +0000 3.\" selective merge up to: OpenSSL 83cf7abf May 29 13:07:08 2018 +0100 4.\" 5.\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>, 6.\" Nick Mathewson <nickm@torproject.org>, and Kazuki Yamaguchi <k@rhe.jp>. 7.\" Copyright (c) 2000, 2005, 2015, 2016 The OpenSSL Project. 8.\" All rights reserved. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 14.\" 1. Redistributions of source code must retain the above copyright 15.\" notice, this list of conditions and the following disclaimer. 16.\" 17.\" 2. Redistributions in binary form must reproduce the above copyright 18.\" notice, this list of conditions and the following disclaimer in 19.\" the documentation and/or other materials provided with the 20.\" distribution. 21.\" 22.\" 3. All advertising materials mentioning features or use of this 23.\" software must display the following acknowledgment: 24.\" "This product includes software developed by the OpenSSL Project 25.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 26.\" 27.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 28.\" endorse or promote products derived from this software without 29.\" prior written permission. For written permission, please contact 30.\" openssl-core@openssl.org. 31.\" 32.\" 5. Products derived from this software may not be called "OpenSSL" 33.\" nor may "OpenSSL" appear in their names without prior written 34.\" permission of the OpenSSL Project. 35.\" 36.\" 6. Redistributions of any form whatsoever must retain the following 37.\" acknowledgment: 38.\" "This product includes software developed by the OpenSSL Project 39.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 40.\" 41.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 42.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 43.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 44.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 45.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 46.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 47.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 48.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 49.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 50.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 51.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 52.\" OF THE POSSIBILITY OF SUCH DAMAGE. 53.\" 54.Dd $Mdocdate: January 22 2019 $ 55.Dt SSL_GET_CIPHERS 3 56.Os 57.Sh NAME 58.Nm SSL_get_ciphers , 59.Nm SSL_CTX_get_ciphers , 60.Nm SSL_get1_supported_ciphers , 61.Nm SSL_get_client_ciphers , 62.Nm SSL_get_cipher_list 63.Nd get list of available SSL_CIPHERs 64.Sh SYNOPSIS 65.In openssl/ssl.h 66.Ft STACK_OF(SSL_CIPHER) * 67.Fn SSL_get_ciphers "const SSL *ssl" 68.Ft STACK_OF(SSL_CIPHER) * 69.Fn SSL_CTX_get_ciphers "const SSL_CTX *ctx" 70.Ft STACK_OF(SSL_CIPHER) * 71.Fn SSL_get1_supported_ciphers "SSL *ssl" 72.Ft STACK_OF(SSL_CIPHER) * 73.Fn SSL_get_client_ciphers "const SSL *ssl" 74.Ft const char * 75.Fn SSL_get_cipher_list "const SSL *ssl" "int priority" 76.Sh DESCRIPTION 77.Fn SSL_get_ciphers 78returns the stack of available 79.Vt SSL_CIPHER Ns s 80for 81.Fa ssl , 82sorted by preference. 83If 84.Fa ssl 85is 86.Dv NULL 87or no ciphers are available, 88.Dv NULL 89is returned. 90.Pp 91.Fn SSL_CTX_get_ciphers 92returns the stack of available 93.Vt SSL_CIPHER Ns s 94for 95.Fa ctx . 96.Pp 97.Fn SSL_get1_supported_ciphers 98returns the stack of enabled 99.Vt SSL_CIPHER Ns s 100for 101.Fa ssl 102as it would be sent in a ClientHello, sorted by preference. 103The list depends on settings like the cipher list, the supported 104protocol versions, the security level, and the enabled signature 105algorithms. 106The list of ciphers that would be sent in a ClientHello can differ 107from the list of ciphers that would be acceptable when acting as a 108server. 109For example, 110additional ciphers may be usable by a server if there is a gap in the 111list of supported protocols, and some ciphers may not be usable by a 112server if there is not a suitable certificate configured. 113If 114.Fa ssl 115is 116.Dv NULL 117or no ciphers are available, 118.Dv NULL 119is returned. 120.Pp 121.Fn SSL_get_client_ciphers 122returns the stack of available 123.Vt SSL_CIPHER Ns s 124matching the list received from the client on 125.Fa ssl . 126If 127.Fa ssl 128is 129.Dv NULL , 130no ciphers are available, or 131.Fa ssl 132is not operating in server mode, 133.Dv NULL 134is returned. 135.Pp 136.Fn SSL_get_ciphers , 137.Fn SSL_CTX_get_ciphers , 138and 139.Fn SSL_get_client_ciphers 140return pointers to internal cipher stacks, which will be freed 141later on when the 142.Vt SSL 143or 144.Vt SSL_CTX 145object is freed. 146Therefore, the calling code must not free the return value itself. 147.Pp 148The details of the ciphers obtained by 149.Fn SSL_get_ciphers , 150.Fn SSL_CTX_get_ciphers , 151.Fn SSL_get1_supported_ciphers , 152and 153.Fn SSL_get_client_ciphers 154can be obtained using the 155.Xr SSL_CIPHER_get_name 3 156family of functions. 157.Pp 158.Fn SSL_get_cipher_list 159returns a pointer to the name of the 160.Vt SSL_CIPHER 161listed for 162.Fa ssl 163with 164.Fa priority . 165If 166.Fa ssl 167is 168.Dv NULL , 169no ciphers are available, or there are fewer ciphers than 170.Fa priority 171available, 172.Dv NULL 173is returned. 174.Pp 175Call 176.Fn SSL_get_cipher_list 177with 178.Fa priority 179starting from 0 to obtain the sorted list of available ciphers, until 180.Dv NULL 181is returned. 182.Sh SEE ALSO 183.Xr ssl 3 , 184.Xr SSL_CIPHER_get_name 3 , 185.Xr SSL_CTX_set_cipher_list 3 186.Sh HISTORY 187.Fn SSL_get_cipher_list 188first appeared in SSLeay 0.5.2. 189.Fn SSL_get_ciphers 190first appeared in SSLeay 0.8.0. 191Both functions have been available since 192.Ox 2.4 . 193.Pp 194.Fn SSL_CTX_get_ciphers 195first appeared in OpenSSL 1.1.0 and has been available since 196.Ox 6.3 . 197.Pp 198.Fn SSL_get1_supported_ciphers 199and 200.Fn SSL_get_client_ciphers 201first appeared in OpenSSL 1.1.0 and has been available since 202.Ox 6.5 . 203