Improve tls doxygen [ci skip]

9 files changed, 99 insertions, 0 deletions

diff --git a/src/lib/tls/tls_channel.h b/src/lib/tls/tls_channel.h
index 073af760f..ac5b4e377 100644
--- a/src/lib/tls/tls_channel.h
+++ b/src/lib/tls/tls_channel.h
@@ -41,6 +41,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,
diff --git a/src/lib/tls/tls_client.h b/src/lib/tls/tls_client.h
index 09af053af..1b67a1022 100644
--- a/src/lib/tls/tls_client.h
+++ b/src/lib/tls/tls_client.h
@@ -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_policy.h b/src/lib/tls/tls_policy.h
index 47ac51685..73af80547 100644
--- a/src/lib/tls/tls_policy.h
+++ b/src/lib/tls/tls_policy.h
@@ -248,12 +248,25 @@ 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() {}
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..1faee7801 100644
--- a/src/lib/tls/tls_session_key.h
+++ b/src/lib/tls/tls_session_key.h
@@ -20,19 +20,48 @@ namespace TLS {
 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() {}
 
+      /**
+      * @param state state the handshake state
+      * @param pre_master the pre-master secret
+      * @param resuming whether this TLS session is resumed
+      */
       Session_Keys(const class Handshake_State* state,
                    const secure_vector<byte>& pre_master,
                    bool resuming);
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);