mirror of
https://github.com/openssl/openssl.git
synced 2024-11-21 01:15:20 +08:00
Document the newly added SSL functions
Also document SSL_peek() which was missing from the docs. Reviewed-by: Rich Salz <rsalz@openssl.org>
This commit is contained in:
Matt Caswell
parent
699ae85915
commit
7714dc5ea1
@ -34,26 +34,27 @@ The following mode changes are available:
|
||||
|
||||
=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.
|
||||
Once SSL_write() returns with r, r bytes have been successfully written
|
||||
and the next call to SSL_write() must only send the n-r bytes left,
|
||||
imitating the behaviour of write().
|
||||
Allow SSL_write_ex(..., n, &r) to return with 0 < r < n (i.e. report success
|
||||
when just a single record has been written). This works in a similar way for
|
||||
SSL_write(). When not set (the default), SSL_write_ex() or SSL_write() will only
|
||||
report success once the complete chunk was written. Once SSL_write_ex() or
|
||||
SSL_write() returns successful, r bytes have been written and the next call to
|
||||
SSL_write_ex() or SSL_write() must only send the n-r bytes left, imitating the
|
||||
behaviour of write().
|
||||
|
||||
=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
|
||||
Make it possible to retry SSL_write_ex() or 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)> or L<SSL_write(3)> would return
|
||||
with -1 and indicate the need to retry with SSL_ERROR_WANT_READ.
|
||||
L<SSL_read_ex(3)>, L<SSL_read(3)>, L<SSL_write_ex(3)> or L<SSL_write(3)> would
|
||||
return with a failure 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
|
||||
@ -96,7 +97,8 @@ SSL_CTX_get_mode() and SSL_get_mode() return the current bitmask.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<ssl(3)>, L<SSL_read(3)>, L<SSL_write(3)>, L<SSL_get_error(3)>
|
||||
L<ssl(3)>, L<SSL_read_ex(3)>, L<SSL_read(3)>, L<SSL_write_ex(3)> or
|
||||
L<SSL_write(3)>, L<SSL_get_error(3)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
|
||||
@ -58,19 +58,19 @@ Pipelining operates slightly differently for reading encrypted data compared to
|
||||
writing encrypted data. SSL_CTX_set_split_send_fragment() and
|
||||
SSL_set_split_send_fragment() define how data is split up into pipelines when
|
||||
writing encrypted data. The number of pipelines used will be determined by the
|
||||
amount of data provided to the SSL_write() call divided by
|
||||
amount of data provided to the SSL_write_ex() or SSL_write() call divided by
|
||||
B<split_send_fragment>.
|
||||
|
||||
For example if B<split_send_fragment> is set to 2000 and B<max_pipelines> is 4
|
||||
then:
|
||||
|
||||
SSL_write called with 0-2000 bytes == 1 pipeline used
|
||||
SSL_write(_ex) called with 0-2000 bytes == 1 pipeline used
|
||||
|
||||
SSL_write called with 2001-4000 bytes == 2 pipelines used
|
||||
SSL_write(_ex) called with 2001-4000 bytes == 2 pipelines used
|
||||
|
||||
SSL_write called with 4001-6000 bytes == 3 pipelines used
|
||||
SSL_write(_ex) called with 4001-6000 bytes == 3 pipelines used
|
||||
|
||||
SSL_write called with 6001+ bytes == 4 pipelines used
|
||||
SSL_write(_ex) called with 6001+ bytes == 4 pipelines used
|
||||
|
||||
B<split_send_fragment> must always be less than or equal to
|
||||
B<max_send_fragment>. By default it is set to be equal to B<max_send_fragment>.
|
||||
|
||||
@ -14,9 +14,9 @@ SSL_get_error - obtain result code for TLS/SSL I/O operation
|
||||
|
||||
SSL_get_error() returns a result code (suitable for the C "switch"
|
||||
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>.
|
||||
SSL_read_ex(), SSL_read(), SSL_peek_ex(), SSL_peek(), SSL_write_ex() 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>.
|
||||
|
||||
In addition to B<ssl> and B<ret>, SSL_get_error() inspects the
|
||||
current thread's OpenSSL error queue. Thus, SSL_get_error() must be
|
||||
@ -64,10 +64,11 @@ TLS/SSL I/O function should be retried.
|
||||
|
||||
Caveat: Any TLS/SSL I/O function can lead to either of
|
||||
B<SSL_ERROR_WANT_READ> and B<SSL_ERROR_WANT_WRITE>. In particular,
|
||||
SSL_read() or SSL_peek() may want to write data and SSL_write() may want
|
||||
to read data. This is mainly because TLS/SSL handshakes may occur at any
|
||||
time during the protocol (initiated by either the client or the server);
|
||||
SSL_read(), SSL_peek(), and SSL_write() will handle any pending handshakes.
|
||||
SSL_read_ex(), SSL_read() SSL_peek_ex() or SSL_peek() may want to write data and
|
||||
SSL_write() or SSL_write_ex() may want to read data. This is mainly because
|
||||
TLS/SSL handshakes may occur at any time during the protocol (initiated by
|
||||
either the client or the server); SSL_read_ex(), SSL_read(), SSL_peek_ex(),
|
||||
SSL_peek(), SSL_write_ex() and SSL_write() will handle any pending handshakes.
|
||||
|
||||
=item SSL_ERROR_WANT_CONNECT, SSL_ERROR_WANT_ACCEPT
|
||||
|
||||
|
||||
@ -16,7 +16,7 @@ SSL object
|
||||
|
||||
Data is received in whole blocks known as records from the peer. A whole record
|
||||
is processed (e.g. decrypted) in one go and is buffered by OpenSSL until it is
|
||||
read by the application via a call to L<SSL_read(3)>.
|
||||
read by the application via a call to L<SSL_read_ex(3)> or L<SSL_read(3)>.
|
||||
|
||||
SSL_pending() returns the number of bytes which have been processed, buffered
|
||||
and are available inside B<ssl> for immediate read.
|
||||
@ -34,12 +34,13 @@ the data is in unprocessed buffered records).
|
||||
|
||||
SSL_has_pending() returns 1 if B<s> has buffered data (whether processed or
|
||||
unprocessed) and 0 otherwise. Note that it is possible for SSL_has_pending() to
|
||||
return 1, and then a subsequent call to SSL_read() to return no data because the
|
||||
unprocessed buffered data when processed yielded no application data (for
|
||||
example this can happen during renegotiation). It is also possible in this
|
||||
scenario for SSL_has_pending() to continue to return 1 even after an SSL_read()
|
||||
call because the buffered and unprocessed data is not yet processable (e.g.
|
||||
because OpenSSL has only received a partial record so far).
|
||||
return 1, and then a subsequent call to SSL_read_ex() or SSL_read() to return no
|
||||
data because the unprocessed buffered data when processed yielded no application
|
||||
data (for example this can happen during renegotiation). It is also possible in
|
||||
this scenario for SSL_has_pending() to continue to return 1 even after an
|
||||
SSL_read_ex() or SSL_read() call because the buffered and unprocessed data is
|
||||
not yet processable (e.g. because OpenSSL has only received a partial record so
|
||||
far).
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
@ -49,7 +50,7 @@ returns 1 if there is buffered record data in the SSL object and 0 otherwise.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<SSL_read(3)>, L<SSL_CTX_set_read_ahead(3)>,
|
||||
L<SSL_read_ex(3)>, L<SSL_read(3)>, L<SSL_CTX_set_read_ahead(3)>,
|
||||
L<SSL_CTX_set_split_send_fragment(3)>, L<ssl(3)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
@ -2,82 +2,100 @@
|
||||
|
||||
=head1 NAME
|
||||
|
||||
SSL_read - read bytes from a TLS/SSL connection
|
||||
SSL_read_ex, SSL_read - read bytes from a TLS/SSL connection
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/ssl.h>
|
||||
|
||||
int SSL_read_ex(SSL *ssl, void *buf, size_t num, size_t *read);
|
||||
int SSL_read(SSL *ssl, void *buf, int num);
|
||||
|
||||
int SSL_peek_ex(SSL *ssl, void *buf, size_t num, size_t *read);
|
||||
int SSL_peek(SSL *ssl, void *buf, int num);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
SSL_read() tries to read B<num> bytes from the specified B<ssl> into the
|
||||
buffer B<buf>.
|
||||
SSL_read_ex() and SSL_read() try to read B<num> bytes from the specified B<ssl>
|
||||
into the buffer B<buf>. On success SSL_read_ex() will store the number of bytes
|
||||
actually read in B<*read>.
|
||||
|
||||
SSL_peek_ex() and SSL_peek() are identical to SSL_read_ex() and SSL_read()
|
||||
respectively except no bytes are actually removed from the underlying BIO during
|
||||
the read, so that a subsequent call to SSL_read_ex() or SSL_read() will yield
|
||||
the same bytes.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
If necessary, SSL_read() will negotiate a TLS/SSL session, if
|
||||
In this notes section all comments that apply to SSL_read_ex() or SSL_read()
|
||||
also apply to SSL_peek_ex() and SSL_peek().
|
||||
|
||||
If necessary, SSL_read_ex() or SSL_read() will negotiate a TLS/SSL session, if
|
||||
not already explicitly performed by L<SSL_connect(3)> or
|
||||
L<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.
|
||||
the SSL_read_ex() or SSL_read() operation. The behaviour of SSL_read_ex() and
|
||||
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 being done by calling
|
||||
L<SSL_set_connect_state(3)> or SSL_set_accept_state()
|
||||
before the first call to an SSL_read() or L<SSL_write(3)>
|
||||
function.
|
||||
before the first call to an SSL_read_ex(), SSL_read(), L<SSL_write_ex(3)> or
|
||||
L<SSL_write(3)> function.
|
||||
|
||||
SSL_read() works based on the SSL/TLS records. The data are received in
|
||||
records (with a maximum record size of 16kB for SSLv3/TLSv1). Only when a
|
||||
record has been completely received, it can be processed (decryption and
|
||||
SSL_read_ex() and SSL_read() work based on the SSL/TLS records. The data are
|
||||
received in records (with a maximum record size of 16kB for SSLv3/TLSv1). Only
|
||||
when a record has been completely received, it can be processed (decryption and
|
||||
check of integrity). Therefore data that was not retrieved at the last
|
||||
call of SSL_read() can still be buffered inside the SSL layer and will be
|
||||
retrieved on the next call to SSL_read(). If B<num> is higher than the
|
||||
number of bytes buffered, SSL_read() will return with the bytes buffered.
|
||||
If no more bytes are in the buffer, SSL_read() will trigger the processing
|
||||
of the next record. Only when the record has been received and processed
|
||||
completely, SSL_read() will return reporting success. At most the contents
|
||||
of the record will be returned. As the size of an SSL/TLS record may exceed
|
||||
the maximum packet size of the underlying transport (e.g. TCP), it may
|
||||
be necessary to read several packets from the transport layer before the
|
||||
record is complete and SSL_read() can succeed.
|
||||
call of SSL_read_ex() or SSL_read() can still be buffered inside the SSL layer
|
||||
and will be retrieved on the next call to SSL_read_ex() or SSL_read(). If B<num>
|
||||
is higher than the number of bytes buffered, SSL_read_ex() or SSL_read() will
|
||||
return with the bytes buffered. If no more bytes are in the buffer, SSL_read()
|
||||
will trigger the processing of the next record. Only when the record has been
|
||||
received and processed completely, SSL_read_ex() or SSL_read() will return
|
||||
reporting success. At most the contents of the record will be returned. As the
|
||||
size of an SSL/TLS record may exceed the maximum packet size of the underlying
|
||||
transport (e.g. TCP), it may be necessary to read several packets from the
|
||||
transport layer before the record is complete and SSL_read_ex() or SSL_read()
|
||||
can succeed.
|
||||
|
||||
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.
|
||||
If the underlying BIO is B<blocking>, SSL_read_ex() or 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.
|
||||
This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the
|
||||
L<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
|
||||
If the underlying BIO is B<non-blocking>, SSL_read_ex() or SSL_read() will also
|
||||
return when the underlying BIO could not satisfy the needs of SSL_read_ex() or
|
||||
SSL_read() to continue the operation. In this case a call to
|
||||
L<SSL_get_error(3)> with the
|
||||
return value of SSL_read() will yield B<SSL_ERROR_WANT_READ> or
|
||||
return value of SSL_read_ex() or 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
|
||||
then must repeat the call after taking appropriate action to satisfy the
|
||||
needs of SSL_read(). 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.
|
||||
call to SSL_read_ex() or SSL_read() can also cause write operations! The calling
|
||||
process then must repeat the call after taking appropriate action to satisfy the
|
||||
needs of SSL_read_ex() or SSL_read(). 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.
|
||||
|
||||
L<SSL_pending(3)> can be used to find out whether there
|
||||
are buffered bytes available for immediate retrieval. In this case
|
||||
SSL_read() can be called without blocking or actually receiving new
|
||||
data from the underlying socket.
|
||||
SSL_read_ex() or SSL_read() can be called without blocking or actually receiving
|
||||
new data from the underlying socket.
|
||||
|
||||
=head1 WARNING
|
||||
|
||||
When an SSL_read() operation has to be repeated because of
|
||||
When an SSL_read_ex() or SSL_read() 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.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
The following return values can occur:
|
||||
SSL_read_ex() will return 1 for success or 0 for failure. In the event of a
|
||||
failure call SSL_get_error() to find out the reason.
|
||||
|
||||
For SSL_read() the following return values can occur:
|
||||
|
||||
=over 4
|
||||
|
||||
@ -108,7 +126,7 @@ return value B<ret> to find out the reason.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<SSL_get_error(3)>, L<SSL_write(3)>,
|
||||
L<SSL_get_error(3)>, L<SSL_write_ex(3)>,
|
||||
L<SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)>,
|
||||
L<SSL_connect(3)>, L<SSL_accept(3)>
|
||||
L<SSL_set_connect_state(3)>,
|
||||
|
||||
@ -35,8 +35,8 @@ requested, the handshake routines must be explicitly set.
|
||||
When using the L<SSL_connect(3)> or
|
||||
L<SSL_accept(3)> routines, the correct handshake
|
||||
routines are automatically set. When performing a transparent negotiation
|
||||
using L<SSL_write(3)> or L<SSL_read(3)>, the
|
||||
handshake routines must be explicitly set in advance using either
|
||||
using L<SSL_write_ex(3)>, L<SSL_write(3)> L<SSL_read_ex(3)> or L<SSL_read(3)>,
|
||||
the handshake routines must be explicitly set in advance using either
|
||||
SSL_set_connect_state() or SSL_set_accept_state().
|
||||
|
||||
=head1 RETURN VALUES
|
||||
@ -47,8 +47,8 @@ information.
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<ssl(3)>, L<SSL_new(3)>, L<SSL_CTX_new(3)>,
|
||||
LL<SSL_connect(3)>, L<SSL_accept(3)>,
|
||||
L<SSL_write(3)>, L<SSL_read(3)>,
|
||||
L<SSL_connect(3)>, L<SSL_accept(3)>,
|
||||
L<SSL_write_ex(3)>, L<SSL_write(3)>, L<SSL_read_ex(3)>, L<SSL_read(3)>,
|
||||
L<SSL_do_handshake(3)>,
|
||||
L<SSL_CTX_set_ssl_version(3)>
|
||||
|
||||
|
||||
@ -2,75 +2,83 @@
|
||||
|
||||
=head1 NAME
|
||||
|
||||
SSL_write - write bytes to a TLS/SSL connection
|
||||
SSL_write_ex, SSL_write - write bytes to a TLS/SSL connection
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/ssl.h>
|
||||
|
||||
int SSL_write_ex(SSL *s, const void *buf, size_t num, size_t *written);
|
||||
int SSL_write(SSL *ssl, const void *buf, int num);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
SSL_write() writes B<num> bytes from the buffer B<buf> into the specified
|
||||
B<ssl> connection.
|
||||
SSL_write_ex() and SSL_write() write B<num> bytes from the buffer B<buf> into
|
||||
the specified B<ssl> connection. On success SSL_write_ex() will store the number
|
||||
of bytes written in B<*written>.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
If necessary, SSL_write() will negotiate a TLS/SSL session, if
|
||||
If necessary, SSL_write_ex() or SSL_write() will negotiate a TLS/SSL session, if
|
||||
not already explicitly performed by L<SSL_connect(3)> or
|
||||
L<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.
|
||||
the SSL_write_ex() or SSL_write() operation. The behaviour of SSL_write_ex() or
|
||||
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 being done by calling
|
||||
L<SSL_set_connect_state(3)> or SSL_set_accept_state()
|
||||
before the first call to an L<SSL_read(3)> or SSL_write() function.
|
||||
before the first call to an L<SSL_read_ex(3)>, L<SSL_read(3)>, SSL_write_ex() 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.
|
||||
If the underlying BIO is B<blocking>, SSL_write_ex() and 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.
|
||||
This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the
|
||||
L<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
|
||||
If the underlying BIO is B<non-blocking>, SSL_write_ex() or SSL_write() will
|
||||
also return, when the underlying BIO could not satisfy the needs of
|
||||
SSL_write_ex() or SSL_write() to continue the operation. In this case a call to
|
||||
L<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
|
||||
then must repeat the call after taking appropriate action to satisfy the
|
||||
needs of SSL_write(). 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.
|
||||
return value of SSL_write_ex() or 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_ex() or SSL_write() can also cause read operations! The
|
||||
calling process then must repeat the call after taking appropriate action to
|
||||
satisfy the needs of SSL_write_ex() or SSL_write(). 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.
|
||||
|
||||
SSL_write() will only return with success, when the complete contents
|
||||
of B<buf> of length B<num> has been written. This default behaviour
|
||||
SSL_write_ex() or SSL_write() will only return with success, when the complete
|
||||
contents of B<buf> of length B<num> has been written. This default behaviour
|
||||
can be changed with the SSL_MODE_ENABLE_PARTIAL_WRITE option of
|
||||
L<SSL_CTX_set_mode(3)>. When this flag is set,
|
||||
SSL_write() will also return with success, when a partial write has been
|
||||
successfully completed. In this case the SSL_write() operation is considered
|
||||
completed. The bytes are sent and a new SSL_write() operation with a new
|
||||
SSL_write_ex() or SSL_write() will also return with success, when a partial
|
||||
write has been successfully completed. In this case the SSL_write_ex() or
|
||||
SSL_write() operation is considered completed. The bytes are sent and a new
|
||||
SSL_write_ex() or SSL_write() operation with a new
|
||||
buffer (with the already sent bytes removed) must be started.
|
||||
A partial write is performed with the size of a message block, which is
|
||||
16kB for SSLv3/TLSv1.
|
||||
|
||||
=head1 WARNING
|
||||
|
||||
When an SSL_write() operation has to be repeated because of
|
||||
When an SSL_write_ex() or 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.
|
||||
When calling SSL_write_ex() or SSL_write() with num=0 bytes to be sent the
|
||||
behaviour is undefined.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
The following return values can occur:
|
||||
SSL_write_ex() will return 1 for success or 0 for failure. In the event of a
|
||||
failure call SSL_get_error() to find out the reason.
|
||||
|
||||
For SSL_write() the following return values can occur:
|
||||
|
||||
=over 4
|
||||
|
||||
@ -96,7 +104,7 @@ return value B<ret> to find out the reason.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<SSL_get_error(3)>, L<SSL_read(3)>,
|
||||
L<SSL_get_error(3)>, L<SSL_read_ex(3)>, L<SSL_read(3)>
|
||||
L<SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)>,
|
||||
L<SSL_connect(3)>, L<SSL_accept(3)>
|
||||
L<SSL_set_connect_state(3)>,
|
||||
|
||||
@ -28,8 +28,8 @@ connection with the object.
|
||||
Then the TLS/SSL handshake is performed using
|
||||
L<SSL_accept(3)> or L<SSL_connect(3)>
|
||||
respectively.
|
||||
L<SSL_read(3)> and L<SSL_write(3)> are used
|
||||
to read and write data on the TLS/SSL connection.
|
||||
L<SSL_read_ex(3)>, L<SSL_read(3)>, L<SSL_write_ex(3)> and L<SSL_write(3)> are
|
||||
used to read and write data on the TLS/SSL connection.
|
||||
L<SSL_shutdown(3)> can be used to shut down the
|
||||
TLS/SSL connection.
|
||||
|
||||
@ -792,6 +792,7 @@ L<SSL_get_version(3)>,
|
||||
L<SSL_load_client_CA_file(3)>,
|
||||
L<SSL_new(3)>,
|
||||
L<SSL_pending(3)>,
|
||||
L<SSL_read_ex(3)>,
|
||||
L<SSL_read(3)>,
|
||||
L<SSL_rstate_string(3)>,
|
||||
L<SSL_session_reused(3)>,
|
||||
@ -803,6 +804,7 @@ L<SSL_set_shutdown(3)>,
|
||||
L<SSL_shutdown(3)>,
|
||||
L<SSL_state_string(3)>,
|
||||
L<SSL_want(3)>,
|
||||
L<SSL_write_ex(3)>,
|
||||
L<SSL_write(3)>,
|
||||
L<SSL_SESSION_free(3)>,
|
||||
L<SSL_SESSION_get_time(3)>,
|
||||
|
||||
Loading…
Reference in New Issue
Block a user