pk: fix documentation for RSA sign/verify and encrypt/decrypt
Signed-off-by: Valerio Setti <valerio.setti@nordicsemi.no>
diff --git a/include/mbedtls/pk.h b/include/mbedtls/pk.h
index c37121f..df11de6 100644
--- a/include/mbedtls/pk.h
+++ b/include/mbedtls/pk.h
@@ -612,6 +612,13 @@
* \param sig Signature to verify
* \param sig_len Signature length
*
+ * \note For keys of type #MBEDTLS_PK_RSA, the signature algorithm is
+ * either PKCS#1 v1.5 or PSS (accepting any salt length),
+ * depending on the padding mode in the underlying RSA context.
+ * For a pk object constructed by parsing, this is PKCS#1 v1.5
+ * by default. Use mbedtls_pk_verify_ext() to explicitly select
+ * a different algorithm.
+ *
* \return 0 on success (signature is valid),
* #MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if there is a valid
* signature in \p sig but its length is less than \p sig_len,
@@ -702,6 +709,14 @@
* \param f_rng RNG function, must not be \c NULL.
* \param p_rng RNG parameter
*
+ * \note For keys of type #MBEDTLS_PK_RSA, the signature algorithm is
+ * either PKCS#1 v1.5 or PSS (using the largest possible salt
+ * length up to the hash length), depending on the padding mode
+ * in the underlying RSA context. For a pk object constructed
+ * by parsing, this is PKCS#1 v1.5 by default. Use
+ * mbedtls_pk_verify_ext() to explicitly select a different
+ * algorithm.
+ *
* \return 0 on success, or a specific error code.
*
* \note For RSA, md_alg may be MBEDTLS_MD_NONE if hash_len != 0.
@@ -798,6 +813,11 @@
* \param f_rng RNG function, must not be \c NULL.
* \param p_rng RNG parameter
*
+ * \note For keys of type #MBEDTLS_PK_RSA, the signature algorithm is
+ * either PKCS#1 v1.5 or OAEP, depending on the padding mode in
+ * the underlying RSA context. For a pk object constructed by
+ * parsing, this is PKCS#1 v1.5 by default.
+ *
* \return 0 on success, or a specific error code.
*/
int mbedtls_pk_decrypt(mbedtls_pk_context *ctx,
@@ -817,6 +837,11 @@
* \param f_rng RNG function, must not be \c NULL.
* \param p_rng RNG parameter
*
+ * \note For keys of type #MBEDTLS_PK_RSA, the signature algorithm is
+ * either PKCS#1 v1.5 or OAEP, depending on the padding mode in
+ * the underlying RSA context. For a pk object constructed by
+ * parsing, this is PKCS#1 v1.5 by default.
+ *
* \note \p f_rng is used for padding generation.
*
* \return 0 on success, or a specific error code.