From 64898a5e5caff176d9f70bdde4bacd3f7d9e9c0a Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Wed, 25 Feb 2026 08:40:28 +0100 Subject: [PATCH 1/5] Add warning in mbedtls_ssl_context_save/load documentation Signed-off-by: Ronald Cron --- include/mbedtls/ssl.h | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h index 6b98ad4584..d0114240b0 100644 --- a/include/mbedtls/ssl.h +++ b/include/mbedtls/ssl.h @@ -5138,6 +5138,27 @@ void mbedtls_ssl_free(mbedtls_ssl_context *ssl); * * \see mbedtls_ssl_context_load() * + * \warning The serialized data contains highly sensitive material, + * including the master secret from which the session's traffic + * keys are derived. + * + * The serialized data is not cryptographically protected. + * It is the responsibility of the user of the + * mbedtls_ssl_context_save() and + * mbedtls_ssl_context_load() APIs to ensure both its + * confidentiality and integrity while stored or transported. + * + * A breach of confidentiality could result in full compromise + * of the associated TLS session, including loss of + * confidentiality and integrity of past and future + * application data protected under that session. + * + * A breach of integrity may allow modification of the + * serialized data prior to restoration. As it represents + * trusted internal context, tampering could potentially result + * in arbitrary code execution or other severe compromise of + * the hosting process. + * \note The serialized data only contains the data that is * necessary to resume the connection: negotiated protocol * options, session identifier, keys, etc. @@ -5204,6 +5225,27 @@ int mbedtls_ssl_context_save(mbedtls_ssl_context *ssl, * more than one context would cause severe security failures * including but not limited to loss of confidentiality. * + * \warning The serialized data contains highly sensitive material, + * including the master secret from which the session's traffic + * keys are derived. + * + * The serialized data is not cryptographically protected. + * It is the responsibility of the user of the + * mbedtls_ssl_context_save() and + * mbedtls_ssl_context_load() APIs to ensure both its + * confidentiality and integrity while stored or transported. + * + * A breach of confidentiality could result in full compromise + * of the associated TLS session, including loss of + * confidentiality and integrity of past and future + * application data protected under that session. + * + * A breach of integrity may allow modification of the + * serialized data prior to restoration. As it represents + * trusted internal context, tampering could potentially result + * in arbitrary code execution or other severe compromise of + * the hosting process. + * * \note Before calling this function, the SSL context must be * prepared in one of the two following ways. The first way is * to take a context freshly initialised with From d5d7131eb5f0e9f66d17e65829fa3028d47e50a9 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Wed, 25 Feb 2026 09:04:08 +0100 Subject: [PATCH 2/5] Add warning in mbedtls_ssl_session_load/save documentation Signed-off-by: Ronald Cron --- include/mbedtls/ssl.h | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h index d0114240b0..fac87623af 100644 --- a/include/mbedtls/ssl.h +++ b/include/mbedtls/ssl.h @@ -3156,6 +3156,27 @@ int mbedtls_ssl_set_session(mbedtls_ssl_context *ssl, const mbedtls_ssl_session * On server, this can be used for alternative implementations * of session cache or session tickets. * + * \warning The serialized data contains highly sensitive material, + * including a resumption key (TLS 1.3) or the master secret + * (TLS 1.2) from which the session's traffic keys are derived. + * + * The serialized data is not cryptographically protected. + * It is the responsibility of the user of the + * mbedtls_ssl_session_save() and + * mbedtls_ssl_session_load() APIs to ensure both its + * confidentiality and integrity while stored or transported. + * + * A breach of confidentiality could result in full compromise + * of the associated TLS session, including loss of + * confidentiality and integrity of past and future + * application data protected under that session. + * + * A breach of integrity may allow modification of the + * serialized data prior to restoration. As it represents + * trusted internal context, tampering could potentially result + * in arbitrary code execution or other severe compromise of + * the hosting process. + * * \warning If a peer certificate chain is associated with the session, * the serialized state will only contain the peer's * end-entity certificate and the result of the chain @@ -3194,6 +3215,27 @@ int mbedtls_ssl_session_load(mbedtls_ssl_session *session, * * \see mbedtls_ssl_session_load() * + * \warning The serialized data contains highly sensitive material, + * including a resumption key (TLS 1.3) or the master secret + * (TLS 1.2) from which the session's traffic keys are derived. + * + * The serialized data is not cryptographically protected. + * It is the responsibility of the user of the + * mbedtls_ssl_session_save() and + * mbedtls_ssl_session_load() APIs to ensure both its + * confidentiality and integrity while stored or transported. + * + * A breach of confidentiality could result in full compromise + * of the associated TLS session, including loss of + * confidentiality and integrity of past and future + * application data protected under that session. + * + * A breach of integrity may allow modification of the + * serialized data prior to restoration. As it represents + * trusted internal context, tampering could potentially result + * in arbitrary code execution or other severe compromise of + * the hosting process. + * * \param session The session structure to be saved. * \param buf The buffer to write the serialized data to. It must be a * writeable buffer of at least \p buf_len bytes, or may be \c From 027ed1fef0fcd6450d8ba1c21e8fc86d40e6ee4b Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Wed, 25 Feb 2026 18:56:12 +0100 Subject: [PATCH 3/5] Reduce duplication between save/load documentations Signed-off-by: Ronald Cron --- include/mbedtls/ssl.h | 24 ++++-------------------- 1 file changed, 4 insertions(+), 20 deletions(-) diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h index fac87623af..1fa66f00c8 100644 --- a/include/mbedtls/ssl.h +++ b/include/mbedtls/ssl.h @@ -3225,16 +3225,8 @@ int mbedtls_ssl_session_load(mbedtls_ssl_session *session, * mbedtls_ssl_session_load() APIs to ensure both its * confidentiality and integrity while stored or transported. * - * A breach of confidentiality could result in full compromise - * of the associated TLS session, including loss of - * confidentiality and integrity of past and future - * application data protected under that session. - * - * A breach of integrity may allow modification of the - * serialized data prior to restoration. As it represents - * trusted internal context, tampering could potentially result - * in arbitrary code execution or other severe compromise of - * the hosting process. + * See the mbedtls_ssl_session_load() documentation for + * additional information. * * \param session The session structure to be saved. * \param buf The buffer to write the serialized data to. It must be a @@ -5190,17 +5182,9 @@ void mbedtls_ssl_free(mbedtls_ssl_context *ssl); * mbedtls_ssl_context_load() APIs to ensure both its * confidentiality and integrity while stored or transported. * - * A breach of confidentiality could result in full compromise - * of the associated TLS session, including loss of - * confidentiality and integrity of past and future - * application data protected under that session. + * See the mbedtls_ssl_context_load() documentation for + * additional information. * - * A breach of integrity may allow modification of the - * serialized data prior to restoration. As it represents - * trusted internal context, tampering could potentially result - * in arbitrary code execution or other severe compromise of - * the hosting process. - * \note The serialized data only contains the data that is * necessary to resume the connection: negotiated protocol * options, session identifier, keys, etc. From 894cea1fa2e81ec2c410b78a680573e3f056d537 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Mon, 16 Mar 2026 11:05:21 +0100 Subject: [PATCH 4/5] Add change log Signed-off-by: Ronald Cron --- ChangeLog.d/context_load_and_session_load_documentation.txt | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 ChangeLog.d/context_load_and_session_load_documentation.txt diff --git a/ChangeLog.d/context_load_and_session_load_documentation.txt b/ChangeLog.d/context_load_and_session_load_documentation.txt new file mode 100644 index 0000000000..f7c1d27f8e --- /dev/null +++ b/ChangeLog.d/context_load_and_session_load_documentation.txt @@ -0,0 +1,6 @@ +Security + * The documentation of mbedtls_ssl_session_save(), + mbedtls_ssl_session_load(), mbedtls_ssl_context_save(), and + mbedtls_ssl_context_load() has been updated to clarify the responsibility + of the application to preserve the confidentiality and integrity of + serialized data, mitigating the risk of misuse of these APIs. From ccea2fd244d9f96637149ff0c56d1a1241c58c2b Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Tue, 17 Mar 2026 11:06:04 +0100 Subject: [PATCH 5/5] Improve change log Signed-off-by: Ronald Cron --- ChangeLog.d/context_load_and_session_load_documentation.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/ChangeLog.d/context_load_and_session_load_documentation.txt b/ChangeLog.d/context_load_and_session_load_documentation.txt index f7c1d27f8e..200ab27bf1 100644 --- a/ChangeLog.d/context_load_and_session_load_documentation.txt +++ b/ChangeLog.d/context_load_and_session_load_documentation.txt @@ -4,3 +4,5 @@ Security mbedtls_ssl_context_load() has been updated to clarify the responsibility of the application to preserve the confidentiality and integrity of serialized data, mitigating the risk of misuse of these APIs. + Credit to Haruto Kimura (Stella) for highlighting risks associated with + tampered serialized data.