diff options
author | David Benjamin <davidben@google.com> | 2021-09-10 11:53:20 -0400 |
---|---|---|
committer | Adam Langley <agl@google.com> | 2021-09-13 16:22:16 +0000 |
commit | 62c4f15478c87ed88b25a8bf3f7c6c358af97e63 (patch) | |
tree | 07a7fdea828ec2b932384aaeb4ef1e06c6b82f8f /include | |
parent | 019cc625bd5ea80174a5ab7b2528e8953563dd0d (diff) | |
download | boringssl-62c4f15478c87ed88b25a8bf3f7c6c358af97e63.zip boringssl-62c4f15478c87ed88b25a8bf3f7c6c358af97e63.tar.gz boringssl-62c4f15478c87ed88b25a8bf3f7c6c358af97e63.tar.bz2 |
Clarify that TLS sessions are not application sessions.
Having APIs named "session" and "ID" appears to be far too tempting for
developers, mistaking it as some application-level notion of session.
Update the documentation, in hopes of discouraging this mistake.
Change-Id: Ifd9516287092371d4701114771eff6640df1bcb0
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/49405
Reviewed-by: Adam Langley <agl@google.com>
Diffstat (limited to 'include')
-rw-r--r-- | include/openssl/ssl.h | 18 |
1 files changed, 18 insertions, 0 deletions
diff --git a/include/openssl/ssl.h b/include/openssl/ssl.h index eae3c4b..5965cb4 100644 --- a/include/openssl/ssl.h +++ b/include/openssl/ssl.h @@ -1649,6 +1649,11 @@ OPENSSL_EXPORT int SSL_export_keying_material( // 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. +// +// Note the TLS notion of "session" is not suitable for application-level +// session state. It is an optional caching mechanism for the handshake. Not all +// connections within an application-level session will reuse TLS sessions. TLS +// sessions may be dropped by the client or ignored by the server at any time. DECLARE_PEM_rw(SSL_SESSION, SSL_SESSION) @@ -1703,6 +1708,19 @@ OPENSSL_EXPORT int SSL_SESSION_set_protocol_version(SSL_SESSION *session, // SSL_SESSION_get_id returns a pointer to a buffer containing |session|'s // session ID and sets |*out_len| to its length. +// +// This function should only be used for implementing a TLS session cache. TLS +// sessions are not suitable for application-level session state, and a session +// ID is an implementation detail of the TLS resumption handshake mechanism. Not +// all resumption flows use session IDs, and not all connections within an +// application-level session will reuse TLS sessions. +// +// To determine if resumption occurred, use |SSL_session_reused| instead. +// Comparing session IDs will not give the right result in all cases. +// +// As a workaround for some broken applications, BoringSSL sometimes synthesizes +// arbitrary session IDs for non-ID-based sessions. This behavior may be +// removed in the future. OPENSSL_EXPORT const uint8_t *SSL_SESSION_get_id(const SSL_SESSION *session, unsigned *out_len); |