aboutsummaryrefslogtreecommitdiffstats
path: root/src/lib/tls
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/tls')
-rw-r--r--src/lib/tls/tls_callbacks.h14
-rw-r--r--src/lib/tls/tls_channel.h24
-rw-r--r--src/lib/tls/tls_client.h7
-rw-r--r--src/lib/tls/tls_handshake_msg.h9
-rw-r--r--src/lib/tls/tls_messages.h1
-rw-r--r--src/lib/tls/tls_policy.h17
-rw-r--r--src/lib/tls/tls_record.h7
-rw-r--r--src/lib/tls/tls_server_info.h13
-rw-r--r--src/lib/tls/tls_session.h6
-rw-r--r--src/lib/tls/tls_session_key.h35
-rw-r--r--src/lib/tls/tls_session_manager.h2
-rw-r--r--src/lib/tls/tls_version.h6
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);
generated by cgit v1.2.3 (git 2.39.1) at 2024-12-26 07:00:01 +0000