Change TLS feature macro, major API changes. Start documenting

1 files changed, 122 insertions, 0 deletions

diff --git a/doc/tls.txt b/doc/tls.txt
new file mode 100644
index 000000000..eb7064fdc
--- /dev/null
+++ b/doc/tls.txt
@@ -0,0 +1,122 @@
+
+.. _tls_api:
+
+SSL and TLS
+========================================
+
+.. versionadded:: 1.10.2
+
+Botan supports both client and server implementations of the SSL/TLS
+protocols, including SSL v3, TLS v1.0, and TLS v1.1 (the insecure and
+obsolete SSL v2 protocol is not supported, beyond processing SSL v2
+client hellos which some implementations send for backwards
+compatability).
+
+The implementation uses ``std::tr1::function``, so it may not have
+been compiled into the version you are using; you can test for the
+feature macro ``BOTAN_HAS_TLS`` to check.
+
+TLS Clients
+----------------------------------------
+
+.. cpp:class:: TLS_Client
+
+   .. cpp:function:: TLS_Client( \
+         std::tr1::function<void, const byte[], size_t> socket_output_fn,
+         std::tr1::function<void, const byte[], size_t, u16bit> proc_fn,
+         std::tr1::function<bool, const TLS_Session&> handshake_complete,
+         TLS_Session_Manager& session_manager,
+         Credentials_Manager& credendials_manager,
+         const TLS_Policy& policy,
+         RandomNumberGenerator& rng,
+         const std::string& servername = "",
+         std::tr1::function<std::string, std::vector<std::string>> next_protocol =
+            std::tr1::function<std::string, std::vector<std::string>>());
+
+   Initialize a new TLS client. The constructor will immediately
+   initiate a new session. The *socket_output_fn* callback will be
+   called with output that should be sent to the counterparty.
+
+   The *proc_fn* will be called with data sent by the counterparty
+   after it has been processed. The byte array and size_t represent
+   the plaintext; the u16bit value provides notification if the
+   counterparty sent an alert via the TLS alert system. Possible values
+   of alert data are included in the Alert_Type enum. Particularly
+   relevant is the CLOSE_NOTIFY value.
+
+   The *handshake_complete* function is called when a handshake
+   (either initial or renegotiation) is completed. The return value of
+   the callback specifies if the session should be cached for later
+   resumption.
+
+   The *session_manager* is an interface for storing TLS sessions,
+   which allows for session resumption upon reconnecting to a server.
+   In the absence of a need for persistent sessions, use
+   `TLS_Session_Manager_In_Memory` which caches connections for the
+   lifetime of a single process.
+
+   The *credentials_manager* is an interface that will be called to
+   retrieve any certificates, secret keys, pre-shared keys, or SRP
+   intformation; see :doc:`credentials <credentials_manager>` for more
+   information.
+
+   Use *servername* to specify the DNS name of the server you are
+   attempting to connect to, if you know it.
+
+   The optional *next_protocol* callback is called if the server
+   indicates it supports the next protocol notification extension.
+   The callback wlil be called with a list of protocol names that the
+   server advertises, and the client can select from them or return an
+   unadvertised protocol.
+
+   .. cpp:function size_t received_data(const byte buf[], size_t buf_size)
+
+   This function is used to provide data sent by the counterparty (eg
+   data that you read off the socket layer). Depending on the current
+   protocol state and the amount of data provided this may result in one
+   or more callback functions that were provided to the constructor being
+   called.
+
+   .. cpp:function void queue_for_sending(const byte buf[], size_t buf_size)
+
+   If the connection has completed the initial handshake process, he
+   data provided is sent to the counterparty. Otherwise, an exception
+   is thrown.
+
+   .. cpp:function:: void close()
+
+   A close notification is sent to the counterparty, and the internal
+   state is cleared.
+
+   .. cpp:function:: bool is_active()
+
+   Returns true if and only if a handshake has been completed on this
+   connection.
+
+   .. cpp:function:: bool is_closed()
+
+   Returns true if and only if a close notification has been sent or
+   received, or if a fatal alert of any kind was received from the
+   counterparty.
+
+   .. cpp:function:: void renegotiate()
+
+   Initiates a renegotiation. The counterparty is allowed by the
+   protocol to ignore this request. If a successful renegotiation
+   occurs, the *handshake_complete* callback will be called again.
+
+   .. cpp:function:: std::vector<X509_Certificate> peer_cert_chain()
+
+   Returns the certificate chain of the server
+
+A simple TLS client example:
+
+.. literalinclude:: examples/tls_client.cpp
+
+
+TLS Servers
+----------------------------------------
+
+A simple TLS server
+
+.. literalinclude:: examples/tls_server.cpp