From b491b2b051cde5357dd1e9d4caf0c1faf1aa573d Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Wed, 30 Jun 2021 09:46:07 +0100 Subject: [PATCH] Add SSL error code updates from #4724 Signed-off-by: Dave Rodgman --- docs/3.0-migration-guide.md | 31 +++++++++++++++++++++++++------ 1 file changed, 25 insertions(+), 6 deletions(-) diff --git a/docs/3.0-migration-guide.md b/docs/3.0-migration-guide.md index 2b20b5ce6..4ac677633 100644 --- a/docs/3.0-migration-guide.md +++ b/docs/3.0-migration-guide.md @@ -902,7 +902,7 @@ find themselves unable to migrate their session cache functionality without accessing fields of `mbedtls_ssl_session` should describe their use case on the Mbed TLS mailing list. -### Removal of some SSL error codes +### Changes in the SSL error code space This affects users manually checking for the following error codes: @@ -916,11 +916,11 @@ This affects users manually checking for the following error codes: 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. @@ -928,10 +928,29 @@ Migration paths: 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. - -- `MBEDTLS_ERR_SSL_NO_CIPHER_CHOSEN` and `MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE` have been replaced by `MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE` -- all codes of the form `MBEDTLS_ERR_SSL_BAD_HS_XXX` have been replaced by various alternatives. +- `MBEDTLS_ERR_SSL_NO_CIPHER_CHOSEN` and `MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE` have been + replaced by `MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE`. + +- All codes of the form `MBEDTLS_ERR_SSL_BAD_HS_XXX` have been replaced by various alternatives. + + 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` + * `MBEDTLS_ERR_SSL_UNSUPPORTED_EXTENSION` + * `MBEDTLS_ERR_SSL_NO_APPLICATION_PROTOCOL` + + and the pre-existing generic error codes + + * `MBEDTLS_ERR_SSL_UNEXPECTED_MESSAGE` + * `MBEDTLS_ERR_SSL_INTERNAL_ERROR` + + instead. ### Modified semantics of `mbedtls_ssl_{get,set}_session()`