xref: /freebsd-src/crypto/openssl/doc/man3/SSL_get_ciphers.pod (revision b077aed33b7b6aefca7b17ddb250cf521f938613)
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