From ad28bf0e58b21d38d948e04cd71ba9c84927b02f Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 26 Apr 2018 00:19:16 +0200 Subject: [PATCH] Documentation improvements --- include/mbedtls/ssl.h | 97 +++++++++++++++++++++----------------- library/ssl_srv.c | 4 ++ programs/ssl/ssl_server2.c | 10 ++-- tests/ssl-opt.sh | 2 +- 4 files changed, 65 insertions(+), 48 deletions(-) diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h index 2dac1da77..9b17e610b 100644 --- a/include/mbedtls/ssl.h +++ b/include/mbedtls/ssl.h @@ -556,25 +556,24 @@ typedef struct mbedtls_ssl_flight_item mbedtls_ssl_flight_item; #if defined(MBEDTLS_SSL_ASYNC_PRIVATE) #if defined(MBEDTLS_X509_CRT_PARSE_C) /** - * \brief Callback type: start external signature operation + * \brief Callback type: start external signature operation. * - * Callback to start a signature operation using an + * This callback is called during an SSL handshake to start + * a signature decryption operation using an * external processor. The parameter \c cert contains * the public key; it is up to the callback function to - * look up the associated private key or a handle to the - * private key. + * determine how to access the associated private key. * - * This function must start the signature operation. - * It is expected to be non-blocking, i.e. typically - * this function sends or enqueues a request and does - * not wait for the operation to complete. + * This function typically sends or enqueues a request, and + * does not wait for the operation to complete. This allows + * the handshake step to be non-blocking. * * The parameters \c ssl and \c cert are * guaranteed to remain valid as long as the SSL * configuration remains valid. On the other hand, this - * function must save the contents of \c hash, as the - * \c hash buffer is no longer valid when this function - * returns. + * function must save the contents of \c hash if the value + * is needed for later processing, because the \c hash buffer + * is no longer valid after this function returns. * * This function may call mbedtls_ssl_async_set_data() to * store an operation context for later retrieval @@ -582,12 +581,13 @@ typedef struct mbedtls_ssl_flight_item mbedtls_ssl_flight_item; * * \param config_data The configuration data parameter passed to * mbedtls_ssl_conf_async_private_cb(). - * \param ssl The SSL connection instance. - * \param cert Certificate containing the public key - * \param md_alg Hash algorithm + * \param ssl The SSL connection instance. It should not be + * modified other than via mbedtls_ssl_async_set_data(). + * \param cert Certificate containing the public key. + * \param md_alg Hash algorithm. * \param hash Buffer containing the hash. This buffer is * no longer valid when the function returns. - * \param hash_len Size of the \c hash buffer in bytes + * \param hash_len Size of the \c hash buffer in bytes. * * \return - 0 if the operation was started successfully and the SSL * stack should call the resume callback immediately. @@ -608,25 +608,24 @@ typedef int mbedtls_ssl_async_sign_t( void *config_data, size_t hash_len ); /** - * \brief Callback type: start external decryption operation + * \brief Callback type: start external decryption operation. * - * Callback to start a decryption operation using an + * This callback is called during an SSL handshake to start + * an RSA decryption operation using an * external processor. The parameter \c cert contains * the public key; it is up to the callback function to - * look up the associated private key or a handle to the - * private key. + * determine how to access the associated private key. * - * This function must start the decryption operation. - * It is expected to be non-blocking, i.e. typically - * this function sends or enqueues a request and does - * not wait for the operation to complete. + * This function typically sends or enqueues a request, and + * does not wait for the operation to complete. This allows + * the handshake step to be non-blocking. * * The parameters \c ssl and \c cert are * guaranteed to remain valid as long as the SSL * configuration remains valid. On the other hand, this - * function must save the contents of \c hash, as the - * \c hash buffer is no longer valid when this function - * returns. + * function must save the contents of \c input if the value + * is needed for later processing, because the \c input buffer + * is no longer valid after this function returns. * * This function may call mbedtls_ssl_async_set_data() to * store an operation context for later retrieval @@ -634,11 +633,12 @@ typedef int mbedtls_ssl_async_sign_t( void *config_data, * * \param config_data The configuration data parameter passed to * mbedtls_ssl_conf_async_private_cb(). - * \param ssl The SSL connection instance. - * \param cert Certificate containing the public key + * \param ssl The SSL connection instance. It should not be + * modified other than via mbedtls_ssl_async_set_data(). + * \param cert Certificate containing the public key. * \param input Buffer containing the input ciphertext. This buffer * is no longer valid when the function returns. - * \param input_len Size of the \c input buffer in bytes + * \param input_len Size of the \c input buffer in bytes. * * \return - 0 if the operation was started successfully and the SSL * stack should call the resume callback immediately. @@ -659,10 +659,17 @@ typedef int mbedtls_ssl_async_decrypt_t( void *config_data, #endif /* MBEDTLS_X509_CRT_PARSE_C */ /** - * \brief Callback type: resume external operation + * \brief Callback type: resume external operation. * - * Callback to resume an external operation - * started by the \c mbedtls_ssl_async_sign_t callback. + * This callback is called during an SSL handshake to resume + * an external operation started by the + * \c mbedtls_ssl_async_sign_t or + * \c mbedtls_ssl_async_decrypt_t callback. + * + * This function typically checks the status of a pending + * request or causes the request queue to make progress, and + * does not wait for the operation to complete. This allows + * the handshake step to be non-blocking. * * This function may call mbedtls_ssl_async_get_data() to * retrieve an operation context set by the start callback. @@ -671,10 +678,12 @@ typedef int mbedtls_ssl_async_decrypt_t( void *config_data, * * \param config_data The configuration data parameter passed to * mbedtls_ssl_conf_async_private_cb(). - * \param ssl The SSL connection instance. - * \param output Buffer containing the output on success - * \param output_len On success, number of bytes written to \c output - * \param output_size Size of the \c output buffer in bytes + * \param ssl The SSL connection instance. It should not be + * modified other than via mbedtls_ssl_async_set_data(). + * \param output Buffer containing the output (signature or decrypted + * data) on success. + * \param output_len On success, number of bytes written to \c output. + * \param output_size Size of the \c output buffer in bytes. * * \return - 0 if output of the operation is available in the * \c output buffer. @@ -692,17 +701,18 @@ typedef int mbedtls_ssl_async_resume_t( void *config_data, size_t output_size ); /** - * \brief Callback type: cancel external operation + * \brief Callback type: cancel external operation. * - * Callback to cancel an external operation - * started by the \c mbedtls_ssl_async_sign_t callback. + * This callback is called if an SSL connection is closed + * while an asynchronous operation is in progress. * * This function may call mbedtls_ssl_async_get_data() to * retrieve an operation context set by the start callback. * * \param config_data The configuration data parameter passed to * mbedtls_ssl_conf_async_private_cb(). - * \param ssl The SSL connection instance. + * \param ssl The SSL connection instance. It should not be + * modified. */ typedef void mbedtls_ssl_async_cancel_t( void *config_data, mbedtls_ssl_context *ssl ); @@ -1499,10 +1509,13 @@ void mbedtls_ssl_conf_export_keys_cb( mbedtls_ssl_config *conf, * associated with the certificate will be used. * \param f_async_resume Callback to resume an asynchronous operation. See * the description of \c mbedtls_ssl_async_resume_t - * for more information. + * for more information. This may not be \c NULL unless + * \p f_async_sign and \p f_async_decrypt are both + * \c NULL. * \param f_async_cancel Callback to cancel an asynchronous operation. See * the description of \c mbedtls_ssl_async_cancel_t - * for more information. + * for more information. This may be \c NULL if + * no cleanup is needed. * \param config_data A pointer to configuration data which will be * passed to the callbacks. The library stores and * passes back this value without dereferencing it. diff --git a/library/ssl_srv.c b/library/ssl_srv.c index 92372310d..c4f1adee8 100644 --- a/library/ssl_srv.c +++ b/library/ssl_srv.c @@ -3267,6 +3267,10 @@ static int ssl_write_server_key_exchange( mbedtls_ssl_context *ssl ) if( ret != 0 ) { + /* If we're starting to write a new message, set ssl->out_msglen + * to 0. But if we're resuming after an asynchronous message, + * out_msglen is the amount of data written so far and mst be + * preserved. */ if( ret == MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS ) MBEDTLS_SSL_DEBUG_MSG( 2, ( "<= write server key exchange (pending)" ) ); else diff --git a/programs/ssl/ssl_server2.c b/programs/ssl/ssl_server2.c index 9ff735ad8..7d9072e87 100644 --- a/programs/ssl/ssl_server2.c +++ b/programs/ssl/ssl_server2.c @@ -871,11 +871,11 @@ typedef struct } ssl_async_key_slot_t; typedef enum { - SSL_ASYNC_INJECT_ERROR_NONE = 0, - SSL_ASYNC_INJECT_ERROR_START, - SSL_ASYNC_INJECT_ERROR_CANCEL, - SSL_ASYNC_INJECT_ERROR_RESUME, - SSL_ASYNC_INJECT_ERROR_PK + SSL_ASYNC_INJECT_ERROR_NONE = 0, /*!< Let the callbacks succeed */ + SSL_ASYNC_INJECT_ERROR_START, /*!< Inject error during start */ + SSL_ASYNC_INJECT_ERROR_CANCEL, /*!< Close the connection after async start */ + SSL_ASYNC_INJECT_ERROR_RESUME, /*!< Inject error during resume */ + SSL_ASYNC_INJECT_ERROR_PK /*!< Inject error during resume */ #define SSL_ASYNC_INJECT_ERROR_MAX SSL_ASYNC_INJECT_ERROR_PK } ssl_async_inject_error_t; diff --git a/tests/ssl-opt.sh b/tests/ssl-opt.sh index 1a35aac41..15503e2c5 100755 --- a/tests/ssl-opt.sh +++ b/tests/ssl-opt.sh @@ -4182,7 +4182,7 @@ run_test "SSL async private: slot 0 used with key2" \ # key1: ECDSA, key2: RSA; use key2 from slot 1 requires_config_enabled MBEDTLS_SSL_ASYNC_PRIVATE -run_test "SSL async private: slot 1 used" \ +run_test "SSL async private: slot 1 used with key2" \ "$P_SRV \ async_operations=s async_private_delay1=1 async_private_delay2=1 \ key_file=data_files/server5.key crt_file=data_files/server5.crt \