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