Skip to content

Commit 28494c8

Browse files
ischwarzeischwarze
committed
Start documenting our new pet octopus, SSL_CTX_set_security_level(3).
Or should we call it a centipede? Feedback and OK on a previous version from jsing@ and from our chief myriapodologist, tb@.
1 parent d7636ab commit 28494c8

File tree

2 files changed

+161
-1
lines changed

2 files changed

+161
-1
lines changed

‎lib/libssl/man/Makefile

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# $OpenBSD: Makefile,v 1.76 2021/10/25 15:16:35 tb Exp $
1+
# $OpenBSD: Makefile,v 1.77 2022/07/13 20:52:36 schwarze Exp $
22

33
.include <bsd.own.mk>
44

@@ -41,6 +41,7 @@ MAN = BIO_f_ssl.3 \
4141
SSL_CTX_set_options.3 \
4242
SSL_CTX_set_quiet_shutdown.3 \
4343
SSL_CTX_set_read_ahead.3 \
44+
SSL_CTX_set_security_level.3 \
4445
SSL_CTX_set_session_cache_mode.3 \
4546
SSL_CTX_set_session_id_context.3 \
4647
SSL_CTX_set_ssl_version.3 \

‎lib/libssl/man/SSL_CTX_set_security_level.3

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
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 <[email protected]>
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
47+
A security level is a set of restrictions on algorithms, key lengths,
48+
protocol versions, and other features in TLS connections.
49+
These restrictions apply in addition to those that exist from individually
50+
selecting supported features, for example ciphers, curves, or algorithms.
51+
.Pp
52+
The 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
63+
The meaning of the columns is as follows:
64+
.Pp
65+
.Bl -tag -width features -compact
66+
.It #
67+
The number of the
68+
.Fa level .
69+
.It sec
70+
The minimum security strength measured in bits, which is approximately
71+
the binary logarithm of the number of operations an attacker has
72+
to perform in order to break a cryptographic key.
73+
This minimum strength is enforced for all relevant parameters
74+
including cipher suite encryption algorithms, ECC curves, signature
75+
algorithms, DH parameter sizes, and certificate algorithms and key
76+
sizes.
77+
See SP800-57 below
78+
.Sx SEE ALSO
79+
for details on individual algorithms.
80+
.It RSA
81+
The minimum key length in bits for the RSA, DSA, and DH algorithms.
82+
.It ECC
83+
The minimum key length in bits for ECC algorithms.
84+
.It TLS
85+
The minimum TLS protocol version.
86+
.It MAC
87+
Cipher suites using the given MACs are allowed on this level
88+
and on lower levels, but not on higher levels.
89+
.El
90+
.Pp
91+
Level 0 is only provided for backward compatibility and permits everything.
92+
.Pp
93+
Level 3 and higher disable support for session tickets
94+
and only accept cipher suites that provide forward secrecy.
95+
.Pp
96+
The functions
97+
.Fn SSL_CTX_set_security_level
98+
and
99+
.Fn SSL_set_security_level
100+
choose the security
101+
.Fa level
102+
for
103+
.Fa ctx
104+
or
105+
.Fa s ,
106+
respectively.
107+
If not set, security level 1 is used.
108+
.Pp
109+
.Xr SSL_CTX_new 3
110+
initializes the security level of the new object to 1.
111+
.Pp
112+
.Xr SSL_new 3
113+
and
114+
.Xr SSL_set_SSL_CTX 3
115+
copy the security level from the context to the SSL object.
116+
.Pp
117+
.Xr SSL_dup 3
118+
copies the security level from the old to the new object.
119+
.Sh RETURN VALUES
120+
.Fn SSL_CTX_get_security_level
121+
and
122+
.Fn SSL_get_security_level
123+
return the security level configured in
124+
.Fa ctx
125+
or
126+
.Fa s ,
127+
respectively.
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
144+
These functions first appeared in OpenSSL 1.1.0
145+
and have been available since
146+
.Ox 7.2 .
147+
.Sh CAVEATS
148+
Applications which do not check the return values
149+
of configuration functions will misbehave.
150+
For example, if an application does not check the return value
151+
after trying to set a certificate and the certificate is rejected
152+
because of the security level, the application may behave as if
153+
no certificate had been provided at all.
154+
.Pp
155+
While some restrictions may be handled gracefully by negotiations
156+
between the client and the server, other restrictions may be
157+
fatal and abort the TLS handshake.
158+
For example, this can happen if the peer certificate contains a key
159+
that is too short or if the DH parameter size is too small.

0 commit comments

Comments
 (0)