Add initial security framework docs.

diff --git a/doc/apps/ciphers.pod b/doc/apps/ciphers.pod
index 900f49542f0c365c4d89b1f0f0e89843c129d65c..8a1cf5add1f95d9f8dcf15d466c5bf833a0e4897 100644 (file)
--- 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<openssl> B<ciphers>
+[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<n>.
 
 =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<s_client(1)|s_client(1)>, L<s_server(1)|s_server(1)>, L<ssl(3)|ssl(3)>

diff --git a/doc/ssl/SSL_CTX_set_cipher_list.pod b/doc/ssl/SSL_CTX_set_cipher_list.pod
index 7667661a84073461869b1101d64e989d3f4580fb..c2c349f65e7b6c2fea47715f8f8bad111858d31c 100644 (file)
--- 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 (file)
index 0000000..b5b7f06
--- /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