1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
|
/*
* TLS Callbacks
* (C) 2016 Matthias Gierlings
* 2016 Jack Lloyd
*
* Botan is released under the Simplified BSD License (see license.txt)
*/
#ifndef BOTAN_TLS_CALLBACKS_H__
#define BOTAN_TLS_CALLBACKS_H__
#include <botan/tls_session.h>
#include <botan/tls_alert.h>
namespace Botan {
namespace TLS {
class Handshake_Message;
/**
* Encapsulates the callbacks that a TLS channel will make which are due to
* channel specific operations.
*/
class BOTAN_DLL Callbacks
{
public:
virtual ~Callbacks();
/**
* Mandatory callback: output function
* The channel will call this with data which needs to be sent to the peer
* (eg, over a socket or some other form of IPC). The array will be overwritten
* when the function returns so a copy must be made if the data cannot be
* sent immediately.
*
* @param data the vector of data to send
*
* @param size the number of bytes to send
*/
virtual void tls_emit_data(const uint8_t data[], size_t size) = 0;
/**
* Mandatory callback: process application data
* Called when application data record is received from the peer.
* Again the array is overwritten immediately after the function returns.
*
* @param seq_no the underlying TLS/DTLS record sequence number
*
* @param data the vector containing the received record
*
* @param size the length of the received record, in bytes
*/
virtual void tls_record_received(u64bit seq_no, const uint8_t data[], size_t size) = 0;
/**
* Mandary callback: alert received
* Called when an alert is received from the peer
* If fatal, the connection is closing. If not fatal, the connection may
* still be closing (depending on the error and the peer).
*
* @param alert the source of the alert
*/
virtual void tls_alert(Alert alert) = 0;
/**
* Mandatory callback: session established
* Called when a session is established. Throw an exception to abort
* the connection.
*
* @param session the session descriptor
*
* @return return false to prevent the session from being cached,
* return true to cache the session in the configured session manager
*/
virtual bool tls_session_established(const Session& session) = 0;
/**
* Optional callback: session activated
* Called when a session is active and can be written to
*/
virtual void tls_session_activated() {}
/**
* Optional callback: inspect handshake message
* Throw an exception to abort the handshake.
* Default simply ignores the message.
*
* @param message the handshake message
*/
virtual void tls_inspect_handshake_msg(const Handshake_Message& message);
/**
* Optional callback for server: choose ALPN protocol
* ALPN (RFC 7301) works by the client sending a list of application
* protocols it is willing to negotiate. The server then selects which
* protocol to use, which is not necessarily even on the list that
* the client sent.
*
* @param client_protos the vector of protocols the client is willing to negotiate
*
* @return the protocol selected by the server, which need not be on the
* list that the client sent; if this is the empty string, the server ignores the
* client ALPN extension. Default return value is empty string.
*/
virtual std::string tls_server_choose_app_protocol(const std::vector<std::string>& client_protos);
/**
* Optional callback: error logging. (not currently called)
* @param err An error message related to this connection.
*/
virtual void tls_log_error(const char* err)
{
BOTAN_UNUSED(err);
}
/**
* Optional callback: debug logging. (not currently called)
* @param what Some hopefully informative string
*/
virtual void tls_log_debug(const char* what)
{
BOTAN_UNUSED(what);
}
/**
* Optional callback: debug logging taking a buffer. (not currently called)
* @param descr What this buffer is
* @param val the bytes
* @param val_len length of val
*/
virtual void tls_log_debug_bin(const char* descr, const uint8_t val[], size_t val_len)
{
BOTAN_UNUSED(descr);
BOTAN_UNUSED(val);
BOTAN_UNUSED(val_len);
}
};
/**
* TLS::Callbacks using std::function for compatability with the old API signatures.
* This type is only provided for backward compatibility.
* New implementations should derive from TLS::Callbacks instead.
*/
class BOTAN_DLL Compat_Callbacks final : public Callbacks
{
public:
typedef std::function<void (const byte[], size_t)> output_fn;
typedef std::function<void (const byte[], size_t)> data_cb;
typedef std::function<void (Alert, const byte[], size_t)> alert_cb;
typedef std::function<bool (const Session&)> handshake_cb;
typedef std::function<void (const Handshake_Message&)> handshake_msg_cb;
typedef std::function<std::string (std::vector<std::string>)> next_protocol_fn;
/**
* @param output_fn is called with data for the outbound socket
*
* @param app_data_cb is called when new application data is received
*
* @param alert_cb is called when a TLS alert is received
*
* @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 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(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 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(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) {}
void tls_emit_data(const byte data[], size_t size) override
{
BOTAN_ASSERT(m_output_function != nullptr,
"Invalid TLS output function callback.");
m_output_function(data, size);
}
void tls_record_received(u64bit /*seq_no*/, const byte data[], size_t size) override
{
BOTAN_ASSERT(m_app_data_cb != nullptr,
"Invalid TLS app data callback.");
m_app_data_cb(data, size);
}
void tls_alert(Alert alert) override
{
BOTAN_ASSERT(m_alert_cb != nullptr,
"Invalid TLS alert callback.");
m_alert_cb(alert);
}
bool tls_session_established(const Session& session) override
{
BOTAN_ASSERT(m_hs_cb != nullptr,
"Invalid TLS handshake callback.");
return m_hs_cb(session);
}
std::string tls_server_choose_app_protocol(const std::vector<std::string>& client_protos) override
{
if(m_next_proto != nullptr) { return m_next_proto(client_protos); }
return "";
}
void tls_inspect_handshake_msg(const Handshake_Message& hmsg) override
{
// The handshake message callback is optional so we can
// not assume it has been set.
if(m_hs_msg_cb != nullptr) { m_hs_msg_cb(hmsg); }
}
private:
const output_fn m_output_function;
const data_cb m_app_data_cb;
const std::function<void (Alert)> m_alert_cb;
const handshake_cb m_hs_cb;
const handshake_msg_cb m_hs_msg_cb;
const next_protocol_fn m_next_proto;
};
}
}
#endif
|
