Document functions acting on an SSL_SESSION.

Change-Id: I0b4386d1972af0ac10db397716de8161810a87f4
Reviewed-on: https://boringssl-review.googlesource.com/5877
Reviewed-by: Adam Langley <agl@google.com>

include/openssl/base.h

@@ -235,6 +235,7 @@ typedef struct ssl_cipher_st SSL_CIPHER;
 typedef struct ssl_ctx_st SSL_CTX;
 typedef struct ssl_custom_extension SSL_CUSTOM_EXTENSION;
 typedef struct ssl_method_st SSL_METHOD;
+typedef struct ssl_session_st SSL_SESSION;
 typedef struct ssl_st SSL;
 typedef struct st_ERR_FNS ERR_FNS;
 typedef struct v3_ext_ctx X509V3_CTX;

include/openssl/ssl.h

@@ -1049,6 +1049,89 @@ OPENSSL_EXPORT int SSL_CTX_add_server_custom_ext(
     SSL_custom_ext_parse_cb parse_cb, void *parse_arg);
 
 
+/* Sessions.
+ *
+ * An |SSL_SESSION| represents an SSL session that may be resumed in an
+ * abbreviated handshake. It is reference-counted and immutable. Once
+ * established, an |SSL_SESSION| may be shared by multiple |SSL| objects on
+ * different threads and must not be modified. */
+
+/* SSL_SESSION_new returns a newly-allocated blank |SSL_SESSION| or NULL on
+ * error. This may be useful in writing tests but otherwise should not be
+ * used outside the library. */
+OPENSSL_EXPORT SSL_SESSION *SSL_SESSION_new(void);
+
+/* SSL_SESSION_up_ref, if |session| is not NULL, increments the reference count
+ * of |session|. It then returns |session|. */
+OPENSSL_EXPORT SSL_SESSION *SSL_SESSION_up_ref(SSL_SESSION *session);
+
+/* SSL_SESSION_free decrements the reference count of |session|. If it reaches
+ * zero, all data referenced by |session| and |session| itself are released. */
+OPENSSL_EXPORT void SSL_SESSION_free(SSL_SESSION *session);
+
+/* SSL_SESSION_to_bytes serializes |in| into a newly allocated buffer and sets
+ * |*out_data| to that buffer and |*out_len| to its length. The caller takes
+ * ownership of the buffer and must call |OPENSSL_free| when done. It returns
+ * one on success and zero on error. */
+OPENSSL_EXPORT int SSL_SESSION_to_bytes(SSL_SESSION *in, uint8_t **out_data,
+                                        size_t *out_len);
+
+/* SSL_SESSION_to_bytes_for_ticket serializes |in|, but excludes the session
+ * identification information, namely the session ID and ticket. */
+OPENSSL_EXPORT int SSL_SESSION_to_bytes_for_ticket(SSL_SESSION *in,
+                                                   uint8_t **out_data,
+                                                   size_t *out_len);
+
+/* SSL_SESSION_from_bytes parses |in_len| bytes from |in| as an SSL_SESSION. It
+ * returns a newly-allocated |SSL_SESSION| on success or NULL on error. */
+OPENSSL_EXPORT SSL_SESSION *SSL_SESSION_from_bytes(const uint8_t *in,
+                                                   size_t in_len);
+
+/* SSL_SESSION_get_version returns a string describing the TLS version |session|
+ * was established at. For example, "TLSv1.2" or "SSLv3". */
+OPENSSL_EXPORT const char *SSL_SESSION_get_version(const SSL_SESSION *session);
+
+/* SSL_SESSION_get_id returns a pointer to a buffer containg |session|'s session
+ * ID and sets |*out_len| to its length. */
+OPENSSL_EXPORT const uint8_t *SSL_SESSION_get_id(const SSL_SESSION *session,
+                                                 unsigned *out_len);
+
+/* SSL_SESSION_get_time returns the time at which |session| was established in
+ * seconds since the UNIX epoch. */
+OPENSSL_EXPORT long SSL_SESSION_get_time(const SSL_SESSION *session);
+
+/* SSL_SESSION_get_timeout returns the lifetime of |session| in seconds. */
+OPENSSL_EXPORT long SSL_SESSION_get_timeout(const SSL_SESSION *session);
+
+/* SSL_SESSION_get_key_exchange_info returns a value that describes the
+ * strength of the asymmetric operation that provides confidentiality to
+ * |session|. Its interpretation depends on the operation used. See the
+ * documentation for this value in the |SSL_SESSION| structure. */
+OPENSSL_EXPORT uint32_t SSL_SESSION_get_key_exchange_info(SSL_SESSION *session);
+
+/* SSL_SESSION_get0_peer return's the peer leaf certificate stored in
+ * |session|. */
+OPENSSL_EXPORT X509 *SSL_SESSION_get0_peer(SSL_SESSION *session);
+
+/* SSL_SESSION_set_time sets |session|'s creation time to |time| and returns
+ * |time|. This function may be useful in writing tests but otherwise should not
+ * be used. */
+OPENSSL_EXPORT long SSL_SESSION_set_time(SSL_SESSION *session, long time);
+
+/* SSL_SESSION_set_time sets |session|'s timeout to |timeout| and returns one.
+ * This function may be useful in writing tests but otherwise should not be
+ * used. */
+OPENSSL_EXPORT long SSL_SESSION_set_timeout(SSL_SESSION *session, long timeout);
+
+/* SSL_SESSION_set1_id_context sets |session|'s session ID context (see
+ * |SSL_CTX_set_session_id_context|) to |sid_ctx|. It returns one on success and
+ * zero on error. This function may be useful in writing tests but otherwise
+ * should not be used. */
+OPENSSL_EXPORT int SSL_SESSION_set1_id_context(SSL_SESSION *session,
+                                               const uint8_t *sid_ctx,
+                                               unsigned sid_ctx_len);
+
+
 /* Session tickets. */
 
 /* SSL_CTX_get_tlsext_ticket_keys writes |ctx|'s session ticket key material to
@@ -1186,11 +1269,6 @@ OPENSSL_EXPORT int SSL_CTX_set_tlsext_ticket_key_cb(
 #define SSL_RECEIVED_SHUTDOWN 2
 
 typedef struct ssl_protocol_method_st SSL_PROTOCOL_METHOD;
-
-/* An SSL_SESSION represents an SSL session that may be resumed in an
- * abbreviated handshake. */
-typedef struct ssl_session_st SSL_SESSION;
-
 typedef struct ssl_conf_ctx_st SSL_CONF_CTX;
 typedef struct ssl3_enc_method SSL3_ENC_METHOD;
 
@@ -1770,36 +1848,10 @@ OPENSSL_EXPORT int SSL_add_dir_cert_subjects_to_stack(STACK_OF(X509_NAME) *
 
 OPENSSL_EXPORT const char *SSL_state_string(const SSL *s);
 OPENSSL_EXPORT const char *SSL_state_string_long(const SSL *s);
-OPENSSL_EXPORT long SSL_SESSION_get_time(const SSL_SESSION *s);
-OPENSSL_EXPORT long SSL_SESSION_set_time(SSL_SESSION *s, long t);
-OPENSSL_EXPORT long SSL_SESSION_get_timeout(const SSL_SESSION *s);
-OPENSSL_EXPORT long SSL_SESSION_set_timeout(SSL_SESSION *s, long t);
-
-/* SSL_SESSION_get_key_exchange_info returns a value that describes the
- * strength of the asymmetric operation that provides confidentiality to
- * |session|. Its interpretation depends on the operation used. See the
- * documentation for this value in the |SSL_SESSION| structure. */
-OPENSSL_EXPORT uint32_t SSL_SESSION_get_key_exchange_info(SSL_SESSION *session);
-
-OPENSSL_EXPORT X509 *SSL_SESSION_get0_peer(SSL_SESSION *s);
-OPENSSL_EXPORT int SSL_SESSION_set1_id_context(SSL_SESSION *s,
-                                               const uint8_t *sid_ctx,
-                                               unsigned int sid_ctx_len);
 
-OPENSSL_EXPORT SSL_SESSION *SSL_SESSION_new(void);
-OPENSSL_EXPORT const uint8_t *SSL_SESSION_get_id(const SSL_SESSION *s,
-                                                 unsigned int *len);
 OPENSSL_EXPORT int SSL_SESSION_print_fp(FILE *fp, const SSL_SESSION *ses);
 OPENSSL_EXPORT int SSL_SESSION_print(BIO *fp, const SSL_SESSION *ses);
 
-/* SSL_SESSION_up_ref, if |session| is not NULL, increments the reference count
- * of |session|. It then returns |session|. */
-OPENSSL_EXPORT SSL_SESSION *SSL_SESSION_up_ref(SSL_SESSION *session);
-
-/* SSL_SESSION_free decrements the reference count of |session|. If it reaches
- * zero, all data referenced by |session| and |session| itself are released. */
-OPENSSL_EXPORT void SSL_SESSION_free(SSL_SESSION *session);
-
 OPENSSL_EXPORT int SSL_set_session(SSL *to, SSL_SESSION *session);
 OPENSSL_EXPORT int SSL_CTX_add_session(SSL_CTX *s, SSL_SESSION *c);
 OPENSSL_EXPORT int SSL_CTX_remove_session(SSL_CTX *, SSL_SESSION *c);
@@ -1809,24 +1861,6 @@ OPENSSL_EXPORT int SSL_has_matching_session_id(const SSL *ssl,
                                                const uint8_t *id,
                                                unsigned int id_len);
 
-/* SSL_SESSION_to_bytes serializes |in| into a newly allocated buffer and sets
- * |*out_data| to that buffer and |*out_len| to its length. The caller takes
- * ownership of the buffer and must call |OPENSSL_free| when done. It returns
- * one on success and zero on error. */
-OPENSSL_EXPORT int SSL_SESSION_to_bytes(SSL_SESSION *in, uint8_t **out_data,
-                                        size_t *out_len);
-
-/* SSL_SESSION_to_bytes_for_ticket serializes |in|, but excludes the session
- * identification information, namely the session ID and ticket. */
-OPENSSL_EXPORT int SSL_SESSION_to_bytes_for_ticket(SSL_SESSION *in,
-                                                   uint8_t **out_data,
-                                                   size_t *out_len);
-
-/* SSL_SESSION_from_bytes parses |in_len| bytes from |in| as an SSL_SESSION. It
- * returns a newly-allocated |SSL_SESSION| on success or NULL on error. */
-OPENSSL_EXPORT SSL_SESSION *SSL_SESSION_from_bytes(const uint8_t *in,
-                                                   size_t in_len);
-
 OPENSSL_EXPORT int SSL_CTX_get_verify_mode(const SSL_CTX *ctx);
 OPENSSL_EXPORT int SSL_CTX_get_verify_depth(const SSL_CTX *ctx);
 OPENSSL_EXPORT int (*SSL_CTX_get_verify_callback(const SSL_CTX *ctx))(
@@ -1863,9 +1897,6 @@ OPENSSL_EXPORT X509_VERIFY_PARAM *SSL_get0_param(SSL *ssl);
 /* SSL_get_version returns a string describing the TLS version used by |s|. For
  * example, "TLSv1.2" or "SSLv3". */
 OPENSSL_EXPORT const char *SSL_get_version(const SSL *s);
-/* SSL_SESSION_get_version returns a string describing the TLS version used by
- * |sess|. For example, "TLSv1.2" or "SSLv3". */
-OPENSSL_EXPORT const char *SSL_SESSION_get_version(const SSL_SESSION *sess);
 
 /* SSL_get_curve_name returns a human-readable name for the elliptic curve
  * specified by the given TLS curve id, or NULL if the curve if unknown. */

ssl/ssl_lib.c

@@ -2050,8 +2050,8 @@ const char *SSL_get_version(const SSL *s) {
   return ssl_get_version(s->version);
 }
 
-const char *SSL_SESSION_get_version(const SSL_SESSION *sess) {
-  return ssl_get_version(sess->ssl_version);
+const char *SSL_SESSION_get_version(const SSL_SESSION *session) {
+  return ssl_get_version(session->ssl_version);
 }
 
 const char* SSL_get_curve_name(uint16_t curve_id) {

ssl/ssl_sess.c

@@ -210,11 +210,12 @@ SSL_SESSION *SSL_SESSION_new(void) {
   return ss;
 }
 
-const uint8_t *SSL_SESSION_get_id(const SSL_SESSION *s, unsigned int *len) {
-  if (len) {
-    *len = s->session_id_length;
+const uint8_t *SSL_SESSION_get_id(const SSL_SESSION *session,
+                                  unsigned *out_len) {
+  if (out_len != NULL) {
+    *out_len = session->session_id_length;
   }
-  return s->session_id;
+  return session->session_id;
 }
 
 /* Even with SSLv2, we have 16 bytes (128 bits) of session ID space.
@@ -630,12 +631,12 @@ int SSL_set_session(SSL *s, SSL_SESSION *session) {
   return 1;
 }
 
-long SSL_SESSION_set_timeout(SSL_SESSION *s, long t) {
-  if (s == NULL) {
+long SSL_SESSION_set_timeout(SSL_SESSION *session, long timeout) {
+  if (session == NULL) {
     return 0;
   }
 
-  s->timeout = t;
+  session->timeout = timeout;
   return 1;
 }
 
@@ -647,30 +648,30 @@ long SSL_SESSION_get_time(const SSL_SESSION *session) {
   return session->time;
 }
 
-long SSL_SESSION_set_time(SSL_SESSION *s, long t) {
-  if (s == NULL) {
+long SSL_SESSION_set_time(SSL_SESSION *session, long time) {
+  if (session == NULL) {
     return 0;
   }
 
-  s->time = t;
-  return t;
+  session->time = time;
+  return time;
 }
 
 uint32_t SSL_SESSION_get_key_exchange_info(SSL_SESSION *session) {
   return session->key_exchange_info;
 }
 
-X509 *SSL_SESSION_get0_peer(SSL_SESSION *s) { return s->peer; }
+X509 *SSL_SESSION_get0_peer(SSL_SESSION *session) { return session->peer; }
 
-int SSL_SESSION_set1_id_context(SSL_SESSION *s, const uint8_t *sid_ctx,
-                                unsigned int sid_ctx_len) {
+int SSL_SESSION_set1_id_context(SSL_SESSION *session, const uint8_t *sid_ctx,
+                                unsigned sid_ctx_len) {
   if (sid_ctx_len > SSL_MAX_SID_CTX_LENGTH) {
     OPENSSL_PUT_ERROR(SSL, SSL_R_SSL_SESSION_ID_CONTEXT_TOO_LONG);
     return 0;
   }
 
-  s->sid_ctx_length = sid_ctx_len;
-  memcpy(s->sid_ctx, sid_ctx, sid_ctx_len);
+  session->sid_ctx_length = sid_ctx_len;
+  memcpy(session->sid_ctx, sid_ctx, sid_ctx_len);
 
   return 1;
 }