Debian Codegraph @

upstream/debian-unstable/man3/SSL_CTX_set_security_level.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "SSL_CTX_SET_SECURITY_LEVEL 3SSL"
58 .TH SSL_CTX_SET_SECURITY_LEVEL 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 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
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& #include <openssl/ssl.h>
69 \&
70 \& void SSL_CTX_set_security_level(SSL_CTX *ctx, int level);
71 \& void SSL_set_security_level(SSL *s, int level);
72 \&
73 \& int SSL_CTX_get_security_level(const SSL_CTX *ctx);
74 \& int SSL_get_security_level(const SSL *s);
75 \&
76 \& void SSL_CTX_set_security_callback(SSL_CTX *ctx,
77 \& int (*cb)(SSL *s, SSL_CTX *ctx, int op,
78 \& int bits, int nid,
79 \& void *other, void *ex));
80 \&
81 \& void SSL_set_security_callback(SSL *s, int (*cb)(SSL *s, SSL_CTX *ctx, int op,
82 \& int bits, int nid,
83 \& void *other, void *ex));
84 \&
85 \& int (*SSL_CTX_get_security_callback(const SSL_CTX *ctx))(SSL *s, SSL_CTX *ctx, int op,
86 \& int bits, int nid, void *other,
87 \& void *ex);
88 \& int (*SSL_get_security_callback(const SSL *s))(SSL *s, SSL_CTX *ctx, int op,
89 \& int bits, int nid, void *other,
90 \& void *ex);
91 \&
92 \& void SSL_CTX_set0_security_ex_data(SSL_CTX *ctx, void *ex);
93 \& void SSL_set0_security_ex_data(SSL *s, void *ex);
94 \&
95 \& void *SSL_CTX_get0_security_ex_data(const SSL_CTX *ctx);
96 \& void *SSL_get0_security_ex_data(const SSL *s);
97 .Ve
98 .SH DESCRIPTION
99 .IX Header "DESCRIPTION"
100 The functions \fBSSL_CTX_set_security_level()\fR and \fBSSL_set_security_level()\fR set
101 the security level to \fBlevel\fR. If not set the library default security level
102 is used.
103 .PP
104 The functions \fBSSL_CTX_get_security_level()\fR and \fBSSL_get_security_level()\fR
105 retrieve the current security level.
106 .PP
107 \&\fBSSL_CTX_set_security_callback()\fR, \fBSSL_set_security_callback()\fR,
108 \&\fBSSL_CTX_get_security_callback()\fR and \fBSSL_get_security_callback()\fR get or set
109 the security callback associated with \fBctx\fR or \fBs\fR. If not set a default
110 security callback is used. The meaning of the parameters and the behaviour
111 of the default callbacks is described below.
112 .PP
113 \&\fBSSL_CTX_set0_security_ex_data()\fR, \fBSSL_set0_security_ex_data()\fR,
114 \&\fBSSL_CTX_get0_security_ex_data()\fR and \fBSSL_get0_security_ex_data()\fR set the
115 extra data pointer passed to the \fBex\fR parameter of the callback. This
116 value is passed to the callback verbatim and can be set to any convenient
117 application specific value.
118 .SH "DEFAULT CALLBACK BEHAVIOUR"
119 .IX Header "DEFAULT CALLBACK BEHAVIOUR"
120 If an application doesn't set its own security callback the default
121 callback is used. It is intended to provide sane defaults. The meaning
122 of each level is described below.
123 .IP "\fBLevel 0\fR" 4
124 .IX Item "Level 0"
125 Everything is permitted. This retains compatibility with previous versions of
126 OpenSSL.
127 .IP "\fBLevel 1\fR" 4
128 .IX Item "Level 1"
129 The security level corresponds to a minimum of 80 bits of security. Any
130 parameters offering below 80 bits of security are excluded. As a result RSA,
131 DSA and DH keys shorter than 1024 bits and ECC keys shorter than 160 bits
132 are prohibited. Any cipher suite using MD5 for the MAC is also prohibited. Any
133 cipher suites using CCM with a 64 bit authentication tag are prohibited. Note
134 that signatures using SHA1 and MD5 are also forbidden at this level as they
135 have less than 80 security bits. Additionally, SSLv3, TLS 1.0, TLS 1.1 and
136 DTLS 1.0 are all disabled at this level.
137 .IP "\fBLevel 2\fR" 4
138 .IX Item "Level 2"
139 Security level set to 112 bits of security. As a result RSA, DSA and DH keys
140 shorter than 2048 bits and ECC keys shorter than 224 bits are prohibited.
141 In addition to the level 1 exclusions any cipher suite using RC4 is also
142 prohibited. Compression is disabled.
143 .IP "\fBLevel 3\fR" 4
144 .IX Item "Level 3"
145 Security level set to 128 bits of security. As a result RSA, DSA and DH keys
146 shorter than 3072 bits and ECC keys shorter than 256 bits are prohibited.
147 In addition to the level 2 exclusions cipher suites not offering forward
148 secrecy are prohibited. Session tickets are disabled.
149 .IP "\fBLevel 4\fR" 4
150 .IX Item "Level 4"
151 Security level set to 192 bits of security. As a result RSA, DSA and
152 DH keys shorter than 7680 bits and ECC keys shorter than 384 bits are
153 prohibited. Cipher suites using SHA1 for the MAC are prohibited.
154 .IP "\fBLevel 5\fR" 4
155 .IX Item "Level 5"
156 Security level set to 256 bits of security. As a result RSA, DSA and DH keys
157 shorter than 15360 bits and ECC keys shorter than 512 bits are prohibited.
158 .SH "APPLICATION DEFINED SECURITY CALLBACKS"
159 .IX Header "APPLICATION DEFINED SECURITY CALLBACKS"
160 \&\fIDocumentation to be provided.\fR
161 .SH NOTES
162 .IX Header "NOTES"
163 The default security level can be configured when OpenSSL is compiled by
164 setting \fB\-DOPENSSL_TLS_SECURITY_LEVEL=level\fR. If not set then 2 is used.
165 .PP
166 The security framework disables or reject parameters inconsistent with the
167 set security level. In the past this was difficult as applications had to set
168 a number of distinct parameters (supported ciphers, supported curves supported
169 signature algorithms) to achieve this end and some cases (DH parameter size
170 for example) could not be checked at all.
171 .PP
172 By setting an appropriate security level much of this complexity can be
173 avoided.
174 .PP
175 The bits of security limits affect all relevant parameters including
176 cipher suite encryption algorithms, supported ECC curves, supported
177 signature algorithms, DH parameter sizes, certificate key sizes and
178 signature algorithms. This limit applies no matter what other custom
179 settings an application has set: so if the cipher suite is set to \fBALL\fR
180 then only cipher suites consistent with the security level are permissible.
181 .PP
182 See SP800\-57 for how the security limits are related to individual
183 algorithms.
184 .PP
185 Some security levels require large key sizes for non-ECC public key
186 algorithms which can severely degrade performance. For example 256 bits
187 of security requires the use of RSA keys of at least 15360 bits in size.
188 .PP
189 Some restrictions can be gracefully handled: for example cipher suites
190 offering insufficient security are not sent by the client and will not
191 be selected by the server. Other restrictions such as the peer certificate
192 key size or the DH parameter size will abort the handshake with a fatal
193 alert.
194 .PP
195 Attempts to set certificates or parameters with insufficient security are
196 also blocked. For example trying to set a certificate using a 512 bit RSA key
197 or a certificate with a signature with SHA1 digest at level 1 using
198 \&\fBSSL_CTX_use_certificate()\fR. Applications which do not check the return values
199 for errors will misbehave: for example it might appear that a certificate is
200 not set at all because it had been rejected.
201 .SH "RETURN VALUES"
202 .IX Header "RETURN VALUES"
203 \&\fBSSL_CTX_set_security_level()\fR and \fBSSL_set_security_level()\fR do not return values.
204 .PP
205 \&\fBSSL_CTX_get_security_level()\fR and \fBSSL_get_security_level()\fR return a integer that
206 represents the security level with \fBSSL_CTX\fR or \fBSSL\fR, respectively.
207 .PP
208 \&\fBSSL_CTX_set_security_callback()\fR and \fBSSL_set_security_callback()\fR do not return
209 values.
210 .PP
211 \&\fBSSL_CTX_get_security_callback()\fR and \fBSSL_get_security_callback()\fR return the pointer
212 to the security callback or NULL if the callback is not set.
213 .PP
214 \&\fBSSL_CTX_get0_security_ex_data()\fR and \fBSSL_get0_security_ex_data()\fR return the extra
215 data pointer or NULL if the ex data is not set.
216 .SH "SEE ALSO"
217 .IX Header "SEE ALSO"
218 \&\fBssl\fR\|(7)
219 .SH HISTORY
220 .IX Header "HISTORY"
221 These functions were added in OpenSSL 1.1.0.
222 .SH COPYRIGHT
223 .IX Header "COPYRIGHT"
224 Copyright 2014\-2020 The OpenSSL Project Authors. All Rights Reserved.
225 .PP
226 Licensed under the Apache License 2.0 (the "License"). You may not use
227 this file except in compliance with the License. You can obtain a copy
228 in the file LICENSE in the source distribution or at
229 <https://www.openssl.org/source/license.html>.