Add initial security framework docs.

2 files changed, 157 insertions, 4 deletions

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 <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