5 files changed, 71 insertions, 47 deletions
diff --git a/doc/ssl/SSL_CTX_new.pod b/doc/ssl/SSL_CTX_new.pod
index e166c692c..8b16ea3c9 100644
--- a/doc/ssl/SSL_CTX_new.pod
+++ b/doc/ssl/SSL_CTX_new.pod
@@ -33,9 +33,9 @@ understand SSLv2 client hello messages.
 =item SSLv3_method(void), SSLv3_server_method(void), SSLv3_client_method(void)
 
 A TLS/SSL connection established with these methods will only understand the
-SSLv3 and TLSv1 protocol. A client will send out SSLv3 client hello messages
-and will indicate that it also understands TLSv1. A server will only understand
-SSLv3 and TLSv1 client hello messages. This especially means, that it will
+SSLv3 protocol. A client will send out SSLv3 client hello messages
+and will indicate that it only understands SSLv3. A server will only understand
+SSLv3 client hello messages. This especially means, that it will
 not understand SSLv2 client hello messages which are widely used for
 compatibility reasons, see SSLv23_*_method().
 
@@ -46,7 +46,8 @@ TLSv1 protocol. A client will send out TLSv1 client hello messages
 and will indicate that it only understands TLSv1. A server will only understand
 TLSv1 client hello messages. This especially means, that it will
 not understand SSLv2 client hello messages which are widely used for
-compatibility reasons, see SSLv23_*_method().
+compatibility reasons, see SSLv23_*_method(). It will also not understand
+SSLv3 client hello messages.
 
 =item SSLv23_method(void), SSLv23_server_method(void), SSLv23_client_method(void)
 
diff --git a/doc/ssl/SSL_CTX_set_verify.pod b/doc/ssl/SSL_CTX_set_verify.pod
index f405a6a5c..9d7b7a907 100644
--- a/doc/ssl/SSL_CTX_set_verify.pod
+++ b/doc/ssl/SSL_CTX_set_verify.pod
@@ -187,7 +187,7 @@ certificates.
      * SSL_CTX_set_verify_depth() is by purpose set to "limit+1" so
      * that whenever the "depth>verify_depth" condition is met, we
      * have violated the limit and want to log this error condition.
-     * We must do it here, because the CHAIN_TO_LONG error would not
+     * We must do it here, because the CHAIN_TOO_LONG error would not
      * be found explicitly; only errors introduced by cutting off the
      * additional certificates would be logged.
      */
diff --git a/doc/ssl/SSL_connect.pod b/doc/ssl/SSL_connect.pod
index 0316f8df1..00813ecff 100644
--- a/doc/ssl/SSL_connect.pod
+++ b/doc/ssl/SSL_connect.pod
@@ -64,6 +64,6 @@ 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)>
 
 =cut
diff --git a/doc/ssl/SSL_write.pod b/doc/ssl/SSL_write.pod
index 7ce625ac2..01e3d2c59 100644
--- a/doc/ssl/SSL_write.pod
+++ b/doc/ssl/SSL_write.pod
@@ -31,7 +31,7 @@ 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 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 write operations! The calling process
+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
diff --git a/doc/ssl/ssl.pod b/doc/ssl/ssl.pod
index 557378d72..87f698fba 100644
--- a/doc/ssl/ssl.pod
+++ b/doc/ssl/ssl.pod
@@ -13,6 +13,69 @@ The OpenSSL B<ssl> library implements the Secure Sockets Layer (SSL v2/v3) and
 Transport Layer Security (TLS v1) protocols. It provides a rich API which is
 documented here.
 
+At first the library must be initialized; see
+L<SSL_library_init(3)|SSL_library_init(3)>.
+
+Then an B<SSL_CTX> object is created as a framework to establish
+TLS/SSL enabled connections (see L<SSL_CTX_new(3)|SSL_CTX_new(3)>).
+Various options regarding certificates, algorithms etc. can be set
+in this object.
+
+When a network connection has been created, it can be assigned to an
+B<SSL> object. After the B<SSL> object has been created using
+L<SSL_new(3)|SSL_new(3)>, L<SSL_set_fd(3)|SSL_set_fd(3)> or
+L<SSL_set_bio(3)|SSL_set_bio(3)> can be used to associate the network
+connection with the object.
+
+Then the TLS/SSL handshake is performed using
+L<SSL_accept(3)|SSL_accept(3)> or L<SSL_connect(3)|SSL_connect(3)>
+respectively.
+L<SSL_read(3)|SSL_read(3)> and L<SSL_write(3)|SSL_write(3)> are used
+to read and write data on the TLS/SSL connection.
+L<SSL_shutdown(3)|SSL_shutdown(3)> can be used to shut down the
+TLS/SSL connection.
+
+=head1 DATA STRUCTURES
+
+Currently the OpenSSL B<ssl> library functions deals with the following data
+structures:
+
+=over 4
+
+=item B<SSL_METHOD> (SSL Method)
+
+That's a dispatch structure describing the internal B<ssl> library
+methods/functions which implement the various protocol versions (SSLv1, SSLv2
+and TLSv1). It's needed to create an B<SSL_CTX>.
+
+=item B<SSL_CIPHER> (SSL Cipher)
+
+This structure holds the algorithm information for a particular cipher which
+are a core part of the SSL/TLS protocol. The available ciphers are configured
+on a B<SSL_CTX> basis and the actually used ones are then part of the
+B<SSL_SESSION>.
+
+=item B<SSL_CTX> (SSL Context)
+
+That's the global context structure which is created by a server or client
+once per program life-time and which holds mainly default values for the
+B<SSL> structures which are later created for the connections.
+
+=item B<SSL_SESSION> (SSL Session)
+
+This is a structure containing the current TLS/SSL session details for a
+connection: B<SSL_CIPHER>s, client and server certificates, keys, etc.
+
+=item B<SSL> (SSL Connection)
+
+That's the main SSL/TLS structure which is created by a server or client per
+established connection. This actually is the core structure in the SSL API.
+Under run-time the application usually deals with this structure which has
+links to mostly all other structures.
+
+=back
+
+
 =head1 HEADER FILES
 
 Currently the OpenSSL B<ssl> library provides the following C header files
@@ -55,46 +118,6 @@ it's already included by ssl.h>.
 
 =back
 
-=head1 DATA STRUCTURES
-
-Currently the OpenSSL B<ssl> library functions deals with the following data
-structures:
-
-=over 4
-
-=item B<SSL_METHOD> (SSL Method)
-
-That's a dispatch structure describing the internal B<ssl> library
-methods/functions which implement the various protocol versions (SSLv1, SSLv2
-and TLSv1). It's needed to create an B<SSL_CTX>.
-
-=item B<SSL_CIPHER> (SSL Cipher)
-
-This structure holds the algorithm information for a particular cipher which
-are a core part of the SSL/TLS protocol. The available ciphers are configured
-on a B<SSL_CTX> basis and the actually used ones are then part of the
-B<SSL_SESSION>.
-
-=item B<SSL_CTX> (SSL Context)
-
-That's the global context structure which is created by a server or client
-once per program life-time and which holds mainly default values for the
-B<SSL> structures which are later created for the connections.
-
-=item B<SSL_SESSION> (SSL Session)
-
-This is a structure containing the current TLS/SSL session details for a
-connection: B<SSL_CIPHER>s, client and server certificates, keys, etc.
-
-=item B<SSL> (SSL Connection)
-
-That's the main SSL/TLS structure which is created by a server or client per
-established connection. This actually is the core structure in the SSL API.
-Under run-time the application usually deals with this structure which has
-links to mostly all other structures.
-
-=back
-
 =head1 API FUNCTIONS
 
 Currently the OpenSSL B<ssl> library exports 214 API functions.