OPTIGA Trust M  1.1.0
C++ library for Optiga Trust M Chip Security Controller
rsa_internal.h File Reference

Context-independent RSA helper functions. More...

#include "config.h"
#include "bignum.h"
Include dependency graph for rsa_internal.h:

Go to the source code of this file.

Functions

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. More...
 
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. More...
 
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. More...
 
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(*f_rng)(void *, unsigned char *, size_t), void *p_rng)
 Check validity of core RSA parameters. More...
 
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. More...
 

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.

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
PFirst prime factor of N
QSecond prime factor of N
DRSA private exponent
DPOutput variable for D modulo P-1
DQOutput variable for D modulo Q-1
QPOutput 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
NRSA modulus N = PQ, with P, Q to be found
ERSA public exponent
DRSA private exponent
PPointer to MPI holding first prime factor of N on success
QPointer 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
PFirst prime factor of RSA modulus
QSecond prime factor of RSA modulus
ERSA public exponent
DPointer 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
PFirst prime factor of RSA modulus
QSecond prime factor of RSA modulus
DRSA private exponent
DPMPI to check for D modulo P-1
DQMPI to check for D modulo P-1
QPMPI 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_FAILED if check failed, potentially including MBEDTLS_ERR_MPI_XXX if some MPI calculations failed.
  • MBEDTLS_ERR_RSA_BAD_INPUT_DATA if insufficient data was provided to check DP, DQ or QP.
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
NRSA modulus N = PQ
PFirst prime factor of N
QSecond prime factor of N
DRSA private exponent
ERSA public exponent
f_rngPRNG to be used for primality check, or NULL
p_rngPRNG 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.
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.