Context-independent RSA helper functions. More...
Go to the source code of this file.
Detailed Description
Context-independent RSA helper functions.
This module declares some RSA-related helper functions useful when implementing the RSA interface. These functions are provided in a separate compilation unit in order to make it easy for designers of alternative RSA implementations to use them in their own code, as it is conceived that the functionality they provide will be necessary for most complete implementations.
End-users of Mbed TLS who are not providing their own alternative RSA implementations should not use these functions directly, and should instead use only the functions declared in rsa.h.
The interface provided by this module will be maintained through LTS (Long Term Support) branches of Mbed TLS, but may otherwise be subject to change, and must be considered an internal interface of the library.
There are two classes of helper functions:
(1) Parameter-generating helpers. These are:
- mbedtls_rsa_deduce_primes
- mbedtls_rsa_deduce_private_exponent
- mbedtls_rsa_deduce_crt Each of these functions takes a set of core RSA parameters and generates some other, or CRT related parameters.
(2) Parameter-checking helpers. These are:
- mbedtls_rsa_validate_params
- mbedtls_rsa_validate_crt They take a set of core or CRT related RSA parameters and check their validity.
Definition in file rsa_internal.h.
Function Documentation
◆ mbedtls_rsa_deduce_crt()
| int mbedtls_rsa_deduce_crt | ( | const mbedtls_mpi * | P, |
| const mbedtls_mpi * | Q, | ||
| const mbedtls_mpi * | D, | ||
| mbedtls_mpi * | DP, | ||
| mbedtls_mpi * | DQ, | ||
| mbedtls_mpi * | QP | ||
| ) |
Generate RSA-CRT parameters.
- Note
- This is a 'static' helper function not operating on an RSA context. Alternative implementations need not overwrite it.
- Parameters
-
P First prime factor of N Q Second prime factor of N D RSA private exponent DP Output variable for D modulo P-1 DQ Output variable for D modulo Q-1 QP Output variable for the modular inverse of Q modulo P.
- Returns
- 0 on success, non-zero error code otherwise.
- Note
- This function does not check whether P, Q are prime and whether D is a valid private exponent.
◆ mbedtls_rsa_deduce_primes()
| int mbedtls_rsa_deduce_primes | ( | mbedtls_mpi const * | N, |
| mbedtls_mpi const * | E, | ||
| mbedtls_mpi const * | D, | ||
| mbedtls_mpi * | P, | ||
| mbedtls_mpi * | Q | ||
| ) |
Compute RSA prime moduli P, Q from public modulus N=PQ and a pair of private and public key.
- Note
- This is a 'static' helper function not operating on an RSA context. Alternative implementations need not overwrite it.
- Parameters
-
N RSA modulus N = PQ, with P, Q to be found E RSA public exponent D RSA private exponent P Pointer to MPI holding first prime factor of N on success Q Pointer to MPI holding second prime factor of N on success
- Returns
- 0 if successful. In this case, P and Q constitute a factorization of N.
- A non-zero error code otherwise.
- Note
- It is neither checked that P, Q are prime nor that D, E are modular inverses wrt. P-1 and Q-1. For that, use the helper function
mbedtls_rsa_validate_params.
◆ mbedtls_rsa_deduce_private_exponent()
| int mbedtls_rsa_deduce_private_exponent | ( | mbedtls_mpi const * | P, |
| mbedtls_mpi const * | Q, | ||
| mbedtls_mpi const * | E, | ||
| mbedtls_mpi * | D | ||
| ) |
Compute RSA private exponent from prime moduli and public key.
- Note
- This is a 'static' helper function not operating on an RSA context. Alternative implementations need not overwrite it.
- Parameters
-
P First prime factor of RSA modulus Q Second prime factor of RSA modulus E RSA public exponent D Pointer to MPI holding the private exponent on success.
- Returns
- 0 if successful. In this case, D is set to a simultaneous modular inverse of E modulo both P-1 and Q-1.
- A non-zero error code otherwise.
- Note
- This function does not check whether P and Q are primes.
◆ mbedtls_rsa_validate_crt()
| int mbedtls_rsa_validate_crt | ( | const mbedtls_mpi * | P, |
| const mbedtls_mpi * | Q, | ||
| const mbedtls_mpi * | D, | ||
| const mbedtls_mpi * | DP, | ||
| const mbedtls_mpi * | DQ, | ||
| const mbedtls_mpi * | QP | ||
| ) |
Check validity of RSA CRT parameters.
- Note
- This is a 'static' helper function not operating on an RSA context. Alternative implementations need not overwrite it.
- Parameters
-
P First prime factor of RSA modulus Q Second prime factor of RSA modulus D RSA private exponent DP MPI to check for D modulo P-1 DQ MPI to check for D modulo P-1 QP MPI to check for the modular inverse of Q modulo P.
- Returns
- 0 if the following conditions are satisfied:
- D = DP mod P-1 if P, D, DP != NULL
- Q = DQ mod P-1 if P, D, DQ != NULL
- QP = Q^-1 mod P if P, Q, QP != NULL
MBEDTLS_ERR_RSA_KEY_CHECK_FAILEDif check failed, potentially includingMBEDTLS_ERR_MPI_XXXif some MPI calculations failed.MBEDTLS_ERR_RSA_BAD_INPUT_DATAif insufficient data was provided to check DP, DQ or QP.
- 0 if the following conditions are satisfied:
- Note
- The function can be used with a restricted set of arguments to perform specific checks only. E.g., calling it with the parameters (P, -, D, DP, -, -) will check DP = D mod P-1.
◆ mbedtls_rsa_validate_params()
| int mbedtls_rsa_validate_params | ( | const mbedtls_mpi * | N, |
| const mbedtls_mpi * | P, | ||
| const mbedtls_mpi * | Q, | ||
| const mbedtls_mpi * | D, | ||
| const mbedtls_mpi * | E, | ||
| int(*)(void *, unsigned char *, size_t) | f_rng, | ||
| void * | p_rng | ||
| ) |
Check validity of core RSA parameters.
- Note
- This is a 'static' helper function not operating on an RSA context. Alternative implementations need not overwrite it.
- Parameters
-
N RSA modulus N = PQ P First prime factor of N Q Second prime factor of N D RSA private exponent E RSA public exponent f_rng PRNG to be used for primality check, or NULL p_rng PRNG context for f_rng, or NULL
- Returns
- 0 if the following conditions are satisfied if all relevant parameters are provided:
- P prime if f_rng != NULL (%)
- Q prime if f_rng != NULL (%)
- 1 < N = P * Q
- 1 < D, E < N
- D and E are modular inverses modulo P-1 and Q-1 (%) This is only done if MBEDTLS_GENPRIME is defined.
- A non-zero error code otherwise.
- 0 if the following conditions are satisfied if all relevant parameters are provided:
- Note
- The function can be used with a restricted set of arguments to perform specific checks only. E.g., calling it with (-,P,-,-,-) and a PRNG amounts to a primality check for P.
