mirror/mbedtls
1
0
Fork 0
mirror of https://github.com/Mbed-TLS/mbedtls.git synced 2025-01-28 00:35:21 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Clarify guarantees made by rsa_complete and rsa_check_privkey

Browse Source
This commit is contained in:
Hanno Becker 2017-10-10 16:44:47 +01:00
parent 68b4d58bd8
commit 1e801f5706
1 changed files with 39 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
include/mbedtls/rsa.h
View File

@ -405,19 +405,16 @@ int mbedtls_rsa_import_raw( mbedtls_rsa_context *ctx,
* *
* \return * \return
* - 0 if successful. In this case, it is guaranteed * - 0 if successful. In this case, it is guaranteed
* the functions \c mbedtls_rsa_check_pubkey resp. * that the RSA context can be used for RSA operations
* \c mbedtls_rsa_check_privkey pass in case of a * without the risk of failure or crash.
* public resp. private key.
* - \c MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the attempted * - \c MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the attempted
* derivations failed. * derivations failed.
* *
* \warning Implementations are *not* obliged to perform exhaustive * \warning This function need not perform consistency checks
* validation of the imported parameters! * for the imported parameters! In particular, parameters that
* In particular, parameters that are not needed by the * are not needed by the implementation may be silently discarded
* implementation may be silently discarded and left unchecked. * and left unchecked. For the purpose of checking the consistency
* If the user mistrusts the given key material, he should * of the key material, see \c mbedtls_rsa_check_privkey.
* employ other means for verification like the helper functions
* \c mbedtls_rsa_validate_params, \c mbedtls_rsa_validate_crt.
* *
*/ */
int mbedtls_rsa_complete( mbedtls_rsa_context *ctx, int mbedtls_rsa_complete( mbedtls_rsa_context *ctx,
@ -581,25 +578,41 @@ int mbedtls_rsa_gen_key( mbedtls_rsa_context *ctx,
int mbedtls_rsa_check_pubkey( const mbedtls_rsa_context *ctx ); int mbedtls_rsa_check_pubkey( const mbedtls_rsa_context *ctx );
/** /**
* \brief Check if a context contains an RSA private key * \brief Check if a context contains an RSA private key
* and perform basic sanity checks. * and perform basic consistency checks.
* *
* \param ctx RSA context to be checked * \param ctx RSA context to be checked
* *
* \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code. * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code.
* On success, it is guaranteed that enough information is
* present to perform RSA private and public key operations.
* *
* \warning This function is *not* obliged to perform an exhaustive * \note This function performs checks substantiating
* sanity check what would guarantee the internal parameters * the consistency of the key material used to setup
* to match and \c mbedtls_rsa_private and \c mbedtls_rsa_public * the RSA context. In case of implementations saving
* to be mutually inverse to each other. * all core RSA parameters, this might mean a consistency
* The reason is that for minimal non-CRT implementations * check in the sense of \c mbedtls_rsa_validate_params,
* using only N, D, E, for example, checking the validity * while other implementations might perform an empirical
* would be computationally expensive. * check consisting of an encryption-decryption pair.
* Users mistrusting their key material should use other *
* means for verification; see the documentation of * \warning This function should catch accidental misconfigurations
* \c mbedtls_rsa_complete. * like swapping of parameters, but it cannot establish full
* trust in neither the quality nor the consistency of the key
* material that was used to setup the given RSA context:
* - Regarding consistency, note (see \c mbedtls_rsa_complete)
* that imported parameters irrelevant for the implementation
* might be silently dropped, in which case the present
* function doesn't have access to and hence cannot check them.
* If the user desires to check the consistency of the entire
* content of, say, an PKCS1-encoded RSA private key, he
* should use \c mbedtls_rsa_validate_params before setting
* up the RSA context.
* Further, if the implementation performs empirical checks,
* these checks will substantiate but not guarantee consistency.
* - Regarding quality, this function is not expected to perform
* extended quality assessments like checking that the prime
* factors are safe. Further, it is the user's responsibility to
* ensure trustworthiness of the source of his RSA parameters,
* a question going beyond what's effectively checkable
* by the library.
* *
*/ */
int mbedtls_rsa_check_privkey( const mbedtls_rsa_context *ctx ); int mbedtls_rsa_check_privkey( const mbedtls_rsa_context *ctx );