net: Implement new SSL session cache for OpenSSL sockets.

net/socket/ssl_session_cache_openssl.h

+// Copyright 2013 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef NET_SOCKET_SSL_SESSION_CACHE_OPENSSL_H
+#define NET_SOCKET_SSL_SESSION_CACHE_OPENSSL_H
+
+#include <string>
+
+#include "base/basictypes.h"
+#include "net/base/net_export.h"
+
+// Avoid including OpenSSL headers here.
+typedef struct ssl_ctx_st SSL_CTX;
+typedef struct ssl_st SSL;
+
+namespace net {
+
+class SSLSessionCacheOpenSSLImpl;
+
+// A class used to implement a custom cache of SSL_SESSION objects.
+// Usage is as follows:
+//
+//  - Client creates a new cache instance with appropriate configuration,
+//    associating it with a given SSL_CTX object.
+//
+//    The configuration must include a pointer to a client-provided function
+//    that can retrieve a unique cache key from an existing SSL handle.
+//
+//  - When creating a new SSL connection, call SetSSLSession() with the newly
+//    created SSL handle, and a cache key for the current host/port. If a
+//    session is already in the cache, it will be added to the connection
+//    through SSL_set_session().
+//
+//  - Otherwise, OpenSSL will create a new SSL_SESSION object during the
+//    connection, and will pass it to the cache's internal functions,
+//    transparently to the client.
+//
+//  - Each session has a timeout in seconds, which are checked every N-th call
+//    to SetSSLSession(), where N is the current configuration's
+//    |check_expiration_count|. Expired sessions are removed automatically
+//    from the cache.
+//
+//  - Clients can call Flush() to remove all sessions from the cache, this is
+//    useful when the system's certificate store has changed.
+//
+// This class is thread-safe. There shouldn't be any issue with multiple
+// SSL connections being performed in parallel in multiple threads.
+class NET_EXPORT SSLSessionCacheOpenSSL {
+ public:
+  // Type of a function that takes a SSL handle and returns a unique cache
+  // key string to identify it.
+  typedef std::string GetSessionKeyFunction(const SSL* ssl);
+
+  // A small structure used to configure a cache on creation.
+  // |key_func| is a function used at runtime to retrieve the unique cache key
+  // from a given SSL connection handle.
+  // |max_entries| is the maximum number of entries in the cache.
+  // |expiration_check_count| is the number of calls to SetSSLSession() that
+  // will trigger a check for expired sessions.
+  // |timeout_seconds| is the timeout of new cached sessions in seconds.
+  struct Config {
+    GetSessionKeyFunction* key_func;
+    size_t max_entries;
+    size_t expiration_check_count;
+    int timeout_seconds;
+  };
+
+  SSLSessionCacheOpenSSL() : impl_(NULL) {}
+
+  // Construct a new cache instance.
+  // |ctx| is a SSL_CTX context handle that will be associated with this cache.
+  // |key_func| is a function that will be used at runtime to retrieve the
+  // unique cache key from a SSL connection handle.
+  // |max_entries| is the maximum number of entries in the cache.
+  // |timeout_seconds| is the timeout of new cached sessions in seconds.
+  // |expiration_check_count| is the number of calls to SetSSLSession() that
+  // will trigger a check for expired sessions.
+  SSLSessionCacheOpenSSL(SSL_CTX* ctx, const Config& config) : impl_(NULL) {
+    Reset(ctx, config);
+  }
+
+  // Destroy this instance. This must be called before the SSL_CTX handle
+  // is destroyed.
+  ~SSLSessionCacheOpenSSL();
+
+  // Reset the cache configuration. This flushes any existing entries.
+  void Reset(SSL_CTX* ctx, const Config& config);
+
+  size_t size() const;
+
+  // Lookup the unique cache key associated with |ssl| connection handle,
+  // and find a cached session for it in the cache. If one is found, associate
+  // it with the |ssl| connection through SSL_set_session(). Consider using
+  // SetSSLSessionWithKey() if you already have the key.
+  //
+  // Every |check_expiration_count| call to either SetSSLSession() or
+  // SetSSLSessionWithKey() triggers a check for, and removal of, expired
+  // sessions.
+  //
+  // Return true iff a cached session was associated with the |ssl| connection.
+  bool SetSSLSession(SSL* ssl);
+
+  // A more efficient variant of SetSSLSession() that can be used if the caller
+  // already has the cache key for the session of interest. The caller must
+  // ensure that the value of |cache_key| matches the result of calling the
+  // configuration's |key_func| function with the |ssl| as parameter.
+  //
+  // Every |check_expiration_count| call to either SetSSLSession() or
+  // SetSSLSessionWithKey() triggers a check for, and removal of, expired
+  // sessions.
+  //
+  // Return true iff a cached session was associated with the |ssl| connection.
+  bool SetSSLSessionWithKey(SSL* ssl, const std::string& cache_key);
+
+  // Flush removes all entries from the cache. This is typically called when
+  // the system's certificate store has changed.
+  void Flush();
+
+  // TODO(digit): Move to client code.
+  static const int kDefaultTimeoutSeconds = 60 * 60;
+  static const size_t kMaxEntries = 1024;
+  static const size_t kMaxExpirationChecks = 256;
+
+ private:
+  DISALLOW_COPY_AND_ASSIGN(SSLSessionCacheOpenSSL);
+
+  SSLSessionCacheOpenSSLImpl* impl_;
+};
+
+}  // namespace net
+
+#endif  // NET_SOCKET_SSL_SESSION_CACHE_OPENSSL_H