Revise SSL_CTX_sess_set_new_cb documentation.
This is a bit verbose, but this API is goofy and causes a lot of
confusion. This may be clearer.
Change-Id: I9affff99b838958058e56ee3062521421c9accc5
Reviewed-on: https://boringssl-review.googlesource.com/17645
Reviewed-by: David Benjamin <davidben@google.com>
Reviewed-by: Steven Valdez <svaldez@google.com>
Commit-Queue: David Benjamin <davidben@google.com>
Commit-Queue: Steven Valdez <svaldez@google.com>
diff --git a/include/openssl/ssl.h b/include/openssl/ssl.h
index 59fbeb8..f9f29b6 100644
--- a/include/openssl/ssl.h
+++ b/include/openssl/ssl.h
@@ -1874,12 +1874,17 @@
* unset), the callback is not called.
*
* The callback is passed a reference to |session|. It returns one if it takes
- * ownership and zero otherwise.
+ * ownership (and then calls |SSL_SESSION_free| when done) and zero otherwise. A
+ * consumer which places |session| into an in-memory cache will likely return
+ * one, with the cache calling |SSL_SESSION_free|. A consumer which serializes
+ * |session| with |SSL_SESSION_to_bytes| may not need to retain |session| and
+ * will likely return zero. Returning one is equivalent to calling
+ * |SSL_SESSION_up_ref| and then returning zero.
*
* Note: For a client, the callback may be called on abbreviated handshakes if a
* ticket is renewed. Further, it may not be called until some time after
* |SSL_do_handshake| or |SSL_connect| completes if False Start is enabled. Thus
- * it's recommended to use this callback over checking |SSL_session_reused| on
+ * it's recommended to use this callback over calling |SSL_get_session| on
* handshake completion. */
OPENSSL_EXPORT void SSL_CTX_sess_set_new_cb(
SSL_CTX *ctx, int (*new_session_cb)(SSL *ssl, SSL_SESSION *session));
