306 lines
12 KiB
Groff
306 lines
12 KiB
Groff
|
.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
|
||
|
|
.\"
|
||
|
|
.\" Standard preamble:
|
||
|
|
.\" ========================================================================
|
||
|
|
.de Sp \" Vertical space (when we can't use .PP)
|
||
|
|
.if t .sp .5v
|
||
|
|
.if n .sp
|
||
|
|
..
|
||
|
|
.de Vb \" Begin verbatim text
|
||
|
|
.ft CW
|
||
|
|
.nf
|
||
|
|
.ne \\$1
|
||
|
|
..
|
||
|
|
.de Ve \" End verbatim text
|
||
|
|
.ft R
|
||
|
|
.fi
|
||
|
|
..
|
||
|
|
.\" Set up some character translations and predefined strings. \*(-- will
|
||
|
|
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
|
||
|
|
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
|
||
|
|
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
|
||
|
|
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
|
||
|
|
.\" nothing in troff, for use with C<>.
|
||
|
|
.tr \(*W-
|
||
|
|
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
||
|
|
.ie n \{\
|
||
|
|
. ds -- \(*W-
|
||
|
|
. ds PI pi
|
||
|
|
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
|
||
|
|
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
|
||
|
|
. ds L" ""
|
||
|
|
. ds R" ""
|
||
|
|
. ds C` ""
|
||
|
|
. ds C' ""
|
||
|
|
'br\}
|
||
|
|
.el\{\
|
||
|
|
. ds -- \|\(em\|
|
||
|
|
. ds PI \(*p
|
||
|
|
. ds L" ``
|
||
|
|
. ds R" ''
|
||
|
|
. ds C`
|
||
|
|
. ds C'
|
||
|
|
'br\}
|
||
|
|
.\"
|
||
|
|
.\" Escape single quotes in literal strings from groff's Unicode transform.
|
||
|
|
.ie \n(.g .ds Aq \(aq
|
||
|
|
.el .ds Aq '
|
||
|
|
.\"
|
||
|
|
.\" If the F register is >0, we'll generate index entries on stderr for
|
||
|
|
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
|
||
|
|
.\" entries marked with X<> in POD. Of course, you'll have to process the
|
||
|
|
.\" output yourself in some meaningful fashion.
|
||
|
|
.\"
|
||
|
|
.\" Avoid warning from groff about undefined register 'F'.
|
||
|
|
.de IX
|
||
|
|
..
|
||
|
|
.if !\nF .nr F 0
|
||
|
|
.if \nF>0 \{\
|
||
|
|
. de IX
|
||
|
|
. tm Index:\\$1\t\\n%\t"\\$2"
|
||
|
|
..
|
||
|
|
. if !\nF==2 \{\
|
||
|
|
. nr % 0
|
||
|
|
. nr F 2
|
||
|
|
. \}
|
||
|
|
.\}
|
||
|
|
.\"
|
||
|
|
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
|
||
|
|
.\" Fear. Run. Save yourself. No user-serviceable parts.
|
||
|
|
. \" fudge factors for nroff and troff
|
||
|
|
.if n \{\
|
||
|
|
. ds #H 0
|
||
|
|
. ds #V .8m
|
||
|
|
. ds #F .3m
|
||
|
|
. ds #[ \f1
|
||
|
|
. ds #] \fP
|
||
|
|
.\}
|
||
|
|
.if t \{\
|
||
|
|
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
|
||
|
|
. ds #V .6m
|
||
|
|
. ds #F 0
|
||
|
|
. ds #[ \&
|
||
|
|
. ds #] \&
|
||
|
|
.\}
|
||
|
|
. \" simple accents for nroff and troff
|
||
|
|
.if n \{\
|
||
|
|
. ds ' \&
|
||
|
|
. ds ` \&
|
||
|
|
. ds ^ \&
|
||
|
|
. ds , \&
|
||
|
|
. ds ~ ~
|
||
|
|
. ds /
|
||
|
|
.\}
|
||
|
|
.if t \{\
|
||
|
|
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
|
||
|
|
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
|
||
|
|
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
|
||
|
|
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
|
||
|
|
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
|
||
|
|
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
|
||
|
|
.\}
|
||
|
|
. \" troff and (daisy-wheel) nroff accents
|
||
|
|
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
|
||
|
|
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
|
||
|
|
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
|
||
|
|
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
|
||
|
|
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
|
||
|
|
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
|
||
|
|
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
|
||
|
|
.ds ae a\h'-(\w'a'u*4/10)'e
|
||
|
|
.ds Ae A\h'-(\w'A'u*4/10)'E
|
||
|
|
. \" corrections for vroff
|
||
|
|
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
|
||
|
|
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
|
||
|
|
. \" for low resolution devices (crt and lpr)
|
||
|
|
.if \n(.H>23 .if \n(.V>19 \
|
||
|
|
\{\
|
||
|
|
. ds : e
|
||
|
|
. ds 8 ss
|
||
|
|
. ds o a
|
||
|
|
. ds d- d\h'-1'\(ga
|
||
|
|
. ds D- D\h'-1'\(hy
|
||
|
|
. ds th \o'bp'
|
||
|
|
. ds Th \o'LP'
|
||
|
|
. ds ae ae
|
||
|
|
. ds Ae AE
|
||
|
|
.\}
|
||
|
|
.rm #[ #] #H #V #F C
|
||
|
|
.\" ========================================================================
|
||
|
|
.\"
|
||
|
|
.IX Title "SSL_CTX_SET_SECURITY_LEVEL 3"
|
||
|
|
.TH SSL_CTX_SET_SECURITY_LEVEL 3 "2018-11-20" "1.1.1a" "OpenSSL"
|
||
|
|
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
|
||
|
|
.\" way too many mistakes in technical documents.
|
||
|
|
.if n .ad l
|
||
|
|
.nh
|
||
|
|
.SH "NAME"
|
||
|
|
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
|
||
|
|
.SH "SYNOPSIS"
|
||
|
|
.IX Header "SYNOPSIS"
|
||
|
|
.Vb 1
|
||
|
|
\& #include <openssl/ssl.h>
|
||
|
|
\&
|
||
|
|
\& void SSL_CTX_set_security_level(SSL_CTX *ctx, int level);
|
||
|
|
\& void SSL_set_security_level(SSL *s, int level);
|
||
|
|
\&
|
||
|
|
\& int SSL_CTX_get_security_level(const SSL_CTX *ctx);
|
||
|
|
\& int SSL_get_security_level(const SSL *s);
|
||
|
|
\&
|
||
|
|
\& 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));
|
||
|
|
\&
|
||
|
|
\& void SSL_set_security_callback(SSL *s, int (*cb)(SSL *s, SSL_CTX *ctx, int op,
|
||
|
|
\& int bits, int nid,
|
||
|
|
\& void *other, void *ex));
|
||
|
|
\&
|
||
|
|
\& 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);
|
||
|
|
\&
|
||
|
|
\& void SSL_CTX_set0_security_ex_data(SSL_CTX *ctx, void *ex);
|
||
|
|
\& void SSL_set0_security_ex_data(SSL *s, void *ex);
|
||
|
|
\&
|
||
|
|
\& void *SSL_CTX_get0_security_ex_data(const SSL_CTX *ctx);
|
||
|
|
\& void *SSL_get0_security_ex_data(const SSL *s);
|
||
|
|
.Ve
|
||
|
|
.SH "DESCRIPTION"
|
||
|
|
.IX Header "DESCRIPTION"
|
||
|
|
The functions \fISSL_CTX_set_security_level()\fR and \fISSL_set_security_level()\fR set
|
||
|
|
the security level to \fBlevel\fR. If not set the library default security level
|
||
|
|
is used.
|
||
|
|
.PP
|
||
|
|
The functions \fISSL_CTX_get_security_level()\fR and \fISSL_get_security_level()\fR
|
||
|
|
retrieve the current security level.
|
||
|
|
.PP
|
||
|
|
\&\fISSL_CTX_set_security_callback()\fR, \fISSL_set_security_callback()\fR,
|
||
|
|
\&\fISSL_CTX_get_security_callback()\fR and \fISSL_get_security_callback()\fR get or set
|
||
|
|
the security callback associated with \fBctx\fR or \fBs\fR. If not set a default
|
||
|
|
security callback is used. The meaning of the parameters and the behaviour
|
||
|
|
of the default callbacks is described below.
|
||
|
|
.PP
|
||
|
|
\&\fISSL_CTX_set0_security_ex_data()\fR, \fISSL_set0_security_ex_data()\fR,
|
||
|
|
\&\fISSL_CTX_get0_security_ex_data()\fR and \fISSL_get0_security_ex_data()\fR set the
|
||
|
|
extra data pointer passed to the \fBex\fR parameter of the callback. This
|
||
|
|
value is passed to the callback verbatim and can be set to any convenient
|
||
|
|
application specific value.
|
||
|
|
.SH "DEFAULT CALLBACK BEHAVIOUR"
|
||
|
|
.IX Header "DEFAULT CALLBACK BEHAVIOUR"
|
||
|
|
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.
|
||
|
|
.IP "\fBLevel 0\fR" 4
|
||
|
|
.IX Item "Level 0"
|
||
|
|
Everything is permitted. This retains compatibility with previous versions of
|
||
|
|
OpenSSL.
|
||
|
|
.IP "\fBLevel 1\fR" 4
|
||
|
|
.IX Item "Level 1"
|
||
|
|
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 \s-1RSA,
|
||
|
|
DSA\s0 and \s-1DH\s0 keys shorter than 1024 bits and \s-1ECC\s0 keys shorter than 160 bits
|
||
|
|
are prohibited. All export cipher suites are prohibited since they all offer
|
||
|
|
less than 80 bits of security. \s-1SSL\s0 version 2 is prohibited. Any cipher suite
|
||
|
|
using \s-1MD5\s0 for the \s-1MAC\s0 is also prohibited.
|
||
|
|
.IP "\fBLevel 2\fR" 4
|
||
|
|
.IX Item "Level 2"
|
||
|
|
Security level set to 112 bits of security. As a result \s-1RSA, DSA\s0 and \s-1DH\s0 keys
|
||
|
|
shorter than 2048 bits and \s-1ECC\s0 keys shorter than 224 bits are prohibited.
|
||
|
|
In addition to the level 1 exclusions any cipher suite using \s-1RC4\s0 is also
|
||
|
|
prohibited. \s-1SSL\s0 version 3 is also not allowed. Compression is disabled.
|
||
|
|
.IP "\fBLevel 3\fR" 4
|
||
|
|
.IX Item "Level 3"
|
||
|
|
Security level set to 128 bits of security. As a result \s-1RSA, DSA\s0 and \s-1DH\s0 keys
|
||
|
|
shorter than 3072 bits and \s-1ECC\s0 keys shorter than 256 bits are prohibited.
|
||
|
|
In addition to the level 2 exclusions cipher suites not offering forward
|
||
|
|
secrecy are prohibited. \s-1TLS\s0 versions below 1.1 are not permitted. Session
|
||
|
|
tickets are disabled.
|
||
|
|
.IP "\fBLevel 4\fR" 4
|
||
|
|
.IX Item "Level 4"
|
||
|
|
Security level set to 192 bits of security. As a result \s-1RSA, DSA\s0 and
|
||
|
|
\&\s-1DH\s0 keys shorter than 7680 bits and \s-1ECC\s0 keys shorter than 384 bits are
|
||
|
|
prohibited. Cipher suites using \s-1SHA1\s0 for the \s-1MAC\s0 are prohibited. \s-1TLS\s0
|
||
|
|
versions below 1.2 are not permitted.
|
||
|
|
.IP "\fBLevel 5\fR" 4
|
||
|
|
.IX Item "Level 5"
|
||
|
|
Security level set to 256 bits of security. As a result \s-1RSA, DSA\s0 and \s-1DH\s0 keys
|
||
|
|
shorter than 15360 bits and \s-1ECC\s0 keys shorter than 512 bits are prohibited.
|
||
|
|
.SH "APPLICATION DEFINED SECURITY CALLBACKS"
|
||
|
|
.IX Header "APPLICATION DEFINED SECURITY CALLBACKS"
|
||
|
|
\&\fIDocumentation to be provided.\fR
|
||
|
|
.SH "NOTES"
|
||
|
|
.IX Header "NOTES"
|
||
|
|
\&\fB\s-1WARNING\s0\fR at this time setting the security level higher than 1 for
|
||
|
|
general internet use is likely to cause \fBconsiderable\fR interoperability
|
||
|
|
issues and is not recommended. This is because the \fB\s-1SHA1\s0\fR algorithm
|
||
|
|
is very widely used in certificates and will be rejected at levels
|
||
|
|
higher than 1 because it only offers 80 bits of security.
|
||
|
|
.PP
|
||
|
|
The default security level can be configured when OpenSSL is compiled by
|
||
|
|
setting \fB\-DOPENSSL_TLS_SECURITY_LEVEL=level\fR. If not set then 1 is used.
|
||
|
|
.PP
|
||
|
|
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 (\s-1DH\s0 parameter size
|
||
|
|
for example) could not be checked at all.
|
||
|
|
.PP
|
||
|
|
By setting an appropriate security level much of this complexity can be
|
||
|
|
avoided.
|
||
|
|
.PP
|
||
|
|
The bits of security limits affect all relevant parameters including
|
||
|
|
cipher suite encryption algorithms, supported \s-1ECC\s0 curves, supported
|
||
|
|
signature algorithms, \s-1DH\s0 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 \fB\s-1ALL\s0\fR
|
||
|
|
then only cipher suites consistent with the security level are permissible.
|
||
|
|
.PP
|
||
|
|
See \s-1SP800\-57\s0 for how the security limits are related to individual
|
||
|
|
algorithms.
|
||
|
|
.PP
|
||
|
|
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 \s-1RSA\s0 keys of at least 15360 bits in size.
|
||
|
|
.PP
|
||
|
|
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 \s-1DH\s0 parameter size will abort the handshake with a fatal
|
||
|
|
alert.
|
||
|
|
.PP
|
||
|
|
Attempts to set certificates or parameters with insufficient security are
|
||
|
|
also blocked. For example trying to set a certificate using a 512 bit \s-1RSA\s0
|
||
|
|
key using \fISSL_CTX_use_certificate()\fR 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.
|
||
|
|
.SH "RETURN VALUES"
|
||
|
|
.IX Header "RETURN VALUES"
|
||
|
|
\&\fISSL_CTX_set_security_level()\fR and \fISSL_set_security_level()\fR do not return values.
|
||
|
|
.PP
|
||
|
|
\&\fISSL_CTX_get_security_level()\fR and \fISSL_get_security_level()\fR return a integer that
|
||
|
|
represents the security level with \fB\s-1SSL_CTX\s0\fR or \fB\s-1SSL\s0\fR, respectively.
|
||
|
|
.PP
|
||
|
|
\&\fISSL_CTX_set_security_callback()\fR and \fISSL_set_security_callback()\fR do not return
|
||
|
|
values.
|
||
|
|
.PP
|
||
|
|
\&\fISSL_CTX_get_security_callback()\fR and \fISSL_get_security_callback()\fR return the pointer
|
||
|
|
to the security callback or \s-1NULL\s0 if the callback is not set.
|
||
|
|
.PP
|
||
|
|
\&\fISSL_CTX_get0_security_ex_data()\fR and \fISSL_get0_security_ex_data()\fR return the extra
|
||
|
|
data pointer or \s-1NULL\s0 if the ex data is not set.
|
||
|
|
.SH "HISTORY"
|
||
|
|
.IX Header "HISTORY"
|
||
|
|
These functions were first added to OpenSSL 1.1.0
|
||
|
|
.SH "COPYRIGHT"
|
||
|
|
.IX Header "COPYRIGHT"
|
||
|
|
Copyright 2014\-2018 The OpenSSL Project Authors. All Rights Reserved.
|
||
|
|
.PP
|
||
|
|
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
|
||
|
|
this file except in compliance with the License. You can obtain a copy
|
||
|
|
in the file \s-1LICENSE\s0 in the source distribution or at
|
||
|
|
<https://www.openssl.org/source/license.html>.
|