Clarify guarantees made by `rsa_complete` and `rsa_check_privkey`
diff --git a/include/mbedtls/rsa.h b/include/mbedtls/rsa.h
index 04175eb..0c64907 100644
--- a/include/mbedtls/rsa.h
+++ b/include/mbedtls/rsa.h
@@ -405,19 +405,16 @@
*
* \return
* - 0 if successful. In this case, it is guaranteed
- * the functions \c mbedtls_rsa_check_pubkey resp.
- * \c mbedtls_rsa_check_privkey pass in case of a
- * public resp. private key.
+ * that the RSA context can be used for RSA operations
+ * without the risk of failure or crash.
* - \c MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the attempted
* derivations failed.
*
- * \warning Implementations are *not* obliged to perform exhaustive
- * validation of the imported parameters!
- * In particular, parameters that are not needed by the
- * implementation may be silently discarded and left unchecked.
- * If the user mistrusts the given key material, he should
- * employ other means for verification like the helper functions
- * \c mbedtls_rsa_validate_params, \c mbedtls_rsa_validate_crt.
+ * \warning This function need not perform consistency checks
+ * for the imported parameters! In particular, parameters that
+ * are not needed by the implementation may be silently discarded
+ * and left unchecked. For the purpose of checking the consistency
+ * of the key material, see \c mbedtls_rsa_check_privkey.
*
*/
int mbedtls_rsa_complete( mbedtls_rsa_context *ctx,
@@ -581,25 +578,41 @@
int mbedtls_rsa_check_pubkey( const mbedtls_rsa_context *ctx );
/**
- * \brief Check if a context contains an RSA private key
- * and perform basic sanity checks.
+ * \brief Check if a context contains an RSA private key
+ * 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.
- * On success, it is guaranteed that enough information is
- * present to perform RSA private and public key operations.
+ * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code.
*
- * \warning This function is *not* obliged to perform an exhaustive
- * sanity check what would guarantee the internal parameters
- * to match and \c mbedtls_rsa_private and \c mbedtls_rsa_public
- * to be mutually inverse to each other.
- * The reason is that for minimal non-CRT implementations
- * using only N, D, E, for example, checking the validity
- * would be computationally expensive.
- * Users mistrusting their key material should use other
- * means for verification; see the documentation of
- * \c mbedtls_rsa_complete.
+ * \note This function performs checks substantiating
+ * the consistency of the key material used to setup
+ * the RSA context. In case of implementations saving
+ * all core RSA parameters, this might mean a consistency
+ * check in the sense of \c mbedtls_rsa_validate_params,
+ * while other implementations might perform an empirical
+ * check consisting of an encryption-decryption pair.
+ *
+ * \warning This function should catch accidental misconfigurations
+ * 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 );