1.\" $OpenBSD: SSL_CTX_set_security_level.3,v 1.1 2022/07/13 20:52:36 schwarze Exp $
2.\"
3.\" Copyright (c) 2022 Ingo Schwarze <schwarze@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: July 13 2022 $
18.Dt SSL_CTX_SET_SECURITY_LEVEL 3
19.Os
20.Sh NAME
21.Nm SSL_CTX_set_security_level ,
22.Nm SSL_set_security_level ,
23.Nm SSL_CTX_get_security_level ,
24.Nm SSL_get_security_level
25.Nd change security level for TLS
26.Sh SYNOPSIS
27.In openssl/ssl.h
28.Ft void
29.Fo SSL_CTX_set_security_level
30.Fa "SSL_CTX *ctx"
31.Fa "int level"
32.Fc
33.Ft void
34.Fo SSL_set_security_level
35.Fa "SSL *s"
36.Fa "int level"
37.Fc
38.Ft int
39.Fo SSL_CTX_get_security_level
40.Fa "const SSL_CTX *ctx"
41.Fc
42.Ft int
43.Fo SSL_get_security_level
44.Fa "const SSL *s"
45.Fc
46.Sh DESCRIPTION
47A security level is a set of restrictions on algorithms, key lengths,
48protocol versions, and other features in TLS connections.
49These restrictions apply in addition to those that exist from individually
50selecting supported features, for example ciphers, curves, or algorithms.
51.Pp
52The following table shows properties of the various security levels:
53.Bl -column # sec 15360 ECC TLS SHA1 -offset indent
54.It # Ta   sec Ta   \0\0RSA Ta   ECC Ta TLS Ta MAC
55.It 0 Ta \0\00 Ta \0\0\0\00 Ta \0\00 Ta 1.0 Ta MD5
56.It 1 Ta  \080 Ta    \01024 Ta   160 Ta 1.0 Ta RC4
57.It 2 Ta   112 Ta    \02048 Ta   224 Ta 1.0 Ta
58.It 3 Ta   128 Ta    \03072 Ta   256 Ta 1.1 Ta SHA1
59.It 4 Ta   192 Ta    \07680 Ta   384 Ta 1.2 Ta
60.It 5 Ta   256 Ta     15360 Ta   512 Ta 1.2 Ta
61.El
62.Pp
63The meaning of the columns is as follows:
64.Pp
65.Bl -tag -width features -compact
66.It #
67The number of the
68.Fa level .
69.It sec
70The minimum security strength measured in bits, which is approximately
71the binary logarithm of the number of operations an attacker has
72to perform in order to break a cryptographic key.
73This minimum strength is enforced for all relevant parameters
74including cipher suite encryption algorithms, ECC curves, signature
75algorithms, DH parameter sizes, and certificate algorithms and key
76sizes.
77See SP800-57 below
78.Sx SEE ALSO
79for details on individual algorithms.
80.It RSA
81The minimum key length in bits for the RSA, DSA, and DH algorithms.
82.It ECC
83The minimum key length in bits for ECC algorithms.
84.It TLS
85The minimum TLS protocol version.
86.It MAC
87Cipher suites using the given MACs are allowed on this level
88and on lower levels, but not on higher levels.
89.El
90.Pp
91Level 0 is only provided for backward compatibility and permits everything.
92.Pp
93Level 3 and higher disable support for session tickets
94and only accept cipher suites that provide forward secrecy.
95.Pp
96The functions
97.Fn SSL_CTX_set_security_level
98and
99.Fn SSL_set_security_level
100choose the security
101.Fa level
102for
103.Fa ctx
104or
105.Fa s ,
106respectively.
107If not set, security level 1 is used.
108.Pp
109.Xr SSL_CTX_new 3
110initializes the security level of the new object to 1.
111.Pp
112.Xr SSL_new 3
113and
114.Xr SSL_set_SSL_CTX 3
115copy the security level from the context to the SSL object.
116.Pp
117.Xr SSL_dup 3
118copies the security level from the old to the new object.
119.Sh RETURN VALUES
120.Fn SSL_CTX_get_security_level
121and
122.Fn SSL_get_security_level
123return the security level configured in
124.Fa ctx
125or
126.Fa s ,
127respectively.
128.Sh SEE ALSO
129.Xr EVP_PKEY_security_bits 3 ,
130.Xr RSA_security_bits 3 ,
131.Xr ssl 3 ,
132.Xr SSL_CTX_new 3 ,
133.Xr SSL_new 3
134.Rs
135.%A Elaine Barker
136.%T Recommendation for Key Management
137.%I U.S. National Institute of Standards and Technology
138.%R NIST Special Publication 800-57 Part 1 Revision 5
139.%U https://doi.org/10.6028/NIST.SP.800-57pt1r5
140.%C Gaithersburg, MD
141.%D May 2020
142.Re
143.Sh HISTORY
144These functions first appeared in OpenSSL 1.1.0
145and have been available since
146.Ox 7.2 .
147.Sh CAVEATS
148Applications which do not check the return values
149of configuration functions will misbehave.
150For example, if an application does not check the return value
151after trying to set a certificate and the certificate is rejected
152because of the security level, the application may behave as if
153no certificate had been provided at all.
154.Pp
155While some restrictions may be handled gracefully by negotiations
156between the client and the server, other restrictions may be
157fatal and abort the TLS handshake.
158For example, this can happen if the peer certificate contains a key
159that is too short or if the DH parameter size is too small.
160