The recent session caching modifications (including docs, and CHANGES) were

applied to the "engine" 0.9.6 branch rather than the non-engine one. This
merges all the changes back across so they are in-sync w.r.t. these
changes.

6 files changed, 70 insertions, 19 deletions

diff --git a/CHANGES b/CHANGES
index 693d49b0ad..70e22b7da8 100644
--- a/CHANGES
+++ b/CHANGES
@@ -4,6 +4,16 @@
 
  Changes between 0.9.6g and 0.9.6h  [xx XXX xxxx]
 
+  *) Add a SSL_SESS_CACHE_NO_INTERNAL_STORE flag to take over half
+     the job SSL_SESS_CACHE_NO_INTERNAL_LOOKUP was inconsistently
+     doing, define a new flag (SSL_SESS_CACHE_NO_INTERNAL) to be
+     the bitwise-OR of the two for use by the majority of applications
+     wanting this behaviour, and update the docs. The documented
+     behaviour and actual behaviour were inconsistent and had been
+     changing anyway, so this is more a bug-fix than a behavioural
+     change.
+     [Geoff Thorpe, diagnosed by Nadav Har'El]
+
   *) Don't impose a 16-byte length minimum on session IDs in ssl/s3_clnt.c
      (the SSL 3.0 and TLS 1.0 specifications allow any length up to 32 bytes).
      [Bodo Moeller]
diff --git a/doc/ssl/SSL_CTX_add_session.pod b/doc/ssl/SSL_CTX_add_session.pod
index af326c2f73..82676b26b2 100644
--- a/doc/ssl/SSL_CTX_add_session.pod
+++ b/doc/ssl/SSL_CTX_add_session.pod
@@ -37,6 +37,14 @@ removed and replaced by the new session. If the session is actually
 identical (the SSL_SESSION object is identical), SSL_CTX_add_session()
 is a no-op, and the return value is 0.
 
+If a server SSL_CTX is configured with the SSL_SESS_CACHE_NO_INTERNAL_STORE
+flag then the internal cache will not be populated automatically by new
+sessions negotiated by the SSL/TLS implementation, even though the internal
+cache will be searched automatically for session-resume requests (the
+latter can be surpressed by SSL_SESS_CACHE_NO_INTERNAL_LOOKUP). So the
+application can use SSL_CTX_add_session() directly to have full control
+over the sessions that can be resumed if desired.
+
 
 =head1 RETURN VALUES
 
diff --git a/doc/ssl/SSL_CTX_set_session_cache_mode.pod b/doc/ssl/SSL_CTX_set_session_cache_mode.pod
index 9aa6c6b2e3..c5d2f43dff 100644
--- a/doc/ssl/SSL_CTX_set_session_cache_mode.pod
+++ b/doc/ssl/SSL_CTX_set_session_cache_mode.pod
@@ -26,12 +26,14 @@ SSL_CTX object is being maintained, the sessions are unique for each SSL_CTX
 object.
 
 In order to reuse a session, a client must send the session's id to the
-server. It can only send exactly one id.  The server then decides whether it
-agrees in reusing the session or starts the handshake for a new session.
+server. It can only send exactly one id.  The server then either 
+agrees to reuse the session or it starts a full handshake (to create a new
+session).
 
-A server will lookup up the session in its internal session storage. If
-the session is not found in internal storage or internal storage is
-deactivated, the server will try the external storage if available.
+A server will lookup up the session in its internal session storage. If the
+session is not found in internal storage or lookups for the internal storage
+have been deactivated (SSL_SESS_CACHE_NO_INTERNAL_LOOKUP), the server will try
+the external storage if available.
 
 Since a client may try to reuse a session intended for use in a different
 context, the session id context must be set by the server (see
@@ -57,9 +59,10 @@ function. This option is not activated by default.
 =item SSL_SESS_CACHE_SERVER
 
 Server sessions are added to the session cache. When a client proposes a
-session to be reused, the session is looked up in the internal session cache.
-If the session is found, the server will try to reuse the session.
-This is the default.
+session to be reused, the server looks for the corresponding session in (first)
+the internal session cache (unless SSL_SESS_CACHE_NO_INTERNAL_LOOKUP is set),
+then (second) in the external cache if available. If the session is found, the
+server will try to reuse the session.  This is the default.
 
 =item SSL_SESS_CACHE_BOTH
 
@@ -77,12 +80,32 @@ explicitly by the application.
 
 =item SSL_SESS_CACHE_NO_INTERNAL_LOOKUP
 
-By setting this flag sessions are cached in the internal storage but
-they are not looked up automatically. If an external session cache
-is enabled, sessions are looked up in the external cache. As automatic
-lookup only applies for SSL/TLS servers, the flag has no effect on
+By setting this flag, session-resume operations in an SSL/TLS server will not
+automatically look up sessions in the internal cache, even if sessions are
+automatically stored there. If external session caching callbacks are in use,
+this flag guarantees that all lookups are directed to the external cache.
+As automatic lookup only applies for SSL/TLS servers, the flag has no effect on
 clients.
 
+=item SSL_SESS_CACHE_NO_INTERNAL_STORE
+
+Depending on the presence of SSL_SESS_CACHE_CLIENT and/or SSL_SESS_CACHE_SERVER,
+sessions negotiated in an SSL/TLS handshake may be cached for possible reuse.
+Normally a new session is added to the internal cache as well as any external
+session caching (callback) that is configured for the SSL_CTX. This flag will
+prevent sessions being stored in the internal cache (though the application can
+add them manually using L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)>). Note:
+in any SSL/TLS servers where external caching is configured, any successful
+session lookups in the external cache (ie. for session-resume requests) would
+normally be copied into the local cache before processing continues - this flag
+prevents these additions to the internal cache as well.
+
+=item SSL_SESS_CACHE_NO_INTERNAL
+
+Enable both SSL_SESS_CACHE_NO_INTERNAL_LOOKUP and
+SSL_SESS_CACHE_NO_INTERNAL_STORE at the same time.
+
+
 =back
 
 The default mode is SSL_SESS_CACHE_SERVER.
@@ -98,6 +121,7 @@ SSL_CTX_get_session_cache_mode() returns the currently set cache mode.
 
 L<ssl(3)|ssl(3)>, L<SSL_set_session(3)|SSL_set_session(3)>,
 L<SSL_session_reused(3)|SSL_session_reused(3)>,
+L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)>,
 L<SSL_CTX_sess_number(3)|SSL_CTX_sess_number(3)>,
 L<SSL_CTX_sess_set_cache_size(3)|SSL_CTX_sess_set_cache_size(3)>,
 L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>,
@@ -105,4 +129,9 @@ L<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>,
 L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>,
 L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>
 
+=head1 HISTORY
+
+SSL_SESS_CACHE_NO_INTERNAL_STORE and SSL_SESS_CACHE_NO_INTERNAL
+were introduced in OpenSSL 0.9.6h.
+
 =cut
diff --git a/ssl/ssl.h b/ssl/ssl.h
index 3eecead605..ed2eae96e3 100644
--- a/ssl/ssl.h
+++ b/ssl/ssl.h
@@ -551,10 +551,11 @@ struct ssl_ctx_st
 #define SSL_SESS_CACHE_SERVER			0x0002
 #define SSL_SESS_CACHE_BOTH	(SSL_SESS_CACHE_CLIENT|SSL_SESS_CACHE_SERVER)
 #define SSL_SESS_CACHE_NO_AUTO_CLEAR		0x0080
-/* This one, when set, makes the server session-id lookup not look
- * in the cache.  If there is an application get_session callback
- * defined, this will still get called. */
+/* enough comments already ... see SSL_CTX_set_session_cache_mode(3) */
 #define SSL_SESS_CACHE_NO_INTERNAL_LOOKUP	0x0100
+#define SSL_SESS_CACHE_NO_INTERNAL_STORE	0x0200
+#define SSL_SESS_CACHE_NO_INTERNAL \
+	(SSL_SESS_CACHE_NO_INTERNAL_LOOKUP|SSL_SESS_CACHE_NO_INTERNAL_STORE)
 
   struct lhash_st *SSL_CTX_sessions(SSL_CTX *ctx);
 #define SSL_CTX_sess_number(ctx) \
diff --git a/ssl/ssl_lib.c b/ssl/ssl_lib.c
index 6b5a135ffe..6bc3d4d70e 100644
--- a/ssl/ssl_lib.c
+++ b/ssl/ssl_lib.c
@@ -1483,7 +1483,7 @@ void ssl_update_cache(SSL *s,int mode)
 
 	i=s->ctx->session_cache_mode;
 	if ((i & mode) && (!s->hit)
-		&& ((i & SSL_SESS_CACHE_NO_INTERNAL_LOOKUP)
+		&& ((i & SSL_SESS_CACHE_NO_INTERNAL_STORE)
 		    || SSL_CTX_add_session(s->ctx,s->session))
 		&& (s->ctx->new_session_cb != NULL))
 		{
diff --git a/ssl/ssl_sess.c b/ssl/ssl_sess.c
index 2f2d5bc27f..130fe1018a 100644
--- a/ssl/ssl_sess.c
+++ b/ssl/ssl_sess.c
@@ -258,9 +258,12 @@ int ssl_get_prev_session(SSL *s, unsigned char *session_id, int len)
 			if (copy)
 				CRYPTO_add(&ret->references,1,CRYPTO_LOCK_SSL_SESSION);
 
-			/* The following should not return 1, otherwise,
-			 * things are very strange */
-			SSL_CTX_add_session(s->ctx,ret);
+			/* Add the externally cached session to the internal
+			 * cache as well if and only if we are supposed to. */
+			if(!(s->ctx->session_cache_mode & SSL_SESS_CACHE_NO_INTERNAL_STORE))
+				/* The following should not return 1, otherwise,
+				 * things are very strange */
+				SSL_CTX_add_session(s->ctx,ret);
 			}
 		if (ret == NULL)
 			goto err;