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>
diff --git a/include/openssl/base.h b/include/openssl/base.h
index 9679c2f..e00d71c 100644
--- a/include/openssl/base.h
+++ b/include/openssl/base.h
@@ -235,6 +235,7 @@
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;
diff --git a/include/openssl/ssl.h b/include/openssl/ssl.h
index 4498249..1e1cbb4 100644
--- a/include/openssl/ssl.h
+++ b/include/openssl/ssl.h
@@ -1049,6 +1049,89 @@
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 @@
#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 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 @@
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 @@
/* 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. */
diff --git a/ssl/ssl_lib.c b/ssl/ssl_lib.c
index 9672e8c..a70d55a 100644
--- a/ssl/ssl_lib.c
+++ b/ssl/ssl_lib.c
@@ -2050,8 +2050,8 @@
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) {
diff --git a/ssl/ssl_sess.c b/ssl/ssl_sess.c
index 8baa79a..d08b682 100644
--- a/ssl/ssl_sess.c
+++ b/ssl/ssl_sess.c
@@ -210,11 +210,12 @@
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 @@
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 @@
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;
}
