diff --git a/include/mbedtls/aes.h b/include/mbedtls/aes.h
index 22eb116..4c0429d 100644
--- a/include/mbedtls/aes.h
+++ b/include/mbedtls/aes.h
@@ -1,7 +1,9 @@
 /**
  * \file aes.h
  *
- * \brief   The Advanced Encryption Standard (AES) specifies a FIPS-approved
+ * \brief   This file contains AES definitions and functions.
+ *
+ *          The Advanced Encryption Standard (AES) specifies a FIPS-approved
  *          cryptographic algorithm that can be used to protect electronic
  *          data.
  *
@@ -12,6 +14,7 @@
  *          techniques -- Encryption algorithms -- Part 2: Asymmetric
  *          ciphers</em>.
  */
+
 /*  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved.
  *  SPDX-License-Identifier: Apache-2.0
  *
@@ -59,14 +62,14 @@
 #define inline __inline
 #endif
 
-#if !defined(MBEDTLS_AES_ALT)
-// Regular implementation
-//
-
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+#if !defined(MBEDTLS_AES_ALT)
+// Regular implementation
+//
+
 /**
  * \brief The AES context-type definition.
  */
@@ -85,6 +88,10 @@
 }
 mbedtls_aes_context;
 
+#else  /* MBEDTLS_AES_ALT */
+#include "aes_alt.h"
+#endif /* MBEDTLS_AES_ALT */
+
 /**
  * \brief          This function initializes the specified AES context.
  *
@@ -112,8 +119,8 @@
  *                 <li>192 bits</li>
  *                 <li>256 bits</li></ul>
  *
- * \return         \c 0 on success or #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH
- *                 on failure.
+ * \return         \c 0 on success.
+ * \return         #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure.
  */
 int mbedtls_aes_setkey_enc( mbedtls_aes_context *ctx, const unsigned char *key,
                     unsigned int keybits );
@@ -128,7 +135,8 @@
  *                 <li>192 bits</li>
  *                 <li>256 bits</li></ul>
  *
- * \return         \c 0 on success, or #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure.
+ * \return         \c 0 on success.
+ * \return         #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure.
  */
 int mbedtls_aes_setkey_dec( mbedtls_aes_context *ctx, const unsigned char *key,
                     unsigned int keybits );
@@ -192,7 +200,8 @@
  * \param input    The buffer holding the input data.
  * \param output   The buffer holding the output data.
  *
- * \return         \c 0 on success, or #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH
+ * \return         \c 0 on success.
+ * \return         #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH
  *                 on failure.
  */
 int mbedtls_aes_crypt_cbc( mbedtls_aes_context *ctx,
@@ -330,7 +339,7 @@
  * \param input            The buffer holding the input data.
  * \param output           The buffer holding the output data.
  *
- * \return     \c 0 on success.
+ * \return                 \c 0 on success.
  */
 int mbedtls_aes_crypt_ctr( mbedtls_aes_context *ctx,
                        size_t length,
@@ -408,22 +417,11 @@
 #undef MBEDTLS_DEPRECATED
 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
 
-#ifdef __cplusplus
-}
-#endif
-
-#else  /* MBEDTLS_AES_ALT */
-#include "aes_alt.h"
-#endif /* MBEDTLS_AES_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
 /**
  * \brief          Checkup routine.
  *
- * \return         \c 0 on success, or \c 1 on failure.
+ * \return         \c 0 on success.
+ * \return         \c 1 on failure.
  */
 int mbedtls_aes_self_test( int verbose );
 
diff --git a/include/mbedtls/arc4.h b/include/mbedtls/arc4.h
index f9d93f8..f11fc5b 100644
--- a/include/mbedtls/arc4.h
+++ b/include/mbedtls/arc4.h
@@ -38,14 +38,14 @@
 
 #define MBEDTLS_ERR_ARC4_HW_ACCEL_FAILED                  -0x0019  /**< ARC4 hardware accelerator failed. */
 
-#if !defined(MBEDTLS_ARC4_ALT)
-// Regular implementation
-//
-
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+#if !defined(MBEDTLS_ARC4_ALT)
+// Regular implementation
+//
+
 /**
  * \brief     ARC4 context structure
  *
@@ -61,6 +61,10 @@
 }
 mbedtls_arc4_context;
 
+#else  /* MBEDTLS_ARC4_ALT */
+#include "arc4_alt.h"
+#endif /* MBEDTLS_ARC4_ALT */
+
 /**
  * \brief          Initialize ARC4 context
  *
@@ -118,18 +122,6 @@
 int mbedtls_arc4_crypt( mbedtls_arc4_context *ctx, size_t length, const unsigned char *input,
                 unsigned char *output );
 
-#ifdef __cplusplus
-}
-#endif
-
-#else  /* MBEDTLS_ARC4_ALT */
-#include "arc4_alt.h"
-#endif /* MBEDTLS_ARC4_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
 /**
  * \brief          Checkup routine
  *
diff --git a/include/mbedtls/asn1.h b/include/mbedtls/asn1.h
index fde328a..96c1c9a 100644
--- a/include/mbedtls/asn1.h
+++ b/include/mbedtls/asn1.h
@@ -88,6 +88,21 @@
 #define MBEDTLS_ASN1_PRIMITIVE               0x00
 #define MBEDTLS_ASN1_CONSTRUCTED             0x20
 #define MBEDTLS_ASN1_CONTEXT_SPECIFIC        0x80
+
+/*
+ * Bit masks for each of the components of an ASN.1 tag as specified in
+ * ITU X.690 (08/2015), section 8.1 "General rules for encoding",
+ * paragraph 8.1.2.2:
+ *
+ * Bit  8     7   6   5          1
+ *     +-------+-----+------------+
+ *     | Class | P/C | Tag number |
+ *     +-------+-----+------------+
+ */
+#define MBEDTLS_ASN1_TAG_CLASS_MASK          0xC0
+#define MBEDTLS_ASN1_TAG_PC_MASK             0x20
+#define MBEDTLS_ASN1_TAG_VALUE_MASK          0x1F
+
 /* \} name */
 /* \} addtogroup asn1_module */
 
diff --git a/include/mbedtls/bignum.h b/include/mbedtls/bignum.h
index 3bf02a7..31383b1 100644
--- a/include/mbedtls/bignum.h
+++ b/include/mbedtls/bignum.h
@@ -204,6 +204,8 @@
 /**
  * \brief          Enlarge to the specified number of limbs
  *
+ *                 This function does nothing if the MPI is already large enough.
+ *
  * \param X        MPI to grow
  * \param nblimbs  The target number of limbs
  *
@@ -215,19 +217,23 @@
 /**
  * \brief          Resize down, keeping at least the specified number of limbs
  *
+ *                 If \c X is smaller than \c nblimbs, it is resized up
+ *                 instead.
+ *
  * \param X        MPI to shrink
  * \param nblimbs  The minimum number of limbs to keep
  *
  * \return         0 if successful,
  *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ *                 (this can only happen when resizing up).
  */
 int mbedtls_mpi_shrink( mbedtls_mpi *X, size_t nblimbs );
 
 /**
  * \brief          Copy the contents of Y into X
  *
- * \param X        Destination MPI
- * \param Y        Source MPI
+ * \param X        Destination MPI. It is enlarged if necessary.
+ * \param Y        Source MPI.
  *
  * \return         0 if successful,
  *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
diff --git a/include/mbedtls/blowfish.h b/include/mbedtls/blowfish.h
index f4e8afc..0318db6 100644
--- a/include/mbedtls/blowfish.h
+++ b/include/mbedtls/blowfish.h
@@ -44,14 +44,14 @@
 #define MBEDTLS_ERR_BLOWFISH_HW_ACCEL_FAILED                   -0x0017  /**< Blowfish hardware accelerator failed. */
 #define MBEDTLS_ERR_BLOWFISH_INVALID_INPUT_LENGTH              -0x0018  /**< Invalid data input length. */
 
-#if !defined(MBEDTLS_BLOWFISH_ALT)
-// Regular implementation
-//
-
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+#if !defined(MBEDTLS_BLOWFISH_ALT)
+// Regular implementation
+//
+
 /**
  * \brief          Blowfish context structure
  */
@@ -62,6 +62,10 @@
 }
 mbedtls_blowfish_context;
 
+#else  /* MBEDTLS_BLOWFISH_ALT */
+#include "blowfish_alt.h"
+#endif /* MBEDTLS_BLOWFISH_ALT */
+
 /**
  * \brief          Initialize Blowfish context
  *
@@ -215,8 +219,4 @@
 }
 #endif
 
-#else  /* MBEDTLS_BLOWFISH_ALT */
-#include "blowfish_alt.h"
-#endif /* MBEDTLS_BLOWFISH_ALT */
-
 #endif /* blowfish.h */
diff --git a/include/mbedtls/camellia.h b/include/mbedtls/camellia.h
index 74e0961..2eb945d 100644
--- a/include/mbedtls/camellia.h
+++ b/include/mbedtls/camellia.h
@@ -40,14 +40,14 @@
 #define MBEDTLS_ERR_CAMELLIA_INVALID_INPUT_LENGTH         -0x0026  /**< Invalid data input length. */
 #define MBEDTLS_ERR_CAMELLIA_HW_ACCEL_FAILED              -0x0027  /**< Camellia hardware accelerator failed. */
 
-#if !defined(MBEDTLS_CAMELLIA_ALT)
-// Regular implementation
-//
-
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+#if !defined(MBEDTLS_CAMELLIA_ALT)
+// Regular implementation
+//
+
 /**
  * \brief          CAMELLIA context structure
  */
@@ -58,6 +58,10 @@
 }
 mbedtls_camellia_context;
 
+#else  /* MBEDTLS_CAMELLIA_ALT */
+#include "camellia_alt.h"
+#endif /* MBEDTLS_CAMELLIA_ALT */
+
 /**
  * \brief          Initialize CAMELLIA context
  *
@@ -228,18 +232,6 @@
                        unsigned char *output );
 #endif /* MBEDTLS_CIPHER_MODE_CTR */
 
-#ifdef __cplusplus
-}
-#endif
-
-#else  /* MBEDTLS_CAMELLIA_ALT */
-#include "camellia_alt.h"
-#endif /* MBEDTLS_CAMELLIA_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
 /**
  * \brief          Checkup routine
  *
diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h
index 630b7fd..8585ce5 100644
--- a/include/mbedtls/ccm.h
+++ b/include/mbedtls/ccm.h
@@ -1,8 +1,11 @@
 /**
  * \file ccm.h
  *
- * \brief CCM combines Counter mode encryption with CBC-MAC authentication
- *        for 128-bit block ciphers.
+ * \brief This file provides an API for the CCM authenticated encryption
+ *        mode for block ciphers.
+ *
+ * CCM combines Counter mode encryption with CBC-MAC authentication
+ * for 128-bit block ciphers.
  *
  * Input to CCM includes the following elements:
  * <ul><li>Payload - data that is both authenticated and encrypted.</li>
@@ -40,14 +43,15 @@
 #define MBEDTLS_ERR_CCM_AUTH_FAILED     -0x000F /**< Authenticated decryption failed. */
 #define MBEDTLS_ERR_CCM_HW_ACCEL_FAILED -0x0011 /**< CCM hardware accelerator failed. */
 
-#if !defined(MBEDTLS_CCM_ALT)
-// Regular implementation
-//
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+#if !defined(MBEDTLS_CCM_ALT)
+// Regular implementation
+//
+
 /**
  * \brief    The CCM context-type definition. The CCM context is passed
  *           to the APIs called.
@@ -57,6 +61,10 @@
 }
 mbedtls_ccm_context;
 
+#else  /* MBEDTLS_CCM_ALT */
+#include "ccm_alt.h"
+#endif /* MBEDTLS_CCM_ALT */
+
 /**
  * \brief           This function initializes the specified CCM context,
  *                  to make references valid, and prepare the context
@@ -75,7 +83,8 @@
  * \param key       The encryption key.
  * \param keybits   The key size in bits. This must be acceptable by the cipher.
  *
- * \return          \c 0 on success, or a cipher-specific error code.
+ * \return          \c 0 on success.
+ * \return          A CCM or cipher-specific error code on failure.
  */
 int mbedtls_ccm_setkey( mbedtls_ccm_context *ctx,
                         mbedtls_cipher_id_t cipher,
@@ -93,6 +102,13 @@
 /**
  * \brief           This function encrypts a buffer using CCM.
  *
+ *
+ * \note            The tag is written to a separate buffer. To concatenate
+ *                  the \p tag with the \p output, as done in <em>RFC-3610:
+ *                  Counter with CBC-MAC (CCM)</em>, use
+ *                  \p tag = \p output + \p length, and make sure that the
+ *                  output buffer is at least \p length + \p tag_len wide.
+ *
  * \param ctx       The CCM context to use for encryption.
  * \param length    The length of the input data in Bytes.
  * \param iv        Initialization vector (nonce).
@@ -107,13 +123,8 @@
  * \param tag_len   The length of the tag to generate in Bytes:
  *                  4, 6, 8, 10, 12, 14 or 16.
  *
- * \note            The tag is written to a separate buffer. To concatenate
- *                  the \p tag with the \p output, as done in <em>RFC-3610:
- *                  Counter with CBC-MAC (CCM)</em>, use
- *                  \p tag = \p output + \p length, and make sure that the
- *                  output buffer is at least \p length + \p tag_len wide.
- *
  * \return          \c 0 on success.
+ * \return          A CCM or cipher-specific error code on failure.
  */
 int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length,
                          const unsigned char *iv, size_t iv_len,
@@ -139,8 +150,9 @@
  * \param tag_len   The length of the tag in Bytes.
  *                  4, 6, 8, 10, 12, 14 or 16.
  *
- * \return          0 if successful and authenticated, or
- *                  #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match.
+ * \return          \c 0 on success. This indicates that the message is authentic.
+ * \return          #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match.
+ * \return          A cipher-specific error code on calculation failure.
  */
 int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length,
                       const unsigned char *iv, size_t iv_len,
@@ -148,23 +160,13 @@
                       const unsigned char *input, unsigned char *output,
                       const unsigned char *tag, size_t tag_len );
 
-#ifdef __cplusplus
-}
-#endif
-
-#else  /* MBEDTLS_CCM_ALT */
-#include "ccm_alt.h"
-#endif /* MBEDTLS_CCM_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
 
 #if defined(MBEDTLS_SELF_TEST) && defined(MBEDTLS_AES_C)
 /**
  * \brief          The CCM checkup routine.
  *
- * \return         \c 0 on success, or \c 1 on failure.
+ * \return         \c 0 on success.
+ * \return         \c 1 on failure.
  */
 int mbedtls_ccm_self_test( int verbose );
 #endif /* MBEDTLS_SELF_TEST && MBEDTLS_AES_C */
diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h
index fec259f..46b3bdf 100644
--- a/include/mbedtls/cipher.h
+++ b/include/mbedtls/cipher.h
@@ -1,7 +1,9 @@
 /**
  * \file cipher.h
  *
- * \brief The generic cipher wrapper.
+ * \brief This file contains an abstraction interface for use with the cipher
+ * primitives provided by the library. It provides a common interface to all of
+ * the available cipher operations.
  *
  * \author Adriaan de Jong <dejong@fox-it.com>
  */
@@ -69,112 +71,112 @@
 #endif
 
 /**
- * \brief     An enumeration of supported ciphers.
+ * \brief     Supported cipher types.
  *
- * \warning   ARC4 and DES are considered weak ciphers and their use
- *            constitutes a security risk. We recommend considering stronger
+ * \warning   RC4 and DES are considered weak ciphers and their use
+ *            constitutes a security risk. Arm recommends considering stronger
  *            ciphers instead.
  */
 typedef enum {
-    MBEDTLS_CIPHER_ID_NONE = 0,
-    MBEDTLS_CIPHER_ID_NULL,
-    MBEDTLS_CIPHER_ID_AES,
-    MBEDTLS_CIPHER_ID_DES,
-    MBEDTLS_CIPHER_ID_3DES,
-    MBEDTLS_CIPHER_ID_CAMELLIA,
-    MBEDTLS_CIPHER_ID_BLOWFISH,
-    MBEDTLS_CIPHER_ID_ARC4,
-    MBEDTLS_CIPHER_ID_ARIA,
+    MBEDTLS_CIPHER_ID_NONE = 0,  /**< Placeholder to mark the end of cipher ID lists. */
+    MBEDTLS_CIPHER_ID_NULL,      /**< The identity cipher, treated as a stream cipher. */
+    MBEDTLS_CIPHER_ID_AES,       /**< The AES cipher. */
+    MBEDTLS_CIPHER_ID_DES,       /**< The DES cipher. */
+    MBEDTLS_CIPHER_ID_3DES,      /**< The Triple DES cipher. */
+    MBEDTLS_CIPHER_ID_CAMELLIA,  /**< The Camellia cipher. */
+    MBEDTLS_CIPHER_ID_BLOWFISH,  /**< The Blowfish cipher. */
+    MBEDTLS_CIPHER_ID_ARC4,      /**< The RC4 cipher. */
+    MBEDTLS_CIPHER_ID_ARIA,      /**< The Aria cipher. */
 } mbedtls_cipher_id_t;
 
 /**
- * \brief     An enumeration of supported (cipher, mode) pairs.
+ * \brief     Supported {cipher type, cipher mode} pairs.
  *
- * \warning   ARC4 and DES are considered weak ciphers and their use
- *            constitutes a security risk. We recommend considering stronger
+ * \warning   RC4 and DES are considered weak ciphers and their use
+ *            constitutes a security risk. Arm recommends considering stronger
  *            ciphers instead.
  */
 typedef enum {
-    MBEDTLS_CIPHER_NONE = 0,
-    MBEDTLS_CIPHER_NULL,
-    MBEDTLS_CIPHER_AES_128_ECB,
-    MBEDTLS_CIPHER_AES_192_ECB,
-    MBEDTLS_CIPHER_AES_256_ECB,
-    MBEDTLS_CIPHER_AES_128_CBC,
-    MBEDTLS_CIPHER_AES_192_CBC,
-    MBEDTLS_CIPHER_AES_256_CBC,
-    MBEDTLS_CIPHER_AES_128_CFB128,
-    MBEDTLS_CIPHER_AES_192_CFB128,
-    MBEDTLS_CIPHER_AES_256_CFB128,
-    MBEDTLS_CIPHER_AES_128_CTR,
-    MBEDTLS_CIPHER_AES_192_CTR,
-    MBEDTLS_CIPHER_AES_256_CTR,
-    MBEDTLS_CIPHER_AES_128_GCM,
-    MBEDTLS_CIPHER_AES_192_GCM,
-    MBEDTLS_CIPHER_AES_256_GCM,
-    MBEDTLS_CIPHER_CAMELLIA_128_ECB,
-    MBEDTLS_CIPHER_CAMELLIA_192_ECB,
-    MBEDTLS_CIPHER_CAMELLIA_256_ECB,
-    MBEDTLS_CIPHER_CAMELLIA_128_CBC,
-    MBEDTLS_CIPHER_CAMELLIA_192_CBC,
-    MBEDTLS_CIPHER_CAMELLIA_256_CBC,
-    MBEDTLS_CIPHER_CAMELLIA_128_CFB128,
-    MBEDTLS_CIPHER_CAMELLIA_192_CFB128,
-    MBEDTLS_CIPHER_CAMELLIA_256_CFB128,
-    MBEDTLS_CIPHER_CAMELLIA_128_CTR,
-    MBEDTLS_CIPHER_CAMELLIA_192_CTR,
-    MBEDTLS_CIPHER_CAMELLIA_256_CTR,
-    MBEDTLS_CIPHER_CAMELLIA_128_GCM,
-    MBEDTLS_CIPHER_CAMELLIA_192_GCM,
-    MBEDTLS_CIPHER_CAMELLIA_256_GCM,
-    MBEDTLS_CIPHER_DES_ECB,
-    MBEDTLS_CIPHER_DES_CBC,
-    MBEDTLS_CIPHER_DES_EDE_ECB,
-    MBEDTLS_CIPHER_DES_EDE_CBC,
-    MBEDTLS_CIPHER_DES_EDE3_ECB,
-    MBEDTLS_CIPHER_DES_EDE3_CBC,
-    MBEDTLS_CIPHER_BLOWFISH_ECB,
-    MBEDTLS_CIPHER_BLOWFISH_CBC,
-    MBEDTLS_CIPHER_BLOWFISH_CFB64,
-    MBEDTLS_CIPHER_BLOWFISH_CTR,
-    MBEDTLS_CIPHER_ARC4_128,
-    MBEDTLS_CIPHER_AES_128_CCM,
-    MBEDTLS_CIPHER_AES_192_CCM,
-    MBEDTLS_CIPHER_AES_256_CCM,
-    MBEDTLS_CIPHER_CAMELLIA_128_CCM,
-    MBEDTLS_CIPHER_CAMELLIA_192_CCM,
-    MBEDTLS_CIPHER_CAMELLIA_256_CCM,
-    MBEDTLS_CIPHER_ARIA_128_ECB,
-    MBEDTLS_CIPHER_ARIA_192_ECB,
-    MBEDTLS_CIPHER_ARIA_256_ECB,
-    MBEDTLS_CIPHER_ARIA_128_CBC,
-    MBEDTLS_CIPHER_ARIA_192_CBC,
-    MBEDTLS_CIPHER_ARIA_256_CBC,
-    MBEDTLS_CIPHER_ARIA_128_CFB128,
-    MBEDTLS_CIPHER_ARIA_192_CFB128,
-    MBEDTLS_CIPHER_ARIA_256_CFB128,
-    MBEDTLS_CIPHER_ARIA_128_CTR,
-    MBEDTLS_CIPHER_ARIA_192_CTR,
-    MBEDTLS_CIPHER_ARIA_256_CTR,
-    MBEDTLS_CIPHER_ARIA_128_GCM,
-    MBEDTLS_CIPHER_ARIA_192_GCM,
-    MBEDTLS_CIPHER_ARIA_256_GCM,
-    MBEDTLS_CIPHER_ARIA_128_CCM,
-    MBEDTLS_CIPHER_ARIA_192_CCM,
-    MBEDTLS_CIPHER_ARIA_256_CCM,
+    MBEDTLS_CIPHER_NONE = 0,             /**< Placeholder to mark the end of cipher-pair lists. */
+    MBEDTLS_CIPHER_NULL,                 /**< The identity stream cipher. */
+    MBEDTLS_CIPHER_AES_128_ECB,          /**< AES cipher with 128-bit ECB mode. */
+    MBEDTLS_CIPHER_AES_192_ECB,          /**< AES cipher with 192-bit ECB mode. */
+    MBEDTLS_CIPHER_AES_256_ECB,          /**< AES cipher with 256-bit ECB mode. */
+    MBEDTLS_CIPHER_AES_128_CBC,          /**< AES cipher with 128-bit CBC mode. */
+    MBEDTLS_CIPHER_AES_192_CBC,          /**< AES cipher with 192-bit CBC mode. */
+    MBEDTLS_CIPHER_AES_256_CBC,          /**< AES cipher with 256-bit CBC mode. */
+    MBEDTLS_CIPHER_AES_128_CFB128,       /**< AES cipher with 128-bit CFB128 mode. */
+    MBEDTLS_CIPHER_AES_192_CFB128,       /**< AES cipher with 192-bit CFB128 mode. */
+    MBEDTLS_CIPHER_AES_256_CFB128,       /**< AES cipher with 256-bit CFB128 mode. */
+    MBEDTLS_CIPHER_AES_128_CTR,          /**< AES cipher with 128-bit CTR mode. */
+    MBEDTLS_CIPHER_AES_192_CTR,          /**< AES cipher with 192-bit CTR mode. */
+    MBEDTLS_CIPHER_AES_256_CTR,          /**< AES cipher with 256-bit CTR mode. */
+    MBEDTLS_CIPHER_AES_128_GCM,          /**< AES cipher with 128-bit GCM mode. */
+    MBEDTLS_CIPHER_AES_192_GCM,          /**< AES cipher with 192-bit GCM mode. */
+    MBEDTLS_CIPHER_AES_256_GCM,          /**< AES cipher with 256-bit GCM mode. */
+    MBEDTLS_CIPHER_CAMELLIA_128_ECB,     /**< Camellia cipher with 128-bit ECB mode. */
+    MBEDTLS_CIPHER_CAMELLIA_192_ECB,     /**< Camellia cipher with 192-bit ECB mode. */
+    MBEDTLS_CIPHER_CAMELLIA_256_ECB,     /**< Camellia cipher with 256-bit ECB mode. */
+    MBEDTLS_CIPHER_CAMELLIA_128_CBC,     /**< Camellia cipher with 128-bit CBC mode. */
+    MBEDTLS_CIPHER_CAMELLIA_192_CBC,     /**< Camellia cipher with 192-bit CBC mode. */
+    MBEDTLS_CIPHER_CAMELLIA_256_CBC,     /**< Camellia cipher with 256-bit CBC mode. */
+    MBEDTLS_CIPHER_CAMELLIA_128_CFB128,  /**< Camellia cipher with 128-bit CFB128 mode. */
+    MBEDTLS_CIPHER_CAMELLIA_192_CFB128,  /**< Camellia cipher with 192-bit CFB128 mode. */
+    MBEDTLS_CIPHER_CAMELLIA_256_CFB128,  /**< Camellia cipher with 256-bit CFB128 mode. */
+    MBEDTLS_CIPHER_CAMELLIA_128_CTR,     /**< Camellia cipher with 128-bit CTR mode. */
+    MBEDTLS_CIPHER_CAMELLIA_192_CTR,     /**< Camellia cipher with 192-bit CTR mode. */
+    MBEDTLS_CIPHER_CAMELLIA_256_CTR,     /**< Camellia cipher with 256-bit CTR mode. */
+    MBEDTLS_CIPHER_CAMELLIA_128_GCM,     /**< Camellia cipher with 128-bit GCM mode. */
+    MBEDTLS_CIPHER_CAMELLIA_192_GCM,     /**< Camellia cipher with 192-bit GCM mode. */
+    MBEDTLS_CIPHER_CAMELLIA_256_GCM,     /**< Camellia cipher with 256-bit GCM mode. */
+    MBEDTLS_CIPHER_DES_ECB,              /**< DES cipher with ECB mode. */
+    MBEDTLS_CIPHER_DES_CBC,              /**< DES cipher with CBC mode. */
+    MBEDTLS_CIPHER_DES_EDE_ECB,          /**< DES cipher with EDE ECB mode. */
+    MBEDTLS_CIPHER_DES_EDE_CBC,          /**< DES cipher with EDE CBC mode. */
+    MBEDTLS_CIPHER_DES_EDE3_ECB,         /**< DES cipher with EDE3 ECB mode. */
+    MBEDTLS_CIPHER_DES_EDE3_CBC,         /**< DES cipher with EDE3 CBC mode. */
+    MBEDTLS_CIPHER_BLOWFISH_ECB,         /**< Blowfish cipher with ECB mode. */
+    MBEDTLS_CIPHER_BLOWFISH_CBC,         /**< Blowfish cipher with CBC mode. */
+    MBEDTLS_CIPHER_BLOWFISH_CFB64,       /**< Blowfish cipher with CFB64 mode. */
+    MBEDTLS_CIPHER_BLOWFISH_CTR,         /**< Blowfish cipher with CTR mode. */
+    MBEDTLS_CIPHER_ARC4_128,             /**< RC4 cipher with 128-bit mode. */
+    MBEDTLS_CIPHER_AES_128_CCM,          /**< AES cipher with 128-bit CCM mode. */
+    MBEDTLS_CIPHER_AES_192_CCM,          /**< AES cipher with 192-bit CCM mode. */
+    MBEDTLS_CIPHER_AES_256_CCM,          /**< AES cipher with 256-bit CCM mode. */
+    MBEDTLS_CIPHER_CAMELLIA_128_CCM,     /**< Camellia cipher with 128-bit CCM mode. */
+    MBEDTLS_CIPHER_CAMELLIA_192_CCM,     /**< Camellia cipher with 192-bit CCM mode. */
+    MBEDTLS_CIPHER_CAMELLIA_256_CCM,     /**< Camellia cipher with 256-bit CCM mode. */
+    MBEDTLS_CIPHER_ARIA_128_ECB,         /**< Aria cipher with 128-bit key and ECB mode. */
+    MBEDTLS_CIPHER_ARIA_192_ECB,         /**< Aria cipher with 192-bit key and ECB mode. */
+    MBEDTLS_CIPHER_ARIA_256_ECB,         /**< Aria cipher with 256-bit key and ECB mode. */
+    MBEDTLS_CIPHER_ARIA_128_CBC,         /**< Aria cipher with 128-bit key and CBC mode. */
+    MBEDTLS_CIPHER_ARIA_192_CBC,         /**< Aria cipher with 192-bit key and CBC mode. */
+    MBEDTLS_CIPHER_ARIA_256_CBC,         /**< Aria cipher with 256-bit key and CBC mode. */
+    MBEDTLS_CIPHER_ARIA_128_CFB128,      /**< Aria cipher with 128-bit key and CFB-128 mode. */
+    MBEDTLS_CIPHER_ARIA_192_CFB128,      /**< Aria cipher with 192-bit key and CFB-128 mode. */
+    MBEDTLS_CIPHER_ARIA_256_CFB128,      /**< Aria cipher with 256-bit key and CFB-128 mode. */
+    MBEDTLS_CIPHER_ARIA_128_CTR,         /**< Aria cipher with 128-bit key and CTR mode. */
+    MBEDTLS_CIPHER_ARIA_192_CTR,         /**< Aria cipher with 192-bit key and CTR mode. */
+    MBEDTLS_CIPHER_ARIA_256_CTR,         /**< Aria cipher with 256-bit key and CTR mode. */
+    MBEDTLS_CIPHER_ARIA_128_GCM,         /**< Aria cipher with 128-bit key and GCM mode. */
+    MBEDTLS_CIPHER_ARIA_192_GCM,         /**< Aria cipher with 192-bit key and GCM mode. */
+    MBEDTLS_CIPHER_ARIA_256_GCM,         /**< Aria cipher with 256-bit key and GCM mode. */
+    MBEDTLS_CIPHER_ARIA_128_CCM,         /**< Aria cipher with 128-bit key and CCM mode. */
+    MBEDTLS_CIPHER_ARIA_192_CCM,         /**< Aria cipher with 192-bit key and CCM mode. */
+    MBEDTLS_CIPHER_ARIA_256_CCM,         /**< Aria cipher with 256-bit key and CCM mode. */
 } mbedtls_cipher_type_t;
 
 /** Supported cipher modes. */
 typedef enum {
-    MBEDTLS_MODE_NONE = 0,
-    MBEDTLS_MODE_ECB,
-    MBEDTLS_MODE_CBC,
-    MBEDTLS_MODE_CFB,
-    MBEDTLS_MODE_OFB, /* Unused! */
-    MBEDTLS_MODE_CTR,
-    MBEDTLS_MODE_GCM,
-    MBEDTLS_MODE_STREAM,
-    MBEDTLS_MODE_CCM,
+    MBEDTLS_MODE_NONE = 0,               /**< None. */
+    MBEDTLS_MODE_ECB,                    /**< The ECB cipher mode. */
+    MBEDTLS_MODE_CBC,                    /**< The CBC cipher mode. */
+    MBEDTLS_MODE_CFB,                    /**< The CFB cipher mode. */
+    MBEDTLS_MODE_OFB,                    /**< The OFB cipher mode - unsupported. */
+    MBEDTLS_MODE_CTR,                    /**< The CTR cipher mode. */
+    MBEDTLS_MODE_GCM,                    /**< The GCM cipher mode. */
+    MBEDTLS_MODE_STREAM,                 /**< The stream cipher mode. */
+    MBEDTLS_MODE_CCM,                    /**< The CCM cipher mode. */
 } mbedtls_cipher_mode_t;
 
 /** Supported cipher padding types. */
@@ -182,8 +184,8 @@
     MBEDTLS_PADDING_PKCS7 = 0,     /**< PKCS7 padding (default).        */
     MBEDTLS_PADDING_ONE_AND_ZEROS, /**< ISO/IEC 7816-4 padding.         */
     MBEDTLS_PADDING_ZEROS_AND_LEN, /**< ANSI X.923 padding.             */
-    MBEDTLS_PADDING_ZEROS,         /**< zero padding (not reversible). */
-    MBEDTLS_PADDING_NONE,          /**< never pad (full blocks only).   */
+    MBEDTLS_PADDING_ZEROS,         /**< Zero padding (not reversible). */
+    MBEDTLS_PADDING_NONE,          /**< Never pad (full blocks only).   */
 } mbedtls_cipher_padding_t;
 
 /** Type of operation. */
@@ -247,7 +249,10 @@
      */
     unsigned int iv_size;
 
-    /** Flags to set. For example, if the cipher supports variable IV sizes or variable key sizes. */
+    /** Bitflag comprised of MBEDTLS_CIPHER_VARIABLE_IV_LEN and
+     *  MBEDTLS_CIPHER_VARIABLE_KEY_LEN indicating whether the
+     *  cipher supports variable IV or variable key sizes, respectively.
+     */
     int flags;
 
     /** The block size, in Bytes. */
@@ -318,7 +323,8 @@
  * \param cipher_name   Name of the cipher to search for.
  *
  * \return              The cipher information structure associated with the
- *                      given \p cipher_name, or NULL if not found.
+ *                      given \p cipher_name.
+ * \return              NULL if the associated cipher information is not found.
  */
 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_string( const char *cipher_name );
 
@@ -329,7 +335,8 @@
  * \param cipher_type   Type of the cipher to search for.
  *
  * \return              The cipher information structure associated with the
- *                      given \p cipher_type, or NULL if not found.
+ *                      given \p cipher_type.
+ * \return              NULL if the associated cipher information is not found.
  */
 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_type( const mbedtls_cipher_type_t cipher_type );
 
@@ -344,7 +351,8 @@
  * \param mode          The cipher mode. For example, #MBEDTLS_MODE_CBC.
  *
  * \return              The cipher information structure associated with the
- *                      given \p cipher_id, or NULL if not found.
+ *                      given \p cipher_id.
+ * \return              NULL if the associated cipher information is not found.
  */
 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_values( const mbedtls_cipher_id_t cipher_id,
                                               int key_bitlen,
@@ -371,10 +379,11 @@
  * \param ctx           The context to initialize. May not be NULL.
  * \param cipher_info   The cipher to use.
  *
- * \return              \c 0 on success,
- *                      #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on parameter failure,
- *                      #MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the
- *                      cipher-specific context failed.
+ * \return              \c 0 on success.
+ * \return              #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
+ *                      parameter-verification failure.
+ * \return              #MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the
+ *                      cipher-specific context fails.
  *
  * \internal Currently, the function also clears the structure.
  * In future versions, the caller will be required to call
@@ -387,8 +396,8 @@
  *
  * \param ctx    The context of the cipher. Must be initialized.
  *
- * \return       The size of the blocks of the cipher, or zero if \p ctx
- *               has not been initialized.
+ * \return       The size of the blocks of the cipher.
+ * \return       0 if \p ctx has not been initialized.
  */
 static inline unsigned int mbedtls_cipher_get_block_size( const mbedtls_cipher_context_t *ctx )
 {
@@ -404,8 +413,8 @@
  *
  * \param ctx    The context of the cipher. Must be initialized.
  *
- * \return       The mode of operation, or #MBEDTLS_MODE_NONE if
- *               \p ctx has not been initialized.
+ * \return       The mode of operation.
+ * \return       #MBEDTLS_MODE_NONE if \p ctx has not been initialized.
  */
 static inline mbedtls_cipher_mode_t mbedtls_cipher_get_cipher_mode( const mbedtls_cipher_context_t *ctx )
 {
@@ -421,9 +430,9 @@
  *
  * \param ctx   The context of the cipher. Must be initialized.
  *
- * \return      <ul><li>If no IV has been set: the recommended IV size.
- *              0 for ciphers not using IV or nonce.</li>
- *              <li>If IV has already been set: the actual size.</li></ul>
+ * \return      The recommended IV size if no IV has been set.
+ * \return      \c 0 for ciphers not using an IV or a nonce.
+ * \return      The actual size if an IV has been set.
  */
 static inline int mbedtls_cipher_get_iv_size( const mbedtls_cipher_context_t *ctx )
 {
@@ -441,8 +450,8 @@
  *
  * \param ctx           The context of the cipher. Must be initialized.
  *
- * \return              The type of the cipher, or #MBEDTLS_CIPHER_NONE if
- *                      \p ctx has not been initialized.
+ * \return              The type of the cipher.
+ * \return              #MBEDTLS_CIPHER_NONE if \p ctx has not been initialized.
  */
 static inline mbedtls_cipher_type_t mbedtls_cipher_get_type( const mbedtls_cipher_context_t *ctx )
 {
@@ -458,8 +467,8 @@
  *
  * \param ctx           The context of the cipher. Must be initialized.
  *
- * \return              The name of the cipher, or NULL if \p ctx has not
- *                      been not initialized.
+ * \return              The name of the cipher.
+ * \return              NULL if \p ctx has not been not initialized.
  */
 static inline const char *mbedtls_cipher_get_name( const mbedtls_cipher_context_t *ctx )
 {
@@ -474,8 +483,8 @@
  *
  * \param ctx           The context of the cipher. Must be initialized.
  *
- * \return              The key length of the cipher in bits, or
- *                      #MBEDTLS_KEY_LENGTH_NONE if ctx \p has not been
+ * \return              The key length of the cipher in bits.
+ * \return              #MBEDTLS_KEY_LENGTH_NONE if ctx \p has not been
  *                      initialized.
  */
 static inline int mbedtls_cipher_get_key_bitlen( const mbedtls_cipher_context_t *ctx )
@@ -491,9 +500,8 @@
  *
  * \param ctx      The context of the cipher. Must be initialized.
  *
- * \return         The type of operation: #MBEDTLS_ENCRYPT or
- *                 #MBEDTLS_DECRYPT, or #MBEDTLS_OPERATION_NONE if \p ctx
- *                 has not been initialized.
+ * \return         The type of operation: #MBEDTLS_ENCRYPT or #MBEDTLS_DECRYPT.
+ * \return         #MBEDTLS_OPERATION_NONE if \p ctx has not been initialized.
  */
 static inline mbedtls_operation_t mbedtls_cipher_get_operation( const mbedtls_cipher_context_t *ctx )
 {
@@ -514,9 +522,10 @@
  * \param operation     The operation that the key will be used for:
  *                      #MBEDTLS_ENCRYPT or #MBEDTLS_DECRYPT.
  *
- * \returns             \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
- *                      parameter verification fails, or a cipher-specific
- *                      error code.
+ * \return              \c 0 on success.
+ * \return              #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
+ *                      parameter-verification failure.
+ * \return              A cipher-specific error code on failure.
  */
 int mbedtls_cipher_setkey( mbedtls_cipher_context_t *ctx, const unsigned char *key,
                    int key_bitlen, const mbedtls_operation_t operation );
@@ -531,9 +540,10 @@
  * \param ctx           The generic cipher context.
  * \param mode          The padding mode.
  *
- * \returns             \c 0 on success, #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE
- *                      if the selected padding mode is not supported, or
- *                      #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode
+ * \return              \c 0 on success.
+ * \return              #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE
+ *                      if the selected padding mode is not supported.
+ * \return              #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode
  *                      does not support padding.
  */
 int mbedtls_cipher_set_padding_mode( mbedtls_cipher_context_t *ctx, mbedtls_cipher_padding_t mode );
@@ -543,15 +553,17 @@
  * \brief           This function sets the initialization vector (IV)
  *                  or nonce.
  *
+ * \note            Some ciphers do not use IVs nor nonce. For these
+ *                  ciphers, this function has no effect.
+ *
  * \param ctx       The generic cipher context.
  * \param iv        The IV to use, or NONCE_COUNTER for CTR-mode ciphers.
  * \param iv_len    The IV length for ciphers with variable-size IV.
  *                  This parameter is discarded by ciphers with fixed-size IV.
  *
- * \returns         \c 0 on success, or #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA
- *
- * \note            Some ciphers do not use IVs nor nonce. For these
- *                  ciphers, this function has no effect.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
+ *                  parameter-verification failure.
  */
 int mbedtls_cipher_set_iv( mbedtls_cipher_context_t *ctx,
                    const unsigned char *iv, size_t iv_len );
@@ -561,8 +573,9 @@
  *
  * \param ctx     The generic cipher context.
  *
- * \returns       \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA
- *                if parameter verification fails.
+ * \return        \c 0 on success.
+ * \return        #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
+ *                parameter-verification failure.
  */
 int mbedtls_cipher_reset( mbedtls_cipher_context_t *ctx );
 
@@ -576,7 +589,8 @@
  * \param ad            The additional data to use.
  * \param ad_len        the Length of \p ad.
  *
- * \return              \c 0 on success, or a specific error code on failure.
+ * \return              \c 0 on success.
+ * \return              A specific error code on failure.
  */
 int mbedtls_cipher_update_ad( mbedtls_cipher_context_t *ctx,
                       const unsigned char *ad, size_t ad_len );
@@ -592,6 +606,11 @@
  *                      Exception: For MBEDTLS_MODE_ECB, expects a single block
  *                      in size. For example, 16 Bytes for AES.
  *
+ * \note                If the underlying cipher is used in GCM mode, all calls
+ *                      to this function, except for the last one before
+ *                      mbedtls_cipher_finish(), must have \p ilen as a
+ *                      multiple of the block size of the cipher.
+ *
  * \param ctx           The generic cipher context.
  * \param input         The buffer holding the input data.
  * \param ilen          The length of the input data.
@@ -601,16 +620,12 @@
  * \param olen          The length of the output data, to be updated with the
  *                      actual number of Bytes written.
  *
- * \returns             \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
- *                      parameter verification fails,
- *                      #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE on an
- *                      unsupported mode for a cipher, or a cipher-specific
- *                      error code.
- *
- * \note                If the underlying cipher is GCM, all calls to this
- *                      function, except the last one before
- *                      mbedtls_cipher_finish(). Must have \p ilen as a
- *                      multiple of the block_size.
+ * \return              \c 0 on success.
+ * \return              #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
+ *                      parameter-verification failure.
+ * \return              #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE on an
+ *                      unsupported mode for a cipher.
+ * \return              A cipher-specific error code on failure.
  */
 int mbedtls_cipher_update( mbedtls_cipher_context_t *ctx, const unsigned char *input,
                    size_t ilen, unsigned char *output, size_t *olen );
@@ -625,13 +640,14 @@
  * \param output        The buffer to write data to. Needs block_size available.
  * \param olen          The length of the data written to the \p output buffer.
  *
- * \returns             \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
- *                      parameter verification fails,
- *                      #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption
- *                      expected a full block but was not provided one,
- *                      #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
- *                      while decrypting, or a cipher-specific error code
- *                      on failure for any other reason.
+ * \return              \c 0 on success.
+ * \return              #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
+ *                      parameter-verification failure.
+ * \return              #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED on decryption
+ *                      expecting a full block but not receiving one.
+ * \return              #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
+ *                      while decrypting.
+ * \return              A cipher-specific error code on failure.
  */
 int mbedtls_cipher_finish( mbedtls_cipher_context_t *ctx,
                    unsigned char *output, size_t *olen );
@@ -646,7 +662,8 @@
  * \param tag           The buffer to write the tag to.
  * \param tag_len       The length of the tag to write.
  *
- * \return              \c 0 on success, or a specific error code on failure.
+ * \return              \c 0 on success.
+ * \return              A specific error code on failure.
  */
 int mbedtls_cipher_write_tag( mbedtls_cipher_context_t *ctx,
                       unsigned char *tag, size_t tag_len );
@@ -660,7 +677,8 @@
  * \param tag           The buffer holding the tag.
  * \param tag_len       The length of the tag to check.
  *
- * \return              \c 0 on success, or a specific error code on failure.
+ * \return              \c 0 on success.
+ * \return              A specific error code on failure.
  */
 int mbedtls_cipher_check_tag( mbedtls_cipher_context_t *ctx,
                       const unsigned char *tag, size_t tag_len );
@@ -686,13 +704,14 @@
  * \note                Some ciphers do not use IVs nor nonce. For these
  *                      ciphers, use \p iv = NULL and \p iv_len = 0.
  *
- * \returns             \c 0 on success, or
- *                      #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
- *                      #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption
- *                      expected a full block but was not provided one, or
- *                      #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
- *                      while decrypting, or a cipher-specific error code on
- *                      failure for any other reason.
+ * \return              \c 0 on success.
+ * \return              #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
+ *                      parameter-verification failure.
+ * \return              #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED on decryption
+ *                      expecting a full block but not receiving one.
+ * \return              #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
+ *                      while decrypting.
+ * \return              A cipher-specific error code on failure.
  */
 int mbedtls_cipher_crypt( mbedtls_cipher_context_t *ctx,
                   const unsigned char *iv, size_t iv_len,
@@ -718,9 +737,10 @@
  * \param tag           The buffer for the authentication tag.
  * \param tag_len       The desired length of the authentication tag.
  *
- * \returns             \c 0 on success, or
- *                      #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
- *                      a cipher-specific error code.
+ * \return              \c 0 on success.
+ * \return              #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
+ *                      parameter-verification failure.
+ * \return              A cipher-specific error code on failure.
  */
 int mbedtls_cipher_auth_encrypt( mbedtls_cipher_context_t *ctx,
                          const unsigned char *iv, size_t iv_len,
@@ -732,6 +752,10 @@
 /**
  * \brief               The generic autenticated decryption (AEAD) function.
  *
+ * \note                If the data is not authentic, then the output buffer
+ *                      is zeroed out to prevent the unauthentic plaintext being
+ *                      used, making this interface safer.
+ *
  * \param ctx           The generic cipher context.
  * \param iv            The IV to use, or NONCE_COUNTER for CTR-mode ciphers.
  * \param iv_len        The IV length for ciphers with variable-size IV.
@@ -747,14 +771,11 @@
  * \param tag           The buffer holding the authentication tag.
  * \param tag_len       The length of the authentication tag.
  *
- * \returns             \c 0 on success, or
- *                      #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
- *                      #MBEDTLS_ERR_CIPHER_AUTH_FAILED if data is not authentic,
- *                      or a cipher-specific error code on failure for any other reason.
- *
- * \note                If the data is not authentic, then the output buffer
- *                      is zeroed out to prevent the unauthentic plaintext being
- *                      used, making this interface safer.
+ * \return              \c 0 on success.
+ * \return              #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
+ *                      parameter-verification failure.
+ * \return              #MBEDTLS_ERR_CIPHER_AUTH_FAILED if data is not authentic.
+ * \return              A cipher-specific error code on failure.
  */
 int mbedtls_cipher_auth_decrypt( mbedtls_cipher_context_t *ctx,
                          const unsigned char *iv, size_t iv_len,
diff --git a/include/mbedtls/cmac.h b/include/mbedtls/cmac.h
index 628c9da..913c05f 100644
--- a/include/mbedtls/cmac.h
+++ b/include/mbedtls/cmac.h
@@ -1,8 +1,10 @@
 /**
  * \file cmac.h
  *
- * \brief The Cipher-based Message Authentication Code (CMAC) Mode for
- *        Authentication.
+ * \brief This file contains CMAC definitions and functions.
+ *
+ * The Cipher-based Message Authentication Code (CMAC) Mode for
+ * Authentication is defined in <em>RFC-4493: The AES-CMAC Algorithm</em>.
  */
 /*
  *  Copyright (C) 2015-2018, Arm Limited (or its affiliates), All Rights Reserved
@@ -38,9 +40,9 @@
 #define MBEDTLS_DES3_BLOCK_SIZE         8
 
 #if defined(MBEDTLS_AES_C)
-#define MBEDTLS_CIPHER_BLKSIZE_MAX      16  /* The longest block used by CMAC is that of AES. */
+#define MBEDTLS_CIPHER_BLKSIZE_MAX      16  /**< The longest block used by CMAC is that of AES. */
 #else
-#define MBEDTLS_CIPHER_BLKSIZE_MAX      8   /* The longest block used by CMAC is that of 3DES. */
+#define MBEDTLS_CIPHER_BLKSIZE_MAX      8   /**< The longest block used by CMAC is that of 3DES. */
 #endif
 
 #if !defined(MBEDTLS_CMAC_ALT)
@@ -61,22 +63,25 @@
     size_t              unprocessed_len;
 };
 
+#else  /* !MBEDTLS_CMAC_ALT */
+#include "cmac_alt.h"
+#endif /* !MBEDTLS_CMAC_ALT */
+
 /**
  * \brief               This function sets the CMAC key, and prepares to authenticate
  *                      the input data.
  *                      Must be called with an initialized cipher context.
  *
  * \param ctx           The cipher context used for the CMAC operation, initialized
- *                      as one of the following types:<ul>
- *                      <li>MBEDTLS_CIPHER_AES_128_ECB</li>
- *                      <li>MBEDTLS_CIPHER_AES_192_ECB</li>
- *                      <li>MBEDTLS_CIPHER_AES_256_ECB</li>
- *                      <li>MBEDTLS_CIPHER_DES_EDE3_ECB</li></ul>
+ *                      as one of the following types: MBEDTLS_CIPHER_AES_128_ECB,
+ *                      MBEDTLS_CIPHER_AES_192_ECB, MBEDTLS_CIPHER_AES_256_ECB,
+ *                      or MBEDTLS_CIPHER_DES_EDE3_ECB.
  * \param key           The CMAC key.
  * \param keybits       The length of the CMAC key in bits.
  *                      Must be supported by the cipher.
  *
- * \return              \c 0 on success, or a cipher-specific error code.
+ * \return              \c 0 on success.
+ * \return              A cipher-specific error code on failure.
  */
 int mbedtls_cipher_cmac_starts( mbedtls_cipher_context_t *ctx,
                                 const unsigned char *key, size_t keybits );
@@ -93,8 +98,9 @@
  * \param input         The buffer holding the input data.
  * \param ilen          The length of the input data.
  *
- * \returns             \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
- *                      if parameter verification fails.
+ * \return             \c 0 on success.
+ * \return             #MBEDTLS_ERR_MD_BAD_INPUT_DATA
+ *                     if parameter verification fails.
  */
 int mbedtls_cipher_cmac_update( mbedtls_cipher_context_t *ctx,
                                 const unsigned char *input, size_t ilen );
@@ -110,7 +116,8 @@
  * \param ctx           The cipher context used for the CMAC operation.
  * \param output        The output buffer for the CMAC checksum result.
  *
- * \returns             \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
+ * \return              \c 0 on success.
+ * \return              #MBEDTLS_ERR_MD_BAD_INPUT_DATA
  *                      if parameter verification fails.
  */
 int mbedtls_cipher_cmac_finish( mbedtls_cipher_context_t *ctx,
@@ -126,7 +133,8 @@
  *
  * \param ctx           The cipher context used for the CMAC operation.
  *
- * \returns             \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
+ * \return              \c 0 on success.
+ * \return              #MBEDTLS_ERR_MD_BAD_INPUT_DATA
  *                      if parameter verification fails.
  */
 int mbedtls_cipher_cmac_reset( mbedtls_cipher_context_t *ctx );
@@ -149,7 +157,8 @@
  * \param ilen          The length of the input data.
  * \param output        The buffer for the generic CMAC result.
  *
- * \returns             \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
+ * \return              \c 0 on success.
+ * \return              #MBEDTLS_ERR_MD_BAD_INPUT_DATA
  *                      if parameter verification fails.
  */
 int mbedtls_cipher_cmac( const mbedtls_cipher_info_t *cipher_info,
@@ -180,23 +189,12 @@
                               unsigned char output[16] );
 #endif /* MBEDTLS_AES_C */
 
-#ifdef __cplusplus
-}
-#endif
-
-#else  /* !MBEDTLS_CMAC_ALT */
-#include "cmac_alt.h"
-#endif /* !MBEDTLS_CMAC_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
 #if defined(MBEDTLS_SELF_TEST) && ( defined(MBEDTLS_AES_C) || defined(MBEDTLS_DES_C) )
 /**
  * \brief          The CMAC checkup routine.
  *
- * \return         \c 0 on success, or \c 1 on failure.
+ * \return         \c 0 on success.
+ * \return         \c 1 on failure.
  */
 int mbedtls_cmac_self_test( int verbose );
 #endif /* MBEDTLS_SELF_TEST && ( MBEDTLS_AES_C || MBEDTLS_DES_C ) */
diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h
index 0a35e6e..ae10a4d 100644
--- a/include/mbedtls/config.h
+++ b/include/mbedtls/config.h
@@ -446,13 +446,46 @@
 /**
  * \def MBEDTLS_AES_ROM_TABLES
  *
- * Store the AES tables in ROM.
+ * Use precomputed AES tables stored in ROM.
  *
- * Uncomment this macro to store the AES tables in ROM.
+ * Uncomment this macro to use precomputed AES tables stored in ROM.
+ * Comment this macro to generate AES tables in RAM at runtime.
+ *
+ * Tradeoff: Using precomputed ROM tables reduces RAM usage by ~8kb
+ * (or ~2kb if \c MBEDTLS_AES_FEWER_TABLES is used) and reduces the
+ * initialization time before the first AES operation can be performed.
+ * It comes at the cost of additional ~8kb ROM use (resp. ~2kb if \c
+ * MBEDTLS_AES_FEWER_TABLES below is used), and potentially degraded
+ * performance if ROM access is slower than RAM access.
+ *
+ * This option is independent of \c MBEDTLS_AES_FEWER_TABLES.
+ *
  */
 //#define MBEDTLS_AES_ROM_TABLES
 
 /**
+ * \def MBEDTLS_AES_FEWER_TABLES
+ *
+ * Use less ROM/RAM for AES tables.
+ *
+ * Uncommenting this macro omits 75% of the AES tables from
+ * ROM / RAM (depending on the value of \c MBEDTLS_AES_ROM_TABLES)
+ * by computing their values on the fly during operations
+ * (the tables are entry-wise rotations of one another).
+ *
+ * Tradeoff: Uncommenting this reduces the RAM / ROM footprint
+ * by ~6kb but at the cost of more arithmetic operations during
+ * runtime. Specifically, one has to compare 4 accesses within
+ * different tables to 4 accesses with additional arithmetic
+ * operations within the same table. The performance gain/loss
+ * depends on the system and memory details.
+ *
+ * This option is independent of \c MBEDTLS_AES_ROM_TABLES.
+ *
+ */
+//#define MBEDTLS_AES_FEWER_TABLES
+
+/**
  * \def MBEDTLS_CAMELLIA_SMALL_MEMORY
  *
  * Use less ROM for the Camellia implementation (saves about 768 bytes).
@@ -582,6 +615,7 @@
 #define MBEDTLS_ECP_DP_BP384R1_ENABLED
 #define MBEDTLS_ECP_DP_BP512R1_ENABLED
 #define MBEDTLS_ECP_DP_CURVE25519_ENABLED
+#define MBEDTLS_ECP_DP_CURVE448_ENABLED
 
 /**
  * \def MBEDTLS_ECP_NIST_OPTIM
@@ -1055,7 +1089,8 @@
 /**
  * \def MBEDTLS_RSA_NO_CRT
  *
- * Do not use the Chinese Remainder Theorem for the RSA private operation.
+ * Do not use the Chinese Remainder Theorem
+ * for the RSA private operation.
  *
  * Uncomment this macro to disable the use of CRT in RSA.
  *
@@ -1547,6 +1582,9 @@
  *
  * \note Currently compression can't be used with DTLS.
  *
+ * \deprecated This feature is deprecated and will be removed
+ *             in the next major revision of the library.
+ *
  * Used in: library/ssl_tls.c
  *          library/ssl_cli.c
  *          library/ssl_srv.c
@@ -2872,6 +2910,26 @@
  */
 #define MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_KEY_EXCHANGE
 
+/**
+ * Uncomment the macro to let mbed TLS use your alternate implementation of
+ * mbedtls_platform_zeroize(). This replaces the default implementation in
+ * platform_util.c.
+ *
+ * mbedtls_platform_zeroize() is a widely used function across the library to
+ * zero a block of memory. The implementation is expected to be secure in the
+ * sense that it has been written to prevent the compiler from removing calls
+ * to mbedtls_platform_zeroize() as part of redundant code elimination
+ * optimizations. However, it is difficult to guarantee that calls to
+ * mbedtls_platform_zeroize() will not be optimized by the compiler as older
+ * versions of the C language standards do not provide a secure implementation
+ * of memset(). Therefore, MBEDTLS_PLATFORM_ZEROIZE_ALT enables users to
+ * configure their own implementation of mbedtls_platform_zeroize(), for
+ * example by using directives specific to their compiler, features from newer
+ * C standards (e.g using memset_s() in C11) or calling a secure memset() from
+ * their system (e.g explicit_bzero() in BSD).
+ */
+//#define MBEDTLS_PLATFORM_ZEROIZE_ALT
+
 /* \} name SECTION: Customisation configuration options */
 
 /* Target and application specific configurations */
diff --git a/include/mbedtls/ctr_drbg.h b/include/mbedtls/ctr_drbg.h
index 121575a..dcbc047 100644
--- a/include/mbedtls/ctr_drbg.h
+++ b/include/mbedtls/ctr_drbg.h
@@ -1,10 +1,15 @@
 /**
  * \file ctr_drbg.h
  *
- * \brief    CTR_DRBG is based on AES-256, as defined in <em>NIST SP 800-90A:
- *           Recommendation for Random Number Generation Using Deterministic
- *           Random Bit Generators</em>.
+ * \brief    This file contains CTR_DRBG definitions and functions.
  *
+ * CTR_DRBG is a standardized way of building a PRNG from a block-cipher
+ * in counter mode operation, as defined in <em>NIST SP 800-90A:
+ * Recommendation for Random Number Generation Using Deterministic Random
+ * Bit Generators</em>.
+ *
+ * The Mbed TLS implementation of CTR_DRBG uses AES-256 as the underlying
+ * block cipher.
  */
 /*
  *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
@@ -156,8 +161,8 @@
                         identifiers. Can be NULL.
  * \param len           The length of the personalization data.
  *
- * \return              \c 0 on success, or
- *                      #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
+ * \return              \c 0 on success.
+ * \return              #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
  */
 int mbedtls_ctr_drbg_seed( mbedtls_ctr_drbg_context *ctx,
                    int (*f_entropy)(void *, unsigned char *, size_t),
@@ -216,22 +221,24 @@
  * \param additional    Additional data to add to the state. Can be NULL.
  * \param len           The length of the additional data.
  *
- * \return   \c 0 on success, or
- *           #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
+ * \return              \c 0 on success.
+ * \return              #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
  */
 int mbedtls_ctr_drbg_reseed( mbedtls_ctr_drbg_context *ctx,
                      const unsigned char *additional, size_t len );
 
 /**
- * \brief               This function updates the state of the CTR_DRBG context.
+ * \brief              This function updates the state of the CTR_DRBG context.
  *
- * \param ctx           The CTR_DRBG context.
- * \param additional    The data to update the state with.
- * \param add_len       Length of \p additional data.
+ * \note               If \p add_len is greater than
+ *                     #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT, only the first
+ *                     #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT Bytes are used.
+ *                     The remaining Bytes are silently discarded.
  *
- * \note     If \p add_len is greater than #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT,
- *           only the first #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT Bytes are used.
- *           The remaining Bytes are silently discarded.
+ * \param ctx          The CTR_DRBG context.
+ * \param additional   The data to update the state with.
+ * \param add_len      Length of \p additional data.
+ *
  */
 void mbedtls_ctr_drbg_update( mbedtls_ctr_drbg_context *ctx,
                       const unsigned char *additional, size_t add_len );
@@ -249,8 +256,8 @@
  * \param additional    Additional data to update. Can be NULL.
  * \param add_len       The length of the additional data.
  *
- * \return    \c 0 on success, or
- *            #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
+ * \return    \c 0 on success.
+ * \return    #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
  *            #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
  */
 int mbedtls_ctr_drbg_random_with_add( void *p_rng,
@@ -267,8 +274,8 @@
  * \param output        The buffer to fill.
  * \param output_len    The length of the buffer.
  *
- * \return              \c 0 on success, or
- *                      #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
+ * \return              \c 0 on success.
+ * \return              #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
  *                      #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
  */
 int mbedtls_ctr_drbg_random( void *p_rng,
@@ -281,9 +288,9 @@
  * \param ctx           The CTR_DRBG context.
  * \param path          The name of the file.
  *
- * \return              \c 0 on success,
- *                      #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error, or
- *                      #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on
+ * \return              \c 0 on success.
+ * \return              #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.
+ * \return              #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on
  *                      failure.
  */
 int mbedtls_ctr_drbg_write_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
@@ -295,9 +302,9 @@
  * \param ctx           The CTR_DRBG context.
  * \param path          The name of the file.
  *
- * \return              \c 0 on success,
- *                      #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error,
- *                      #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
+ * \return              \c 0 on success.
+ * \return              #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error.
+ * \return              #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
  *                      #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG on failure.
  */
 int mbedtls_ctr_drbg_update_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
@@ -306,7 +313,8 @@
 /**
  * \brief               The CTR_DRBG checkup routine.
  *
- * \return              \c 0 on success, or \c 1 on failure.
+ * \return              \c 0 on success.
+ * \return              \c 1 on failure.
  */
 int mbedtls_ctr_drbg_self_test( int verbose );
 
diff --git a/include/mbedtls/des.h b/include/mbedtls/des.h
index 5a1a636..6eb7d03 100644
--- a/include/mbedtls/des.h
+++ b/include/mbedtls/des.h
@@ -46,14 +46,14 @@
 
 #define MBEDTLS_DES_KEY_SIZE    8
 
-#if !defined(MBEDTLS_DES_ALT)
-// Regular implementation
-//
-
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+#if !defined(MBEDTLS_DES_ALT)
+// Regular implementation
+//
+
 /**
  * \brief          DES context structure
  *
@@ -76,6 +76,10 @@
 }
 mbedtls_des3_context;
 
+#else  /* MBEDTLS_DES_ALT */
+#include "des_alt.h"
+#endif /* MBEDTLS_DES_ALT */
+
 /**
  * \brief          Initialize DES context
  *
@@ -331,17 +335,6 @@
  */
 void mbedtls_des_setkey( uint32_t SK[32],
                          const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
-#ifdef __cplusplus
-}
-#endif
-
-#else  /* MBEDTLS_DES_ALT */
-#include "des_alt.h"
-#endif /* MBEDTLS_DES_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
 
 /**
  * \brief          Checkup routine
diff --git a/include/mbedtls/dhm.h b/include/mbedtls/dhm.h
index 00fafd8..75317a8 100644
--- a/include/mbedtls/dhm.h
+++ b/include/mbedtls/dhm.h
@@ -1,7 +1,13 @@
 /**
  * \file dhm.h
  *
- * \brief Diffie-Hellman-Merkle key exchange.
+ * \brief   This file contains Diffie-Hellman-Merkle (DHM) key exchange
+ *          definitions and functions.
+ *
+ * Diffie-Hellman-Merkle (DHM) key exchange is defined in
+ * <em>RFC-2631: Diffie-Hellman Key Agreement Method</em> and
+ * <em>Public-Key Cryptography Standards (PKCS) #3: Diffie
+ * Hellman Key Agreement Standard</em>.
  *
  * <em>RFC-3526: More Modular Exponential (MODP) Diffie-Hellman groups for
  * Internet Key Exchange (IKE)</em> defines a number of standardized
@@ -65,7 +71,6 @@
 #include MBEDTLS_CONFIG_FILE
 #endif
 #include "bignum.h"
-#if !defined(MBEDTLS_DHM_ALT)
 
 /*
  * DHM Error codes
@@ -86,6 +91,8 @@
 extern "C" {
 #endif
 
+#if !defined(MBEDTLS_DHM_ALT)
+
 /**
  * \brief          The DHM context structure.
  */
@@ -105,6 +112,10 @@
 }
 mbedtls_dhm_context;
 
+#else /* MBEDTLS_DHM_ALT */
+#include "dhm_alt.h"
+#endif /* MBEDTLS_DHM_ALT */
+
 /**
  * \brief          This function initializes the DHM context.
  *
@@ -125,8 +136,8 @@
  *                 failures.
  * \param end      The end of the input buffer.
  *
- * \return         \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
- *                 on failure.
+ * \return         \c 0 on success.
+ * \return         An \c MBEDTLS_ERR_DHM_XXX error code on failure.
  */
 int mbedtls_dhm_read_params( mbedtls_dhm_context *ctx,
                      unsigned char **p,
@@ -136,13 +147,6 @@
  * \brief          This function sets up and writes the ServerKeyExchange
  *                 parameters.
  *
- * \param ctx      The DHM context.
- * \param x_size   The private value size in Bytes.
- * \param olen     The number of characters written.
- * \param output   The destination buffer.
- * \param f_rng    The RNG function.
- * \param p_rng    The RNG parameter.
- *
  * \note           The destination buffer must be large enough to hold
  *                 the reduced binary presentation of the modulus, the generator
  *                 and the public key, each wrapped with a 2-byte length field.
@@ -155,8 +159,15 @@
  *                 mbedtls_dhm_set_group() below in conjunction with
  *                 mbedtls_mpi_read_binary() and mbedtls_mpi_read_string().
  *
- * \return         \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
- *                 on failure.
+ * \param ctx      The DHM context.
+ * \param x_size   The private key size in Bytes.
+ * \param olen     The number of characters written.
+ * \param output   The destination buffer.
+ * \param f_rng    The RNG function.
+ * \param p_rng    The RNG context.
+ *
+ * \return         \c 0 on success.
+ * \return         An \c MBEDTLS_ERR_DHM_XXX error code on failure.
  */
 int mbedtls_dhm_make_params( mbedtls_dhm_context *ctx, int x_size,
                      unsigned char *output, size_t *olen,
@@ -164,54 +175,54 @@
                      void *p_rng );
 
 /**
- * \brief          Set prime modulus and generator
+ * \brief          This function sets the prime modulus and generator.
+ *
+ * \note           This function can be used to set \p P, \p G
+ *                 in preparation for mbedtls_dhm_make_params().
  *
  * \param ctx      The DHM context.
- * \param P        The MPI holding DHM prime modulus.
- * \param G        The MPI holding DHM generator.
+ * \param P        The MPI holding the DHM prime modulus.
+ * \param G        The MPI holding the DHM generator.
  *
- * \note           This function can be used to set P, G
- *                 in preparation for \c mbedtls_dhm_make_params.
- *
- * \return         \c 0 if successful, or an \c MBEDTLS_ERR_DHM_XXX error code
- *                 on failure.
+ * \return         \c 0 if successful.
+ * \return         An \c MBEDTLS_ERR_DHM_XXX error code on failure.
  */
 int mbedtls_dhm_set_group( mbedtls_dhm_context *ctx,
                            const mbedtls_mpi *P,
                            const mbedtls_mpi *G );
 
 /**
- * \brief          This function imports the public value G^Y of the peer.
+ * \brief          This function imports the public value of the peer, G^Y.
  *
  * \param ctx      The DHM context.
- * \param input    The input buffer.
+ * \param input    The input buffer containing the G^Y value of the peer.
  * \param ilen     The size of the input buffer.
  *
- * \return         \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
- *                 on failure.
+ * \return         \c 0 on success.
+ * \return         An \c MBEDTLS_ERR_DHM_XXX error code on failure.
  */
 int mbedtls_dhm_read_public( mbedtls_dhm_context *ctx,
                      const unsigned char *input, size_t ilen );
 
 /**
- * \brief          This function creates its own private value \c X and
+ * \brief          This function creates its own private key, \c X, and
  *                 exports \c G^X.
  *
+ * \note           The destination buffer is always fully written
+ *                 so as to contain a big-endian representation of G^X mod P.
+ *                 If it is larger than ctx->len, it is padded accordingly
+ *                 with zero-bytes at the beginning.
+ *
  * \param ctx      The DHM context.
- * \param x_size   The private value size in Bytes.
+ * \param x_size   The private key size in Bytes.
  * \param output   The destination buffer.
  * \param olen     The length of the destination buffer. Must be at least
-                   equal to ctx->len (the size of \c P).
+ *                  equal to ctx->len (the size of \c P).
  * \param f_rng    The RNG function.
- * \param p_rng    The RNG parameter.
+ * \param p_rng    The RNG context.
  *
- * \note           The destination buffer will always be fully written
- *                 so as to contain a big-endian presentation of G^X mod P.
- *                 If it is larger than ctx->len, it will accordingly be
- *                 padded with zero-bytes in the beginning.
- *
- * \return         \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
- *                 on failure.
+ * \return         \c 0 on success.
+ * \return         An \c MBEDTLS_ERR_DHM_XXX error code on failure.
  */
 int mbedtls_dhm_make_public( mbedtls_dhm_context *ctx, int x_size,
                      unsigned char *output, size_t olen,
@@ -222,22 +233,22 @@
  * \brief               This function derives and exports the shared secret
  *                      \c (G^Y)^X mod \c P.
  *
+ * \note                If \p f_rng is not NULL, it is used to blind the input as
+ *                      a countermeasure against timing attacks. Blinding is used
+ *                      only if our private key \c X is re-used, and not used
+ *                      otherwise. We recommend always passing a non-NULL
+ *                      \p f_rng argument.
+ *
  * \param ctx           The DHM context.
  * \param output        The destination buffer.
  * \param output_size   The size of the destination buffer. Must be at least
- *                      the size of ctx->len.
+ *                      the size of ctx->len (the size of \c P).
  * \param olen          On exit, holds the actual number of Bytes written.
  * \param f_rng         The RNG function, for blinding purposes.
- * \param p_rng         The RNG parameter.
+ * \param p_rng         The RNG context.
  *
- * \return         \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
- *                 on failure.
- *
- * \note           If non-NULL, \p f_rng is used to blind the input as
- *                 a countermeasure against timing attacks. Blinding is used
- *                 only if our secret value \p X is re-used and omitted
- *                 otherwise. Therefore, we recommend always passing a
- *                 non-NULL \p f_rng argument.
+ * \return              \c 0 on success.
+ * \return              An \c MBEDTLS_ERR_DHM_XXX error code on failure.
  */
 int mbedtls_dhm_calc_secret( mbedtls_dhm_context *ctx,
                      unsigned char *output, size_t output_size, size_t *olen,
@@ -245,7 +256,7 @@
                      void *p_rng );
 
 /**
- * \brief          This function frees and clears the components of a DHM key.
+ * \brief          This function frees and clears the components of a DHM context.
  *
  * \param ctx      The DHM context to free and clear.
  */
@@ -261,8 +272,9 @@
  * \param dhminlen    The size of the buffer, including the terminating null
  *                    Byte for PEM data.
  *
- * \return            \c 0 on success, or a specific DHM or PEM error code
- *                    on failure.
+ * \return            \c 0 on success.
+ * \return            An \c MBEDTLS_ERR_DHM_XXX or \c MBEDTLS_ERR_PEM_XXX error code
+ *                    error code on failure.
  */
 int mbedtls_dhm_parse_dhm( mbedtls_dhm_context *dhm, const unsigned char *dhmin,
                    size_t dhminlen );
@@ -275,29 +287,19 @@
  * \param dhm      The DHM context to load the parameters to.
  * \param path     The filename to read the DHM parameters from.
  *
- * \return         \c 0 on success, or a specific DHM or PEM error code
- *                 on failure.
+ * \return         \c 0 on success.
+ * \return            An \c MBEDTLS_ERR_DHM_XXX or \c MBEDTLS_ERR_PEM_XXX error code
+ *                    error code on failure.
  */
 int mbedtls_dhm_parse_dhmfile( mbedtls_dhm_context *dhm, const char *path );
 #endif /* MBEDTLS_FS_IO */
 #endif /* MBEDTLS_ASN1_PARSE_C */
 
-#ifdef __cplusplus
-}
-#endif
-
-#else /* MBEDTLS_DHM_ALT */
-#include "dhm_alt.h"
-#endif /* MBEDTLS_DHM_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
 /**
  * \brief          The DMH checkup routine.
  *
- * \return         \c 0 on success, or \c 1 on failure.
+ * \return         \c 0 on success.
+ * \return         \c 1 on failure.
  */
 int mbedtls_dhm_self_test( int verbose );
 
diff --git a/include/mbedtls/ecdh.h b/include/mbedtls/ecdh.h
index 99cfde0..5fdf55a 100644
--- a/include/mbedtls/ecdh.h
+++ b/include/mbedtls/ecdh.h
@@ -1,10 +1,11 @@
 /**
  * \file ecdh.h
  *
- * \brief The Elliptic Curve Diffie-Hellman (ECDH) protocol APIs.
+ * \brief This file contains ECDH definitions and functions.
  *
- * ECDH is an anonymous key agreement protocol allowing two parties to
- * establish a shared secret over an insecure channel. Each party must have an
+ * The Elliptic Curve Diffie-Hellman (ECDH) protocol is an anonymous
+ * key agreement protocol allowing two parties to establish a shared
+ * secret over an insecure channel. Each party must have an
  * elliptic-curve public–private key pair.
  *
  * For more information, see <em>NIST SP 800-56A Rev. 2: Recommendation for
@@ -40,14 +41,12 @@
 #endif
 
 /**
- * Defines the source of the imported EC key:
- * <ul><li>Our key.</li>
- * <li>The key of the peer.</li></ul>
+ * Defines the source of the imported EC key.
  */
 typedef enum
 {
-    MBEDTLS_ECDH_OURS,
-    MBEDTLS_ECDH_THEIRS,
+    MBEDTLS_ECDH_OURS,   /**< Our key. */
+    MBEDTLS_ECDH_THEIRS, /**< The key of the peer. */
 } mbedtls_ecdh_side;
 
 /**
@@ -75,16 +74,18 @@
  *                  implemented during the ECDH key exchange. The second core
  *                  computation is performed by mbedtls_ecdh_compute_shared().
  *
+ * \see             ecp.h
+ *
  * \param grp       The ECP group.
  * \param d         The destination MPI (private key).
  * \param Q         The destination point (public key).
  * \param f_rng     The RNG function.
- * \param p_rng     The RNG parameter.
+ * \param p_rng     The RNG context.
  *
- * \return          \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX or
+ * \return          \c 0 on success.
+ * \return          An \c MBEDTLS_ERR_ECP_XXX or
  *                  \c MBEDTLS_MPI_XXX error code on failure.
  *
- * \see             ecp.h
  */
 int mbedtls_ecdh_gen_public( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q,
                      int (*f_rng)(void *, unsigned char *, size_t),
@@ -97,21 +98,22 @@
  *                  implemented during the ECDH key exchange. The first core
  *                  computation is performed by mbedtls_ecdh_gen_public().
  *
+ * \see             ecp.h
+ *
+ * \note            If \p f_rng is not NULL, it is used to implement
+ *                  countermeasures against side-channel attacks.
+ *                  For more information, see mbedtls_ecp_mul().
+ *
  * \param grp       The ECP group.
  * \param z         The destination MPI (shared secret).
  * \param Q         The public key from another party.
  * \param d         Our secret exponent (private key).
  * \param f_rng     The RNG function.
- * \param p_rng     The RNG parameter.
+ * \param p_rng     The RNG context.
  *
- * \return          \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX or
+ * \return          \c 0 on success.
+ * \return          An \c MBEDTLS_ERR_ECP_XXX or
  *                  \c MBEDTLS_MPI_XXX error code on failure.
- *
- * \see             ecp.h
- *
- * \note            If \p f_rng is not NULL, it is used to implement
- *                  countermeasures against potential elaborate timing
- *                  attacks. For more information, see mbedtls_ecp_mul().
  */
 int mbedtls_ecdh_compute_shared( mbedtls_ecp_group *grp, mbedtls_mpi *z,
                          const mbedtls_ecp_point *Q, const mbedtls_mpi *d,
@@ -139,21 +141,21 @@
  *                  This is the first function used by a TLS server for ECDHE
  *                  ciphersuites.
  *
+ * \note            This function assumes that the ECP group (grp) of the
+ *                  \p ctx context has already been properly set,
+ *                  for example, using mbedtls_ecp_group_load().
+ *
+ * \see             ecp.h
+ *
  * \param ctx       The ECDH context.
  * \param olen      The number of characters written.
  * \param buf       The destination buffer.
  * \param blen      The length of the destination buffer.
  * \param f_rng     The RNG function.
- * \param p_rng     The RNG parameter.
+ * \param p_rng     The RNG context.
  *
- * \note            This function assumes that the ECP group (grp) of the
- *                  \p ctx context has already been properly set,
- *                  for example, using mbedtls_ecp_group_load().
- *
- * \return          \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
- *                  on failure.
- *
- * \see             ecp.h
+ * \return          \c 0 on success.
+ * \return          An \c MBEDTLS_ERR_ECP_XXX error code on failure.
  */
 int mbedtls_ecdh_make_params( mbedtls_ecdh_context *ctx, size_t *olen,
                       unsigned char *buf, size_t blen,
@@ -167,14 +169,15 @@
  *                  This is the first function used by a TLS client for ECDHE
  *                  ciphersuites.
  *
+ * \see             ecp.h
+ *
  * \param ctx       The ECDH context.
  * \param buf       The pointer to the start of the input buffer.
  * \param end       The address for one Byte past the end of the buffer.
  *
- * \return          \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
- *                  on failure.
+ * \return          \c 0 on success.
+ * \return          An \c MBEDTLS_ERR_ECP_XXX error code on failure.
  *
- * \see             ecp.h
  */
 int mbedtls_ecdh_read_params( mbedtls_ecdh_context *ctx,
                       const unsigned char **buf, const unsigned char *end );
@@ -186,16 +189,16 @@
  *                  ServerKeyEchange for static ECDH, and imports ECDH
  *                  parameters from the EC key information of a certificate.
  *
+ * \see             ecp.h
+ *
  * \param ctx       The ECDH context to set up.
  * \param key       The EC key to use.
- * \param side      Defines the source of the key:
- *                  <ul><li>1: Our key.</li>
-                    <li>0: The key of the peer.</li></ul>
+ * \param side      Defines the source of the key: 1: Our key, or
+ *                  0: The key of the peer.
  *
- * \return          \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
- *                  on failure.
+ * \return          \c 0 on success.
+ * \return          An \c MBEDTLS_ERR_ECP_XXX error code on failure.
  *
- * \see             ecp.h
  */
 int mbedtls_ecdh_get_params( mbedtls_ecdh_context *ctx, const mbedtls_ecp_keypair *key,
                      mbedtls_ecdh_side side );
@@ -207,17 +210,17 @@
  *                  This is the second function used by a TLS client for ECDH(E)
  *                  ciphersuites.
  *
+ * \see             ecp.h
+ *
  * \param ctx       The ECDH context.
  * \param olen      The number of Bytes written.
  * \param buf       The destination buffer.
  * \param blen      The size of the destination buffer.
  * \param f_rng     The RNG function.
- * \param p_rng     The RNG parameter.
+ * \param p_rng     The RNG context.
  *
- * \return          \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
- *                  on failure.
- *
- * \see             ecp.h
+ * \return          \c 0 on success.
+ * \return          An \c MBEDTLS_ERR_ECP_XXX error code on failure.
  */
 int mbedtls_ecdh_make_public( mbedtls_ecdh_context *ctx, size_t *olen,
                       unsigned char *buf, size_t blen,
@@ -231,14 +234,14 @@
  *              This is the second function used by a TLS server for ECDH(E)
  *              ciphersuites.
  *
+ * \see         ecp.h
+ *
  * \param ctx   The ECDH context.
  * \param buf   The start of the input buffer.
  * \param blen  The length of the input buffer.
  *
- * \return      \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
- *              on failure.
- *
- * \see         ecp.h
+ * \return      \c 0 on success.
+ * \return      An \c MBEDTLS_ERR_ECP_XXX error code on failure.
  */
 int mbedtls_ecdh_read_public( mbedtls_ecdh_context *ctx,
                       const unsigned char *buf, size_t blen );
@@ -249,21 +252,21 @@
  *                  This is the last function used by both TLS client
  *                  and servers.
  *
+ * \note            If \p f_rng is not NULL, it is used to implement
+ *                  countermeasures against side-channel attacks.
+ *                  For more information, see mbedtls_ecp_mul().
+ *
+ * \see             ecp.h
+ *
  * \param ctx       The ECDH context.
  * \param olen      The number of Bytes written.
  * \param buf       The destination buffer.
  * \param blen      The length of the destination buffer.
  * \param f_rng     The RNG function.
- * \param p_rng     The RNG parameter.
+ * \param p_rng     The RNG context.
  *
- * \return          \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
- *                  on failure.
- *
- * \see             ecp.h
- *
- * \note            If \p f_rng is not NULL, it is used to implement
- *                  countermeasures against potential elaborate timing
- *                  attacks. For more information, see mbedtls_ecp_mul().
+ * \return          \c 0 on success.
+ * \return          An \c MBEDTLS_ERR_ECP_XXX error code on failure.
  */
 int mbedtls_ecdh_calc_secret( mbedtls_ecdh_context *ctx, size_t *olen,
                       unsigned char *buf, size_t blen,
diff --git a/include/mbedtls/ecdsa.h b/include/mbedtls/ecdsa.h
index aa23d67..ce1a03d 100644
--- a/include/mbedtls/ecdsa.h
+++ b/include/mbedtls/ecdsa.h
@@ -1,9 +1,10 @@
 /**
  * \file ecdsa.h
  *
- * \brief The Elliptic Curve Digital Signature Algorithm (ECDSA).
+ * \brief This file contains ECDSA definitions and functions.
  *
- * ECDSA is defined in <em>Standards for Efficient Cryptography Group (SECG):
+ * The Elliptic Curve Digital Signature Algorithm (ECDSA) is defined in
+ * <em>Standards for Efficient Cryptography Group (SECG):
  * SEC1 Elliptic Curve Cryptography</em>.
  * The use of ECDSA for TLS is defined in <em>RFC-4492: Elliptic Curve
  * Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS)</em>.
@@ -69,6 +70,14 @@
  *
  * \note            The deterministic version is usually preferred.
  *
+ * \note            If the bitlength of the message hash is larger than the
+ *                  bitlength of the group order, then the hash is truncated
+ *                  as defined in <em>Standards for Efficient Cryptography Group
+ *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
+ *                  4.1.3, step 5.
+ *
+ * \see             ecp.h
+ *
  * \param grp       The ECP group.
  * \param r         The first output integer.
  * \param s         The second output integer.
@@ -76,18 +85,11 @@
  * \param buf       The message hash.
  * \param blen      The length of \p buf.
  * \param f_rng     The RNG function.
- * \param p_rng     The RNG parameter.
+ * \param p_rng     The RNG context.
  *
- * \note            If the bitlength of the message hash is larger than the
- *                  bitlength of the group order, then the hash is truncated
- *                  as defined in <em>Standards for Efficient Cryptography Group
- *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
- *                  4.1.3, step 5.
- *
- * \return          \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX
+ * \return          \c 0 on success.
+ * \return          An \c MBEDTLS_ERR_ECP_XXX
  *                  or \c MBEDTLS_MPI_XXX error code on failure.
- *
- * \see             ecp.h
  */
 int mbedtls_ecdsa_sign( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
                 const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
@@ -97,10 +99,19 @@
 /**
  * \brief           This function computes the ECDSA signature of a
  *                  previously-hashed message, deterministic version.
+ *
  *                  For more information, see <em>RFC-6979: Deterministic
  *                  Usage of the Digital Signature Algorithm (DSA) and Elliptic
  *                  Curve Digital Signature Algorithm (ECDSA)</em>.
  *
+ * \note            If the bitlength of the message hash is larger than the
+ *                  bitlength of the group order, then the hash is truncated as
+ *                  defined in <em>Standards for Efficient Cryptography Group
+ *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
+ *                  4.1.3, step 5.
+ *
+ * \see             ecp.h
+ *
  * \param grp       The ECP group.
  * \param r         The first output integer.
  * \param s         The second output integer.
@@ -109,17 +120,9 @@
  * \param blen      The length of \p buf.
  * \param md_alg    The MD algorithm used to hash the message.
  *
- * \note            If the bitlength of the message hash is larger than the
- *                  bitlength of the group order, then the hash is truncated as
- *                  defined in <em>Standards for Efficient Cryptography Group
- *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
- *                  4.1.3, step 5.
- *
- * \return          \c 0 on success,
- *                  or an \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
+ * \return          \c 0 on success.
+ * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
  *                  error code on failure.
- *
- * \see             ecp.h
  */
 int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
                     const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
@@ -130,6 +133,14 @@
  * \brief           This function verifies the ECDSA signature of a
  *                  previously-hashed message.
  *
+ * \note            If the bitlength of the message hash is larger than the
+ *                  bitlength of the group order, then the hash is truncated as
+ *                  defined in <em>Standards for Efficient Cryptography Group
+ *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
+ *                  4.1.4, step 3.
+ *
+ * \see             ecp.h
+ *
  * \param grp       The ECP group.
  * \param buf       The message hash.
  * \param blen      The length of \p buf.
@@ -137,18 +148,11 @@
  * \param r         The first integer of the signature.
  * \param s         The second integer of the signature.
  *
- * \note            If the bitlength of the message hash is larger than the
- *                  bitlength of the group order, then the hash is truncated as
- *                  defined in <em>Standards for Efficient Cryptography Group
- *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
- *                  4.1.4, step 3.
- *
- * \return          \c 0 on success,
- *                  #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid,
- *                  or an \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the signature
+ *                  is invalid.
+ * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
  *                  error code on failure for any other reason.
- *
- * \see             ecp.h
  */
 int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp,
                   const unsigned char *buf, size_t blen,
@@ -169,15 +173,6 @@
  *                  of the Digital Signature Algorithm (DSA) and Elliptic
  *                  Curve Digital Signature Algorithm (ECDSA)</em>.
  *
- * \param ctx       The ECDSA context.
- * \param md_alg    The message digest that was used to hash the message.
- * \param hash      The message hash.
- * \param hlen      The length of the hash.
- * \param sig       The buffer that holds the signature.
- * \param slen      The length of the signature written.
- * \param f_rng     The RNG function.
- * \param p_rng     The RNG parameter.
- *
  * \note            The \p sig buffer must be at least twice as large as the
  *                  size of the curve used, plus 9. For example, 73 Bytes if
  *                  a 256-bit curve is used. A buffer length of
@@ -189,11 +184,20 @@
  *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
  *                  4.1.3, step 5.
  *
- * \return          \c 0 on success,
- *                  or an \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
- *                  \c MBEDTLS_ERR_ASN1_XXX error code on failure.
- *
  * \see             ecp.h
+ *
+ * \param ctx       The ECDSA context.
+ * \param md_alg    The message digest that was used to hash the message.
+ * \param hash      The message hash.
+ * \param hlen      The length of the hash.
+ * \param sig       The buffer that holds the signature.
+ * \param slen      The length of the signature written.
+ * \param f_rng     The RNG function.
+ * \param p_rng     The RNG context.
+ *
+ * \return          \c 0 on success.
+ * \return          An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
+ *                  \c MBEDTLS_ERR_ASN1_XXX error code on failure.
  */
 int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t md_alg,
                            const unsigned char *hash, size_t hlen,
@@ -209,26 +213,17 @@
 #define MBEDTLS_DEPRECATED
 #endif
 /**
- * \brief   This function computes an ECDSA signature and writes it to a buffer,
- *          serialized as defined in <em>RFC-4492: Elliptic Curve Cryptography
- *          (ECC) Cipher Suites for Transport Layer Security (TLS)</em>.
+ * \brief           This function computes an ECDSA signature and writes
+ *                  it to a buffer, serialized as defined in <em>RFC-4492:
+ *                  Elliptic Curve Cryptography (ECC) Cipher Suites for
+ *                  Transport Layer Security (TLS)</em>.
  *
- *          The deterministic version is defined in <em>RFC-6979:
- *          Deterministic Usage of the Digital Signature Algorithm (DSA) and
- *          Elliptic Curve Digital Signature Algorithm (ECDSA)</em>.
+ *                  The deterministic version is defined in <em>RFC-6979:
+ *                  Deterministic Usage of the Digital Signature Algorithm (DSA)
+ *                  and Elliptic Curve Digital Signature Algorithm (ECDSA)</em>.
  *
  * \warning         It is not thread-safe to use the same context in
  *                  multiple threads.
-
- *
- * \deprecated      Superseded by mbedtls_ecdsa_write_signature() in 2.0.0
- *
- * \param ctx       The ECDSA context.
- * \param hash      The Message hash.
- * \param hlen      The length of the hash.
- * \param sig       The buffer that holds the signature.
- * \param slen      The length of the signature written.
- * \param md_alg    The MD algorithm used to hash the message.
  *
  * \note            The \p sig buffer must be at least twice as large as the
  *                  size of the curve used, plus 9. For example, 73 Bytes if a
@@ -241,11 +236,21 @@
  *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
  *                  4.1.3, step 5.
  *
- * \return          \c 0 on success,
- *                  or an \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
- *                  \c MBEDTLS_ERR_ASN1_XXX error code on failure.
- *
  * \see             ecp.h
+ *
+ * \deprecated      Superseded by mbedtls_ecdsa_write_signature() in
+ *                  Mbed TLS version 2.0 and later.
+ *
+ * \param ctx       The ECDSA context.
+ * \param hash      The message hash.
+ * \param hlen      The length of the hash.
+ * \param sig       The buffer that holds the signature.
+ * \param slen      The length of the signature written.
+ * \param md_alg    The MD algorithm used to hash the message.
+ *
+ * \return          \c 0 on success.
+ * \return          An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
+ *                  \c MBEDTLS_ERR_ASN1_XXX error code on failure.
  */
 int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx,
                                const unsigned char *hash, size_t hlen,
@@ -258,26 +263,26 @@
 /**
  * \brief           This function reads and verifies an ECDSA signature.
  *
- * \param ctx       The ECDSA context.
- * \param hash      The message hash.
- * \param hlen      The size of the hash.
- * \param sig       The signature to read and verify.
- * \param slen      The size of \p sig.
- *
  * \note            If the bitlength of the message hash is larger than the
  *                  bitlength of the group order, then the hash is truncated as
  *                  defined in <em>Standards for Efficient Cryptography Group
  *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
  *                  4.1.4, step 3.
  *
- * \return          \c 0 on success,
- *                  #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid,
- *                  #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if the signature is
- *                  valid but its actual length is less than \p siglen,
- *                  or an \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX
- *                  error code on failure for any other reason.
- *
  * \see             ecp.h
+ *
+ * \param ctx       The ECDSA context.
+ * \param hash      The message hash.
+ * \param hlen      The size of the hash.
+ * \param sig       The signature to read and verify.
+ * \param slen      The size of \p sig.
+ *
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid.
+ * \return          #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if there is a valid
+ *                  signature in \p sig, but its length is less than \p siglen.
+ * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX
+ *                  error code on failure for any other reason.
  */
 int mbedtls_ecdsa_read_signature( mbedtls_ecdsa_context *ctx,
                           const unsigned char *hash, size_t hlen,
@@ -286,16 +291,16 @@
 /**
  * \brief          This function generates an ECDSA keypair on the given curve.
  *
+ * \see            ecp.h
+ *
  * \param ctx      The ECDSA context to store the keypair in.
  * \param gid      The elliptic curve to use. One of the various
  *                 \c MBEDTLS_ECP_DP_XXX macros depending on configuration.
  * \param f_rng    The RNG function.
- * \param p_rng    The RNG parameter.
+ * \param p_rng    The RNG context.
  *
- * \return         \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX code on
- *                 failure.
- *
- * \see            ecp.h
+ * \return         \c 0 on success.
+ * \return         An \c MBEDTLS_ERR_ECP_XXX code on failure.
  */
 int mbedtls_ecdsa_genkey( mbedtls_ecdsa_context *ctx, mbedtls_ecp_group_id gid,
                   int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
@@ -303,13 +308,13 @@
 /**
  * \brief           This function sets an ECDSA context from an EC key pair.
  *
+ * \see             ecp.h
+ *
  * \param ctx       The ECDSA context to set.
  * \param key       The EC key to use.
  *
- * \return          \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX code on
- *                  failure.
- *
- * \see             ecp.h
+ * \return          \c 0 on success.
+ * \return          An \c MBEDTLS_ERR_ECP_XXX code on failure.
  */
 int mbedtls_ecdsa_from_keypair( mbedtls_ecdsa_context *ctx, const mbedtls_ecp_keypair *key );
 
diff --git a/include/mbedtls/ecjpake.h b/include/mbedtls/ecjpake.h
index d86e820..cc2b316 100644
--- a/include/mbedtls/ecjpake.h
+++ b/include/mbedtls/ecjpake.h
@@ -44,8 +44,6 @@
 #include "ecp.h"
 #include "md.h"
 
-#if !defined(MBEDTLS_ECJPAKE_ALT)
-
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -58,6 +56,7 @@
     MBEDTLS_ECJPAKE_SERVER,             /**< Server                         */
 } mbedtls_ecjpake_role;
 
+#if !defined(MBEDTLS_ECJPAKE_ALT)
 /**
  * EC J-PAKE context structure.
  *
@@ -88,6 +87,10 @@
     mbedtls_mpi s;                      /**< Pre-shared secret (passphrase) */
 } mbedtls_ecjpake_context;
 
+#else  /* MBEDTLS_ECJPAKE_ALT */
+#include "ecjpake_alt.h"
+#endif /* MBEDTLS_ECJPAKE_ALT */
+
 /**
  * \brief           Initialize a context
  *                  (just makes it ready for setup() or free()).
@@ -225,20 +228,10 @@
  */
 void mbedtls_ecjpake_free( mbedtls_ecjpake_context *ctx );
 
-#ifdef __cplusplus
-}
-#endif
 
-#else  /* MBEDTLS_ECJPAKE_ALT */
-#include "ecjpake_alt.h"
-#endif /* MBEDTLS_ECJPAKE_ALT */
 
 #if defined(MBEDTLS_SELF_TEST)
 
-#ifdef __cplusplus
-extern "C" {
-#endif
-
 /**
  * \brief          Checkup routine
  *
@@ -246,10 +239,11 @@
  */
 int mbedtls_ecjpake_self_test( int verbose );
 
+#endif /* MBEDTLS_SELF_TEST */
+
 #ifdef __cplusplus
 }
 #endif
 
-#endif /* MBEDTLS_SELF_TEST */
 
 #endif /* ecjpake.h */
diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h
index b00ba4d..3a40798 100644
--- a/include/mbedtls/ecp.h
+++ b/include/mbedtls/ecp.h
@@ -1,10 +1,21 @@
 /**
  * \file ecp.h
  *
- * \brief Elliptic curves over GF(p)
+ * \brief This file provides an API for Elliptic Curves over GF(P) (ECP).
+ *
+ * The use of ECP in cryptography and TLS is defined in
+ * <em>Standards for Efficient Cryptography Group (SECG): SEC1
+ * Elliptic Curve Cryptography</em> and
+ * <em>RFC-4492: Elliptic Curve Cryptography (ECC) Cipher Suites
+ * for Transport Layer Security (TLS)</em>.
+ *
+ * <em>RFC-2409: The Internet Key Exchange (IKE)</em> defines ECP
+ * group types.
+ *
  */
+
 /*
- *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
@@ -19,8 +30,9 @@
  *  See the License for the specific language governing permissions and
  *  limitations under the License.
  *
- *  This file is part of mbed TLS (https://tls.mbed.org)
+ *  This file is part of Mbed TLS (https://tls.mbed.org)
  */
+
 #ifndef MBEDTLS_ECP_H
 #define MBEDTLS_ECP_H
 
@@ -31,13 +43,81 @@
  */
 #define MBEDTLS_ERR_ECP_BAD_INPUT_DATA                    -0x4F80  /**< Bad input parameters to function. */
 #define MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL                  -0x4F00  /**< The buffer is too small to write to. */
-#define MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE               -0x4E80  /**< Requested curve not available. */
+#define MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE               -0x4E80  /**< The requested feature is not available, for example, the requested curve is not supported. */
 #define MBEDTLS_ERR_ECP_VERIFY_FAILED                     -0x4E00  /**< The signature is not valid. */
 #define MBEDTLS_ERR_ECP_ALLOC_FAILED                      -0x4D80  /**< Memory allocation failed. */
-#define MBEDTLS_ERR_ECP_RANDOM_FAILED                     -0x4D00  /**< Generation of random value, such as (ephemeral) key, failed. */
+#define MBEDTLS_ERR_ECP_RANDOM_FAILED                     -0x4D00  /**< Generation of random value, such as ephemeral key, failed. */
 #define MBEDTLS_ERR_ECP_INVALID_KEY                       -0x4C80  /**< Invalid private or public key. */
-#define MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH                  -0x4C00  /**< Signature is valid but shorter than the user-supplied length. */
-#define MBEDTLS_ERR_ECP_HW_ACCEL_FAILED                   -0x4B80  /**< ECP hardware accelerator failed. */
+#define MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH                  -0x4C00  /**< The buffer contains a valid signature followed by more data. */
+#define MBEDTLS_ERR_ECP_HW_ACCEL_FAILED                   -0x4B80  /**< The ECP hardware accelerator failed. */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Domain-parameter identifiers: curve, subgroup, and generator.
+ *
+ * \note Only curves over prime fields are supported.
+ *
+ * \warning This library does not support validation of arbitrary domain
+ * parameters. Therefore, only standardized domain parameters from trusted
+ * sources should be used. See mbedtls_ecp_group_load().
+ */
+typedef enum
+{
+    MBEDTLS_ECP_DP_NONE = 0,       /*!< Curve not defined. */
+    MBEDTLS_ECP_DP_SECP192R1,      /*!< Domain parameters for the 192-bit curve defined by FIPS 186-4 and SEC1. */
+    MBEDTLS_ECP_DP_SECP224R1,      /*!< Domain parameters for the 224-bit curve defined by FIPS 186-4 and SEC1. */
+    MBEDTLS_ECP_DP_SECP256R1,      /*!< Domain parameters for the 256-bit curve defined by FIPS 186-4 and SEC1. */
+    MBEDTLS_ECP_DP_SECP384R1,      /*!< Domain parameters for the 384-bit curve defined by FIPS 186-4 and SEC1. */
+    MBEDTLS_ECP_DP_SECP521R1,      /*!< Domain parameters for the 521-bit curve defined by FIPS 186-4 and SEC1. */
+    MBEDTLS_ECP_DP_BP256R1,        /*!< Domain parameters for 256-bit Brainpool curve. */
+    MBEDTLS_ECP_DP_BP384R1,        /*!< Domain parameters for 384-bit Brainpool curve. */
+    MBEDTLS_ECP_DP_BP512R1,        /*!< Domain parameters for 512-bit Brainpool curve. */
+    MBEDTLS_ECP_DP_CURVE25519,     /*!< Domain parameters for Curve25519. */
+    MBEDTLS_ECP_DP_SECP192K1,      /*!< Domain parameters for 192-bit "Koblitz" curve. */
+    MBEDTLS_ECP_DP_SECP224K1,      /*!< Domain parameters for 224-bit "Koblitz" curve. */
+    MBEDTLS_ECP_DP_SECP256K1,      /*!< Domain parameters for 256-bit "Koblitz" curve. */
+    MBEDTLS_ECP_DP_CURVE448,       /*!< Domain parameters for Curve448. */
+} mbedtls_ecp_group_id;
+
+/**
+ * The number of supported curves, plus one for #MBEDTLS_ECP_DP_NONE.
+ *
+ * \note Montgomery curves are currently excluded.
+ */
+#define MBEDTLS_ECP_DP_MAX     12
+
+/**
+ * Curve information, for use by other modules.
+ */
+typedef struct
+{
+    mbedtls_ecp_group_id grp_id;    /*!< An internal identifier. */
+    uint16_t tls_id;                /*!< The TLS NamedCurve identifier. */
+    uint16_t bit_size;              /*!< The curve size in bits. */
+    const char *name;               /*!< A human-friendly name. */
+} mbedtls_ecp_curve_info;
+
+/**
+ * \brief           The ECP point structure, in Jacobian coordinates.
+ *
+ * \note            All functions expect and return points satisfying
+ *                  the following condition: <code>Z == 0</code> or
+ *                  <code>Z == 1</code>. Other values of \p Z are
+ *                  used only by internal functions.
+ *                  The point is zero, or "at infinity", if <code>Z == 0</code>.
+ *                  Otherwise, \p X and \p Y are its standard (affine)
+ *                  coordinates.
+ */
+typedef struct
+{
+    mbedtls_mpi X;          /*!< The X coordinate of the ECP point. */
+    mbedtls_mpi Y;          /*!< The Y coordinate of the ECP point. */
+    mbedtls_mpi Z;          /*!< The Z coordinate of the ECP point. */
+}
+mbedtls_ecp_point;
 
 #if !defined(MBEDTLS_ECP_ALT)
 /*
@@ -48,143 +128,72 @@
  * one.)
  */
 
-#ifdef __cplusplus
-extern "C" {
-#endif
-
 /**
- * Domain parameters (curve, subgroup and generator) identifiers.
+ * \brief           The ECP group structure.
  *
- * Only curves over prime fields are supported.
+ * We consider two types of curve equations:
+ * <ul><li>Short Weierstrass: <code>y^2 = x^3 + A x + B mod P</code>
+ * (SEC1 + RFC-4492)</li>
+ * <li>Montgomery: <code>y^2 = x^3 + A x^2 + x mod P</code> (Curve25519,
+ * Curve448)</li></ul>
+ * In both cases, the generator (\p G) for a prime-order subgroup is fixed.
  *
- * \warning This library does not support validation of arbitrary domain
- * parameters. Therefore, only well-known domain parameters from trusted
- * sources should be used. See mbedtls_ecp_group_load().
- */
-typedef enum
-{
-    MBEDTLS_ECP_DP_NONE = 0,
-    MBEDTLS_ECP_DP_SECP192R1,      /*!< 192-bits NIST curve  */
-    MBEDTLS_ECP_DP_SECP224R1,      /*!< 224-bits NIST curve  */
-    MBEDTLS_ECP_DP_SECP256R1,      /*!< 256-bits NIST curve  */
-    MBEDTLS_ECP_DP_SECP384R1,      /*!< 384-bits NIST curve  */
-    MBEDTLS_ECP_DP_SECP521R1,      /*!< 521-bits NIST curve  */
-    MBEDTLS_ECP_DP_BP256R1,        /*!< 256-bits Brainpool curve */
-    MBEDTLS_ECP_DP_BP384R1,        /*!< 384-bits Brainpool curve */
-    MBEDTLS_ECP_DP_BP512R1,        /*!< 512-bits Brainpool curve */
-    MBEDTLS_ECP_DP_CURVE25519,           /*!< Curve25519               */
-    MBEDTLS_ECP_DP_SECP192K1,      /*!< 192-bits "Koblitz" curve */
-    MBEDTLS_ECP_DP_SECP224K1,      /*!< 224-bits "Koblitz" curve */
-    MBEDTLS_ECP_DP_SECP256K1,      /*!< 256-bits "Koblitz" curve */
-} mbedtls_ecp_group_id;
-
-/**
- * Number of supported curves (plus one for NONE).
+ * For Short Weierstrass, this subgroup is the whole curve, and its
+ * cardinality is denoted by \p N. Our code requires that \p N is an
+ * odd prime as mbedtls_ecp_mul() requires an odd number, and
+ * mbedtls_ecdsa_sign() requires that it is prime for blinding purposes.
  *
- * (Montgomery curves excluded for now.)
- */
-#define MBEDTLS_ECP_DP_MAX     12
-
-/**
- * Curve information for use by other modules
+ * For Montgomery curves, we do not store \p A, but <code>(A + 2) / 4</code>,
+ * which is the quantity used in the formulas. Additionally, \p nbits is
+ * not the size of \p N but the required size for private keys.
+ *
+ * If \p modp is NULL, reduction modulo \p P is done using a generic algorithm.
+ * Otherwise, \p modp must point to a function that takes an \p mbedtls_mpi in the
+ * range of <code>0..2^(2*pbits)-1</code>, and transforms it in-place to an integer
+ * which is congruent mod \p P to the given MPI, and is close enough to \p pbits
+ * in size, so that it may be efficiently brought in the 0..P-1 range by a few
+ * additions or subtractions. Therefore, it is only an approximative modular
+ * reduction. It must return 0 on success and non-zero on failure.
+ *
  */
 typedef struct
 {
-    mbedtls_ecp_group_id grp_id;    /*!< Internal identifier        */
-    uint16_t tls_id;                /*!< TLS NamedCurve identifier  */
-    uint16_t bit_size;              /*!< Curve size in bits         */
-    const char *name;               /*!< Human-friendly name        */
-} mbedtls_ecp_curve_info;
-
-/**
- * \brief           ECP point structure (jacobian coordinates)
- *
- * \note            All functions expect and return points satisfying
- *                  the following condition: Z == 0 or Z == 1. (Other
- *                  values of Z are used by internal functions only.)
- *                  The point is zero, or "at infinity", if Z == 0.
- *                  Otherwise, X and Y are its standard (affine) coordinates.
- */
-typedef struct
-{
-    mbedtls_mpi X;          /*!<  the point's X coordinate  */
-    mbedtls_mpi Y;          /*!<  the point's Y coordinate  */
-    mbedtls_mpi Z;          /*!<  the point's Z coordinate  */
-}
-mbedtls_ecp_point;
-
-/**
- * \brief           ECP group structure
- *
- * We consider two types of curves equations:
- * 1. Short Weierstrass y^2 = x^3 + A x + B     mod P   (SEC1 + RFC 4492)
- * 2. Montgomery,       y^2 = x^3 + A x^2 + x   mod P   (Curve25519 + draft)
- * In both cases, a generator G for a prime-order subgroup is fixed. In the
- * short weierstrass, this subgroup is actually the whole curve, and its
- * cardinal is denoted by N.
- *
- * In the case of Short Weierstrass curves, our code requires that N is an odd
- * prime. (Use odd in mbedtls_ecp_mul() and prime in mbedtls_ecdsa_sign() for blinding.)
- *
- * In the case of Montgomery curves, we don't store A but (A + 2) / 4 which is
- * the quantity actually used in the formulas. Also, nbits is not the size of N
- * but the required size for private keys.
- *
- * If modp is NULL, reduction modulo P is done using a generic algorithm.
- * Otherwise, it must point to a function that takes an mbedtls_mpi in the range
- * 0..2^(2*pbits)-1 and transforms it in-place in an integer of little more
- * than pbits, so that the integer may be efficiently brought in the 0..P-1
- * range by a few additions or substractions. It must return 0 on success and
- * non-zero on failure.
- */
-typedef struct
-{
-    mbedtls_ecp_group_id id;    /*!<  internal group identifier                     */
-    mbedtls_mpi P;              /*!<  prime modulus of the base field               */
-    mbedtls_mpi A;              /*!<  1. A in the equation, or 2. (A + 2) / 4       */
-    mbedtls_mpi B;              /*!<  1. B in the equation, or 2. unused            */
-    mbedtls_ecp_point G;        /*!<  generator of the (sub)group used              */
-    mbedtls_mpi N;              /*!<  1. the order of G, or 2. unused               */
-    size_t pbits;       /*!<  number of bits in P                           */
-    size_t nbits;       /*!<  number of bits in 1. P, or 2. private keys    */
-    unsigned int h;     /*!<  internal: 1 if the constants are static       */
-    int (*modp)(mbedtls_mpi *); /*!<  function for fast reduction mod P             */
-    int (*t_pre)(mbedtls_ecp_point *, void *);  /*!< unused                         */
-    int (*t_post)(mbedtls_ecp_point *, void *); /*!< unused                         */
-    void *t_data;                       /*!< unused                         */
-    mbedtls_ecp_point *T;       /*!<  pre-computed points for ecp_mul_comb()        */
-    size_t T_size;      /*!<  number for pre-computed points                */
+    mbedtls_ecp_group_id id;    /*!< An internal group identifier. */
+    mbedtls_mpi P;              /*!< The prime modulus of the base field. */
+    mbedtls_mpi A;              /*!< For Short Weierstrass: \p A in the equation. For
+                                     Montgomery curves: <code>(A + 2) / 4</code>. */
+    mbedtls_mpi B;              /*!< For Short Weierstrass: \p B in the equation.
+                                     For Montgomery curves: unused. */
+    mbedtls_ecp_point G;        /*!< The generator of the subgroup used. */
+    mbedtls_mpi N;              /*!< The order of \p G. */
+    size_t pbits;               /*!< The number of bits in \p P.*/
+    size_t nbits;               /*!< For Short Weierstrass: The number of bits in \p P.
+                                     For Montgomery curves: the number of bits in the
+                                     private keys. */
+    unsigned int h;             /*!< \internal 1 if the constants are static. */
+    int (*modp)(mbedtls_mpi *); /*!< The function for fast pseudo-reduction
+                                     mod \p P (see above).*/
+    int (*t_pre)(mbedtls_ecp_point *, void *);  /*!< Unused. */
+    int (*t_post)(mbedtls_ecp_point *, void *); /*!< Unused. */
+    void *t_data;               /*!< Unused. */
+    mbedtls_ecp_point *T;       /*!< Pre-computed points for ecp_mul_comb(). */
+    size_t T_size;              /*!< The number of pre-computed points. */
 }
 mbedtls_ecp_group;
 
 /**
- * \brief           ECP key pair structure
- *
- * A generic key pair that could be used for ECDSA, fixed ECDH, etc.
- *
- * \note Members purposefully in the same order as struc mbedtls_ecdsa_context.
- */
-typedef struct
-{
-    mbedtls_ecp_group grp;      /*!<  Elliptic curve and base point     */
-    mbedtls_mpi d;              /*!<  our secret value                  */
-    mbedtls_ecp_point Q;        /*!<  our public value                  */
-}
-mbedtls_ecp_keypair;
-
-/**
  * \name SECTION: Module settings
  *
  * The configuration options you can set for this module are in this section.
- * Either change them in config.h or define them on the compiler command line.
+ * Either change them in config.h, or define them using the compiler command line.
  * \{
  */
 
 #if !defined(MBEDTLS_ECP_MAX_BITS)
 /**
- * Maximum size of the groups (that is, of N and P)
+ * The maximum size of the groups, that is, of \c N and \c P.
  */
-#define MBEDTLS_ECP_MAX_BITS     521   /**< Maximum bit size of groups */
+#define MBEDTLS_ECP_MAX_BITS     521   /**< The maximum size of groups, in bits. */
 #endif
 
 #define MBEDTLS_ECP_MAX_BYTES    ( ( MBEDTLS_ECP_MAX_BITS + 7 ) / 8 )
@@ -207,11 +216,10 @@
  *      521       145     141     135     120      97
  *      384       214     209     198     177     146
  *      256       320     320     303     262     226
-
  *      224       475     475     453     398     342
  *      192       640     640     633     587     476
  */
-#define MBEDTLS_ECP_WINDOW_SIZE    6   /**< Maximum window size used */
+#define MBEDTLS_ECP_WINDOW_SIZE    6   /**< The maximum window size used. */
 #endif /* MBEDTLS_ECP_WINDOW_SIZE */
 
 #if !defined(MBEDTLS_ECP_FIXED_POINT_OPTIM)
@@ -226,33 +234,55 @@
  *
  * Change this value to 0 to reduce peak memory usage.
  */
-#define MBEDTLS_ECP_FIXED_POINT_OPTIM  1   /**< Enable fixed-point speed-up */
+#define MBEDTLS_ECP_FIXED_POINT_OPTIM  1   /**< Enable fixed-point speed-up. */
 #endif /* MBEDTLS_ECP_FIXED_POINT_OPTIM */
 
 /* \} name SECTION: Module settings */
 
+#else  /* MBEDTLS_ECP_ALT */
+#include "ecp_alt.h"
+#endif /* MBEDTLS_ECP_ALT */
+
+/**
+ * \brief    The ECP key-pair structure.
+ *
+ * A generic key-pair that may be used for ECDSA and fixed ECDH, for example.
+ *
+ * \note    Members are deliberately in the same order as in the
+ *          ::mbedtls_ecdsa_context structure.
+ */
+typedef struct
+{
+    mbedtls_ecp_group grp;      /*!<  Elliptic curve and base point     */
+    mbedtls_mpi d;              /*!<  our secret value                  */
+    mbedtls_ecp_point Q;        /*!<  our public value                  */
+}
+mbedtls_ecp_keypair;
+
 /*
  * Point formats, from RFC 4492's enum ECPointFormat
  */
-#define MBEDTLS_ECP_PF_UNCOMPRESSED    0   /**< Uncompressed point format */
-#define MBEDTLS_ECP_PF_COMPRESSED      1   /**< Compressed point format */
+#define MBEDTLS_ECP_PF_UNCOMPRESSED    0   /**< Uncompressed point format. */
+#define MBEDTLS_ECP_PF_COMPRESSED      1   /**< Compressed point format. */
 
 /*
  * Some other constants from RFC 4492
  */
-#define MBEDTLS_ECP_TLS_NAMED_CURVE    3   /**< ECCurveType's named_curve */
+#define MBEDTLS_ECP_TLS_NAMED_CURVE    3   /**< The named_curve of ECCurveType. */
 
 /**
- * \brief           Get the list of supported curves in order of preferrence
- *                  (full information)
+ * \brief           This function retrieves the information defined in
+ *                  mbedtls_ecp_curve_info() for all supported curves in order
+ *                  of preference.
  *
- * \return          A statically allocated array, the last entry is 0.
+ * \return          A statically allocated array. The last entry is 0.
  */
 const mbedtls_ecp_curve_info *mbedtls_ecp_curve_list( void );
 
 /**
- * \brief           Get the list of supported curves in order of preferrence
- *                  (grp_id only)
+ * \brief           This function retrieves the list of internal group
+ *                  identifiers of all supported curves in the order of
+ *                  preference.
  *
  * \return          A statically allocated array,
  *                  terminated with MBEDTLS_ECP_DP_NONE.
@@ -260,357 +290,400 @@
 const mbedtls_ecp_group_id *mbedtls_ecp_grp_id_list( void );
 
 /**
- * \brief           Get curve information from an internal group identifier
+ * \brief           This function retrieves curve information from an internal
+ *                  group identifier.
  *
- * \param grp_id    A MBEDTLS_ECP_DP_XXX value
+ * \param grp_id    An \c MBEDTLS_ECP_DP_XXX value.
  *
- * \return          The associated curve information or NULL
+ * \return          The associated curve information on success.
+ * \return          NULL on failure.
  */
 const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_grp_id( mbedtls_ecp_group_id grp_id );
 
 /**
- * \brief           Get curve information from a TLS NamedCurve value
+ * \brief           This function retrieves curve information from a TLS
+ *                  NamedCurve value.
  *
- * \param tls_id    A MBEDTLS_ECP_DP_XXX value
+ * \param tls_id    An \c MBEDTLS_ECP_DP_XXX value.
  *
- * \return          The associated curve information or NULL
+ * \return          The associated curve information on success.
+ * \return          NULL on failure.
  */
 const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_tls_id( uint16_t tls_id );
 
 /**
- * \brief           Get curve information from a human-readable name
+ * \brief           This function retrieves curve information from a
+ *                  human-readable name.
  *
- * \param name      The name
+ * \param name      The human-readable name.
  *
- * \return          The associated curve information or NULL
+ * \return          The associated curve information on success.
+ * \return          NULL on failure.
  */
 const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_name( const char *name );
 
 /**
- * \brief           Initialize a point (as zero)
+ * \brief           This function initializes a point as zero.
+ *
+ * \param pt        The point to initialize.
  */
 void mbedtls_ecp_point_init( mbedtls_ecp_point *pt );
 
 /**
- * \brief           Initialize a group (to something meaningless)
+ * \brief           This function initializes an ECP group context
+ *                  without loading any domain parameters.
+ *
+ * \note            After this function is called, domain parameters
+ *                  for various ECP groups can be loaded through the
+ *                  mbedtls_ecp_load() or mbedtls_ecp_tls_read_group()
+ *                  functions.
  */
 void mbedtls_ecp_group_init( mbedtls_ecp_group *grp );
 
 /**
- * \brief           Initialize a key pair (as an invalid one)
+ * \brief           This function initializes a key pair as an invalid one.
+ *
+ * \param key       The key pair to initialize.
  */
 void mbedtls_ecp_keypair_init( mbedtls_ecp_keypair *key );
 
 /**
- * \brief           Free the components of a point
+ * \brief           This function frees the components of a point.
+ *
+ * \param pt        The point to free.
  */
 void mbedtls_ecp_point_free( mbedtls_ecp_point *pt );
 
 /**
- * \brief           Free the components of an ECP group
+ * \brief           This function frees the components of an ECP group.
+ * \param grp       The group to free.
  */
 void mbedtls_ecp_group_free( mbedtls_ecp_group *grp );
 
 /**
- * \brief           Free the components of a key pair
+ * \brief           This function frees the components of a key pair.
+ * \param key       The key pair to free.
  */
 void mbedtls_ecp_keypair_free( mbedtls_ecp_keypair *key );
 
 /**
- * \brief           Copy the contents of point Q into P
+ * \brief           This function copies the contents of point \p Q into
+ *                  point \p P.
  *
- * \param P         Destination point
- * \param Q         Source point
+ * \param P         The destination point.
+ * \param Q         The source point.
  *
- * \return          0 if successful,
- *                  MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
  */
 int mbedtls_ecp_copy( mbedtls_ecp_point *P, const mbedtls_ecp_point *Q );
 
 /**
- * \brief           Copy the contents of a group object
+ * \brief           This function copies the contents of group \p src into
+ *                  group \p dst.
  *
- * \param dst       Destination group
- * \param src       Source group
+ * \param dst       The destination group.
+ * \param src       The source group.
  *
- * \return          0 if successful,
- *                  MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
  */
 int mbedtls_ecp_group_copy( mbedtls_ecp_group *dst, const mbedtls_ecp_group *src );
 
 /**
- * \brief           Set a point to zero
+ * \brief           This function sets a point to zero.
  *
- * \param pt        Destination point
+ * \param pt        The point to set.
  *
- * \return          0 if successful,
- *                  MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
  */
 int mbedtls_ecp_set_zero( mbedtls_ecp_point *pt );
 
 /**
- * \brief           Tell if a point is zero
+ * \brief           This function checks if a point is zero.
  *
- * \param pt        Point to test
+ * \param pt        The point to test.
  *
- * \return          1 if point is zero, 0 otherwise
+ * \return          \c 1 if the point is zero.
+ * \return          \c 0 if the point is non-zero.
  */
 int mbedtls_ecp_is_zero( mbedtls_ecp_point *pt );
 
 /**
- * \brief           Compare two points
+ * \brief           This function compares two points.
  *
- * \note            This assumes the points are normalized. Otherwise,
+ * \note            This assumes that the points are normalized. Otherwise,
  *                  they may compare as "not equal" even if they are.
  *
- * \param P         First point to compare
- * \param Q         Second point to compare
+ * \param P         The first point to compare.
+ * \param Q         The second point to compare.
  *
- * \return          0 if the points are equal,
- *                  MBEDTLS_ERR_ECP_BAD_INPUT_DATA otherwise
+ * \return          \c 0 if the points are equal.
+ * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the points are not equal.
  */
 int mbedtls_ecp_point_cmp( const mbedtls_ecp_point *P,
                            const mbedtls_ecp_point *Q );
 
 /**
- * \brief           Import a non-zero point from two ASCII strings
+ * \brief           This function imports a non-zero point from two ASCII
+ *                  strings.
  *
- * \param P         Destination point
- * \param radix     Input numeric base
- * \param x         First affine coordinate as a null-terminated string
- * \param y         Second affine coordinate as a null-terminated string
+ * \param P         The destination point.
+ * \param radix     The numeric base of the input.
+ * \param x         The first affine coordinate, as a null-terminated string.
+ * \param y         The second affine coordinate, as a null-terminated string.
  *
- * \return          0 if successful, or a MBEDTLS_ERR_MPI_XXX error code
+ * \return          \c 0 on success.
+ * \return          An \c MBEDTLS_ERR_MPI_XXX error code on failure.
  */
 int mbedtls_ecp_point_read_string( mbedtls_ecp_point *P, int radix,
                            const char *x, const char *y );
 
 /**
- * \brief           Export a point into unsigned binary data
+ * \brief           This function exports a point into unsigned binary data.
  *
- * \param grp       Group to which the point should belong
- * \param P         Point to export
- * \param format    Point format, should be a MBEDTLS_ECP_PF_XXX macro
- * \param olen      Length of the actual output
- * \param buf       Output buffer
- * \param buflen    Length of the output buffer
+ * \param grp       The group to which the point should belong.
+ * \param P         The point to export.
+ * \param format    The point format. Should be an \c MBEDTLS_ECP_PF_XXX macro.
+ * \param olen      The length of the output.
+ * \param buf       The output buffer.
+ * \param buflen    The length of the output buffer.
  *
- * \return          0 if successful,
- *                  or MBEDTLS_ERR_ECP_BAD_INPUT_DATA
- *                  or MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA
+ *                  or #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL on failure.
  */
 int mbedtls_ecp_point_write_binary( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *P,
                             int format, size_t *olen,
                             unsigned char *buf, size_t buflen );
 
 /**
- * \brief           Import a point from unsigned binary data
+ * \brief           This function imports a point from unsigned binary data.
  *
- * \param grp       Group to which the point should belong
- * \param P         Point to import
- * \param buf       Input buffer
- * \param ilen      Actual length of input
+ * \note            This function does not check that the point actually
+ *                  belongs to the given group, see mbedtls_ecp_check_pubkey()
+ *                  for that.
  *
- * \return          0 if successful,
- *                  MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid,
- *                  MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
- *                  MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format
+ * \param grp       The group to which the point should belong.
+ * \param P         The point to import.
+ * \param buf       The input buffer.
+ * \param ilen      The length of the input.
+ *
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
+ * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
+ * \return          #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format
  *                  is not implemented.
  *
- * \note            This function does NOT check that the point actually
- *                  belongs to the given group, see mbedtls_ecp_check_pubkey() for
- *                  that.
  */
 int mbedtls_ecp_point_read_binary( const mbedtls_ecp_group *grp, mbedtls_ecp_point *P,
                            const unsigned char *buf, size_t ilen );
 
 /**
- * \brief           Import a point from a TLS ECPoint record
+ * \brief           This function imports a point from a TLS ECPoint record.
  *
- * \param grp       ECP group used
- * \param pt        Destination point
- * \param buf       $(Start of input buffer)
- * \param len       Buffer length
+ * \note            On function return, \p buf is updated to point to immediately
+ *                  after the ECPoint record.
  *
- * \note            buf is updated to point right after the ECPoint on exit
+ * \param grp       The ECP group used.
+ * \param pt        The destination point.
+ * \param buf       The address of the pointer to the start of the input buffer.
+ * \param len       The length of the buffer.
  *
- * \return          0 if successful,
- *                  MBEDTLS_ERR_MPI_XXX if initialization failed
- *                  MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid
+ * \return          \c 0 on success.
+ * \return          An \c MBEDTLS_ERR_MPI_XXX error code on initialization failure.
+ * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
  */
 int mbedtls_ecp_tls_read_point( const mbedtls_ecp_group *grp, mbedtls_ecp_point *pt,
                         const unsigned char **buf, size_t len );
 
 /**
- * \brief           Export a point as a TLS ECPoint record
+ * \brief           This function exports a point as a TLS ECPoint record.
  *
- * \param grp       ECP group used
- * \param pt        Point to export
- * \param format    Export format
- * \param olen      length of data written
- * \param buf       Buffer to write to
- * \param blen      Buffer length
+ * \param grp       The ECP group used.
+ * \param pt        The point format to export to. The point format is an
+ *                  \c MBEDTLS_ECP_PF_XXX constant.
+ * \param format    The export format.
+ * \param olen      The length of the data written.
+ * \param buf       The buffer to write to.
+ * \param blen      The length of the buffer.
  *
- * \return          0 if successful,
- *                  or MBEDTLS_ERR_ECP_BAD_INPUT_DATA
- *                  or MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA or
+ *                  #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL on failure.
  */
 int mbedtls_ecp_tls_write_point( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *pt,
                          int format, size_t *olen,
                          unsigned char *buf, size_t blen );
 
 /**
- * \brief           Set a group using well-known domain parameters
+ * \brief           This function sets a group using standardized domain parameters.
  *
- * \param grp       Destination group
- * \param id        Index in the list of well-known domain parameters
+ * \note            The index should be a value of the NamedCurve enum,
+ *                  as defined in <em>RFC-4492: Elliptic Curve Cryptography
+ *                  (ECC) Cipher Suites for Transport Layer Security (TLS)</em>,
+ *                  usually in the form of an \c MBEDTLS_ECP_DP_XXX macro.
  *
- * \return          0 if successful,
- *                  MBEDTLS_ERR_MPI_XXX if initialization failed
- *                  MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE for unkownn groups
+ * \param grp       The destination group.
+ * \param id        The identifier of the domain parameter set to load.
  *
- * \note            Index should be a value of RFC 4492's enum NamedCurve,
- *                  usually in the form of a MBEDTLS_ECP_DP_XXX macro.
+ * \return          \c 0 on success,
+ * \return          An \c MBEDTLS_ERR_MPI_XXX error code on initialization failure.
+ * \return          #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE for unkownn groups.
+
  */
 int mbedtls_ecp_group_load( mbedtls_ecp_group *grp, mbedtls_ecp_group_id id );
 
 /**
- * \brief           Set a group from a TLS ECParameters record
+ * \brief           This function sets a group from a TLS ECParameters record.
  *
- * \param grp       Destination group
- * \param buf       &(Start of input buffer)
- * \param len       Buffer length
+ * \note            \p buf is updated to point right after the ECParameters record
+ *                  on exit.
  *
- * \note            buf is updated to point right after ECParameters on exit
+ * \param grp       The destination group.
+ * \param buf       The address of the pointer to the start of the input buffer.
+ * \param len       The length of the buffer.
  *
- * \return          0 if successful,
- *                  MBEDTLS_ERR_MPI_XXX if initialization failed
- *                  MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid
+ * \return          \c 0 on success.
+ * \return          An \c MBEDTLS_ERR_MPI_XXX error code on initialization failure.
+ * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
  */
 int mbedtls_ecp_tls_read_group( mbedtls_ecp_group *grp, const unsigned char **buf, size_t len );
 
 /**
- * \brief           Write the TLS ECParameters record for a group
+ * \brief           This function writes the TLS ECParameters record for a group.
  *
- * \param grp       ECP group used
- * \param olen      Number of bytes actually written
- * \param buf       Buffer to write to
- * \param blen      Buffer length
+ * \param grp       The ECP group used.
+ * \param olen      The number of Bytes written.
+ * \param buf       The buffer to write to.
+ * \param blen      The length of the buffer.
  *
- * \return          0 if successful,
- *                  or MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL on failure.
  */
 int mbedtls_ecp_tls_write_group( const mbedtls_ecp_group *grp, size_t *olen,
                          unsigned char *buf, size_t blen );
 
 /**
- * \brief           Multiplication by an integer: R = m * P
- *                  (Not thread-safe to use same group in multiple threads)
+ * \brief           This function performs multiplication of a point by
+ *                  an integer: \p R = \p m * \p P.
  *
- * \note            In order to prevent timing attacks, this function
- *                  executes the exact same sequence of (base field)
- *                  operations for any valid m. It avoids any if-branch or
- *                  array index depending on the value of m.
+ *                  It is not thread-safe to use same group in multiple threads.
  *
- * \note            If f_rng is not NULL, it is used to randomize intermediate
- *                  results in order to prevent potential timing attacks
- *                  targeting these results. It is recommended to always
- *                  provide a non-NULL f_rng (the overhead is negligible).
+ * \note            To prevent timing attacks, this function
+ *                  executes the exact same sequence of base-field
+ *                  operations for any valid \p m. It avoids any if-branch or
+ *                  array index depending on the value of \p m.
  *
- * \param grp       ECP group
- * \param R         Destination point
- * \param m         Integer by which to multiply
- * \param P         Point to multiply
- * \param f_rng     RNG function (see notes)
- * \param p_rng     RNG parameter
+ * \note            If \p f_rng is not NULL, it is used to randomize
+ *                  intermediate results to prevent potential timing attacks
+ *                  targeting these results. We recommend always providing
+ *                  a non-NULL \p f_rng. The overhead is negligible.
  *
- * \return          0 if successful,
- *                  MBEDTLS_ERR_ECP_INVALID_KEY if m is not a valid privkey
- *                  or P is not a valid pubkey,
- *                  MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \param grp       The ECP group.
+ * \param R         The destination point.
+ * \param m         The integer by which to multiply.
+ * \param P         The point to multiply.
+ * \param f_rng     The RNG function.
+ * \param p_rng     The RNG context.
+ *
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_ECP_INVALID_KEY if \p m is not a valid private
+ *                  key, or \p P is not a valid public key.
+ * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
  */
 int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
              const mbedtls_mpi *m, const mbedtls_ecp_point *P,
              int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
 
 /**
- * \brief           Multiplication and addition of two points by integers:
- *                  R = m * P + n * Q
- *                  (Not thread-safe to use same group in multiple threads)
+ * \brief           This function performs multiplication and addition of two
+ *                  points by integers: \p R = \p m * \p P + \p n * \p Q
  *
- * \note            In contrast to mbedtls_ecp_mul(), this function does not guarantee
- *                  a constant execution flow and timing.
+ *                  It is not thread-safe to use same group in multiple threads.
  *
- * \param grp       ECP group
- * \param R         Destination point
- * \param m         Integer by which to multiply P
- * \param P         Point to multiply by m
- * \param n         Integer by which to multiply Q
- * \param Q         Point to be multiplied by n
+ * \note            In contrast to mbedtls_ecp_mul(), this function does not
+ *                  guarantee a constant execution flow and timing.
  *
- * \return          0 if successful,
- *                  MBEDTLS_ERR_ECP_INVALID_KEY if m or n is not a valid privkey
- *                  or P or Q is not a valid pubkey,
- *                  MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \param grp       The ECP group.
+ * \param R         The destination point.
+ * \param m         The integer by which to multiply \p P.
+ * \param P         The point to multiply by \p m.
+ * \param n         The integer by which to multiply \p Q.
+ * \param Q         The point to be multiplied by \p n.
+ *
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_ECP_INVALID_KEY if \p m or \p n are not
+ *                  valid private keys, or \p P or \p Q are not valid public
+ *                  keys.
+ * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
  */
 int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
              const mbedtls_mpi *m, const mbedtls_ecp_point *P,
              const mbedtls_mpi *n, const mbedtls_ecp_point *Q );
 
 /**
- * \brief           Check that a point is a valid public key on this curve
+ * \brief           This function checks that a point is a valid public key
+ *                  on this curve.
  *
- * \param grp       Curve/group the point should belong to
- * \param pt        Point to check
+ *                  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
+ *                  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
+ *                  the NIST groups which all have a cofactor of 1.
  *
- * \return          0 if point is a valid public key,
- *                  MBEDTLS_ERR_ECP_INVALID_KEY otherwise.
+ * \note            This function uses bare components rather than an
+ *                  ::mbedtls_ecp_keypair structure, to ease use with other
+ *                  structures, such as ::mbedtls_ecdh_context or
+ *                  ::mbedtls_ecdsa_context.
  *
- * \note            This function only checks the point is non-zero, has valid
- *                  coordinates and lies on the curve, but not that it is
- *                  indeed a multiple of G. This is additional check is more
- *                  expensive, isn't required by standards, and shouldn't be
- *                  necessary if the group used has a small cofactor. In
- *                  particular, it is useless for the NIST groups which all
- *                  have a cofactor of 1.
+ * \param grp       The curve the point should lie on.
+ * \param pt        The point to check.
  *
- * \note            Uses bare components rather than an mbedtls_ecp_keypair structure
- *                  in order to ease use with other structures such as
- *                  mbedtls_ecdh_context of mbedtls_ecdsa_context.
+ * \return          \c 0 if the point is a valid public key.
+ * \return          #MBEDTLS_ERR_ECP_INVALID_KEY on failure.
  */
 int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *pt );
 
 /**
- * \brief           Check that an mbedtls_mpi is a valid private key for this curve
+ * \brief           This function checks that an \p mbedtls_mpi is a valid private
+ *                  key for this curve.
  *
- * \param grp       Group used
- * \param d         Integer to check
+ * \note            This function uses bare components rather than an
+ *                  ::mbedtls_ecp_keypair structure to ease use with other
+ *                  structures, such as ::mbedtls_ecdh_context or
+ *                  ::mbedtls_ecdsa_context.
  *
- * \return          0 if point is a valid private key,
- *                  MBEDTLS_ERR_ECP_INVALID_KEY otherwise.
+ * \param grp       The group used.
+ * \param d         The integer to check.
  *
- * \note            Uses bare components rather than an mbedtls_ecp_keypair structure
- *                  in order to ease use with other structures such as
- *                  mbedtls_ecdh_context of mbedtls_ecdsa_context.
+ * \return          \c 0 if the point is a valid private key.
+ * \return          #MBEDTLS_ERR_ECP_INVALID_KEY on failure.
  */
 int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp, const mbedtls_mpi *d );
 
 /**
- * \brief           Generate a keypair with configurable base point
+ * \brief           This function generates a keypair with a configurable base
+ *                  point.
  *
- * \param grp       ECP group
- * \param G         Chosen base point
- * \param d         Destination MPI (secret part)
- * \param Q         Destination point (public part)
- * \param f_rng     RNG function
- * \param p_rng     RNG parameter
+ * \note            This function uses bare components rather than an
+ *                  ::mbedtls_ecp_keypair structure to ease use with other
+ *                  structures, such as ::mbedtls_ecdh_context or
+ *                  ::mbedtls_ecdsa_context.
  *
- * \return          0 if successful,
- *                  or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
+ * \param grp       The ECP group.
+ * \param G         The chosen base point.
+ * \param d         The destination MPI (secret part).
+ * \param Q         The destination point (public part).
+ * \param f_rng     The RNG function.
+ * \param p_rng     The RNG context.
  *
- * \note            Uses bare components rather than an mbedtls_ecp_keypair structure
- *                  in order to ease use with other structures such as
- *                  mbedtls_ecdh_context of mbedtls_ecdsa_context.
+ * \return          \c 0 on success.
+ * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
+ *                  on failure.
  */
 int mbedtls_ecp_gen_keypair_base( mbedtls_ecp_group *grp,
                      const mbedtls_ecp_point *G,
@@ -619,57 +692,66 @@
                      void *p_rng );
 
 /**
- * \brief           Generate a keypair
+ * \brief           This function generates an ECP keypair.
  *
- * \param grp       ECP group
- * \param d         Destination MPI (secret part)
- * \param Q         Destination point (public part)
- * \param f_rng     RNG function
- * \param p_rng     RNG parameter
+ * \note            This function uses bare components rather than an
+ *                  ::mbedtls_ecp_keypair structure to ease use with other
+ *                  structures, such as ::mbedtls_ecdh_context or
+ *                  ::mbedtls_ecdsa_context.
  *
- * \return          0 if successful,
- *                  or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
+ * \param grp       The ECP group.
+ * \param d         The destination MPI (secret part).
+ * \param Q         The destination point (public part).
+ * \param f_rng     The RNG function.
+ * \param p_rng     The RNG context.
  *
- * \note            Uses bare components rather than an mbedtls_ecp_keypair structure
- *                  in order to ease use with other structures such as
- *                  mbedtls_ecdh_context of mbedtls_ecdsa_context.
+ * \return          \c 0 on success.
+ * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
+ *                  on failure.
  */
 int mbedtls_ecp_gen_keypair( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q,
                      int (*f_rng)(void *, unsigned char *, size_t),
                      void *p_rng );
 
 /**
- * \brief           Generate a keypair
+ * \brief           This function generates an ECP key.
  *
- * \param grp_id    ECP group identifier
- * \param key       Destination keypair
- * \param f_rng     RNG function
- * \param p_rng     RNG parameter
+ * \param grp_id    The ECP group identifier.
+ * \param key       The destination key.
+ * \param f_rng     The RNG function.
+ * \param p_rng     The RNG context.
  *
- * \return          0 if successful,
- *                  or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
+ * \return          \c 0 on success.
+ * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
+ *                  on failure.
  */
 int mbedtls_ecp_gen_key( mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key,
                 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
 
 /**
- * \brief           Check a public-private key pair
+ * \brief           This function checks that the keypair objects
+ *                  \p pub and \p prv have the same group and the
+ *                  same public point, and that the private key in
+ *                  \p prv is consistent with the public key.
  *
- * \param pub       Keypair structure holding a public key
- * \param prv       Keypair structure holding a private (plus public) key
+ * \param pub       The keypair structure holding the public key.
+ *                  If it contains a private key, that part is ignored.
+ * \param prv       The keypair structure holding the full keypair.
  *
- * \return          0 if successful (keys are valid and match), or
- *                  MBEDTLS_ERR_ECP_BAD_INPUT_DATA, or
- *                  a MBEDTLS_ERR_ECP_XXX or MBEDTLS_ERR_MPI_XXX code.
+ * \return          \c 0 on success, meaning that the keys are valid and match.
+ * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the keys are invalid or do not match.
+ * \return          An \c MBEDTLS_ERR_ECP_XXX or an \c MBEDTLS_ERR_MPI_XXX
+ *                  error code on calculation failure.
  */
 int mbedtls_ecp_check_pub_priv( const mbedtls_ecp_keypair *pub, const mbedtls_ecp_keypair *prv );
 
 #if defined(MBEDTLS_SELF_TEST)
 
 /**
- * \brief          Checkup routine
+ * \brief          The ECP checkup routine.
  *
- * \return         0 if successful, or 1 if a test failed
+ * \return         \c 0 on success.
+ * \return         \c 1 on failure.
  */
 int mbedtls_ecp_self_test( int verbose );
 
@@ -679,8 +761,4 @@
 }
 #endif
 
-#else  /* MBEDTLS_ECP_ALT */
-#include "ecp_alt.h"
-#endif /* MBEDTLS_ECP_ALT */
-
 #endif /* ecp.h */
diff --git a/include/mbedtls/ecp_internal.h b/include/mbedtls/ecp_internal.h
index 8a6d517..1804069 100644
--- a/include/mbedtls/ecp_internal.h
+++ b/include/mbedtls/ecp_internal.h
@@ -48,7 +48,7 @@
  * [6] Digital Signature Standard (DSS), FIPS 186-4.
  *     <http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf>
  *
- * [7] Elliptic Curve Cryptography (ECC) Cipher Suites for Transport Layer 
+ * [7] Elliptic Curve Cryptography (ECC) Cipher Suites for Transport Layer
  *     Security (TLS), RFC 4492.
  *     <https://tools.ietf.org/search/rfc4492>
  *
diff --git a/include/mbedtls/entropy.h b/include/mbedtls/entropy.h
index fcb4d02..a5cb05a 100644
--- a/include/mbedtls/entropy.h
+++ b/include/mbedtls/entropy.h
@@ -166,7 +166,7 @@
  * \param threshold Minimum required from source before entropy is released
  *                  ( with mbedtls_entropy_func() ) (in bytes)
  * \param strong    MBEDTLS_ENTROPY_SOURCE_STRONG or
- *                  MBEDTSL_ENTROPY_SOURCE_WEAK.
+ *                  MBEDTLS_ENTROPY_SOURCE_WEAK.
  *                  At least one strong source needs to be added.
  *                  Weaker sources (such as the cycle counter) can be used as
  *                  a complement.
diff --git a/include/mbedtls/gcm.h b/include/mbedtls/gcm.h
index 1e5a507..bec5577 100644
--- a/include/mbedtls/gcm.h
+++ b/include/mbedtls/gcm.h
@@ -1,9 +1,11 @@
 /**
  * \file gcm.h
  *
- * \brief Galois/Counter Mode (GCM) for 128-bit block ciphers, as defined
- *        in <em>D. McGrew, J. Viega, The Galois/Counter Mode of Operation
- *        (GCM), Natl. Inst. Stand. Technol.</em>
+ * \brief This file contains GCM definitions and functions.
+ *
+ * The Galois/Counter Mode (GCM) for 128-bit block ciphers is defined
+ * in <em>D. McGrew, J. Viega, The Galois/Counter Mode of Operation
+ * (GCM), Natl. Inst. Stand. Technol.</em>
  *
  * For more information on GCM, see <em>NIST SP 800-38D: Recommendation for
  * Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC</em>.
@@ -42,12 +44,12 @@
 #define MBEDTLS_ERR_GCM_HW_ACCEL_FAILED                   -0x0013  /**< GCM hardware accelerator failed. */
 #define MBEDTLS_ERR_GCM_BAD_INPUT                         -0x0014  /**< Bad input parameters to function. */
 
-#if !defined(MBEDTLS_GCM_ALT)
-
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+#if !defined(MBEDTLS_GCM_ALT)
+
 /**
  * \brief          The GCM context structure.
  */
@@ -66,6 +68,10 @@
 }
 mbedtls_gcm_context;
 
+#else  /* !MBEDTLS_GCM_ALT */
+#include "gcm_alt.h"
+#endif /* !MBEDTLS_GCM_ALT */
+
 /**
  * \brief           This function initializes the specified GCM context,
  *                  to make references valid, and prepares the context
@@ -91,7 +97,8 @@
  *                  <li>192 bits</li>
  *                  <li>256 bits</li></ul>
  *
- * \return          \c 0 on success, or a cipher specific error code.
+ * \return          \c 0 on success.
+ * \return          A cipher-specific error code on failure.
  */
 int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx,
                         mbedtls_cipher_id_t cipher,
@@ -101,15 +108,16 @@
 /**
  * \brief           This function performs GCM encryption or decryption of a buffer.
  *
- * \note For encryption, the output buffer can be the same as the input buffer.
- *       For decryption, the output buffer cannot be the same as input buffer.
- *       If the buffers overlap, the output buffer must trail at least 8 Bytes
- *       behind the input buffer.
+ * \note            For encryption, the output buffer can be the same as the
+ *                  input buffer. For decryption, the output buffer cannot be
+ *                  the same as input buffer. If the buffers overlap, the output
+ *                  buffer must trail at least 8 Bytes behind the input buffer.
  *
  * \param ctx       The GCM context to use for encryption or decryption.
  * \param mode      The operation to perform: #MBEDTLS_GCM_ENCRYPT or
  *                  #MBEDTLS_GCM_DECRYPT.
- * \param length    The length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish().
+ * \param length    The length of the input data. This must be a multiple of
+ *                  16 except in the last call before mbedtls_gcm_finish().
  * \param iv        The initialization vector.
  * \param iv_len    The length of the IV.
  * \param add       The buffer holding the additional data.
@@ -137,12 +145,13 @@
  * \brief           This function performs a GCM authenticated decryption of a
  *                  buffer.
  *
- * \note For decryption, the output buffer cannot be the same as input buffer.
- *       If the buffers overlap, the output buffer must trail at least 8 Bytes
- *       behind the input buffer.
+ * \note            For decryption, the output buffer cannot be the same as
+ *                  input buffer. If the buffers overlap, the output buffer
+ *                  must trail at least 8 Bytes behind the input buffer.
  *
  * \param ctx       The GCM context.
- * \param length    The length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish().
+ * \param length    The length of the input data. This must be a multiple
+ *                  of 16 except in the last call before mbedtls_gcm_finish().
  * \param iv        The initialization vector.
  * \param iv_len    The length of the IV.
  * \param add       The buffer holding the additional data.
@@ -152,8 +161,8 @@
  * \param input     The buffer holding the input data.
  * \param output    The buffer for holding the output data.
  *
- * \return         0 if successful and authenticated, or
- *                 #MBEDTLS_ERR_GCM_AUTH_FAILED if tag does not match.
+ * \return         0 if successful and authenticated.
+ * \return         #MBEDTLS_ERR_GCM_AUTH_FAILED if the tag does not match.
  */
 int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx,
                       size_t length,
@@ -175,10 +184,12 @@
  *                  #MBEDTLS_GCM_DECRYPT.
  * \param iv        The initialization vector.
  * \param iv_len    The length of the IV.
- * \param add       The buffer holding the additional data, or NULL if \p add_len is 0.
- * \param add_len   The length of the additional data. If 0, \p  add is NULL.
+ * \param add       The buffer holding the additional data, or NULL
+ *                  if \p add_len is 0.
+ * \param add_len   The length of the additional data. If 0,
+ *                  \p add is NULL.
  *
- * \return         \c 0 on success.
+ * \return          \c 0 on success.
  */
 int mbedtls_gcm_starts( mbedtls_gcm_context *ctx,
                 int mode,
@@ -195,16 +206,18 @@
  *                  Bytes. Only the last call before calling
  *                  mbedtls_gcm_finish() can be less than 16 Bytes.
  *
- * \note For decryption, the output buffer cannot be the same as input buffer.
- *       If the buffers overlap, the output buffer must trail at least 8 Bytes
- *       behind the input buffer.
+ * \note            For decryption, the output buffer cannot be the same as
+ *                  input buffer. If the buffers overlap, the output buffer
+ *                  must trail at least 8 Bytes behind the input buffer.
  *
  * \param ctx       The GCM context.
- * \param length    The length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish().
+ * \param length    The length of the input data. This must be a multiple of
+ *                  16 except in the last call before mbedtls_gcm_finish().
  * \param input     The buffer holding the input data.
  * \param output    The buffer for holding the output data.
  *
- * \return         \c 0 on success, or #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
+ * \return         \c 0 on success.
+ * \return         #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
  */
 int mbedtls_gcm_update( mbedtls_gcm_context *ctx,
                 size_t length,
@@ -222,7 +235,8 @@
  * \param tag       The buffer for holding the tag.
  * \param tag_len   The length of the tag to generate. Must be at least four.
  *
- * \return          \c 0 on success, or #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
  */
 int mbedtls_gcm_finish( mbedtls_gcm_context *ctx,
                 unsigned char *tag,
@@ -236,22 +250,11 @@
  */
 void mbedtls_gcm_free( mbedtls_gcm_context *ctx );
 
-#ifdef __cplusplus
-}
-#endif
-
-#else  /* !MBEDTLS_GCM_ALT */
-#include "gcm_alt.h"
-#endif /* !MBEDTLS_GCM_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
 /**
  * \brief          The GCM checkup routine.
  *
- * \return         \c 0 on success, or \c 1 on failure.
+ * \return         \c 0 on success.
+ * \return         \c 1 on failure.
  */
 int mbedtls_gcm_self_test( int verbose );
 
diff --git a/include/mbedtls/md.h b/include/mbedtls/md.h
index 06538c3..6b6f5c5 100644
--- a/include/mbedtls/md.h
+++ b/include/mbedtls/md.h
@@ -1,7 +1,7 @@
  /**
  * \file md.h
  *
- * \brief The generic message-digest wrapper.
+ * \brief This file contains the generic message-digest wrapper.
  *
  * \author Adriaan de Jong <dejong@fox-it.com>
  */
@@ -46,7 +46,7 @@
 #endif
 
 /**
- * \brief     Enumeration of supported message digests
+ * \brief     Supported message digests.
  *
  * \warning   MD2, MD4, MD5 and SHA-1 are considered weak message digests and
  *            their use constitutes a security risk. We recommend considering
@@ -54,16 +54,16 @@
  *
  */
 typedef enum {
-    MBEDTLS_MD_NONE=0,
-    MBEDTLS_MD_MD2,
-    MBEDTLS_MD_MD4,
-    MBEDTLS_MD_MD5,
-    MBEDTLS_MD_SHA1,
-    MBEDTLS_MD_SHA224,
-    MBEDTLS_MD_SHA256,
-    MBEDTLS_MD_SHA384,
-    MBEDTLS_MD_SHA512,
-    MBEDTLS_MD_RIPEMD160,
+    MBEDTLS_MD_NONE=0,    /**< None. */
+    MBEDTLS_MD_MD2,       /**< The MD2 message digest. */
+    MBEDTLS_MD_MD4,       /**< The MD4 message digest. */
+    MBEDTLS_MD_MD5,       /**< The MD5 message digest. */
+    MBEDTLS_MD_SHA1,      /**< The SHA-1 message digest. */
+    MBEDTLS_MD_SHA224,    /**< The SHA-224 message digest. */
+    MBEDTLS_MD_SHA256,    /**< The SHA-256 message digest. */
+    MBEDTLS_MD_SHA384,    /**< The SHA-384 message digest. */
+    MBEDTLS_MD_SHA512,    /**< The SHA-512 message digest. */
+    MBEDTLS_MD_RIPEMD160, /**< The RIPEMD-160 message digest. */
 } mbedtls_md_type_t;
 
 #if defined(MBEDTLS_SHA512_C)
@@ -108,8 +108,8 @@
  *
  * \param md_name   The name of the digest to search for.
  *
- * \return          The message-digest information associated with \p md_name,
- *                  or NULL if not found.
+ * \return          The message-digest information associated with \p md_name.
+ * \return          NULL if the associated message-digest information is not found.
  */
 const mbedtls_md_info_t *mbedtls_md_info_from_string( const char *md_name );
 
@@ -119,8 +119,8 @@
  *
  * \param md_type   The type of digest to search for.
  *
- * \return          The message-digest information associated with \p md_type,
- *                  or NULL if not found.
+ * \return          The message-digest information associated with \p md_type.
+ * \return          NULL if the associated message-digest information is not found.
  */
 const mbedtls_md_info_t *mbedtls_md_info_from_type( mbedtls_md_type_t md_type );
 
@@ -168,9 +168,10 @@
  * \param md_info   The information structure of the message-digest algorithm
  *                  to use.
  *
- * \returns         \c 0 on success,
- *                  #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure,
- *                  #MBEDTLS_ERR_MD_ALLOC_FAILED memory allocation failure.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ *                  failure.
+ * \return          #MBEDTLS_ERR_MD_ALLOC_FAILED on memory-allocation failure.
  */
 int mbedtls_md_init_ctx( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info ) MBEDTLS_DEPRECATED;
 #undef MBEDTLS_DEPRECATED
@@ -187,12 +188,13 @@
  * \param ctx       The context to set up.
  * \param md_info   The information structure of the message-digest algorithm
  *                  to use.
- * \param hmac      <ul><li>0: HMAC is not used. Saves some memory.</li>
- *                  <li>non-zero: HMAC is used with this context.</li></ul>
+ * \param hmac      Defines if HMAC is used. 0: HMAC is not used (saves some memory),
+ *                  or non-zero: HMAC is used with this context.
  *
- * \returns         \c 0 on success,
- *                  #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure, or
- *                  #MBEDTLS_ERR_MD_ALLOC_FAILED on memory allocation failure.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ *                  failure.
+ * \return          #MBEDTLS_ERR_MD_ALLOC_FAILED on memory-allocation failure.
  */
 int mbedtls_md_setup( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info, int hmac );
 
@@ -212,8 +214,8 @@
  * \param dst       The destination context.
  * \param src       The context to be cloned.
  *
- * \return          \c 0 on success,
- *                  #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.
  */
 int mbedtls_md_clone( mbedtls_md_context_t *dst,
                       const mbedtls_md_context_t *src );
@@ -260,8 +262,9 @@
  *
  * \param ctx       The generic message-digest context.
  *
- * \returns         \c 0 on success, #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
- *                  parameter verification fails.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ *                  failure.
  */
 int mbedtls_md_starts( mbedtls_md_context_t *ctx );
 
@@ -277,8 +280,9 @@
  * \param input     The buffer holding the input data.
  * \param ilen      The length of the input data.
  *
- * \returns         \c 0 on success, #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
- *                  parameter verification fails.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ *                  failure.
  */
 int mbedtls_md_update( mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen );
 
@@ -296,8 +300,9 @@
  * \param ctx       The generic message-digest context.
  * \param output    The buffer for the generic message-digest checksum result.
  *
- * \returns         \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
- *                  parameter verification fails.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ *                  failure.
  */
 int mbedtls_md_finish( mbedtls_md_context_t *ctx, unsigned char *output );
 
@@ -315,8 +320,9 @@
  * \param ilen     The length of the input data.
  * \param output   The generic message-digest checksum result.
  *
- * \returns        \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
- *                 parameter verification fails.
+ * \return         \c 0 on success.
+ * \return         #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ *                 failure.
  */
 int mbedtls_md( const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen,
         unsigned char *output );
@@ -334,9 +340,10 @@
  * \param path     The input file name.
  * \param output   The generic message-digest checksum result.
  *
- * \return         \c 0 on success,
- *                 #MBEDTLS_ERR_MD_FILE_IO_ERROR if file input failed, or
- *                 #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info was NULL.
+ * \return         \c 0 on success.
+ * \return         #MBEDTLS_ERR_MD_FILE_IO_ERROR on an I/O error accessing
+ *                 the file pointed by \p path.
+ * \return         #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info was NULL.
  */
 int mbedtls_md_file( const mbedtls_md_info_t *md_info, const char *path,
                      unsigned char *output );
@@ -356,8 +363,9 @@
  * \param key       The HMAC secret key.
  * \param keylen    The length of the HMAC key in Bytes.
  *
- * \returns         \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
- *                  parameter verification fails.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ *                  failure.
  */
 int mbedtls_md_hmac_starts( mbedtls_md_context_t *ctx, const unsigned char *key,
                     size_t keylen );
@@ -377,8 +385,9 @@
  * \param input     The buffer holding the input data.
  * \param ilen      The length of the input data.
  *
- * \returns         \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
- *                  parameter verification fails.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ *                  failure.
  */
 int mbedtls_md_hmac_update( mbedtls_md_context_t *ctx, const unsigned char *input,
                     size_t ilen );
@@ -397,8 +406,9 @@
  *                  context.
  * \param output    The generic HMAC checksum result.
  *
- * \returns         \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
- *                  parameter verification fails.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ *                  failure.
  */
 int mbedtls_md_hmac_finish( mbedtls_md_context_t *ctx, unsigned char *output);
 
@@ -413,8 +423,9 @@
  * \param ctx       The message digest context containing an embedded HMAC
  *                  context.
  *
- * \returns         \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
- *                  parameter verification fails.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ *                  failure.
  */
 int mbedtls_md_hmac_reset( mbedtls_md_context_t *ctx );
 
@@ -436,8 +447,9 @@
  * \param ilen     The length of the input data.
  * \param output   The generic HMAC result.
  *
- * \returns        \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
- *                 parameter verification fails.
+ * \return         \c 0 on success.
+ * \return         #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ *                 failure.
  */
 int mbedtls_md_hmac( const mbedtls_md_info_t *md_info, const unsigned char *key, size_t keylen,
                 const unsigned char *input, size_t ilen,
diff --git a/include/mbedtls/md2.h b/include/mbedtls/md2.h
index 0fd8b5a..08e75b2 100644
--- a/include/mbedtls/md2.h
+++ b/include/mbedtls/md2.h
@@ -39,14 +39,14 @@
 
 #define MBEDTLS_ERR_MD2_HW_ACCEL_FAILED                   -0x002B  /**< MD2 hardware accelerator failed */
 
-#if !defined(MBEDTLS_MD2_ALT)
-// Regular implementation
-//
-
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+#if !defined(MBEDTLS_MD2_ALT)
+// Regular implementation
+//
+
 /**
  * \brief          MD2 context structure
  *
@@ -64,6 +64,10 @@
 }
 mbedtls_md2_context;
 
+#else  /* MBEDTLS_MD2_ALT */
+#include "md2_alt.h"
+#endif /* MBEDTLS_MD2_ALT */
+
 /**
  * \brief          Initialize MD2 context
  *
@@ -235,18 +239,6 @@
 #undef MBEDTLS_DEPRECATED
 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
 
-#ifdef __cplusplus
-}
-#endif
-
-#else  /* MBEDTLS_MD2_ALT */
-#include "md2_alt.h"
-#endif /* MBEDTLS_MD2_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
 /**
  * \brief          Output = MD2( input buffer )
  *
diff --git a/include/mbedtls/md4.h b/include/mbedtls/md4.h
index 23fa95e..8ee4e5c 100644
--- a/include/mbedtls/md4.h
+++ b/include/mbedtls/md4.h
@@ -40,14 +40,14 @@
 
 #define MBEDTLS_ERR_MD4_HW_ACCEL_FAILED                   -0x002D  /**< MD4 hardware accelerator failed */
 
-#if !defined(MBEDTLS_MD4_ALT)
-// Regular implementation
-//
-
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+#if !defined(MBEDTLS_MD4_ALT)
+// Regular implementation
+//
+
 /**
  * \brief          MD4 context structure
  *
@@ -64,6 +64,10 @@
 }
 mbedtls_md4_context;
 
+#else  /* MBEDTLS_MD4_ALT */
+#include "md4_alt.h"
+#endif /* MBEDTLS_MD4_ALT */
+
 /**
  * \brief          Initialize MD4 context
  *
@@ -238,18 +242,6 @@
 #undef MBEDTLS_DEPRECATED
 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
 
-#ifdef __cplusplus
-}
-#endif
-
-#else  /* MBEDTLS_MD4_ALT */
-#include "md4_alt.h"
-#endif /* MBEDTLS_MD4_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
 /**
  * \brief          Output = MD4( input buffer )
  *
diff --git a/include/mbedtls/md5.h b/include/mbedtls/md5.h
index 06ea4c5..43ead4b 100644
--- a/include/mbedtls/md5.h
+++ b/include/mbedtls/md5.h
@@ -39,14 +39,14 @@
 
 #define MBEDTLS_ERR_MD5_HW_ACCEL_FAILED                   -0x002F  /**< MD5 hardware accelerator failed */
 
-#if !defined(MBEDTLS_MD5_ALT)
-// Regular implementation
-//
-
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+#if !defined(MBEDTLS_MD5_ALT)
+// Regular implementation
+//
+
 /**
  * \brief          MD5 context structure
  *
@@ -63,6 +63,10 @@
 }
 mbedtls_md5_context;
 
+#else  /* MBEDTLS_MD5_ALT */
+#include "md5_alt.h"
+#endif /* MBEDTLS_MD5_ALT */
+
 /**
  * \brief          Initialize MD5 context
  *
@@ -238,18 +242,6 @@
 #undef MBEDTLS_DEPRECATED
 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
 
-#ifdef __cplusplus
-}
-#endif
-
-#else  /* MBEDTLS_MD5_ALT */
-#include "md5_alt.h"
-#endif /* MBEDTLS_MD5_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
 /**
  * \brief          Output = MD5( input buffer )
  *
diff --git a/include/mbedtls/net_sockets.h b/include/mbedtls/net_sockets.h
index 54e612c..0f9b31e 100644
--- a/include/mbedtls/net_sockets.h
+++ b/include/mbedtls/net_sockets.h
@@ -46,12 +46,17 @@
 #define MBEDTLS_ERR_NET_UNKNOWN_HOST                      -0x0052  /**< Failed to get an IP address for the given hostname. */
 #define MBEDTLS_ERR_NET_BUFFER_TOO_SMALL                  -0x0043  /**< Buffer is too small to hold the data. */
 #define MBEDTLS_ERR_NET_INVALID_CONTEXT                   -0x0045  /**< The context is invalid, eg because it was free()ed. */
+#define MBEDTLS_ERR_NET_POLL_FAILED                       -0x0047  /**< Polling the net context failed. */
+#define MBEDTLS_ERR_NET_BAD_INPUT_DATA                    -0x0049  /**< Input invalid. */
 
 #define MBEDTLS_NET_LISTEN_BACKLOG         10 /**< The backlog that listen() should use. */
 
 #define MBEDTLS_NET_PROTO_TCP 0 /**< The TCP transport protocol */
 #define MBEDTLS_NET_PROTO_UDP 1 /**< The UDP transport protocol */
 
+#define MBEDTLS_NET_POLL_READ  1 /**< Used in \c mbedtls_net_poll to check for pending data  */
+#define MBEDTLS_NET_POLL_WRITE 2 /**< Used in \c mbedtls_net_poll to check if write possible */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -118,9 +123,10 @@
  *
  * \param bind_ctx  Relevant socket
  * \param client_ctx Will contain the connected client socket
- * \param client_ip Will contain the client IP address
+ * \param client_ip Will contain the client IP address, can be NULL
  * \param buf_size  Size of the client_ip buffer
- * \param ip_len    Will receive the size of the client IP written
+ * \param ip_len    Will receive the size of the client IP written,
+ *                  can be NULL if client_ip is null
  *
  * \return          0 if successful, or
  *                  MBEDTLS_ERR_NET_ACCEPT_FAILED, or
@@ -133,6 +139,29 @@
                         void *client_ip, size_t buf_size, size_t *ip_len );
 
 /**
+ * \brief          Check and wait for the context to be ready for read/write
+ *
+ * \param ctx      Socket to check
+ * \param rw       Bitflag composed of MBEDTLS_NET_POLL_READ and
+ *                 MBEDTLS_NET_POLL_WRITE specifying the events
+ *                 to wait for:
+ *                 - If MBEDTLS_NET_POLL_READ is set, the function
+ *                   will return as soon as the net context is available
+ *                   for reading.
+ *                 - If MBEDTLS_NET_POLL_WRITE is set, the function
+ *                   will return as soon as the net context is available
+ *                   for writing.
+ * \param timeout  Maximal amount of time to wait before returning,
+ *                 in milliseconds. If \c timeout is zero, the
+ *                 function returns immediately. If \c timeout is
+ *                 -1u, the function blocks potentially indefinitely.
+ *
+ * \return         Bitmask composed of MBEDTLS_NET_POLL_READ/WRITE
+ *                 on success or timeout, or a negative return code otherwise.
+ */
+int mbedtls_net_poll( mbedtls_net_context *ctx, uint32_t rw, uint32_t timeout );
+
+/**
  * \brief          Set the socket blocking
  *
  * \param ctx      Socket to set
diff --git a/include/mbedtls/pk.h b/include/mbedtls/pk.h
index 1059bda..ee06b2f 100644
--- a/include/mbedtls/pk.h
+++ b/include/mbedtls/pk.h
@@ -63,7 +63,7 @@
 #define MBEDTLS_ERR_PK_INVALID_ALG         -0x3A80  /**< The algorithm tag or value is invalid. */
 #define MBEDTLS_ERR_PK_UNKNOWN_NAMED_CURVE -0x3A00  /**< Elliptic curve is unsupported (only NIST curves are supported). */
 #define MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE -0x3980  /**< Unavailable feature, e.g. RSA disabled for RSA key. */
-#define MBEDTLS_ERR_PK_SIG_LEN_MISMATCH    -0x3900  /**< The signature is valid but its length is less than expected. */
+#define MBEDTLS_ERR_PK_SIG_LEN_MISMATCH    -0x3900  /**< The buffer contains a valid signature followed by more data. */
 #define MBEDTLS_ERR_PK_HW_ACCEL_FAILED     -0x3880  /**< PK hardware accelerator failed. */
 
 #ifdef __cplusplus
@@ -269,8 +269,8 @@
  * \param sig_len   Signature length
  *
  * \return          0 on success (signature is valid),
- *                  MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if the signature is
- *                  valid but its actual length is less than sig_len,
+ *                  #MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if there is a valid
+ *                  signature in sig but its length is less than \p siglen,
  *                  or a specific error code.
  *
  * \note            For RSA keys, the default padding type is PKCS#1 v1.5.
@@ -300,10 +300,10 @@
  * \param sig_len   Signature length
  *
  * \return          0 on success (signature is valid),
- *                  MBEDTLS_ERR_PK_TYPE_MISMATCH if the PK context can't be
+ *                  #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 the signature is
- *                  valid but its actual length is less than sig_len,
+ *                  #MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if there is a valid
+ *                  signature in sig but its length is less than \p siglen,
  *                  or a specific error code.
  *
  * \note            If hash_len is 0, then the length associated with md_alg
diff --git a/include/mbedtls/platform.h b/include/mbedtls/platform.h
index ed10775..bba7709 100644
--- a/include/mbedtls/platform.h
+++ b/include/mbedtls/platform.h
@@ -1,7 +1,16 @@
 /**
  * \file platform.h
  *
- * \brief The Mbed TLS platform abstraction layer.
+ * \brief This file contains the definitions and functions of the
+ *        Mbed TLS platform abstraction layer.
+ *
+ *        The platform abstraction layer removes the need for the library
+ *        to directly link to standard C library functions or operating
+ *        system services, making the library easier to port and embed.
+ *        Application developers and users of the library can provide their own
+ *        implementations of these functions, or implementations specific to
+ *        their platform, which can be statically linked to the library or
+ *        dynamically configured at runtime.
  */
 /*
  *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
@@ -102,7 +111,7 @@
 /* \} name SECTION: Module settings */
 
 /*
- * The function pointers for calloc and free
+ * The function pointers for calloc and free.
  */
 #if defined(MBEDTLS_PLATFORM_MEMORY)
 #if defined(MBEDTLS_PLATFORM_FREE_MACRO) && \
@@ -116,7 +125,8 @@
 extern void (*mbedtls_free)( void *ptr );
 
 /**
- * \brief   This function allows configuring custom memory-management functions.
+ * \brief               This function dynamically sets the memory-management
+ *                      functions used by the library, during runtime.
  *
  * \param calloc_func   The \c calloc function implementation.
  * \param free_func     The \c free function implementation.
@@ -140,7 +150,9 @@
 extern int (*mbedtls_fprintf)( FILE *stream, const char *format, ... );
 
 /**
- * \brief   This function allows configuring a custom \p fprintf function pointer.
+ * \brief                This function dynamically configures the fprintf
+ *                       function that is called when the
+ *                       mbedtls_fprintf() function is invoked by the library.
  *
  * \param fprintf_func   The \c fprintf function implementation.
  *
@@ -163,8 +175,9 @@
 extern int (*mbedtls_printf)( const char *format, ... );
 
 /**
- * \brief    This function allows configuring a custom \c printf function
- *           pointer.
+ * \brief               This function dynamically configures the snprintf
+ *                      function that is called when the mbedtls_snprintf()
+ *                      function is invoked by the library.
  *
  * \param printf_func   The \c printf function implementation.
  *
@@ -197,12 +210,12 @@
 extern int (*mbedtls_snprintf)( char * s, size_t n, const char * format, ... );
 
 /**
- * \brief   This function allows configuring a custom \c snprintf function
- *          pointer.
+ * \brief                 This function allows configuring a custom
+ *                        \c snprintf function pointer.
  *
  * \param snprintf_func   The \c snprintf function implementation.
  *
- * \return    \c 0 on success.
+ * \return                \c 0 on success.
  */
 int mbedtls_platform_set_snprintf( int (*snprintf_func)( char * s, size_t n,
                                                  const char * format, ... ) );
@@ -210,7 +223,7 @@
 #if defined(MBEDTLS_PLATFORM_SNPRINTF_MACRO)
 #define mbedtls_snprintf   MBEDTLS_PLATFORM_SNPRINTF_MACRO
 #else
-#define mbedtls_snprintf   snprintf
+#define mbedtls_snprintf   MBEDTLS_PLATFORM_STD_SNPRINTF
 #endif /* MBEDTLS_PLATFORM_SNPRINTF_MACRO */
 #endif /* MBEDTLS_PLATFORM_SNPRINTF_ALT */
 
@@ -221,12 +234,13 @@
 extern void (*mbedtls_exit)( int status );
 
 /**
- * \brief   This function allows configuring a custom \c exit function
- *          pointer.
+ * \brief             This function dynamically configures the exit
+ *                    function that is called when the mbedtls_exit()
+ *                    function is invoked by the library.
  *
  * \param exit_func   The \c exit function implementation.
  *
- * \return  \c 0 on success.
+ * \return            \c 0 on success.
  */
 int mbedtls_platform_set_exit( void (*exit_func)( int status ) );
 #else
@@ -302,7 +316,7 @@
  *          setup or teardown operations.
  */
 typedef struct {
-    char dummy; /**< Placeholder member, as empty structs are not portable. */
+    char dummy; /**< A placeholder member, as empty structs are not portable. */
 }
 mbedtls_platform_context;
 
@@ -311,33 +325,34 @@
 #endif /* !MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT */
 
 /**
- * \brief   This function performs any platform initialization operations.
+ * \brief   This function performs any platform-specific initialization
+ *          operations.
  *
- * \param   ctx     The Mbed TLS context.
+ * \note    This function should be called before any other library functions.
  *
- * \return  \c 0 on success.
- *
- * \note    This function is intended to allow platform-specific initialization,
- *          and should be called before any other library functions. Its
- *          implementation is platform-specific, and unless
+ *          Its implementation is platform-specific, and unless
  *          platform-specific code is provided, it does nothing.
  *
- *          Its use and whether it is necessary to call it is dependent on the
- *          platform.
+ * \note    The usage and necessity of this function is dependent on the platform.
+ *
+ * \param   ctx     The platform context.
+ *
+ * \return  \c 0 on success.
  */
 int mbedtls_platform_setup( mbedtls_platform_context *ctx );
 /**
  * \brief   This function performs any platform teardown operations.
  *
- * \param   ctx     The Mbed TLS context.
- *
  * \note    This function should be called after every other Mbed TLS module
  *          has been correctly freed using the appropriate free function.
+ *
  *          Its implementation is platform-specific, and unless
  *          platform-specific code is provided, it does nothing.
  *
- *          Its use and whether it is necessary to call it is dependent on the
- *          platform.
+ * \note    The usage and necessity of this function is dependent on the platform.
+ *
+ * \param   ctx     The platform context.
+ *
  */
 void mbedtls_platform_teardown( mbedtls_platform_context *ctx );
 
diff --git a/include/mbedtls/platform_util.h b/include/mbedtls/platform_util.h
new file mode 100644
index 0000000..84f0732
--- /dev/null
+++ b/include/mbedtls/platform_util.h
@@ -0,0 +1,62 @@
+/**
+ * \file platform_util.h
+ *
+ * \brief Common and shared functions used by multiple modules in the Mbed TLS
+ *        library.
+ */
+/*
+ *  Copyright (C) 2018, Arm Limited, All Rights Reserved
+ *  SPDX-License-Identifier: Apache-2.0
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License"); you may
+ *  not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ *  This file is part of Mbed TLS (https://tls.mbed.org)
+ */
+#ifndef MBEDTLS_PLATFORM_UTIL_H
+#define MBEDTLS_PLATFORM_UTIL_H
+
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * \brief       Securely zeroize a buffer
+ *
+ *              The function is meant to wipe the data contained in a buffer so
+ *              that it can no longer be recovered even if the program memory
+ *              is later compromised. Call this function on sensitive data
+ *              stored on the stack before returning from a function, and on
+ *              sensitive data stored on the heap before freeing the heap
+ *              object.
+ *
+ *              It is extremely difficult to guarantee that calls to
+ *              mbedtls_platform_zeroize() are not removed by aggressive
+ *              compiler optimizations in a portable way. For this reason, Mbed
+ *              TLS provides the configuration option
+ *              MBEDTLS_PLATFORM_ZEROIZE_ALT, which allows users to configure
+ *              mbedtls_platform_zeroize() to use a suitable implementation for
+ *              their platform and needs
+ *
+ * \param buf   Buffer to be zeroized
+ * \param len   Length of the buffer in bytes
+ *
+ */
+void mbedtls_platform_zeroize( void *buf, size_t len );
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* MBEDTLS_PLATFORM_UTIL_H */
diff --git a/include/mbedtls/ripemd160.h b/include/mbedtls/ripemd160.h
index 3a8b50a..a0dac0c 100644
--- a/include/mbedtls/ripemd160.h
+++ b/include/mbedtls/ripemd160.h
@@ -35,14 +35,14 @@
 
 #define MBEDTLS_ERR_RIPEMD160_HW_ACCEL_FAILED             -0x0031  /**< RIPEMD160 hardware accelerator failed */
 
-#if !defined(MBEDTLS_RIPEMD160_ALT)
-// Regular implementation
-//
-
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+#if !defined(MBEDTLS_RIPEMD160_ALT)
+// Regular implementation
+//
+
 /**
  * \brief          RIPEMD-160 context structure
  */
@@ -54,6 +54,10 @@
 }
 mbedtls_ripemd160_context;
 
+#else  /* MBEDTLS_RIPEMD160_ALT */
+#include "ripemd160.h"
+#endif /* MBEDTLS_RIPEMD160_ALT */
+
 /**
  * \brief          Initialize RIPEMD-160 context
  *
@@ -178,18 +182,6 @@
 #undef MBEDTLS_DEPRECATED
 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
 
-#ifdef __cplusplus
-}
-#endif
-
-#else  /* MBEDTLS_RIPEMD160_ALT */
-#include "ripemd160_alt.h"
-#endif /* MBEDTLS_RIPEMD160_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
 /**
  * \brief          Output = RIPEMD-160( input buffer )
  *
diff --git a/include/mbedtls/rsa.h b/include/mbedtls/rsa.h
index fb2f77f..19eb2ee 100644
--- a/include/mbedtls/rsa.h
+++ b/include/mbedtls/rsa.h
@@ -1,11 +1,12 @@
 /**
  * \file rsa.h
  *
- * \brief The RSA public-key cryptosystem.
+ * \brief This file provides an API for the RSA public-key cryptosystem.
  *
- * For more information, see <em>Public-Key Cryptography Standards (PKCS)
- * #1 v1.5: RSA Encryption</em> and <em>Public-Key Cryptography Standards
- * (PKCS) #1 v2.1: RSA Cryptography Specifications</em>.
+ * The RSA public-key cryptosystem is defined in <em>Public-Key
+ * Cryptography Standards (PKCS) #1 v1.5: RSA Encryption</em>
+ * and <em>Public-Key Cryptography Standards (PKCS) #1 v2.1:
+ * RSA Cryptography Specifications</em>.
  *
  */
 /*
@@ -63,8 +64,8 @@
 #define MBEDTLS_RSA_PUBLIC      0 /**< Request private key operation. */
 #define MBEDTLS_RSA_PRIVATE     1 /**< Request public key operation. */
 
-#define MBEDTLS_RSA_PKCS_V15    0 /**< Use PKCS-1 v1.5 encoding. */
-#define MBEDTLS_RSA_PKCS_V21    1 /**< Use PKCS-1 v2.1 encoding. */
+#define MBEDTLS_RSA_PKCS_V15    0 /**< Use PKCS#1 v1.5 encoding. */
+#define MBEDTLS_RSA_PKCS_V21    1 /**< Use PKCS#1 v2.1 encoding. */
 
 #define MBEDTLS_RSA_SIGN        1 /**< Identifier for RSA signature operations. */
 #define MBEDTLS_RSA_CRYPT       2 /**< Identifier for RSA encryption and decryption operations. */
@@ -76,14 +77,14 @@
  * eg for alternative (PKCS#11) RSA implemenations in the PK layers.
  */
 
-#if !defined(MBEDTLS_RSA_ALT)
-// Regular implementation
-//
-
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+#if !defined(MBEDTLS_RSA_ALT)
+// Regular implementation
+//
+
 /**
  * \brief   The RSA context structure.
  *
@@ -96,24 +97,24 @@
     int ver;                    /*!<  Always 0.*/
     size_t len;                 /*!<  The size of \p N in Bytes. */
 
-    mbedtls_mpi N;                      /*!<  The public modulus. */
-    mbedtls_mpi E;                      /*!<  The public exponent. */
+    mbedtls_mpi N;              /*!<  The public modulus. */
+    mbedtls_mpi E;              /*!<  The public exponent. */
 
-    mbedtls_mpi D;                      /*!<  The private exponent. */
-    mbedtls_mpi P;                      /*!<  The first prime factor. */
-    mbedtls_mpi Q;                      /*!<  The second prime factor. */
+    mbedtls_mpi D;              /*!<  The private exponent. */
+    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;             /*!<  <code>D % (P - 1)</code>. */
+    mbedtls_mpi DQ;             /*!<  <code>D % (Q - 1)</code>. */
+    mbedtls_mpi QP;             /*!<  <code>1 / (Q % P)</code>. */
 
-    mbedtls_mpi RN;                     /*!<  cached R^2 mod \p N  */
+    mbedtls_mpi RN;             /*!<  cached <code>R^2 mod N</code>. */
 
-    mbedtls_mpi RP;                     /*!<  cached R^2 mod \p P  */
-    mbedtls_mpi RQ;                     /*!<  cached R^2 mod \p Q  */
+    mbedtls_mpi RP;             /*!<  cached <code>R^2 mod P</code>. */
+    mbedtls_mpi RQ;             /*!<  cached <code>R^2 mod Q</code>. */
 
-    mbedtls_mpi Vi;                     /*!<  The cached blinding value. */
-    mbedtls_mpi Vf;                     /*!<  The cached un-blinding value. */
+    mbedtls_mpi Vi;             /*!<  The cached blinding value. */
+    mbedtls_mpi Vf;             /*!<  The cached un-blinding value. */
 
     int padding;                /*!< Selects padding mode:
                                      #MBEDTLS_RSA_PKCS_V15 for 1.5 padding and
@@ -128,18 +129,16 @@
 }
 mbedtls_rsa_context;
 
+#else  /* MBEDTLS_RSA_ALT */
+#include "rsa_alt.h"
+#endif /* MBEDTLS_RSA_ALT */
+
 /**
  * \brief          This function initializes an RSA context.
  *
  * \note           Set padding to #MBEDTLS_RSA_PKCS_V21 for the RSAES-OAEP
  *                 encryption scheme and the RSASSA-PSS signature scheme.
  *
- * \param ctx      The RSA context to initialize.
- * \param padding  Selects padding mode: #MBEDTLS_RSA_PKCS_V15 or
- *                 #MBEDTLS_RSA_PKCS_V21.
- * \param hash_id  The hash identifier of #mbedtls_md_type_t type, if
- *                 \p padding is #MBEDTLS_RSA_PKCS_V21.
- *
  * \note           The \p hash_id parameter is ignored when using
  *                 #MBEDTLS_RSA_PKCS_V15 padding.
  *
@@ -153,6 +152,12 @@
  *                 encryption. For PSS signatures, it is always used for
  *                 making signatures, but can be overriden for verifying them.
  *                 If set to #MBEDTLS_MD_NONE, it is always overriden.
+ *
+ * \param ctx      The RSA context to initialize.
+ * \param padding  Selects padding mode: #MBEDTLS_RSA_PKCS_V15 or
+ *                 #MBEDTLS_RSA_PKCS_V21.
+ * \param hash_id  The hash identifier of #mbedtls_md_type_t type, if
+ *                 \p padding is #MBEDTLS_RSA_PKCS_V21.
  */
 void mbedtls_rsa_init( mbedtls_rsa_context *ctx,
                        int padding,
@@ -162,13 +167,6 @@
  * \brief          This function imports a set of core parameters into an
  *                 RSA context.
  *
- * \param ctx      The initialized RSA context to store the parameters in.
- * \param N        The RSA modulus, or NULL.
- * \param P        The first prime factor of \p N, or NULL.
- * \param Q        The second prime factor of \p N, or NULL.
- * \param D        The private exponent, or NULL.
- * \param E        The public exponent, or NULL.
- *
  * \note           This function can be called multiple times for successive
  *                 imports, if the parameters are not simultaneously present.
  *
@@ -184,7 +182,15 @@
  * \note           The imported parameters are copied and need not be preserved
  *                 for the lifetime of the RSA context being set up.
  *
- * \return         \c 0 on success, or a non-zero error code on failure.
+ * \param ctx      The initialized RSA context to store the parameters in.
+ * \param N        The RSA modulus, or NULL.
+ * \param P        The first prime factor of \p N, or NULL.
+ * \param Q        The second prime factor of \p N, or NULL.
+ * \param D        The private exponent, or NULL.
+ * \param E        The public exponent, or NULL.
+ *
+ * \return         \c 0 on success.
+ * \return         A non-zero error code on failure.
  */
 int mbedtls_rsa_import( mbedtls_rsa_context *ctx,
                         const mbedtls_mpi *N,
@@ -195,6 +201,21 @@
  * \brief          This function imports core RSA parameters, in raw big-endian
  *                 binary format, into an RSA context.
  *
+ * \note           This function can be called multiple times for successive
+ *                 imports, if the parameters are not simultaneously present.
+ *
+ *                 Any sequence of calls to this function should be followed
+ *                 by a call to mbedtls_rsa_complete(), which checks and
+ *                 completes the provided information to a ready-for-use
+ *                 public or private RSA key.
+ *
+ * \note           See mbedtls_rsa_complete() for more information on which
+ *                 parameters are necessary to set up a private or public
+ *                 RSA key.
+ *
+ * \note           The imported parameters are copied and need not be preserved
+ *                 for the lifetime of the RSA context being set up.
+ *
  * \param ctx      The initialized RSA context to store the parameters in.
  * \param N        The RSA modulus, or NULL.
  * \param N_len    The Byte length of \p N, ignored if \p N == NULL.
@@ -207,22 +228,8 @@
  * \param E        The public exponent, or NULL.
  * \param E_len    The Byte length of \p E, ignored if \p E == NULL.
  *
- * \note           This function can be called multiple times for successive
- *                 imports, if the parameters are not simultaneously present.
- *
- *                 Any sequence of calls to this function should be followed
- *                 by a call to mbedtls_rsa_complete(), which checks and
- *                 completes the provided information to a ready-for-use
- *                 public or private RSA key.
- *
- * \note           See mbedtls_rsa_complete() for more information on which
- *                 parameters are necessary to set up a private or public
- *                 RSA key.
- *
- * \note           The imported parameters are copied and need not be preserved
- *                 for the lifetime of the RSA context being set up.
- *
- * \return         \c 0 on success, or a non-zero error code on failure.
+ * \return         \c 0 on success.
+ * \return         A non-zero error code on failure.
  */
 int mbedtls_rsa_import_raw( mbedtls_rsa_context *ctx,
                             unsigned char const *N, size_t N_len,
@@ -250,17 +257,18 @@
  *                 the RSA context can be used for RSA operations without
  *                 the risk of failure or crash.
  *
- * \param ctx      The initialized RSA context holding imported parameters.
- *
- * \return         \c 0 on success, or #MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the
- *                 attempted derivations failed.
- *
  * \warning        This function need not perform consistency checks
  *                 for the imported parameters. In particular, parameters that
  *                 are not needed by the implementation might be silently
  *                 discarded and left unchecked. To check the consistency
  *                 of the key material, see mbedtls_rsa_check_privkey().
  *
+ * \param ctx      The initialized RSA context holding imported parameters.
+ *
+ * \return         \c 0 on success.
+ * \return         #MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the attempted derivations
+ *                 failed.
+ *
  */
 int mbedtls_rsa_complete( mbedtls_rsa_context *ctx );
 
@@ -292,11 +300,11 @@
  * \param D        The MPI to hold the private exponent, or NULL.
  * \param E        The MPI to hold the public exponent, or NULL.
  *
- * \return         \c 0 on success,
- *                 #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the
+ * \return         \c 0 on success.
+ * \return         #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the
  *                 requested parameters cannot be done due to missing
- *                 functionality or because of security policies,
- *                 or a non-zero return code on any other failure.
+ *                 functionality or because of security policies.
+ * \return         A non-zero return code on any other failure.
  *
  */
 int mbedtls_rsa_export( const mbedtls_rsa_context *ctx,
@@ -324,6 +332,9 @@
  *                 If the function fails due to an unsupported operation,
  *                 the RSA context stays intact and remains usable.
  *
+ * \note           The length parameters are ignored if the corresponding
+ *                 buffer pointers are NULL.
+ *
  * \param ctx      The initialized RSA context.
  * \param N        The Byte array to store the RSA modulus, or NULL.
  * \param N_len    The size of the buffer for the modulus.
@@ -331,21 +342,18 @@
  *                 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.
  * \param E        The Byte array to hold the public exponent, or NULL.
  * \param E_len    The size of the buffer for the public exponent.
  *
- * \note           The length fields are ignored if the corresponding
- *                 buffer pointers are NULL.
- *
- * \return         \c 0 on success,
- *                 #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the
+ * \return         \c 0 on success.
+ * \return         #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the
  *                 requested parameters cannot be done due to missing
- *                 functionality or because of security policies,
- *                 or a non-zero return code on any other failure.
+ *                 functionality or because of security policies.
+ * \return         A non-zero return code on any other failure.
  */
 int mbedtls_rsa_export_raw( const mbedtls_rsa_context *ctx,
                             unsigned char *N, size_t N_len,
@@ -357,16 +365,17 @@
 /**
  * \brief          This function exports CRT parameters of a private RSA key.
  *
+ * \note           Alternative RSA implementations not using CRT-parameters
+ *                 internally can implement this function based on
+ *                 mbedtls_rsa_deduce_opt().
+ *
  * \param ctx      The initialized RSA context.
  * \param DP       The MPI to hold D modulo P-1, or NULL.
  * \param DQ       The MPI to hold D modulo Q-1, or NULL.
  * \param QP       The MPI to hold modular inverse of Q modulo P, or NULL.
  *
- * \return         \c 0 on success, non-zero error code otherwise.
- *
- * \note           Alternative RSA implementations not using CRT-parameters
- *                 internally can implement this function based on
- *                 mbedtls_rsa_deduce_opt().
+ * \return         \c 0 on success.
+ * \return         A non-zero error code on failure.
  *
  */
 int mbedtls_rsa_export_crt( const mbedtls_rsa_context *ctx,
@@ -397,17 +406,17 @@
 /**
  * \brief          This function generates an RSA keypair.
  *
- * \param ctx      The RSA context used to hold the key.
- * \param f_rng    The RNG function.
- * \param p_rng    The RNG parameter.
- * \param nbits    The size of the public key in bits.
- * \param exponent The public exponent. For example, 65537.
- *
  * \note           mbedtls_rsa_init() must be called before this function,
  *                 to set up the RSA context.
  *
- * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
-                   on failure.
+ * \param ctx      The RSA context used to hold the key.
+ * \param f_rng    The RNG function.
+ * \param p_rng    The RNG context.
+ * \param nbits    The size of the public key in bits.
+ * \param exponent The public exponent. For example, 65537.
+ *
+ * \return         \c 0 on success.
+ * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
  */
 int mbedtls_rsa_gen_key( mbedtls_rsa_context *ctx,
                          int (*f_rng)(void *, unsigned char *, size_t),
@@ -424,8 +433,8 @@
  *
  * \param ctx      The RSA context to check.
  *
- * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
- *                 on failure.
+ * \return         \c 0 on success.
+ * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
  *
  */
 int mbedtls_rsa_check_pubkey( const mbedtls_rsa_context *ctx );
@@ -434,11 +443,6 @@
  * \brief      This function checks if a context contains an RSA private key
  *             and perform basic consistency checks.
  *
- * \param ctx  The RSA context to check.
- *
- * \return     \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code on
- *             failure.
- *
  * \note       The consistency checks performed by this function not only
  *             ensure that mbedtls_rsa_private() can be called successfully
  *             on the given context, but that the various parameters are
@@ -465,6 +469,11 @@
  *             user to ensure the trustworthiness of the source of his RSA
  *             parameters, which goes beyond what is effectively checkable
  *             by the library.</li></ul>
+ *
+ * \param ctx  The RSA context to check.
+ *
+ * \return     \c 0 on success.
+ * \return     An \c MBEDTLS_ERR_RSA_XXX error code on failure.
  */
 int mbedtls_rsa_check_privkey( const mbedtls_rsa_context *ctx );
 
@@ -476,8 +485,8 @@
  * \param pub      The RSA context holding the public key.
  * \param prv      The RSA context holding the private key.
  *
- * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
- *                 on failure.
+ * \return         \c 0 on success.
+ * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
  */
 int mbedtls_rsa_check_pub_priv( const mbedtls_rsa_context *pub,
                                 const mbedtls_rsa_context *prv );
@@ -485,13 +494,6 @@
 /**
  * \brief          This function performs an RSA public key operation.
  *
- * \param ctx      The RSA context.
- * \param input    The input buffer.
- * \param output   The output buffer.
- *
- * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
- *                 on failure.
- *
  * \note           This function does not handle message padding.
  *
  * \note           Make sure to set \p input[0] = 0 or ensure that
@@ -499,6 +501,13 @@
  *
  * \note           The input and output buffers must be large
  *                 enough. For example, 128 Bytes if RSA-1024 is used.
+ *
+ * \param ctx      The RSA context.
+ * \param input    The input buffer.
+ * \param output   The output buffer.
+ *
+ * \return         \c 0 on success.
+ * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
  */
 int mbedtls_rsa_public( mbedtls_rsa_context *ctx,
                 const unsigned char *input,
@@ -507,17 +516,29 @@
 /**
  * \brief          This function performs an RSA private key operation.
  *
+ * \note           The input and output buffers must be large
+ *                 enough. For example, 128 Bytes if RSA-1024 is used.
+ *
+ * \note           Blinding is used if and only if a PRNG is provided.
+ *
+ * \note           If blinding is used, both the base of exponentation
+ *                 and the exponent are blinded, providing protection
+ *                 against some side-channel attacks.
+ *
+ * \warning        It is deprecated and a security risk to not provide
+ *                 a PRNG here and thereby prevent the use of blinding.
+ *                 Future versions of the library may enforce the presence
+ *                 of a PRNG.
+ *
  * \param ctx      The RSA context.
  * \param f_rng    The RNG function. Needed for blinding.
- * \param p_rng    The RNG parameter.
+ * \param p_rng    The RNG context.
  * \param input    The input buffer.
  * \param output   The output buffer.
  *
- * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
- *                 on failure.
+ * \return         \c 0 on success.
+ * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
  *
- * \note           The input and output buffers must be large
- *                 enough. For example, 128 Bytes if RSA-1024 is used.
  */
 int mbedtls_rsa_private( mbedtls_rsa_context *ctx,
                  int (*f_rng)(void *, unsigned char *, size_t),
@@ -532,15 +553,8 @@
  *                 It is the generic wrapper for performing a PKCS#1 encryption
  *                 operation using the \p mode from the context.
  *
- *
- * \param ctx      The RSA context.
- * \param f_rng    The RNG function. Needed for padding, PKCS#1 v2.1
- *                 encoding, and #MBEDTLS_RSA_PRIVATE.
- * \param p_rng    The RNG parameter.
- * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
- * \param ilen     The length of the plaintext.
- * \param input    The buffer holding the data to encrypt.
- * \param output   The buffer used to hold the ciphertext.
+ * \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.
  *
  * \deprecated     It is deprecated and discouraged to call this function
  *                 in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
@@ -551,11 +565,17 @@
  *                 mode being set to #MBEDTLS_RSA_PRIVATE and might instead
  *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
- *                 on failure.
+ * \param ctx      The RSA context.
+ * \param f_rng    The RNG function. Needed for padding, PKCS#1 v2.1
+ *                 encoding, and #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng    The RNG context.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param ilen     The length of the plaintext.
+ * \param input    The buffer holding the data to encrypt.
+ * \param output   The buffer used to hold the ciphertext.
  *
- * \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.
+ * \return         \c 0 on success.
+ * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
  */
 int mbedtls_rsa_pkcs1_encrypt( mbedtls_rsa_context *ctx,
                        int (*f_rng)(void *, unsigned char *, size_t),
@@ -568,14 +588,8 @@
  * \brief          This function performs a PKCS#1 v1.5 encryption operation
  *                 (RSAES-PKCS1-v1_5-ENCRYPT).
  *
- * \param ctx      The RSA context.
- * \param f_rng    The RNG function. Needed for padding and
- *                 #MBEDTLS_RSA_PRIVATE.
- * \param p_rng    The RNG parameter.
- * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
- * \param ilen     The length of the plaintext.
- * \param input    The buffer holding the data to encrypt.
- * \param output   The buffer used to hold the ciphertext.
+ * \note           The output 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_PRIVATE mode. Future versions of the library
@@ -586,11 +600,17 @@
  *                 mode being set to #MBEDTLS_RSA_PRIVATE and might instead
  *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
- *                 on failure.
+ * \param ctx      The RSA context.
+ * \param f_rng    The RNG function. Needed for padding and
+ *                 #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng    The RNG context.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param ilen     The length of the plaintext.
+ * \param input    The buffer holding the data to encrypt.
+ * \param output   The buffer used to hold the ciphertext.
  *
- * \note           The output buffer must be as large as the size
- *                 of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
+ * \return         \c 0 on success.
+ * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
  */
 int mbedtls_rsa_rsaes_pkcs1_v15_encrypt( mbedtls_rsa_context *ctx,
                                  int (*f_rng)(void *, unsigned char *, size_t),
@@ -603,10 +623,22 @@
  * \brief            This function performs a PKCS#1 v2.1 OAEP encryption
  *                   operation (RSAES-OAEP-ENCRYPT).
  *
+ * \note             The output buffer must be as large as the size
+ *                   of ctx->N. For example, 128 Bytes if RSA-1024 is used.
+ *
+ * \deprecated       It is deprecated and discouraged to call this function
+ *                   in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
+ *                   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.
- * \param p_rng      The RNG parameter.
+ * \param p_rng      The RNG context.
  * \param mode       #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
  * \param label      The buffer holding the custom label to use.
  * \param label_len  The length of the label.
@@ -614,20 +646,8 @@
  * \param input      The buffer holding the data to encrypt.
  * \param output     The buffer used to hold the ciphertext.
  *
- * \deprecated     It is deprecated and discouraged to call this function
- *                 in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
- *                 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.
- *
- * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
- *                 on failure.
- *
- * \note           The output buffer must be as large as the size
- *                 of ctx->N. For example, 128 Bytes if RSA-1024 is used.
+ * \return           \c 0 on success.
+ * \return           An \c MBEDTLS_ERR_RSA_XXX error code on failure.
  */
 int mbedtls_rsa_rsaes_oaep_encrypt( mbedtls_rsa_context *ctx,
                             int (*f_rng)(void *, unsigned char *, size_t),
@@ -645,14 +665,15 @@
  *                 It is the generic wrapper for performing a PKCS#1 decryption
  *                 operation using the \p mode from the context.
  *
- * \param ctx      The RSA context.
- * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
- * \param p_rng    The RNG parameter.
- * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
- * \param olen     The length of the plaintext.
- * \param input    The buffer holding the encrypted data.
- * \param output   The buffer used to hold the plaintext.
- * \param output_max_len    The maximum length of the output buffer.
+ * \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 \c 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.
  *
  * \deprecated     It is deprecated and discouraged to call this function
  *                 in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
@@ -663,18 +684,17 @@
  *                 mode being set to #MBEDTLS_RSA_PUBLIC and might instead
  *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
- *                 on failure.
+ * \param ctx      The RSA context.
+ * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng    The RNG context.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param olen     The length of the plaintext.
+ * \param input    The buffer holding the encrypted data.
+ * \param output   The buffer used to hold the plaintext.
+ * \param output_max_len    The maximum length of the output buffer.
  *
- * \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 \c 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.
+ * \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),
@@ -688,14 +708,15 @@
  * \brief          This function performs a PKCS#1 v1.5 decryption
  *                 operation (RSAES-PKCS1-v1_5-DECRYPT).
  *
- * \param ctx      The RSA context.
- * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
- * \param p_rng    The RNG parameter.
- * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
- * \param olen     The length of the plaintext.
- * \param input    The buffer holding the encrypted data.
- * \param output   The buffer to hold the plaintext.
- * \param output_max_len    The maximum length of the output buffer.
+ * \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.
  *
  * \deprecated     It is deprecated and discouraged to call this function
  *                 in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
@@ -706,18 +727,18 @@
  *                 mode being set to #MBEDTLS_RSA_PUBLIC and might instead
  *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
- *                 on failure.
+ * \param ctx      The RSA context.
+ * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng    The RNG context.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param olen     The length of the plaintext.
+ * \param input    The buffer holding the encrypted data.
+ * \param output   The buffer to hold the plaintext.
+ * \param output_max_len    The maximum length of the output buffer.
  *
- * \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.
+ * \return         \c 0 on success.
+ * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
  *
- * \note           The input buffer must be as large as the size
- *                 of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
  */
 int mbedtls_rsa_rsaes_pkcs1_v15_decrypt( mbedtls_rsa_context *ctx,
                                  int (*f_rng)(void *, unsigned char *, size_t),
@@ -728,12 +749,32 @@
                                  size_t output_max_len );
 
 /**
- * \brief          This function performs a PKCS#1 v2.1 OAEP decryption
- *                 operation (RSAES-OAEP-DECRYPT).
+ * \brief            This function performs a PKCS#1 v2.1 OAEP decryption
+ *                   operation (RSAES-OAEP-DECRYPT).
+ *
+ * \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.
+ *
+ * \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 parameter.
+ * \param p_rng      The RNG context.
  * \param mode       #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
  * \param label      The buffer holding the custom label to use.
  * \param label_len  The length of the label.
@@ -742,28 +783,8 @@
  * \param output     The buffer to hold the plaintext.
  * \param output_max_len    The maximum length of the output buffer.
  *
- * \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.
- *
- * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
- *                 on failure.
- *
- * \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.
+ * \return         \c 0 on success.
+ * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
  */
 int mbedtls_rsa_rsaes_oaep_decrypt( mbedtls_rsa_context *ctx,
                             int (*f_rng)(void *, unsigned char *, size_t),
@@ -782,16 +803,12 @@
  *                 It is the generic wrapper for performing a PKCS#1
  *                 signature using the \p mode from the context.
  *
- * \param ctx      The RSA context.
- * \param f_rng    The RNG function. Needed for PKCS#1 v2.1 encoding and for
- *                 #MBEDTLS_RSA_PRIVATE.
- * \param p_rng    The RNG parameter.
- * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
- * \param md_alg   The message-digest algorithm used to hash the original data.
- *                 Use #MBEDTLS_MD_NONE for signing raw data.
- * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
- * \param hash     The buffer holding the message digest.
- * \param sig      The buffer to hold the ciphertext.
+ * \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.
+ *
+ * \note           For PKCS#1 v2.1 encoding, see comments on
+ *                 mbedtls_rsa_rsassa_pss_sign() for details on
+ *                 \p md_alg and \p hash_id.
  *
  * \deprecated     It is deprecated and discouraged to call this function
  *                 in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
@@ -802,15 +819,19 @@
  *                 mode being set to #MBEDTLS_RSA_PUBLIC and might instead
  *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         \c 0 if the signing operation was successful,
- *                 or an \c MBEDTLS_ERR_RSA_XXX error code on failure.
+ * \param ctx      The RSA context.
+ * \param f_rng    The RNG function. Needed for PKCS#1 v2.1 encoding and for
+ *                 #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng    The RNG context.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param md_alg   The message-digest algorithm used to hash the original data.
+ *                 Use #MBEDTLS_MD_NONE for signing raw data.
+ * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash     The buffer holding the message digest.
+ * \param sig      The buffer to hold the ciphertext.
  *
- * \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.
- *
- * \note           For PKCS#1 v2.1 encoding, see comments on
- *                 mbedtls_rsa_rsassa_pss_sign() for details on
- *                 \p md_alg and \p hash_id.
+ * \return         \c 0 if the signing operation was successful.
+ * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
  */
 int mbedtls_rsa_pkcs1_sign( mbedtls_rsa_context *ctx,
                     int (*f_rng)(void *, unsigned char *, size_t),
@@ -825,15 +846,8 @@
  * \brief          This function performs a PKCS#1 v1.5 signature
  *                 operation (RSASSA-PKCS1-v1_5-SIGN).
  *
- * \param ctx      The RSA context.
- * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
- * \param p_rng    The RNG parameter.
- * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
- * \param md_alg   The message-digest algorithm used to hash the original data.
- *                 Use #MBEDTLS_MD_NONE for signing raw data.
- * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
- * \param hash     The buffer holding the message digest.
- * \param sig      The buffer to hold the ciphertext.
+ * \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.
  *
  * \deprecated     It is deprecated and discouraged to call this function
  *                 in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
@@ -844,12 +858,18 @@
  *                 mode being set to #MBEDTLS_RSA_PUBLIC and might instead
  *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         \c 0 if the signing operation was successful,
- *                 or an \c MBEDTLS_ERR_RSA_XXX error code
- *                 on failure.
+ * \param ctx      The RSA context.
+ * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng    The RNG context.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param md_alg   The message-digest algorithm used to hash the original data.
+ *                 Use #MBEDTLS_MD_NONE for signing raw data.
+ * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash     The buffer holding the message digest.
+ * \param sig      The buffer to hold the ciphertext.
  *
- * \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.
+ * \return         \c 0 if the signing operation was successful.
+ * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
  */
 int mbedtls_rsa_rsassa_pkcs1_v15_sign( mbedtls_rsa_context *ctx,
                                int (*f_rng)(void *, unsigned char *, size_t),
@@ -864,16 +884,15 @@
  * \brief          This function performs a PKCS#1 v2.1 PSS signature
  *                 operation (RSASSA-PSS-SIGN).
  *
- * \param ctx      The RSA context.
- * \param f_rng    The RNG function. Needed for PKCS#1 v2.1 encoding and for
- *                 #MBEDTLS_RSA_PRIVATE.
- * \param p_rng    The RNG parameter.
- * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
- * \param md_alg   The message-digest algorithm used to hash the original data.
- *                 Use #MBEDTLS_MD_NONE for signing raw data.
- * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
- * \param hash     The buffer holding the message digest.
- * \param sig      The buffer to hold the ciphertext.
+ * \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.
+ *
+ * \note           The \p hash_id in the RSA context is the one used for the
+ *                 encoding. \p md_alg in the function call is the type of hash
+ *                 that is encoded. According to <em>RFC-3447: Public-Key
+ *                 Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography
+ *                 Specifications</em> it is advised to keep both hashes the
+ *                 same.
  *
  * \deprecated     It is deprecated and discouraged to call this function
  *                 in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
@@ -884,19 +903,19 @@
  *                 mode being set to #MBEDTLS_RSA_PUBLIC and might instead
  *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         \c 0 if the signing operation was successful,
- *                 or an \c MBEDTLS_ERR_RSA_XXX error code
- *                 on failure.
+ * \param ctx      The RSA context.
+ * \param f_rng    The RNG function. Needed for PKCS#1 v2.1 encoding and for
+ *                 #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng    The RNG context.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param md_alg   The message-digest algorithm used to hash the original data.
+ *                 Use #MBEDTLS_MD_NONE for signing raw data.
+ * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash     The buffer holding the message digest.
+ * \param sig      The buffer to hold the ciphertext.
  *
- * \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.
- *
- * \note           The \p hash_id in the RSA context is the one used for the
- *                 encoding. \p md_alg in the function call is the type of hash
- *                 that is encoded. According to <em>RFC-3447: Public-Key
- *                 Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography
- *                 Specifications</em> it is advised to keep both hashes the
- *                 same.
+ * \return         \c 0 if the signing operation was successful.
+ * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
  */
 int mbedtls_rsa_rsassa_pss_sign( mbedtls_rsa_context *ctx,
                          int (*f_rng)(void *, unsigned char *, size_t),
@@ -914,15 +933,12 @@
  *                 This is the generic wrapper for performing a PKCS#1
  *                 verification using the mode from the context.
  *
- * \param ctx      The RSA public key context.
- * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
- * \param p_rng    The RNG parameter.
- * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
- * \param md_alg   The message-digest algorithm used to hash the original data.
- *                 Use #MBEDTLS_MD_NONE for signing raw data.
- * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
- * \param hash     The buffer holding the message digest.
- * \param sig      The buffer holding the ciphertext.
+ * \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.
+ *
+ * \note           For PKCS#1 v2.1 encoding, see comments on
+ *                 mbedtls_rsa_rsassa_pss_verify() about \p md_alg and
+ *                 \p hash_id.
  *
  * \deprecated     It is deprecated and discouraged to call this function
  *                 in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
@@ -933,16 +949,18 @@
  *                 mode being set to #MBEDTLS_RSA_PRIVATE and might instead
  *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         \c 0 if the verify operation was successful,
- *                 or an \c MBEDTLS_ERR_RSA_XXX error code
- *                 on failure.
+ * \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.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param md_alg   The message-digest algorithm used to hash the original data.
+ *                 Use #MBEDTLS_MD_NONE for signing raw data.
+ * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash     The buffer holding the message digest.
+ * \param sig      The buffer holding the ciphertext.
  *
- * \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.
- *
- * \note           For PKCS#1 v2.1 encoding, see comments on
- *                 mbedtls_rsa_rsassa_pss_verify() about \p md_alg and
- *                 \p hash_id.
+ * \return         \c 0 if the verify operation was successful.
+ * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
  */
 int mbedtls_rsa_pkcs1_verify( mbedtls_rsa_context *ctx,
                       int (*f_rng)(void *, unsigned char *, size_t),
@@ -957,15 +975,8 @@
  * \brief          This function performs a PKCS#1 v1.5 verification
  *                 operation (RSASSA-PKCS1-v1_5-VERIFY).
  *
- * \param ctx      The RSA public key context.
- * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
- * \param p_rng    The RNG parameter.
- * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
- * \param md_alg   The message-digest algorithm used to hash the original data.
- *                 Use #MBEDTLS_MD_NONE for signing raw data.
- * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
- * \param hash     The buffer holding the message digest.
- * \param sig      The buffer holding the ciphertext.
+ * \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.
  *
  * \deprecated     It is deprecated and discouraged to call this function
  *                 in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
@@ -976,12 +987,18 @@
  *                 mode being set to #MBEDTLS_RSA_PRIVATE and might instead
  *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         \c 0 if the verify operation was successful,
- *                 or an \c MBEDTLS_ERR_RSA_XXX error code
- *                 on failure.
+ * \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.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param md_alg   The message-digest algorithm used to hash the original data.
+ *                 Use #MBEDTLS_MD_NONE for signing raw data.
+ * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash     The buffer holding the message digest.
+ * \param sig      The buffer holding the ciphertext.
  *
- * \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.
+ * \return         \c 0 if the verify operation was successful.
+ * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
  */
 int mbedtls_rsa_rsassa_pkcs1_v15_verify( mbedtls_rsa_context *ctx,
                                  int (*f_rng)(void *, unsigned char *, size_t),
@@ -999,29 +1016,6 @@
  *                 The hash function for the MGF mask generating function
  *                 is that specified in the RSA context.
  *
- * \param ctx      The RSA public key context.
- * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
- * \param p_rng    The RNG parameter.
- * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
- * \param md_alg   The message-digest algorithm used to hash the original data.
- *                 Use #MBEDTLS_MD_NONE for signing raw data.
- * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
- * \param hash     The buffer holding the message digest.
- * \param sig      The buffer holding the ciphertext.
- *
- * \deprecated     It is deprecated and discouraged to call this function
- *                 in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
- *                 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.
- *
- * \return         \c 0 if the verify operation was successful,
- *                 or an \c MBEDTLS_ERR_RSA_XXX error code
- *                 on failure.
- *
  * \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.
  *
@@ -1032,6 +1026,28 @@
  *                 Specifications</em> it is advised to keep both hashes the
  *                 same. If \p hash_id in the RSA context is unset,
  *                 the \p md_alg from the function call is used.
+ *
+ * \deprecated     It is deprecated and discouraged to call this function
+ *                 in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
+ *                 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.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param md_alg   The message-digest algorithm used to hash the original data.
+ *                 Use #MBEDTLS_MD_NONE for signing raw data.
+ * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash     The buffer holding the message digest.
+ * \param sig      The buffer holding the ciphertext.
+ *
+ * \return         \c 0 if the verify operation was successful.
+ * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
  */
 int mbedtls_rsa_rsassa_pss_verify( mbedtls_rsa_context *ctx,
                            int (*f_rng)(void *, unsigned char *, size_t),
@@ -1049,27 +1065,27 @@
  *                 The hash function for the MGF mask generating function
  *                 is that specified in \p mgf1_hash_id.
  *
- * \param ctx      The RSA public key context.
- * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
- * \param p_rng    The RNG parameter.
- * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
- * \param md_alg   The message-digest algorithm used to hash the original data.
- *                 Use #MBEDTLS_MD_NONE for signing raw data.
- * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
- * \param hash     The buffer holding the message digest.
- * \param mgf1_hash_id The message digest used for mask generation.
- * \param expected_salt_len The length of the salt used in padding. Use
- *                 #MBEDTLS_RSA_SALT_LEN_ANY to accept any salt length.
- * \param sig      The buffer holding the ciphertext.
- *
- * \return         \c 0 if the verify operation was successful,
- *                 or an \c MBEDTLS_ERR_RSA_XXX error code
- *                 on failure.
- *
  * \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.
  *
  * \note           The \p hash_id in the RSA context is ignored.
+ *
+ * \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.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param md_alg   The message-digest algorithm used to hash the original data.
+ *                 Use #MBEDTLS_MD_NONE for signing raw data.
+ * \param hashlen  The length of the message digest. Only used if \p md_alg is
+ *                 #MBEDTLS_MD_NONE.
+ * \param hash     The buffer holding the message digest.
+ * \param mgf1_hash_id       The message digest used for mask generation.
+ * \param expected_salt_len  The length of the salt used in padding. Use
+ *                           #MBEDTLS_RSA_SALT_LEN_ANY to accept any salt length.
+ * \param sig      The buffer holding the ciphertext.
+ *
+ * \return         \c 0 if the verify operation was successful.
+ * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
  */
 int mbedtls_rsa_rsassa_pss_verify_ext( mbedtls_rsa_context *ctx,
                                int (*f_rng)(void *, unsigned char *, size_t),
@@ -1088,8 +1104,8 @@
  * \param dst      The destination context.
  * \param src      The source context.
  *
- * \return         \c 0 on success,
- *                 #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure.
+ * \return         \c 0 on success.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure.
  */
 int mbedtls_rsa_copy( mbedtls_rsa_context *dst, const mbedtls_rsa_context *src );
 
@@ -1100,22 +1116,11 @@
  */
 void mbedtls_rsa_free( mbedtls_rsa_context *ctx );
 
-#ifdef __cplusplus
-}
-#endif
-
-#else  /* MBEDTLS_RSA_ALT */
-#include "rsa_alt.h"
-#endif /* MBEDTLS_RSA_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
 /**
  * \brief          The RSA checkup routine.
  *
- * \return         \c 0 on success, or \c 1 on failure.
+ * \return         \c 0 on success.
+ * \return         \c 1 on failure.
  */
 int mbedtls_rsa_self_test( int verbose );
 
diff --git a/include/mbedtls/rsa_internal.h b/include/mbedtls/rsa_internal.h
index bcb3c94..53abd3c 100644
--- a/include/mbedtls/rsa_internal.h
+++ b/include/mbedtls/rsa_internal.h
@@ -2,6 +2,37 @@
  * \file rsa_internal.h
  *
  * \brief Context-independent RSA helper functions
+ *
+ *  This module declares some RSA-related helper functions useful when
+ *  implementing the RSA interface. These functions are provided in a separate
+ *  compilation unit in order to make it easy for designers of alternative RSA
+ *  implementations to use them in their own code, as it is conceived that the
+ *  functionality they provide will be necessary for most complete
+ *  implementations.
+ *
+ *  End-users of Mbed TLS who are not providing their own alternative RSA
+ *  implementations should not use these functions directly, and should instead
+ *  use only the functions declared in rsa.h.
+ *
+ *  The interface provided by this module will be maintained through LTS (Long
+ *  Term Support) branches of Mbed TLS, but may otherwise be subject to change,
+ *  and must be considered an internal interface of the library.
+ *
+ *  There are two classes of helper functions:
+ *
+ *  (1) Parameter-generating helpers. These are:
+ *      - mbedtls_rsa_deduce_primes
+ *      - mbedtls_rsa_deduce_private_exponent
+ *      - mbedtls_rsa_deduce_crt
+ *       Each of these functions takes a set of core RSA parameters and
+ *       generates some other, or CRT related parameters.
+ *
+ *  (2) Parameter-checking helpers. These are:
+ *      - mbedtls_rsa_validate_params
+ *      - mbedtls_rsa_validate_crt
+ *      They take a set of core or CRT related RSA parameters and check their
+ *      validity.
+ *
  */
 /*
  *  Copyright (C) 2006-2017, ARM Limited, All Rights Reserved
@@ -21,31 +52,6 @@
  *
  *  This file is part of mbed TLS (https://tls.mbed.org)
  *
- *
- *  This file declares some RSA-related helper functions useful when
- *  implementing the RSA interface. They are public and provided in a
- *  separate compilation unit in order to make it easy for designers of
- *  alternative RSA implementations to use them in their code, as it is
- *  conceived that the functionality they provide will be necessary
- *  for most complete implementations.
- *
- *  End-users of Mbed TLS not intending to re-implement the RSA functionality
- *  are not expected to get into the need of making use of these functions directly,
- *  but instead should be able to use the functions declared in rsa.h.
- *
- *  There are two classes of helper functions:
- *  (1) Parameter-generating helpers. These are:
- *      - mbedtls_rsa_deduce_primes
- *      - mbedtls_rsa_deduce_private_exponent
- *      - mbedtls_rsa_deduce_crt
- *       Each of these functions takes a set of core RSA parameters
- *       and generates some other, or CRT related parameters.
- *  (2) Parameter-checking helpers. These are:
- *      - mbedtls_rsa_validate_params
- *      - mbedtls_rsa_validate_crt
- *      They take a set of core or CRT related RSA parameters
- *      and check their validity.
- *
  */
 
 #ifndef MBEDTLS_RSA_INTERNAL_H
@@ -213,4 +219,8 @@
                               const mbedtls_mpi *D,  const mbedtls_mpi *DP,
                               const mbedtls_mpi *DQ, const mbedtls_mpi *QP );
 
+#ifdef __cplusplus
+}
+#endif
+
 #endif /* rsa_internal.h */
diff --git a/include/mbedtls/sha1.h b/include/mbedtls/sha1.h
index 05540cd..65a124c 100644
--- a/include/mbedtls/sha1.h
+++ b/include/mbedtls/sha1.h
@@ -1,7 +1,10 @@
 /**
  * \file sha1.h
  *
- * \brief The SHA-1 cryptographic hash function.
+ * \brief This file contains SHA-1 definitions and functions.
+ *
+ * The Secure Hash Algorithm 1 (SHA-1) cryptographic hash function is defined in
+ * <em>FIPS 180-4: Secure Hash Standard (SHS)</em>.
  *
  * \warning   SHA-1 is considered a weak message digest and its use constitutes
  *            a security risk. We recommend considering stronger message
@@ -39,14 +42,14 @@
 
 #define MBEDTLS_ERR_SHA1_HW_ACCEL_FAILED                  -0x0035  /**< SHA-1 hardware accelerator failed */
 
-#if !defined(MBEDTLS_SHA1_ALT)
-// Regular implementation
-//
-
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+#if !defined(MBEDTLS_SHA1_ALT)
+// Regular implementation
+//
+
 /**
  * \brief          The SHA-1 context structure.
  *
@@ -63,40 +66,44 @@
 }
 mbedtls_sha1_context;
 
+#else  /* MBEDTLS_SHA1_ALT */
+#include "sha1_alt.h"
+#endif /* MBEDTLS_SHA1_ALT */
+
 /**
  * \brief          This function initializes a SHA-1 context.
  *
- * \param ctx      The SHA-1 context to initialize.
- *
  * \warning        SHA-1 is considered a weak message digest and its use
  *                 constitutes a security risk. We recommend considering
  *                 stronger message digests instead.
  *
+ * \param ctx      The SHA-1 context to initialize.
+ *
  */
 void mbedtls_sha1_init( mbedtls_sha1_context *ctx );
 
 /**
  * \brief          This function clears a SHA-1 context.
  *
- * \param ctx      The SHA-1 context to clear.
- *
  * \warning        SHA-1 is considered a weak message digest and its use
  *                 constitutes a security risk. We recommend considering
  *                 stronger message digests instead.
  *
+ * \param ctx      The SHA-1 context to clear.
+ *
  */
 void mbedtls_sha1_free( mbedtls_sha1_context *ctx );
 
 /**
  * \brief          This function clones the state of a SHA-1 context.
  *
- * \param dst      The destination context.
- * \param src      The context to clone.
- *
  * \warning        SHA-1 is considered a weak message digest and its use
  *                 constitutes a security risk. We recommend considering
  *                 stronger message digests instead.
  *
+ * \param dst      The SHA-1 context to clone to.
+ * \param src      The SHA-1 context to clone from.
+ *
  */
 void mbedtls_sha1_clone( mbedtls_sha1_context *dst,
                          const mbedtls_sha1_context *src );
@@ -104,14 +111,14 @@
 /**
  * \brief          This function starts a SHA-1 checksum calculation.
  *
- * \param ctx      The context to initialize.
- *
- * \return         \c 0 if successful
- *
  * \warning        SHA-1 is considered a weak message digest and its use
  *                 constitutes a security risk. We recommend considering
  *                 stronger message digests instead.
  *
+ * \param ctx      The SHA-1 context to initialize.
+ *
+ * \return         \c 0 on success.
+ *
  */
 int mbedtls_sha1_starts_ret( mbedtls_sha1_context *ctx );
 
@@ -119,16 +126,15 @@
  * \brief          This function feeds an input buffer into an ongoing SHA-1
  *                 checksum calculation.
  *
- * \param ctx      The SHA-1 context.
- * \param input    The buffer holding the input data.
- * \param ilen     The length of the input data.
- *
- * \return         \c 0 if successful
- *
  * \warning        SHA-1 is considered a weak message digest and its use
  *                 constitutes a security risk. We recommend considering
  *                 stronger message digests instead.
  *
+ * \param ctx      The SHA-1 context.
+ * \param input    The buffer holding the input data.
+ * \param ilen     The length of the input data.
+ *
+ * \return         \c 0 on success.
  */
 int mbedtls_sha1_update_ret( mbedtls_sha1_context *ctx,
                              const unsigned char *input,
@@ -138,31 +144,30 @@
  * \brief          This function finishes the SHA-1 operation, and writes
  *                 the result to the output buffer.
  *
- * \param ctx      The SHA-1 context.
- * \param output   The SHA-1 checksum result.
- *
- * \return         \c 0 if successful
- *
  * \warning        SHA-1 is considered a weak message digest and its use
  *                 constitutes a security risk. We recommend considering
  *                 stronger message digests instead.
  *
+ * \param ctx      The SHA-1 context.
+ * \param output   The SHA-1 checksum result.
+ *
+ * \return         \c 0 on success.
  */
 int mbedtls_sha1_finish_ret( mbedtls_sha1_context *ctx,
                              unsigned char output[20] );
 
 /**
- * \brief          SHA-1 process data block (internal use only)
- *
- * \param ctx      SHA-1 context
- * \param data     The data block being processed.
- *
- * \return         \c 0 if successful
+ * \brief          SHA-1 process data block (internal use only).
  *
  * \warning        SHA-1 is considered a weak message digest and its use
  *                 constitutes a security risk. We recommend considering
  *                 stronger message digests instead.
  *
+ * \param ctx      The SHA-1 context.
+ * \param data     The data block being processed.
+ *
+ * \return         \c 0 on success.
+ *
  */
 int mbedtls_internal_sha1_process( mbedtls_sha1_context *ctx,
                                    const unsigned char data[64] );
@@ -174,65 +179,67 @@
 #define MBEDTLS_DEPRECATED
 #endif
 /**
- * \brief          SHA-1 context setup
- *
- * \deprecated     Superseded by mbedtls_sha1_starts_ret() in 2.7.0
- *
- * \param ctx      The SHA-1 context to be initialized.
+ * \brief          This function starts a SHA-1 checksum calculation.
  *
  * \warning        SHA-1 is considered a weak message digest and its use
  *                 constitutes a security risk. We recommend considering
  *                 stronger message digests instead.
  *
+ * \deprecated     Superseded by mbedtls_sha1_starts_ret() in 2.7.0.
+ *
+ * \param ctx      The SHA-1 context to initialize.
+ *
  */
 MBEDTLS_DEPRECATED void mbedtls_sha1_starts( mbedtls_sha1_context *ctx );
 
 /**
- * \brief          SHA-1 process buffer
- *
- * \deprecated     Superseded by mbedtls_sha1_update_ret() in 2.7.0
- *
- * \param ctx      The SHA-1 context.
- * \param input    The buffer holding the input data.
- * \param ilen     The length of the input data.
+ * \brief          This function feeds an input buffer into an ongoing SHA-1
+ *                 checksum calculation.
  *
  * \warning        SHA-1 is considered a weak message digest and its use
  *                 constitutes a security risk. We recommend considering
  *                 stronger message digests instead.
  *
+ * \deprecated     Superseded by mbedtls_sha1_update_ret() in 2.7.0.
+ *
+ * \param ctx      The SHA-1 context.
+ * \param input    The buffer holding the input data.
+ * \param ilen     The length of the input data.
+ *
  */
 MBEDTLS_DEPRECATED void mbedtls_sha1_update( mbedtls_sha1_context *ctx,
                                              const unsigned char *input,
                                              size_t ilen );
 
 /**
- * \brief          SHA-1 final digest
- *
- * \deprecated     Superseded by mbedtls_sha1_finish_ret() in 2.7.0
- *
- * \param ctx      The SHA-1 context.
- * \param output   The SHA-1 checksum result.
+ * \brief          This function finishes the SHA-1 operation, and writes
+ *                 the result to the output buffer.
  *
  * \warning        SHA-1 is considered a weak message digest and its use
  *                 constitutes a security risk. We recommend considering
  *                 stronger message digests instead.
  *
+ * \deprecated     Superseded by mbedtls_sha1_finish_ret() in 2.7.0.
+ *
+ * \param ctx      The SHA-1 context.
+ * \param output   The SHA-1 checksum result.
+ *
  */
 MBEDTLS_DEPRECATED void mbedtls_sha1_finish( mbedtls_sha1_context *ctx,
                                              unsigned char output[20] );
 
 /**
- * \brief          SHA-1 process data block (internal use only)
- *
- * \deprecated     Superseded by mbedtls_internal_sha1_process() in 2.7.0
- *
- * \param ctx      The SHA-1 context.
- * \param data     The data block being processed.
+ * \brief          SHA-1 process data block (internal use only).
  *
  * \warning        SHA-1 is considered a weak message digest and its use
  *                 constitutes a security risk. We recommend considering
  *                 stronger message digests instead.
  *
+ * \deprecated     Superseded by mbedtls_internal_sha1_process() in 2.7.0.
+ *
+ * \param ctx      The SHA-1 context.
+ * \param data     The data block being processed.
+ *
  */
 MBEDTLS_DEPRECATED void mbedtls_sha1_process( mbedtls_sha1_context *ctx,
                                               const unsigned char data[64] );
@@ -240,18 +247,6 @@
 #undef MBEDTLS_DEPRECATED
 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
 
-#ifdef __cplusplus
-}
-#endif
-
-#else  /* MBEDTLS_SHA1_ALT */
-#include "sha1_alt.h"
-#endif /* MBEDTLS_SHA1_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
 /**
  * \brief          This function calculates the SHA-1 checksum of a buffer.
  *
@@ -261,15 +256,15 @@
  *                 The SHA-1 result is calculated as
  *                 output = SHA-1(input buffer).
  *
+ * \warning        SHA-1 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  * \param input    The buffer holding the input data.
  * \param ilen     The length of the input data.
  * \param output   The SHA-1 checksum result.
  *
- * \return         \c 0 if successful
- *
- * \warning        SHA-1 is considered a weak message digest and its use
- *                 constitutes a security risk. We recommend considering
- *                 stronger message digests instead.
+ * \return         \c 0 on success.
  *
  */
 int mbedtls_sha1_ret( const unsigned char *input,
@@ -283,7 +278,17 @@
 #define MBEDTLS_DEPRECATED
 #endif
 /**
- * \brief          Output = SHA-1( input buffer )
+ * \brief          This function calculates the SHA-1 checksum of a buffer.
+ *
+ *                 The function allocates the context, performs the
+ *                 calculation, and frees the context.
+ *
+ *                 The SHA-1 result is calculated as
+ *                 output = SHA-1(input buffer).
+ *
+ * \warning        SHA-1 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
  *
  * \deprecated     Superseded by mbedtls_sha1_ret() in 2.7.0
  *
@@ -291,10 +296,6 @@
  * \param ilen     The length of the input data.
  * \param output   The SHA-1 checksum result.
  *
- * \warning        SHA-1 is considered a weak message digest and its use
- *                 constitutes a security risk. We recommend considering
- *                 stronger message digests instead.
- *
  */
 MBEDTLS_DEPRECATED void mbedtls_sha1( const unsigned char *input,
                                       size_t ilen,
@@ -306,12 +307,13 @@
 /**
  * \brief          The SHA-1 checkup routine.
  *
- * \return         \c 0 on success, or \c 1 on failure.
- *
  * \warning        SHA-1 is considered a weak message digest and its use
  *                 constitutes a security risk. We recommend considering
  *                 stronger message digests instead.
  *
+ * \return         \c 0 on success.
+ * \return         \c 1 on failure.
+ *
  */
 int mbedtls_sha1_self_test( int verbose );
 
diff --git a/include/mbedtls/sha256.h b/include/mbedtls/sha256.h
index ffb16c2..adf31a8 100644
--- a/include/mbedtls/sha256.h
+++ b/include/mbedtls/sha256.h
@@ -1,7 +1,10 @@
 /**
  * \file sha256.h
  *
- * \brief The SHA-224 and SHA-256 cryptographic hash function.
+ * \brief This file contains SHA-224 and SHA-256 definitions and functions.
+ *
+ * The Secure Hash Algorithms 224 and 256 (SHA-224 and SHA-256) cryptographic
+ * hash functions are defined in <em>FIPS 180-4: Secure Hash Standard (SHS)</em>.
  */
 /*
  *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
@@ -35,14 +38,14 @@
 
 #define MBEDTLS_ERR_SHA256_HW_ACCEL_FAILED                -0x0037  /**< SHA-256 hardware accelerator failed */
 
-#if !defined(MBEDTLS_SHA256_ALT)
-// Regular implementation
-//
-
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+#if !defined(MBEDTLS_SHA256_ALT)
+// Regular implementation
+//
+
 /**
  * \brief          The SHA-256 context structure.
  *
@@ -55,12 +58,15 @@
     uint32_t total[2];          /*!< The number of Bytes processed.  */
     uint32_t state[8];          /*!< The intermediate digest state.  */
     unsigned char buffer[64];   /*!< The data block being processed. */
-    int is224;                  /*!< Determines which function to use.
-                                     <ul><li>0: Use SHA-256.</li>
-                                     <li>1: Use SHA-224.</li></ul> */
+    int is224;                  /*!< Determines which function to use:
+                                     0: Use SHA-256, or 1: Use SHA-224. */
 }
 mbedtls_sha256_context;
 
+#else  /* MBEDTLS_SHA256_ALT */
+#include "sha256_alt.h"
+#endif /* MBEDTLS_SHA256_ALT */
+
 /**
  * \brief          This function initializes a SHA-256 context.
  *
@@ -89,9 +95,8 @@
  *                 calculation.
  *
  * \param ctx      The context to initialize.
- * \param is224    Determines which function to use.
- *                 <ul><li>0: Use SHA-256.</li>
- *                 <li>1: Use SHA-224.</li></ul>
+ * \param is224    Determines which function to use:
+ *                 0: Use SHA-256, or 1: Use SHA-224.
  *
  * \return         \c 0 on success.
  */
@@ -101,9 +106,9 @@
  * \brief          This function feeds an input buffer into an ongoing
  *                 SHA-256 checksum calculation.
  *
- * \param ctx      SHA-256 context
- * \param input    buffer holding the data
- * \param ilen     length of the input data
+ * \param ctx      The SHA-256 context.
+ * \param input    The buffer holding the data.
+ * \param ilen     The length of the input data.
  *
  * \return         \c 0 on success.
  */
@@ -143,14 +148,15 @@
 #define MBEDTLS_DEPRECATED
 #endif
 /**
- * \brief          This function starts a SHA-256 checksum calculation.
+ * \brief          This function starts a SHA-224 or SHA-256 checksum
+ *                 calculation.
+ *
  *
  * \deprecated     Superseded by mbedtls_sha256_starts_ret() in 2.7.0.
  *
- * \param ctx      The SHA-256 context to initialize.
- * \param is224    Determines which function to use.
- *                 <ul><li>0: Use SHA-256.</li>
- *                 <li>1: Use SHA-224.</li></ul>
+ * \param ctx      The context to initialize.
+ * \param is224    Determines which function to use:
+ *                 0: Use SHA-256, or 1: Use SHA-224.
  */
 MBEDTLS_DEPRECATED void mbedtls_sha256_starts( mbedtls_sha256_context *ctx,
                                                int is224 );
@@ -176,7 +182,7 @@
  * \deprecated     Superseded by mbedtls_sha256_finish_ret() in 2.7.0.
  *
  * \param ctx      The SHA-256 context.
- * \param output   The SHA-224or SHA-256 checksum result.
+ * \param output   The SHA-224 or SHA-256 checksum result.
  */
 MBEDTLS_DEPRECATED void mbedtls_sha256_finish( mbedtls_sha256_context *ctx,
                                                unsigned char output[32] );
@@ -196,17 +202,6 @@
 
 #undef MBEDTLS_DEPRECATED
 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
-#ifdef __cplusplus
-}
-#endif
-
-#else  /* MBEDTLS_SHA256_ALT */
-#include "sha256_alt.h"
-#endif /* MBEDTLS_SHA256_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
 
 /**
  * \brief          This function calculates the SHA-224 or SHA-256
@@ -221,9 +216,8 @@
  * \param input    The buffer holding the input data.
  * \param ilen     The length of the input data.
  * \param output   The SHA-224 or SHA-256 checksum result.
- * \param is224    Determines which function to use.
- *                 <ul><li>0: Use SHA-256.</li>
- *                 <li>1: Use SHA-224.</li></ul>
+ * \param is224    Determines which function to use:
+ *                 0: Use SHA-256, or 1: Use SHA-224.
  */
 int mbedtls_sha256_ret( const unsigned char *input,
                         size_t ilen,
@@ -252,9 +246,8 @@
  * \param input    The buffer holding the data.
  * \param ilen     The length of the input data.
  * \param output   The SHA-224 or SHA-256 checksum result.
- * \param is224    Determines which function to use.
- *                 <ul><li>0: Use SHA-256.</li>
- *                 <li>1: Use SHA-224.</li></ul>
+ * \param is224    Determines which function to use:
+ *                 0: Use SHA-256, or 1: Use SHA-224.
  */
 MBEDTLS_DEPRECATED void mbedtls_sha256( const unsigned char *input,
                                         size_t ilen,
@@ -267,7 +260,8 @@
 /**
  * \brief          The SHA-224 and SHA-256 checkup routine.
  *
- * \return         \c 0 on success, or \c 1 on failure.
+ * \return         \c 0 on success.
+ * \return         \c 1 on failure.
  */
 int mbedtls_sha256_self_test( int verbose );
 
diff --git a/include/mbedtls/sha512.h b/include/mbedtls/sha512.h
index 8404a2d..5bb83f4 100644
--- a/include/mbedtls/sha512.h
+++ b/include/mbedtls/sha512.h
@@ -1,7 +1,9 @@
 /**
  * \file sha512.h
+ * \brief This file contains SHA-384 and SHA-512 definitions and functions.
  *
- * \brief The SHA-384 and SHA-512 cryptographic hash function.
+ * The Secure Hash Algorithms 384 and 512 (SHA-384 and SHA-512) cryptographic
+ * hash functions are defined in <em>FIPS 180-4: Secure Hash Standard (SHS)</em>.
  */
 /*
  *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
@@ -35,14 +37,14 @@
 
 #define MBEDTLS_ERR_SHA512_HW_ACCEL_FAILED                -0x0039  /**< SHA-512 hardware accelerator failed */
 
-#if !defined(MBEDTLS_SHA512_ALT)
-// Regular implementation
-//
-
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+#if !defined(MBEDTLS_SHA512_ALT)
+// Regular implementation
+//
+
 /**
  * \brief          The SHA-512 context structure.
  *
@@ -55,12 +57,15 @@
     uint64_t total[2];          /*!< The number of Bytes processed. */
     uint64_t state[8];          /*!< The intermediate digest state. */
     unsigned char buffer[128];  /*!< The data block being processed. */
-    int is384;                  /*!< Determines which function to use.
-                                 *   <ul><li>0: Use SHA-512.</li>
-                                 *   <li>1: Use SHA-384.</li></ul> */
+    int is384;                  /*!< Determines which function to use:
+                                     0: Use SHA-512, or 1: Use SHA-384. */
 }
 mbedtls_sha512_context;
 
+#else  /* MBEDTLS_SHA512_ALT */
+#include "sha512_alt.h"
+#endif /* MBEDTLS_SHA512_ALT */
+
 /**
  * \brief          This function initializes a SHA-512 context.
  *
@@ -89,9 +94,8 @@
  *                 calculation.
  *
  * \param ctx      The SHA-512 context to initialize.
- * \param is384    Determines which function to use.
- *                 <ul><li>0: Use SHA-512.</li>
- *                 <li>1: Use SHA-384.</li></ul>
+ * \param is384    Determines which function to use:
+ *                 0: Use SHA-512, or 1: Use SHA-384.
  *
  * \return         \c 0 on success.
  */
@@ -148,9 +152,8 @@
  * \deprecated     Superseded by mbedtls_sha512_starts_ret() in 2.7.0
  *
  * \param ctx      The SHA-512 context to initialize.
- * \param is384    Determines which function to use.
- *                 <ul><li>0: Use SHA-512.</li>
- *                 <li>1: Use SHA-384.</li></ul>
+ * \param is384    Determines which function to use:
+ *                 0: Use SHA-512, or 1: Use SHA-384.
  */
 MBEDTLS_DEPRECATED void mbedtls_sha512_starts( mbedtls_sha512_context *ctx,
                                                int is384 );
@@ -159,7 +162,7 @@
  * \brief          This function feeds an input buffer into an ongoing
  *                 SHA-512 checksum calculation.
  *
- * \deprecated     Superseded by mbedtls_sha512_update_ret() in 2.7.0
+ * \deprecated     Superseded by mbedtls_sha512_update_ret() in 2.7.0.
  *
  * \param ctx      The SHA-512 context.
  * \param input    The buffer holding the data.
@@ -173,7 +176,7 @@
  * \brief          This function finishes the SHA-512 operation, and writes
  *                 the result to the output buffer.
  *
- * \deprecated     Superseded by mbedtls_sha512_finish_ret() in 2.7.0
+ * \deprecated     Superseded by mbedtls_sha512_finish_ret() in 2.7.0.
  *
  * \param ctx      The SHA-512 context.
  * \param output   The SHA-384 or SHA-512 checksum result.
@@ -186,7 +189,7 @@
  *                 the ongoing SHA-512 computation. This function is for
  *                 internal use only.
  *
- * \deprecated     Superseded by mbedtls_internal_sha512_process() in 2.7.0
+ * \deprecated     Superseded by mbedtls_internal_sha512_process() in 2.7.0.
  *
  * \param ctx      The SHA-512 context.
  * \param data     The buffer holding one block of data.
@@ -198,18 +201,6 @@
 #undef MBEDTLS_DEPRECATED
 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
 
-#ifdef __cplusplus
-}
-#endif
-
-#else  /* MBEDTLS_SHA512_ALT */
-#include "sha512_alt.h"
-#endif /* MBEDTLS_SHA512_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
 /**
  * \brief          This function calculates the SHA-512 or SHA-384
  *                 checksum of a buffer.
@@ -223,9 +214,8 @@
  * \param input    The buffer holding the input data.
  * \param ilen     The length of the input data.
  * \param output   The SHA-384 or SHA-512 checksum result.
- * \param is384    Determines which function to use.
- *                 <ul><li>0: Use SHA-512.</li>
- *                 <li>1: Use SHA-384.</li></ul>
+ * \param is384    Determines which function to use:
+ *                 0: Use SHA-512, or 1: Use SHA-384.
  *
  * \return         \c 0 on success.
  */
@@ -255,9 +245,8 @@
  * \param input    The buffer holding the data.
  * \param ilen     The length of the input data.
  * \param output   The SHA-384 or SHA-512 checksum result.
- * \param is384    Determines which function to use.
- *                 <ul><li>0: Use SHA-512.</li>
- *                 <li>1: Use SHA-384.</li></ul>
+ * \param is384    Determines which function to use:
+ *                 0: Use SHA-512, or 1: Use SHA-384.
  */
 MBEDTLS_DEPRECATED void mbedtls_sha512( const unsigned char *input,
                                         size_t ilen,
@@ -269,7 +258,8 @@
  /**
  * \brief          The SHA-384 or SHA-512 checkup routine.
  *
- * \return         \c 0 on success, or \c 1 on failure.
+ * \return         \c 0 on success.
+ * \return         \c 1 on failure.
  */
 int mbedtls_sha512_self_test( int verbose );
 
diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index 51e843a..f91066d 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -49,6 +49,15 @@
 #endif
 
 #if defined(MBEDTLS_ZLIB_SUPPORT)
+
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#warning "Record compression support via MBEDTLS_ZLIB_SUPPORT is deprecated and will be removed in the next major revision of the library"
+#endif
+
+#if defined(MBEDTLS_DEPRECATED_REMOVED)
+#error "Record compression support via MBEDTLS_ZLIB_SUPPORT is deprecated and cannot be used if MBEDTLS_DEPRECATED_REMOVED is set"
+#endif
+
 #include "zlib.h"
 #endif
 
@@ -103,13 +112,14 @@
 #define MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED             -0x6A80  /**< DTLS client must retry for hello verification */
 #define MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL                  -0x6A00  /**< A buffer is too small to receive or write a message */
 #define MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE             -0x6980  /**< None of the common ciphersuites is usable (eg, no suitable certificate, see debug messages). */
-#define MBEDTLS_ERR_SSL_WANT_READ                         -0x6900  /**< Connection requires a read call. */
+#define MBEDTLS_ERR_SSL_WANT_READ                         -0x6900  /**< No data of requested type currently available on underlying transport. */
 #define MBEDTLS_ERR_SSL_WANT_WRITE                        -0x6880  /**< Connection requires a write call. */
 #define MBEDTLS_ERR_SSL_TIMEOUT                           -0x6800  /**< The operation timed out. */
 #define MBEDTLS_ERR_SSL_CLIENT_RECONNECT                  -0x6780  /**< The client initiated a reconnect from the same port. */
 #define MBEDTLS_ERR_SSL_UNEXPECTED_RECORD                 -0x6700  /**< Record header looks valid but is not expected. */
 #define MBEDTLS_ERR_SSL_NON_FATAL                         -0x6680  /**< The alert message received indicates a non-fatal error. */
 #define MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH               -0x6600  /**< Couldn't set the hash for verifying CertificateVerify */
+#define MBEDTLS_ERR_SSL_CONTINUE_PROCESSING               -0x6580  /**< Internal-only message signaling that further message-processing should be done */
 
 /*
  * Various constants
@@ -673,10 +683,18 @@
 #endif
 
 #if defined(MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED)
-    unsigned char *psk;             /*!< pre-shared key                     */
-    size_t         psk_len;         /*!< length of the pre-shared key       */
-    unsigned char *psk_identity;    /*!< identity for PSK negotiation       */
-    size_t         psk_identity_len;/*!< length of identity                 */
+    unsigned char *psk;             /*!< pre-shared key. This field should
+                                         only be set via
+                                         mbedtls_ssl_conf_psk() */
+    size_t         psk_len;         /*!< length of the pre-shared key. This
+                                         field should only be set via
+                                         mbedtls_ssl_conf_psk() */
+    unsigned char *psk_identity;    /*!< identity for PSK negotiation. This
+                                         field should only be set via
+                                         mbedtls_ssl_conf_psk() */
+    size_t         psk_identity_len;/*!< length of identity. This field should
+                                         only be set via
+                                         mbedtls_ssl_conf_psk() */
 #endif
 
 #if defined(MBEDTLS_SSL_ALPN)
@@ -971,8 +989,13 @@
  * \note           No copy of the configuration context is made, it can be
  *                 shared by many mbedtls_ssl_context structures.
  *
- * \warning        Modifying the conf structure after it has been used in this
- *                 function is unsupported!
+ * \warning        The conf structure will be accessed during the session.
+ *                 It must not be modified or freed as long as the session
+ *                 is active.
+ *
+ * \warning        This function must be called exactly once per context.
+ *                 Calling mbedtls_ssl_setup again is not supported, even
+ *                 if no session is active.
  *
  * \param ssl      SSL context
  * \param conf     SSL configuration to use
@@ -1587,6 +1610,10 @@
 /**
  * \brief          Set the data required to verify peer certificate
  *
+ * \note           See \c mbedtls_x509_crt_verify() for notes regarding the
+ *                 parameters ca_chain (maps to trust_ca for that function)
+ *                 and ca_crl.
+ *
  * \param conf     SSL configuration
  * \param ca_chain trusted CA chain (meaning all fully trusted top-level CAs)
  * \param ca_crl   trusted CA CRLs
@@ -1827,21 +1854,21 @@
 
 #if defined(MBEDTLS_X509_CRT_PARSE_C)
 /**
- * \brief          Set or reset the hostname to check against the received 
- *                 server certificate. It sets the ServerName TLS extension, 
+ * \brief          Set or reset the hostname to check against the received
+ *                 server certificate. It sets the ServerName TLS extension,
  *                 too, if that extension is enabled. (client-side only)
  *
  * \param ssl      SSL context
  * \param hostname the server hostname, may be NULL to clear hostname
- 
+
  * \note           Maximum hostname length MBEDTLS_SSL_MAX_HOST_NAME_LEN.
  *
- * \return         0 if successful, MBEDTLS_ERR_SSL_ALLOC_FAILED on 
- *                 allocation failure, MBEDTLS_ERR_SSL_BAD_INPUT_DATA on 
+ * \return         0 if successful, MBEDTLS_ERR_SSL_ALLOC_FAILED on
+ *                 allocation failure, MBEDTLS_ERR_SSL_BAD_INPUT_DATA on
  *                 too long input hostname.
  *
  *                 Hostname set to the one provided on success (cleared
- *                 when NULL). On allocation failure hostname is cleared. 
+ *                 when NULL). On allocation failure hostname is cleared.
  *                 On too long input failure, old hostname is unchanged.
  */
 int mbedtls_ssl_set_hostname( mbedtls_ssl_context *ssl, const char *hostname );
@@ -2275,11 +2302,59 @@
 #endif /* MBEDTLS_SSL_RENEGOTIATION */
 
 /**
- * \brief          Return the number of data bytes available to read
+ * \brief          Check if there is data already read from the
+ *                 underlying transport but not yet processed.
  *
  * \param ssl      SSL context
  *
- * \return         how many bytes are available in the read buffer
+ * \return         0 if nothing's pending, 1 otherwise.
+ *
+ * \note           This is different in purpose and behaviour from
+ *                 \c mbedtls_ssl_get_bytes_avail in that it considers
+ *                 any kind of unprocessed data, not only unread
+ *                 application data. If \c mbedtls_ssl_get_bytes
+ *                 returns a non-zero value, this function will
+ *                 also signal pending data, but the converse does
+ *                 not hold. For example, in DTLS there might be
+ *                 further records waiting to be processed from
+ *                 the current underlying transport's datagram.
+ *
+ * \note           If this function returns 1 (data pending), this
+ *                 does not imply that a subsequent call to
+ *                 \c mbedtls_ssl_read will provide any data;
+ *                 e.g., the unprocessed data might turn out
+ *                 to be an alert or a handshake message.
+ *
+ * \note           This function is useful in the following situation:
+ *                 If the SSL/TLS module successfully returns from an
+ *                 operation - e.g. a handshake or an application record
+ *                 read - and you're awaiting incoming data next, you
+ *                 must not immediately idle on the underlying transport
+ *                 to have data ready, but you need to check the value
+ *                 of this function first. The reason is that the desired
+ *                 data might already be read but not yet processed.
+ *                 If, in contrast, a previous call to the SSL/TLS module
+ *                 returned MBEDTLS_ERR_SSL_WANT_READ, it is not necessary
+ *                 to call this function, as the latter error code entails
+ *                 that all internal data has been processed.
+ *
+ */
+int mbedtls_ssl_check_pending( const mbedtls_ssl_context *ssl );
+
+/**
+ * \brief          Return the number of application data bytes
+ *                 remaining to be read from the current record.
+ *
+ * \param ssl      SSL context
+ *
+ * \return         How many bytes are available in the application
+ *                 data record read buffer.
+ *
+ * \note           When working over a datagram transport, this is
+ *                 useful to detect the current datagram's boundary
+ *                 in case \c mbedtls_ssl_read has written the maximal
+ *                 amount of data fitting into the input buffer.
+ *
  */
 size_t mbedtls_ssl_get_bytes_avail( const mbedtls_ssl_context *ssl );
 
@@ -2394,11 +2469,25 @@
  *                 MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED (see below), or
  *                 a specific SSL error code.
  *
+ *                 If this function returns MBEDTLS_ERR_SSL_WANT_READ, the
+ *                 handshake is unfinished and no further data is available
+ *                 from the underlying transport. In this case, you must call
+ *                 the function again at some later stage.
+ *
+ * \note           Remarks regarding event-driven DTLS:
+ *                 If the function returns MBEDTLS_ERR_SSL_WANT_READ, no datagram
+ *                 from the underlying transport layer is currently being processed,
+ *                 and it is safe to idle until the timer or the underlying transport
+ *                 signal a new event. This is not true for a successful handshake,
+ *                 in which case the datagram of the underlying transport that is
+ *                 currently being processed might or might not contain further
+ *                 DTLS records.
+ *
  * \note           If this function returns something other than 0 or
- *                 MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context
- *                 becomes unusable, and you should either free it or call
- *                 \c mbedtls_ssl_session_reset() on it before re-using it for
- *                 a new connection; the current connection must be closed.
+ *                 MBEDTLS_ERR_SSL_WANT_READ/WRITE, you must stop using
+ *                 the SSL context for reading or writing, and either free it or
+ *                 call \c mbedtls_ssl_session_reset() on it before re-using it
+ *                 for a new connection; the current connection must be closed.
  *
  * \note           If DTLS is in use, then you may choose to handle
  *                 MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED specially for logging
@@ -2415,10 +2504,10 @@
  *                 call this function if state is MBEDTLS_SSL_HANDSHAKE_OVER.
  *
  * \note           If this function returns something other than 0 or
- *                 MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context
- *                 becomes unusable, and you should either free it or call
- *                 \c mbedtls_ssl_session_reset() on it before re-using it for
- *                 a new connection; the current connection must be closed.
+ *                 MBEDTLS_ERR_SSL_WANT_READ/WRITE, you must stop using
+ *                 the SSL context for reading or writing, and either free it or
+ *                 call \c mbedtls_ssl_session_reset() on it before re-using it
+ *                 for a new connection; the current connection must be closed.
  *
  * \param ssl      SSL context
  *
@@ -2442,10 +2531,10 @@
  *                 value.
  *
  * \note           If this function returns something other than 0 or
- *                 MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context
- *                 becomes unusable, and you should either free it or call
- *                 \c mbedtls_ssl_session_reset() on it before re-using it for
- *                 a new connection; the current connection must be closed.
+ *                 MBEDTLS_ERR_SSL_WANT_READ/WRITE, you must stop using
+ *                 the SSL context for reading or writing, and either free it or
+ *                 call \c mbedtls_ssl_session_reset() on it before re-using it
+ *                 for a new connection; the current connection must be closed.
  */
 int mbedtls_ssl_renegotiate( mbedtls_ssl_context *ssl );
 #endif /* MBEDTLS_SSL_RENEGOTIATION */
@@ -2457,20 +2546,20 @@
  * \param buf      buffer that will hold the data
  * \param len      maximum number of bytes to read
  *
- * \return         the number of bytes read, or
- *                 0 for EOF, or
- *                 MBEDTLS_ERR_SSL_WANT_READ or MBEDTLS_ERR_SSL_WANT_WRITE, or
- *                 MBEDTLS_ERR_SSL_CLIENT_RECONNECT (see below), or
- *                 another negative error code.
+ * \return         One of the following:
+ *                 - 0 if the read end of the underlying transport was closed,
+ *                 - the (positive) number of bytes read, or
+ *                 - a negative error code on failure.
  *
- * \note           If this function returns something other than a positive
- *                 value or MBEDTLS_ERR_SSL_WANT_READ/WRITE or
- *                 MBEDTLS_ERR_SSL_CLIENT_RECONNECT, then the ssl context
- *                 becomes unusable, and you should either free it or call
- *                 \c mbedtls_ssl_session_reset() on it before re-using it for
- *                 a new connection; the current connection must be closed.
+ *                 If MBEDTLS_ERR_SSL_WANT_READ is returned, no application data
+ *                 is available from the underlying transport. In this case,
+ *                 the function needs to be called again at some later stage.
  *
- * \note           When this function return MBEDTLS_ERR_SSL_CLIENT_RECONNECT
+ *                 If MBEDTLS_ERR_SSL_WANT_WRITE is returned, a write is pending
+ *                 but the underlying transport isn't available for writing. In this
+ *                 case, the function needs to be called again at some later stage.
+ *
+ *                 When this function return MBEDTLS_ERR_SSL_CLIENT_RECONNECT
  *                 (which can only happen server-side), it means that a client
  *                 is initiating a new connection using the same source port.
  *                 You can either treat that as a connection close and wait
@@ -2483,6 +2572,28 @@
  *                 again. WARNING: not validating the identity of the client
  *                 again, or not transmitting the new identity to the
  *                 application layer, would allow authentication bypass!
+ *
+ * \note           If this function returns something other than a positive value
+ *                 or MBEDTLS_ERR_SSL_WANT_READ/WRITE or MBEDTLS_ERR_SSL_CLIENT_RECONNECT,
+ *                 you must stop using the SSL context for reading or writing,
+ *                 and either free it or call \c mbedtls_ssl_session_reset() on it
+ *                 before re-using it for a new connection; the current connection
+ *                 must be closed.
+ *
+ * \note           Remarks regarding event-driven DTLS:
+ *                 - If the function returns MBEDTLS_ERR_SSL_WANT_READ, no datagram
+ *                   from the underlying transport layer is currently being processed,
+ *                   and it is safe to idle until the timer or the underlying transport
+ *                   signal a new event.
+ *                 - This function may return MBEDTLS_ERR_SSL_WANT_READ even if data was
+ *                   initially available on the underlying transport, as this data may have
+ *                   been only e.g. duplicated messages or a renegotiation request.
+ *                   Therefore, you must be prepared to receive MBEDTLS_ERR_SSL_WANT_READ even
+ *                   when reacting to an incoming-data event from the underlying transport.
+ *                 - On success, the datagram of the underlying transport that is currently
+ *                   being processed may contain further DTLS records. You should call
+ *                   \c mbedtls_ssl_check_pending to check for remaining records.
+ *
  */
 int mbedtls_ssl_read( mbedtls_ssl_context *ssl, unsigned char *buf, size_t len );
 
@@ -2503,15 +2614,17 @@
  *                 or MBEDTLS_ERR_SSL_WANT_WRITE or MBEDTLS_ERR_SSL_WANT_READ,
  *                 or another negative error code.
  *
- * \note           If this function returns something other than a positive
- *                 value or MBEDTLS_ERR_SSL_WANT_READ/WRITE, the ssl context
- *                 becomes unusable, and you should either free it or call
- *                 \c mbedtls_ssl_session_reset() on it before re-using it for
- *                 a new connection; the current connection must be closed.
+ * \note           If this function returns something other than a positive value
+ *                 or MBEDTLS_ERR_SSL_WANT_READ/WRITE, you must stop using
+ *                 the SSL context for reading or writing, and either free it or
+ *                 call \c mbedtls_ssl_session_reset() on it before re-using it
+ *                 for a new connection; the current connection must be closed.
  *
  * \note           When this function returns MBEDTLS_ERR_SSL_WANT_WRITE/READ,
  *                 it must be called later with the *same* arguments,
- *                 until it returns a positive value.
+ *                 until it returns a positive value. When the function returns
+ *                 MBEDTLS_ERR_SSL_WANT_WRITE there may be some partial
+ *                 data in the output buffer, however this is not yet sent.
  *
  * \note           If the requested length is greater than the maximum
  *                 fragment length (either the built-in limit or the one set
@@ -2534,10 +2647,10 @@
  * \return          0 if successful, or a specific SSL error code.
  *
  * \note           If this function returns something other than 0 or
- *                 MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context
- *                 becomes unusable, and you should either free it or call
- *                 \c mbedtls_ssl_session_reset() on it before re-using it for
- *                 a new connection; the current connection must be closed.
+ *                 MBEDTLS_ERR_SSL_WANT_READ/WRITE, you must stop using
+ *                 the SSL context for reading or writing, and either free it or
+ *                 call \c mbedtls_ssl_session_reset() on it before re-using it
+ *                 for a new connection; the current connection must be closed.
  */
 int mbedtls_ssl_send_alert_message( mbedtls_ssl_context *ssl,
                             unsigned char level,
@@ -2550,10 +2663,10 @@
  * \return          0 if successful, or a specific SSL error code.
  *
  * \note           If this function returns something other than 0 or
- *                 MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context
- *                 becomes unusable, and you should either free it or call
- *                 \c mbedtls_ssl_session_reset() on it before re-using it for
- *                 a new connection; the current connection must be closed.
+ *                 MBEDTLS_ERR_SSL_WANT_READ/WRITE, you must stop using
+ *                 the SSL context for reading or writing, and either free it or
+ *                 call \c mbedtls_ssl_session_reset() on it before re-using it
+ *                 for a new connection; the current connection must be closed.
  */
 int mbedtls_ssl_close_notify( mbedtls_ssl_context *ssl );
 
diff --git a/include/mbedtls/ssl_internal.h b/include/mbedtls/ssl_internal.h
index 9f583a8..60b431a 100644
--- a/include/mbedtls/ssl_internal.h
+++ b/include/mbedtls/ssl_internal.h
@@ -71,6 +71,9 @@
 #endif /* MBEDTLS_SSL_PROTO_TLS1   */
 #endif /* MBEDTLS_SSL_PROTO_SSL3   */
 
+#define MBEDTLS_SSL_MIN_VALID_MINOR_VERSION MBEDTLS_SSL_MINOR_VERSION_1
+#define MBEDTLS_SSL_MIN_VALID_MAJOR_VERSION MBEDTLS_SSL_MAJOR_VERSION_3
+
 /* Determine maximum supported version */
 #define MBEDTLS_SSL_MAX_MAJOR_VERSION           MBEDTLS_SSL_MAJOR_VERSION_3
 
diff --git a/include/mbedtls/threading.h b/include/mbedtls/threading.h
index 58e6db2..aeea5d0 100644
--- a/include/mbedtls/threading.h
+++ b/include/mbedtls/threading.h
@@ -96,8 +96,12 @@
 /*
  * Global mutexes
  */
+#if defined(MBEDTLS_FS_IO)
 extern mbedtls_threading_mutex_t mbedtls_threading_readdir_mutex;
+#endif
+#if defined(MBEDTLS_HAVE_TIME_DATE)
 extern mbedtls_threading_mutex_t mbedtls_threading_gmtime_mutex;
+#endif
 #endif /* MBEDTLS_THREADING_C */
 
 #ifdef __cplusplus
diff --git a/include/mbedtls/timing.h b/include/mbedtls/timing.h
index 2c497bf..bbcb906 100644
--- a/include/mbedtls/timing.h
+++ b/include/mbedtls/timing.h
@@ -30,16 +30,16 @@
 #include MBEDTLS_CONFIG_FILE
 #endif
 
-#if !defined(MBEDTLS_TIMING_ALT)
-// Regular implementation
-//
-
 #include <stdint.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+#if !defined(MBEDTLS_TIMING_ALT)
+// Regular implementation
+//
+
 /**
  * \brief          timer structure
  */
@@ -58,6 +58,10 @@
     uint32_t                        fin_ms;
 } mbedtls_timing_delay_context;
 
+#else  /* MBEDTLS_TIMING_ALT */
+#include "timing_alt.h"
+#endif /* MBEDTLS_TIMING_ALT */
+
 extern volatile int mbedtls_timing_alarmed;
 
 /**
@@ -133,18 +137,6 @@
  */
 int mbedtls_timing_get_delay( void *data );
 
-#ifdef __cplusplus
-}
-#endif
-
-#else  /* MBEDTLS_TIMING_ALT */
-#include "timing_alt.h"
-#endif /* MBEDTLS_TIMING_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
 #if defined(MBEDTLS_SELF_TEST)
 /**
  * \brief          Checkup routine
diff --git a/include/mbedtls/version.h b/include/mbedtls/version.h
index 961be59..aa52ce2 100644
--- a/include/mbedtls/version.h
+++ b/include/mbedtls/version.h
@@ -39,7 +39,7 @@
  * Major, Minor, Patchlevel
  */
 #define MBEDTLS_VERSION_MAJOR  2
-#define MBEDTLS_VERSION_MINOR  7
+#define MBEDTLS_VERSION_MINOR  9
 #define MBEDTLS_VERSION_PATCH  0
 
 /**
@@ -47,9 +47,9 @@
  *    MMNNPP00
  *    Major version | Minor version | Patch version
  */
-#define MBEDTLS_VERSION_NUMBER         0x02070000
-#define MBEDTLS_VERSION_STRING         "2.7.0"
-#define MBEDTLS_VERSION_STRING_FULL    "mbed TLS 2.7.0"
+#define MBEDTLS_VERSION_NUMBER         0x02090000
+#define MBEDTLS_VERSION_STRING         "2.9.0"
+#define MBEDTLS_VERSION_STRING_FULL    "mbed TLS 2.9.0"
 
 #if defined(MBEDTLS_VERSION_C)
 
diff --git a/include/mbedtls/x509_crt.h b/include/mbedtls/x509_crt.h
index 2dbb7ec..ac23cff 100644
--- a/include/mbedtls/x509_crt.h
+++ b/include/mbedtls/x509_crt.h
@@ -287,8 +287,15 @@
  *                 used to sign the certificate, CRL verification is skipped
  *                 silently, that is *without* setting any flag.
  *
+ * \note           The \c trust_ca list can contain two types of certificates:
+ *                 (1) those of trusted root CAs, so that certificates
+ *                 chaining up to those CAs will be trusted, and (2)
+ *                 self-signed end-entity certificates to be trusted (for
+ *                 specific peers you know) - in that case, the self-signed
+ *                 certificate doesn't need to have the CA bit set.
+ *
  * \param crt      a certificate (chain) to be verified
- * \param trust_ca the list of trusted CAs
+ * \param trust_ca the list of trusted CAs (see note above)
  * \param ca_crl   the list of CRLs for trusted CAs (see note above)
  * \param cn       expected Common Name (can be set to
  *                 NULL if the CN must not be verified)
diff --git a/include/mbedtls/xtea.h b/include/mbedtls/xtea.h
index 34ccee3..8df708a 100644
--- a/include/mbedtls/xtea.h
+++ b/include/mbedtls/xtea.h
@@ -39,14 +39,14 @@
 #define MBEDTLS_ERR_XTEA_INVALID_INPUT_LENGTH             -0x0028  /**< The data input has an invalid length. */
 #define MBEDTLS_ERR_XTEA_HW_ACCEL_FAILED                  -0x0029  /**< XTEA hardware accelerator failed. */
 
-#if !defined(MBEDTLS_XTEA_ALT)
-// Regular implementation
-//
-
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+#if !defined(MBEDTLS_XTEA_ALT)
+// Regular implementation
+//
+
 /**
  * \brief          XTEA context structure
  */
@@ -56,6 +56,10 @@
 }
 mbedtls_xtea_context;
 
+#else  /* MBEDTLS_XTEA_ALT */
+#include "xtea_alt.h"
+#endif /* MBEDTLS_XTEA_ALT */
+
 /**
  * \brief          Initialize XTEA context
  *
@@ -115,18 +119,6 @@
                     unsigned char *output);
 #endif /* MBEDTLS_CIPHER_MODE_CBC */
 
-#ifdef __cplusplus
-}
-#endif
-
-#else  /* MBEDTLS_XTEA_ALT */
-#include "xtea_alt.h"
-#endif /* MBEDTLS_XTEA_ALT */
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
 /**
  * \brief          Checkup routine
  *