diff options
author | Dr. Stephen Henson <steve@openssl.org> | 2014-03-28 16:40:56 +0000 |
---|---|---|
committer | Dr. Stephen Henson <steve@openssl.org> | 2014-03-28 16:42:18 +0000 |
commit | 0f817d3b2705f315f4c8c22b5dfee0218848f37a (patch) | |
tree | c60a8256aafb3de79ce032848041ab0432c4e9b0 /doc/ssl/SSL_CTX_set_security_level.pod | |
parent | 21e0c1d23afff48601eb93135defddae51f7e2e3 (diff) |
Add initial security framework docs.
Diffstat (limited to 'doc/ssl/SSL_CTX_set_security_level.pod')
-rw-r--r-- | doc/ssl/SSL_CTX_set_security_level.pod | 153 |
1 files changed, 153 insertions, 0 deletions
diff --git a/doc/ssl/SSL_CTX_set_security_level.pod b/doc/ssl/SSL_CTX_set_security_level.pod new file mode 100644 index 0000000000..b5b7f0623f --- /dev/null +++ b/doc/ssl/SSL_CTX_set_security_level.pod @@ -0,0 +1,153 @@ +=pod + +=head1 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 + +=head1 SYNOPSIS + + #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); + +=head1 DESCRIPTION + +The functions SSL_CTX_set_security_level() and SSL_set_security_level() set +the security level to B<level>. If not set the libary default security level +is used. + +The functions SSL_CTX_get_security_level() and SSL_get_security_level() +retrieve the current security level. + +SSL_CTX_set_security_callback(), SSL_set_security_callback(), +SSL_CTX_get_security_callback() and SSL_get_security_callback() get or set +the security callback associated with B<ctx> or B<s>. If not set a default +security callback is used. The meaning of the parameters and the behaviour +of the default callbacks is described below. + +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 B<ex> parameter of the callback. This +value is passed to the callback verbatim and can be set to any convenient +application specific value. + +=head1 DEFAULT CALLBACK BEHAVIOUR + +If an application doesn't set it's own security callback the default +callback is used. It is intended to provide sane defaults. The meaning +of each level is described below. + +=over 4 + +=item B<Level 0> + +Everything is permitted. This retains compatibility with previous versions of +OpenSSL. + +=item B<Level 1> + +The security level set to 80 bits of security. Any parameters offering +below 80 bits of security are excluded. As a result all export ciphersuites +are prohibited. SSL version 2 is prohibited. Any ciphersuite using MD5 for +the MAC is also prohibited. + +=item B<Level 2> + +Security level set to 112 bits of security. In addition to the level 1 +exclusions any ciphersuite using RC4 is also prohibited. SSL version +3 is also not allowed. Compression is disabled. + +=item B<Level 3> + +Ssecurity level set to 128 bits of security. In addition to the level 2 +exclusions any ciphersuite not offering forward secrecy are prohibited. +TLS versions below 1.1 are not permitted. Session tickets are disabled. + +=item B<Level 4> + +Security level set to 192 bits of security. TLS versions below 1.2 are not +permitted. + +=item B<Level 5> + +Security level set to 256 bits of security. + +=back + +=head1 APPLICATION DEFINED SECURITY CALLBACKS + +TBA + +=head1 NOTES + +The default security level can be configured when OpenSSL is compiled by +setting B<-DOPENSSL_TLS_SECURITY_LEVEL=level>. If not set then 1 is used. + +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. + +By setting an appropriate security level much of this complexity can be +avoided. + +The bits of security limits affect all relevant parameters including +ciphersuite 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 ciphersuite is set to B<ALL> +then only ciphersuites consistent with the security level are permissible. + +See SP800-57 for how the security limits are related to individual +algorithms. + +SHA1 is in widespread use in certificates but it only offers 80 bits +of security. This is problematic as anything above level 1 will reject +them. + +Some security levels require large key sizes for none-ECC public key +algorithms. For example 256 bits of security requires the use of RSA +keys of at least 15360 bits in size. + +Some restrictions can be gracefully handled: for example ciphersuites +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 pameter size will abort the handshake with a fatal +alert. + +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 SSL_CTX_use_certificate() at level 1. Applications which do not +check the return values for errors will misbehave. + +=head1 SEE ALSO + +TBA + +=head1 HISTORY + +These functions were first added to OpenSSL 1.1.0 + +=cut |