yuzu/mbedtls
1
0
Fork 0
mirror of https://github.com/yuzu-emu/mbedtls.git synced 2025-01-09 21:45:34 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documentation improvements

Browse source
This commit is contained in:
Gilles Peskine 2018-04-26 00:19:16 +02:00
parent 168dae8567
commit ad28bf0e58
4 changed files with 65 additions and 48 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

97
include/mbedtls/ssl.h
View file

@ -556,25 +556,24 @@ typedef struct mbedtls_ssl_flight_item mbedtls_ssl_flight_item;
#if defined(MBEDTLS_SSL_ASYNC_PRIVATE) #if defined(MBEDTLS_SSL_ASYNC_PRIVATE)
#if defined(MBEDTLS_X509_CRT_PARSE_C) #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 * external processor. The parameter \c cert contains
* the public key; it is up to the callback function to * the public key; it is up to the callback function to
* look up the associated private key or a handle to the * determine how to access the associated private key.
* private key.
* *
* This function must start the signature operation. * This function typically sends or enqueues a request, and
* It is expected to be non-blocking, i.e. typically * does not wait for the operation to complete. This allows
* this function sends or enqueues a request and does * the handshake step to be non-blocking.
* not wait for the operation to complete.
* *
* The parameters \c ssl and \c cert are * The parameters \c ssl and \c cert are
* guaranteed to remain valid as long as the SSL * guaranteed to remain valid as long as the SSL
* configuration remains valid. On the other hand, this * configuration remains valid. On the other hand, this
* function must save the contents of \c hash, as the * function must save the contents of \c hash if the value
* \c hash buffer is no longer valid when this function * is needed for later processing, because the \c hash buffer
* returns. * is no longer valid after this function returns.
* *
* This function may call mbedtls_ssl_async_set_data() to * This function may call mbedtls_ssl_async_set_data() to
* store an operation context for later retrieval * 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 * \param config_data The configuration data parameter passed to
* mbedtls_ssl_conf_async_private_cb(). * mbedtls_ssl_conf_async_private_cb().
* \param ssl The SSL connection instance. * \param ssl The SSL connection instance. It should not be
* \param cert Certificate containing the public key * modified other than via mbedtls_ssl_async_set_data().
* \param md_alg Hash algorithm * \param cert Certificate containing the public key.
* \param md_alg Hash algorithm.
* \param hash Buffer containing the hash. This buffer is * \param hash Buffer containing the hash. This buffer is
* no longer valid when the function returns. * 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 * \return - 0 if the operation was started successfully and the SSL
* stack should call the resume callback immediately. * 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 ); 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 * external processor. The parameter \c cert contains
* the public key; it is up to the callback function to * the public key; it is up to the callback function to
* look up the associated private key or a handle to the * determine how to access the associated private key.
* private key.
* *
* This function must start the decryption operation. * This function typically sends or enqueues a request, and
* It is expected to be non-blocking, i.e. typically * does not wait for the operation to complete. This allows
* this function sends or enqueues a request and does * the handshake step to be non-blocking.
* not wait for the operation to complete.
* *
* The parameters \c ssl and \c cert are * The parameters \c ssl and \c cert are
* guaranteed to remain valid as long as the SSL * guaranteed to remain valid as long as the SSL
* configuration remains valid. On the other hand, this * configuration remains valid. On the other hand, this
* function must save the contents of \c hash, as the * function must save the contents of \c input if the value
* \c hash buffer is no longer valid when this function * is needed for later processing, because the \c input buffer
* returns. * is no longer valid after this function returns.
* *
* This function may call mbedtls_ssl_async_set_data() to * This function may call mbedtls_ssl_async_set_data() to
* store an operation context for later retrieval * 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 * \param config_data The configuration data parameter passed to
* mbedtls_ssl_conf_async_private_cb(). * mbedtls_ssl_conf_async_private_cb().
* \param ssl The SSL connection instance. * \param ssl The SSL connection instance. It should not be
* \param cert Certificate containing the public key * 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 * \param input Buffer containing the input ciphertext. This buffer
* is no longer valid when the function returns. * 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 * \return - 0 if the operation was started successfully and the SSL
* stack should call the resume callback immediately. * 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 */ #endif /* MBEDTLS_X509_CRT_PARSE_C */
/** /**
* \brief Callback type: resume external operation * \brief Callback type: resume external operation.
* *
* Callback to resume an external operation * This callback is called during an SSL handshake to resume
* started by the \c mbedtls_ssl_async_sign_t callback. * 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 * This function may call mbedtls_ssl_async_get_data() to
* retrieve an operation context set by the start callback. * 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 * \param config_data The configuration data parameter passed to
* mbedtls_ssl_conf_async_private_cb(). * mbedtls_ssl_conf_async_private_cb().
* \param ssl The SSL connection instance. * \param ssl The SSL connection instance. It should not be
* \param output Buffer containing the output on success * modified other than via mbedtls_ssl_async_set_data().
* \param output_len On success, number of bytes written to \c output * \param output Buffer containing the output (signature or decrypted
* \param output_size Size of the \c output buffer in bytes * 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 * \return - 0 if output of the operation is available in the
* \c output buffer. * \c output buffer.
@ -692,17 +701,18 @@ typedef int mbedtls_ssl_async_resume_t( void *config_data,
size_t output_size ); size_t output_size );
/** /**
* \brief Callback type: cancel external operation * \brief Callback type: cancel external operation.
* *
* Callback to cancel an external operation * This callback is called if an SSL connection is closed
* started by the \c mbedtls_ssl_async_sign_t callback. * while an asynchronous operation is in progress.
* *
* This function may call mbedtls_ssl_async_get_data() to * This function may call mbedtls_ssl_async_get_data() to
* retrieve an operation context set by the start callback. * retrieve an operation context set by the start callback.
* *
* \param config_data The configuration data parameter passed to * \param config_data The configuration data parameter passed to
* mbedtls_ssl_conf_async_private_cb(). * 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, typedef void mbedtls_ssl_async_cancel_t( void *config_data,
mbedtls_ssl_context *ssl ); 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. * associated with the certificate will be used.
* \param f_async_resume Callback to resume an asynchronous operation. See * \param f_async_resume Callback to resume an asynchronous operation. See
* the description of \c mbedtls_ssl_async_resume_t * 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 * \param f_async_cancel Callback to cancel an asynchronous operation. See
* the description of \c mbedtls_ssl_async_cancel_t * 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 * \param config_data A pointer to configuration data which will be
* passed to the callbacks. The library stores and * passed to the callbacks. The library stores and
* passes back this value without dereferencing it. * passes back this value without dereferencing it.

4
library/ssl_srv.c
View file

@ -3267,6 +3267,10 @@ static int ssl_write_server_key_exchange( mbedtls_ssl_context *ssl )
if( ret != 0 ) 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 ) if( ret == MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS )
MBEDTLS_SSL_DEBUG_MSG( 2, ( "<= write server key exchange (pending)" ) ); MBEDTLS_SSL_DEBUG_MSG( 2, ( "<= write server key exchange (pending)" ) );
else else

10
programs/ssl/ssl_server2.c
View file

@ -871,11 +871,11 @@ typedef struct
} ssl_async_key_slot_t; } ssl_async_key_slot_t;
typedef enum { typedef enum {
SSL_ASYNC_INJECT_ERROR_NONE = 0, SSL_ASYNC_INJECT_ERROR_NONE = 0, /*!< Let the callbacks succeed */
SSL_ASYNC_INJECT_ERROR_START, SSL_ASYNC_INJECT_ERROR_START, /*!< Inject error during start */
SSL_ASYNC_INJECT_ERROR_CANCEL, SSL_ASYNC_INJECT_ERROR_CANCEL, /*!< Close the connection after async start */
SSL_ASYNC_INJECT_ERROR_RESUME, SSL_ASYNC_INJECT_ERROR_RESUME, /*!< Inject error during resume */
SSL_ASYNC_INJECT_ERROR_PK SSL_ASYNC_INJECT_ERROR_PK /*!< Inject error during resume */
#define SSL_ASYNC_INJECT_ERROR_MAX SSL_ASYNC_INJECT_ERROR_PK #define SSL_ASYNC_INJECT_ERROR_MAX SSL_ASYNC_INJECT_ERROR_PK
} ssl_async_inject_error_t; } ssl_async_inject_error_t;

2
tests/ssl-opt.sh
View file

@ -4182,7 +4182,7 @@ run_test "SSL async private: slot 0 used with key2" \
# key1: ECDSA, key2: RSA; use key2 from slot 1 # key1: ECDSA, key2: RSA; use key2 from slot 1
requires_config_enabled MBEDTLS_SSL_ASYNC_PRIVATE 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 \ "$P_SRV \
async_operations=s async_private_delay1=1 async_private_delay2=1 \ async_operations=s async_private_delay1=1 async_private_delay2=1 \
key_file=data_files/server5.key crt_file=data_files/server5.crt \ key_file=data_files/server5.key crt_file=data_files/server5.crt \