From f282ca7413a33773dc1ba008c7e04c06db54499b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lutz=20J=C3=A4nicke?= <jaenicke@openssl.org>
Date: Tue, 13 Feb 2001 11:43:11 +0000
Subject: New manual page: SSL_CTX_set_mode.

---
 doc/ssl/SSL_CTX_set_mode.pod | 78 ++++++++++++++++++++++++++++++++++++++++++++
 doc/ssl/SSL_read.pod         |  6 +++-
 doc/ssl/SSL_write.pod        |  6 +++-
 doc/ssl/ssl.pod              |  1 +
 4 files changed, 89 insertions(+), 2 deletions(-)
 create mode 100644 doc/ssl/SSL_CTX_set_mode.pod

(limited to 'doc')

diff --git a/doc/ssl/SSL_CTX_set_mode.pod b/doc/ssl/SSL_CTX_set_mode.pod
new file mode 100644
index 0000000000..9a035bb4d1
--- /dev/null
+++ b/doc/ssl/SSL_CTX_set_mode.pod
@@ -0,0 +1,78 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_mode, SSL_set_mode, SSL_CTX_get_mode, SSL_get_mode - manipulate SSL engine mode
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_CTX_set_mode(SSL_CTX *ctx, long mode);
+ long SSL_set_mode(SSL *ssl, long mode);
+
+ long SSL_CTX_get_mode(SSL_CTX *ctx);
+ long SSL_get_mode(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_mode() adds the mode set via bitmask in B<mode> to B<ctx>.
+Options already set before are not cleared.
+
+SSL_set_mode() adds the mode set via bitmask in B<mode> to B<ssl>.
+Options already set before are not cleared.
+
+SSL_CTX_get_mode() returns the mode set for B<ctx>.
+
+SSL_get_mode() returns the mode set for B<ssl>.
+
+=head1 NOTES
+
+The following mode changes are available:
+
+=over 4
+
+=item SSL_MODE_ENABLE_PARTIAL_WRITE
+
+Allow SSL_write(..., n) to return r with 0 < r < n (i.e. report success
+when just a single record has been written). When not set (the default),
+SSL_write() will only report success once the complete chunk was written.
+
+=item SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER
+
+Make it possible to retry SSL_write() with changed buffer location
+(the buffer contents must stay the same). This is not the default to avoid
+the misconception that non-blocking SSL_write() behaves like
+non-blocking write().
+
+=item SSL_MODE_AUTO_RETRY
+
+Never bother the application with retries if the transport is blocking.
+If a renegotiation take place during normal operation, a
+L<SSL_read(3)|SSL_read(3)> or L<SSL_write(3)|SSL_write(3)> would return
+with -1 and indicate the need to retry with SSL_ERROR_WANT_READ.
+In a non-blocking environment applications must be prepared to handle
+incomplete read/write operations.
+In a blocking environment, applications are not always prepared to
+deal with read/write operations returning without success report. The
+flag SSL_MODE_AUTO_RETRY will cause read/write operations to only
+return after the handshake and successful completion.
+
+=back
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_mode() and SSL_set_mode() return the new mode bitmask
+after adding B<mode>.
+
+SSL_CTX_get_mode() and SSL_get_mode() return the current bitmask.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_read(3)|SSL_read(3)>, L<SSL_write(3)|SSL_write(3)>
+
+=head1 HISTORY
+
+SSL_MODE_AUTO_RETRY as been added in OpenSSL 0.9.6.
+
+=cut
diff --git a/doc/ssl/SSL_read.pod b/doc/ssl/SSL_read.pod
index 9bff32500b..ed86d269dc 100644
--- a/doc/ssl/SSL_read.pod
+++ b/doc/ssl/SSL_read.pod
@@ -24,7 +24,10 @@ the SSL_read() operation. The behaviour of SSL_read() depends on the
 underlying BIO. 
 
 If the underlying BIO is B<blocking>, SSL_read() will only return, once the
-read operation has been finished or an error occurred.
+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. 
+This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the
+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()
@@ -72,6 +75,7 @@ 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(3)|ssl(3)>, L<bio(3)|bio(3)>
 
 =cut
diff --git a/doc/ssl/SSL_write.pod b/doc/ssl/SSL_write.pod
index 8110161522..f95907981d 100644
--- a/doc/ssl/SSL_write.pod
+++ b/doc/ssl/SSL_write.pod
@@ -24,7 +24,10 @@ the SSL_write() operation. The behaviour of SSL_write() depends on the
 underlying BIO. 
 
 If the underlying BIO is B<blocking>, SSL_write() will only return, once the
-write operation has been finished or an error occurred.
+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. 
+This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the
+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()
@@ -71,6 +74,7 @@ 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(3)|ssl(3)>, L<bio(3)|bio(3)>
 
 =cut
diff --git a/doc/ssl/ssl.pod b/doc/ssl/ssl.pod
index 3375525cc5..530ee102e2 100644
--- a/doc/ssl/ssl.pod
+++ b/doc/ssl/ssl.pod
@@ -663,6 +663,7 @@ L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>,
 L<SSL_CTX_sessions(3)|SSL_CTX_sessions(3)>,
 L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>,
 L<SSL_CTX_set_default_passwd_cb(3)|SSL_CTX_set_default_passwd_cb(3)>,
+L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>,
 L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>,
 L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>,
 L<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>,
-- 
cgit v1.2.1