Merge pull request #7965 from gilles-peskine-arm/psa_inject_entropy-file-stability-2.28
Backport 2.28: Fix and test MBEDTLS_PSA_INJECT_ENTROPY
diff --git a/include/mbedtls/aria.h b/include/mbedtls/aria.h
index 9856a1c..d307ff9 100644
--- a/include/mbedtls/aria.h
+++ b/include/mbedtls/aria.h
@@ -274,10 +274,6 @@
* \brief This function performs an ARIA-CTR encryption or decryption
* operation.
*
- * This function performs the operation defined in the \p mode
- * parameter (encrypt/decrypt), on the input data buffer
- * defined in the \p input parameter.
- *
* Due to the nature of CTR, you must use the same key schedule
* for both encryption and decryption operations. Therefore, you
* must use the context initialized with mbedtls_aria_setkey_enc()
diff --git a/include/mbedtls/asn1.h b/include/mbedtls/asn1.h
index 540cdcc..82aaee8 100644
--- a/include/mbedtls/asn1.h
+++ b/include/mbedtls/asn1.h
@@ -453,7 +453,7 @@
* on a successful invocation.
* \param end The end of the ASN.1 SEQUENCE container.
* \param tag_must_mask A mask to be applied to the ASN.1 tags found within
- * the SEQUENCE before comparing to \p tag_must_value.
+ * the SEQUENCE before comparing to \p tag_must_val.
* \param tag_must_val The required value of each ASN.1 tag found in the
* SEQUENCE, after masking with \p tag_must_mask.
* Mismatching tags lead to an error.
@@ -462,7 +462,7 @@
* while a value of \c 0xFF for \p tag_must_mask means
* that \p tag_must_val is the only allowed tag.
* \param tag_may_mask A mask to be applied to the ASN.1 tags found within
- * the SEQUENCE before comparing to \p tag_may_value.
+ * the SEQUENCE before comparing to \p tag_may_val.
* \param tag_may_val The desired value of each ASN.1 tag found in the
* SEQUENCE, after masking with \p tag_may_mask.
* Mismatching tags will be silently ignored.
diff --git a/include/mbedtls/bignum.h b/include/mbedtls/bignum.h
index f66379d..cbed259 100644
--- a/include/mbedtls/bignum.h
+++ b/include/mbedtls/bignum.h
@@ -533,7 +533,7 @@
* \param X The destination MPI. This must point to an initialized MPI.
* \param buf The input buffer. This must be a readable buffer of length
* \p buflen Bytes.
- * \param buflen The length of the input buffer \p p in Bytes.
+ * \param buflen The length of the input buffer \p buf in Bytes.
*
* \return \c 0 if successful.
* \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
@@ -548,7 +548,7 @@
* \param X The destination MPI. This must point to an initialized MPI.
* \param buf The input buffer. This must be a readable buffer of length
* \p buflen Bytes.
- * \param buflen The length of the input buffer \p p in Bytes.
+ * \param buflen The length of the input buffer \p buf in Bytes.
*
* \return \c 0 if successful.
* \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
@@ -986,8 +986,8 @@
* \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
* \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if \p N is less than
* or equal to one.
- * \return #MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if \p has no modular inverse
- * with respect to \p N.
+ * \return #MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if \p A has no modular
+ * inverse with respect to \p N.
*/
int mbedtls_mpi_inv_mod(mbedtls_mpi *X, const mbedtls_mpi *A,
const mbedtls_mpi *N);
diff --git a/include/mbedtls/camellia.h b/include/mbedtls/camellia.h
index 05397d2..e840947 100644
--- a/include/mbedtls/camellia.h
+++ b/include/mbedtls/camellia.h
@@ -231,7 +231,7 @@
* *note Due to the nature of CTR mode, you should use the same
* key for both encryption and decryption. In particular, calls
* to this function should be preceded by a key-schedule via
- * mbedtls_camellia_setkey_enc() regardless of whether \p mode
+ * mbedtls_camellia_setkey_enc() regardless of whether the mode
* is #MBEDTLS_CAMELLIA_ENCRYPT or #MBEDTLS_CAMELLIA_DECRYPT.
*
* \warning You must never reuse a nonce value with the same key. Doing so
diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h
index aa155d7..56fc2d8 100644
--- a/include/mbedtls/cipher.h
+++ b/include/mbedtls/cipher.h
@@ -427,7 +427,7 @@
const mbedtls_cipher_mode_t mode);
/**
- * \brief This function initializes a \p cipher_context as NONE.
+ * \brief This function initializes a \p ctx as NONE.
*
* \param ctx The context to be initialized. This must not be \c NULL.
*/
@@ -602,7 +602,7 @@
* \param ctx The context of the cipher. This must be initialized.
*
* \return The key length of the cipher in bits.
- * \return #MBEDTLS_KEY_LENGTH_NONE if ctx \p has not been
+ * \return #MBEDTLS_KEY_LENGTH_NONE if \p ctx has not been
* initialized.
*/
static inline int mbedtls_cipher_get_key_bitlen(
@@ -779,7 +779,7 @@
* \param ctx The generic cipher context. This must be initialized and
* bound to a key.
* \param output The buffer to write data to. This needs to be a writable
- * buffer of at least \p block_size Bytes.
+ * buffer of at least block_size Bytes.
* \param olen The length of the data written to the \p output buffer.
* This may not be \c NULL.
*
diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h
index 1381c1f..04acc1c 100644
--- a/include/mbedtls/config.h
+++ b/include/mbedtls/config.h
@@ -1458,8 +1458,8 @@
* );
* ```
* The \c context value is initialized to 0 before the first call.
- * The function must fill the \c output buffer with \p output_size bytes
- * of random data and set \c *output_length to \p output_size.
+ * The function must fill the \c output buffer with \c output_size bytes
+ * of random data and set \c *output_length to \c output_size.
*
* Requires: MBEDTLS_PSA_CRYPTO_C
*
diff --git a/include/mbedtls/ecdsa.h b/include/mbedtls/ecdsa.h
index e42d114..b7029d7 100644
--- a/include/mbedtls/ecdsa.h
+++ b/include/mbedtls/ecdsa.h
@@ -266,8 +266,9 @@
* \param md_alg The hash algorithm used to hash the original data.
* \param f_rng_blind The RNG function used for blinding. This must not be
* \c NULL.
- * \param p_rng_blind The RNG context to be passed to \p f_rng. This may be
- * \c NULL if \p f_rng doesn't need a context parameter.
+ * \param p_rng_blind The RNG context to be passed to \p f_rng_blind. This
+ * may be \c NULL if \p f_rng_blind doesn't need
+ * a context parameter.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
@@ -344,7 +345,7 @@
* via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair().
* \param md_alg The message digest that was used to hash the message.
* \param hash The message hash to be signed. This must be a readable
- * buffer of length \p blen Bytes.
+ * buffer of length \p hlen Bytes.
* \param hlen The length of the hash \p hash in Bytes.
* \param sig The buffer to which to write the signature. This must be a
* writable buffer of length at least twice as large as the
@@ -386,7 +387,7 @@
* via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair().
* \param md_alg The message digest that was used to hash the message.
* \param hash The message hash to be signed. This must be a readable
- * buffer of length \p blen Bytes.
+ * buffer of length \p hlen Bytes.
* \param hlen The length of the hash \p hash in Bytes.
* \param sig The buffer to which to write the signature. This must be a
* writable buffer of length at least twice as large as the
@@ -453,7 +454,7 @@
* and have a group and private key bound to it, for example
* via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair().
* \param hash The message hash to be signed. This must be a readable
- * buffer of length \p blen Bytes.
+ * buffer of length \p hlen Bytes.
* \param hlen The length of the hash \p hash in Bytes.
* \param sig The buffer to which to write the signature. This must be a
* writable buffer of length at least twice as large as the
@@ -490,7 +491,7 @@
* \param ctx The ECDSA context to use. This must be initialized
* and have a group and public key bound to it.
* \param hash The message hash that was signed. This must be a readable
- * buffer of length \p size Bytes.
+ * buffer of length \p hlen Bytes.
* \param hlen The size of the hash \p hash.
* \param sig The signature to read and verify. This must be a readable
* buffer of length \p slen Bytes.
@@ -520,7 +521,7 @@
* \param ctx The ECDSA context to use. This must be initialized
* and have a group and public key bound to it.
* \param hash The message hash that was signed. This must be a readable
- * buffer of length \p size Bytes.
+ * buffer of length \p hlen Bytes.
* \param hlen The size of the hash \p hash.
* \param sig The signature to read and verify. This must be a readable
* buffer of length \p slen Bytes.
diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h
index 5402e74..d56069e 100644
--- a/include/mbedtls/ecp.h
+++ b/include/mbedtls/ecp.h
@@ -1081,7 +1081,7 @@
*
* It only checks that the point is non-zero, has
* valid coordinates and lies on the curve. It does not verify
- * that it is indeed a multiple of \p G. This additional
+ * that it is indeed a multiple of \c G. This additional
* check is computationally more expensive, is not required
* by standards, and should not be necessary if the group
* used has a small cofactor. In particular, it is useless for
@@ -1106,7 +1106,7 @@
const mbedtls_ecp_point *pt);
/**
- * \brief This function checks that an \p mbedtls_mpi is a
+ * \brief This function checks that an \c mbedtls_mpi is a
* valid private key for this curve.
*
* \note This function uses bare components rather than an
diff --git a/include/mbedtls/hmac_drbg.h b/include/mbedtls/hmac_drbg.h
index 3ccf61c..6b22485 100644
--- a/include/mbedtls/hmac_drbg.h
+++ b/include/mbedtls/hmac_drbg.h
@@ -186,8 +186,8 @@
* \param len The length of the personalization string.
* This must be at most #MBEDTLS_HMAC_DRBG_MAX_INPUT
* and also at most
- * #MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT - \p entropy_len * 3 / 2
- * where \p entropy_len is the entropy length
+ * #MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT - \c entropy_len * 3 / 2
+ * where \c entropy_len is the entropy length
* described above.
*
* \return \c 0 if successful.
@@ -316,8 +316,8 @@
* \param len The length of the additional data.
* This must be at most #MBEDTLS_HMAC_DRBG_MAX_INPUT
* and also at most
- * #MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT - \p entropy_len
- * where \p entropy_len is the entropy length
+ * #MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT - \c entropy_len
+ * where \c entropy_len is the entropy length
* (see mbedtls_hmac_drbg_set_entropy_len()).
*
* \return \c 0 if successful.
diff --git a/include/mbedtls/pk.h b/include/mbedtls/pk.h
index ec83551..0e9d58a 100644
--- a/include/mbedtls/pk.h
+++ b/include/mbedtls/pk.h
@@ -395,7 +395,7 @@
*
* \return 0 on success (signature is valid),
* #MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if there is a valid
- * signature in sig but its length is less than \p siglen,
+ * signature in \p sig but its length is less than \p sig_len,
* or a specific error code.
*
* \note For RSA keys, the default padding type is PKCS#1 v1.5.
@@ -459,7 +459,7 @@
* #MBEDTLS_ERR_PK_TYPE_MISMATCH if the PK context can't be
* used for this type of signatures,
* #MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if there is a valid
- * signature in sig but its length is less than \p siglen,
+ * signature in \p sig but its length is less than \p sig_len,
* or a specific error code.
*
* \note If hash_len is 0, then the length associated with md_alg
diff --git a/include/mbedtls/rsa.h b/include/mbedtls/rsa.h
index f8725ff..37f07c0 100644
--- a/include/mbedtls/rsa.h
+++ b/include/mbedtls/rsa.h
@@ -260,15 +260,15 @@
* \brief This function completes an RSA context from
* a set of imported core parameters.
*
- * To setup an RSA public key, precisely \p N and \p E
+ * To setup an RSA public key, precisely \c N and \c E
* must have been imported.
*
* To setup an RSA private key, sufficient information must
* be present for the other parameters to be derivable.
*
* The default implementation supports the following:
- * <ul><li>Derive \p P, \p Q from \p N, \p D, \p E.</li>
- * <li>Derive \p N, \p D from \p P, \p Q, \p E.</li></ul>
+ * <ul><li>Derive \c P, \c Q from \c N, \c D, \c E.</li>
+ * <li>Derive \c N, \c D from \c P, \c Q, \c E.</li></ul>
* Alternative implementations need not support these.
*
* If this function runs successfully, it guarantees that
@@ -537,7 +537,7 @@
* \note This function does not handle message padding.
*
* \note Make sure to set \p input[0] = 0 or ensure that
- * input is smaller than \p N.
+ * input is smaller than \c N.
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -1109,8 +1109,8 @@
* verification using the mode from the context.
*
* \note For PKCS#1 v2.1 encoding, see comments on
- * mbedtls_rsa_rsassa_pss_verify() about \p md_alg and
- * \p hash_id.
+ * mbedtls_rsa_rsassa_pss_verify() about \c md_alg and
+ * \c hash_id.
*
* \deprecated It is deprecated and discouraged to call this function
* in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index 26e4ec4..e07da11 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -1746,10 +1746,10 @@
* \param own_cid The address of the readable buffer holding the CID we want
* the peer to use when sending encrypted messages to us.
* This may be \c NULL if \p own_cid_len is \c 0.
- * This parameter is unused if \p enabled is set to
+ * This parameter is unused if \p enable is set to
* MBEDTLS_SSL_CID_DISABLED.
* \param own_cid_len The length of \p own_cid.
- * This parameter is unused if \p enabled is set to
+ * This parameter is unused if \p enable is set to
* MBEDTLS_SSL_CID_DISABLED.
*
* \note The value of \p own_cid_len must match the value of the
@@ -2573,8 +2573,8 @@
*
* \param session The session structure to be saved.
* \param buf The buffer to write the serialized data to. It must be a
- * writeable buffer of at least \p len bytes, or may be \c
- * NULL if \p len is \c 0.
+ * writeable buffer of at least \p buf_len bytes, or may be \c
+ * NULL if \p buf_len is \c 0.
* \param buf_len The number of bytes available for writing in \p buf.
* \param olen The size in bytes of the data that has been or would have
* been written. It must point to a valid \c size_t.
@@ -2659,7 +2659,7 @@
* record headers.
*
* \return \c 0 on success.
- * \return #MBEDTLS_ERR_SSL_BAD_INPUT_DATA if \p own_cid_len
+ * \return #MBEDTLS_ERR_SSL_BAD_INPUT_DATA if \p len
* is too large.
*/
int mbedtls_ssl_conf_cid(mbedtls_ssl_config *conf, size_t len,
diff --git a/include/mbedtls/x509_crt.h b/include/mbedtls/x509_crt.h
index 466611f..d436635 100644
--- a/include/mbedtls/x509_crt.h
+++ b/include/mbedtls/x509_crt.h
@@ -509,7 +509,7 @@
* \param san_buf The buffer holding the raw data item of the subject
* alternative name.
* \param san The target structure to populate with the parsed presentation
- * of the subject alternative name encoded in \p san_raw.
+ * of the subject alternative name encoded in \p san_buf.
*
* \note Only "dnsName" and "otherName" of type hardware_module_name
* as defined in RFC 4180 is supported.
@@ -517,7 +517,7 @@
* \note This function should be called on a single raw data of
* subject alternative name. For example, after successful
* certificate parsing, one must iterate on every item in the
- * \p crt->subject_alt_names sequence, and pass it to
+ * \c crt->subject_alt_names sequence, and pass it to
* this function.
*
* \warning The target structure contains pointers to the raw data of the