diff --git a/ChangeLog.d/ssl-error-code-cleanup.txt b/ChangeLog.d/ssl-error-code-cleanup.txt new file mode 100644 index 000000000..768d1905a --- /dev/null +++ b/ChangeLog.d/ssl-error-code-cleanup.txt @@ -0,0 +1,6 @@ +API changes + * Remove SSL error codes `MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED` + and `MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH` which are never + returned from the public SSL API. + * Remove `MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE` and return + `MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL` instead. 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 new file mode 100644 index 000000000..49d1a0f22 --- /dev/null +++ b/docs/3.0-migration-guide.d/ssl-error-code-cleanup.md @@ -0,0 +1,20 @@ +Removal of some SSL error codes +----------------------------------------------------------------- + +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` + +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. diff --git a/include/mbedtls/error.h b/include/mbedtls/error.h index 94b95fcca..199ea3df9 100644 --- a/include/mbedtls/error.h +++ b/include/mbedtls/error.h @@ -106,8 +106,10 @@ * HKDF 5 1 (Started from top) * SSL 5 2 (Started from 0x5F00) * CIPHER 6 8 (Started from 0x6080) - * SSL 6 24 (Started from top, plus 0x6000) - * SSL 7 32 + * SSL 6 23 (Started from top, plus 0x6000, gaps at + * 0x6600) + * SSL 7 28 (Started from 0x7080, gaps at + * 0x7300, 0x7500, 0x7580, 0x7800) * * Module dependent error code (5 bits 0x.00.-0x.F8.) */ diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h index b9b2e045f..c9c1a66e3 100644 --- a/include/mbedtls/ssl.h +++ b/include/mbedtls/ssl.h @@ -67,17 +67,17 @@ #define MBEDTLS_ERR_SSL_INVALID_MAC -0x7180 /**< Verification of the message MAC failed. */ #define MBEDTLS_ERR_SSL_INVALID_RECORD -0x7200 /**< An invalid SSL record was received. */ #define MBEDTLS_ERR_SSL_CONN_EOF -0x7280 /**< The connection indicated an EOF. */ -#define MBEDTLS_ERR_SSL_UNKNOWN_CIPHER -0x7300 /**< An unknown cipher was received. */ +/* NOTE: Error space gap */ #define MBEDTLS_ERR_SSL_NO_CIPHER_CHOSEN -0x7380 /**< The server has no ciphersuites in common with the client. */ #define MBEDTLS_ERR_SSL_NO_RNG -0x7400 /**< No RNG was provided to the SSL module. */ #define MBEDTLS_ERR_SSL_NO_CLIENT_CERTIFICATE -0x7480 /**< No client certification received from the client, but required by the authentication mode. */ -#define MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE -0x7500 /**< Our own certificate(s) is/are too large to send in an SSL message. */ -#define MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED -0x7580 /**< The own certificate is not set, but needed by the server. */ +/* NOTE: Error space gap */ +/* NOTE: Error space gap */ #define MBEDTLS_ERR_SSL_PRIVATE_KEY_REQUIRED -0x7600 /**< The own private key or pre-shared key is not set, but needed. */ #define MBEDTLS_ERR_SSL_CA_CHAIN_REQUIRED -0x7680 /**< No CA Chain is set, but required to operate. */ #define MBEDTLS_ERR_SSL_UNEXPECTED_MESSAGE -0x7700 /**< An unexpected message was received from our peer. */ #define MBEDTLS_ERR_SSL_FATAL_ALERT_MESSAGE -0x7780 /**< A fatal alert message was received from our peer. */ -#define MBEDTLS_ERR_SSL_PEER_VERIFY_FAILED -0x7800 /**< Verification of our peer failed. */ +/* NOTE: Error space gap */ #define MBEDTLS_ERR_SSL_PEER_CLOSE_NOTIFY -0x7880 /**< The peer notified us that the connection is going to be closed. */ #define MBEDTLS_ERR_SSL_BAD_HS_CLIENT_HELLO -0x7900 /**< Processing of the ClientHello handshake message failed. */ #define MBEDTLS_ERR_SSL_BAD_HS_SERVER_HELLO -0x7980 /**< Processing of the ServerHello handshake message failed. */ @@ -111,7 +111,7 @@ #define MBEDTLS_ERR_SSL_CLIENT_RECONNECT -0x6780 /**< The client initiated a reconnect from the same port. */ #define MBEDTLS_ERR_SSL_UNEXPECTED_RECORD -0x6700 /**< Record header looks valid but is not expected. */ #define MBEDTLS_ERR_SSL_NON_FATAL -0x6680 /**< The alert message received indicates a non-fatal error. */ -#define MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH -0x6600 /**< Couldn't set the hash for verifying CertificateVerify */ +/* NOTE: Error space gap */ #define MBEDTLS_ERR_SSL_CONTINUE_PROCESSING -0x6580 /**< Internal-only message signaling that further message-processing should be done */ #define MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS -0x6500 /**< The asynchronous operation is not completed yet. */ #define MBEDTLS_ERR_SSL_EARLY_MESSAGE -0x6480 /**< Internal-only message signaling that a message arrived early. */ diff --git a/library/error.c b/library/error.c index a176deb8c..3a8436632 100644 --- a/library/error.c +++ b/library/error.c @@ -374,18 +374,12 @@ const char * mbedtls_high_level_strerr( int error_code ) return( "SSL - An invalid SSL record was received" ); case -(MBEDTLS_ERR_SSL_CONN_EOF): return( "SSL - The connection indicated an EOF" ); - case -(MBEDTLS_ERR_SSL_UNKNOWN_CIPHER): - return( "SSL - An unknown cipher was received" ); case -(MBEDTLS_ERR_SSL_NO_CIPHER_CHOSEN): return( "SSL - The server has no ciphersuites in common with the client" ); case -(MBEDTLS_ERR_SSL_NO_RNG): return( "SSL - No RNG was provided to the SSL module" ); case -(MBEDTLS_ERR_SSL_NO_CLIENT_CERTIFICATE): return( "SSL - No client certification received from the client, but required by the authentication mode" ); - case -(MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE): - return( "SSL - Our own certificate(s) is/are too large to send in an SSL message" ); - case -(MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED): - return( "SSL - The own certificate is not set, but needed by the server" ); case -(MBEDTLS_ERR_SSL_PRIVATE_KEY_REQUIRED): return( "SSL - The own private key or pre-shared key is not set, but needed" ); case -(MBEDTLS_ERR_SSL_CA_CHAIN_REQUIRED): @@ -394,8 +388,6 @@ const char * mbedtls_high_level_strerr( int error_code ) return( "SSL - An unexpected message was received from our peer" ); case -(MBEDTLS_ERR_SSL_FATAL_ALERT_MESSAGE): return( "SSL - A fatal alert message was received from our peer" ); - case -(MBEDTLS_ERR_SSL_PEER_VERIFY_FAILED): - return( "SSL - Verification of our peer failed" ); case -(MBEDTLS_ERR_SSL_PEER_CLOSE_NOTIFY): return( "SSL - The peer notified us that the connection is going to be closed" ); case -(MBEDTLS_ERR_SSL_BAD_HS_CLIENT_HELLO): @@ -462,8 +454,6 @@ const char * mbedtls_high_level_strerr( int error_code ) return( "SSL - Record header looks valid but is not expected" ); case -(MBEDTLS_ERR_SSL_NON_FATAL): return( "SSL - The alert message received indicates a non-fatal error" ); - case -(MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH): - return( "SSL - Couldn't set the hash for verifying CertificateVerify" ); case -(MBEDTLS_ERR_SSL_CONTINUE_PROCESSING): return( "SSL - Internal-only message signaling that further message-processing should be done" ); case -(MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS): diff --git a/library/ssl_tls.c b/library/ssl_tls.c index bc2f269a9..f147ad33a 100644 --- a/library/ssl_tls.c +++ b/library/ssl_tls.c @@ -1936,8 +1936,9 @@ int mbedtls_ssl_write_certificate( mbedtls_ssl_context *ssl ) { if( mbedtls_ssl_own_cert( ssl ) == NULL ) { - MBEDTLS_SSL_DEBUG_MSG( 1, ( "got no certificate to send" ) ); - return( MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED ); + /* Should never happen because we shouldn't have picked the + * ciphersuite if we don't have a certificate. */ + return( MBEDTLS_ERR_SSL_INTERNAL_ERROR ); } } #endif @@ -1964,7 +1965,7 @@ int mbedtls_ssl_write_certificate( mbedtls_ssl_context *ssl ) MBEDTLS_SSL_DEBUG_MSG( 1, ( "certificate too large, %" MBEDTLS_PRINTF_SIZET " > %" MBEDTLS_PRINTF_SIZET, i + 3 + n, (size_t) MBEDTLS_SSL_OUT_CONTENT_LEN ) ); - return( MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE ); + return( MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL ); } ssl->out_msg[i ] = (unsigned char)( n >> 16 ); @@ -6973,14 +6974,14 @@ int mbedtls_ssl_set_calc_verify_md( mbedtls_ssl_context *ssl, int md ) { #if defined(MBEDTLS_SSL_PROTO_TLS1_2) if( ssl->minor_ver != MBEDTLS_SSL_MINOR_VERSION_3 ) - return MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH; + return( -1 ); switch( md ) { #if defined(MBEDTLS_SSL_PROTO_TLS1) || defined(MBEDTLS_SSL_PROTO_TLS1_1) #if defined(MBEDTLS_MD5_C) case MBEDTLS_SSL_HASH_MD5: - return MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH; + return( -1 ); #endif #if defined(MBEDTLS_SHA1_C) case MBEDTLS_SSL_HASH_SHA1: @@ -6999,7 +7000,7 @@ int mbedtls_ssl_set_calc_verify_md( mbedtls_ssl_context *ssl, int md ) break; #endif default: - return MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH; + return( -1 ); } return 0; @@ -7007,7 +7008,7 @@ int mbedtls_ssl_set_calc_verify_md( mbedtls_ssl_context *ssl, int md ) (void) ssl; (void) md; - return MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH; + return( -1 ); #endif /* MBEDTLS_SSL_PROTO_TLS1_2 */ }