docs/3.0-migration-guide.d/ssl-error-code-cleanup.md

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
  `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.