diff --git a/include/mbedtls/rsa.h b/include/mbedtls/rsa.h index 711329c52..033e58027 100644 --- a/include/mbedtls/rsa.h +++ b/include/mbedtls/rsa.h @@ -1,7 +1,7 @@ /** * \file rsa.h * - * \brief This file contains RSA definitions and functions. + * \brief This file defines the RSA public-key cryptosystem. * * The RSA public-key cryptosystem is defined in Public-Key * Cryptography Standards (PKCS) #1 v1.5: RSA Encryption @@ -104,14 +104,14 @@ typedef struct mbedtls_mpi P; /*!< The first prime factor. */ mbedtls_mpi Q; /*!< The second prime factor. */ - mbedtls_mpi DP; /*!< \p D % (P - 1) */ - mbedtls_mpi DQ; /*!< \p D % (Q - 1) */ - mbedtls_mpi QP; /*!< 1 / (Q % P) */ + mbedtls_mpi DP; /*!< D % (P - 1). */ + mbedtls_mpi DQ; /*!< D % (Q - 1). */ + mbedtls_mpi QP; /*!< 1 / (Q % P). */ - mbedtls_mpi RN; /*!< cached R^2 mod \p N */ + mbedtls_mpi RN; /*!< cached R^2 mod N. */ - mbedtls_mpi RP; /*!< cached R^2 mod \p P */ - mbedtls_mpi RQ; /*!< cached R^2 mod \p Q */ + mbedtls_mpi RP; /*!< cached R^2 mod P. */ + mbedtls_mpi RQ; /*!< cached R^2 mod Q. */ mbedtls_mpi Vi; /*!< The cached blinding value. */ mbedtls_mpi Vf; /*!< The cached un-blinding value. */ @@ -328,7 +328,7 @@ int mbedtls_rsa_export( const mbedtls_rsa_context *ctx, * If the function fails due to an unsupported operation, * the RSA context stays intact and remains usable. * - * \note The length fields are ignored if the corresponding + * \note The length parameters are ignored if the corresponding * buffer pointers are NULL. * * \param ctx The initialized RSA context. @@ -338,7 +338,7 @@ int mbedtls_rsa_export( const mbedtls_rsa_context *ctx, * NULL. * \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 - NULL. + * NULL. * \param Q_len The size of the buffer for the second prime factor. * \param D The Byte array to hold the private exponent, or NULL. * \param D_len The size of the buffer for the private exponent. @@ -549,10 +549,6 @@ int mbedtls_rsa_private( mbedtls_rsa_context *ctx, * It is the generic wrapper for performing a PKCS#1 encryption * operation using the \p mode from the context. * - * \note Alternative implementations of RSA need not support - * mode being set to #MBEDTLS_RSA_PRIVATE and might instead - * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. - * * \note The input and output buffers must be as large as the size * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. * @@ -561,6 +557,10 @@ int mbedtls_rsa_private( mbedtls_rsa_context *ctx, * are likely to remove the \p mode argument and have it * implicitly set to #MBEDTLS_RSA_PUBLIC. * + * \note Alternative implementations of RSA need not support + * mode being set to #MBEDTLS_RSA_PRIVATE and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * * \param ctx The RSA context. * \param f_rng The RNG function. Needed for padding, PKCS#1 v2.1 * encoding, and #MBEDTLS_RSA_PRIVATE. @@ -584,10 +584,6 @@ int mbedtls_rsa_pkcs1_encrypt( mbedtls_rsa_context *ctx, * \brief This function performs a PKCS#1 v1.5 encryption operation * (RSAES-PKCS1-v1_5-ENCRYPT). * - * \note Alternative implementations of RSA need not support - * mode being set to #MBEDTLS_RSA_PRIVATE and might instead - * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. - * * \note The output buffer must be as large as the size * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. * @@ -596,6 +592,10 @@ int mbedtls_rsa_pkcs1_encrypt( mbedtls_rsa_context *ctx, * are likely to remove the \p mode argument and have it * implicitly set to #MBEDTLS_RSA_PUBLIC. * + * \note Alternative implementations of RSA need not support + * mode being set to #MBEDTLS_RSA_PRIVATE and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * * \param ctx The RSA context. * \param f_rng The RNG function. Needed for padding and * #MBEDTLS_RSA_PRIVATE. @@ -619,10 +619,6 @@ int mbedtls_rsa_rsaes_pkcs1_v15_encrypt( mbedtls_rsa_context *ctx, * \brief This function performs a PKCS#1 v2.1 OAEP encryption * operation (RSAES-OAEP-ENCRYPT). * - * \note Alternative implementations of RSA need not support - * mode being set to #MBEDTLS_RSA_PRIVATE and might instead - * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. - * * \note The output buffer must be as large as the size * of ctx->N. For example, 128 Bytes if RSA-1024 is used. * @@ -631,6 +627,10 @@ int mbedtls_rsa_rsaes_pkcs1_v15_encrypt( mbedtls_rsa_context *ctx, * are likely to remove the \p mode argument and have it * implicitly set to #MBEDTLS_RSA_PUBLIC. * + * \note Alternative implementations of RSA need not support + * mode being set to #MBEDTLS_RSA_PRIVATE and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * * \param ctx The RSA context. * \param f_rng The RNG function. Needed for padding and PKCS#1 v2.1 * encoding and #MBEDTLS_RSA_PRIVATE. @@ -671,15 +671,15 @@ int mbedtls_rsa_rsaes_oaep_encrypt( mbedtls_rsa_context *ctx, * \note The input buffer must be as large as the size * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. * - * \note Alternative implementations of RSA need not support - * mode being set to #MBEDTLS_RSA_PUBLIC and might instead - * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. - * * \deprecated It is deprecated and discouraged to call this function * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library * are likely to remove the \p mode argument and have it * implicitly set to #MBEDTLS_RSA_PRIVATE. * + * \note Alternative implementations of RSA need not support + * mode being set to #MBEDTLS_RSA_PUBLIC and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * * \param ctx The RSA context. * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. * \param p_rng The RNG context. @@ -691,7 +691,6 @@ int mbedtls_rsa_rsaes_oaep_encrypt( mbedtls_rsa_context *ctx, * * \return \c 0 on success. * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. - */ int mbedtls_rsa_pkcs1_decrypt( mbedtls_rsa_context *ctx, int (*f_rng)(void *, unsigned char *, size_t), @@ -705,10 +704,6 @@ int mbedtls_rsa_pkcs1_decrypt( mbedtls_rsa_context *ctx, * \brief This function performs a PKCS#1 v1.5 decryption * operation (RSAES-PKCS1-v1_5-DECRYPT). * - * \note Alternative implementations of RSA need not support - * mode being set to #MBEDTLS_RSA_PUBLIC and might instead - * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. - * * \note The output buffer length \c output_max_len should be * as large as the size \p ctx->len of \p ctx->N, for example, * 128 Bytes if RSA-1024 is used, to be able to hold an @@ -724,6 +719,10 @@ int mbedtls_rsa_pkcs1_decrypt( mbedtls_rsa_context *ctx, * are likely to remove the \p mode argument and have it * implicitly set to #MBEDTLS_RSA_PRIVATE. * + * \note Alternative implementations of RSA need not support + * mode being set to #MBEDTLS_RSA_PUBLIC and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * * \param ctx The RSA context. * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. * \param p_rng The RNG context. @@ -749,26 +748,26 @@ int mbedtls_rsa_rsaes_pkcs1_v15_decrypt( mbedtls_rsa_context *ctx, * \brief This function performs a PKCS#1 v2.1 OAEP decryption * operation (RSAES-OAEP-DECRYPT). * - * \note Alternative implementations of RSA need not support - * mode being set to #MBEDTLS_RSA_PUBLIC and might instead - * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * \note The output buffer length \c output_max_len should be + * as large as the size \p ctx->len of \p ctx->N, for + * example, 128 Bytes if RSA-1024 is used, to be able to + * hold an arbitrary decrypted message. If it is not + * large enough to hold the decryption of the particular + * ciphertext provided, the function returns + * #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE. * - * \note The output buffer length \c output_max_len should be - * as large as the size \p ctx->len of \p ctx->N, for - * example, 128 Bytes if RSA-1024 is used, to be able to - * hold an arbitrary decrypted message. If it is not - * large enough to hold the decryption of the particular - * ciphertext provided, the function returns - * #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE. - * - * \note The input buffer must be as large as the size - * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. + * \note The input buffer must be as large as the size + * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. * * \deprecated It is deprecated and discouraged to call this function * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library * are likely to remove the \p mode argument and have it * implicitly set to #MBEDTLS_RSA_PRIVATE. * + * \note Alternative implementations of RSA need not support + * mode being set to #MBEDTLS_RSA_PUBLIC and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * * \param ctx The RSA context. * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. * \param p_rng The RNG context. @@ -800,10 +799,6 @@ int mbedtls_rsa_rsaes_oaep_decrypt( mbedtls_rsa_context *ctx, * It is the generic wrapper for performing a PKCS#1 * signature using the \p mode from the context. * - * \note Alternative implementations of RSA need not support - * mode being set to #MBEDTLS_RSA_PUBLIC and might instead - * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. - * * \note The \p sig buffer must be as large as the size * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. * @@ -816,6 +811,10 @@ int mbedtls_rsa_rsaes_oaep_decrypt( mbedtls_rsa_context *ctx, * are likely to remove the \p mode argument and have it * implicitly set to #MBEDTLS_RSA_PRIVATE. * + * \note Alternative implementations of RSA need not support + * mode being set to #MBEDTLS_RSA_PUBLIC and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * * \param ctx The RSA context. * \param f_rng The RNG function. Needed for PKCS#1 v2.1 encoding and for * #MBEDTLS_RSA_PRIVATE. @@ -843,10 +842,6 @@ int mbedtls_rsa_pkcs1_sign( mbedtls_rsa_context *ctx, * \brief This function performs a PKCS#1 v1.5 signature * operation (RSASSA-PKCS1-v1_5-SIGN). * - * \note Alternative implementations of RSA need not support - * mode being set to #MBEDTLS_RSA_PUBLIC and might instead - * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. - * * \note The \p sig buffer must be as large as the size * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. * @@ -855,6 +850,10 @@ int mbedtls_rsa_pkcs1_sign( mbedtls_rsa_context *ctx, * are likely to remove the \p mode argument and have it * implicitly set to #MBEDTLS_RSA_PRIVATE. * + * \note Alternative implementations of RSA need not support + * mode being set to #MBEDTLS_RSA_PUBLIC and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * * \param ctx The RSA context. * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. * \param p_rng The RNG context. @@ -881,10 +880,6 @@ int mbedtls_rsa_rsassa_pkcs1_v15_sign( mbedtls_rsa_context *ctx, * \brief This function performs a PKCS#1 v2.1 PSS signature * operation (RSASSA-PSS-SIGN). * - * \note Alternative implementations of RSA need not support - * mode being set to #MBEDTLS_RSA_PUBLIC and might instead - * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. - * * \note The \p sig buffer must be as large as the size * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. * @@ -900,6 +895,10 @@ int mbedtls_rsa_rsassa_pkcs1_v15_sign( mbedtls_rsa_context *ctx, * are likely to remove the \p mode argument and have it * implicitly set to #MBEDTLS_RSA_PRIVATE. * + * \note Alternative implementations of RSA need not support + * mode being set to #MBEDTLS_RSA_PUBLIC and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * * \param ctx The RSA context. * \param f_rng The RNG function. Needed for PKCS#1 v2.1 encoding and for * #MBEDTLS_RSA_PRIVATE. @@ -930,10 +929,6 @@ int mbedtls_rsa_rsassa_pss_sign( mbedtls_rsa_context *ctx, * This is the generic wrapper for performing a PKCS#1 * verification using the mode from the context. * - * \note Alternative implementations of RSA need not support - * mode being set to #MBEDTLS_RSA_PRIVATE and might instead - * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. - * * \note The \p sig buffer must be as large as the size * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. * @@ -946,6 +941,10 @@ int mbedtls_rsa_rsassa_pss_sign( mbedtls_rsa_context *ctx, * are likely to remove the \p mode argument and have it * set to #MBEDTLS_RSA_PUBLIC. * + * \note Alternative implementations of RSA need not support + * mode being set to #MBEDTLS_RSA_PRIVATE and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * * \param ctx The RSA public key context. * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. * \param p_rng The RNG context. @@ -972,10 +971,6 @@ int mbedtls_rsa_pkcs1_verify( mbedtls_rsa_context *ctx, * \brief This function performs a PKCS#1 v1.5 verification * operation (RSASSA-PKCS1-v1_5-VERIFY). * - * \note Alternative implementations of RSA need not support - * mode being set to #MBEDTLS_RSA_PRIVATE and might instead - * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. - * * \note The \p sig buffer must be as large as the size * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. * @@ -984,6 +979,10 @@ int mbedtls_rsa_pkcs1_verify( mbedtls_rsa_context *ctx, * are likely to remove the \p mode argument and have it * set to #MBEDTLS_RSA_PUBLIC. * + * \note Alternative implementations of RSA need not support + * mode being set to #MBEDTLS_RSA_PRIVATE and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * * \param ctx The RSA public key context. * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. * \param p_rng The RNG context. @@ -1013,10 +1012,6 @@ int mbedtls_rsa_rsassa_pkcs1_v15_verify( mbedtls_rsa_context *ctx, * The hash function for the MGF mask generating function * is that specified in the RSA context. * - * \note Alternative implementations of RSA need not support - * mode being set to #MBEDTLS_RSA_PRIVATE and might instead - * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. - * * \note The \p sig buffer must be as large as the size * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. * @@ -1033,6 +1028,10 @@ int mbedtls_rsa_rsassa_pkcs1_v15_verify( mbedtls_rsa_context *ctx, * are likely to remove the \p mode argument and have it * implicitly set to #MBEDTLS_RSA_PUBLIC. * + * \note Alternative implementations of RSA need not support + * mode being set to #MBEDTLS_RSA_PRIVATE and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * * \param ctx The RSA public key context. * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. * \param p_rng The RNG context.