]>
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. | |
40 | RSA export ciphers with a keylength of 512 bits for the RSA key require | |
41 | a temporary 512 bit RSA key, as typically the supplied key has a length | |
4db48ec0 | 42 | of 1024 bit (see |
9b86974e | 43 | L<SSL_CTX_set_tmp_rsa_callback(3)>). |
0b30fc90 | 44 | RSA ciphers using DHE need a certificate and key and additional DH-parameters |
9b86974e | 45 | (see L<SSL_CTX_set_tmp_dh_callback(3)>). |
6d3dec92 LJ |
46 | |
47 | A DSA cipher can only be chosen, when a DSA certificate is available. | |
3e3dac9f | 48 | DSA ciphers always use DH key exchange and therefore need DH-parameters |
9b86974e | 49 | (see L<SSL_CTX_set_tmp_dh_callback(3)>). |
6d3dec92 LJ |
50 | |
51 | When these conditions are not met for any cipher in the list (e.g. a | |
52 | client only supports export RSA ciphers with a asymmetric key length | |
53 | of 512 bits and the server is not configured to use temporary RSA | |
54 | keys), the "no shared cipher" (SSL_R_NO_SHARED_CIPHER) error is generated | |
55 | and the handshake will fail. | |
dd3430a6 | 56 | |
615513ba RL |
57 | =head1 RETURN VALUES |
58 | ||
59 | SSL_CTX_set_cipher_list() and SSL_set_cipher_list() return 1 if any cipher | |
60 | could be selected and 0 on complete failure. | |
61 | ||
62 | =head1 SEE ALSO | |
63 | ||
9b86974e RS |
64 | L<ssl(3)>, L<SSL_get_ciphers(3)>, |
65 | L<SSL_CTX_use_certificate(3)>, | |
66 | L<SSL_CTX_set_tmp_rsa_callback(3)>, | |
67 | L<SSL_CTX_set_tmp_dh_callback(3)>, | |
68 | L<ciphers(1)> | |
615513ba RL |
69 | |
70 | =cut |