diff options
author | nectar <nectar@FreeBSD.org> | 2002-07-30 13:38:06 +0000 |
---|---|---|
committer | nectar <nectar@FreeBSD.org> | 2002-07-30 13:38:06 +0000 |
commit | 2f13e0916590f8488178999aec4874ed5662a031 (patch) | |
tree | f3c141823975717e132c7687cf833f6378cc87d4 /crypto/openssl/doc/ssl | |
parent | 0aed2eea83b351d68092e43b5a9496ce3dd5043d (diff) | |
download | FreeBSD-src-2f13e0916590f8488178999aec4874ed5662a031.zip FreeBSD-src-2f13e0916590f8488178999aec4874ed5662a031.tar.gz |
Import of OpenSSL 0.9.6e.
Diffstat (limited to 'crypto/openssl/doc/ssl')
-rw-r--r-- | crypto/openssl/doc/ssl/SSL_CTX_sess_set_cache_size.pod | 4 | ||||
-rw-r--r-- | crypto/openssl/doc/ssl/SSL_CTX_sess_set_get_cb.pod | 2 | ||||
-rw-r--r-- | crypto/openssl/doc/ssl/SSL_CTX_set_cert_store.pod | 2 | ||||
-rw-r--r-- | crypto/openssl/doc/ssl/SSL_CTX_set_client_cert_cb.pod | 50 | ||||
-rw-r--r-- | crypto/openssl/doc/ssl/SSL_CTX_set_options.pod | 19 | ||||
-rw-r--r-- | crypto/openssl/doc/ssl/SSL_accept.pod | 1 | ||||
-rw-r--r-- | crypto/openssl/doc/ssl/SSL_connect.pod | 1 | ||||
-rw-r--r-- | crypto/openssl/doc/ssl/SSL_do_handshake.pod | 75 | ||||
-rw-r--r-- | crypto/openssl/doc/ssl/SSL_get_error.pod | 2 | ||||
-rw-r--r-- | crypto/openssl/doc/ssl/SSL_set_connect_state.pod | 1 | ||||
-rw-r--r-- | crypto/openssl/doc/ssl/SSL_write.pod | 3 | ||||
-rw-r--r-- | crypto/openssl/doc/ssl/ssl.pod | 1 |
12 files changed, 130 insertions, 31 deletions
diff --git a/crypto/openssl/doc/ssl/SSL_CTX_sess_set_cache_size.pod b/crypto/openssl/doc/ssl/SSL_CTX_sess_set_cache_size.pod index d59a7db..c8b99f4 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_sess_set_cache_size.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_sess_set_cache_size.pod @@ -27,7 +27,7 @@ case is the size 0, which is used for unlimited size. When the maximum number of sessions is reached, no more new sessions are added to the cache. New space may be added by calling -L<SSL_CTX_flush_sessions(3)|<SSL_CTX_flush_sessions(3)> to remove +L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> to remove expired sessions. If the size of the session cache is reduced and more sessions are already @@ -46,6 +46,6 @@ SSL_CTX_sess_get_cache_size() returns the currently valid size. L<ssl(3)|ssl(3)>, L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, L<SSL_CTX_sess_number(3)|SSL_CTX_sess_number(3)>, -L<SSL_CTX_flush_sessions(3)|<SSL_CTX_flush_sessions(3)> +L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> =cut diff --git a/crypto/openssl/doc/ssl/SSL_CTX_sess_set_get_cb.pod b/crypto/openssl/doc/ssl/SSL_CTX_sess_set_get_cb.pod index 6e0ef00..7c0b2ba 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_sess_set_get_cb.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_sess_set_get_cb.pod @@ -79,7 +79,7 @@ L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>. L<ssl(3)|ssl(3)>, L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)>, L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>, -L<SSL_CTX_flush_sessions(3)|<SSL_CTX_flush_sessions(3)>, +L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>, L<SSL_SESSION_free(3)|SSL_SESSION_free(3)> =cut diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_cert_store.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_cert_store.pod index 81286ee..3a240c4 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_set_cert_store.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_cert_store.pod @@ -14,7 +14,7 @@ SSL_CTX_set_cert_store, SSL_CTX_get_cert_store - manipulate X509 certificate ver =head1 DESCRIPTION SSL_CTX_set_cert_store() sets/replaces the certificate verification storage -of B<ctx> to/with B<store>. If another X505_STORE object is currently +of B<ctx> to/with B<store>. If another X509_STORE object is currently set in B<ctx>, it will be X509_STORE_free()ed. SSL_CTX_get_cert_store() returns a pointer to the current certificate diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_client_cert_cb.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_client_cert_cb.pod index 53e1827..3465b5c 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_set_client_cert_cb.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_client_cert_cb.pod @@ -15,8 +15,10 @@ SSL_CTX_set_client_cert_cb, SSL_CTX_get_client_cert_cb - handle client certifica =head1 DESCRIPTION SSL_CTX_set_client_cert_cb() sets the B<client_cert_cb()> callback, that is -called when a client certificate is requested by a server. -When B<client_cert_cb()> is NULL, not callback function is used. +called when a client certificate is requested by a server and no certificate +was yet set for the SSL object. + +When B<client_cert_cb()> is NULL, no callback function is used. SSL_CTX_get_client_cert_cb() returns a pointer to the currently set callback function. @@ -25,9 +27,13 @@ client_cert_cb() is the application defined callback. If it wants to set a certificate, a certificate/private key combination must be set using the B<x509> and B<pkey> arguments and "1" must be returned. The certificate will be installed into B<ssl>, see the NOTES and BUGS sections. -If no certificate should be set, "0" has to be returned and the default -certificate will be sent. A fatal error can be indicated by returning -a negative value, in which case the handshake will be canceled. +If no certificate should be set, "0" has to be returned and no certificate +will be sent. A negative return value will suspend the handshake and the +handshake function will return immediatly. 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 client_cert_cb(). It is the job of the client_cert_cb() to store information +about the state of the last call, if required to continue. =head1 NOTES @@ -35,26 +41,24 @@ During a handshake (or renegotiation) a server may request a certificate from the client. A client certificate must only be sent, when the server did send the request. -When no callback function is set, an OpenSSL client will send the certificate -that was set using the -L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)> family of functions. -The TLS standard requires that only a certificate is sent, if it matches -the list of acceptable CAs sent by the server. This constraint is -violated by the default behavior of the OpenSSL library. Using the -callback function it is possible to implement a proper selection routine -or to allow a user interaction to choose the certificate to be sent. -The callback function can obtain the list of acceptable CAs using the -L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)> function. - -If a callback function is defined, the callback function will be called. +When a certificate was set using the +L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)> family of functions, +it will be sent to the server. The TLS standard requires that only a +certificate is sent, if it matches the list of acceptable CAs sent by the +server. This constraint is violated by the default behavior of the OpenSSL +library. Using the callback function it is possible to implement a proper +selection routine or to allow a user interaction to choose the certificate to +be sent. + +If a callback function is defined and no certificate was yet defined for the +SSL object, the callback function will be called. If the callback function returns a certificate, the OpenSSL library will try to load the private key and certificate data into the SSL -object using SSL_use_certificate() and SSL_use_private_key() functions. -Thus it will permanently override the certificate and key previously -installed and will not be reset by calling L<SSL_clear(3)|SSL_clear(3)>. -If the callback returns no certificate, the OpenSSL library will send -the certificate previously installed for the SSL_CTX object or the specific -certificate of the SSL object, if available. +object using the SSL_use_certificate() and SSL_use_private_key() functions. +Thus it will permanently install the certificate and key for this SSL +object. It will not be reset by calling L<SSL_clear(3)|SSL_clear(3)>. +If the callback returns no certificate, the OpenSSL library will not send +a certificate. =head1 BUGS diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_options.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_options.pod index 5842a31..5c07e53 100644 --- a/crypto/openssl/doc/ssl/SSL_CTX_set_options.pod +++ b/crypto/openssl/doc/ssl/SSL_CTX_set_options.pod @@ -35,7 +35,7 @@ operation (|). Options can only be added but can never be reset. SSL_CTX_set_options() and SSL_set_options() affect the (external) protocol behaviour of the SSL library. The (internal) behaviour of the API can be changed by using the similar -L<SSL_CTX_set_modes(3)|SSL_CTX_set_modes(3)> and SSL_set_modes() functions. +L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)> and SSL_set_mode() functions. During a handshake, the option settings of the SSL object are used. When a new SSL object is created from a context using SSL_new(), the current @@ -112,14 +112,22 @@ only understands up to SSLv3. In this case the client must still use the same SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect to the server's answer and violate the version rollback protection.) +=item SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS + +Disables a countermeasure against a SSL 3.0/TLS 1.0 protocol +vulnerability affecting CBC ciphers, which cannot be handled by some +broken SSL implementations. This option has no effect for connections +using other ciphers. + =item SSL_OP_ALL All of the above bug workarounds. =back -It is save and recommended to use SSL_OP_ALL to enable the bug workaround -options. +It is usually safe to use B<SSL_OP_ALL> to enable the bug workaround +options if compatibility with somewhat broken implementations is +desired. The following B<modifying> options are available: @@ -199,4 +207,9 @@ L<dhparam(1)|dhparam(1)> SSL_OP_TLS_ROLLBACK_BUG has been added in OpenSSL 0.9.6. +B<SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS> has been added in OpenSSL 0.9.6e. +Versions up to OpenSSL 0.9.6c do not include the countermeasure that +can be disabled with this option (in OpenSSL 0.9.6d, it was always +enabled). + =cut diff --git a/crypto/openssl/doc/ssl/SSL_accept.pod b/crypto/openssl/doc/ssl/SSL_accept.pod index ac6caf9..a673edb 100644 --- a/crypto/openssl/doc/ssl/SSL_accept.pod +++ b/crypto/openssl/doc/ssl/SSL_accept.pod @@ -69,6 +69,7 @@ to find out the reason. L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_connect(3)|SSL_connect(3)>, L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>, L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>, +L<SSL_do_handshake(3)|SSL_do_handshake(3)>, L<SSL_CTX_new(3)|SSL_CTX_new(3)> =cut diff --git a/crypto/openssl/doc/ssl/SSL_connect.pod b/crypto/openssl/doc/ssl/SSL_connect.pod index 766f187..8426310 100644 --- a/crypto/openssl/doc/ssl/SSL_connect.pod +++ b/crypto/openssl/doc/ssl/SSL_connect.pod @@ -66,6 +66,7 @@ to find out the reason. L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_accept(3)|SSL_accept(3)>, L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>, L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>, +L<SSL_do_handshake(3)|SSL_do_handshake(3)>, L<SSL_CTX_new(3)|SSL_CTX_new(3)> =cut diff --git a/crypto/openssl/doc/ssl/SSL_do_handshake.pod b/crypto/openssl/doc/ssl/SSL_do_handshake.pod new file mode 100644 index 0000000..2435764 --- /dev/null +++ b/crypto/openssl/doc/ssl/SSL_do_handshake.pod @@ -0,0 +1,75 @@ +=pod + +=head1 NAME + +SSL_do_handshake - perform a TLS/SSL handshake + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_do_handshake(SSL *ssl); + +=head1 DESCRIPTION + +SSL_do_handshake() will wait for a SSL/TLS handshake to take place. If the +connection is in client mode, the handshake will be started. The handshake +routines may have to be explicitly set in advance using either +L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> or +L<SSL_set_accept_state(3)|SSL_set_accept_state(3)>. + +=head1 NOTES + +The behaviour of SSL_do_handshake() depends on the underlying BIO. + +If the underlying BIO is B<blocking>, SSL_do_handshake() will only return +once the handshake has been finished or an error occurred, except for SGC +(Server Gated Cryptography). For SGC, SSL_do_handshake() may return with -1, +but SSL_get_error() will yield B<SSL_ERROR_WANT_READ/WRITE> and +SSL_do_handshake() should be called again. + +If the underlying BIO is B<non-blocking>, SSL_do_handshake() will also return +when the underlying BIO could not satisfy the needs of SSL_do_handshake() +to continue the handshake. In this case a call to SSL_get_error() with the +return value of SSL_do_handshake() will yield B<SSL_ERROR_WANT_READ> or +B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after +taking appropriate action to satisfy the needs of SSL_do_handshake(). +The action depends on the underlying BIO. When using a non-blocking socket, +nothing is to be done, but select() can be used to check for the required +condition. When using a buffering BIO, like a BIO pair, data must be written +into or retrieved out of the BIO before being able to continue. + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item 1 + +The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been +established. + +=item 0 + +The TLS/SSL handshake was not successful but was shut down controlled and +by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the +return value B<ret> to find out the reason. + +=item E<lt>0 + +The TLS/SSL handshake was not successful because a fatal error occurred either +at the protocol level or a connection failure occurred. The shutdown was +not clean. It can also occur of action is need to continue the operation +for non-blocking BIOs. Call SSL_get_error() with the return value B<ret> +to find out the reason. + +=back + +=head1 SEE ALSO + +L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_connect(3)|SSL_connect(3)>, +L<SSL_accept(3)|SSL_accept(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>, +L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> + +=cut diff --git a/crypto/openssl/doc/ssl/SSL_get_error.pod b/crypto/openssl/doc/ssl/SSL_get_error.pod index f700bf0..fe28dd9 100644 --- a/crypto/openssl/doc/ssl/SSL_get_error.pod +++ b/crypto/openssl/doc/ssl/SSL_get_error.pod @@ -13,7 +13,7 @@ SSL_get_error - obtain result code for TLS/SSL I/O operation =head1 DESCRIPTION SSL_get_error() returns a result code (suitable for the C "switch" -statement) for a preceding call to SSL_connect(), SSL_accept(), +statement) for a preceding call to SSL_connect(), SSL_accept(), SSL_do_handshake(), SSL_read(), SSL_peek(), or SSL_write() on B<ssl>. The value returned by that TLS/SSL I/O function must be passed to SSL_get_error() in parameter B<ret>. diff --git a/crypto/openssl/doc/ssl/SSL_set_connect_state.pod b/crypto/openssl/doc/ssl/SSL_set_connect_state.pod index 7adf8ad..d88a057 100644 --- a/crypto/openssl/doc/ssl/SSL_set_connect_state.pod +++ b/crypto/openssl/doc/ssl/SSL_set_connect_state.pod @@ -49,6 +49,7 @@ information. L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_CTX_new(3)|SSL_CTX_new(3)>, L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)>, L<SSL_write(3)|SSL_write(3)>, L<SSL_read(3)|SSL_read(3)>, +L<SSL_do_handshake(3)|SSL_do_handshake(3)>, L<SSL_CTX_set_ssl_version(3)|SSL_CTX_set_ssl_version(3)> =cut diff --git a/crypto/openssl/doc/ssl/SSL_write.pod b/crypto/openssl/doc/ssl/SSL_write.pod index dfa42e9..e013c12 100644 --- a/crypto/openssl/doc/ssl/SSL_write.pod +++ b/crypto/openssl/doc/ssl/SSL_write.pod @@ -65,6 +65,9 @@ When an SSL_write() operation has to be repeated because of B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated with the same arguments. +When calling SSL_write() with num=0 bytes to be sent the behaviour is +undefined. + =head1 RETURN VALUES The following return values can occur: diff --git a/crypto/openssl/doc/ssl/ssl.pod b/crypto/openssl/doc/ssl/ssl.pod index 79b19d9..2dcee03 100644 --- a/crypto/openssl/doc/ssl/ssl.pod +++ b/crypto/openssl/doc/ssl/ssl.pod @@ -682,6 +682,7 @@ L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>, L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>, L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>, L<SSL_alert_type_string(3)|SSL_alert_type_string(3)>, +L<SSL_do_handshake(3)|SSL_do_handshake(3)>, L<SSL_get_SSL_CTX(3)|SSL_get_SSL_CTX(3)>, L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>, L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>, |