More doc fixes.
This commit is contained in:
Dr. Stephen Henson
parent
eba0aa995d
commit
a4dde82423
4 changed files with 1 additions and 244 deletions
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
Loading…
Reference in a new issue