]>
Commit | Line | Data |
---|---|---|
0f817d3b DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | SSL_CTX_set_security_level, SSL_set_security_level, SSL_CTX_get_security_level, SSL_get_security_level, SSL_CTX_set_security_callback, SSL_set_security_callback, SSL_CTX_get_security_callback, SSL_get_security_callback, SSL_CTX_set0_security_ex_data, SSL_set0_security_ex_data, SSL_CTX_get0_security_ex_data, SSL_get0_security_ex_data - SSL/TLS security framework | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/ssl.h> | |
10 | ||
11 | void SSL_CTX_set_security_level(SSL_CTX *ctx, int level); | |
12 | void SSL_set_security_level(SSL *s, int level); | |
13 | ||
14 | int SSL_CTX_get_security_level(const SSL_CTX *ctx); | |
15 | int SSL_get_security_level(const SSL *s); | |
16 | ||
17 | void SSL_CTX_set_security_callback(SSL_CTX *ctx, | |
e9b77246 BB |
18 | int (*cb)(SSL *s, SSL_CTX *ctx, int op, |
19 | int bits, int nid, | |
20 | void *other, void *ex)); | |
21 | ||
22 | void SSL_set_security_callback(SSL *s, int (*cb)(SSL *s, SSL_CTX *ctx, int op, | |
23 | int bits, int nid, | |
24 | void *other, void *ex)); | |
25 | ||
26 | int (*SSL_CTX_get_security_callback(const SSL_CTX *ctx))(SSL *s, SSL_CTX *ctx, int op, | |
27 | int bits, int nid, void *other, | |
28 | void *ex); | |
29 | int (*SSL_get_security_callback(const SSL *s))(SSL *s, SSL_CTX *ctx, int op, | |
30 | int bits, int nid, void *other, | |
31 | void *ex); | |
0f817d3b DSH |
32 | |
33 | void SSL_CTX_set0_security_ex_data(SSL_CTX *ctx, void *ex); | |
34 | void SSL_set0_security_ex_data(SSL *s, void *ex); | |
35 | ||
36 | void *SSL_CTX_get0_security_ex_data(const SSL_CTX *ctx); | |
37 | void *SSL_get0_security_ex_data(const SSL *s); | |
38 | ||
39 | =head1 DESCRIPTION | |
40 | ||
41 | The functions SSL_CTX_set_security_level() and SSL_set_security_level() set | |
5812e6f1 | 42 | the security level to B<level>. If not set the library default security level |
0f817d3b DSH |
43 | is used. |
44 | ||
45 | The functions SSL_CTX_get_security_level() and SSL_get_security_level() | |
46 | retrieve the current security level. | |
47 | ||
48 | SSL_CTX_set_security_callback(), SSL_set_security_callback(), | |
49 | SSL_CTX_get_security_callback() and SSL_get_security_callback() get or set | |
50 | the security callback associated with B<ctx> or B<s>. If not set a default | |
51 | security callback is used. The meaning of the parameters and the behaviour | |
52 | of the default callbacks is described below. | |
53 | ||
54 | SSL_CTX_set0_security_ex_data(), SSL_set0_security_ex_data(), | |
55 | SSL_CTX_get0_security_ex_data() and SSL_get0_security_ex_data() set the | |
56 | extra data pointer passed to the B<ex> parameter of the callback. This | |
57 | value is passed to the callback verbatim and can be set to any convenient | |
58 | application specific value. | |
59 | ||
60 | =head1 DEFAULT CALLBACK BEHAVIOUR | |
61 | ||
b9b6a7e5 | 62 | If an application doesn't set its own security callback the default |
0f817d3b DSH |
63 | callback is used. It is intended to provide sane defaults. The meaning |
64 | of each level is described below. | |
65 | ||
66 | =over 4 | |
67 | ||
68 | =item B<Level 0> | |
69 | ||
70 | Everything is permitted. This retains compatibility with previous versions of | |
71 | OpenSSL. | |
72 | ||
73 | =item B<Level 1> | |
74 | ||
b7e46a9b DSH |
75 | The security level corresponds to a minimum of 80 bits of security. Any |
76 | parameters offering below 80 bits of security are excluded. As a result RSA, | |
77 | DSA and DH keys shorter than 1024 bits and ECC keys shorter than 160 bits | |
c4de074e P |
78 | are prohibited. All export cipher suites are prohibited since they all offer |
79 | less than 80 bits of security. SSL version 2 is prohibited. Any cipher suite | |
b7e46a9b | 80 | using MD5 for the MAC is also prohibited. |
0f817d3b DSH |
81 | |
82 | =item B<Level 2> | |
83 | ||
b7e46a9b DSH |
84 | Security level set to 112 bits of security. As a result RSA, DSA and DH keys |
85 | shorter than 2048 bits and ECC keys shorter than 224 bits are prohibited. | |
c4de074e | 86 | In addition to the level 1 exclusions any cipher suite using RC4 is also |
b7e46a9b | 87 | prohibited. SSL version 3 is also not allowed. Compression is disabled. |
0f817d3b DSH |
88 | |
89 | =item B<Level 3> | |
90 | ||
b7e46a9b DSH |
91 | Security level set to 128 bits of security. As a result RSA, DSA and DH keys |
92 | shorter than 3072 bits and ECC keys shorter than 256 bits are prohibited. | |
c4de074e | 93 | In addition to the level 2 exclusions cipher suites not offering forward |
b7e46a9b DSH |
94 | secrecy are prohibited. TLS versions below 1.1 are not permitted. Session |
95 | tickets are disabled. | |
0f817d3b DSH |
96 | |
97 | =item B<Level 4> | |
98 | ||
c4de074e P |
99 | Security level set to 192 bits of security. As a result RSA, DSA and |
100 | DH keys shorter than 7680 bits and ECC keys shorter than 384 bits are | |
101 | prohibited. Cipher suites using SHA1 for the MAC are prohibited. TLS | |
102 | versions below 1.2 are not permitted. | |
0f817d3b DSH |
103 | |
104 | =item B<Level 5> | |
105 | ||
b7e46a9b DSH |
106 | Security level set to 256 bits of security. As a result RSA, DSA and DH keys |
107 | shorter than 15360 bits and ECC keys shorter than 512 bits are prohibited. | |
0f817d3b DSH |
108 | |
109 | =back | |
110 | ||
111 | =head1 APPLICATION DEFINED SECURITY CALLBACKS | |
112 | ||
05ea606a | 113 | I<Documentation to be provided.> |
0f817d3b DSH |
114 | |
115 | =head1 NOTES | |
116 | ||
b7e46a9b DSH |
117 | B<WARNING> at this time setting the security level higher than 1 for |
118 | general internet use is likely to cause B<considerable> interoperability | |
119 | issues and is not recommended. This is because the B<SHA1> algorithm | |
120 | is very widely used in certificates and will be rejected at levels | |
121 | higher than 1 because it only offers 80 bits of security. | |
122 | ||
0f817d3b DSH |
123 | The default security level can be configured when OpenSSL is compiled by |
124 | setting B<-DOPENSSL_TLS_SECURITY_LEVEL=level>. If not set then 1 is used. | |
125 | ||
126 | The security framework disables or reject parameters inconsistent with the | |
127 | set security level. In the past this was difficult as applications had to set | |
128 | a number of distinct parameters (supported ciphers, supported curves supported | |
129 | signature algorithms) to achieve this end and some cases (DH parameter size | |
130 | for example) could not be checked at all. | |
131 | ||
132 | By setting an appropriate security level much of this complexity can be | |
133 | avoided. | |
134 | ||
135 | The bits of security limits affect all relevant parameters including | |
c4de074e | 136 | cipher suite encryption algorithms, supported ECC curves, supported |
0f817d3b DSH |
137 | signature algorithms, DH parameter sizes, certificate key sizes and |
138 | signature algorithms. This limit applies no matter what other custom | |
c4de074e P |
139 | settings an application has set: so if the cipher suite is set to B<ALL> |
140 | then only cipher suites consistent with the security level are permissible. | |
0f817d3b DSH |
141 | |
142 | See SP800-57 for how the security limits are related to individual | |
143 | algorithms. | |
144 | ||
a6099d4f | 145 | Some security levels require large key sizes for non-ECC public key |
b7e46a9b DSH |
146 | algorithms which can severely degrade performance. For example 256 bits |
147 | of security requires the use of RSA keys of at least 15360 bits in size. | |
0f817d3b | 148 | |
c4de074e | 149 | Some restrictions can be gracefully handled: for example cipher suites |
0f817d3b DSH |
150 | offering insufficient security are not sent by the client and will not |
151 | be selected by the server. Other restrictions such as the peer certificate | |
fc1d88f0 | 152 | key size or the DH parameter size will abort the handshake with a fatal |
0f817d3b DSH |
153 | alert. |
154 | ||
155 | Attempts to set certificates or parameters with insufficient security are | |
156 | also blocked. For example trying to set a certificate using a 512 bit RSA | |
157 | key using SSL_CTX_use_certificate() at level 1. Applications which do not | |
b7e46a9b DSH |
158 | check the return values for errors will misbehave: for example it might |
159 | appear that a certificate is not set at all because it had been rejected. | |
0f817d3b | 160 | |
1f13ad31 PY |
161 | =head1 RETURN VALUES |
162 | ||
163 | SSL_CTX_set_security_level() and SSL_set_security_level() do not return values. | |
164 | ||
165 | SSL_CTX_get_security_level() and SSL_get_security_level() return a integer that | |
166 | represents the security level with B<SSL_CTX> or B<SSL>, respectively. | |
167 | ||
168 | SSL_CTX_set_security_callback() and SSL_set_security_callback() do not return | |
169 | values. | |
170 | ||
171 | SSL_CTX_get_security_callback() and SSL_get_security_callback() return the pointer | |
172 | to the security callback or NULL if the callback is not set. | |
173 | ||
174 | SSL_CTX_get0_security_ex_data() and SSL_get0_security_ex_data() return the extra | |
175 | data pointer or NULL if the ex data is not set. | |
176 | ||
0f817d3b DSH |
177 | =head1 HISTORY |
178 | ||
179 | These functions were first added to OpenSSL 1.1.0 | |
180 | ||
e2f92610 RS |
181 | =head1 COPYRIGHT |
182 | ||
61f805c1 | 183 | Copyright 2014-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 RS |
184 | |
185 | Licensed under the OpenSSL license (the "License"). You may not use | |
186 | this file except in compliance with the License. You can obtain a copy | |
187 | in the file LICENSE in the source distribution or at | |
188 | L<https://www.openssl.org/source/license.html>. | |
189 | ||
190 | =cut |