blob: 701fe8bed9274cbf6287e4a5b2204370e1ae6384 [file] [log] [blame]
• Derive \p P, \p Q from \p N, \p D, \p E.
• *
• Derive \p N, \p D from \p P, \p Q, \p E.
* Alternative implementations need not support these. * * If this function runs successfully, it guarantees that * the RSA context can be used for RSA operations without * the risk of failure or crash. * * \warning This function need not perform consistency checks * for the imported parameters. In particular, parameters that * are not needed by the implementation might be silently * discarded and left unchecked. To check the consistency * of the key material, see mbedtls_rsa_check_privkey(). * * \param ctx The initialized RSA context holding imported parameters. * * \return \c 0 on success. * \return #MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the attempted derivations * failed. * */ int mbedtls_rsa_complete( mbedtls_rsa_context *ctx ); /** * \brief This function exports the core parameters of an RSA key. * * If this function runs successfully, the non-NULL buffers * pointed to by \p N, \p P, \p Q, \p D, and \p E are fully * written, with additional unused space filled leading by * zero Bytes. * * Possible reasons for returning * #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED:
*
• An alternative RSA implementation is in use, which * stores the key externally, and either cannot or should * not export it into RAM.
• *
• A SW or HW implementation might not support a certain * deduction. For example, \p P, \p Q from \p N, \p D, * and \p E if the former are not part of the * implementation.
* * If the function fails due to an unsupported operation, * the RSA context stays intact and remains usable. * * \param ctx The initialized RSA context. * \param N The MPI to hold the RSA modulus. * This may be \c NULL if this field need not be exported. * \param P The MPI to hold the first prime factor of \p N. * This may be \c NULL if this field need not be exported. * \param Q The MPI to hold the second prime factor of \p N. * This may be \c NULL if this field need not be exported. * \param D The MPI to hold the private exponent. * This may be \c NULL if this field need not be exported. * \param E The MPI to hold the public exponent. * This may be \c NULL if this field need not be exported. * * \return \c 0 on success. * \return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED if exporting the * requested parameters cannot be done due to missing * functionality or because of security policies. * \return A non-zero return code on any other failure. * */ int mbedtls_rsa_export( const mbedtls_rsa_context *ctx, mbedtls_mpi *N, mbedtls_mpi *P, mbedtls_mpi *Q, mbedtls_mpi *D, mbedtls_mpi *E ); /** * \brief This function exports core parameters of an RSA key * in raw big-endian binary format. * * If this function runs successfully, the non-NULL buffers * pointed to by \p N, \p P, \p Q, \p D, and \p E are fully * written, with additional unused space filled leading by * zero Bytes. * * Possible reasons for returning * #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED:
*
• An alternative RSA implementation is in use, which * stores the key externally, and either cannot or should * not export it into RAM.
• *
• A SW or HW implementation might not support a certain * deduction. For example, \p P, \p Q from \p N, \p D, * and \p E if the former are not part of the * implementation.
* If the function fails due to an unsupported operation, * the RSA context stays intact and remains usable. * * \note The length parameters are ignored if the corresponding * buffer pointers are NULL. * * \param ctx The initialized RSA context. * \param N The Byte array to store the RSA modulus, * or \c NULL if this field need not be exported. * \param N_len The size of the buffer for the modulus. * \param P The Byte array to hold the first prime factor of \p N, * or \c NULL if this field need not be exported. * \param P_len The size of the buffer for the first prime factor. * \param Q The Byte array to hold the second prime factor of \p N, * or \c NULL if this field need not be exported. * \param Q_len The size of the buffer for the second prime factor. * \param D The Byte array to hold the private exponent, * or \c NULL if this field need not be exported. * \param D_len The size of the buffer for the private exponent. * \param E The Byte array to hold the public exponent, * or \c NULL if this field need not be exported. * \param E_len The size of the buffer for the public exponent. * * \return \c 0 on success. * \return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED if exporting the * requested parameters cannot be done due to missing * functionality or because of security policies. * \return A non-zero return code on any other failure. */ int mbedtls_rsa_export_raw( const mbedtls_rsa_context *ctx, unsigned char *N, size_t N_len, unsigned char *P, size_t P_len, unsigned char *Q, size_t Q_len, unsigned char *D, size_t D_len, unsigned char *E, size_t E_len ); /** * \brief This function exports CRT parameters of a private RSA key. * * \note Alternative RSA implementations not using CRT-parameters * internally can implement this function based on * mbedtls_rsa_deduce_opt(). * * \param ctx The initialized RSA context. * \param DP The MPI to hold \c D modulo `P-1`, * or \c NULL if it need not be exported. * \param DQ The MPI to hold \c D modulo `Q-1`, * or \c NULL if it need not be exported. * \param QP The MPI to hold modular inverse of \c Q modulo \c P, * or \c NULL if it need not be exported. * * \return \c 0 on success. * \return A non-zero error code on failure. * */ int mbedtls_rsa_export_crt( const mbedtls_rsa_context *ctx, mbedtls_mpi *DP, mbedtls_mpi *DQ, mbedtls_mpi *QP ); /** * \brief This function sets padding for an already initialized RSA * context. See mbedtls_rsa_init() for details. * * \param ctx The initialized RSA context to be configured. * \param padding The padding mode to use. This must be either * #MBEDTLS_RSA_PKCS_V15 or #MBEDTLS_RSA_PKCS_V21. * \param hash_id The #MBEDTLS_RSA_PKCS_V21 hash identifier. */ void mbedtls_rsa_set_padding( mbedtls_rsa_context *ctx, int padding, int hash_id ); /** * \brief This function retrieves the length of RSA modulus in Bytes. * * \param ctx The initialized RSA context. * * \return The length of the RSA modulus in Bytes. * */ size_t mbedtls_rsa_get_len( const mbedtls_rsa_context *ctx ); /** * \brief This function generates an RSA keypair. * * \note mbedtls_rsa_init() must be called before this function, * to set up the RSA context. * * \param ctx The initialized RSA context used to hold the key. * \param f_rng The RNG function to be used for key generation. * This must not be \c NULL. * \param p_rng The RNG context to be passed to \p f_rng. * This may be \c NULL if \p f_rng doesn't need a context. * \param nbits The size of the public key in bits. * \param exponent The public exponent to use. For example, \c 65537. * This must be odd and greater than \c 1. * * \return \c 0 on success. * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. */ int mbedtls_rsa_gen_key( mbedtls_rsa_context *ctx, int (*f_rng)(void *, unsigned char *, size_t), void *p_rng, unsigned int nbits, int exponent ); /** * \brief This function checks if a context contains at least an RSA * public key. * * If the function runs successfully, it is guaranteed that * enough information is present to perform an RSA public key * operation using mbedtls_rsa_public(). * * \param ctx The initialized RSA context to check. * * \return \c 0 on success. * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. * */ int mbedtls_rsa_check_pubkey( const mbedtls_rsa_context *ctx ); /** * \brief This function checks if a context contains an RSA private key * and perform basic consistency checks. * * \note The consistency checks performed by this function not only * ensure that mbedtls_rsa_private() can be called successfully * on the given context, but that the various parameters are * mutually consistent with high probability, in the sense that * mbedtls_rsa_public() and mbedtls_rsa_private() are inverses. * * \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: *
• Consistency: Imported parameters that are irrelevant * for the implementation might be silently dropped. If dropped, * the current function does not have access to them, * and therefore cannot check them. See mbedtls_rsa_complete(). * If you want to check the consistency of the entire * content of an PKCS1-encoded RSA private key, for example, you * should use mbedtls_rsa_validate_params() before setting * up the RSA context. * Additionally, if the implementation performs empirical checks, * these checks substantiate but do not guarantee consistency.
• *
• Quality: This function is not expected to perform * extended quality assessments like checking that the prime * factors are safe. Additionally, it is the responsibility of the * user to ensure the trustworthiness of the source of his RSA * parameters, which goes beyond what is effectively checkable * by the library.