From 2e3ecda684f867a6304d1611e13859ea1312e5c3 Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Thu, 24 Jun 2021 11:22:22 +0100 Subject: [PATCH] Adust migration guide for SSL error codes Signed-off-by: Hanno Becker --- .../ssl-error-code-cleanup.md | 25 +++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/docs/3.0-migration-guide.d/ssl-error-code-cleanup.md b/docs/3.0-migration-guide.d/ssl-error-code-cleanup.md index 49d1a0f22..cad5a61b5 100644 --- a/docs/3.0-migration-guide.d/ssl-error-code-cleanup.md +++ b/docs/3.0-migration-guide.d/ssl-error-code-cleanup.md @@ -1,20 +1,41 @@ -Removal of some SSL error codes +Changes in the SSL error code space ----------------------------------------------------------------- +# Removals + This affects users manually checking for the following error codes: - `MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED` - `MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH` - `MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE` +- `MBEDTLS_ERR_SSL_BAD_HS_XXX` Migration paths: + - `MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED` and `MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH` should never be returned from Mbed TLS, and there is no need to check for it. + Users should simply remove manual checks for those codes, and let the Mbed TLS team know if -- contrary to the team's understanding -- there is in fact a situation where one of them was ever returned. + - `MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE` has been removed, and `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` is returned instead if the user's own certificate - is too large to fit into the output buffers. Users should check for + is too large to fit into the output buffers. + + Users should check for `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` instead, and potentially compare the size of their own certificate against the configured size of the output buffer to understand if the error is due to an overly large certificate. + +- All `MBEDTLS_ERR_SSL_BAD_HS_XXX` error code have been removed. + + Users should check for the newly introduced generic error codes + * `MBEDTLS_ERR_SSL_DECODE_ERROR` + * `MBEDTLS_ERR_SSL_ILLEGAL_PARAMETER`, + * `MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE` + * `MBEDTLS_ERR_SSL_BAD_PROTOCOL_VERSION` + * `MBEDTLS_ERR_SSL_BAD_CERTIFICATE` + * `MBEDTLS_ERR_SSL_UNRECOGNIZED_NAME` + instead. + + Users should check for the generic error codes instead.