diff options
author | Dr. Stephen Henson <steve@openssl.org> | 2014-07-03 21:31:51 +0100 |
---|---|---|
committer | Dr. Stephen Henson <steve@openssl.org> | 2014-07-03 21:31:51 +0100 |
commit | a4dde824231befe5e2defffb2942e1faab631748 (patch) | |
tree | 730a0a2473ba82d54954a029ff2871991788236d | |
parent | eba0aa995d4354ab9e35206e683b9abf4ab67b04 (diff) |
More doc fixes.
-rw-r--r-- | doc/apps/s_client.pod | 6 | ||||
-rw-r--r-- | doc/apps/verify.pod | 7 | ||||
-rw-r--r-- | doc/ssl/SSL_CTX_set_cert_cb.pod | 68 | ||||
-rw-r--r-- | doc/ssl/SSL_CTX_set_security_level.pod | 164 |
4 files changed, 1 insertions, 244 deletions
diff --git a/doc/apps/s_client.pod b/doc/apps/s_client.pod index a623b8c78b..96307a9dfe 100644 --- a/doc/apps/s_client.pod +++ b/doc/apps/s_client.pod @@ -17,7 +17,6 @@ B<openssl> B<s_client> [B<-pass arg>] [B<-CApath directory>] [B<-CAfile filename>] -[B<-trusted_first>] [B<-attime timestamp>] [B<-check_ss_sig>] [B<-crl_check>] @@ -31,7 +30,6 @@ B<openssl> B<s_client> [B<-policy_check>] [B<-policy_print>] [B<-purpose purpose>] -[B<-trusted_first>] [B<-use_deltas>] [B<-verify_depth num>] [B<-x509_strict>] @@ -129,9 +127,7 @@ and to use when attempting to build the client certificate chain. B<explicit_policy>, B<-ignore_critical>, B<-inhibit_any>, B<-inhibit_map>, B<-issuer_checks>, B<-policy>, B<-policy_check>, B<-policy_print>, B<-purpose>, -B<-trusted_first>, B<-use_deltas>, -B<-verify_depth>, -B<-x509_strict> +B<-use_deltas>, B<-verify_depth>, B<-x509_strict> Set various certificate chain valiadition options. See the L<B<verify>|verify(1)> manual page for details. diff --git a/doc/apps/verify.pod b/doc/apps/verify.pod index 8a3cc6a15a..ec173ef0b9 100644 --- a/doc/apps/verify.pod +++ b/doc/apps/verify.pod @@ -23,7 +23,6 @@ B<openssl> B<verify> [B<-policy_check>] [B<-policy_print>] [B<-purpose purpose>] -[B<-trusted_first>] [B<-untrusted file>] [B<-use_deltas>] [B<-verbose>] @@ -127,12 +126,6 @@ Currently accepted uses are B<sslclient>, B<sslserver>, B<nssslserver>, B<smimesign>, B<smimeencrypt>. See the B<VERIFY OPERATION> section for more information. -=item B<-trusted_first> - -Use certificates in CA file or CA directory before certificates in untrusted -file when building the trust chain to verify certificates. -This is mainly useful in environments with Bridge CA or Cross-Certified CAs. - =item B<-untrusted file> A file of untrusted certificates. The file should contain multiple certificates diff --git a/doc/ssl/SSL_CTX_set_cert_cb.pod b/doc/ssl/SSL_CTX_set_cert_cb.pod deleted file mode 100644 index 141d828f5b..0000000000 --- a/doc/ssl/SSL_CTX_set_cert_cb.pod +++ /dev/null @@ -1,68 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_cert_cb, SSL_set_cert_cb - handle certificate callback function - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void SSL_CTX_set_cert_cb(SSL_CTX *c, int (*cert_cb)(SSL *ssl, void *arg), void *arg); - void SSL_set_cert_cb(SSL *s, int (*cert_cb)(SSL *ssl, void *arg), void *arg); - - int (*cert_cb)(SSL *ssl, void *arg); - -=head1 DESCRIPTION - -SSL_CTX_set_cert_cb() and SSL_set_cert_cb() sets the B<cert_cb()> callback, -B<arg> value is pointer which is passed to the application callback. - -When B<cert_cb()> is NULL, no callback function is used. - -cert_cb() is the application defined callback. It is called before a -certificate will be used by a client or server. The callback can then inspect -the passed B<ssl> structure and set or clear any appropriate certificates. If -the callback is successful it B<MUST> return 1 even if no certificates have -been set. A zero is returned on error which will abort the handshake with a -fatal internal error alert. A negative return value will suspend the handshake -and the handshake function will return immediately. -L<SSL_get_error(3)|SSL_get_error(3)> will return SSL_ERROR_WANT_X509_LOOKUP to -indicate, that the handshake was suspended. The next call to the handshake -function will again lead to the call of cert_cb(). It is the job of the -cert_cb() to store information about the state of the last call, -if required to continue. - -=head1 NOTES - -An application will typically call SSL_use_certificate() and -SSL_use_PrivateKey() to set the end entity certificate and private key. -It can add intermediate and optionally the root CA certificates using -SSL_add1_chain_cert(). - -It might also call SSL_certs_clear() to delete any certificates associated -with the B<SSL> object. - -The certificate callback functionality supercedes the (largely broken) -functionality provided by the old client certificate callback interface. -It is B<always> called even is a certificate is already set so the callback -can modify or delete the existing certificate. - -A more advanced callback might examine the handshake parameters and set -whatever chain is appropriate. For example a legacy client supporting only -TLS v1.0 might receive a certificate chain signed using SHA1 whereas a -TLS v1.2 client which advertises support for SHA256 could receive a chain -using SHA256. - -Normal server sanity checks are performed on any certificates set -by the callback. So if an EC chain is set for a curve the client does not -support it will B<not> be used. - -=head1 SEE ALSO - -L<ssl(3)|ssl(3)>, L<SSL_use_certificate(3)|SSL_use_certificate(3)>, -L<SSL_add1_chain_cert(3)|SSL_add1_chain_cert(3)>, -L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>, -L<SSL_clear(3)|SSL_clear(3)>, L<SSL_free(3)|SSL_free(3)> - -=cut diff --git a/doc/ssl/SSL_CTX_set_security_level.pod b/doc/ssl/SSL_CTX_set_security_level.pod deleted file mode 100644 index d7d1429b25..0000000000 --- a/doc/ssl/SSL_CTX_set_security_level.pod +++ /dev/null @@ -1,164 +0,0 @@ -=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 corresponds to a minimum of 80 bits of security. Any -parameters offering below 80 bits of security are excluded. As a result RSA, -DSA and DH keys shorter than 1024 bits and ECC keys shorter than 160 bits -are prohibited. All export ciphersuites are prohibited since they all offer -less than 80 bits of security. 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. As a result RSA, DSA and DH keys -shorter than 2048 bits and ECC keys shorter than 224 bits are prohibited. -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> - -Security level set to 128 bits of security. As a result RSA, DSA and DH keys -shorter than 3072 bits and ECC keys shorter than 256 bits are prohibited. -In addition to the level 2 exclusions ciphersuites 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. As a result RSA, DSA and DH keys -shorter than 7680 bits and ECC keys shorter than 384 bits are prohibited. -Ciphersuites using SHA1 for the MAC are prohibited. TLS versions below 1.2 are -not permitted. - -=item B<Level 5> - -Security level set to 256 bits of security. As a result RSA, DSA and DH keys -shorter than 15360 bits and ECC keys shorter than 512 bits are prohibited. - -=back - -=head1 APPLICATION DEFINED SECURITY CALLBACKS - -TBA - -=head1 NOTES - -B<WARNING> at this time setting the security level higher than 1 for -general internet use is likely to cause B<considerable> interoperability -issues and is not recommended. This is because the B<SHA1> algorithm -is very widely used in certificates and will be rejected at levels -higher than 1 because it only offers 80 bits of security. - -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. - -Some security levels require large key sizes for none-ECC public key -algorithms which can severely degrade performance. 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: for example it might -appear that a certificate is not set at all because it had been rejected. - -=head1 SEE ALSO - -TBA - -=head1 HISTORY - -These functions were first added to OpenSSL 1.1.0 - -=cut |