229 lines
10 KiB
HTML
229 lines
10 KiB
HTML
|
<?xml version="1.0" ?>
|
||
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
||
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
|
<head>
|
||
|
<title>SSL_CTX_set_security_level</title>
|
||
|
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
||
|
<link rev="made" href="mailto:root@localhost" />
|
||
|
</head>
|
||
|
|
||
|
<body style="background-color: white">
|
||
|
|
||
|
|
||
|
<!-- INDEX BEGIN -->
|
||
|
<div name="index">
|
||
|
<p><a name="__index__"></a></p>
|
||
|
|
||
|
<ul>
|
||
|
|
||
|
<li><a href="#name">NAME</a></li>
|
||
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
||
|
<li><a href="#description">DESCRIPTION</a></li>
|
||
|
<li><a href="#default_callback_behaviour">DEFAULT CALLBACK BEHAVIOUR</a></li>
|
||
|
<li><a href="#application_defined_security_callbacks">APPLICATION DEFINED SECURITY CALLBACKS</a></li>
|
||
|
<li><a href="#notes">NOTES</a></li>
|
||
|
<li><a href="#return_values">RETURN VALUES</a></li>
|
||
|
<li><a href="#see_also">SEE ALSO</a></li>
|
||
|
<li><a href="#history">HISTORY</a></li>
|
||
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
||
|
</ul>
|
||
|
|
||
|
<hr name="index" />
|
||
|
</div>
|
||
|
<!-- INDEX END -->
|
||
|
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="name">NAME</a></h1>
|
||
|
<p>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</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
||
|
<pre>
|
||
|
#include <openssl/ssl.h></pre>
|
||
|
<pre>
|
||
|
void SSL_CTX_set_security_level(SSL_CTX *ctx, int level);
|
||
|
void SSL_set_security_level(SSL *s, int level);</pre>
|
||
|
<pre>
|
||
|
int SSL_CTX_get_security_level(const SSL_CTX *ctx);
|
||
|
int SSL_get_security_level(const SSL *s);</pre>
|
||
|
<pre>
|
||
|
void SSL_CTX_set_security_callback(SSL_CTX *ctx,
|
||
|
int (*cb)(SSL *s, SSL_CTX *ctx, int op,
|
||
|
int bits, int nid,
|
||
|
void *other, void *ex));</pre>
|
||
|
<pre>
|
||
|
void SSL_set_security_callback(SSL *s, int (*cb)(SSL *s, SSL_CTX *ctx, int op,
|
||
|
int bits, int nid,
|
||
|
void *other, void *ex));</pre>
|
||
|
<pre>
|
||
|
int (*SSL_CTX_get_security_callback(const SSL_CTX *ctx))(SSL *s, SSL_CTX *ctx, int op,
|
||
|
int bits, int nid, void *other,
|
||
|
void *ex);
|
||
|
int (*SSL_get_security_callback(const SSL *s))(SSL *s, SSL_CTX *ctx, int op,
|
||
|
int bits, int nid, void *other,
|
||
|
void *ex);</pre>
|
||
|
<pre>
|
||
|
void SSL_CTX_set0_security_ex_data(SSL_CTX *ctx, void *ex);
|
||
|
void SSL_set0_security_ex_data(SSL *s, void *ex);</pre>
|
||
|
<pre>
|
||
|
void *SSL_CTX_get0_security_ex_data(const SSL_CTX *ctx);
|
||
|
void *SSL_get0_security_ex_data(const SSL *s);</pre>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="description">DESCRIPTION</a></h1>
|
||
|
<p>The functions <code>SSL_CTX_set_security_level()</code> and <code>SSL_set_security_level()</code> set
|
||
|
the security level to <strong>level</strong>. If not set the library default security level
|
||
|
is used.</p>
|
||
|
<p>The functions <code>SSL_CTX_get_security_level()</code> and <code>SSL_get_security_level()</code>
|
||
|
retrieve the current security level.</p>
|
||
|
<p><code>SSL_CTX_set_security_callback()</code>, <code>SSL_set_security_callback()</code>,
|
||
|
<code>SSL_CTX_get_security_callback()</code> and <code>SSL_get_security_callback()</code> get or set
|
||
|
the security callback associated with <strong>ctx</strong> or <strong>s</strong>. If not set a default
|
||
|
security callback is used. The meaning of the parameters and the behaviour
|
||
|
of the default callbacks is described below.</p>
|
||
|
<p>SSL_CTX_set0_security_ex_data(), SSL_set0_security_ex_data(),
|
||
|
SSL_CTX_get0_security_ex_data() and SSL_get0_security_ex_data() set the
|
||
|
extra data pointer passed to the <strong>ex</strong> parameter of the callback. This
|
||
|
value is passed to the callback verbatim and can be set to any convenient
|
||
|
application specific value.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="default_callback_behaviour">DEFAULT CALLBACK BEHAVIOUR</a></h1>
|
||
|
<p>If an application doesn't set its own security callback the default
|
||
|
callback is used. It is intended to provide sane defaults. The meaning
|
||
|
of each level is described below.</p>
|
||
|
<dl>
|
||
|
<dt><strong><a name="level_0" class="item"><strong>Level 0</strong></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>Everything is permitted. This retains compatibility with previous versions of
|
||
|
OpenSSL.</p>
|
||
|
</dd>
|
||
|
<dt><strong><a name="level_1" class="item"><strong>Level 1</strong></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>The security level corresponds to a minimum of 80 bits of security. Any
|
||
|
parameters offering below 80 bits of security are excluded. As a result RSA,
|
||
|
DSA and DH keys shorter than 1024 bits and ECC keys shorter than 160 bits
|
||
|
are prohibited. All export cipher suites are prohibited since they all offer
|
||
|
less than 80 bits of security. SSL version 2 is prohibited. Any cipher suite
|
||
|
using MD5 for the MAC is also prohibited.</p>
|
||
|
</dd>
|
||
|
<dt><strong><a name="level_2" class="item"><strong>Level 2</strong></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>Security level set to 112 bits of security. As a result RSA, DSA and DH keys
|
||
|
shorter than 2048 bits and ECC keys shorter than 224 bits are prohibited.
|
||
|
In addition to the level 1 exclusions any cipher suite using RC4 is also
|
||
|
prohibited. SSL version 3 is also not allowed. Compression is disabled.</p>
|
||
|
</dd>
|
||
|
<dt><strong><a name="level_3" class="item"><strong>Level 3</strong></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>Security level set to 128 bits of security. As a result RSA, DSA and DH keys
|
||
|
shorter than 3072 bits and ECC keys shorter than 256 bits are prohibited.
|
||
|
In addition to the level 2 exclusions cipher suites not offering forward
|
||
|
secrecy are prohibited. TLS versions below 1.1 are not permitted. Session
|
||
|
tickets are disabled.</p>
|
||
|
</dd>
|
||
|
<dt><strong><a name="level_4" class="item"><strong>Level 4</strong></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>Security level set to 192 bits of security. As a result RSA, DSA and
|
||
|
DH keys shorter than 7680 bits and ECC keys shorter than 384 bits are
|
||
|
prohibited. Cipher suites using SHA1 for the MAC are prohibited. TLS
|
||
|
versions below 1.2 are not permitted.</p>
|
||
|
</dd>
|
||
|
<dt><strong><a name="level_5" class="item"><strong>Level 5</strong></a></strong></dt>
|
||
|
|
||
|
<dd>
|
||
|
<p>Security level set to 256 bits of security. As a result RSA, DSA and DH keys
|
||
|
shorter than 15360 bits and ECC keys shorter than 512 bits are prohibited.</p>
|
||
|
</dd>
|
||
|
</dl>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="application_defined_security_callbacks">APPLICATION DEFINED SECURITY CALLBACKS</a></h1>
|
||
|
<p><em>Documentation to be provided.</em></p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="notes">NOTES</a></h1>
|
||
|
<p><strong>WARNING</strong> at this time setting the security level higher than 1 for
|
||
|
general internet use is likely to cause <strong>considerable</strong> interoperability
|
||
|
issues and is not recommended. This is because the <strong>SHA1</strong> algorithm
|
||
|
is very widely used in certificates and will be rejected at levels
|
||
|
higher than 1 because it only offers 80 bits of security.</p>
|
||
|
<p>The default security level can be configured when OpenSSL is compiled by
|
||
|
setting <strong>-DOPENSSL_TLS_SECURITY_LEVEL=level</strong>. If not set then 1 is used.</p>
|
||
|
<p>The security framework disables or reject parameters inconsistent with the
|
||
|
set security level. In the past this was difficult as applications had to set
|
||
|
a number of distinct parameters (supported ciphers, supported curves supported
|
||
|
signature algorithms) to achieve this end and some cases (DH parameter size
|
||
|
for example) could not be checked at all.</p>
|
||
|
<p>By setting an appropriate security level much of this complexity can be
|
||
|
avoided.</p>
|
||
|
<p>The bits of security limits affect all relevant parameters including
|
||
|
cipher suite encryption algorithms, supported ECC curves, supported
|
||
|
signature algorithms, DH parameter sizes, certificate key sizes and
|
||
|
signature algorithms. This limit applies no matter what other custom
|
||
|
settings an application has set: so if the cipher suite is set to <strong>ALL</strong>
|
||
|
then only cipher suites consistent with the security level are permissible.</p>
|
||
|
<p>See SP800-57 for how the security limits are related to individual
|
||
|
algorithms.</p>
|
||
|
<p>Some security levels require large key sizes for non-ECC public key
|
||
|
algorithms which can severely degrade performance. For example 256 bits
|
||
|
of security requires the use of RSA keys of at least 15360 bits in size.</p>
|
||
|
<p>Some restrictions can be gracefully handled: for example cipher suites
|
||
|
offering insufficient security are not sent by the client and will not
|
||
|
be selected by the server. Other restrictions such as the peer certificate
|
||
|
key size or the DH parameter size will abort the handshake with a fatal
|
||
|
alert.</p>
|
||
|
<p>Attempts to set certificates or parameters with insufficient security are
|
||
|
also blocked. For example trying to set a certificate using a 512 bit RSA
|
||
|
key using <code>SSL_CTX_use_certificate()</code> at level 1. Applications which do not
|
||
|
check the return values for errors will misbehave: for example it might
|
||
|
appear that a certificate is not set at all because it had been rejected.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="return_values">RETURN VALUES</a></h1>
|
||
|
<p><code>SSL_CTX_set_security_level()</code> and <code>SSL_set_security_level()</code> do not return values.</p>
|
||
|
<p><code>SSL_CTX_get_security_level()</code> and <code>SSL_get_security_level()</code> return a integer that
|
||
|
represents the security level with <strong>SSL_CTX</strong> or <strong>SSL</strong>, respectively.</p>
|
||
|
<p><code>SSL_CTX_set_security_callback()</code> and <code>SSL_set_security_callback()</code> do not return
|
||
|
values.</p>
|
||
|
<p><code>SSL_CTX_get_security_callback()</code> and <code>SSL_get_security_callback()</code> return the pointer
|
||
|
to the security callback or NULL if the callback is not set.</p>
|
||
|
<p>SSL_CTX_get0_security_ex_data() and SSL_get0_security_ex_data() return the extra
|
||
|
data pointer or NULL if the ex data is not set.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
||
|
<p><em>ssl(7)</em></p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="history">HISTORY</a></h1>
|
||
|
<p>These functions were added in OpenSSL 1.1.0.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
||
|
<p>Copyright 2014-2018 The OpenSSL Project Authors. All Rights Reserved.</p>
|
||
|
<p>Licensed under the Apache License 2.0 (the "License"). You may not use
|
||
|
this file except in compliance with the License. You can obtain a copy
|
||
|
in the file LICENSE in the source distribution or at
|
||
|
<a href="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</a>.</p>
|
||
|
|
||
|
</body>
|
||
|
|
||
|
</html>
|