From 47532b63e947e020df15a03d91f9d67657cd11dd Mon Sep 17 00:00:00 2001 From: René Korthaus Date: Tue, 18 Oct 2016 09:54:45 +0200 Subject: Improve tls doxygen [ci skip] --- src/lib/tls/tls_channel.h | 18 ++++++++++++++++++ src/lib/tls/tls_client.h | 3 +++ src/lib/tls/tls_handshake_msg.h | 9 +++++++++ src/lib/tls/tls_policy.h | 13 +++++++++++++ src/lib/tls/tls_server_info.h | 13 +++++++++++++ src/lib/tls/tls_session.h | 6 ++++++ src/lib/tls/tls_session_key.h | 29 +++++++++++++++++++++++++++++ src/lib/tls/tls_session_manager.h | 2 ++ src/lib/tls/tls_version.h | 6 ++++++ 9 files changed, 99 insertions(+) (limited to 'src/lib/tls') 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 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& 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 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 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& 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& 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& 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); -- cgit v1.2.3