Botan 3.14.1
Crypto and TLS for C&
tls_session_manager.h
Go to the documentation of this file.
1/*
2* TLS Session Manager
3* (C) 2011-2023 Jack Lloyd
4* 2022-2023 René Meusel - Rohde & Schwarz Cybersecurity
5*
6* Botan is released under the Simplified BSD License (see license.txt)
7*/
8
9#ifndef BOTAN_TLS_SESSION_MANAGER_H_
10#define BOTAN_TLS_SESSION_MANAGER_H_
11
12#include <botan/mutex.h>
13#include <botan/tls_session_id.h>
14#include <botan/types.h>
15#include <memory>
16#include <optional>
17#include <utility>
18#include <vector>
19
20namespace Botan {
21
23
24}
25
26namespace Botan::TLS {
27
28class Callbacks;
29class Policy;
30class PskIdentity;
32class Session;
34
35/**
36* Session_Manager is an interface to systems which can save session parameters
37* for supporting session resumption.
38*
39* Saving sessions is done on a best-effort basis; an implementation is
40* allowed to drop sessions due to space constraints or other issues.
41*
42* Implementations should strive to be thread safe. This base class provides a
43* recursive mutex (via Session_Manager::mutex()). Derived classes may simply
44* reuse this for their own locking.
45*/
46class BOTAN_PUBLIC_API(3, 0) Session_Manager /* NOLINT(*-special-member-functions) */ {
47 public:
48 BOTAN_FUTURE_EXPLICIT Session_Manager(const std::shared_ptr<RandomNumberGenerator>& rng);
49
50 /**
51 * @brief Save a new Session and assign a Session_Handle (TLS Server)
52 *
53 * Save a new session on a best effort basis; the manager may not in fact
54 * be able to save the session for whatever reason; this is not an error.
55 * Callers cannot assume that calling establish() followed immediately by
56 * retrieve() or choose_from_offered_tickets() will result in a successful
57 * lookup. In case no session was stored, std::nullopt is returned.
58 *
59 * This method is only called on TLS servers.
60 *
61 * Note that implementations will silently refrain from sending session
62 * tickets to the client when this method returns std::nullopt.
63 *
64 * @param session to save
65 * @param id to use (instead of an ID chosen by the manager)
66 * @param tls12_no_ticket disable tickets for this establishment
67 * (set when TLS 1.2 client does not support them)
68 * @return a Session_Handle containing either an ID or a ticket
69 * if the session was saved, otherwise std::nullopt
70 */
71 virtual std::optional<Session_Handle> establish(const Session& session,
72 const std::optional<Session_ID>& id = std::nullopt,
73 bool tls12_no_ticket = false);
74
75 /**
76 * @brief Save a Session under a Session_Handle (TLS Client)
77 *
78 * Save a session on a best effort basis; the manager may not in fact be
79 * able to save the session for whatever reason; this is not an error.
80 * Callers cannot assume that calling store() followed immediately by
81 * find() will result in a successful lookup.
82 *
83 * In contrast to establish(), this stores sessions that were created by
84 * the server along with a Session_Handle also coined by the server.
85 *
86 * This method is only called on TLS clients.
87 *
88 * @param session to save
89 * @param handle a Session_Handle on which this session should by stored
90 */
91 virtual void store(const Session& session, const Session_Handle& handle) = 0;
92
93#if defined(BOTAN_HAS_TLS_13)
94 /**
95 * Lets the server application choose a PSK to use for a new TLS
96 * connection. Implementers must make sure that the PSK's associated
97 * hash function is equal to the passed @p hash_function.
98 *
99 * RFC 8446 4.2.11
100 * The server MUST ensure that it selects a compatible PSK (if any)
101 * and cipher suite.
102 *
103 * The default implementation simply tries to retrieve all tickets in
104 * the order offered by the peer and picks the first that is found and
105 * features a matching hash algorithm.
106 *
107 * This method is called only by TLS 1.3 servers. Implementations must
108 * only return sessions that were established by a TLS server (via
109 * Session_Manager::establish()), as applications may share a single
110 * manager between a client and a server role. The TLS server treats a
111 * session that was stored by a TLS client as an internal error. The
112 * default implementation relies on Session_Manager::retrieve() for this.
113 *
114 * @param tickets a list of tickets that were offered by the client
115 * @param hash_function the hash algorithm name we are going to use for
116 * the to-be-negotiated connection
117 * @param callbacks callbacks to be used for session policy decisions
118 * @param policy policy to be used for session policy decisions
119 *
120 * @return a std::pair of the Session associated to the chosen PSK and
121 * the index of the selected ticket; std::nullopt if no PSK was
122 * chosen for usage (will result in a full handshake)
123 *
124 * @note if no PSK is chosen, the server will attempt a regular handshake.
125 */
126 virtual std::optional<std::pair<Session, uint16_t>> choose_from_offered_tickets(
127 const std::vector<PskIdentity>& tickets,
128 std::string_view hash_function,
129 Callbacks& callbacks,
130 const Policy& policy);
131#endif
132
133 /**
134 * @brief Retrieves a specific session given a @p handle
135 *
136 * This is typically used by TLS servers to obtain resumption information
137 * for a previous call to Session_Manager::establish() when a client
138 * requested resumption using the @p handle.
139 *
140 * Even if the session is found successfully, it is returned only if it
141 * passes policy validations. Most notably an expiry check. If the expiry
142 * check fails, the default implementation calls Session_Manager::remove()
143 * for the provided @p handle.
144 *
145 * Sessions that were stored by a TLS client (via Session_Manager::store())
146 * are never returned, as applications may share a single manager between
147 * a client and a server role. Such sessions are not removed; they remain
148 * valid for the client role. Overriding implementations must uphold this;
149 * the TLS server treats a client session returned here as an internal
150 * error.
151 *
152 * Applications that wish to implement their own Session_Manager may
153 * override the default implementation to add further policy checks.
154 * Though, typically implementing Session_Manager::retrieve_one() and
155 * relying on the default implementation is enough.
156 *
157 * @param handle the Session_Handle to be retrieved
158 * @param callbacks callbacks to be used for session policy decisions
159 * @param policy policy to be used for session policy decisions
160 * @return the obtained session or std::nullopt if no session
161 * was found or the policy checks failed
162 */
163 virtual std::optional<Session> retrieve(const Session_Handle& handle, Callbacks& callbacks, const Policy& policy);
164
165 /**
166 * @brief Find all sessions that match a given server @p info
167 *
168 * TLS clients use this to obtain session resumption information for a
169 * server they are wishing to handshake with. Typically, session info will
170 * have been received in prior connections to that same server and stored
171 * using Session_Manager::store().
172 *
173 * The default implementation will invoke Session_Manager::find_some() and
174 * filter the result against a policy. Most notably an expiry check.
175 * Expired sessions will be removed via Session_Manager::remove().
176 *
177 * Sessions that were established by a TLS server (via
178 * Session_Manager::establish()) are never returned, as applications may
179 * share a single manager between a client and a server role. Such
180 * sessions are not removed; they remain valid for the server role.
181 *
182 * The TLS client implementations will query the session manager exactly
183 * once per handshake attempt. If no reuse is desired, the session manager
184 * may remove the sessions internally when handing them out to the client.
185 * The default implementation adheres to Policy::reuse_session_tickets().
186 *
187 * For TLS 1.2 the client implementation will attempt a resumption with
188 * the first session in the returned list. For TLS 1.3, it will offer all
189 * found sessions to the server.
190 *
191 * Applications that wish to implement their own Session_Manager may
192 * override the default implementation to add further policy checks.
193 * Though, typically implementing Session_Manager::find_some() and
194 * relying on the default implementation is enough.
195 *
196 * @param info the info about the server we want to handshake with
197 * @param callbacks callbacks to be used for session policy decisions
198 * @param policy policy to be used for session policy decisions
199 * @return a list of usable sessions that might be empty if no
200 * such session exists or passed the policy validation
201 */
202 virtual std::vector<Session_with_Handle> find(const Server_Information& info,
203 Callbacks& callbacks,
204 const Policy& policy);
205
206 /**
207 * Remove a specific session from the cache, if it exists.
208 * The handle might contain either a session ID or a ticket.
209 *
210 * @param handle a Session_Handle of the session to be removed
211 * @return the number of sessions that were removed
212 */
213 virtual size_t remove(const Session_Handle& handle) = 0;
214
215 /**
216 * Remove all sessions from the cache
217 * @return the number of sessions that were removed
218 */
219 virtual size_t remove_all() = 0;
220
221 /**
222 * Declares whether the given Session_Manager implementation may emit
223 * session tickets. Note that this _does not_ mean that the implementation
224 * must always emit tickets.
225 *
226 * Concrete implementations should declare this, to allow the TLS
227 * implementations to act accordingly. E.g. to advertise support for
228 * session tickets in their Server Hello.
229 *
230 * @return true if the Session_Manager produces session tickets
231 */
232 virtual bool emits_session_tickets() { return false; }
233
234 virtual ~Session_Manager() = default;
235
236 protected:
237 /**
238 * @brief Internal retrieval function for a single session
239 *
240 * Try to obtain a Session from a Session_Handle that contains either
241 * a session ID or a session ticket. This method should not apply any
242 * policy decision (such as ticket expiry) but simply be a storage
243 * interface.
244 *
245 * Applications that wish to implement their own Session_Manager will
246 * have to provide an implementation for it.
247 *
248 * This method is called only by servers. Sessions that were stored by a
249 * TLS client (via Session_Manager::store()) must not be returned, as
250 * applications may share a single manager between a client and a server
251 * role. Session_Manager::retrieve() discards them regardless.
252 *
253 * @param handle a Session_Handle containing either an ID or a ticket
254 * @return the obtained session or std::nullopt if none can be obtained
255 */
256 virtual std::optional<Session> retrieve_one(const Session_Handle& handle) = 0;
257
258 /**
259 * @brief Internal retrieval function to find sessions to resume
260 *
261 * Try to find saved sessions using info about the server we're planning
262 * to connect to. It should return a list of sessions in preference order
263 * of the session manager.
264 *
265 * Applications that wish to implement their own Session_Manager will
266 * have to provide an implementation for it.
267 *
268 * Note that the TLS client implementations do not perform any checks on
269 * the validity of the session for a given @p info. Particularly, it is
270 * the Session_Manager's responsibility to ensure the restrictions posed
271 * in RFC 8446 4.6.1 regarding server certificate validity for the given
272 * @p info.
273 *
274 * This is called for TLS clients only. Sessions that were established by
275 * a TLS server (via Session_Manager::establish()) must not be returned,
276 * as applications may share a single manager between a client and a
277 * server role. Session_Manager::find() discards them regardless, but
278 * they would use up the @p max_sessions_hint budget.
279 *
280 * @param info the information about the server
281 * @param max_sessions_hint a non-binding guideline for an upper bound of
282 * sessions to return from this method
283 * (will be at least 1 but potentially more)
284 * @return the found sessions along with their handles (containing either a
285 * session ID or a ticket)
286 */
287 virtual std::vector<Session_with_Handle> find_some(const Server_Information& info, size_t max_sessions_hint) = 0;
288
289 /**
290 * Returns the base class' recursive mutex for reuse in derived classes
291 */
292 recursive_mutex_type& mutex() { return m_mutex; }
293
294 private:
295 std::vector<Session_with_Handle> find_and_filter(const Server_Information& info,
296 Callbacks& callbacks,
297 const Policy& policy);
298
299 protected:
300 std::shared_ptr<RandomNumberGenerator> m_rng; // NOLINT(*non-private-member-variable*)
301
302 private:
303 recursive_mutex_type m_mutex;
304};
305
306} // namespace Botan::TLS
307
308#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:21
#define BOTAN_FUTURE_EXPLICIT
Definition api.h:52
Helper class to embody a session handle in all protocol versions.
virtual std::optional< std::pair< Session, uint16_t > > choose_from_offered_tickets(const std::vector< PskIdentity > &tickets, std::string_view hash_function, Callbacks &callbacks, const Policy &policy)
virtual ~Session_Manager()=default
virtual size_t remove(const Session_Handle &handle)=0
virtual std::optional< Session > retrieve_one(const Session_Handle &handle)=0
Internal retrieval function for a single session.
virtual void store(const Session &session, const Session_Handle &handle)=0
Save a Session under a Session_Handle (TLS Client).
recursive_mutex_type & mutex()
BOTAN_FUTURE_EXPLICIT Session_Manager(const std::shared_ptr< RandomNumberGenerator > &rng)
virtual std::vector< Session_with_Handle > find_some(const Server_Information &info, size_t max_sessions_hint)=0
Internal retrieval function to find sessions to resume.
virtual std::optional< Session_Handle > establish(const Session &session, const std::optional< Session_ID > &id=std::nullopt, bool tls12_no_ticket=false)
Save a new Session and assign a Session_Handle (TLS Server).
virtual std::vector< Session_with_Handle > find(const Server_Information &info, Callbacks &callbacks, const Policy &policy)
Find all sessions that match a given server info.
std::shared_ptr< RandomNumberGenerator > m_rng
virtual size_t remove_all()=0
virtual std::optional< Session > retrieve(const Session_Handle &handle, Callbacks &callbacks, const Policy &policy)
Retrieves a specific session given a handle.
noop_mutex recursive_mutex_type
Definition mutex.h:41