Debian Codegraph @

upstream/debian-unstable/man3/SSL_get_ciphers.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "SSL_GET_CIPHERS 3SSL"
58 .TH SSL_GET_CIPHERS 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 SSL_get1_supported_ciphers,
65 SSL_get_client_ciphers,
66 SSL_get_ciphers,
67 SSL_CTX_get_ciphers,
68 SSL_bytes_to_cipher_list,
69 SSL_get_cipher_list,
70 SSL_get_shared_ciphers
71 \&\- get list of available SSL_CIPHERs
72 .SH SYNOPSIS
73 .IX Header "SYNOPSIS"
74 .Vb 1
75 \& #include <openssl/ssl.h>
76 \&
77 \& STACK_OF(SSL_CIPHER) *SSL_get_ciphers(const SSL *ssl);
78 \& STACK_OF(SSL_CIPHER) *SSL_CTX_get_ciphers(const SSL_CTX *ctx);
79 \& STACK_OF(SSL_CIPHER) *SSL_get1_supported_ciphers(SSL *s);
80 \& STACK_OF(SSL_CIPHER) *SSL_get_client_ciphers(const SSL *ssl);
81 \& int SSL_bytes_to_cipher_list(SSL *s, const unsigned char *bytes, size_t len,
82 \& int isv2format, STACK_OF(SSL_CIPHER) **sk,
83 \& STACK_OF(SSL_CIPHER) **scsvs);
84 \& const char *SSL_get_cipher_list(const SSL *ssl, int priority);
85 \& char *SSL_get_shared_ciphers(const SSL *s, char *buf, int size);
86 .Ve
87 .SH DESCRIPTION
88 .IX Header "DESCRIPTION"
89 \&\fBSSL_get_ciphers()\fR returns the stack of available SSL_CIPHERs for \fBssl\fR,
90 sorted by preference. If \fBssl\fR is NULL or no ciphers are available, NULL
91 is returned.
92 .PP
93 \&\fBSSL_CTX_get_ciphers()\fR returns the stack of available SSL_CIPHERs for \fBctx\fR.
94 .PP
95 \&\fBSSL_get1_supported_ciphers()\fR returns the stack of enabled SSL_CIPHERs for
96 \&\fBssl\fR as would be sent in a ClientHello (that is, sorted by preference).
97 The list depends on settings like the cipher list, the supported protocol
98 versions, the security level, and the enabled signature algorithms.
99 SRP and PSK ciphers are only enabled if the appropriate callbacks or settings
100 have been applied.
101 The list of ciphers that would be sent in a ClientHello can differ from
102 the list of ciphers that would be acceptable when acting as a server.
103 For example, additional ciphers may be usable by a server if there is
104 a gap in the list of supported protocols, and some ciphers may not be
105 usable by a server if there is not a suitable certificate configured.
106 If \fBssl\fR is NULL or no ciphers are available, NULL is returned.
107 .PP
108 \&\fBSSL_get_client_ciphers()\fR returns the stack of available SSL_CIPHERs matching the
109 list received from the client on \fBssl\fR. If \fBssl\fR is NULL, no ciphers are
110 available, or \fBssl\fR is not operating in server mode, NULL is returned.
111 .PP
112 \&\fBSSL_bytes_to_cipher_list()\fR treats the supplied \fBlen\fR octets in \fBbytes\fR
113 as a wire-protocol cipher suite specification (in the three-octet-per-cipher
114 SSLv2 wire format if \fBisv2format\fR is nonzero; otherwise the two-octet
115 SSLv3/TLS wire format), and parses the cipher suites supported by the library
116 into the returned stacks of SSL_CIPHER objects sk and Signalling Cipher-Suite
117 Values scsvs. Unsupported cipher suites are ignored. Returns 1 on success
118 and 0 on failure.
119 .PP
120 \&\fBSSL_get_cipher_list()\fR returns a pointer to the name of the SSL_CIPHER
121 listed for \fBssl\fR with \fBpriority\fR. If \fBssl\fR is NULL, no ciphers are
122 available, or there are less ciphers than \fBpriority\fR available, NULL
123 is returned.
124 .PP
125 \&\fBSSL_get_shared_ciphers()\fR creates a colon separated and NUL terminated list of
126 SSL_CIPHER names that are available in both the client and the server. \fBbuf\fR is
127 the buffer that should be populated with the list of names and \fBsize\fR is the
128 size of that buffer. A pointer to \fBbuf\fR is returned on success or NULL on
129 error. If the supplied buffer is not large enough to contain the complete list
130 of names then a truncated list of names will be returned. Note that just because
131 a ciphersuite is available (i.e. it is configured in the cipher list) and shared
132 by both the client and the server it does not mean that it is enabled (see the
133 description of \fBSSL_get1_supported_ciphers()\fR above). This function will return
134 available shared ciphersuites whether or not they are enabled. This is a server
135 side function only and must only be called after the completion of the initial
136 handshake.
137 The function sets an empty string when \fBssl\fR fails the handshake due to the
138 absence of shared ciphers.
139 .SH NOTES
140 .IX Header "NOTES"
141 The details of the ciphers obtained by \fBSSL_get_ciphers()\fR, \fBSSL_CTX_get_ciphers()\fR
142 \&\fBSSL_get1_supported_ciphers()\fR and \fBSSL_get_client_ciphers()\fR can be obtained using
143 the \fBSSL_CIPHER_get_name\fR\|(3) family of functions.
144 .PP
145 Call \fBSSL_get_cipher_list()\fR with \fBpriority\fR starting from 0 to obtain the
146 sorted list of available ciphers, until NULL is returned.
147 .PP
148 Note: \fBSSL_get_ciphers()\fR, \fBSSL_CTX_get_ciphers()\fR and \fBSSL_get_client_ciphers()\fR
149 return a pointer to an internal cipher stack, which will be freed later on when
150 the SSL or SSL_SESSION object is freed. Therefore, the calling code \fBMUST NOT\fR
151 free the return value itself.
152 .PP
153 The stack returned by \fBSSL_get1_supported_ciphers()\fR should be freed using
154 \&\fBsk_SSL_CIPHER_free()\fR.
155 .PP
156 The stacks returned by \fBSSL_bytes_to_cipher_list()\fR should be freed using
157 \&\fBsk_SSL_CIPHER_free()\fR.
158 .SH "RETURN VALUES"
159 .IX Header "RETURN VALUES"
160 See DESCRIPTION
161 .SH "SEE ALSO"
162 .IX Header "SEE ALSO"
163 \&\fBssl\fR\|(7), \fBSSL_CTX_set_cipher_list\fR\|(3),
164 \&\fBSSL_CIPHER_get_name\fR\|(3)
165 .SH COPYRIGHT
166 .IX Header "COPYRIGHT"
167 Copyright 2000\-2026 The OpenSSL Project Authors. All Rights Reserved.
168 .PP
169 Licensed under the Apache License 2.0 (the "License"). You may not use
170 this file except in compliance with the License. You can obtain a copy
171 in the file LICENSE in the source distribution or at
172 <https://www.openssl.org/source/license.html>.