Merge GH #670 Improve Doxygen coverage

12 files changed, 123 insertions, 18 deletions

diff --git a/src/lib/tls/tls_callbacks.h b/src/lib/tls/tls_callbacks.h
index 75887c23f..17cd19b81 100644
--- a/src/lib/tls/tls_callbacks.h
+++ b/src/lib/tls/tls_callbacks.h
@@ -126,23 +126,27 @@ class BOTAN_DLL Compat_Callbacks final : public Callbacks
        *
        * @param alert_cb is called when a TLS alert is received
        *
-       * @param handshake_cb is called when a handshake is completed
+       * @param hs_cb is called when a handshake is completed
+       *
+       * @param hs_msg_cb is called for each handshake message received
+       *
+       * @param next_proto is called with ALPN protocol data sent by the client
        */
        BOTAN_DEPRECATED("Use TLS::Callbacks (virtual interface).")
-       Compat_Callbacks(output_fn out, data_cb app_data_cb, alert_cb alert_cb,
+       Compat_Callbacks(output_fn output_fn, data_cb app_data_cb, alert_cb alert_cb,
                         handshake_cb hs_cb, handshake_msg_cb hs_msg_cb = nullptr,
                         next_protocol_fn next_proto = nullptr)
-          : m_output_function(out), m_app_data_cb(app_data_cb),
+          : m_output_function(output_fn), m_app_data_cb(app_data_cb),
             m_alert_cb(std::bind(alert_cb, std::placeholders::_1, nullptr, 0)),
             m_hs_cb(hs_cb), m_hs_msg_cb(hs_msg_cb), m_next_proto(next_proto) {}
 
        BOTAN_DEPRECATED("Use TLS::Callbacks (virtual interface).")
-       Compat_Callbacks(output_fn out, data_cb app_data_cb,
+       Compat_Callbacks(output_fn output_fn, data_cb app_data_cb,
                         std::function<void (Alert)> alert_cb,
                         handshake_cb hs_cb,
                         handshake_msg_cb hs_msg_cb = nullptr,
                         next_protocol_fn next_proto = nullptr)
-          : m_output_function(out), m_app_data_cb(app_data_cb),
+          : m_output_function(output_fn), m_app_data_cb(app_data_cb),
             m_alert_cb(alert_cb),
             m_hs_cb(hs_cb), m_hs_msg_cb(hs_msg_cb), m_next_proto(next_proto) {}
 
diff --git a/src/lib/tls/tls_channel.h b/src/lib/tls/tls_channel.h
index 073af760f..2f4793211 100644
--- a/src/lib/tls/tls_channel.h
+++ b/src/lib/tls/tls_channel.h
@@ -27,6 +27,8 @@ class Connection_Cipher_State;
 class Connection_Sequence_Numbers;
 class Handshake_State;
 class Handshake_Message;
+class Client_Hello;
+class Server_Hello;
 
 /**
 * Generic interface for TLS endpoint
@@ -41,6 +43,24 @@ class BOTAN_DLL Channel
       typedef std::function<void (const Handshake_Message&)> handshake_msg_cb;
       static size_t IO_BUF_DEFAULT_SIZE;
 
+      /**
+      * Set up a new TLS session
+      *
+      * @param callbacks contains a set of callback function references
+      *        required by the TLS endpoint.
+      *
+      * @param session_manager manages session state
+      *
+      * @param rng a random number generator
+      *
+      * @param policy specifies other connection policy information
+      *
+      * @param is_datagram whether this is a DTLS session
+      *
+      * @param io_buf_sz This many bytes of memory will
+      *        be preallocated for the read and write buffers. Smaller
+      *        values just mean reallocations and copies are more likely.
+      */
       Channel(Callbacks& callbacks,
               Session_Manager& session_manager,
               RandomNumberGenerator& rng,
@@ -203,8 +223,8 @@ class BOTAN_DLL Channel
 
       /* secure renegotiation handling */
 
-      void secure_renegotiation_check(const class Client_Hello* client_hello);
-      void secure_renegotiation_check(const class Server_Hello* server_hello);
+      void secure_renegotiation_check(const Client_Hello* client_hello);
+      void secure_renegotiation_check(const Server_Hello* server_hello);
 
       std::vector<byte> secure_renegotiation_data_for_client_hello() const;
       std::vector<byte> secure_renegotiation_data_for_server_hello() const;
diff --git a/src/lib/tls/tls_client.h b/src/lib/tls/tls_client.h
index 09af053af..d3cff147e 100644
--- a/src/lib/tls/tls_client.h
+++ b/src/lib/tls/tls_client.h
@@ -72,7 +72,7 @@ class BOTAN_DLL Client final : public Channel
       *
       * @param alert_cb is called when a TLS alert is received
       *
-      * @param handshake_cb is called when a handshake is completed
+      * @param hs_cb is called when a handshake is completed
       *
       * @param session_manager manages session state
       *
@@ -94,7 +94,7 @@ class BOTAN_DLL Client final : public Channel
       *        values just mean reallocations and copies are more likely.
       */
       BOTAN_DEPRECATED("Use TLS::Client(TLS::Callbacks ...)")
-      Client(output_fn out,
+      Client(output_fn output_fn,
              data_cb app_data_cb,
              alert_cb alert_cb,
              handshake_cb hs_cb,
@@ -127,6 +127,9 @@ class BOTAN_DLL Client final : public Channel
              const std::vector<std::string>& next_protocols = {}
          );
 
+      /**
+      * @return network protocol as advertised by the TLS server, if server sent the ALPN extension
+      */
       const std::string& application_protocol() const { return m_application_protocol; }
    private:
       void init(const Protocol_Version& protocol_version,
diff --git a/src/lib/tls/tls_handshake_msg.h b/src/lib/tls/tls_handshake_msg.h
index 618ae8d76..c1d3bfdc7 100644
--- a/src/lib/tls/tls_handshake_msg.h
+++ b/src/lib/tls/tls_handshake_msg.h
@@ -26,10 +26,19 @@ class Handshake_Hash;
 class BOTAN_DLL Handshake_Message
    {
    public:
+      /**
+      * @return string representation of this message type
+      */
       std::string type_string() const;
 
+      /**
+      * @return the message type
+      */
       virtual Handshake_Type type() const = 0;
 
+      /**
+      * @return DER representation of this message
+      */
       virtual std::vector<byte> serialize() const = 0;
 
       virtual ~Handshake_Message() {}
diff --git a/src/lib/tls/tls_messages.h b/src/lib/tls/tls_messages.h
index 25228c865..1e012a899 100644
--- a/src/lib/tls/tls_messages.h
+++ b/src/lib/tls/tls_messages.h
@@ -479,6 +479,7 @@ class BOTAN_DLL Certificate_Verify final : public Handshake_Message
       * Check the signature on a certificate verify message
       * @param cert the purported certificate
       * @param state the handshake state
+      * @param policy the TLS policy
       */
       bool verify(const X509_Certificate& cert,
                   const Handshake_State& state,
diff --git a/src/lib/tls/tls_policy.h b/src/lib/tls/tls_policy.h
index 47ac51685..f387361f6 100644
--- a/src/lib/tls/tls_policy.h
+++ b/src/lib/tls/tls_policy.h
@@ -248,19 +248,32 @@ class BOTAN_DLL Policy
       virtual std::vector<u16bit> ciphersuite_list(Protocol_Version version,
                                                    bool have_srp) const;
 
+      /**
+      * @return the default MTU for DTLS
+      */
       virtual size_t dtls_default_mtu() const;
 
+      /**
+      * @return the initial timeout for DTLS
+      */
       virtual size_t dtls_initial_timeout() const;
 
+      /**
+      * @return the maximum timeout for DTLS
+      */
       virtual size_t dtls_maximum_timeout() const;
 
+      /**
+      * Convert this policy to a printable format.
+      * @param o stream to be printed to
+      */
       virtual void print(std::ostream& o) const;
 
       virtual ~Policy() {}
    };
 
 /**
-* NSA Suite B 128-bit security level (see @rfc 6460)
+* NSA Suite B 128-bit security level (RFC 6460)
 */
 class BOTAN_DLL NSA_Suite_B_128 : public Policy
    {
@@ -291,7 +304,7 @@ class BOTAN_DLL NSA_Suite_B_128 : public Policy
    };
 
 /**
-* Policy for DTLS. We require DTLS v1.2 and an AEAD mode
+* Policy for DTLS. We require DTLS v1.2 and an AEAD mode.
 */
 class BOTAN_DLL Datagram_Policy : public Policy
    {
diff --git a/src/lib/tls/tls_record.h b/src/lib/tls/tls_record.h
index b17d0a7b6..d4a2a9372 100644
--- a/src/lib/tls/tls_record.h
+++ b/src/lib/tls/tls_record.h
@@ -149,14 +149,11 @@ class Record_Raw_Input
 /**
 * Create a TLS record
 * @param write_buffer the output record is placed here
-* @param msg_type is the type of the message (handshake, alert, ...)
-* @param msg is the plaintext message
-* @param msg_length is the length of msg
-* @param msg_sequence is the sequence number
+* @param rec_msg is the plaintext message
 * @param version is the protocol version
+* @param msg_sequence is the sequence number
 * @param cipherstate is the writing cipher state
 * @param rng is a random number generator
-* @return number of bytes written to write_buffer
 */
 void write_record(secure_vector<byte>& write_buffer,
                   Record_Message rec_msg,
diff --git a/src/lib/tls/tls_server_info.h b/src/lib/tls/tls_server_info.h
index 4ae291d3a..cd46aea3f 100644
--- a/src/lib/tls/tls_server_info.h
+++ b/src/lib/tls/tls_server_info.h
@@ -47,12 +47,25 @@ class BOTAN_DLL Server_Information
                         u16bit port = 0) :
          m_hostname(hostname), m_service(service), m_port(port) {}
 
+      /**
+      * @return the host's DNS name, if known
+      */
       std::string hostname() const { return m_hostname; }
 
+      /**
+      * @return text string of the service type, e.g.,
+      * "https", "tor", or "git"
+      */
       std::string service() const { return m_service; }
 
+      /**
+      * @return the protocol port of the server, or zero if unknown
+      */
       u16bit port() const { return m_port; }
 
+      /**
+      * @return whether the hostname is known
+      */
       bool empty() const { return m_hostname.empty(); }
 
    private:
diff --git a/src/lib/tls/tls_session.h b/src/lib/tls/tls_session.h
index 643b79ac6..5530632db 100644
--- a/src/lib/tls/tls_session.h
+++ b/src/lib/tls/tls_session.h
@@ -61,11 +61,14 @@ class BOTAN_DLL Session
 
       /**
       * Load a session from DER representation (created by DER_encode)
+      * @param ber DER representation buffer
+      * @param ber_len size of buffer in bytes
       */
       Session(const byte ber[], size_t ber_len);
 
       /**
       * Load a session from PEM representation (created by PEM_encode)
+      * @param pem PEM representation
       */
       explicit Session(const std::string& pem);
 
@@ -181,6 +184,9 @@ class BOTAN_DLL Session
       */
       const std::vector<byte>& session_ticket() const { return m_session_ticket; }
 
+      /**
+      * @return information about the TLS server
+      */
       const Server_Information& server_info() const { return m_server_info; }
 
    private:
diff --git a/src/lib/tls/tls_session_key.h b/src/lib/tls/tls_session_key.h
index 2ea18d636..8399a9676 100644
--- a/src/lib/tls/tls_session_key.h
+++ b/src/lib/tls/tls_session_key.h
@@ -14,27 +14,58 @@ namespace Botan {
 
 namespace TLS {
 
+class Handshake_State;
+
 /**
 * TLS Session Keys
 */
 class Session_Keys
    {
    public:
+      /**
+      * @return client encipherment key
+      */
       const SymmetricKey& client_cipher_key() const { return m_c_cipher; }
+
+      /**
+      * @return client encipherment key
+      */
       const SymmetricKey& server_cipher_key() const { return m_s_cipher; }
 
+      /**
+      * @return client MAC key
+      */
       const SymmetricKey& client_mac_key() const { return m_c_mac; }
+
+      /**
+      * @return server MAC key
+      */
       const SymmetricKey& server_mac_key() const { return m_s_mac; }
 
+      /**
+      * @return client IV
+      */
       const InitializationVector& client_iv() const { return m_c_iv; }
+
+      /**
+      * @return server IV
+      */
       const InitializationVector& server_iv() const { return m_s_iv; }
 
+      /**
+      * @return TLS master secret
+      */
       const secure_vector<byte>& master_secret() const { return m_master_sec; }
 
       Session_Keys() {}
 
-      Session_Keys(const class Handshake_State* state,
-                   const secure_vector<byte>& pre_master,
+      /**
+      * @param state state the handshake state
+      * @param pre_master_secret the pre-master secret
+      * @param resuming whether this TLS session is resumed
+      */
+      Session_Keys(const Handshake_State* state,
+                   const secure_vector<byte>& pre_master_secret,
                    bool resuming);
 
    private:
diff --git a/src/lib/tls/tls_session_manager.h b/src/lib/tls/tls_session_manager.h
index 49f4925d8..ca6712e1f 100644
--- a/src/lib/tls/tls_session_manager.h
+++ b/src/lib/tls/tls_session_manager.h
@@ -109,6 +109,8 @@ class BOTAN_DLL Session_Manager_In_Memory : public Session_Manager
    {
    public:
       /**
+      * @param rng a RNG used for generating session key and for
+      *        session encryption
       * @param max_sessions a hint on the maximum number of sessions
       *        to keep in memory at any one time. (If zero, don't cap)
       * @param session_lifetime sessions are expired after this many
diff --git a/src/lib/tls/tls_version.h b/src/lib/tls/tls_version.h
index 73968bb8c..29839502d 100644
--- a/src/lib/tls/tls_version.h
+++ b/src/lib/tls/tls_version.h
@@ -30,11 +30,17 @@ class BOTAN_DLL Protocol_Version
          DTLS_V12           = 0xFEFD
       };
 
+      /**
+      * @return latest known TLS version
+      */
       static Protocol_Version latest_tls_version()
          {
          return Protocol_Version(TLS_V12);
          }
 
+      /**
+      * @return latest known DTLS version
+      */
       static Protocol_Version latest_dtls_version()
          {
          return Protocol_Version(DTLS_V12);