From: Dr. Stephen Henson Date: Fri, 28 Mar 2014 16:40:56 +0000 (+0000) Subject: Add initial security framework docs. X-Git-Tag: master-post-reformat~886 X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=commitdiff_plain;h=0f817d3b2705f315f4c8c22b5dfee0218848f37a Add initial security framework docs. --- diff --git a/doc/apps/ciphers.pod b/doc/apps/ciphers.pod index 900f49542f..8a1cf5add1 100644 --- a/doc/apps/ciphers.pod +++ b/doc/apps/ciphers.pod @@ -7,6 +7,7 @@ ciphers - SSL cipher display and cipher list tool. =head1 SYNOPSIS B B +[B<-s>] [B<-v>] [B<-V>] [B<-ssl2>] @@ -25,6 +26,12 @@ the appropriate cipherlist. =over 4 +=item B<-s> + +Only list supported ciphers: those consistent with the security level. This +is the actual cipher list an application will support. If this option is +not used then ciphers excluded by the security level will still be listed. + =item B<-v> Verbose option. List ciphers with a complete description of @@ -104,8 +111,11 @@ as a list of ciphers to be appended to the current preference list. If the list includes any ciphers already present they will be ignored: that is they will not moved to the end of the list. -Additionally the cipher string B<@STRENGTH> can be used at any point to sort -the current cipher list in order of encryption algorithm key length. +The cipher string B<@STRENGTH> can be used at any point to sort the current +cipher list in order of encryption algorithm key length. + +The cipher string B<@SECLEVEL=n> can be used at any point to set the security +level to B. =head1 CIPHER STRINGS @@ -585,6 +595,10 @@ encryption. openssl ciphers -v 'RSA:!COMPLEMENTOFALL' +Set security level to 2 and display all ciphers consistent with level 2: + + openssl ciphers -v 'ALL:@SECLEVEL=2' + =head1 SEE ALSO L, L, L diff --git a/doc/ssl/SSL_CTX_set_cipher_list.pod b/doc/ssl/SSL_CTX_set_cipher_list.pod index 7667661a84..c2c349f65e 100644 --- a/doc/ssl/SSL_CTX_set_cipher_list.pod +++ b/doc/ssl/SSL_CTX_set_cipher_list.pod @@ -31,10 +31,10 @@ at all. It should be noted, that inclusion of a cipher to be used into the list is a necessary condition. On the client side, the inclusion into the list is -also sufficient. On the server side, additional restrictions apply. All ciphers -have additional requirements. ADH ciphers don't need a certificate, but -DH-parameters must have been set. All other ciphers need a corresponding -certificate and key. +also sufficient unless the security level excludes it. On the server side, +additional restrictions apply. All ciphers have additional requirements. +ADH ciphers don't need a certificate, but DH-parameters must have been set. +All other ciphers need a corresponding certificate and key. A RSA cipher can only be chosen, when a RSA certificate is available. RSA export ciphers with a keylength of 512 bits for the RSA key require 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 + + 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. 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 or B. 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 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 + +Everything is permitted. This retains compatibility with previous versions of +OpenSSL. + +=item B + +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 + +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 + +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 + +Security level set to 192 bits of security. TLS versions below 1.2 are not +permitted. + +=item B + +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 +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