Add a number of documentation files, mostly for SSL routines, but also

for a few BIO routines.
Submitted by Lutz Jaenicke <Lutz.Jaenicke@aet.TU-Cottbus.DE>

CHANGES

@@ -4,6 +4,9 @@
 
  Changes between 0.9.5a and 0.9.6  [xx XXX 2000]
 
+  *) Add a large number of documentation files for many SSL routines.
+     [Lutz Jaenicke <Lutz.Jaenicke@aet.TU-Cottbus.DE>]
+
   *) Add a configuration entry for Sony News 4.
      [NAKAJI Hiroyuki <nakaji@tutrp.tut.ac.jp>]
 

doc/crypto/BIO_ctrl_get_read_request.pod

@@ -0,0 +1,38 @@
+=pod
+
+=head1 NAME
+
+ BIO_ctrl_get_read_request - Find out how much bytes are were requested from the BIO
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ size_t BIO_ctrl_get_read_request(BIO *bio);
+
+=head1 DESCRIPTION
+
+BIO_ctrl_get_read_request() returns the number of bytes that were last
+requested from B<bio> by a BIO_read() operation. This is useful e.g. for
+BIO pairs, so that the application knows how much bytes to supply to B<bio>.
+
+=head1 BUGS
+
+When B<bio> is NULL, the OpenSSL library calls assert().
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item E<gt>=0
+
+The number of bytes requested.
+
+=back
+
+=head1 SEE ALSO
+
+L<bio(3)|bio(3)>, L<BIO_s_mem(3)|BIO_s_mem(3)>,
+L<BIO_new_bio_pair(3)|BIO_new_bio_pair(3)>

doc/crypto/BIO_ctrl_pending.pod

@@ -0,0 +1,36 @@
+=pod
+
+=head1 NAME
+
+BIO_ctrl_pending - Find out how much bytes are buffered in a BIO
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ size_t BIO_ctrl_pending(BIO *bio);
+
+=head1 DESCRIPTION
+
+BIO_ctrl_pending() returns the number of bytes buffered in a BIO.
+
+=head1 BUGS
+
+When B<bio> is NULL, the OpenSSL library calls assert().
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item E<gt>=0
+
+The number of bytes pending the BIO.
+
+=back
+
+=head1 SEE ALSO
+
+L<bio(3)|bio(3)>, L<BIO_s_mem(3)|BIO_s_mem(3)>,
+L<BIO_new_bio_pair(3)|BIO_new_bio_pair(3)>

doc/crypto/BIO_new_bio_pair.pod

@@ -0,0 +1,102 @@
+=pod
+
+=head1 NAME
+
+BIO_new_bio_pair - create a new BIO pair
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2);
+
+=head1 DESCRIPTION
+
+BIO_new_bio_pair() creates a buffering BIO pair. It has two endpoints between
+data can be buffered. Its typical use is to connect one endpoint as underlying
+input/output BIO to an SSL and access the other one controlled by the program
+instead of accessing the network connection directly.
+
+The two new BIOs B<bio1> and B<bio2> are symmetric with respect to their
+functionality. The size of their buffers is determined by B<writebuf1> and
+B<writebuf2>. If the size give is 0, the default size is used.
+
+BIO_new_bio_pair() does not check whether B<bio1> or B<bio2> do point to
+some other BIO, the values are overwritten, BIO_free() is not called.
+
+The two BIOs, even though forming a BIO pair and must be BIO_free()'ed
+seperately. This can be of importance, as some SSL-functions like SSL_set_bio()
+or SSL_free() call BIO_free() implicitely, so that the peer-BIO is left
+untouched and must also be BIO_free()'ed.
+
+=head1 EXAMPLE
+
+The BIO pair can be used to have full control over the network access of an
+application. The application can call select() on the socket as required
+without having to go through the SSL-interface.
+
+ BIO *internal_bio, *network_bio;
+ ...
+ BIO_new_bio_pair(internal_bio, 0, network_bio, 0);
+ SSL_set_bio(ssl, internal_bio);
+ SSL_operations();
+ ...
+
+ application |   TLS-engine
+    |        |
+    +----------> SSL_operations()
+             |     /\    ||
+             |     ||    \/
+             |   BIO-pair (internal_bio)
+    +----------< BIO-pair (network_bio)
+    |        |
+  socket     |
+
+  ...
+  SSL_free(ssl);		/* implicitely frees internal_bio */
+  BIO_free(network_bio);
+  ...
+
+As the BIO pair will only buffer the data and never directly access the
+connection, it behaves non-blocking and will return as soon as the write
+buffer is full or the read buffer is drained. Then the application has to
+flush the write buffer and/or fill the read buffer.
+
+Use the BIO_ctrl_pending(), to find out whether data is buffered in the BIO
+and must be transfered to the network. Use BIO_ctrl_get_read_request() to
+find out, how many bytes must be written into the buffer before the
+SSL_operation() can successfully be continued.
+
+=head1 IMPORTANT
+
+As the data is buffered, SSL_operation() may return with a ERROR_SSL_WANT_READ
+condition, but there is still data in the write buffer. An application must
+not rely on the error value of SSL_operation() but must assure that the
+write buffer is always flushed first. Otherwise a deadlock may occur as
+the peer might be waiting for the data before being able to continue.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item 1
+
+The BIO pair was created successfully. The new BIOs are available in
+B<bio1> and B<bio2>.
+
+=item 0
+
+The operation failed. The NULL pointer is stored into the locations for
+B<bio1> and B<bio2>. Check the error stack for more information.
+
+=back
+
+=head1 SEE ALSO
+
+L<SSL_set_bio(3)|SSL_set_bio(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>,
+L<BIO_ctrl_pending(3)|BIO_ctrl_pending(3)>,
+L<BIO_ctrl_get_read_request(3)|BIO_ctrl_get_read_request(3)>
+
+=cut

doc/ssl/SSL_SESSION_free.pod

@@ -0,0 +1,25 @@
+=pod
+
+=head1 NAME
+
+SSL_SESSION_free - Free up an allocated SSL_SESSION structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void *SSL_SESSION_free(SSL_SESSION *session);
+
+=head1 DESCRIPTION
+
+SSL_SESSION_free() decrements the reference count of B<session> and removes
+the SSL_SESSION structure pointed to by B<session> and frees up the allocated
+memory, if the the reference count has reached 0.
+
+=head1 RETURN VALUES
+
+SSL_SESSION_free() does not provide diagnostic information.
+
+L<ssl(3)|ssl(3)>, L<SSL_get_session(3)|SSL_get_session(3)>
+
+=cut

doc/ssl/SSL_accept.pod

@@ -0,0 +1,69 @@
+=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, except for SGC (Server
+Gated Cryptography). For SGC SSL_accept() may return with -1 but
+SSL_get_error() will yield SSL_ERROR_WANT_READ/WRITE and SSL_accept()
+should be called again.
+
+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 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

doc/ssl/SSL_clear.pod

@@ -0,0 +1,39 @@
+=pod
+
+=head1 NAME
+
+SSL_clear - Reset SSL to allow another connection
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int *SSL_clear(SSL *ssl);
+
+=head1 DESCRIPTION
+
+Reset the B<ssl> to allow another connection. All settings (method, ciphers,
+BIOs) are kept. A completely negotiated SSL_SESSION is not freed but left
+untouched for the underlying SSL_CTX.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item 0
+
+The SSL_clear() operation could not be performed. Check the error stack to
+find out the reason.
+
+=item 1
+
+The SSL_clear() operation was successfull.
+
+=back
+
+L<SSL_new(3)|SSL_new(3)>, L<SSL_free(3)|SSL_free(3)>,
+L<ssl(3)|ssl(3)>
+
+=cut

doc/ssl/SSL_connect.pod

@@ -0,0 +1,66 @@
+=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 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

doc/ssl/SSL_free.pod

@@ -0,0 +1,33 @@
+=pod
+
+=head1 NAME
+
+SSL_free - Free up an allocated SSL structure
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void *SSL_free(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_free() decrements the reference count of B<ssl> and removes the SSL
+structure pointed to by B<ssl> and frees up the allocated memory, if the
+the reference count has reached 0.
+
+It also calls the free()ing procedures for indirectly affected items, if
+applicable: the buffering BIO, the read and write BIOs,
+cipher lists especially created for this B<ssl>, the SSL_SESSION.
+Do not explicitly free these indirectly freed up items before or after
+calling SSL_free(), as trying to free things twice may lead to program
+failure.
+
+=head1 RETURN VALUES
+
+SSL_free() does not provide diagnostic information.
+
+L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>,
+L<ssl(3)|ssl(3)>
+
+=cut

doc/ssl/SSL_get_fd.pod

@@ -0,0 +1,44 @@
+=pod
+
+=head1 NAME
+
+SSL_get_fd - Get file descriptor linked to an SSL
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_get_fd(SSL *ssl);
+ int SSL_get_rfd(SSL *ssl);
+ int SSL_get_wfd(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_get_fd() returns the file descriptor which is linked to B<ssl>.
+SSL_get_rfd() and SSL_get_wfd() return the file descriptors for the
+read or the write channel, which can be different. If the read and the
+write channel are different, SSL_get_fd() will return the file descriptor
+of the read channel.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item -1
+
+The operation failed, because the underlying BIO is not of the correct type
+(suitable for file descriptors).
+
+=item E<gt>=0
+
+The file descriptor linked to B<ssl>.
+
+=back
+
+=head1 SEE ALSO
+
+L<SSL_set_fd(3)|SSL_set_fd(3)>, L<ssl(3)|ssl(3)> , L<bio(3)|bio(3)>
+
+=cut

doc/ssl/SSL_get_rbio.pod

@@ -0,0 +1,40 @@
+=pod
+
+=head1 NAME
+
+SSL_get_rbio - Get BIO linked to an SSL
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ BIO *SSL_get_rbio(SSL *ssl);
+ BIO *SSL_get_wbio(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_get_rbio() and SSL_get_wbio() return pointers to the BIOs for the
+read or the write channel, which can be different. The reference count
+of the BIO is not incremented.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item NULL
+
+No BIO was connected to the SSL
+
+=item Any other pointer
+
+The BIO linked to B<ssl>.
+
+=back
+
+=head1 SEE ALSO
+
+L<SSL_set_bio(3)|SSL_set_bio(3)>, L<ssl(3)|ssl(3)> , L<bio(3)|bio(3)>
+
+=cut

doc/ssl/SSL_get_session.pod

@@ -0,0 +1,48 @@
+=pod
+
+=head1 NAME
+
+SSL_get_session - Retrieve SSL session data
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ SSL_SESSION *SSL_get_session(SSL *ssl);
+ SSL_SESSION *SSL_get0_session(SSL *ssl);
+ SSL_SESSION *SSL_get1_session(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_get_session() returns a pointer to the SSL session actually used in
+B<ssl>. The reference count of the SSL session is not incremented, so
+that the pointer can become invalid when the B<ssl> is freed and
+SSL_SESSION_free() is implicitly called.
+
+SSL_get0_session() is the same as SSL_get_session().
+
+SSL_get1_session() is the same as SSL_get_session(), but the reference
+count of the SSL session is incremented by one.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item NULL
+
+There is no session available in B<ssl>.
+
+=item Pointer to an SSL
+
+The return value points to the data of an SSL session.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_free(3)|SSL_free(3)>,
+L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>
+
+=cut

doc/ssl/SSL_new.pod

@@ -0,0 +1,42 @@
+=pod
+
+=head1 NAME
+
+SSL_new - Create a new SSL structure for a connection
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ SSL *SSL_new(SSL_CTX *ctx);
+
+=head1 DESCRIPTION
+
+SSL_new() creates a new B<SSL> structure which is needed to hold the data
+for a SSL connection. The new SSL inherits the settings of the underlying
+context B<ctx>: connection method (SSLv2/v3/TLSv1), options, verification
+settings, timeout settings.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item NULL
+
+The creation of a new SSL failed. Check the error stack to find out the
+reason.
+
+=item Pointer to an SSL
+
+The return value points to an allocated SSL structure.
+
+=back
+
+=head1 SEE ALSO
+
+L<SSL_free(3)|SSL_free(3)>, L<SSL_clear(3)|SSL_clear(3)>,
+L<ssl(3)|ssl(3)>
+
+=cut

doc/ssl/SSL_read.pod

@@ -0,0 +1,67 @@
+=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 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

doc/ssl/SSL_set_bio.pod

@@ -0,0 +1,34 @@
+=pod
+
+=head1 NAME
+
+SSL_set_bio - Connect the SSL with a BIO
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_set_bio(SSL *ssl, BIO *rbio, BIO *wbio);
+
+=head1 DESCRIPTION
+
+SSL_set_bio() connects the BIOs B<rbio> and B<wbio> for the read and write
+operations of the TLS (encrypted) side of B<ssl>.
+
+The SSL engine inherits the behaviour of B<rbio> and B<wbio>, respectively.
+If a BIO is non-blocking, the B<ssl> will also have non-blocking behaviour.
+
+If there was already a BIO connected to B<ssl>, BIO_free() will be called
+(for both the reading and writing side, if different).
+
+=head1 RETURN VALUES
+
+SSL_set_bio() cannot fail.
+
+=head1 SEE ALSO
+
+L<SSL_get_rbio(3)|SSL_get_rbio(3)>,
+L<SSL_connect(3)|SSL_connect(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

doc/ssl/SSL_set_fd.pod

@@ -0,0 +1,54 @@
+=pod
+
+=head1 NAME
+
+SSL_set_fd - Connect the SSL with a file descriptor
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_set_fd(SSL *ssl, int fd);
+ int SSL_set_rfd(SSL *ssl, int fd);
+ int SSL_set_wfd(SSL *ssl, int fd);
+
+=head1 DESCRIPTION
+
+SSL_set_fd() sets the file descriptor B<fd> as the input/output facility
+for the TLS (encrypted) side of SSL engine. B<fd> will typically be the
+socket file descriptor of a network connection.
+
+When performing the operation, a B<socket BIO> is automatically created to
+interface between the B<ssl> and B<fd>. The BIO and hence the SSL engine
+inherit the behaviour of B<fd>. If B<fd> is non-blocking, the B<ssl> will
+also have non-blocking behaviour.
+
+If there was already a BIO connected to B<ssl>, BIO_free() will be called
+(for both the reading and writing side, if different).
+
+SSL_set_rfd() and SSL_set_wfd() perform the respective action but only
+for the read channel or the write channel, which can be set independantly.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item 0
+
+The operation failed. Check the error stack to find out why.
+
+=item 1
+
+The operation succeeded.
+
+=back
+
+=head1 SEE ALSO
+
+L<SSL_get_fd(3)|SSL_get_fd(3)>, L<SSL_set_bio(3)|SSL_set_bio(3)>,
+L<SSL_connect(3)|SSL_connect(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

doc/ssl/SSL_set_session.pod

@@ -0,0 +1,45 @@
+=pod
+
+=head1 NAME
+
+SSL_set_session - Set an SSL session to be used during SSL connect
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int *SSL_set_session(SSL *ssl, SSL_SESSION *session);
+
+=head1 DESCRIPTION
+
+SSL_set_session() sets B<session> to be used, when the SSL connection
+is to be established. SSL_set_session() is only useful for SSL clients.
+When the session is set, the reference count of B<session> is incremented
+by 1. If the session is not reused, the reference count is decremented
+again during SSL_connect().
+
+If there is already a session set inside B<ssl> (because it was set with
+SSL_set_session() before or because the same B<ssl> was already used for
+a connection) SSL_SESSION_free() will be called for that session.
+
+=head1 RETURN VALUES
+
+The following return values can occur:
+
+=over 4
+
+=item 0
+
+The operation failed, check the error stack to find out the reason.
+
+=item 1
+
+The operation succeeded.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>
+
+=cut

doc/ssl/SSL_shutdown.pod

@@ -0,0 +1,62 @@
+=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 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

doc/ssl/SSL_write.pod

@@ -0,0 +1,66 @@
+=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 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