Adust migration guide for SSL error codes
Signed-off-by: Hanno Becker <hanno.becker@arm.com>
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 49d1a0f..cad5a61 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.
