1=pod 2 3=head1 NAME 4 5SSL_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, 18 int (*cb)(const SSL *s, const SSL_CTX *ctx, 19 int op, int bits, int nid, 20 void *other, void *ex)); 21 22 void SSL_set_security_callback(SSL *s, 23 int (*cb)(const SSL *s, const SSL_CTX *ctx, 24 int op, int bits, int nid, 25 void *other, void *ex)); 26 27 int (*SSL_CTX_get_security_callback(const SSL_CTX *ctx))(const SSL *s, 28 const SSL_CTX *ctx, 29 int op, int bits, 30 int nid, void *other, 31 void *ex); 32 int (*SSL_get_security_callback(const SSL *s))(const SSL *s, 33 const SSL_CTX *ctx, int op, 34 int bits, int nid, void *other, 35 void *ex); 36 37 void SSL_CTX_set0_security_ex_data(SSL_CTX *ctx, void *ex); 38 void SSL_set0_security_ex_data(SSL *s, void *ex); 39 40 void *SSL_CTX_get0_security_ex_data(const SSL_CTX *ctx); 41 void *SSL_get0_security_ex_data(const SSL *s); 42 43=head1 DESCRIPTION 44 45The functions SSL_CTX_set_security_level() and SSL_set_security_level() set 46the security level to B<level>. If not set the library default security level 47is used. 48 49The functions SSL_CTX_get_security_level() and SSL_get_security_level() 50retrieve the current security level. 51 52SSL_CTX_set_security_callback(), SSL_set_security_callback(), 53SSL_CTX_get_security_callback() and SSL_get_security_callback() get or set 54the security callback associated with B<ctx> or B<s>. If not set a default 55security callback is used. The meaning of the parameters and the behaviour 56of the default callbacks is described below. 57 58SSL_CTX_set0_security_ex_data(), SSL_set0_security_ex_data(), 59SSL_CTX_get0_security_ex_data() and SSL_get0_security_ex_data() set the 60extra data pointer passed to the B<ex> parameter of the callback. This 61value is passed to the callback verbatim and can be set to any convenient 62application specific value. 63 64=head1 DEFAULT CALLBACK BEHAVIOUR 65 66If an application doesn't set its own security callback the default 67callback is used. It is intended to provide sane defaults. The meaning 68of each level is described below. 69 70=over 4 71 72=item B<Level 0> 73 74Everything is permitted. This retains compatibility with previous versions of 75OpenSSL. 76 77=item B<Level 1> 78 79The security level corresponds to a minimum of 80 bits of security. Any 80parameters offering below 80 bits of security are excluded. As a result RSA, 81DSA and DH keys shorter than 1024 bits and ECC keys shorter than 160 bits 82are prohibited. Any cipher suite using MD5 for the MAC is also prohibited. Any 83cipher suites using CCM with a 64 bit authentication tag are prohibited. Note 84that signatures using SHA1 and MD5 are also forbidden at this level as they 85have less than 80 security bits. Additionally, SSLv3, TLS 1.0, TLS 1.1 and 86DTLS 1.0 are all disabled at this level. 87 88=item B<Level 2> 89 90Security level set to 112 bits of security. As a result RSA, DSA and DH keys 91shorter than 2048 bits and ECC keys shorter than 224 bits are prohibited. 92In addition to the level 1 exclusions any cipher suite using RC4 is also 93prohibited. Compression is disabled. 94 95=item B<Level 3> 96 97Security level set to 128 bits of security. As a result RSA, DSA and DH keys 98shorter than 3072 bits and ECC keys shorter than 256 bits are prohibited. 99In addition to the level 2 exclusions cipher suites not offering forward 100secrecy are prohibited. Session tickets are disabled. 101 102=item B<Level 4> 103 104Security level set to 192 bits of security. As a result RSA, DSA and 105DH keys shorter than 7680 bits and ECC keys shorter than 384 bits are 106prohibited. Cipher suites using SHA1 for the MAC are prohibited. 107 108=item B<Level 5> 109 110Security level set to 256 bits of security. As a result RSA, DSA and DH keys 111shorter than 15360 bits and ECC keys shorter than 512 bits are prohibited. 112 113=back 114 115=head1 APPLICATION DEFINED SECURITY CALLBACKS 116 117An application defined security callback is installed with 118SSL_CTX_set_security_callback() or SSL_set_security_callback() and replaces the 119default callback. It is consulted whenever the library needs to decide whether 120an algorithm, key, parameter or protocol version meets the configured security 121level. It should return 1 to permit the operation and 0 to reject it. A 122rejected parameter is not advertised or used, as appropriate. 123 124The callback arguments are: 125 126=over 4 127 128=item B<s>, B<ctx> 129 130The B<SSL> or B<SSL_CTX> the check applies to. One of the two is NULL: checks 131originating from a connection pass B<s> (with B<ctx> NULL), and checks 132originating from a context pass B<ctx> (with B<s> NULL). 133 134=item B<op> 135 136The operation being checked, one of the B<SSL_SECOP_*> values below. 137 138=item B<bits> 139 140The number of bits of security the parameter provides, or 0 when not 141meaningful for B<op>. 142 143=item B<nid> 144 145An identifier whose meaning depends on B<op>, or B<NID_undef> when not 146applicable. 147 148=item B<other> 149 150A pointer to the object being checked, whose type depends on B<op> as listed 151below. It is NULL when no object is associated with the operation. 152 153=item B<ex> 154 155The extra data pointer previously set with SSL_CTX_set0_security_ex_data() or 156SSL_set0_security_ex_data(), or NULL. 157 158=back 159 160Several operations have B<_SUPPORTED>, B<_SHARED> and B<_CHECK> variants. 161The I<supported> variant checks a parameter before advertising support for it. 162The I<shared> variant checks a parameter when selecting from the options 163offered by both peers. The I<check> variant checks a parameter the peer has 164selected before accepting it. 165 166The defined operations, and the corresponding type of B<other>, are: 167 168=over 4 169 170=item B<SSL_SECOP_CIPHER_SUPPORTED>, B<SSL_SECOP_CIPHER_SHARED>, B<SSL_SECOP_CIPHER_CHECK> 171 172Advertise/select/accept a TLS cipher suite. B<other> is the B<SSL_CIPHER>. 173 174=item B<SSL_SECOP_CURVE_SUPPORTED>, B<SSL_SECOP_CURVE_SHARED>, B<SSL_SECOP_CURVE_CHECK> 175 176Advertise/select/accept a named group used for key exchange, either an elliptic 177curve or a finite-field DH group. B<nid> is the group and B<other> points to 178its two byte TLS codepoint. 179 180=item B<SSL_SECOP_SIGALG_SUPPORTED>, B<SSL_SECOP_SIGALG_SHARED>, B<SSL_SECOP_SIGALG_CHECK>, B<SSL_SECOP_SIGALG_MASK> 181 182Advertise/select/accept a signature algorithm used in the handshake; 183B<SSL_SECOP_SIGALG_MASK> is used when building the mask of permitted signature 184algorithms. B<nid> is its hash and B<other> points to its two byte TLS 185codepoint. 186 187=item B<SSL_SECOP_VERSION> 188 189Negotiate a protocol version. B<nid> is the version, for example 190B<TLS1_2_VERSION>, and B<other> is NULL. 191 192=item B<SSL_SECOP_TMP_DH> 193 194Use an ephemeral DH key. B<other> is the B<EVP_PKEY>. 195 196=item B<SSL_SECOP_EE_KEY>, B<SSL_SECOP_CA_KEY> 197 198Accept an end entity or CA certificate public key. B<other> is the B<X509> 199certificate. 200 201=item B<SSL_SECOP_TICKET>, B<SSL_SECOP_COMPRESSION> 202 203Issue or accept a session ticket, or enable record compression. B<other> 204is NULL. 205 206=back 207 208=head1 NOTES 209 210The default security level can be configured when OpenSSL is compiled by 211setting B<-DOPENSSL_TLS_SECURITY_LEVEL=level>. If not set then 2 is used. 212 213The security framework disables or reject parameters inconsistent with the 214set security level. In the past this was difficult as applications had to set 215a number of distinct parameters (supported ciphers, supported curves supported 216signature algorithms) to achieve this end and some cases (DH parameter size 217for example) could not be checked at all. 218 219By setting an appropriate security level much of this complexity can be 220avoided. 221 222The bits of security limits affect all relevant parameters including 223cipher suite encryption algorithms, supported ECC curves, supported 224signature algorithms, DH parameter sizes, certificate key sizes and 225signature algorithms. This limit applies no matter what other custom 226settings an application has set: so if the cipher suite is set to B<ALL> 227then only cipher suites consistent with the security level are permissible. 228 229See SP800-57 for how the security limits are related to individual 230algorithms. 231 232Some security levels require large key sizes for non-ECC public key 233algorithms which can severely degrade performance. For example 256 bits 234of security requires the use of RSA keys of at least 15360 bits in size. 235 236Some restrictions can be gracefully handled: for example cipher suites 237offering insufficient security are not sent by the client and will not 238be selected by the server. Other restrictions such as the peer certificate 239key size or the DH parameter size will abort the handshake with a fatal 240alert. 241 242Attempts to set certificates or parameters with insufficient security are 243also blocked. For example trying to set a certificate using a 512 bit RSA key 244or a certificate with a signature with SHA1 digest at level 1 using 245SSL_CTX_use_certificate(). Applications which do not check the return values 246for errors will misbehave: for example it might appear that a certificate is 247not set at all because it had been rejected. 248 249=head1 RETURN VALUES 250 251SSL_CTX_set_security_level() and SSL_set_security_level() do not return values. 252 253SSL_CTX_get_security_level() and SSL_get_security_level() return a integer that 254represents the security level with B<SSL_CTX> or B<SSL>, respectively. 255 256SSL_CTX_set_security_callback() and SSL_set_security_callback() do not return 257values. 258 259SSL_CTX_get_security_callback() and SSL_get_security_callback() return the pointer 260to the security callback or NULL if the callback is not set. 261 262SSL_CTX_get0_security_ex_data() and SSL_get0_security_ex_data() return the extra 263data pointer or NULL if the ex data is not set. 264 265=head1 SEE ALSO 266 267L<ssl(7)> 268 269=head1 HISTORY 270 271These functions were added in OpenSSL 1.1.0. 272 273=head1 COPYRIGHT 274 275Copyright 2014-2026 The OpenSSL Project Authors. All Rights Reserved. 276 277Licensed under the Apache License 2.0 (the "License"). You may not use 278this file except in compliance with the License. You can obtain a copy 279in the file LICENSE in the source distribution or at 280L<https://www.openssl.org/source/license.html>. 281 282=cut 283