]>
Commit | Line | Data |
---|---|---|
615513ba RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
66ebbb6a | 5 | SSL_CTX_set_cipher_list, SSL_set_cipher_list - choose list of available SSL_CIPHERs |
615513ba RL |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/ssl.h> | |
10 | ||
11 | int SSL_CTX_set_cipher_list(SSL_CTX *ctx, const char *str); | |
12 | int SSL_set_cipher_list(SSL *ssl, const char *str); | |
13 | ||
14 | =head1 DESCRIPTION | |
15 | ||
16 | SSL_CTX_set_cipher_list() sets the list of available ciphers for B<ctx> | |
17 | using the control string B<str>. The format of the string is described | |
9b86974e | 18 | in L<ciphers(1)>. The list of ciphers is inherited by all |
615513ba RL |
19 | B<ssl> objects created from B<ctx>. |
20 | ||
21 | SSL_set_cipher_list() sets the list of ciphers only for B<ssl>. | |
22 | ||
23 | =head1 NOTES | |
24 | ||
c69c47b9 | 25 | The control string B<str> should be universally usable and not depend |
615513ba RL |
26 | on details of the library configuration (ciphers compiled in). Thus no |
27 | syntax checking takes place. Items that are not recognized, because the | |
c69c47b9 | 28 | corresponding ciphers are not compiled in or because they are mistyped, |
615513ba RL |
29 | are simply ignored. Failure is only flagged if no ciphers could be collected |
30 | at all. | |
31 | ||
dd3430a6 RL |
32 | It should be noted, that inclusion of a cipher to be used into the list is |
33 | a necessary condition. On the client side, the inclusion into the list is | |
0f817d3b DSH |
34 | also sufficient unless the security level excludes it. On the server side, |
35 | additional restrictions apply. All ciphers have additional requirements. | |
36 | ADH ciphers don't need a certificate, but DH-parameters must have been set. | |
37 | All other ciphers need a corresponding certificate and key. | |
6d3dec92 LJ |
38 | |
39 | A RSA cipher can only be chosen, when a RSA certificate is available. | |
0b30fc90 | 40 | RSA ciphers using DHE need a certificate and key and additional DH-parameters |
9b86974e | 41 | (see L<SSL_CTX_set_tmp_dh_callback(3)>). |
6d3dec92 LJ |
42 | |
43 | A DSA cipher can only be chosen, when a DSA certificate is available. | |
3e3dac9f | 44 | DSA ciphers always use DH key exchange and therefore need DH-parameters |
9b86974e | 45 | (see L<SSL_CTX_set_tmp_dh_callback(3)>). |
6d3dec92 LJ |
46 | |
47 | When these conditions are not met for any cipher in the list (e.g. a | |
48 | client only supports export RSA ciphers with a asymmetric key length | |
49 | of 512 bits and the server is not configured to use temporary RSA | |
50 | keys), the "no shared cipher" (SSL_R_NO_SHARED_CIPHER) error is generated | |
51 | and the handshake will fail. | |
dd3430a6 | 52 | |
615513ba RL |
53 | =head1 RETURN VALUES |
54 | ||
55 | SSL_CTX_set_cipher_list() and SSL_set_cipher_list() return 1 if any cipher | |
56 | could be selected and 0 on complete failure. | |
57 | ||
58 | =head1 SEE ALSO | |
59 | ||
9b86974e RS |
60 | L<ssl(3)>, L<SSL_get_ciphers(3)>, |
61 | L<SSL_CTX_use_certificate(3)>, | |
9b86974e RS |
62 | L<SSL_CTX_set_tmp_dh_callback(3)>, |
63 | L<ciphers(1)> | |
615513ba RL |
64 | |
65 | =cut |