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