Lines Matching +full:for +full:- +full:context
4 * \brief This file provides an API for the RSA public-key cryptosystem.
6 * The RSA public-key cryptosystem is defined in <em>Public-Key
8 * and <em>Public-Key Cryptography Standards (PKCS) #1 v2.1:
14 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
33 #define MBEDTLS_ERR_RSA_BAD_INPUT_DATA -0x4080
35 #define MBEDTLS_ERR_RSA_INVALID_PADDING -0x4100
37 #define MBEDTLS_ERR_RSA_KEY_GEN_FAILED -0x4180
39 #define MBEDTLS_ERR_RSA_KEY_CHECK_FAILED -0x4200
41 #define MBEDTLS_ERR_RSA_PUBLIC_FAILED -0x4280
43 #define MBEDTLS_ERR_RSA_PRIVATE_FAILED -0x4300
45 #define MBEDTLS_ERR_RSA_VERIFY_FAILED -0x4380
46 /** The output buffer for decryption is not large enough. */
47 #define MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE -0x4400
48 /** The random generator failed to generate non-zeros. */
49 #define MBEDTLS_ERR_RSA_RNG_FAILED -0x4480
58 #define MBEDTLS_RSA_SIGN 1 /**< Identifier for RSA signature operations. */
59 #define MBEDTLS_RSA_CRYPT 2 /**< Identifier for RSA encryption and decryption operations. */
61 #define MBEDTLS_RSA_SALT_LEN_ANY -1
65 * eg for alternative (PKCS#11) RSA implementations in the PK layers.
83 * \brief The RSA context structure.
86 int MBEDTLS_PRIVATE(ver); /*!< Reserved for internal purposes.
99 mbedtls_mpi MBEDTLS_PRIVATE(DP); /*!< <code>D % (P - 1)</code>. */
100 mbedtls_mpi MBEDTLS_PRIVATE(DQ); /*!< <code>D % (Q - 1)</code>. */
109 mbedtls_mpi MBEDTLS_PRIVATE(Vf); /*!< The cached un-blinding value. */
112 #MBEDTLS_RSA_PKCS_V15 for 1.5 padding and
113 #MBEDTLS_RSA_PKCS_V21 for OAEP or PSS. */
115 as specified in md.h for use in the MGF
117 EME-OAEP and EMSA-PSS encodings. */
120 mbedtls_threading_mutex_t MBEDTLS_PRIVATE(mutex); /*!< Thread-safety mutex. */
130 * \brief This function initializes an RSA context.
134 * #MBEDTLS_MD_NONE. See mbedtls_rsa_set_padding() for more
137 * \param ctx The RSA context to initialize. This must not be \c NULL.
142 * \brief This function sets padding for an already initialized RSA
143 * context.
145 * \note Set padding to #MBEDTLS_RSA_PKCS_V21 for the RSAES-OAEP
146 * encryption scheme and the RSASSA-PSS signature scheme.
151 * \note The choice of padding mode is strictly enforced for private
153 * mixing padding modes. For public key operations it is
158 * \note The hash selected in \p hash_id is always used for OEAP
159 * encryption. For PSS signatures, it is always used for
160 * making signatures, but can be overridden for verifying them.
163 * \param ctx The initialized RSA context to be configured.
166 * \param hash_id The hash identifier for PSS or OAEP, if \p padding is
168 * function but may be not suitable for some operations.
180 * RSA context.
182 * \param ctx The initialized RSA context.
193 * \param ctx The initialized RSA context.
202 * RSA context.
204 * \note This function can be called multiple times for successive
209 * completes the provided information to a ready-for-use
212 * \note See mbedtls_rsa_complete() for more information on which
217 * for the lifetime of the RSA context being set up.
219 * \param ctx The initialized RSA context to store the parameters in.
227 * \return A non-zero error code on failure.
235 * \brief This function imports core RSA parameters, in raw big-endian
236 * binary format, into an RSA context.
238 * \note This function can be called multiple times for successive
243 * completes the provided information to a ready-for-use
246 * \note See mbedtls_rsa_complete() for more information on which
251 * for the lifetime of the RSA context being set up.
253 * \param ctx The initialized RSA context to store the parameters in.
266 * \return A non-zero error code on failure.
276 * \brief This function completes an RSA context from
283 * be present for the other parameters to be derivable.
291 * the RSA context can be used for RSA operations without
295 * for the imported parameters. In particular, parameters that
300 * \param ctx The initialized RSA context holding imported parameters.
312 * If this function runs successfully, the non-NULL buffers
317 * Possible reasons for returning
323 * deduction. For example, \p P, \p Q from \p N, \p D,
328 * the RSA context stays intact and remains usable.
330 * \param ctx The initialized RSA context.
346 * \return A non-zero return code on any other failure.
355 * in raw big-endian binary format.
357 * If this function runs successfully, the non-NULL buffers
362 * Possible reasons for returning
368 * deduction. For example, \p P, \p Q from \p N, \p D,
372 * the RSA context stays intact and remains usable.
377 * \param ctx The initialized RSA context.
380 * \param N_len The size of the buffer for the modulus.
383 * \param P_len The size of the buffer for the first prime factor.
386 * \param Q_len The size of the buffer for the second prime factor.
389 * \param D_len The size of the buffer for the private exponent.
392 * \param E_len The size of the buffer for the public exponent.
398 * \return A non-zero return code on any other failure.
410 * \note Alternative RSA implementations not using CRT-parameters
414 * \param ctx The initialized RSA context.
415 * \param DP The MPI to hold \c D modulo `P-1`,
417 * \param DQ The MPI to hold \c D modulo `Q-1`,
423 * \return A non-zero error code on failure.
432 * \param ctx The initialized RSA context.
442 * \param ctx The initialized RSA context.
453 * to set up the RSA context.
455 * \param ctx The initialized RSA context used to hold the key.
456 * \param f_rng The RNG function to be used for key generation.
458 * \param p_rng The RNG context to be passed to \p f_rng.
459 * This may be \c NULL if \p f_rng doesn't need a context.
461 * \param exponent The public exponent to use. For example, \c 65537.
473 * \brief This function checks if a context contains at least an RSA
480 * \param ctx The initialized RSA context to check.
489 * \brief This function checks if a context contains an RSA private key
494 * on the given context, but that the various parameters are
501 * material that was used to setup the given RSA context:
503 * for the implementation might be silently dropped. If dropped,
507 * content of a PKCS1-encoded RSA private key, for example, you
509 * up the RSA context.
519 * \param ctx The initialized RSA context to check.
527 * \brief This function checks a public-private RSA key pair.
531 * \param pub The initialized RSA context holding the public key.
532 * \param prv The initialized RSA context holding the private key.
543 * \param ctx The initialized RSA context to use.
545 * of length \c ctx->len Bytes. For example, \c 256 Bytes
546 * for an 2048-bit RSA modulus.
548 * of length \c ctx->len Bytes. For example, \c 256 Bytes
549 * for an 2048-bit RSA modulus.
570 * against some side-channel attacks.
577 * \param ctx The initialized RSA context to use.
578 * \param f_rng The RNG function, used for blinding. It is mandatory.
579 * \param p_rng The RNG context to pass to \p f_rng. This may be \c NULL
580 * if \p f_rng doesn't need a context.
582 * of length \c ctx->len Bytes. For example, \c 256 Bytes
583 * for an 2048-bit RSA modulus.
585 * of length \c ctx->len Bytes. For example, \c 256 Bytes
586 * for an 2048-bit RSA modulus.
602 * It is the generic wrapper for performing a PKCS#1 encryption
605 * \param ctx The initialized RSA context to use.
606 * \param f_rng The RNG to use. It is used for padding generation
608 * \param p_rng The RNG context to be passed to \p f_rng. May be
609 * \c NULL if \p f_rng doesn't need a context argument.
615 * of length \c ctx->len Bytes. For example, \c 256 Bytes
616 * for an 2048-bit RSA modulus.
630 * (RSAES-PKCS1-v1_5-ENCRYPT).
632 * \param ctx The initialized RSA context to use.
633 * \param f_rng The RNG function to use. It is mandatory and used for
635 * \param p_rng The RNG context to be passed to \p f_rng. This may
636 * be \c NULL if \p f_rng doesn't need a context argument.
642 * of length \c ctx->len Bytes. For example, \c 256 Bytes
643 * for an 2048-bit RSA modulus.
657 * operation (RSAES-OAEP-ENCRYPT).
660 * of ctx->N. For example, 128 Bytes if RSA-1024 is used.
662 * \param ctx The initialized RSA context to use.
663 * \param f_rng The RNG function to use. This is needed for padding
665 * \param p_rng The RNG context to be passed to \p f_rng. This may
666 * be \c NULL if \p f_rng doesn't need a context argument.
676 * of length \c ctx->len Bytes. For example, \c 256 Bytes
677 * for an 2048-bit RSA modulus.
694 * It is the generic wrapper for performing a PKCS#1 decryption
697 * \warning When \p ctx->padding is set to #MBEDTLS_RSA_PKCS_V15,
699 * inherently dangerous function (CWE-242).
702 * as large as the size \p ctx->len of \p ctx->N (for example,
703 * 128 Bytes if RSA-1024 is used) to be able to hold an
708 * \param ctx The initialized RSA context to use.
709 * \param f_rng The RNG function. This is used for blinding and is
710 * mandatory; see mbedtls_rsa_private() for more.
711 * \param p_rng The RNG context to be passed to \p f_rng. This may be
712 * \c NULL if \p f_rng doesn't need a context.
716 * of length \c ctx->len Bytes. For example, \c 256 Bytes
717 * for an 2048-bit RSA modulus.
735 * operation (RSAES-PKCS1-v1_5-DECRYPT).
737 * \warning This is an inherently dangerous function (CWE-242). Unless
743 * as large as the size \p ctx->len of \p ctx->N, for example,
744 * 128 Bytes if RSA-1024 is used, to be able to hold an
749 * \param ctx The initialized RSA context to use.
750 * \param f_rng The RNG function. This is used for blinding and is
751 * mandatory; see mbedtls_rsa_private() for more.
752 * \param p_rng The RNG context to be passed to \p f_rng. This may be
753 * \c NULL if \p f_rng doesn't need a context.
757 * of length \c ctx->len Bytes. For example, \c 256 Bytes
758 * for an 2048-bit RSA modulus.
777 * operation (RSAES-OAEP-DECRYPT).
780 * as large as the size \p ctx->len of \p ctx->N, for
781 * example, 128 Bytes if RSA-1024 is used, to be able to
787 * \param ctx The initialized RSA context to use.
788 * \param f_rng The RNG function. This is used for blinding and is
790 * \param p_rng The RNG context to be passed to \p f_rng. This may be
791 * \c NULL if \p f_rng doesn't need a context.
799 * of length \c ctx->len Bytes. For example, \c 256 Bytes
800 * for an 2048-bit RSA modulus.
821 * It is the generic wrapper for performing a PKCS#1
825 * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
827 * \note For PKCS#1 v2.1 encoding, see comments on
828 * mbedtls_rsa_rsassa_pss_sign() for details on
831 * \param ctx The initialized RSA context to use.
834 * \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL
835 * if \p f_rng doesn't need a context argument.
836 * \param md_alg The message-digest algorithm used to hash the original data.
837 * Use #MBEDTLS_MD_NONE for signing raw data.
844 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
845 * for an 2048-bit RSA modulus. A buffer length of
861 * operation (RSASSA-PKCS1-v1_5-SIGN).
863 * \param ctx The initialized RSA context to use.
864 * \param f_rng The RNG function. This is used for blinding and is
865 * mandatory; see mbedtls_rsa_private() for more.
866 * \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL
867 * if \p f_rng doesn't need a context argument.
868 * \param md_alg The message-digest algorithm used to hash the original data.
869 * Use #MBEDTLS_MD_NONE for signing raw data.
876 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
877 * for an 2048-bit RSA modulus. A buffer length of
894 * operation (RSASSA-PSS-SIGN).
897 * mbedtls_rsa_set_padding() selects the hash used for the
898 * encoding operation and for the mask generation function
899 * (MGF1). For more details on the encoding operation and the
900 * mask generation function, consult <em>RFC-3447: Public-Key
905 * with FIPS 186-4 §5.5 (e) and RFC 8017 (PKCS#1 v2.2) §9.1.1
911 * \param ctx The initialized RSA context to use.
913 * \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL
914 * if \p f_rng doesn't need a context argument.
915 * \param md_alg The message-digest algorithm used to hash the original data.
916 * Use #MBEDTLS_MD_NONE for signing raw data.
926 * FIPS 186-4 §5.5.
928 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
929 * for an 2048-bit RSA modulus. A buffer length of
946 * operation (RSASSA-PSS-SIGN).
949 * mbedtls_rsa_set_padding() selects the hash used for the
950 * encoding operation and for the mask generation function
951 * (MGF1). For more details on the encoding operation and the
952 * mask generation function, consult <em>RFC-3447: Public-Key
958 * size complies with FIPS 186-4 §5.5 (e) and RFC 8017 (PKCS#1
966 * \param ctx The initialized RSA context to use.
968 * \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL
969 * if \p f_rng doesn't need a context argument.
970 * \param md_alg The message-digest algorithm used to hash the original data.
971 * Use #MBEDTLS_MD_NONE for signing raw data.
978 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
979 * for an 2048-bit RSA modulus. A buffer length of
998 * This is the generic wrapper for performing a PKCS#1
1001 * \note For PKCS#1 v2.1 encoding, see comments on
1005 * \param ctx The initialized RSA public key context to use.
1006 * \param md_alg The message-digest algorithm used to hash the original data.
1007 * Use #MBEDTLS_MD_NONE for signing raw data.
1014 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
1015 * for an 2048-bit RSA modulus.
1028 * operation (RSASSA-PKCS1-v1_5-VERIFY).
1030 * \param ctx The initialized RSA public key context to use.
1031 * \param md_alg The message-digest algorithm used to hash the original data.
1032 * Use #MBEDTLS_MD_NONE for signing raw data.
1039 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
1040 * for an 2048-bit RSA modulus.
1053 * operation (RSASSA-PSS-VERIFY).
1056 * mbedtls_rsa_set_padding() selects the hash used for the
1057 * encoding operation and for the mask generation function
1058 * (MGF1). For more details on the encoding operation and the
1059 * mask generation function, consult <em>RFC-3447: Public-Key
1065 * \param ctx The initialized RSA public key context to use.
1066 * \param md_alg The message-digest algorithm used to hash the original data.
1067 * Use #MBEDTLS_MD_NONE for signing raw data.
1074 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
1075 * for an 2048-bit RSA modulus.
1088 * operation (RSASSA-PSS-VERIFY).
1091 * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
1096 * \param ctx The initialized RSA public key context to use.
1097 * \param md_alg The message-digest algorithm used to hash the original data.
1098 * Use #MBEDTLS_MD_NONE for signing raw data.
1104 * \param mgf1_hash_id The message digest algorithm used for the
1106 * function (MGF1). For more details on the encoding
1108 * <em>RFC-3447: Public-Key Cryptography Standards
1114 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
1115 * for an 2048-bit RSA modulus.
1129 * \brief This function copies the components of an RSA context.
1131 * \param dst The destination context. This must be initialized.
1132 * \param src The source context. This must be initialized.
1142 * \param ctx The RSA context to free. May be \c NULL, in which case
1143 * this function is a no-op. If it is not \c NULL, it must
1144 * point to an initialized RSA context.