diff --git a/include/mbedtls/pkcs12.h b/include/mbedtls/pkcs12.h
index eb9e2d9..8d003b5 100644
--- a/include/mbedtls/pkcs12.h
+++ b/include/mbedtls/pkcs12.h
@@ -56,6 +56,21 @@
  * \brief            PKCS12 Password Based function (encryption / decryption)
  *                   for cipher-based and mbedtls_md-based PBE's
  *
+ * \note             When encrypting, #MBEDTLS_CIPHER_PADDING_PKCS7 must
+ *                   be enabled at compile time.
+ *
+ * \warning          When decrypting:
+ *                   - if #MBEDTLS_CIPHER_PADDING_PKCS7 is enabled at compile
+ *                     time, this function validates the CBC padding and returns
+ *                     #MBEDTLS_ERR_PKCS12_PASSWORD_MISMATCH if the padding is
+ *                     invalid. Note that this can help active adversaries
+ *                     attempting to brute-forcing the password. Note also that
+ *                     there is no guarantee that an invalid password will be
+ *                     detected (the chances of a valid padding with a random
+ *                     password are about 1/255).
+ *                   - if #MBEDTLS_CIPHER_PADDING_PKCS7 is disabled at compile
+ *                     time, this function does not validate the CBC padding.
+ *
  * \param pbe_params an ASN1 buffer containing the pkcs-12 PbeParams structure
  * \param mode       either #MBEDTLS_PKCS12_PBE_ENCRYPT or
  *                   #MBEDTLS_PKCS12_PBE_DECRYPT
@@ -66,7 +81,15 @@
  * \param pwdlen     length of the password (may be 0)
  * \param input      the input data
  * \param len        data length
- * \param output     the output buffer
+ * \param output     Output buffer.
+ *                   On success, it contains the encrypted or decrypted data,
+ *                   possibly followed by the CBC padding.
+ *                   On failure, the content is indeterminate.
+ *                   For decryption, there must be enough room for \p len
+ *                   bytes.
+ *                   For encryption, there must be enough room for
+ *                   \p len + 1 bytes, rounded up to the block size of
+ *                   the block cipher identified by \p pbe_params.
  *
  * \return           0 if successful, or a MBEDTLS_ERR_XXX code
  */