]>
Commit | Line | Data |
---|---|---|
615513ba RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
c952780c | 5 | SSL_get1_supported_ciphers, SSL_get_client_ciphers, |
ccb8e6e0 BK |
6 | SSL_get_ciphers, SSL_CTX_get_ciphers, |
7 | SSL_bytes_to_cipher_list, SSL_get_cipher_list | |
c952780c | 8 | - get list of available SSL_CIPHERs |
615513ba RL |
9 | |
10 | =head1 SYNOPSIS | |
11 | ||
12 | #include <openssl/ssl.h> | |
13 | ||
c3e64028 | 14 | STACK_OF(SSL_CIPHER) *SSL_get_ciphers(const SSL *ssl); |
9d5ac953 | 15 | STACK_OF(SSL_CIPHER) *SSL_CTX_get_ciphers(const SSL_CTX *ctx); |
cdc72e49 | 16 | STACK_OF(SSL_CIPHER) *SSL_get1_supported_ciphers(SSL *s); |
831eef2c | 17 | STACK_OF(SSL_CIPHER) *SSL_get_client_ciphers(const SSL *ssl); |
90134d98 BK |
18 | int SSL_bytes_to_cipher_list(SSL *s, const unsigned char *bytes, size_t len, |
19 | int isv2format, STACK_OF(SSL_CIPHER) **sk, | |
20 | STACK_OF(SSL_CIPHER) **scsvs); | |
c3e64028 | 21 | const char *SSL_get_cipher_list(const SSL *ssl, int priority); |
615513ba RL |
22 | |
23 | =head1 DESCRIPTION | |
24 | ||
25 | SSL_get_ciphers() returns the stack of available SSL_CIPHERs for B<ssl>, | |
26 | sorted by preference. If B<ssl> is NULL or no ciphers are available, NULL | |
27 | is returned. | |
28 | ||
9d5ac953 KY |
29 | SSL_CTX_get_ciphers() returns the stack of available SSL_CIPHERs for B<ctx>. |
30 | ||
cdc72e49 | 31 | SSL_get1_supported_ciphers() returns the stack of enabled SSL_CIPHERs for |
e65dfa47 | 32 | B<ssl> as would be sent in a ClientHello (that is, sorted by preference). |
cdc72e49 KR |
33 | The list depends on settings like the cipher list, the supported protocol |
34 | versions, the security level, and the enabled signature algorithms. | |
35 | SRP and PSK ciphers are only enabled if the appropriate callbacks or settings | |
36 | have been applied. | |
e65dfa47 BK |
37 | The list of ciphers that would be sent in a ClientHello can differ from |
38 | the list of ciphers that would be acceptable when acting as a server. | |
39 | For example, additional ciphers may be usable by a server if there is | |
40 | a gap in the list of supported protocols, and some ciphers may not be | |
41 | usable by a server if there is not a suitable certificate configured. | |
cdc72e49 KR |
42 | If B<ssl> is NULL or no ciphers are available, NULL is returned. |
43 | ||
44 | SSL_get_client_ciphers() returns the stack of available SSL_CIPHERs matching the | |
45 | list received from the client on B<ssl>. If B<ssl> is NULL, no ciphers are | |
831eef2c NM |
46 | available, or B<ssl> is not operating in server mode, NULL is returned. |
47 | ||
ccb8e6e0 BK |
48 | SSL_bytes_to_cipher_list() treats the supplied B<len> octets in B<bytes> |
49 | as a wire-protocol cipher suite specification (in the three-octet-per-cipher | |
50 | SSLv2 wire format if B<isv2format> is nonzero; otherwise the two-octet | |
51 | SSLv3/TLS wire format), and parses the cipher suites supported by the library | |
90134d98 BK |
52 | into the returned stacks of SSL_CIPHER objects sk and Signalling Cipher-Suite |
53 | Values scsvs. Unsupported cipher suites are ignored. Returns 1 on success | |
54 | and 0 on failure. | |
ccb8e6e0 | 55 | |
615513ba RL |
56 | SSL_get_cipher_list() returns a pointer to the name of the SSL_CIPHER |
57 | listed for B<ssl> with B<priority>. If B<ssl> is NULL, no ciphers are | |
58 | available, or there are less ciphers than B<priority> available, NULL | |
59 | is returned. | |
60 | ||
61 | =head1 NOTES | |
62 | ||
9d5ac953 | 63 | The details of the ciphers obtained by SSL_get_ciphers(), SSL_CTX_get_ciphers() |
cdc72e49 | 64 | SSL_get1_supported_ciphers() and SSL_get_client_ciphers() can be obtained using |
9b86974e | 65 | the L<SSL_CIPHER_get_name(3)> family of functions. |
615513ba RL |
66 | |
67 | Call SSL_get_cipher_list() with B<priority> starting from 0 to obtain the | |
68 | sorted list of available ciphers, until NULL is returned. | |
69 | ||
9d5ac953 KY |
70 | Note: SSL_get_ciphers(), SSL_CTX_get_ciphers() and SSL_get_client_ciphers() |
71 | return a pointer to an internal cipher stack, which will be freed later on when | |
72 | the SSL or SSL_SESSION object is freed. Therefore, the calling code B<MUST NOT> | |
73 | free the return value itself. | |
9ef17514 | 74 | |
cdc72e49 KR |
75 | The stack returned by SSL_get1_supported_ciphers() should be freed using |
76 | sk_SSL_CIPHER_free(). | |
77 | ||
90134d98 | 78 | The stacks returned by SSL_bytes_to_cipher_list() should be freed using |
ccb8e6e0 BK |
79 | sk_SSL_CIPHER_free(). |
80 | ||
615513ba RL |
81 | =head1 RETURN VALUES |
82 | ||
83 | See DESCRIPTION | |
84 | ||
85 | =head1 SEE ALSO | |
86 | ||
b97fdb57 | 87 | L<ssl(7)>, L<SSL_CTX_set_cipher_list(3)>, |
9b86974e | 88 | L<SSL_CIPHER_get_name(3)> |
615513ba | 89 | |
e2f92610 RS |
90 | =head1 COPYRIGHT |
91 | ||
92 | Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. | |
93 | ||
94 | Licensed under the OpenSSL license (the "License"). You may not use | |
95 | this file except in compliance with the License. You can obtain a copy | |
96 | in the file LICENSE in the source distribution or at | |
97 | L<https://www.openssl.org/source/license.html>. | |
98 | ||
99 | =cut |