secure/lib/libcrypto/man/man3/SSL_get_ciphers.3

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "SSL_GET_CIPHERS 3"
 136 .TH SSL_GET_CIPHERS 3 "2022-05-03" "1.1.1o" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 SSL_get1_supported_ciphers, SSL_get_client_ciphers, SSL_get_ciphers, SSL_CTX_get_ciphers, SSL_bytes_to_cipher_list, SSL_get_cipher_list, SSL_get_shared_ciphers \&\- get list of available SSL_CIPHERs
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/ssl.h>
 147 \&
 148 \& STACK_OF(SSL_CIPHER) *SSL_get_ciphers(const SSL *ssl);
 149 \& STACK_OF(SSL_CIPHER) *SSL_CTX_get_ciphers(const SSL_CTX *ctx);
 150 \& STACK_OF(SSL_CIPHER) *SSL_get1_supported_ciphers(SSL *s);
 151 \& STACK_OF(SSL_CIPHER) *SSL_get_client_ciphers(const SSL *ssl);
 152 \& int SSL_bytes_to_cipher_list(SSL *s, const unsigned char *bytes, size_t len,
 153 \&                              int isv2format, STACK_OF(SSL_CIPHER) **sk,
 154 \&                              STACK_OF(SSL_CIPHER) **scsvs);
 155 \& const char *SSL_get_cipher_list(const SSL *ssl, int priority);
 156 \& char *SSL_get_shared_ciphers(const SSL *s, char *buf, int size);
 157 .Ve
 158 .SH "DESCRIPTION"
 159 .IX Header "DESCRIPTION"
 160 \&\fBSSL_get_ciphers()\fR returns the stack of available SSL_CIPHERs for \fBssl\fR,
 161 sorted by preference. If \fBssl\fR is \s-1NULL\s0 or no ciphers are available, \s-1NULL\s0
 162 is returned.
 163 .PP
 164 \&\fBSSL_CTX_get_ciphers()\fR returns the stack of available SSL_CIPHERs for \fBctx\fR.
 165 .PP
 166 \&\fBSSL_get1_supported_ciphers()\fR returns the stack of enabled SSL_CIPHERs for
 167 \&\fBssl\fR as would be sent in a ClientHello (that is, sorted by preference).
 168 The list depends on settings like the cipher list, the supported protocol
 169 versions, the security level, and the enabled signature algorithms.
 170 \&\s-1SRP\s0 and \s-1PSK\s0 ciphers are only enabled if the appropriate callbacks or settings
 171 have been applied.
 172 The list of ciphers that would be sent in a ClientHello can differ from
 173 the list of ciphers that would be acceptable when acting as a server.
 174 For example, additional ciphers may be usable by a server if there is
 175 a gap in the list of supported protocols, and some ciphers may not be
 176 usable by a server if there is not a suitable certificate configured.
 177 If \fBssl\fR is \s-1NULL\s0 or no ciphers are available, \s-1NULL\s0 is returned.
 178 .PP
 179 \&\fBSSL_get_client_ciphers()\fR returns the stack of available SSL_CIPHERs matching the
 180 list received from the client on \fBssl\fR. If \fBssl\fR is \s-1NULL,\s0 no ciphers are
 181 available, or \fBssl\fR is not operating in server mode, \s-1NULL\s0 is returned.
 182 .PP
 183 \&\fBSSL_bytes_to_cipher_list()\fR treats the supplied \fBlen\fR octets in \fBbytes\fR
 184 as a wire-protocol cipher suite specification (in the three-octet-per-cipher
 185 SSLv2 wire format if \fBisv2format\fR is nonzero; otherwise the two-octet
 186 SSLv3/TLS wire format), and parses the cipher suites supported by the library
 187 into the returned stacks of \s-1SSL_CIPHER\s0 objects sk and Signalling Cipher-Suite
 188 Values scsvs.  Unsupported cipher suites are ignored.  Returns 1 on success
 189 and 0 on failure.
 190 .PP
 191 \&\fBSSL_get_cipher_list()\fR returns a pointer to the name of the \s-1SSL_CIPHER\s0
 192 listed for \fBssl\fR with \fBpriority\fR. If \fBssl\fR is \s-1NULL,\s0 no ciphers are
 193 available, or there are less ciphers than \fBpriority\fR available, \s-1NULL\s0
 194 is returned.
 195 .PP
 196 \&\fBSSL_get_shared_ciphers()\fR creates a colon separated and \s-1NUL\s0 terminated list of
 197 \&\s-1SSL_CIPHER\s0 names that are available in both the client and the server. \fBbuf\fR is
 198 the buffer that should be populated with the list of names and \fBsize\fR is the
 199 size of that buffer. A pointer to \fBbuf\fR is returned on success or \s-1NULL\s0 on
 200 error. If the supplied buffer is not large enough to contain the complete list
 201 of names then a truncated list of names will be returned. Note that just because
 202 a ciphersuite is available (i.e. it is configured in the cipher list) and shared
 203 by both the client and the server it does not mean that it is enabled (see the
 204 description of \fBSSL_get1_supported_ciphers()\fR above). This function will return
 205 available shared ciphersuites whether or not they are enabled. This is a server
 206 side function only and must only be called after the completion of the initial
 207 handshake.
 208 .SH "NOTES"
 209 .IX Header "NOTES"
 210 The details of the ciphers obtained by \fBSSL_get_ciphers()\fR, \fBSSL_CTX_get_ciphers()\fR
 211 \&\fBSSL_get1_supported_ciphers()\fR and \fBSSL_get_client_ciphers()\fR can be obtained using
 212 the \fBSSL_CIPHER_get_name\fR\|(3) family of functions.
 213 .PP
 214 Call \fBSSL_get_cipher_list()\fR with \fBpriority\fR starting from 0 to obtain the
 215 sorted list of available ciphers, until \s-1NULL\s0 is returned.
 216 .PP
 217 Note: \fBSSL_get_ciphers()\fR, \fBSSL_CTX_get_ciphers()\fR and \fBSSL_get_client_ciphers()\fR
 218 return a pointer to an internal cipher stack, which will be freed later on when
 219 the \s-1SSL\s0 or \s-1SSL_SESSION\s0 object is freed.  Therefore, the calling code \fB\s-1MUST NOT\s0\fR
 220 free the return value itself.
 221 .PP
 222 The stack returned by \fBSSL_get1_supported_ciphers()\fR should be freed using
 223 \&\fBsk_SSL_CIPHER_free()\fR.
 224 .PP
 225 The stacks returned by \fBSSL_bytes_to_cipher_list()\fR should be freed using
 226 \&\fBsk_SSL_CIPHER_free()\fR.
 227 .SH "RETURN VALUES"
 228 .IX Header "RETURN VALUES"
 229 See \s-1DESCRIPTION\s0
 230 .SH "SEE ALSO"
 231 .IX Header "SEE ALSO"
 232 \&\fBssl\fR\|(7), \fBSSL_CTX_set_cipher_list\fR\|(3),
 233 \&\fBSSL_CIPHER_get_name\fR\|(3)
 234 .SH "COPYRIGHT"
 235 .IX Header "COPYRIGHT"
 236 Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
 237 .PP
 238 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 239 this file except in compliance with the License.  You can obtain a copy
 240 in the file \s-1LICENSE\s0 in the source distribution or at
 241 <https://www.openssl.org/source/license.html>.