Add minimal example code to tls handbook

1 files changed, 237 insertions, 2 deletions

diff --git a/doc/manual/tls.rst b/doc/manual/tls.rst
index 77794657c..8d9a6fb12 100644
--- a/doc/manual/tls.rst
+++ b/doc/manual/tls.rst
@@ -328,7 +328,120 @@ TLS Clients
    resized as needed to process inputs). Otherwise some reasonable
    default is used.
 
-Code for a TLS client using BSD sockets is in `src/cli/tls_client.cpp`
+Code Example
+^^^^^^^^^^^^
+A minimal example of a TLS client is provided below.
+The full code for a TLS client using BSD sockets is in `src/cli/tls_client.cpp`
+
+.. code-block:: cpp
+
+    #include <botan/tls_client.h>
+    #include <botan/tls_callbacks.h>
+    #include <botan/tls_session_manager.h>
+    #include <botan/tls_policy.h>
+    #include <botan/auto_rng.h>
+    #include <botan/certstor.h>
+
+    /**
+     * @brief Callbacks invoked by TLS::Channel.
+     *
+     * Botan::TLS::Callbacks is an abstract class.
+     * For improved readability, only the functions that are mandatory
+     * to implement are listed here. See src/lib/tls/tls_callbacks.h.
+     */
+    class Callbacks : public Botan::TLS::Callbacks
+    {
+       public:
+          void tls_emit_data(const uint8_t data[], size_t size) override
+             {
+             // send data to tls server, e.g., using BSD sockets or boost asio
+             }
+
+          void tls_record_received(uint64_t seq_no, const uint8_t data[], size_t size) override
+             {
+             // process full TLS record received by tls server, e.g.,
+             // by passing it to the application
+             }
+
+          void tls_alert(Botan::TLS::Alert alert) override
+             {
+             // handle a tls alert received from the tls server
+             }
+
+          bool tls_session_established(const Botan::TLS::Session& session) override
+             {
+             // the session with the tls server was established
+             // return false to prevent the session from being cached, true to
+             // cache the session in the configured session manager
+             return false;
+             }
+    };
+
+    /**
+     * @brief Credentials storage for the tls client.
+     *
+     * It returns a list of trusted CA certificates from a local directory.
+     * TLS client authentication is disabled. See src/lib/tls/credentials_manager.h.
+     */
+    class Client_Credentials : public Botan::Credentials_Manager
+    {
+       public:
+          std::vector<Certificate_Store*> trusted_certificate_authorities(
+             const std::string& type,
+             const std::string& context) override
+             {
+             // return a list of certificates of CAs we trust for tls server certificates,
+             // e.g., all the certificates in the local directory "cas"
+             return { new Botan::Certificate_Store_In_Memory("cas") };
+             }
+
+          std::vector<X509_Certificate> cert_chain(
+             const std::vector<std::string>& cert_key_types,
+             const std::string& type,
+             const std::string& context) override
+             {
+             // when using tls client authentication (optional), return
+             // a certificate chain being sent to the tls server,
+             // else an empty list
+             return std::vector<Botan::X509_Certificate>();
+             }
+
+          Botan::Private_Key* private_key_for(const Botan::X509_Certificate& cert,
+             const std::string& type,
+             const std::string& context) override
+             {
+             // when returning a chain in cert_chain(), return the private key
+             // associated with the leaf certificate here
+             return nullptr;
+             }
+    };
+
+    int main()
+       {
+       // prepare all the parameters
+       Callbacks callbacks;
+       Botan::AutoSeeded_RNG rng;
+       Botan::TLS::Session_Manager_In_Memory session_mgr(rng);
+       Botan::Client_Credentials creds;
+       Botan::TLS::Strict_Policy policy;
+
+       // open the tls connection
+       Botan::TLS::Client client(callbacks,
+                                 session_mgr,
+                                 creds,
+                                 policy,
+                                 rng,
+                                 Botan::TLS::Server_Information("botan.randombit.net", 443),
+                                 Botan::TLS::Protocol_Version::TLS_V12);
+
+       while(!client.is_closed())
+          {
+          // read data received from the tls server, e.g., using BSD sockets or boost asio
+          // ...
+
+          // send data to the tls server using client.send_data()
+          }
+       }
 
 TLS Servers
 ----------------------------------------
@@ -361,7 +474,129 @@ server; unlike clients, which know what type of protocol (TLS vs DTLS)
 they are negotiating from the start via the *offer_version*, servers
 would not until they actually received a client hello.
 
-Code for a TLS server using asio is in `src/cli/tls_proxy.cpp`.
+Code Example
+^^^^^^^^^^^^
+A minimal example of a TLS server is provided below.
+The full code for a TLS server using asio is in `src/cli/tls_proxy.cpp`.
+
+.. code-block:: cpp
+
+    #include <botan/tls_client.h>
+    #include <botan/tls_callbacks.h>
+    #include <botan/tls_session_manager.h>
+    #include <botan/tls_policy.h>
+    #include <botan/auto_rng.h>
+    #include <botan/certstor.h>
+    #include <botan/pk_keys.h>
+
+    #include <memory>
+
+    /**
+     * @brief Callbacks invoked by TLS::Channel.
+     *
+     * Botan::TLS::Callbacks is an abstract class.
+     * For improved readability, only the functions that are mandatory
+     * to implement are listed here. See src/lib/tls/tls_callbacks.h.
+     */
+    class Callbacks : public Botan::TLS::Callbacks
+    {
+       public:
+          void tls_emit_data(const uint8_t data[], size_t size) override
+             {
+             // send data to tls client, e.g., using BSD sockets or boost asio
+             }
+
+          void tls_record_received(uint64_t seq_no, const uint8_t data[], size_t size) override
+             {
+             // process full TLS record received by tls client, e.g.,
+             // by passing it to the application
+             }
+
+          void tls_alert(Botan::TLS::Alert alert) override
+             {
+             // handle a tls alert received from the tls server
+             }
+
+          bool tls_session_established(const Botan::TLS::Session& session) override
+             {
+             // the session with the tls client was established
+             // return false to prevent the session from being cached, true to
+             // cache the session in the configured session manager
+             return false;
+             }
+    };
+
+    /**
+     * @brief Credentials storage for the tls server.
+     *
+     * It returns a certificate and the associated private key to
+     * authenticate the tls server to the client.
+     * TLS client authentication is not requested.
+     * See src/lib/tls/credentials_manager.h.
+     */
+    class Server_Credentials : public Botan::Credentials_Manager
+    {
+       public:
+	  Server_Credentials() : m_key(Botan::X509::load_key("botan.randombit.net.key"))
+             {
+             }
+
+          std::vector<Certificate_Store*> trusted_certificate_authorities(
+             const std::string& type,
+             const std::string& context) override
+             {
+             // if client authentication is required, this function
+             // shall return a list of certificates of CAs we trust
+             // for tls client certificates, otherwise return an empty list
+             return std::vector<Certificate_Store*>();
+             }
+
+          std::vector<X509_Certificate> cert_chain(
+             const std::vector<std::string>& cert_key_types,
+             const std::string& type,
+             const std::string& context) override
+             {
+             // return the certificate chain being sent to the tls client
+             // e.g., the certificate file "botan.randombit.net.crt"
+             return { Botan::X509_Certificate("botan.randombit.net.crt") };
+             }
+
+          Botan::Private_Key* private_key_for(const Botan::X509_Certificate& cert,
+             const std::string& type,
+             const std::string& context) override
+             {
+             // return the private key associated with the leaf certificate,
+             // in this case the one associated with "botan.randombit.net.crt"
+             return &m_key;
+             }
+
+          private:
+             std::unique_ptr<Botan::Private_Key> m_key;
+    };
+
+    int main()
+       {
+       // prepare all the parameters
+       Callbacks callbacks;
+       Botan::AutoSeeded_RNG rng;
+       Botan::TLS::Session_Manager_In_Memory session_mgr(rng);
+       Botan::Client_Credentials creds;
+       Botan::TLS::Strict_Policy policy;
+
+       // accept tls connection from client
+       Botan::TLS::Server server(callbacks,
+                                 session_mgr,
+                                 creds,
+                                 policy,
+                                 rng);
+
+       // read data received from the tls client, e.g., using BSD sockets or boost asio
+       // and pass it to server.received_data().
+       // ...
+
+       // send data to the tls client using server.send_data()
+       // ...
+       }
 
 .. _tls_sessions: