| // 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); |
| |
| // Indicates that the SSL session associated with |ssl| is "good" - that is, |
| // that all associated cryptographic parameters that were negotiated, |
| // including the peer's certificate, were successfully validated. Because |
| // OpenSSL does not provide an asynchronous certificate verification |
| // callback, it's necessary to manually manage the sessions to ensure that |
| // only validated sessions are resumed. |
| void MarkSSLSessionAsGood(SSL* ssl); |
| |
| // 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 |