Hi!
As the usual non-blocking question had to be answered again in the last days,
I thought it would be better to provide some man-pages instead of writing
things again and again... (Do I really think this helps? ...)
Hopefully, I have not messed around too much with this .pod stuff :-)
Best regards,
Lutz
PS. I can provide some more as it seems to be useful to integrate as much
as possible _before_ 0.9.6 comes out.
I have collected some experiences with BIO-pairs and related stuff. But then
I probably have to arrange this with Stephen Henson, who seems to be working
on documenting these things.
--
Lutz Jaenicke [EMAIL PROTECTED]
BTU Cottbus http://www.aet.TU-Cottbus.DE/personen/jaenicke/
Lehrstuhl Allgemeine Elektrotechnik Tel. +49 355 69-4129
Universitaetsplatz 3-4, D-03044 Cottbus Fax. +49 355 69-4153
=pod
=head1 NAME
SSL_accept - Wait for a TLS client to initiate a TLS handshake
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_accept(SSL *ssl);
=head1 DESCRIPTION
SSL_accept() waits for a TLS client to initiate the TLS handshake.
The communication channel must already have been set and assigned to the
B<ssl> by setting an underlying B<BIO>. The behaviour of SSL_accept() depends
on the underlying BIO.
If the underlying BIO is B<blocking>, SSL_accept() will only return, once the
handshake has been finished or an error occured.
If the underlying BIO is B<non-blocking>, SSL_accept() will also return,
when the underlying BIO could not satisfy the needs of SSL_accept()
to continue the handshake. In this case a call to SSL_get_error() with the
return value of SSL_accept() will yield SSL_ERROR_WANT_READ or
SSL_ERROR_WANT_WRITE. The calling process then must repeat the call after
taking appropriate action to satisfy the needs of SSL_accept().
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 currently occur:
=over 4
=item 1
The TLS handshake was successfully completed, a TLS connection has been
established.
=item 0
The TLS handshake was not successfull but was shut down controlled and
by the specifications of the TLS protocol. Call SSL_get_error() with the
return value B<ret> to find out the reason.
=item -1
The TLS handshake was not successfull, because a fatal error occured either
at the protocol level or a connection failure occured. The shutdown was
not clean. It can also occure 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_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>
=cut
=pod
=head1 NAME
SSL_connect - Initiate the TLS handshake with an TLS server
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_connect(SSL *ssl);
=head1 DESCRIPTION
SSL_connect() initiates the TLS handshake with a server. The communication
channel must already have been set and assigned to the B<ssl> by setting an
underlying B<BIO>. The behaviour of SSL_connect() depends on the underlying
BIO.
If the underlying BIO is B<blocking>, SSL_connect() will only return, once the
handshake has been finished or an error occured.
If the underlying BIO is B<non-blocking>, SSL_connect() will also return,
when the underlying BIO could not satisfy the needs of SSL_connect()
to continue the handshake. In this case a call to SSL_get_error() with the
return value of SSL_connect() will yield SSL_ERROR_WANT_READ or
SSL_ERROR_WANT_WRITE. The calling process then must repeat the call after
taking appropriate action to satisfy the needs of SSL_connect().
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 currently occur:
=over 4
=item 1
The TLS handshake was successfully completed, a TLS connection has been
established.
=item 0
The TLS handshake was not successfull but was shut down controlled and
by the specifications of the TLS protocol. Call SSL_get_error() with the
return value B<ret> to find out the reason.
=item -1
The TLS handshake was not successfull, because a fatal error occured either
at the protocol level or a connection failure occured. The shutdown was
not clean. It can also occure 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_accept(3)|SSL_accept(3)>,
L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)> , L<bio(3)|bio(3)>
=cut
=pod
=head1 NAME
SSL_read - Read bytes from a TLS connection.
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_read(SSL *ssl, char *buf, int num);
=head1 DESCRIPTION
SSL_read() tries to read B<num> bytes from the specified B<ssl> into the
buffer B<buf>. If necessary, SSL_read() will negotiate a TLS session, if
not already explicitely performed by SSL_connect() or SSL_accept(). 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.
If the underlying BIO is B<blocking>, SSL_read() will only return, once the
read operation has been finished or an error occured.
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
return value of SSL_read() will yield SSL_ERROR_WANT_READ or
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.
=head1 RETURN VALUES
The following return values can currently occur:
=over 4
=item E<gt>0
The read operation was successfull, the return value is the number of
bytes actually read from the TLS connection.
=item 0
The read operation was not successfull, probably because no data was
available. Call SSL_get_error() with the return value B<ret> to find out,
whether an error occured.
=item -1
The read operation was not successfull, because either an error occured
or action must be taken by the calling process. 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_write(3)|SSL_write(3)>,
L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>
=cut
=pod
=head1 NAME
SSL_read - Write bytes to a TLS connection.
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_write(SSL *ssl, char *buf, int num);
=head1 DESCRIPTION
SSL_write() writes B<num> bytes from the buffer B<buf> into the specified
B<ssl>. If necessary, SSL_write() will negotiate a TLS session, if
not already explicitely performed by SSL_connect() or SSL_accept(). 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.
If the underlying BIO is B<blocking>, SSL_write() will only return, once the
write operation has been finished or an error occured.
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
return value of SSL_write() will yield SSL_ERROR_WANT_READ or
SSL_ERROR_WANT_WRITE. As at any time a re-negotiation is possible, a
call to SSL_write() can also cause write 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.
=head1 RETURN VALUES
The following return values can currently occur:
=over 4
=item E<gt>0
The write operation was successfull, the return value is the number of
bytes actually written to the TLS connection.
=item 0
The write operation was not successfull. Call SSL_get_error() with the return
value B<ret> to find out, whether an error occured.
=item -1
The read operation was not successfull, because either an error occured
or action must be taken by the calling process. 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_read(3)|SSL_read(3)>,
L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>
=cut
=pod
=head1 NAME
SSL_shutdown - Shut down a TLS connection
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_shutdown(SSL *ssl);
=head1 DESCRIPTION
SSL_shutdown() shuts down an active TLS connection. It sends the shutdown
alert to the peer. The behaviour of SSL_shutdown() depends on the underlying
BIO.
If the underlying BIO is B<blocking>, SSL_shutdown() will only return, once the
handshake has been finished or an error occured.
If the underlying BIO is B<non-blocking>, SSL_shutdown() will also return,
when the underlying BIO could not satisfy the needs of SSL_shutdown()
to continue the handshake. In this case a call to SSL_get_error() with the
return value of SSL_shutdown() will yield SSL_ERROR_WANT_READ or
SSL_ERROR_WANT_WRITE. The calling process then must repeat the call after
taking appropriate action to satisfy the needs of SSL_shutdown().
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 currently occur:
=over 4
=item 1
The shutdown was successfully completed.
=item 0
The shutdown was not successfull. Call SSL_get_error() with the return
value B<ret> to find out the reason.
=item -1
The shutdown was not successfull, because a fatal error occured either
at the protocol level or a connection failure occured. It can also occure 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)>
=cut
