From 67e49a627d5d22b5ed67a593200b48f4654c032b Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Fri, 14 May 2021 20:02:42 +0100 Subject: [PATCH] Add migration guide Signed-off-by: Hanno Becker --- .../relaxed-psk-semantics.md | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 docs/3.0-migration-guide.d/relaxed-psk-semantics.md diff --git a/docs/3.0-migration-guide.d/relaxed-psk-semantics.md b/docs/3.0-migration-guide.d/relaxed-psk-semantics.md new file mode 100644 index 000000000..5af2b6108 --- /dev/null +++ b/docs/3.0-migration-guide.d/relaxed-psk-semantics.md @@ -0,0 +1,23 @@ +Relaxed semantics for PSK configuration +----------------------------------------------------------------- + +This affects users which call the PSK configuration APIs +`mbedtlsl_ssl_conf_psk()` and `mbedtls_ssl_conf_psk_opaque()` +multiple times on the same SSL configuration. + +In Mbed TLS 2.x, users would observe later calls overwriting +the effect of earlier calls, with the prevailing PSK being +the one that has been configured last. + +To achieve equivalent functionality when migrating to Mbed TLS 3.0, +users calling `mbedtls_ssl_conf_[opaque_]psk()` multiple times should +remove all but the last call, so that only one call to _either_ +`mbedtls_ssl_conf_psk()` _or_ `mbedtls_ssl_conf_psk_opaque()` +remains. + +However, if the _intent_ of the multiple calls to +`mbedtls_ssl_conf_[opaque_]psk()` was to offer multiple PSKs, then +users should _keep_ all calls and only check for the expected +non-fatal failure code `MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE` +indicating that no more PSKs could be buffered by the +implementation.