diff options
author | Lutz Jänicke <jaenicke@openssl.org> | 2001-03-08 17:24:02 +0000 |
---|---|---|
committer | Lutz Jänicke <jaenicke@openssl.org> | 2001-03-08 17:24:02 +0000 |
commit | b72ff47037804dfbe5ed884c59a68de6fe475821 (patch) | |
tree | 2c839890024c5549472605a4014ac1e37b719a6f /doc/ssl | |
parent | a2b03690a8057f6ed3f85afce93c490139f3305a (diff) |
Add newly learned knowledge from yesterday's discussion.
Diffstat (limited to 'doc/ssl')
-rw-r--r-- | doc/ssl/SSL_CTX_new.pod | 6 | ||||
-rw-r--r-- | doc/ssl/SSL_CTX_set_ssl_version.pod | 13 | ||||
-rw-r--r-- | doc/ssl/SSL_accept.pod | 9 | ||||
-rw-r--r-- | doc/ssl/SSL_connect.pod | 9 | ||||
-rw-r--r-- | doc/ssl/SSL_read.pod | 17 | ||||
-rw-r--r-- | doc/ssl/SSL_write.pod | 17 | ||||
-rw-r--r-- | doc/ssl/ssl.pod | 1 |
7 files changed, 57 insertions, 15 deletions
diff --git a/doc/ssl/SSL_CTX_new.pod b/doc/ssl/SSL_CTX_new.pod index 8b16ea3c90..1dae8b0bdd 100644 --- a/doc/ssl/SSL_CTX_new.pod +++ b/doc/ssl/SSL_CTX_new.pod @@ -59,6 +59,10 @@ choice when compatibility is a concern. =back +If a generic method is used, it is necessary to explicitly set client or +server mode with L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> +or SSL_set_accept_state(). + The list of protocols available can later be limited using the SSL_OP_NO_SSLv2, SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1 options of the B<SSL_CTX_set_options()> or B<SSL_set_options()> functions. Using these options it is possible to choose @@ -89,6 +93,6 @@ The return value points to an allocated SSL_CTX object. =head1 SEE ALSO L<SSL_CTX_free(3)|SSL_CTX_free(3)>, L<SSL_accept(3)|SSL_accept(3)>, -L<ssl(3)|ssl(3)> +L<ssl(3)|ssl(3)>, L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> =cut diff --git a/doc/ssl/SSL_CTX_set_ssl_version.pod b/doc/ssl/SSL_CTX_set_ssl_version.pod index 3091bd6895..0020180965 100644 --- a/doc/ssl/SSL_CTX_set_ssl_version.pod +++ b/doc/ssl/SSL_CTX_set_ssl_version.pod @@ -17,8 +17,8 @@ SSL_CTX_set_ssl_version, SSL_set_ssl_method, SSL_get_ssl_method SSL_CTX_set_ssl_version() sets a new default TLS/SSL B<method> for SSL objects newly created from this B<ctx>. SSL objects already created with -L<SSL_new(3)|SSL_new(3)> are not affected, except when SSL_clear() is -being called. +L<SSL_new(3)|SSL_new(3)> are not affected, except when +L<SSL_clear(3)|SSL_clear(3)> is being called. SSL_set_ssl_method() sets a new TLS/SSL B<method> for a particular B<ssl> object. It may be reset, when SSL_clear() is called. @@ -31,9 +31,9 @@ set in B<ssl>. The available B<method> choices are described in L<SSL_CTX_new(3)|SSL_CTX_new(3)>. -When SSL_clear() is called and no session is connected to an SSL object, -the method of the SSL object is reset to the method currently set in -the corresponding SSL_CTX object. +When L<SSL_clear(3)|SSL_clear(3)> is called and no session is connected to +an SSL object, the method of the SSL object is reset to the method currently +set in the corresponding SSL_CTX object. =head1 RETURN VALUES @@ -55,6 +55,7 @@ The operation succeeded. =head1 SEE ALSO L<SSL_CTX_new(3)|SSL_CTX_new(3)>, L<SSL_new(3)|SSL_new(3)>, -L<SSL_clear(3)|SSL_clear(3)>, L<ssl(3)|ssl(3)> +L<SSL_clear(3)|SSL_clear(3)>, L<ssl(3)|ssl(3)>, +L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> =cut diff --git a/doc/ssl/SSL_accept.pod b/doc/ssl/SSL_accept.pod index 46f95abb2f..86f980de41 100644 --- a/doc/ssl/SSL_accept.pod +++ b/doc/ssl/SSL_accept.pod @@ -37,6 +37,11 @@ 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. +When using a generic method (see L<SSL_CTX_new(3)|SSL_CTX_new(3)>), it +is necessary to call SSL_set_accept_state() +before calling SSL_accept() to explicitly switch the B<ssl> to server +mode. + =head1 RETURN VALUES The following return values can occur: @@ -67,6 +72,8 @@ to find out the reason. =head1 SEE ALSO 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_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_CTX_new(3)|SSL_CTX_new(3)> =cut diff --git a/doc/ssl/SSL_connect.pod b/doc/ssl/SSL_connect.pod index 00813ecfff..bcc167745b 100644 --- a/doc/ssl/SSL_connect.pod +++ b/doc/ssl/SSL_connect.pod @@ -34,6 +34,11 @@ 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. +When using a generic method (see L<SSL_CTX_new(3)|SSL_CTX_new(3)>), it +is necessary to call L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> +before calling SSL_connect() to explicitly switch the B<ssl> to client +mode. + =head1 RETURN VALUES The following return values can occur: @@ -64,6 +69,8 @@ to find out the reason. =head1 SEE ALSO 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_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_CTX_new(3)|SSL_CTX_new(3)> =cut diff --git a/doc/ssl/SSL_read.pod b/doc/ssl/SSL_read.pod index ed86d269dc..91f068a119 100644 --- a/doc/ssl/SSL_read.pod +++ b/doc/ssl/SSL_read.pod @@ -18,11 +18,19 @@ buffer B<buf>. =head1 NOTES If necessary, SSL_read() will negotiate a TLS/SSL session, if -not already explicitly performed by SSL_connect() or SSL_accept(). If the +not already explicitly performed by L<SSL_connect(3)|SSL_connect(3)> or +L<SSL_accept(3)|SSL_accept(3)>. If the peer requests a re-negotiation, it will be performed transparently during the SSL_read() operation. The behaviour of SSL_read() depends on the underlying BIO. +For the transparent negotiation to succeed, the B<ssl> must have been +initialized to client or server mode. This is not the case if a generic +method is being used (see L<SSL_CTX_new(3)|SSL_CTX_new(3)>, so that +L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> or SSL_set_accept_state() +must be used before the first call to an SSL_read() or +L<SSL_write(3)|SSL_write(3)> function. + If the underlying BIO is B<blocking>, SSL_read() will only return, once the read operation has been finished or an error occurred, except when a renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur. @@ -31,7 +39,8 @@ L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)> call. If the underlying BIO is B<non-blocking>, SSL_read() will also return when the underlying BIO could not satisfy the needs of SSL_read() -to continue the operation. In this case a call to SSL_get_error() with the +to continue the operation. In this case a call to +L<SSL_get_error(3)|SSL_get_error(3)> with the return value of SSL_read() will yield B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a call to SSL_read() can also cause write operations! The calling process @@ -75,7 +84,9 @@ return value B<ret> to find out the reason. =head1 SEE ALSO L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_write(3)|SSL_write(3)>, -L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>, +L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(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_set_connect_state(3)|SSL_set_connect_state(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> =cut diff --git a/doc/ssl/SSL_write.pod b/doc/ssl/SSL_write.pod index f95907981d..6e3ecffa1a 100644 --- a/doc/ssl/SSL_write.pod +++ b/doc/ssl/SSL_write.pod @@ -18,11 +18,19 @@ B<ssl> connection. =head1 NOTES If necessary, SSL_write() will negotiate a TLS/SSL session, if -not already explicitly performed by SSL_connect() or SSL_accept(). If the +not already explicitly performed by L<SSL_connect(3)|SSL_connect(3)> or +L<SSL_accept(3)|SSL_accept(3)>. If the peer requests a re-negotiation, it will be performed transparently during the SSL_write() operation. The behaviour of SSL_write() depends on the underlying BIO. +For the transparent negotiation to succeed, the B<ssl> must have been +initialized to client or server mode. This is not the case if a generic +method is being used (see L<SSL_CTX_new(3)|SSL_CTX_new(3)>, so that +L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> or SSL_set_accept_state() +must be used before the first call to an L<SSL_read(3)|SSL_read(3)> +or SSL_write() function. + If the underlying BIO is B<blocking>, SSL_write() will only return, once the write operation has been finished or an error occurred, except when a renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur. @@ -31,7 +39,8 @@ L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)> call. If the underlying BIO is B<non-blocking>, SSL_write() will also return, when the underlying BIO could not satisfy the needs of SSL_write() -to continue the operation. In this case a call to SSL_get_error() with the +to continue the operation. In this case a call to +L<SSL_get_error(3)|SSL_get_error(3)> with the return value of SSL_write() will yield B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a call to SSL_write() can also cause read operations! The calling process @@ -74,7 +83,9 @@ return value B<ret> to find out the reason. =head1 SEE ALSO L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_read(3)|SSL_read(3)>, -L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>, +L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(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_set_connect_state(3)|SSL_set_connect_state(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> =cut diff --git a/doc/ssl/ssl.pod b/doc/ssl/ssl.pod index 50f8d869a5..b0255e3695 100644 --- a/doc/ssl/ssl.pod +++ b/doc/ssl/ssl.pod @@ -687,6 +687,7 @@ L<SSL_library_init(3)|SSL_library_init(3)>, L<SSL_load_client_CA_file(3)|SSL_load_client_CA_file(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_read(3)|SSL_read(3)>, L<SSL_set_bio(3)|SSL_set_bio(3)>, +L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>, L<SSL_set_fd(3)|SSL_set_fd(3)>, L<SSL_pending(3)|SSL_pending(3)>, L<SSL_set_session(3)|SSL_set_session(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>, |