1 // Copyright 2013 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 #include "net/socket/ssl_session_cache_openssl.h"
10 #include <openssl/rand.h>
11 #include <openssl/ssl.h>
13 #include "base/containers/hash_tables.h"
14 #include "base/lazy_instance.h"
15 #include "base/logging.h"
16 #include "base/synchronization/lock.h"
22 // A helper class to lazily create a new EX_DATA index to map SSL_CTX handles
23 // to their corresponding SSLSessionCacheOpenSSLImpl object.
24 class SSLContextExIndex
{
27 context_index_
= SSL_CTX_get_ex_new_index(0, NULL
, NULL
, NULL
, NULL
);
28 DCHECK_NE(-1, context_index_
);
29 session_index_
= SSL_SESSION_get_ex_new_index(0, NULL
, NULL
, NULL
, NULL
);
30 DCHECK_NE(-1, session_index_
);
33 int context_index() const { return context_index_
; }
34 int session_index() const { return session_index_
; }
42 base::LazyInstance
<SSLContextExIndex
>::Leaky s_ssl_context_ex_instance
=
43 LAZY_INSTANCE_INITIALIZER
;
45 // Retrieve the global EX_DATA index, created lazily on first call, to
46 // be used with SSL_CTX_set_ex_data() and SSL_CTX_get_ex_data().
47 static int GetSSLContextExIndex() {
48 return s_ssl_context_ex_instance
.Get().context_index();
51 // Retrieve the global EX_DATA index, created lazily on first call, to
52 // be used with SSL_SESSION_set_ex_data() and SSL_SESSION_get_ex_data().
53 static int GetSSLSessionExIndex() {
54 return s_ssl_context_ex_instance
.Get().session_index();
57 // Helper struct used to store session IDs in a SessionIdIndex container
58 // (see definition below). To save memory each entry only holds a pointer
59 // to the session ID buffer, which must outlive the entry itself. On the
60 // other hand, a hash is included to minimize the number of hashing
61 // computations during cache operations.
63 SessionId(const unsigned char* a_id
, unsigned a_id_len
)
64 : id(a_id
), id_len(a_id_len
), hash(ComputeHash(a_id
, a_id_len
)) {}
66 explicit SessionId(const SessionId
& other
)
67 : id(other
.id
), id_len(other
.id_len
), hash(other
.hash
) {}
69 explicit SessionId(SSL_SESSION
* session
)
70 : id(session
->session_id
),
71 id_len(session
->session_id_length
),
72 hash(ComputeHash(session
->session_id
, session
->session_id_length
)) {}
74 bool operator==(const SessionId
& other
) const {
75 return hash
== other
.hash
&& id_len
== other
.id_len
&&
76 !memcmp(id
, other
.id
, id_len
);
79 const unsigned char* id
;
84 // Session ID are random strings of bytes. This happens to compute the same
85 // value as std::hash<std::string> without the extra string copy. See
86 // base/containers/hash_tables.h. Other hashing computations are possible,
87 // this one is just simple enough to do the job.
88 size_t ComputeHash(const unsigned char* id
, unsigned id_len
) {
90 for (unsigned n
= 0; n
< id_len
; ++n
)
91 result
+= 131 * id
[n
];
100 namespace BASE_HASH_NAMESPACE
{
103 struct hash
<net::SessionId
> {
104 std::size_t operator()(const net::SessionId
& entry
) const {
109 } // namespace BASE_HASH_NAMESPACE
113 // Implementation of the real SSLSessionCache.
115 // The implementation is inspired by base::MRUCache, except that the deletor
116 // also needs to remove the entry from other containers. In a nutshell, this
117 // uses several basic containers:
119 // |ordering_| is a doubly-linked list of SSL_SESSION handles, ordered in
122 // |key_index_| is a hash table mapping unique cache keys (e.g. host/port
123 // values) to a single iterator of |ordering_|. It is used to efficiently
124 // find the cached session associated with a given key.
126 // |id_index_| is a hash table mapping SessionId values to iterators
127 // of |key_index_|. If is used to efficiently remove sessions from the cache,
128 // as well as check for the existence of a session ID value in the cache.
130 // SSL_SESSION objects are reference-counted, and owned by the cache. This
131 // means that their reference count is incremented when they are added, and
132 // decremented when they are removed.
134 // Assuming an average key size of 100 characters, each node requires the
135 // following memory usage on 32-bit Android, when linked against STLport:
137 // 12 (ordering_ node, including SSL_SESSION handle)
138 // 100 (key characters)
139 // + 24 (std::string header/minimum size)
140 // + 8 (key_index_ node, excluding the 2 lines above for the key).
141 // + 20 (id_index_ node)
145 // Hence, 41 KiB for a full cache with a maximum of 1024 entries, excluding
146 // the size of SSL_SESSION objects and heap fragmentation.
149 class SSLSessionCacheOpenSSLImpl
{
151 // Construct new instance. This registers various hooks into the SSL_CTX
152 // context |ctx|. OpenSSL will call back during SSL connection
153 // operations. |key_func| is used to map a SSL handle to a unique cache
154 // string, according to the client's preferences.
155 SSLSessionCacheOpenSSLImpl(SSL_CTX
* ctx
,
156 const SSLSessionCacheOpenSSL::Config
& config
)
157 : ctx_(ctx
), config_(config
), expiration_check_(0) {
160 // NO_INTERNAL_STORE disables OpenSSL's builtin cache, and
161 // NO_AUTO_CLEAR disables the call to SSL_CTX_flush_sessions
162 // every 256 connections (this number is hard-coded in the library
163 // and can't be changed).
164 SSL_CTX_set_session_cache_mode(ctx_
,
165 SSL_SESS_CACHE_CLIENT
|
166 SSL_SESS_CACHE_NO_INTERNAL_STORE
|
167 SSL_SESS_CACHE_NO_AUTO_CLEAR
);
169 SSL_CTX_sess_set_new_cb(ctx_
, NewSessionCallbackStatic
);
170 SSL_CTX_sess_set_remove_cb(ctx_
, RemoveSessionCallbackStatic
);
171 SSL_CTX_set_generate_session_id(ctx_
, GenerateSessionIdStatic
);
172 SSL_CTX_set_timeout(ctx_
, config_
.timeout_seconds
);
174 SSL_CTX_set_ex_data(ctx_
, GetSSLContextExIndex(), this);
177 // Destroy this instance. Must happen before |ctx_| is destroyed.
178 ~SSLSessionCacheOpenSSLImpl() {
180 SSL_CTX_set_ex_data(ctx_
, GetSSLContextExIndex(), NULL
);
181 SSL_CTX_sess_set_new_cb(ctx_
, NULL
);
182 SSL_CTX_sess_set_remove_cb(ctx_
, NULL
);
183 SSL_CTX_set_generate_session_id(ctx_
, NULL
);
186 // Return the number of items in this cache.
187 size_t size() const { return key_index_
.size(); }
189 // Retrieve the cache key from |ssl| and look for a corresponding
190 // cached session ID. If one is found, call SSL_set_session() to associate
191 // it with the |ssl| connection.
193 // Will also check for expired sessions every |expiration_check_count|
196 // Return true if a cached session ID was found, false otherwise.
197 bool SetSSLSession(SSL
* ssl
) {
198 std::string cache_key
= config_
.key_func(ssl
);
199 if (cache_key
.empty())
202 return SetSSLSessionWithKey(ssl
, cache_key
);
205 // Variant of SetSSLSession to be used when the client already has computed
206 // the cache key. Avoid a call to the configuration's |key_func| function.
207 bool SetSSLSessionWithKey(SSL
* ssl
, const std::string
& cache_key
) {
208 base::AutoLock
locked(lock_
);
210 DCHECK_EQ(config_
.key_func(ssl
), cache_key
);
212 if (++expiration_check_
>= config_
.expiration_check_count
) {
213 expiration_check_
= 0;
214 FlushExpiredSessionsLocked();
217 KeyIndex::iterator it
= key_index_
.find(cache_key
);
218 if (it
== key_index_
.end())
221 SSL_SESSION
* session
= *it
->second
;
224 DVLOG(2) << "Lookup session: " << session
<< " for " << cache_key
;
226 void* session_is_good
=
227 SSL_SESSION_get_ex_data(session
, GetSSLSessionExIndex());
228 if (!session_is_good
)
229 return false; // Session has not yet been marked good. Treat as a miss.
231 // Move to front of MRU list.
232 ordering_
.push_front(session
);
233 ordering_
.erase(it
->second
);
234 it
->second
= ordering_
.begin();
236 return SSL_set_session(ssl
, session
) == 1;
239 // Return true iff a cached session was associated with the given |cache_key|.
240 bool SSLSessionIsInCache(const std::string
& cache_key
) const {
241 base::AutoLock
locked(lock_
);
242 KeyIndex::const_iterator it
= key_index_
.find(cache_key
);
243 if (it
== key_index_
.end())
246 SSL_SESSION
* session
= *it
->second
;
249 void* session_is_good
=
250 SSL_SESSION_get_ex_data(session
, GetSSLSessionExIndex());
252 return session_is_good
;
255 void MarkSSLSessionAsGood(SSL
* ssl
) {
256 SSL_SESSION
* session
= SSL_get_session(ssl
);
259 // Mark the session as good, allowing it to be used for future connections.
260 SSL_SESSION_set_ex_data(
261 session
, GetSSLSessionExIndex(), reinterpret_cast<void*>(1));
264 // Flush all entries from the cache.
266 base::AutoLock
lock(lock_
);
269 while (!ordering_
.empty()) {
270 SSL_SESSION
* session
= ordering_
.front();
271 ordering_
.pop_front();
272 SSL_SESSION_free(session
);
277 // Type for list of SSL_SESSION handles, ordered in MRU order.
278 typedef std::list
<SSL_SESSION
*> MRUSessionList
;
279 // Type for a dictionary from unique cache keys to session list nodes.
280 typedef base::hash_map
<std::string
, MRUSessionList::iterator
> KeyIndex
;
281 // Type for a dictionary from SessionId values to key index nodes.
282 typedef base::hash_map
<SessionId
, KeyIndex::iterator
> SessionIdIndex
;
284 // Return the key associated with a given session, or the empty string if
285 // none exist. This shall only be used for debugging.
286 std::string
SessionKey(SSL_SESSION
* session
) {
288 return std::string("<null-session>");
290 if (session
->session_id_length
== 0)
291 return std::string("<empty-session-id>");
293 SessionIdIndex::iterator it
= id_index_
.find(SessionId(session
));
294 if (it
== id_index_
.end())
295 return std::string("<unknown-session>");
297 return it
->second
->first
;
300 // Remove a given |session| from the cache. Lock must be held.
301 void RemoveSessionLocked(SSL_SESSION
* session
) {
302 lock_
.AssertAcquired();
304 DCHECK_GT(session
->session_id_length
, 0U);
305 SessionId
session_id(session
);
306 SessionIdIndex::iterator id_it
= id_index_
.find(session_id
);
307 if (id_it
== id_index_
.end()) {
308 LOG(ERROR
) << "Trying to remove unknown session from cache: " << session
;
311 KeyIndex::iterator key_it
= id_it
->second
;
312 DCHECK(key_it
!= key_index_
.end());
313 DCHECK_EQ(session
, *key_it
->second
);
315 id_index_
.erase(session_id
);
316 ordering_
.erase(key_it
->second
);
317 key_index_
.erase(key_it
);
319 SSL_SESSION_free(session
);
321 DCHECK_EQ(key_index_
.size(), id_index_
.size());
324 // Used internally to flush expired sessions. Lock must be held.
325 void FlushExpiredSessionsLocked() {
326 lock_
.AssertAcquired();
328 // Unfortunately, OpenSSL initializes |session->time| with a time()
329 // timestamps, which makes mocking / unit testing difficult.
330 long timeout_secs
= static_cast<long>(::time(NULL
));
331 MRUSessionList::iterator it
= ordering_
.begin();
332 while (it
!= ordering_
.end()) {
333 SSL_SESSION
* session
= *it
++;
335 // Important, use <= instead of < here to allow unit testing to
336 // work properly. That's because unit tests that check the expiration
337 // behaviour will use a session timeout of 0 seconds.
338 if (session
->time
+ session
->timeout
<= timeout_secs
) {
339 DVLOG(2) << "Expiring session " << session
<< " for "
340 << SessionKey(session
);
341 RemoveSessionLocked(session
);
346 // Retrieve the cache associated with a given SSL context |ctx|.
347 static SSLSessionCacheOpenSSLImpl
* GetCache(SSL_CTX
* ctx
) {
349 void* result
= SSL_CTX_get_ex_data(ctx
, GetSSLContextExIndex());
351 return reinterpret_cast<SSLSessionCacheOpenSSLImpl
*>(result
);
354 // Called by OpenSSL when a new |session| was created and added to a given
355 // |ssl| connection. Note that the session's reference count was already
356 // incremented before the function is entered. The function must return 1
357 // to indicate that it took ownership of the session, i.e. that the caller
358 // should not decrement its reference count after completion.
359 static int NewSessionCallbackStatic(SSL
* ssl
, SSL_SESSION
* session
) {
360 SSLSessionCacheOpenSSLImpl
* cache
= GetCache(ssl
->ctx
);
361 cache
->OnSessionAdded(ssl
, session
);
365 // Called by OpenSSL to indicate that a session must be removed from the
366 // cache. This happens when SSL_CTX is destroyed.
367 static void RemoveSessionCallbackStatic(SSL_CTX
* ctx
, SSL_SESSION
* session
) {
368 GetCache(ctx
)->OnSessionRemoved(session
);
371 // Called by OpenSSL to generate a new session ID. This happens during a
372 // SSL connection operation, when the SSL object doesn't have a session yet.
374 // A session ID is a random string of bytes used to uniquely identify the
375 // session between a client and a server.
377 // |ssl| is a SSL connection handle. Ignored here.
378 // |id| is the target buffer where the ID must be generated.
379 // |*id_len| is, on input, the size of the desired ID. It will be 16 for
380 // SSLv2, and 32 for anything else. OpenSSL allows an implementation
381 // to change it on output, but this will not happen here.
383 // The function must ensure the generated ID is really unique, i.e. that
384 // another session in the cache doesn't already use the same value. It must
385 // return 1 to indicate success, or 0 for failure.
386 static int GenerateSessionIdStatic(const SSL
* ssl
,
389 if (!GetCache(ssl
->ctx
)->OnGenerateSessionId(id
, *id_len
))
395 // Add |session| to the cache in association with |cache_key|. If a session
396 // already exists, it is replaced with the new one. This assumes that the
397 // caller already incremented the session's reference count.
398 void OnSessionAdded(SSL
* ssl
, SSL_SESSION
* session
) {
399 base::AutoLock
locked(lock_
);
401 DCHECK_GT(session
->session_id_length
, 0U);
402 std::string cache_key
= config_
.key_func(ssl
);
403 KeyIndex::iterator it
= key_index_
.find(cache_key
);
404 if (it
== key_index_
.end()) {
405 DVLOG(2) << "Add session " << session
<< " for " << cache_key
;
406 // This is a new session. Add it to the cache.
407 ordering_
.push_front(session
);
408 std::pair
<KeyIndex::iterator
, bool> ret
=
409 key_index_
.insert(std::make_pair(cache_key
, ordering_
.begin()));
412 DCHECK(it
!= key_index_
.end());
414 // An existing session exists for this key, so replace it if needed.
415 DVLOG(2) << "Replace session " << *it
->second
<< " with " << session
416 << " for " << cache_key
;
417 SSL_SESSION
* old_session
= *it
->second
;
418 if (old_session
!= session
) {
419 id_index_
.erase(SessionId(old_session
));
420 SSL_SESSION_free(old_session
);
422 ordering_
.erase(it
->second
);
423 ordering_
.push_front(session
);
424 it
->second
= ordering_
.begin();
427 id_index_
[SessionId(session
)] = it
;
429 if (key_index_
.size() > config_
.max_entries
)
432 DCHECK_EQ(key_index_
.size(), id_index_
.size());
433 DCHECK_LE(key_index_
.size(), config_
.max_entries
);
436 // Shrink the cache to ensure no more than config_.max_entries entries,
437 // starting with older entries first. Lock must be acquired.
438 void ShrinkCacheLocked() {
439 lock_
.AssertAcquired();
440 DCHECK_EQ(key_index_
.size(), ordering_
.size());
441 DCHECK_EQ(key_index_
.size(), id_index_
.size());
443 while (key_index_
.size() > config_
.max_entries
) {
444 MRUSessionList::reverse_iterator it
= ordering_
.rbegin();
445 DCHECK(it
!= ordering_
.rend());
447 SSL_SESSION
* session
= *it
;
449 DVLOG(2) << "Evicting session " << session
<< " for "
450 << SessionKey(session
);
451 RemoveSessionLocked(session
);
455 // Remove |session| from the cache.
456 void OnSessionRemoved(SSL_SESSION
* session
) {
457 base::AutoLock
locked(lock_
);
458 DVLOG(2) << "Remove session " << session
<< " for " << SessionKey(session
);
459 RemoveSessionLocked(session
);
462 // See GenerateSessionIdStatic for a description of what this function does.
463 bool OnGenerateSessionId(unsigned char* id
, unsigned id_len
) {
464 base::AutoLock
locked(lock_
);
465 // This mimics def_generate_session_id() in openssl/ssl/ssl_sess.cc,
466 // I.e. try to generate a pseudo-random bit string, and check that no
467 // other entry in the cache has the same value.
468 const size_t kMaxTries
= 10;
469 for (size_t tries
= 0; tries
< kMaxTries
; ++tries
) {
470 if (RAND_pseudo_bytes(id
, id_len
) <= 0) {
471 DLOG(ERROR
) << "Couldn't generate " << id_len
472 << " pseudo random bytes?";
475 if (id_index_
.find(SessionId(id
, id_len
)) == id_index_
.end())
478 DLOG(ERROR
) << "Couldn't generate unique session ID of " << id_len
479 << "bytes after " << kMaxTries
<< " tries.";
484 SSLSessionCacheOpenSSL::Config config_
;
486 // method to get the index which can later be used with SSL_CTX_get_ex_data()
487 // or SSL_CTX_set_ex_data().
488 mutable base::Lock lock_
; // Protects access to containers below.
490 MRUSessionList ordering_
;
492 SessionIdIndex id_index_
;
494 size_t expiration_check_
;
497 SSLSessionCacheOpenSSL::~SSLSessionCacheOpenSSL() { delete impl_
; }
499 size_t SSLSessionCacheOpenSSL::size() const { return impl_
->size(); }
501 void SSLSessionCacheOpenSSL::Reset(SSL_CTX
* ctx
, const Config
& config
) {
505 impl_
= new SSLSessionCacheOpenSSLImpl(ctx
, config
);
508 bool SSLSessionCacheOpenSSL::SetSSLSession(SSL
* ssl
) {
509 return impl_
->SetSSLSession(ssl
);
512 bool SSLSessionCacheOpenSSL::SetSSLSessionWithKey(
514 const std::string
& cache_key
) {
515 return impl_
->SetSSLSessionWithKey(ssl
, cache_key
);
518 bool SSLSessionCacheOpenSSL::SSLSessionIsInCache(
519 const std::string
& cache_key
) const {
520 return impl_
->SSLSessionIsInCache(cache_key
);
523 void SSLSessionCacheOpenSSL::MarkSSLSessionAsGood(SSL
* ssl
) {
524 return impl_
->MarkSSLSessionAsGood(ssl
);
527 void SSLSessionCacheOpenSSL::Flush() { impl_
->Flush(); }