Split up docs into the reference manual, the website, and everything else.

Add `website` target to makefile.

Some progress towards fixing minimized builds.

TLS now hard requires ECDSA and GCM since otherwise a minimized build
has only insecure options.

Remove boost_thread dependency in command line tool

1 files changed, 753 insertions, 0 deletions

diff --git a/doc/manual/tls.rst b/doc/manual/tls.rst
new file mode 100644
index 000000000..805bca823
--- /dev/null
+++ b/doc/manual/tls.rst
@@ -0,0 +1,753 @@
+
+Transport Layer Security (TLS)
+========================================
+
+.. versionadded:: 1.11.0
+
+Botan supports both client and server implementations of the SSL/TLS
+protocols, including SSL v3, TLS v1.0, TLS v1.1, and TLS v1.2 (the
+insecure and obsolete SSL v2 protocol is not supported, beyond
+processing SSL v2 client hellos which some clients still send for
+backwards compatability with ancient servers). There is also some
+initial support for DTLS (v1.0 and v1.2), a variant of TLS adapted for
+operation on datagram transports such as UDP and SCTP, though as of
+1.11.6 DTLS handshaking does not support timeouts or retransmissions,
+so it can only be used over reliable datagrams (such as SCTP with
+reliable transmission turned on for DTLS handshake packets). DTLS
+support should be considered as beta quality and further testing is
+invited.
+
+The TLS implementation does not know anything about sockets or the
+network layer. Instead, it calls a user provided callback (hereafter
+``output_fn``) whenever it has data that it would want to send to the
+other party (for instance, by writing it to a network socket), and
+whenever the application receives some data from the counterparty (for
+instance, by reading from a network socket) it passes that information
+to TLS using :cpp:func:`TLS::Channel::received_data`. If the data
+passed in results in some change in the state, such as a handshake
+completing, or some data or an alert being received from the other
+side, then a user provided callback will be invoked. If the reader is
+familiar with OpenSSL's BIO layer, it might be analagous to saying the
+only way of interacting with Botan's TLS is via a `BIO_mem` I/O
+abstraction. This makes the library completely agnostic to how you
+write your network layer, be it blocking sockets, libevent, asio, a
+message queue, etc.
+
+The callbacks that TLS calls have the signatures
+
+ .. cpp:function:: void output_fn(const byte data[], size_t data_len)
+
+    TLS requests that all bytes of *data* be queued up to send to the
+    counterparty. After this function returns, *data* will be
+    overwritten, so a copy of the input must be made if the callback
+    cannot send the data immediately.
+
+ .. cpp:function:: void data_cb(const byte data[], size_t data_len)
+
+     Called whenever application data is received from the other side
+     of the connection, in which case *data* and *data_len* specify
+     the data received. This array will be overwritten sometime after
+     the callback returns, so again a copy should be made if need be.
+
+ .. cpp:function:: void alert_cb(Alert alert, const byte data[], size_t data_len)
+
+     Called when an alert is received. Normally, data is null and
+     data_len is 0, as most alerts have no associated data. However,
+     if TLS heartbeats (see :rfc:`6520`) were negotiated, and we
+     initiated a heartbeat, then if/when the other party responds,
+     ``alert_cb`` will be called with whatever data was included in
+     the heartbeat response (if any) along with a psuedo-alert value
+     of ``HEARTBEAT_PAYLOAD``.
+
+ .. cpp:function:: bool handshake_cb(const TLS::Session& session)
+
+     Called whenever a negotiation completes. This can happen more
+     than once on any connection. The *session* parameter provides
+     information about the session which was established.
+
+     If this function returns false, the session will not be cached
+     for later resumption.
+
+     If this function wishes to cancel the handshake, it can throw an
+     exception which will send a close message to the counterparty and
+     reset the connection state.
+
+You can of course use tools like ``std::bind`` to bind additional
+parameters to your callback functions.
+
+TLS Channels
+----------------------------------------
+
+TLS servers and clients share an interface called `TLS::Channel`. A
+TLS channel (either client or server object) has these methods
+available:
+
+.. cpp:class:: TLS::Channel
+
+   .. 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.
+
+     The return value of ``received_data`` specifies how many more
+     bytes of input are needed to make any progress, unless the end of
+     the data fell exactly on a message boundary, in which case it
+     will return 0 instead.
+
+   .. cpp:function:: void send(const byte buf[], size_t buf_size)
+
+     If the connection has completed the initial handshake process,
+     the data provided is sent to the counterparty as TLS
+     traffic. 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:: void send_alert(const Alert& alert)
+
+     Some other alert is sent to the counterparty. If the alert is
+     fatal, the internal state is cleared.
+
+   .. cpp:function:: bool is_active()
+
+     Returns true if and only if a handshake has been completed on
+     this connection and the connection has not been subsequently
+     closed.
+
+   .. cpp:function:: bool is_closed()
+
+      Returns true if and only if either a close notification or a
+      fatal alert message have been either sent or received.
+
+   .. cpp:function:: void renegotiate(bool force_full_renegotiation = false)
+
+      Initiates a renegotiation. The counterparty is allowed by the
+      protocol to ignore this request. If a successful renegotiation
+      occurs, the *handshake_cb* callback will be called again.
+
+      If *force_full_renegotiation* is false, then the client will
+      attempt to simply renew the current session - this will refresh
+      the symmetric keys but will not change the session master
+      secret. Otherwise it will initiate a completely new session.
+
+      For a server, if *force_full_renegotiation* is false, then a
+      session resumption will be allowed if the client attempts
+      it. Otherwise the server will prevent resumption and force the
+      creation of a new session.
+
+   .. cpp:function:: std::vector<X509_Certificate> peer_cert_chain()
+
+      Returns the certificate chain of the counterparty. When acting
+      as a client, this value will be non-empty unless the client's
+      policy allowed anonymous connections and the server then chose
+      an anonymous ciphersuite. Acting as a server, this value will
+      ordinarily be empty, unless the server requested a certificate
+      and the client responded with one.
+
+   .. cpp:function:: SymmetricKey key_material_export( \
+          const std::string& label, \
+          const std::string& context, \
+          size_t length)
+
+      Returns an exported key of *length* bytes derived from *label*,
+      *context*, and the session's master secret and client and server
+      random values. This key will be unique to this connection, and
+      as long as the session master secret remains secure an attacker
+      should not be able to guess the key.
+
+      Per :rfc:`5705`, *label* should begin with "EXPERIMENTAL" unless
+      the label has been standardized in an RFC.
+
+
+.. _tls_client:
+
+TLS Clients
+----------------------------------------
+
+.. cpp:class:: TLS::Client
+
+   .. cpp:function:: TLS::Client( \
+         std::function<void, const byte*, size_t> output_fn, \
+         std::function<void, const byte*, size_t> data_cb, \
+         std::function<TLS::Alert, const byte*, size_t> alert_cb,
+         std::function<bool, const TLS::Session&> handshake_cb, \
+         TLS::Session_Manager& session_manager, \
+         Credentials_Manager& credendials_manager, \
+         const TLS::Policy& policy, \
+         RandomNumberGenerator& rng, \
+         const Server_Information& server_info, \
+         const Protocol_Version offer_version, \
+         std::function<std::string, std::vector<std::string> > next_protocol, \
+         size_t reserved_io_buffer_size)
+
+   Initialize a new TLS client. The constructor will immediately
+   initiate a new session.
+
+   The *output_fn* callback will be called with output that
+   should be sent to the counterparty. For instance this will be
+   called immediately from the constructor after the client hello
+   message is constructed. An implementation of *output_fn* is
+   allowed to defer the write (for instance if writing when the
+   callback occurs would block), but should eventually write the data
+   to the counterparty *in order*.
+
+   The *data_cb* will be called with data sent by the counterparty
+   after it has been processed. The byte array and size_t represent
+   the plaintext value and size.
+
+   The *alert_cb* will be called when a protocol alert is received,
+   commonly with a close alert during connection teardown.
+
+   The *handshake_cb* 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. If the function for some reason desires to prevent the
+   connection from completing, it should throw an exception
+   (preferably a TLS::Exception, which can provide more specific alert
+   information to the counterparty). The :cpp:class:`TLS::Session`
+   provides information about the session that was just established.
+
+   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
+   :cpp:class:`TLS::Session_Manager_In_Memory` which caches
+   connections for the lifetime of a single process. See
+   :ref:`tls_session_managers` for more about session managers.
+
+   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_manager` for more information.
+
+   Use *server_info* to specify the DNS name of the server you are
+   attempting to connect to, if you know it. This helps the server
+   select what certificate to use and helps the client validate the
+   connection.
+
+   Use *offer_version* to control the version of TLS you wish the
+   client to offer. Normally, you'll want to offer the most recent
+   version of TLS that is available, however some broken servers are
+   intolerant of certain versions being offered, and for classes of
+   applications that have to deal with such servers (typically web
+   browsers) it may be necessary to implement a version backdown
+   strategy if the initial attempt fails.
+
+   Setting *offer_version* is also used to offer DTLS instead of TLS;
+   use :cpp:func:`TLS::Protocol_Version::latest_dtls_version`.
+
+   .. warning::
+
+     Implementing such a backdown strategy allows an attacker to
+     downgrade your connection to the weakest protocol that both you
+     and the server support.
+
+   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.
+
+   The optional *reserved_io_buffer_size* specifies how many bytes to
+   pre-allocate in the I/O buffers. Use this if you want to control
+   how much memory the channel uses initially (the buffers will be
+   resized as needed to process inputs). Otherwise some reasonable
+   default is used.
+
+A simple TLS client example:
+
+.. literalinclude:: ../../src/cmd/tls_client.cpp
+
+TLS Servers
+----------------------------------------
+
+.. cpp:class:: TLS::Server
+
+   .. cpp:function:: TLS::Server( \
+          std::function<void, const byte*, size_t> output_fn, \
+          std::function<void, const byte*, size_t> data_cb, \
+          std::function<TLS::Alert, const byte*, size_t> alert_cb,
+          TLS::Session_Manager& session_manager, \
+          Credentials_Manager& creds, \
+          const TLS::Policy& policy, \
+          RandomNumberGenerator& rng, \
+          const std::vector<std::string>& protocols, \
+          bool reserved_io_buffer_size)
+
+The first 7 arguments as well as the final argument
+*reserved_io_buffer_size*, are treated similiarly to the :ref:`client
+<tls_client>`.  The (optional) argument, *protocols*, specifies the
+protocols the server is willing to advertise it supports.
+
+.. cpp:function:: std::string TLS::Server::next_protocol() const
+
+   If a handshake has completed, and if the client indicated a next
+   protocol (ie, the protocol that it intends to run over this TLS
+   session) this return value will specify it. The next protocol
+   extension is somewhat unusual in that it applies to the connection
+   rather than the session. The next protocol can not change during a
+   renegotiation, but might change across different connections using
+   that session.
+
+A TLS server that can handle concurrent connections using asio:
+
+.. literalinclude:: ../../src/cmd/tls_server_asio.cpp
+
+.. _tls_sessions:
+
+TLS Sessions
+----------------------------------------
+
+TLS allows clients and servers to support *session resumption*, where
+the end point retains some information about an established session
+and then reuse that information to bootstrap a new session in way that
+is much cheaper computationally than a full handshake.
+
+Every time your handshake callback is called, a new session has been
+established, and a ``TLS::Session`` is included that provides
+information about that session:
+
+.. cpp:class:: TLS::Session
+
+   .. cpp:function:: Protocol_Version version() const
+
+       Returns the :cpp:class:`protocol version <TLS::Protocol_Version>`
+       that was negotiated
+
+   .. cpp:function:: Ciphersuite ciphersite() const
+
+       Returns the :cpp:class:`ciphersuite <TLS::Ciphersuite>` that
+       was negotiated.
+
+   .. cpp:function:: Server_Information server_info() const
+
+       Returns information that identifies the server side of the
+       connection.  This is useful for the client in that it
+       identifies what was originally passed to the constructor. For
+       the server, it includes the name the client specified in the
+       server name indicator extension.
+
+   .. cpp:function:: std::vector<X509_Certificate> peer_certs() const
+
+       Returns the certificate chain of the peer
+
+   .. cpp:function:: std::string srp_identifier() const
+
+       If an SRP ciphersuite was used, then this is the identifier
+       that was used for authentication.
+
+   .. cpp:function:: bool secure_renegotiation() const
+
+      Returns ``true`` if the connection was negotiated with the
+      correct extensions to prevent the renegotiation attack.
+
+There are also functions for serialization and deserializing sessions:
+
+.. cpp:class:: TLS::Session
+
+   .. cpp:function:: std::vector<byte> encrypt(const SymmetricKey& key, \
+                                               RandomNumberGenerator& rng)
+
+      Encrypts a session using a symmetric key *key* and returns a raw
+      binary value that can later be passed to ``decrypt``. The key
+      may be of any length.
+
+      Currently the implementation uses AES-256 in CBC mode with a
+      SHA-256 HMAC. The keys for these are derived from *key* using
+      KDF2(SHA-256).
+
+   .. cpp:function:: static Session decrypt(const byte ciphertext[], \
+                                            size_t length, \
+                                            const SymmetricKey& key)
+
+      Decrypts a session that was encrypted previously with
+      ``encrypt`` and *key*, or throws an exception if decryption
+      fails.
+
+   .. cpp:function:: secure_vector<byte> DER_encode() const
+
+       Returns a serialized version of the session.
+
+       .. warning:: The return value contains the master secret for
+                    the session, and an attacker who recovers it could
+                    recover plaintext of previous sessions or
+                    impersonate one side to the other.
+
+.. _tls_session_managers:
+
+TLS Session Managers
+----------------------------------------
+
+You may want sessions stored in a specific format or storage type. To
+do so, implement the ``TLS::Session_Manager`` interface and pass your
+implementation to the ``TLS::Client`` or ``TLS::Server`` constructor.
+
+.. cpp:class:: TLS::Session_Mananger
+
+ .. cpp:function:: void save(const Session& session)
+
+     Save a new *session*. It is possible that this sessions session
+     ID will replicate a session ID already stored, in which case the
+     new session information should overwrite the previous information.
+
+ .. cpp:function:: void remove_entry(const std::vector<byte>& session_id)
+
+      Remove the session identified by *session_id*. Future attempts
+      at resumption should fail for this session.
+
+ .. cpp:function:: bool load_from_session_id(const std::vector<byte>& session_id, \
+                                             Session& session)
+
+      Attempt to resume a session identified by *session_id*. If
+      located, *session* is set to the session data previously passed
+      to *save*, and ``true`` is returned. Otherwise *session* is not
+      modified and ``false`` is returned.
+
+ .. cpp:function:: bool load_from_server_info(const Server_Information& server, \
+                                              Session& session)
+
+      Attempt to resume a session with a known server.
+
+ .. cpp:function:: std::chrono::seconds session_lifetime() const
+
+      Returns the expected maximum lifetime of a session when using
+      this session manager. Will return 0 if the lifetime is unknown
+      or has no explicit expiration policy.
+
+.. _tls_session_manager_inmem:
+
+In Memory Session Manager
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``TLS::Session_Manager_In_Memory`` implementation saves sessions
+in memory, with an upper bound on the maximum number of sessions and
+the lifetime of a session.
+
+It is safe to share a single object across many threads as it uses a
+lock internally.
+
+.. cpp:class:: TLS::Session_Managers_In_Memory
+
+ .. cpp:function:: Session_Manager_In_Memory(RandomNumberGenerator& rng, \
+                                             size_t max_sessions = 1000, \
+                                             std::chrono::seconds session_lifetime = 7200)
+
+    Limits the maximum number of saved sessions to *max_sessions*, and
+    expires all sessions older than *session_lifetime*.
+
+Noop Session Mananger
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``TLS::Session_Manager_Noop`` implementation does not save
+sessions at all, and thus session resumption always fails. Its
+constructor has no arguments.
+
+SQLite3 Session Manager
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This session manager is only available if support for SQLite3 was
+enabled at build time. If the macro
+``BOTAN_HAS_TLS_SQLITE3_SESSION_MANAGER`` is defined, then
+``botan/tls_session_manager_sqlite.h`` contains
+``TLS::Session_Manager_SQLite`` which stores sessions persistently to
+a sqlite3 database. The session data is encrypted using a passphrase,
+and stored in two tables, named ``tls_sessions`` (which holds the
+actual session information) and ``tls_sessions_metadata`` (which holds
+the PBKDF information).
+
+.. warning:: The hostnames associated with the saved sessions are
+             stored in the database in plaintext. This may be a
+             serious privacy risk in some applications.
+
+.. cpp:class:: TLS::Session_Manager_SQLite
+
+ .. cpp:function:: Session_Manager_SQLite( \
+       const std::string& passphrase, \
+       RandomNumberGenerator& rng, \
+       const std::string& db_filename, \
+       size_t max_sessions = 1000, \
+       std::chrono::seconds session_lifetime = 7200)
+
+   Uses the sqlite3 database named by *db_filename*.
+
+TLS Policies
+----------------------------------------
+
+``TLS::Policy`` is how an application can control details of what will
+be negotiated during a handshake.
+
+.. cpp:class:: TLS::Policy
+
+ .. cpp:function:: std::vector<std::string> allowed_ciphers() const
+
+     Returns the list of ciphers we are willing to negotiate, in order
+     of preference.
+
+     Default: "AES-256/GCM", "AES-128/GCM",
+     "AES-256/CCM", "AES-128/CCM", "AES-256/CCM-8", "AES-128/CCM-8",
+     "AES-256", "AES-128"
+
+     Also allowed: "Camellia-256/GCM", "Camellia-128/GCM",
+     "Camellia-256", "Camellia-128", "SEED", "3DES", "RC4"
+
+     .. note::
+
+        RC4 will never be negotiated in DTLS due to protocol limitations
+
+ .. cpp:function:: std::vector<std::string> allowed_macs() const
+
+     Returns the list of algorithms we are willing to use for
+     message authentication, in order of preference.
+
+     Default: "AEAD", "SHA-384", "SHA-256", "SHA-1"
+
+     Also allowed: "MD5"
+
+ .. cpp:function:: std::vector<std::string> allowed_key_exchange_methods() const
+
+     Returns the list of key exchange methods we are willing to use,
+     in order of preference.
+
+     Default: "ECDH", "DH", "RSA"
+
+     Also allowed: "SRP_SHA", "ECDHE_PSK", "DHE_PSK", "PSK"
+
+ .. cpp:function:: std::vector<std::string> allowed_signature_hashes() const
+
+     Returns the list of algorithms we are willing to use for
+     public key signatures, in order of preference.
+
+     Default: "SHA-512", "SHA-384", "SHA-256", "SHA-224"
+
+     Also allowed (although **not recommended**): "MD5", "SHA-1"
+
+     .. note::
+
+        This is only used with TLS v1.2. In earlier versions of the
+        protocol, signatures are fixed to using only SHA-1 (for
+        DSA/ECDSA) or a MD5/SHA-1 pair (for RSA).
+
+ .. cpp:function:: std::vector<std::string> allowed_signature_methods() const
+
+     Default: "ECDSA", "RSA", "DSA"
+
+     Also allowed: "" (meaning anonymous)
+
+ .. cpp:function:: std::vector<std::string> allowed_ecc_curves() const
+
+     Return a list of ECC curves we are willing to use, in order of preference.
+
+     Default: "brainpool512r1", "brainpool384r1", "brainpool256r1",
+              "secp521r1", "secp384r1", "secp256r1",
+              "secp256k1"
+
+     Also allowed: "secp224r1", "secp224k1", "secp192r1", "secp192k1",
+     "secp160r2", "secp160r1", "secp160k1"
+
+ .. cpp:function:: std::vector<byte> compression() const
+
+     Return the list of compression methods we are willing to use, in order of
+     preference. Default is null compression only.
+
+     .. note::
+
+        TLS compression is not currently supported.
+
+ .. cpp:function:: bool acceptable_protocol_version(Protocol_Version version)
+
+     Return true if this version of the protocol is one that we are
+     willing to negotiate.
+
+     Default: True if a known TLS version. DTLS is not accepted by default;
+     to enable DTLS (or combined TLS/DTLS) in your application, override this
+     function.
+
+ .. cpp:function:: bool server_uses_own_ciphersuite_preferences() const
+
+     If this returns true, a server will pick the cipher it prefers the
+     most out of the client's list. Otherwise, it will negotiate the
+     first cipher in the client's ciphersuite list that it supports.
+
+ .. cpp:function:: bool negotiate_heartbeat_support() const
+
+     If this function returns true, clients will offer the heartbeat
+     support extension, and servers will respond to clients offering
+     the extension. Otherwise, clients will not offer heartbeat
+     support and servers will ignore clients offering heartbeat
+     support.
+
+     If this returns true, callers should expect to handle heartbeat
+     data in their ``alert_cb``.
+
+     Default: false
+
+ .. cpp:function:: bool allow_server_initiated_renegotiation() const
+
+     If this function returns true, a client will accept a
+     server-initiated renegotiation attempt. Otherwise it will send
+     the server a non-fatal ``no_renegotiation`` alert.
+
+     Default: true
+
+ .. cpp:function:: bool allow_insecure_renegotiation() const
+
+     If this function returns true, we will allow renegotiation attempts
+     even if the counterparty does not support the RFC 5746 extensions.
+
+     .. warning:: Returning true here could expose you to attacks
+
+     Default: false
+
+ .. cpp:function:: DL_Group dh_group() const
+
+     For ephemeral Diffie-Hellman key exchange, the server sends a
+     group parameter. Return the group parameter a server should
+     use.
+
+     Default: 2048 bit IETF IPsec group ("modp/ietf/2048")
+
+ .. cpp:function:: size_t minimum_dh_group_size() const
+
+     Return the minimum size in bits for a Diffie-Hellman group that a
+     client will accept. Due to the design of the protocol the client
+     has only two options - accept the group, or reject it with a
+     fatal alert then attempt to reconnect after disabling ephemeral
+     Diffie-Hellman.
+
+     Default: 1024 bits
+
+ .. cpp:function:: bool hide_unknown_users() const
+
+     The SRP and PSK suites work using an identifier along with a
+     shared secret. If this function returns true, when an identifier
+     that the server does not recognize is provided by a client, a
+     random shared secret will be generated in such a way that a
+     client should not be able to tell the difference between the
+     identifier not being known and the secret being wrong.  This can
+     help protect against some username probing attacks.  If it
+     returns false, the server will instead send an
+     ``unknown_psk_identity`` alert when an unknown identifier is
+     used.
+
+     Default: false
+
+ .. cpp:function:: u32bit session_ticket_lifetime() const
+
+     Return the lifetime of session tickets. Each session includes the
+     start time. Sessions resumptions using tickets older than
+     ``session_ticket_lifetime`` seconds will fail, forcing a full
+     renegotiation.
+
+     Default: 86400 seconds (1 day)
+
+TLS Ciphersuites
+----------------------------------------
+
+.. cpp:class:: TLS::Ciphersuite
+
+ .. cpp:function:: u16bit ciphersuite_code() const
+
+     Return the numerical code for this ciphersuite
+
+ .. cpp:function:: std::string to_string() const
+
+     Return the ful name of ciphersuite (for example
+     "RSA_WITH_RC4_128_SHA" or "ECDHE_RSA_WITH_AES_128_GCM_SHA256")
+
+ .. cpp:function:: std::string kex_algo() const
+
+     Return the key exchange algorithm of this ciphersuite
+
+ .. cpp:function:: std::string sig_algo() const
+
+     Return the signature algorithm of this ciphersuite
+
+ .. cpp:function:: std::string cipher_algo() const
+
+     Return the cipher algorithm of this ciphersuite
+
+ .. cpp:function:: std::string mac_algo() const
+
+     Return the authentication algorithm of this ciphersuite
+
+.. _tls_alerts:
+
+TLS Alerts
+----------------------------------------
+
+A ``TLS::Alert`` is passed to every invocation of a channel's *alert_cb*.
+
+.. cpp:class:: TLS::Alert
+
+  .. cpp:function:: is_valid() const
+
+       Return true if this alert is not a null alert
+
+  .. cpp:function:: is_fatal() const
+
+       Return true if this alert is fatal. A fatal alert causes the
+       connection to be immediately disconnected. Otherwise, the alert
+       is a warning and the connection remains valid.
+
+  .. cpp:function:: Type type() const
+
+       Returns the type of the alert as an enum
+
+  .. cpp:function:: std::string type_string()
+
+       Returns the type of the alert as a string
+
+TLS Protocol Version
+----------------------------------------
+
+TLS has several different versions with slightly different behaviors.
+The ``TLS::Protocol_Version`` class represents a specific version:
+
+.. cpp:class:: TLS::Protocol_Version
+
+ .. cpp:type:: enum Version_Code
+
+     ``SSL_V3``, ``TLS_V10``, ``TLS_V11``, ``TLS_V12``, ``DTLS_V10``,
+     ``DTLS_V12``
+
+ .. cpp:function:: static Protocol_Version latest_tls_version()
+
+      Returns the latest version of TLS supported by this implementation
+      (currently TLS v1.2)
+
+ .. cpp:function:: static Protocol_Version latest_dtls_version()
+
+      Returns the latest version of DTLS supported by this implementation
+      (currently DTLS v1.2)
+
+ .. cpp:function:: Protocol_Version(Version_Code named_version)
+
+      Create a specific version
+
+ .. cpp:function:: byte major_version() const
+
+      Returns major number of the protocol version
+
+ .. cpp:function:: byte minor_version() const
+
+      Returns minor number of the protocol version
+
+ .. cpp:function:: std::string to_string() const
+
+      Returns string description of the version, for instance "SSL v3",
+      "TLS v1.1", or "DTLS v1.0".
+
+ .. cpp:function:: static Protocol_Version latest_tls_version()
+
+      Returns the latest version of the TLS protocol known the the library
+      (currently TLS v1.2)
+
+ .. cpp:function:: static Protocol_Version latest_dtls_version()
+
+      Returns the latest version of the DTLS protocol known the the
+      library (currently DTLS v1.2)
+
+