diff --git a/include/CMakeLists.txt b/include/CMakeLists.txt
index 67c66c8..dac97f4 100644
--- a/include/CMakeLists.txt
+++ b/include/CMakeLists.txt
@@ -15,7 +15,8 @@
 
 endif(INSTALL_MBEDTLS_HEADERS)
 
-# Make config.h available in an out-of-source build. ssl-opt.sh requires it.
+# Make config.h available in an out-of-source build.
 if (NOT ${CMAKE_CURRENT_BINARY_DIR} STREQUAL ${CMAKE_CURRENT_SOURCE_DIR})
     link_to_source(mbedtls)
+    link_to_source(psa)
 endif()
diff --git a/include/mbedtls/aes.h b/include/mbedtls/aes.h
index cfb20c4..94e7282 100644
--- a/include/mbedtls/aes.h
+++ b/include/mbedtls/aes.h
@@ -121,7 +121,7 @@
  *                 It must be the first API called before using
  *                 the context.
  *
- * \param ctx      The AES context to initialize.
+ * \param ctx      The AES context to initialize. This must not be \c NULL.
  */
 void mbedtls_aes_init( mbedtls_aes_context *ctx );
 
@@ -129,6 +129,8 @@
  * \brief          This function releases and clears the specified AES context.
  *
  * \param ctx      The AES context to clear.
+ *                 If this is \c NULL, this function does nothing.
+ *                 Otherwise, the context must have been at least initialized.
  */
 void mbedtls_aes_free( mbedtls_aes_context *ctx );
 
@@ -139,7 +141,7 @@
  *                 It must be the first API called before using
  *                 the context.
  *
- * \param ctx      The AES XTS context to initialize.
+ * \param ctx      The AES XTS context to initialize. This must not be \c NULL.
  */
 void mbedtls_aes_xts_init( mbedtls_aes_xts_context *ctx );
 
@@ -147,6 +149,8 @@
  * \brief          This function releases and clears the specified AES XTS context.
  *
  * \param ctx      The AES XTS context to clear.
+ *                 If this is \c NULL, this function does nothing.
+ *                 Otherwise, the context must have been at least initialized.
  */
 void mbedtls_aes_xts_free( mbedtls_aes_xts_context *ctx );
 #endif /* MBEDTLS_CIPHER_MODE_XTS */
@@ -155,7 +159,9 @@
  * \brief          This function sets the encryption key.
  *
  * \param ctx      The AES context to which the key should be bound.
+ *                 It must be initialized.
  * \param key      The encryption key.
+ *                 This must be a readable buffer of size \p keybits bits.
  * \param keybits  The size of data passed in bits. Valid options are:
  *                 <ul><li>128 bits</li>
  *                 <li>192 bits</li>
@@ -171,7 +177,9 @@
  * \brief          This function sets the decryption key.
  *
  * \param ctx      The AES context to which the key should be bound.
+ *                 It must be initialized.
  * \param key      The decryption key.
+ *                 This must be a readable buffer of size \p keybits bits.
  * \param keybits  The size of data passed. Valid options are:
  *                 <ul><li>128 bits</li>
  *                 <li>192 bits</li>
@@ -189,8 +197,10 @@
  *                 sets the encryption key.
  *
  * \param ctx      The AES XTS context to which the key should be bound.
+ *                 It must be initialized.
  * \param key      The encryption key. This is comprised of the XTS key1
  *                 concatenated with the XTS key2.
+ *                 This must be a readable buffer of size \p keybits bits.
  * \param keybits  The size of \p key passed in bits. Valid options are:
  *                 <ul><li>256 bits (each of key1 and key2 is a 128-bit key)</li>
  *                 <li>512 bits (each of key1 and key2 is a 256-bit key)</li></ul>
@@ -207,8 +217,10 @@
  *                 sets the decryption key.
  *
  * \param ctx      The AES XTS context to which the key should be bound.
+ *                 It must be initialized.
  * \param key      The decryption key. This is comprised of the XTS key1
  *                 concatenated with the XTS key2.
+ *                 This must be a readable buffer of size \p keybits bits.
  * \param keybits  The size of \p key passed in bits. Valid options are:
  *                 <ul><li>256 bits (each of key1 and key2 is a 128-bit key)</li>
  *                 <li>512 bits (each of key1 and key2 is a 256-bit key)</li></ul>
@@ -234,10 +246,13 @@
  *                 call to this API with the same context.
  *
  * \param ctx      The AES context to use for encryption or decryption.
+ *                 It must be initialized and bound to a key.
  * \param mode     The AES operation: #MBEDTLS_AES_ENCRYPT or
  *                 #MBEDTLS_AES_DECRYPT.
- * \param input    The 16-Byte buffer holding the input data.
- * \param output   The 16-Byte buffer holding the output data.
+ * \param input    The buffer holding the input data.
+ *                 It must be readable and at least \c 16 Bytes long.
+ * \param output   The buffer where the output data will be written.
+ *                 It must be writeable and at least \c 16 Bytes long.
 
  * \return         \c 0 on success.
  */
@@ -260,8 +275,8 @@
  *         mbedtls_aes_setkey_enc() or mbedtls_aes_setkey_dec() must be called
  *         before the first call to this API with the same context.
  *
- * \note   This function operates on aligned blocks, that is, the input size
- *         must be a multiple of the AES block size of 16 Bytes.
+ * \note   This function operates on full blocks, that is, the input size
+ *         must be a multiple of the AES block size of \c 16 Bytes.
  *
  * \note   Upon exit, the content of the IV is updated so that you can
  *         call the same function again on the next
@@ -272,13 +287,17 @@
  *
  *
  * \param ctx      The AES context to use for encryption or decryption.
+ *                 It must be initialized and bound to a key.
  * \param mode     The AES operation: #MBEDTLS_AES_ENCRYPT or
  *                 #MBEDTLS_AES_DECRYPT.
  * \param length   The length of the input data in Bytes. This must be a
- *                 multiple of the block size (16 Bytes).
+ *                 multiple of the block size (\c 16 Bytes).
  * \param iv       Initialization vector (updated after use).
+ *                 It must be a readable and writeable buffer of \c 16 Bytes.
  * \param input    The buffer holding the input data.
+ *                 It must be readable and of size \p length Bytes.
  * \param output   The buffer holding the output data.
+ *                 It must be writeable and of size \p length Bytes.
  *
  * \return         \c 0 on success.
  * \return         #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH
@@ -306,9 +325,10 @@
  *             returns #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH.
  *
  * \param ctx          The AES XTS context to use for AES XTS operations.
+ *                     It must be initialized and bound to a key.
  * \param mode         The AES operation: #MBEDTLS_AES_ENCRYPT or
  *                     #MBEDTLS_AES_DECRYPT.
- * \param length       The length of a data unit in bytes. This can be any
+ * \param length       The length of a data unit in Bytes. This can be any
  *                     length between 16 bytes and 2^24 bytes inclusive
  *                     (between 1 and 2^20 block cipher blocks).
  * \param data_unit    The address of the data unit encoded as an array of 16
@@ -316,15 +336,15 @@
  *                     is typically the index of the block device sector that
  *                     contains the data.
  * \param input        The buffer holding the input data (which is an entire
- *                     data unit). This function reads \p length bytes from \p
+ *                     data unit). This function reads \p length Bytes from \p
  *                     input.
  * \param output       The buffer holding the output data (which is an entire
- *                     data unit). This function writes \p length bytes to \p
+ *                     data unit). This function writes \p length Bytes to \p
  *                     output.
  *
  * \return             \c 0 on success.
  * \return             #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH if \p length is
- *                     smaller than an AES block in size (16 bytes) or if \p
+ *                     smaller than an AES block in size (16 Bytes) or if \p
  *                     length is larger than 2^20 blocks (16 MiB).
  */
 int mbedtls_aes_crypt_xts( mbedtls_aes_xts_context *ctx,
@@ -360,13 +380,18 @@
  *
  *
  * \param ctx      The AES context to use for encryption or decryption.
+ *                 It must be initialized and bound to a key.
  * \param mode     The AES operation: #MBEDTLS_AES_ENCRYPT or
  *                 #MBEDTLS_AES_DECRYPT.
- * \param length   The length of the input data.
+ * \param length   The length of the input data in Bytes.
  * \param iv_off   The offset in IV (updated after use).
+ *                 It must point to a valid \c size_t.
  * \param iv       The initialization vector (updated after use).
+ *                 It must be a readable and writeable buffer of \c 16 Bytes.
  * \param input    The buffer holding the input data.
+ *                 It must be readable and of size \p length Bytes.
  * \param output   The buffer holding the output data.
+ *                 It must be writeable and of size \p length Bytes.
  *
  * \return         \c 0 on success.
  */
@@ -401,12 +426,16 @@
  *
  *
  * \param ctx      The AES context to use for encryption or decryption.
+ *                 It must be initialized and bound to a key.
  * \param mode     The AES operation: #MBEDTLS_AES_ENCRYPT or
  *                 #MBEDTLS_AES_DECRYPT
  * \param length   The length of the input data.
  * \param iv       The initialization vector (updated after use).
+ *                 It must be a readable and writeable buffer of \c 16 Bytes.
  * \param input    The buffer holding the input data.
+ *                 It must be readable and of size \p length Bytes.
  * \param output   The buffer holding the output data.
+ *                 It must be writeable and of size \p length Bytes.
  *
  * \return         \c 0 on success.
  */
@@ -451,11 +480,16 @@
  *              will compromise security.
  *
  * \param ctx      The AES context to use for encryption or decryption.
+ *                 It must be initialized and bound to a key.
  * \param length   The length of the input data.
  * \param iv_off   The offset in IV (updated after use).
+ *                 It must point to a valid \c size_t.
  * \param iv       The initialization vector (updated after use).
+ *                 It must be a readable and writeable buffer of \c 16 Bytes.
  * \param input    The buffer holding the input data.
+ *                 It must be readable and of size \p length Bytes.
  * \param output   The buffer holding the output data.
+ *                 It must be writeable and of size \p length Bytes.
  *
  * \return         \c 0 on success.
  */
@@ -527,15 +561,21 @@
  *             securely discarded as soon as it's no longer needed.
  *
  * \param ctx              The AES context to use for encryption or decryption.
+ *                         It must be initialized and bound to a key.
  * \param length           The length of the input data.
  * \param nc_off           The offset in the current \p stream_block, for
  *                         resuming within the current cipher stream. The
  *                         offset pointer should be 0 at the start of a stream.
+ *                         It must point to a valid \c size_t.
  * \param nonce_counter    The 128-bit nonce and counter.
+ *                         It must be a readable-writeable buffer of \c 16 Bytes.
  * \param stream_block     The saved stream block for resuming. This is
  *                         overwritten by the function.
+ *                         It must be a readable-writeable buffer of \c 16 Bytes.
  * \param input            The buffer holding the input data.
+ *                         It must be readable and of size \p length Bytes.
  * \param output           The buffer holding the output data.
+ *                         It must be writeable and of size \p length Bytes.
  *
  * \return                 \c 0 on success.
  */
@@ -588,7 +628,7 @@
  * \brief           Deprecated internal AES block encryption function
  *                  without return value.
  *
- * \deprecated      Superseded by mbedtls_aes_encrypt_ext() in 2.5.0.
+ * \deprecated      Superseded by mbedtls_internal_aes_encrypt()
  *
  * \param ctx       The AES context to use for encryption.
  * \param input     Plaintext block.
@@ -602,7 +642,7 @@
  * \brief           Deprecated internal AES block decryption function
  *                  without return value.
  *
- * \deprecated      Superseded by mbedtls_aes_decrypt_ext() in 2.5.0.
+ * \deprecated      Superseded by mbedtls_internal_aes_decrypt()
  *
  * \param ctx       The AES context to use for decryption.
  * \param input     Ciphertext block.
@@ -615,6 +655,8 @@
 #undef MBEDTLS_DEPRECATED
 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
 
+
+#if defined(MBEDTLS_SELF_TEST)
 /**
  * \brief          Checkup routine.
  *
@@ -623,6 +665,8 @@
  */
 int mbedtls_aes_self_test( int verbose );
 
+#endif /* MBEDTLS_SELF_TEST */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/mbedtls/aesni.h b/include/mbedtls/aesni.h
index 746baa0..a4ca012 100644
--- a/include/mbedtls/aesni.h
+++ b/include/mbedtls/aesni.h
@@ -2,6 +2,9 @@
  * \file aesni.h
  *
  * \brief AES-NI for hardware AES acceleration on some Intel processors
+ *
+ * \warning These functions are only for internal use by other library
+ *          functions; you must not call them directly.
  */
 /*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
@@ -24,6 +27,12 @@
 #ifndef MBEDTLS_AESNI_H
 #define MBEDTLS_AESNI_H
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
 #include "aes.h"
 
 #define MBEDTLS_AESNI_AES      0x02000000u
@@ -42,7 +51,10 @@
 #endif
 
 /**
- * \brief          AES-NI features detection routine
+ * \brief          Internal function to detect the AES-NI feature in CPUs.
+ *
+ * \note           This function is only for internal use by other library
+ *                 functions; you must not call it directly.
  *
  * \param what     The feature to detect
  *                 (MBEDTLS_AESNI_AES or MBEDTLS_AESNI_CLMUL)
@@ -52,7 +64,10 @@
 int mbedtls_aesni_has_support( unsigned int what );
 
 /**
- * \brief          AES-NI AES-ECB block en(de)cryption
+ * \brief          Internal AES-NI AES-ECB block encryption and decryption
+ *
+ * \note           This function is only for internal use by other library
+ *                 functions; you must not call it directly.
  *
  * \param ctx      AES context
  * \param mode     MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT
@@ -62,12 +77,15 @@
  * \return         0 on success (cannot fail)
  */
 int mbedtls_aesni_crypt_ecb( mbedtls_aes_context *ctx,
-                     int mode,
-                     const unsigned char input[16],
-                     unsigned char output[16] );
+                             int mode,
+                             const unsigned char input[16],
+                             unsigned char output[16] );
 
 /**
- * \brief          GCM multiplication: c = a * b in GF(2^128)
+ * \brief          Internal GCM multiplication: c = a * b in GF(2^128)
+ *
+ * \note           This function is only for internal use by other library
+ *                 functions; you must not call it directly.
  *
  * \param c        Result
  * \param a        First operand
@@ -77,21 +95,29 @@
  *                 elements of GF(2^128) as per the GCM spec.
  */
 void mbedtls_aesni_gcm_mult( unsigned char c[16],
-                     const unsigned char a[16],
-                     const unsigned char b[16] );
+                             const unsigned char a[16],
+                             const unsigned char b[16] );
 
 /**
- * \brief           Compute decryption round keys from encryption round keys
+ * \brief           Internal round key inversion. This function computes
+ *                  decryption round keys from the encryption round keys.
+ *
+ * \note            This function is only for internal use by other library
+ *                  functions; you must not call it directly.
  *
  * \param invkey    Round keys for the equivalent inverse cipher
  * \param fwdkey    Original round keys (for encryption)
  * \param nr        Number of rounds (that is, number of round keys minus one)
  */
 void mbedtls_aesni_inverse_key( unsigned char *invkey,
-                        const unsigned char *fwdkey, int nr );
+                                const unsigned char *fwdkey,
+                                int nr );
 
 /**
- * \brief           Perform key expansion (for encryption)
+ * \brief           Internal key expansion for encryption
+ *
+ * \note            This function is only for internal use by other library
+ *                  functions; you must not call it directly.
  *
  * \param rk        Destination buffer where the round keys are written
  * \param key       Encryption key
@@ -100,8 +126,8 @@
  * \return          0 if successful, or MBEDTLS_ERR_AES_INVALID_KEY_LENGTH
  */
 int mbedtls_aesni_setkey_enc( unsigned char *rk,
-                      const unsigned char *key,
-                      size_t bits );
+                              const unsigned char *key,
+                              size_t bits );
 
 #ifdef __cplusplus
 }
diff --git a/include/mbedtls/arc4.h b/include/mbedtls/arc4.h
index c43f406..fb044d5 100644
--- a/include/mbedtls/arc4.h
+++ b/include/mbedtls/arc4.h
@@ -123,6 +123,8 @@
 int mbedtls_arc4_crypt( mbedtls_arc4_context *ctx, size_t length, const unsigned char *input,
                 unsigned char *output );
 
+#if defined(MBEDTLS_SELF_TEST)
+
 /**
  * \brief          Checkup routine
  *
@@ -135,6 +137,8 @@
  */
 int mbedtls_arc4_self_test( int verbose );
 
+#endif /* MBEDTLS_SELF_TEST */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/mbedtls/aria.h b/include/mbedtls/aria.h
index 483d4c2..1e8956e 100644
--- a/include/mbedtls/aria.h
+++ b/include/mbedtls/aria.h
@@ -39,6 +39,8 @@
 #include <stddef.h>
 #include <stdint.h>
 
+#include "platform_util.h"
+
 #define MBEDTLS_ARIA_ENCRYPT     1 /**< ARIA encryption. */
 #define MBEDTLS_ARIA_DECRYPT     0 /**< ARIA decryption. */
 
@@ -46,8 +48,12 @@
 #define MBEDTLS_ARIA_MAX_ROUNDS  16 /**< Maxiumum number of rounds in ARIA. */
 #define MBEDTLS_ARIA_MAX_KEYSIZE 32 /**< Maximum size of an ARIA key in bytes. */
 
-#define MBEDTLS_ERR_ARIA_INVALID_KEY_LENGTH   -0x005C  /**< Invalid key length. */
-#define MBEDTLS_ERR_ARIA_INVALID_INPUT_LENGTH -0x005E  /**< Invalid data input length. */
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#define MBEDTLS_ERR_ARIA_INVALID_KEY_LENGTH   MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( -0x005C )
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
+#define MBEDTLS_ERR_ARIA_BAD_INPUT_DATA -0x005C /**< Bad input data. */
+
+#define MBEDTLS_ERR_ARIA_INVALID_INPUT_LENGTH -0x005E /**< Invalid data input length. */
 
 /* MBEDTLS_ERR_ARIA_FEATURE_UNAVAILABLE is deprecated and should not be used.
  */
@@ -85,14 +91,16 @@
  *                 It must be the first API called before using
  *                 the context.
  *
- * \param ctx      The ARIA context to initialize.
+ * \param ctx      The ARIA context to initialize. This must not be \c NULL.
  */
 void mbedtls_aria_init( mbedtls_aria_context *ctx );
 
 /**
  * \brief          This function releases and clears the specified ARIA context.
  *
- * \param ctx      The ARIA context to clear.
+ * \param ctx      The ARIA context to clear. This may be \c NULL, in which
+ *                 case this function returns immediately. If it is not \c NULL,
+ *                 it must point to an initialized ARIA context.
  */
 void mbedtls_aria_free( mbedtls_aria_context *ctx );
 
@@ -100,14 +108,16 @@
  * \brief          This function sets the encryption key.
  *
  * \param ctx      The ARIA context to which the key should be bound.
- * \param key      The encryption key.
- * \param keybits  The size of data passed in bits. Valid options are:
+ *                 This must be initialized.
+ * \param key      The encryption key. This must be a readable buffer
+ *                 of size \p keybits Bits.
+ * \param keybits  The size of \p key in Bits. Valid options are:
  *                 <ul><li>128 bits</li>
  *                 <li>192 bits</li>
  *                 <li>256 bits</li></ul>
  *
- * \return         \c 0 on success or #MBEDTLS_ERR_ARIA_INVALID_KEY_LENGTH
- *                 on failure.
+ * \return         \c 0 on success.
+ * \return         A negative error code on failure.
  */
 int mbedtls_aria_setkey_enc( mbedtls_aria_context *ctx,
                              const unsigned char *key,
@@ -117,13 +127,16 @@
  * \brief          This function sets the decryption key.
  *
  * \param ctx      The ARIA context to which the key should be bound.
- * \param key      The decryption key.
+ *                 This must be initialized.
+ * \param key      The decryption key. This must be a readable buffer
+ *                 of size \p keybits Bits.
  * \param keybits  The size of data passed. Valid options are:
  *                 <ul><li>128 bits</li>
  *                 <li>192 bits</li>
  *                 <li>256 bits</li></ul>
  *
- * \return         \c 0 on success, or #MBEDTLS_ERR_ARIA_INVALID_KEY_LENGTH on failure.
+ * \return         \c 0 on success.
+ * \return         A negative error code on failure.
  */
 int mbedtls_aria_setkey_dec( mbedtls_aria_context *ctx,
                              const unsigned char *key,
@@ -142,10 +155,12 @@
  *                 call to this API with the same context.
  *
  * \param ctx      The ARIA context to use for encryption or decryption.
+ *                 This must be initialized and bound to a key.
  * \param input    The 16-Byte buffer holding the input data.
  * \param output   The 16-Byte buffer holding the output data.
 
  * \return         \c 0 on success.
+ * \return         A negative error code on failure.
  */
 int mbedtls_aria_crypt_ecb( mbedtls_aria_context *ctx,
                             const unsigned char input[MBEDTLS_ARIA_BLOCKSIZE],
@@ -177,16 +192,21 @@
  *
  *
  * \param ctx      The ARIA context to use for encryption or decryption.
- * \param mode     The ARIA operation: #MBEDTLS_ARIA_ENCRYPT or
- *                 #MBEDTLS_ARIA_DECRYPT.
+ *                 This must be initialized and bound to a key.
+ * \param mode     The mode of operation. This must be either
+ *                 #MBEDTLS_ARIA_ENCRYPT for encryption, or
+ *                 #MBEDTLS_ARIA_DECRYPT for decryption.
  * \param length   The length of the input data in Bytes. This must be a
  *                 multiple of the block size (16 Bytes).
  * \param iv       Initialization vector (updated after use).
- * \param input    The buffer holding the input data.
- * \param output   The buffer holding the output data.
+ *                 This must be a readable buffer of size 16 Bytes.
+ * \param input    The buffer holding the input data. This must
+ *                 be a readable buffer of length \p length Bytes.
+ * \param output   The buffer holding the output data. This must
+ *                 be a writable buffer of length \p length Bytes.
  *
- * \return         \c 0 on success, or #MBEDTLS_ERR_ARIA_INVALID_INPUT_LENGTH
- *                 on failure.
+ * \return         \c 0 on success.
+ * \return         A negative error code on failure.
  */
 int mbedtls_aria_crypt_cbc( mbedtls_aria_context *ctx,
                             int mode,
@@ -221,15 +241,22 @@
  *
  *
  * \param ctx      The ARIA context to use for encryption or decryption.
- * \param mode     The ARIA operation: #MBEDTLS_ARIA_ENCRYPT or
- *                 #MBEDTLS_ARIA_DECRYPT.
- * \param length   The length of the input data.
+ *                 This must be initialized and bound to a key.
+ * \param mode     The mode of operation. This must be either
+ *                 #MBEDTLS_ARIA_ENCRYPT for encryption, or
+ *                 #MBEDTLS_ARIA_DECRYPT for decryption.
+ * \param length   The length of the input data \p input in Bytes.
  * \param iv_off   The offset in IV (updated after use).
+ *                 This must not be larger than 15.
  * \param iv       The initialization vector (updated after use).
- * \param input    The buffer holding the input data.
- * \param output   The buffer holding the output data.
+ *                 This must be a readable buffer of size 16 Bytes.
+ * \param input    The buffer holding the input data. This must
+ *                 be a readable buffer of length \p length Bytes.
+ * \param output   The buffer holding the output data. This must
+ *                 be a writable buffer of length \p length Bytes.
  *
  * \return         \c 0 on success.
+ * \return         A negative error code on failure.
  */
 int mbedtls_aria_crypt_cfb128( mbedtls_aria_context *ctx,
                                int mode,
@@ -299,17 +326,24 @@
  *             securely discarded as soon as it's no longer needed.
  *
  * \param ctx              The ARIA context to use for encryption or decryption.
- * \param length           The length of the input data.
- * \param nc_off           The offset in the current \p stream_block, for
- *                         resuming within the current cipher stream. The
- *                         offset pointer should be 0 at the start of a stream.
- * \param nonce_counter    The 128-bit nonce and counter.
- * \param stream_block     The saved stream block for resuming. This is
- *                         overwritten by the function.
- * \param input            The buffer holding the input data.
- * \param output           The buffer holding the output data.
+ *                         This must be initialized and bound to a key.
+ * \param length           The length of the input data \p input in Bytes.
+ * \param nc_off           The offset in Bytes in the current \p stream_block,
+ *                         for resuming within the current cipher stream. The
+ *                         offset pointer should be \c 0 at the start of a
+ *                         stream. This must not be larger than \c 15 Bytes.
+ * \param nonce_counter    The 128-bit nonce and counter. This must point to
+ *                         a read/write buffer of length \c 16 bytes.
+ * \param stream_block     The saved stream block for resuming. This must
+ *                         point to a read/write buffer of length \c 16 bytes.
+ *                         This is overwritten by the function.
+ * \param input            The buffer holding the input data. This must
+ *                         be a readable buffer of length \p length Bytes.
+ * \param output           The buffer holding the output data. This must
+ *                         be a writable buffer of length \p length Bytes.
  *
- * \return     \c 0 on success.
+ * \return                 \c 0 on success.
+ * \return                 A negative error code on failure.
  */
 int mbedtls_aria_crypt_ctr( mbedtls_aria_context *ctx,
                             size_t length,
diff --git a/include/mbedtls/asn1.h b/include/mbedtls/asn1.h
index 96c1c9a..f80acd7 100644
--- a/include/mbedtls/asn1.h
+++ b/include/mbedtls/asn1.h
@@ -66,7 +66,7 @@
  * - 0x02 -- tag indicating INTEGER
  * - 0x01 -- length in octets
  * - 0x05 -- value
- * Such sequences are typically read into \c ::mbedtls_x509_buf.
+ * Such sequences are typically read into Mbed TLS's \c mbedtls_x509_buf.
  * \{
  */
 #define MBEDTLS_ASN1_BOOLEAN                 0x01
diff --git a/include/mbedtls/asn1write.h b/include/mbedtls/asn1write.h
index 76c1780..dc81782 100644
--- a/include/mbedtls/asn1write.h
+++ b/include/mbedtls/asn1write.h
@@ -24,6 +24,12 @@
 #ifndef MBEDTLS_ASN1_WRITE_H
 #define MBEDTLS_ASN1_WRITE_H
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
 #include "asn1.h"
 
 #define MBEDTLS_ASN1_CHK_ADD(g, f)                      \
@@ -277,6 +283,28 @@
                                   const unsigned char *buf, size_t bits );
 
 /**
+ * \brief           This function writes a named bitstring tag
+ *                  (#MBEDTLS_ASN1_BIT_STRING) and value in ASN.1 format.
+ *
+ *                  As stated in RFC 5280 Appendix B, trailing zeroes are
+ *                  omitted when encoding named bitstrings in DER.
+ *
+ * \note            This function works backwards within the data buffer.
+ *
+ * \param p         The reference to the current position pointer.
+ * \param start     The start of the buffer which is used for bounds-checking.
+ * \param buf       The bitstring to write.
+ * \param bits      The total number of bits in the bitstring.
+ *
+ * \return          The number of bytes written to \p p on success.
+ * \return          A negative error code on failure.
+ */
+int mbedtls_asn1_write_named_bitstring( unsigned char **p,
+                                        unsigned char *start,
+                                        const unsigned char *buf,
+                                        size_t bits );
+
+/**
  * \brief           Write an octet string tag (#MBEDTLS_ASN1_OCTET_STRING)
  *                  and value in ASN.1 format.
  *
diff --git a/include/mbedtls/base64.h b/include/mbedtls/base64.h
index 7a64f52..0d02416 100644
--- a/include/mbedtls/base64.h
+++ b/include/mbedtls/base64.h
@@ -24,6 +24,12 @@
 #ifndef MBEDTLS_BASE64_H
 #define MBEDTLS_BASE64_H
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
 #include <stddef.h>
 
 #define MBEDTLS_ERR_BASE64_BUFFER_TOO_SMALL               -0x002A  /**< Output buffer too small. */
@@ -75,6 +81,7 @@
 int mbedtls_base64_decode( unsigned char *dst, size_t dlen, size_t *olen,
                    const unsigned char *src, size_t slen );
 
+#if defined(MBEDTLS_SELF_TEST)
 /**
  * \brief          Checkup routine
  *
@@ -82,6 +89,8 @@
  */
 int mbedtls_base64_self_test( int verbose );
 
+#endif /* MBEDTLS_SELF_TEST */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/mbedtls/bignum.h b/include/mbedtls/bignum.h
index 40cfab4..c4d7686 100644
--- a/include/mbedtls/bignum.h
+++ b/include/mbedtls/bignum.h
@@ -186,96 +186,115 @@
 mbedtls_mpi;
 
 /**
- * \brief           Initialize one MPI (make internal references valid)
- *                  This just makes it ready to be set or freed,
+ * \brief           Initialize an MPI context.
+ *
+ *                  This makes the MPI ready to be set or freed,
  *                  but does not define a value for the MPI.
  *
- * \param X         One MPI to initialize.
+ * \param X         The MPI context to initialize. This must not be \c NULL.
  */
 void mbedtls_mpi_init( mbedtls_mpi *X );
 
 /**
- * \brief          Unallocate one MPI
+ * \brief          This function frees the components of an MPI context.
  *
- * \param X        One MPI to unallocate.
+ * \param X        The MPI context to be cleared. This may be \c NULL,
+ *                 in which case this function is a no-op. If it is
+ *                 not \c NULL, it must point to an initialized MPI.
  */
 void mbedtls_mpi_free( mbedtls_mpi *X );
 
 /**
- * \brief          Enlarge to the specified number of limbs
+ * \brief          Enlarge an MPI to the specified number of limbs.
  *
- *                 This function does nothing if the MPI is already large enough.
+ * \note           This function does nothing if the MPI is
+ *                 already large enough.
  *
- * \param X        MPI to grow
- * \param nblimbs  The target number of limbs
+ * \param X        The MPI to grow. It must be initialized.
+ * \param nblimbs  The target number of limbs.
  *
- * \return         0 if successful,
- *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
+ * \return         Another negative error code on other kinds of failure.
  */
 int mbedtls_mpi_grow( mbedtls_mpi *X, size_t nblimbs );
 
 /**
- * \brief          Resize down, keeping at least the specified number of limbs
+ * \brief          This function resizes an MPI downwards, 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
+ * \param X        The MPI to shrink. This must point to an initialized MPI.
+ * \param nblimbs  The minimum number of limbs to keep.
  *
- * \return         0 if successful,
- *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
  *                 (this can only happen when resizing up).
+ * \return         Another negative error code on other kinds of failure.
  */
 int mbedtls_mpi_shrink( mbedtls_mpi *X, size_t nblimbs );
 
 /**
- * \brief          Copy the contents of Y into X
+ * \brief          Make a copy of an MPI.
  *
- * \param X        Destination MPI. It is enlarged if necessary.
- * \param Y        Source MPI.
+ * \param X        The destination MPI. This must point to an initialized MPI.
+ * \param Y        The source MPI. This must point to an initialized MPI.
  *
- * \return         0 if successful,
- *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \note           The limb-buffer in the destination MPI is enlarged
+ *                 if necessary to hold the value in the source MPI.
+ *
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
+ * \return         Another negative error code on other kinds of failure.
  */
 int mbedtls_mpi_copy( mbedtls_mpi *X, const mbedtls_mpi *Y );
 
 /**
- * \brief          Swap the contents of X and Y
+ * \brief          Swap the contents of two MPIs.
  *
- * \param X        First MPI value
- * \param Y        Second MPI value
+ * \param X        The first MPI. It must be initialized.
+ * \param Y        The second MPI. It must be initialized.
  */
 void mbedtls_mpi_swap( mbedtls_mpi *X, mbedtls_mpi *Y );
 
 /**
- * \brief          Safe conditional assignement X = Y if assign is 1
+ * \brief          Perform a safe conditional copy of MPI which doesn't
+ *                 reveal whether the condition was true or not.
  *
- * \param X        MPI to conditionally assign to
- * \param Y        Value to be assigned
- * \param assign   1: perform the assignment, 0: keep X's original value
- *
- * \return         0 if successful,
- *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
+ * \param X        The MPI to conditionally assign to. This must point
+ *                 to an initialized MPI.
+ * \param Y        The MPI to be assigned from. This must point to an
+ *                 initialized MPI.
+ * \param assign   The condition deciding whether to perform the
+ *                 assignment or not. Possible values:
+ *                 * \c 1: Perform the assignment `X = Y`.
+ *                 * \c 0: Keep the original value of \p X.
  *
  * \note           This function is equivalent to
- *                      if( assign ) mbedtls_mpi_copy( X, Y );
+ *                      `if( assign ) mbedtls_mpi_copy( X, Y );`
  *                 except that it avoids leaking any information about whether
  *                 the assignment was done or not (the above code may leak
  *                 information through branch prediction and/or memory access
  *                 patterns analysis).
+ *
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
+ * \return         Another negative error code on other kinds of failure.
  */
 int mbedtls_mpi_safe_cond_assign( mbedtls_mpi *X, const mbedtls_mpi *Y, unsigned char assign );
 
 /**
- * \brief          Safe conditional swap X <-> Y if swap is 1
+ * \brief          Perform a safe conditional swap which doesn't
+ *                 reveal whether the condition was true or not.
  *
- * \param X        First mbedtls_mpi value
- * \param Y        Second mbedtls_mpi value
- * \param assign   1: perform the swap, 0: keep X and Y's original values
- *
- * \return         0 if successful,
- *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
+ * \param X        The first MPI. This must be initialized.
+ * \param Y        The second MPI. This must be initialized.
+ * \param assign   The condition deciding whether to perform
+ *                 the swap or not. Possible values:
+ *                 * \c 1: Swap the values of \p X and \p Y.
+ *                 * \c 0: Keep the original values of \p X and \p Y.
  *
  * \note           This function is equivalent to
  *                      if( assign ) mbedtls_mpi_swap( X, Y );
@@ -283,415 +302,546 @@
  *                 the assignment was done or not (the above code may leak
  *                 information through branch prediction and/or memory access
  *                 patterns analysis).
+ *
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
+ * \return         Another negative error code on other kinds of failure.
+ *
  */
 int mbedtls_mpi_safe_cond_swap( mbedtls_mpi *X, mbedtls_mpi *Y, unsigned char assign );
 
 /**
- * \brief          Set value from integer
+ * \brief          Store integer value in MPI.
  *
- * \param X        MPI to set
- * \param z        Value to use
+ * \param X        The MPI to set. This must be initialized.
+ * \param z        The value to use.
  *
- * \return         0 if successful,
- *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
+ * \return         Another negative error code on other kinds of failure.
  */
 int mbedtls_mpi_lset( mbedtls_mpi *X, mbedtls_mpi_sint z );
 
 /**
- * \brief          Get a specific bit from X
+ * \brief          Get a specific bit from an MPI.
  *
- * \param X        MPI to use
- * \param pos      Zero-based index of the bit in X
+ * \param X        The MPI to query. This must be initialized.
+ * \param pos      Zero-based index of the bit to query.
  *
- * \return         Either a 0 or a 1
+ * \return         \c 0 or \c 1 on success, depending on whether bit \c pos
+ *                 of \c X is unset or set.
+ * \return         A negative error code on failure.
  */
 int mbedtls_mpi_get_bit( const mbedtls_mpi *X, size_t pos );
 
 /**
- * \brief          Set a bit of X to a specific value of 0 or 1
+ * \brief          Modify a specific bit in an MPI.
  *
- * \note           Will grow X if necessary to set a bit to 1 in a not yet
- *                 existing limb. Will not grow if bit should be set to 0
+ * \note           This function will grow the target MPI if necessary to set a
+ *                 bit to \c 1 in a not yet existing limb. It will not grow if
+ *                 the bit should be set to \c 0.
  *
- * \param X        MPI to use
- * \param pos      Zero-based index of the bit in X
- * \param val      The value to set the bit to (0 or 1)
+ * \param X        The MPI to modify. This must be initialized.
+ * \param pos      Zero-based index of the bit to modify.
+ * \param val      The desired value of bit \c pos: \c 0 or \c 1.
  *
- * \return         0 if successful,
- *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
- *                 MBEDTLS_ERR_MPI_BAD_INPUT_DATA if val is not 0 or 1
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
+ * \return         Another negative error code on other kinds of failure.
  */
 int mbedtls_mpi_set_bit( mbedtls_mpi *X, size_t pos, unsigned char val );
 
 /**
- * \brief          Return the number of zero-bits before the least significant
- *                 '1' bit
+ * \brief          Return the number of bits of value \c 0 before the
+ *                 least significant bit of value \c 1.
  *
- * Note: Thus also the zero-based index of the least significant '1' bit
+ * \note           This is the same as the zero-based index of
+ *                 the least significant bit of value \c 1.
  *
- * \param X        MPI to use
+ * \param X        The MPI to query.
+ *
+ * \return         The number of bits of value \c 0 before the least significant
+ *                 bit of value \c 1 in \p X.
  */
 size_t mbedtls_mpi_lsb( const mbedtls_mpi *X );
 
 /**
  * \brief          Return the number of bits up to and including the most
- *                 significant '1' bit'
+ *                 significant bit of value \c 1.
  *
- * Note: Thus also the one-based index of the most significant '1' bit
+ * * \note         This is same as the one-based index of the most
+ *                 significant bit of value \c 1.
  *
- * \param X        MPI to use
+ * \param X        The MPI to query. This must point to an initialized MPI.
+ *
+ * \return         The number of bits up to and including the most
+ *                 significant bit of value \c 1.
  */
 size_t mbedtls_mpi_bitlen( const mbedtls_mpi *X );
 
 /**
- * \brief          Return the total size in bytes
+ * \brief          Return the total size of an MPI value in bytes.
  *
- * \param X        MPI to use
+ * \param X        The MPI to use. This must point to an initialized MPI.
+ *
+ * \note           The value returned by this function may be less than
+ *                 the number of bytes used to store \p X internally.
+ *                 This happens if and only if there are trailing bytes
+ *                 of value zero.
+ *
+ * \return         The least number of bytes capable of storing
+ *                 the absolute value of \p X.
  */
 size_t mbedtls_mpi_size( const mbedtls_mpi *X );
 
 /**
- * \brief          Import from an ASCII string
+ * \brief          Import an MPI from an ASCII string.
  *
- * \param X        Destination MPI
- * \param radix    Input numeric base
- * \param s        Null-terminated string buffer
+ * \param X        The destination MPI. This must point to an initialized MPI.
+ * \param radix    The numeric base of the input string.
+ * \param s        Null-terminated string buffer.
  *
- * \return         0 if successful, or a MBEDTLS_ERR_MPI_XXX error code
+ * \return         \c 0 if successful.
+ * \return         A negative error code on failure.
  */
 int mbedtls_mpi_read_string( mbedtls_mpi *X, int radix, const char *s );
 
 /**
- * \brief          Export into an ASCII string
+ * \brief          Export an MPI to an ASCII string.
  *
- * \param X        Source MPI
- * \param radix    Output numeric base
- * \param buf      Buffer to write the string to
- * \param buflen   Length of buf
- * \param olen     Length of the string written, including final NUL byte
+ * \param X        The source MPI. This must point to an initialized MPI.
+ * \param radix    The numeric base of the output string.
+ * \param buf      The buffer to write the string to. This must be writable
+ *                 buffer of length \p buflen Bytes.
+ * \param buflen   The available size in Bytes of \p buf.
+ * \param olen     The address at which to store the length of the string
+ *                 written, including the  final \c NULL byte. This must
+ *                 not be \c NULL.
  *
- * \return         0 if successful, or a MBEDTLS_ERR_MPI_XXX error code.
- *                 *olen is always updated to reflect the amount
- *                 of data that has (or would have) been written.
+ * \note           You can call this function with `buflen == 0` to obtain the
+ *                 minimum required buffer size in `*olen`.
  *
- * \note           Call this function with buflen = 0 to obtain the
- *                 minimum required buffer size in *olen.
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if the target buffer \p buf
+ *                 is too small to hold the value of \p X in the desired base.
+ *                 In this case, `*olen` is nonetheless updated to contain the
+ *                 size of \p buf required for a successful call.
+ * \return         Another negative error code on different kinds of failure.
  */
 int mbedtls_mpi_write_string( const mbedtls_mpi *X, int radix,
                               char *buf, size_t buflen, size_t *olen );
 
 #if defined(MBEDTLS_FS_IO)
 /**
- * \brief          Read MPI from a line in an opened file
+ * \brief          Read an MPI from a line in an opened file.
  *
- * \param X        Destination MPI
- * \param radix    Input numeric base
- * \param fin      Input file handle
- *
- * \return         0 if successful, MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if
- *                 the file read buffer is too small or a
- *                 MBEDTLS_ERR_MPI_XXX error code
+ * \param X        The destination MPI. This must point to an initialized MPI.
+ * \param radix    The numeric base of the string representation used
+ *                 in the source line.
+ * \param fin      The input file handle to use. This must not be \c NULL.
  *
  * \note           On success, this function advances the file stream
  *                 to the end of the current line or to EOF.
  *
- *                 The function returns 0 on an empty line.
+ *                 The function returns \c 0 on an empty line.
  *
  *                 Leading whitespaces are ignored, as is a
- *                 '0x' prefix for radix 16.
+ *                 '0x' prefix for radix \c 16.
  *
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if the file read buffer
+ *                 is too small.
+ * \return         Another negative error code on failure.
  */
 int mbedtls_mpi_read_file( mbedtls_mpi *X, int radix, FILE *fin );
 
 /**
- * \brief          Write X into an opened file, or stdout if fout is NULL
+ * \brief          Export an MPI into an opened file.
  *
- * \param p        Prefix, can be NULL
- * \param X        Source MPI
- * \param radix    Output numeric base
- * \param fout     Output file handle (can be NULL)
+ * \param p        A string prefix to emit prior to the MPI data.
+ *                 For example, this might be a label, or "0x" when
+ *                 printing in base \c 16. This may be \c NULL if no prefix
+ *                 is needed.
+ * \param X        The source MPI. This must point to an initialized MPI.
+ * \param radix    The numeric base to be used in the emitted string.
+ * \param fout     The output file handle. This may be \c NULL, in which case
+ *                 the output is written to \c stdout.
  *
- * \return         0 if successful, or a MBEDTLS_ERR_MPI_XXX error code
- *
- * \note           Set fout == NULL to print X on the console.
+ * \return         \c 0 if successful.
+ * \return         A negative error code on failure.
  */
-int mbedtls_mpi_write_file( const char *p, const mbedtls_mpi *X, int radix, FILE *fout );
+int mbedtls_mpi_write_file( const char *p, const mbedtls_mpi *X,
+                            int radix, FILE *fout );
 #endif /* MBEDTLS_FS_IO */
 
 /**
- * \brief          Import X from unsigned binary data, big endian
+ * \brief          Import an MPI from unsigned big endian binary data.
  *
- * \param X        Destination MPI
- * \param buf      Input buffer
- * \param buflen   Input buffer size
+ * \param X        The destination MPI. This must point to an initialized MPI.
+ * \param buf      The input buffer. This must be a readable buffer of length
+ *                 \p buflen Bytes.
+ * \param buflen   The length of the input buffer \p p in Bytes.
  *
- * \return         0 if successful,
- *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
+ * \return         Another negative error code on different kinds of failure.
  */
-int mbedtls_mpi_read_binary( mbedtls_mpi *X, const unsigned char *buf, size_t buflen );
+int mbedtls_mpi_read_binary( mbedtls_mpi *X, const unsigned char *buf,
+                             size_t buflen );
+
+/**
+ * \brief          Import X from unsigned binary data, little endian
+ *
+ * \param X        The destination MPI. This must point to an initialized MPI.
+ * \param buf      The input buffer. This must be a readable buffer of length
+ *                 \p buflen Bytes.
+ * \param buflen   The length of the input buffer \p p in Bytes.
+ *
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
+ * \return         Another negative error code on different kinds of failure.
+ */
+int mbedtls_mpi_read_binary_le( mbedtls_mpi *X,
+                                const unsigned char *buf, size_t buflen );
 
 /**
  * \brief          Export X into unsigned binary data, big endian.
  *                 Always fills the whole buffer, which will start with zeros
  *                 if the number is smaller.
  *
- * \param X        Source MPI
- * \param buf      Output buffer
- * \param buflen   Output buffer size
+ * \param X        The source MPI. This must point to an initialized MPI.
+ * \param buf      The output buffer. This must be a writable buffer of length
+ *                 \p buflen Bytes.
+ * \param buflen   The size of the output buffer \p buf in Bytes.
  *
- * \return         0 if successful,
- *                 MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if buf isn't large enough
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if \p buf isn't
+ *                 large enough to hold the value of \p X.
+ * \return         Another negative error code on different kinds of failure.
  */
-int mbedtls_mpi_write_binary( const mbedtls_mpi *X, unsigned char *buf, size_t buflen );
+int mbedtls_mpi_write_binary( const mbedtls_mpi *X, unsigned char *buf,
+                              size_t buflen );
 
 /**
- * \brief          Left-shift: X <<= count
+ * \brief          Export X into unsigned binary data, little endian.
+ *                 Always fills the whole buffer, which will end with zeros
+ *                 if the number is smaller.
  *
- * \param X        MPI to shift
- * \param count    Amount to shift
+ * \param X        The source MPI. This must point to an initialized MPI.
+ * \param buf      The output buffer. This must be a writable buffer of length
+ *                 \p buflen Bytes.
+ * \param buflen   The size of the output buffer \p buf in Bytes.
  *
- * \return         0 if successful,
- *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if \p buf isn't
+ *                 large enough to hold the value of \p X.
+ * \return         Another negative error code on different kinds of failure.
+ */
+int mbedtls_mpi_write_binary_le( const mbedtls_mpi *X,
+                                 unsigned char *buf, size_t buflen );
+
+/**
+ * \brief          Perform a left-shift on an MPI: X <<= count
+ *
+ * \param X        The MPI to shift. This must point to an initialized MPI.
+ * \param count    The number of bits to shift by.
+ *
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return         Another negative error code on different kinds of failure.
  */
 int mbedtls_mpi_shift_l( mbedtls_mpi *X, size_t count );
 
 /**
- * \brief          Right-shift: X >>= count
+ * \brief          Perform a right-shift on an MPI: X >>= count
  *
- * \param X        MPI to shift
- * \param count    Amount to shift
+ * \param X        The MPI to shift. This must point to an initialized MPI.
+ * \param count    The number of bits to shift by.
  *
- * \return         0 if successful,
- *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return         Another negative error code on different kinds of failure.
  */
 int mbedtls_mpi_shift_r( mbedtls_mpi *X, size_t count );
 
 /**
- * \brief          Compare unsigned values
+ * \brief          Compare the absolute values of two MPIs.
  *
- * \param X        Left-hand MPI
- * \param Y        Right-hand MPI
+ * \param X        The left-hand MPI. This must point to an initialized MPI.
+ * \param Y        The right-hand MPI. This must point to an initialized MPI.
  *
- * \return         1 if |X| is greater than |Y|,
- *                -1 if |X| is lesser  than |Y| or
- *                 0 if |X| is equal to |Y|
+ * \return         \c 1 if `|X|` is greater than `|Y|`.
+ * \return         \c -1 if `|X|` is lesser than `|Y|`.
+ * \return         \c 0 if `|X|` is equal to `|Y|`.
  */
 int mbedtls_mpi_cmp_abs( const mbedtls_mpi *X, const mbedtls_mpi *Y );
 
 /**
- * \brief          Compare signed values
+ * \brief          Compare two MPIs.
  *
- * \param X        Left-hand MPI
- * \param Y        Right-hand MPI
+ * \param X        The left-hand MPI. This must point to an initialized MPI.
+ * \param Y        The right-hand MPI. This must point to an initialized MPI.
  *
- * \return         1 if X is greater than Y,
- *                -1 if X is lesser  than Y or
- *                 0 if X is equal to Y
+ * \return         \c 1 if \p X is greater than \p Y.
+ * \return         \c -1 if \p X is lesser than \p Y.
+ * \return         \c 0 if \p X is equal to \p Y.
  */
 int mbedtls_mpi_cmp_mpi( const mbedtls_mpi *X, const mbedtls_mpi *Y );
 
 /**
- * \brief          Compare signed values
+ * \brief          Compare an MPI with an integer.
  *
- * \param X        Left-hand MPI
- * \param z        The integer value to compare to
+ * \param X        The left-hand MPI. This must point to an initialized MPI.
+ * \param z        The integer value to compare \p X to.
  *
- * \return         1 if X is greater than z,
- *                -1 if X is lesser  than z or
- *                 0 if X is equal to z
+ * \return         \c 1 if \p X is greater than \p z.
+ * \return         \c -1 if \p X is lesser than \p z.
+ * \return         \c 0 if \p X is equal to \p z.
  */
 int mbedtls_mpi_cmp_int( const mbedtls_mpi *X, mbedtls_mpi_sint z );
 
 /**
- * \brief          Unsigned addition: X = |A| + |B|
+ * \brief          Perform an unsigned addition of MPIs: X = |A| + |B|
  *
- * \param X        Destination MPI
- * \param A        Left-hand MPI
- * \param B        Right-hand MPI
+ * \param X        The destination MPI. This must point to an initialized MPI.
+ * \param A        The first summand. This must point to an initialized MPI.
+ * \param B        The second summand. This must point to an initialized MPI.
  *
- * \return         0 if successful,
- *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return         Another negative error code on different kinds of failure.
  */
-int mbedtls_mpi_add_abs( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *B );
+int mbedtls_mpi_add_abs( mbedtls_mpi *X, const mbedtls_mpi *A,
+                         const mbedtls_mpi *B );
 
 /**
- * \brief          Unsigned subtraction: X = |A| - |B|
+ * \brief          Perform an unsigned subtraction of MPIs: X = |A| - |B|
  *
- * \param X        Destination MPI
- * \param A        Left-hand MPI
- * \param B        Right-hand MPI
+ * \param X        The destination MPI. This must point to an initialized MPI.
+ * \param A        The minuend. This must point to an initialized MPI.
+ * \param B        The subtrahend. This must point to an initialized MPI.
  *
- * \return         0 if successful,
- *                 MBEDTLS_ERR_MPI_NEGATIVE_VALUE if B is greater than A
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_NEGATIVE_VALUE if \p B is greater than \p A.
+ * \return         Another negative error code on different kinds of failure.
+ *
  */
-int mbedtls_mpi_sub_abs( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *B );
+int mbedtls_mpi_sub_abs( mbedtls_mpi *X, const mbedtls_mpi *A,
+                         const mbedtls_mpi *B );
 
 /**
- * \brief          Signed addition: X = A + B
+ * \brief          Perform a signed addition of MPIs: X = A + B
  *
- * \param X        Destination MPI
- * \param A        Left-hand MPI
- * \param B        Right-hand MPI
+ * \param X        The destination MPI. This must point to an initialized MPI.
+ * \param A        The first summand. This must point to an initialized MPI.
+ * \param B        The second summand. This must point to an initialized MPI.
  *
- * \return         0 if successful,
- *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return         Another negative error code on different kinds of failure.
  */
-int mbedtls_mpi_add_mpi( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *B );
+int mbedtls_mpi_add_mpi( mbedtls_mpi *X, const mbedtls_mpi *A,
+                         const mbedtls_mpi *B );
 
 /**
- * \brief          Signed subtraction: X = A - B
+ * \brief          Perform a signed subtraction of MPIs: X = A - B
  *
- * \param X        Destination MPI
- * \param A        Left-hand MPI
- * \param B        Right-hand MPI
+ * \param X        The destination MPI. This must point to an initialized MPI.
+ * \param A        The minuend. This must point to an initialized MPI.
+ * \param B        The subtrahend. This must point to an initialized MPI.
  *
- * \return         0 if successful,
- *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return         Another negative error code on different kinds of failure.
  */
-int mbedtls_mpi_sub_mpi( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *B );
+int mbedtls_mpi_sub_mpi( mbedtls_mpi *X, const mbedtls_mpi *A,
+                         const mbedtls_mpi *B );
 
 /**
- * \brief          Signed addition: X = A + b
+ * \brief          Perform a signed addition of an MPI and an integer: X = A + b
  *
- * \param X        Destination MPI
- * \param A        Left-hand MPI
- * \param b        The integer value to add
+ * \param X        The destination MPI. This must point to an initialized MPI.
+ * \param A        The first summand. This must point to an initialized MPI.
+ * \param b        The second summand.
  *
- * \return         0 if successful,
- *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return         Another negative error code on different kinds of failure.
  */
-int mbedtls_mpi_add_int( mbedtls_mpi *X, const mbedtls_mpi *A, mbedtls_mpi_sint b );
+int mbedtls_mpi_add_int( mbedtls_mpi *X, const mbedtls_mpi *A,
+                         mbedtls_mpi_sint b );
 
 /**
- * \brief          Signed subtraction: X = A - b
+ * \brief          Perform a signed subtraction of an MPI and an integer:
+ *                 X = A - b
  *
- * \param X        Destination MPI
- * \param A        Left-hand MPI
- * \param b        The integer value to subtract
+ * \param X        The destination MPI. This must point to an initialized MPI.
+ * \param A        The minuend. This must point to an initialized MPI.
+ * \param b        The subtrahend.
  *
- * \return         0 if successful,
- *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return         Another negative error code on different kinds of failure.
  */
-int mbedtls_mpi_sub_int( mbedtls_mpi *X, const mbedtls_mpi *A, mbedtls_mpi_sint b );
+int mbedtls_mpi_sub_int( mbedtls_mpi *X, const mbedtls_mpi *A,
+                         mbedtls_mpi_sint b );
 
 /**
- * \brief          Baseline multiplication: X = A * B
+ * \brief          Perform a multiplication of two MPIs: X = A * B
  *
- * \param X        Destination MPI
- * \param A        Left-hand MPI
- * \param B        Right-hand MPI
+ * \param X        The destination MPI. This must point to an initialized MPI.
+ * \param A        The first factor. This must point to an initialized MPI.
+ * \param B        The second factor. This must point to an initialized MPI.
  *
- * \return         0 if successful,
- *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return         Another negative error code on different kinds of failure.
+ *
  */
-int mbedtls_mpi_mul_mpi( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *B );
+int mbedtls_mpi_mul_mpi( mbedtls_mpi *X, const mbedtls_mpi *A,
+                         const mbedtls_mpi *B );
 
 /**
- * \brief          Baseline multiplication: X = A * b
+ * \brief          Perform a multiplication of an MPI with an unsigned integer:
+ *                 X = A * b
  *
- * \param X        Destination MPI
- * \param A        Left-hand MPI
- * \param b        The unsigned integer value to multiply with
+ * \param X        The destination MPI. This must point to an initialized MPI.
+ * \param A        The first factor. This must point to an initialized MPI.
+ * \param b        The second factor.
  *
- * \note           b is unsigned
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return         Another negative error code on different kinds of failure.
  *
- * \return         0 if successful,
- *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
  */
-int mbedtls_mpi_mul_int( mbedtls_mpi *X, const mbedtls_mpi *A, mbedtls_mpi_uint b );
+int mbedtls_mpi_mul_int( mbedtls_mpi *X, const mbedtls_mpi *A,
+                         mbedtls_mpi_uint b );
 
 /**
- * \brief          Division by mbedtls_mpi: A = Q * B + R
+ * \brief          Perform a division with remainder of two MPIs:
+ *                 A = Q * B + R
  *
- * \param Q        Destination MPI for the quotient
- * \param R        Destination MPI for the rest value
- * \param A        Left-hand MPI
- * \param B        Right-hand MPI
+ * \param Q        The destination MPI for the quotient.
+ *                 This may be \c NULL if the value of the
+ *                 quotient is not needed.
+ * \param R        The destination MPI for the remainder value.
+ *                 This may be \c NULL if the value of the
+ *                 remainder is not needed.
+ * \param A        The dividend. This must point to an initialized MPi.
+ * \param B        The divisor. This must point to an initialized MPI.
  *
- * \return         0 if successful,
- *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
- *                 MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if B == 0
- *
- * \note           Either Q or R can be NULL.
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
+ * \return         #MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if \p B equals zero.
+ * \return         Another negative error code on different kinds of failure.
  */
-int mbedtls_mpi_div_mpi( mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A, const mbedtls_mpi *B );
+int mbedtls_mpi_div_mpi( mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A,
+                         const mbedtls_mpi *B );
 
 /**
- * \brief          Division by int: A = Q * b + R
+ * \brief          Perform a division with remainder of an MPI by an integer:
+ *                 A = Q * b + R
  *
- * \param Q        Destination MPI for the quotient
- * \param R        Destination MPI for the rest value
- * \param A        Left-hand MPI
- * \param b        Integer to divide by
+ * \param Q        The destination MPI for the quotient.
+ *                 This may be \c NULL if the value of the
+ *                 quotient is not needed.
+ * \param R        The destination MPI for the remainder value.
+ *                 This may be \c NULL if the value of the
+ *                 remainder is not needed.
+ * \param A        The dividend. This must point to an initialized MPi.
+ * \param b        The divisor.
  *
- * \return         0 if successful,
- *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
- *                 MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if b == 0
- *
- * \note           Either Q or R can be NULL.
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
+ * \return         #MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if \p b equals zero.
+ * \return         Another negative error code on different kinds of failure.
  */
-int mbedtls_mpi_div_int( mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A, mbedtls_mpi_sint b );
+int mbedtls_mpi_div_int( mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A,
+                         mbedtls_mpi_sint b );
 
 /**
- * \brief          Modulo: R = A mod B
+ * \brief          Perform a modular reduction. R = A mod B
  *
- * \param R        Destination MPI for the rest value
- * \param A        Left-hand MPI
- * \param B        Right-hand MPI
+ * \param R        The destination MPI for the residue value.
+ *                 This must point to an initialized MPI.
+ * \param A        The MPI to compute the residue of.
+ *                 This must point to an initialized MPI.
+ * \param B        The base of the modular reduction.
+ *                 This must point to an initialized MPI.
  *
- * \return         0 if successful,
- *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
- *                 MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if B == 0,
- *                 MBEDTLS_ERR_MPI_NEGATIVE_VALUE if B < 0
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return         #MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if \p B equals zero.
+ * \return         #MBEDTLS_ERR_MPI_NEGATIVE_VALUE if \p B is negative.
+ * \return         Another negative error code on different kinds of failure.
+ *
  */
-int mbedtls_mpi_mod_mpi( mbedtls_mpi *R, const mbedtls_mpi *A, const mbedtls_mpi *B );
+int mbedtls_mpi_mod_mpi( mbedtls_mpi *R, const mbedtls_mpi *A,
+                         const mbedtls_mpi *B );
 
 /**
- * \brief          Modulo: r = A mod b
+ * \brief          Perform a modular reduction with respect to an integer.
+ *                 r = A mod b
  *
- * \param r        Destination mbedtls_mpi_uint
- * \param A        Left-hand MPI
- * \param b        Integer to divide by
+ * \param r        The address at which to store the residue.
+ *                 This must not be \c NULL.
+ * \param A        The MPI to compute the residue of.
+ *                 This must point to an initialized MPi.
+ * \param b        The integer base of the modular reduction.
  *
- * \return         0 if successful,
- *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
- *                 MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if b == 0,
- *                 MBEDTLS_ERR_MPI_NEGATIVE_VALUE if b < 0
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return         #MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if \p b equals zero.
+ * \return         #MBEDTLS_ERR_MPI_NEGATIVE_VALUE if \p b is negative.
+ * \return         Another negative error code on different kinds of failure.
  */
-int mbedtls_mpi_mod_int( mbedtls_mpi_uint *r, const mbedtls_mpi *A, mbedtls_mpi_sint b );
+int mbedtls_mpi_mod_int( mbedtls_mpi_uint *r, const mbedtls_mpi *A,
+                         mbedtls_mpi_sint b );
 
 /**
- * \brief          Sliding-window exponentiation: X = A^E mod N
+ * \brief          Perform a sliding-window exponentiation: X = A^E mod N
  *
- * \param X        Destination MPI
- * \param A        Left-hand MPI
- * \param E        Exponent MPI
- * \param N        Modular MPI
- * \param _RR      Speed-up MPI used for recalculations
+ * \param X        The destination MPI. This must point to an initialized MPI.
+ * \param A        The base of the exponentiation.
+ *                 This must point to an initialized MPI.
+ * \param E        The exponent MPI. This must point to an initialized MPI.
+ * \param N        The base for the modular reduction. This must point to an
+ *                 initialized MPI.
+ * \param _RR      A helper MPI depending solely on \p N which can be used to
+ *                 speed-up multiple modular exponentiations for the same value
+ *                 of \p N. This may be \c NULL. If it is not \c NULL, it must
+ *                 point to an initialized MPI. If it hasn't been used after
+ *                 the call to mbedtls_mpi_init(), this function will compute
+ *                 the helper value and store it in \p _RR for reuse on
+ *                 subsequent calls to this function. Otherwise, the function
+ *                 will assume that \p _RR holds the helper value set by a
+ *                 previous call to mbedtls_mpi_exp_mod(), and reuse it.
  *
- * \return         0 if successful,
- *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
- *                 MBEDTLS_ERR_MPI_BAD_INPUT_DATA if N is negative or even or
- *                 if E is negative
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return         #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if \c N is negative or
+ *                 even, or if \c E is negative.
+ * \return         Another negative error code on different kinds of failures.
  *
- * \note           _RR is used to avoid re-computing R*R mod N across
- *                 multiple calls, which speeds up things a bit. It can
- *                 be set to NULL if the extra performance is unneeded.
  */
-int mbedtls_mpi_exp_mod( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *E, const mbedtls_mpi *N, mbedtls_mpi *_RR );
+int mbedtls_mpi_exp_mod( mbedtls_mpi *X, const mbedtls_mpi *A,
+                         const mbedtls_mpi *E, const mbedtls_mpi *N,
+                         mbedtls_mpi *_RR );
 
 /**
- * \brief          Fill an MPI X with size bytes of random
+ * \brief          Fill an MPI with a number of random bytes.
  *
- * \param X        Destination MPI
- * \param size     Size in bytes
- * \param f_rng    RNG function
- * \param p_rng    RNG parameter
+ * \param X        The destination MPI. This must point to an initialized MPI.
+ * \param size     The number of random bytes to generate.
+ * \param f_rng    The RNG function to use. This must not be \c NULL.
+ * \param p_rng    The RNG parameter to be passed to \p f_rng. This may be
+ *                 \c NULL if \p f_rng doesn't need a context argument.
  *
- * \return         0 if successful,
- *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return         Another negative error code on failure.
  *
- * \note           The bytes obtained from the PRNG are interpreted
+ * \note           The bytes obtained from the RNG are interpreted
  *                 as a big-endian representation of an MPI; this can
  *                 be relevant in applications like deterministic ECDSA.
  */
@@ -700,30 +850,37 @@
                      void *p_rng );
 
 /**
- * \brief          Greatest common divisor: G = gcd(A, B)
+ * \brief          Compute the greatest common divisor: G = gcd(A, B)
  *
- * \param G        Destination MPI
- * \param A        Left-hand MPI
- * \param B        Right-hand MPI
+ * \param G        The destination MPI. This must point to an initialized MPI.
+ * \param A        The first operand. This must point to an initialized MPI.
+ * \param B        The second operand. This must point to an initialized MPI.
  *
- * \return         0 if successful,
- *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return         Another negative error code on different kinds of failure.
  */
-int mbedtls_mpi_gcd( mbedtls_mpi *G, const mbedtls_mpi *A, const mbedtls_mpi *B );
+int mbedtls_mpi_gcd( mbedtls_mpi *G, const mbedtls_mpi *A,
+                     const mbedtls_mpi *B );
 
 /**
- * \brief          Modular inverse: X = A^-1 mod N
+ * \brief          Compute the modular inverse: X = A^-1 mod N
  *
- * \param X        Destination MPI
- * \param A        Left-hand MPI
- * \param N        Right-hand MPI
+ * \param X        The destination MPI. This must point to an initialized MPI.
+ * \param A        The MPI to calculate the modular inverse of. This must point
+ *                 to an initialized MPI.
+ * \param N        The base of the modular inversion. This must point to an
+ *                 initialized MPI.
  *
- * \return         0 if successful,
- *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
- *                 MBEDTLS_ERR_MPI_BAD_INPUT_DATA if N is <= 1,
-                   MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if A has no inverse mod N.
+ * \return         \c 0 if successful.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return         #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if \p N is less than
+ *                 or equal to one.
+ * \return         #MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if \p has no modular inverse
+ *                 with respect to \p N.
  */
-int mbedtls_mpi_inv_mod( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *N );
+int mbedtls_mpi_inv_mod( mbedtls_mpi *X, const mbedtls_mpi *A,
+                         const mbedtls_mpi *N );
 
 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
 #if defined(MBEDTLS_DEPRECATED_WARNING)
@@ -732,19 +889,23 @@
 #define MBEDTLS_DEPRECATED
 #endif
 /**
- * \brief          Miller-Rabin primality test with error probability of
- *                 2<sup>-80</sup>
+ * \brief          Perform a Miller-Rabin primality test with error
+ *                 probability of 2<sup>-80</sup>.
  *
  * \deprecated     Superseded by mbedtls_mpi_is_prime_ext() which allows
  *                 specifying the number of Miller-Rabin rounds.
  *
- * \param X        MPI to check
- * \param f_rng    RNG function
- * \param p_rng    RNG parameter
+ * \param X        The MPI to check for primality.
+ *                 This must point to an initialized MPI.
+ * \param f_rng    The RNG function to use. This must not be \c NULL.
+ * \param p_rng    The RNG parameter to be passed to \p f_rng.
+ *                 This may be \c NULL if \p f_rng doesn't use a
+ *                 context parameter.
  *
- * \return         0 if successful (probably prime),
- *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
- *                 MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if X is not prime
+ * \return         \c 0 if successful, i.e. \p X is probably prime.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return         #MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if \p X is not prime.
+ * \return         Another negative error code on other kinds of failure.
  */
 MBEDTLS_DEPRECATED int mbedtls_mpi_is_prime( const mbedtls_mpi *X,
                           int (*f_rng)(void *, unsigned char *, size_t),
@@ -764,16 +925,20 @@
  *                 case when mbedtls_mpi_gen_prime calls this function), then
  *                 \p rounds can be much lower.
  *
- * \param X        MPI to check
- * \param rounds   Number of bases to perform Miller-Rabin primality test for.
- *                 The probability of returning 0 on a composite is at most
- *                 2<sup>-2*\p rounds</sup>.
- * \param f_rng    RNG function
- * \param p_rng    RNG parameter
+ * \param X        The MPI to check for primality.
+ *                 This must point to an initialized MPI.
+ * \param rounds   The number of bases to perform the Miller-Rabin primality
+ *                 test for. The probability of returning 0 on a composite is
+ *                 at most 2<sup>-2*\p rounds</sup>.
+ * \param f_rng    The RNG function to use. This must not be \c NULL.
+ * \param p_rng    The RNG parameter to be passed to \p f_rng.
+ *                 This may be \c NULL if \p f_rng doesn't use
+ *                 a context parameter.
  *
- * \return         0 if successful (probably prime),
- *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
- *                 MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if X is not prime
+ * \return         \c 0 if successful, i.e. \p X is probably prime.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return         #MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if \p X is not prime.
+ * \return         Another negative error code on other kinds of failure.
  */
 int mbedtls_mpi_is_prime_ext( const mbedtls_mpi *X, int rounds,
                               int (*f_rng)(void *, unsigned char *, size_t),
@@ -790,23 +955,30 @@
 } mbedtls_mpi_gen_prime_flag_t;
 
 /**
- * \brief          Prime number generation
+ * \brief          Generate a prime number.
  *
- * \param X        Destination MPI
- * \param nbits    Required size of X in bits
- *                 ( 3 <= nbits <= MBEDTLS_MPI_MAX_BITS )
- * \param flags    Mask of flags of type #mbedtls_mpi_gen_prime_flag_t
- * \param f_rng    RNG function
- * \param p_rng    RNG parameter
+ * \param X        The destination MPI to store the generated prime in.
+ *                 This must point to an initialized MPi.
+ * \param nbits    The required size of the destination MPI in bits.
+ *                 This must be between \c 3 and #MBEDTLS_MPI_MAX_BITS.
+ * \param flags    A mask of flags of type #mbedtls_mpi_gen_prime_flag_t.
+ * \param f_rng    The RNG function to use. This must not be \c NULL.
+ * \param p_rng    The RNG parameter to be passed to \p f_rng.
+ *                 This may be \c NULL if \p f_rng doesn't use
+ *                 a context parameter.
  *
- * \return         0 if successful (probably prime),
- *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed,
- *                 MBEDTLS_ERR_MPI_BAD_INPUT_DATA if nbits is < 3
+ * \return         \c 0 if successful, in which case \p X holds a
+ *                 probably prime number.
+ * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
+ * \return         #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if `nbits` is not between
+ *                 \c 3 and #MBEDTLS_MPI_MAX_BITS.
  */
 int mbedtls_mpi_gen_prime( mbedtls_mpi *X, size_t nbits, int flags,
                    int (*f_rng)(void *, unsigned char *, size_t),
                    void *p_rng );
 
+#if defined(MBEDTLS_SELF_TEST)
+
 /**
  * \brief          Checkup routine
  *
@@ -814,6 +986,8 @@
  */
 int mbedtls_mpi_self_test( int verbose );
 
+#endif /* MBEDTLS_SELF_TEST */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/mbedtls/blowfish.h b/include/mbedtls/blowfish.h
index 82b772a..f01573d 100644
--- a/include/mbedtls/blowfish.h
+++ b/include/mbedtls/blowfish.h
@@ -33,6 +33,8 @@
 #include <stddef.h>
 #include <stdint.h>
 
+#include "platform_util.h"
+
 #define MBEDTLS_BLOWFISH_ENCRYPT     1
 #define MBEDTLS_BLOWFISH_DECRYPT     0
 #define MBEDTLS_BLOWFISH_MAX_KEY_BITS     448
@@ -40,14 +42,17 @@
 #define MBEDTLS_BLOWFISH_ROUNDS      16         /**< Rounds to use. When increasing this value, make sure to extend the initialisation vectors */
 #define MBEDTLS_BLOWFISH_BLOCKSIZE   8          /* Blowfish uses 64 bit blocks */
 
-#define MBEDTLS_ERR_BLOWFISH_INVALID_KEY_LENGTH                -0x0016  /**< Invalid key length. */
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#define MBEDTLS_ERR_BLOWFISH_INVALID_KEY_LENGTH   MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( -0x0016 )
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
+#define MBEDTLS_ERR_BLOWFISH_BAD_INPUT_DATA -0x0016 /**< Bad input data. */
+
+#define MBEDTLS_ERR_BLOWFISH_INVALID_INPUT_LENGTH -0x0018 /**< Invalid data input length. */
 
 /* MBEDTLS_ERR_BLOWFISH_HW_ACCEL_FAILED is deprecated and should not be used.
  */
 #define MBEDTLS_ERR_BLOWFISH_HW_ACCEL_FAILED                   -0x0017  /**< Blowfish hardware accelerator failed. */
 
-#define MBEDTLS_ERR_BLOWFISH_INVALID_INPUT_LENGTH              -0x0018  /**< Invalid data input length. */
-
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -71,40 +76,53 @@
 #endif /* MBEDTLS_BLOWFISH_ALT */
 
 /**
- * \brief          Initialize Blowfish context
+ * \brief          Initialize a Blowfish context.
  *
- * \param ctx      Blowfish context to be initialized
+ * \param ctx      The Blowfish context to be initialized.
+ *                 This must not be \c NULL.
  */
 void mbedtls_blowfish_init( mbedtls_blowfish_context *ctx );
 
 /**
- * \brief          Clear Blowfish context
+ * \brief          Clear a Blowfish context.
  *
- * \param ctx      Blowfish context to be cleared
+ * \param ctx      The Blowfish context to be cleared.
+ *                 This may be \c NULL, in which case this function
+ *                 returns immediately. If it is not \c NULL, it must
+ *                 point to an initialized Blowfish context.
  */
 void mbedtls_blowfish_free( mbedtls_blowfish_context *ctx );
 
 /**
- * \brief          Blowfish key schedule
+ * \brief          Perform a Blowfish key schedule operation.
  *
- * \param ctx      Blowfish context to be initialized
- * \param key      encryption key
- * \param keybits  must be between 32 and 448 bits
+ * \param ctx      The Blowfish context to perform the key schedule on.
+ * \param key      The encryption key. This must be a readable buffer of
+ *                 length \p keybits Bits.
+ * \param keybits  The length of \p key in Bits. This must be between
+ *                 \c 32 and \c 448 and a multiple of \c 8.
  *
- * \return         0 if successful, or MBEDTLS_ERR_BLOWFISH_INVALID_KEY_LENGTH
+ * \return         \c 0 if successful.
+ * \return         A negative error code on failure.
  */
 int mbedtls_blowfish_setkey( mbedtls_blowfish_context *ctx, const unsigned char *key,
                      unsigned int keybits );
 
 /**
- * \brief          Blowfish-ECB block encryption/decryption
+ * \brief          Perform a Blowfish-ECB block encryption/decryption operation.
  *
- * \param ctx      Blowfish context
- * \param mode     MBEDTLS_BLOWFISH_ENCRYPT or MBEDTLS_BLOWFISH_DECRYPT
- * \param input    8-byte input block
- * \param output   8-byte output block
+ * \param ctx      The Blowfish context to use. This must be initialized
+ *                 and bound to a key.
+ * \param mode     The mode of operation. Possible values are
+ *                 #MBEDTLS_BLOWFISH_ENCRYPT for encryption, or
+ *                 #MBEDTLS_BLOWFISH_DECRYPT for decryption.
+ * \param input    The input block. This must be a readable buffer
+ *                 of size \c 8 Bytes.
+ * \param output   The output block. This must be a writable buffer
+ *                 of size \c 8 Bytes.
  *
- * \return         0 if successful
+ * \return         \c 0 if successful.
+ * \return         A negative error code on failure.
  */
 int mbedtls_blowfish_crypt_ecb( mbedtls_blowfish_context *ctx,
                         int mode,
@@ -113,9 +131,7 @@
 
 #if defined(MBEDTLS_CIPHER_MODE_CBC)
 /**
- * \brief          Blowfish-CBC buffer encryption/decryption
- *                 Length should be a multiple of the block
- *                 size (8 bytes)
+ * \brief          Perform a Blowfish-CBC buffer encryption/decryption operation.
  *
  * \note           Upon exit, the content of the IV is updated so that you can
  *                 call the function same function again on the following
@@ -125,15 +141,22 @@
  *                 IV, you should either save it manually or use the cipher
  *                 module instead.
  *
- * \param ctx      Blowfish context
- * \param mode     MBEDTLS_BLOWFISH_ENCRYPT or MBEDTLS_BLOWFISH_DECRYPT
- * \param length   length of the input data
- * \param iv       initialization vector (updated after use)
- * \param input    buffer holding the input data
- * \param output   buffer holding the output data
+ * \param ctx      The Blowfish context to use. This must be initialized
+ *                 and bound to a key.
+ * \param mode     The mode of operation. Possible values are
+ *                 #MBEDTLS_BLOWFISH_ENCRYPT for encryption, or
+ *                 #MBEDTLS_BLOWFISH_DECRYPT for decryption.
+ * \param length   The length of the input data in Bytes. This must be
+ *                 multiple of \c 8.
+ * \param iv       The initialization vector. This must be a read/write buffer
+ *                 of length \c 8 Bytes. It is updated by this function.
+ * \param input    The input data. This must be a readable buffer of length
+ *                 \p length Bytes.
+ * \param output   The output data. This must be a writable buffer of length
+ *                 \p length Bytes.
  *
- * \return         0 if successful, or
- *                 MBEDTLS_ERR_BLOWFISH_INVALID_INPUT_LENGTH
+ * \return         \c 0 if successful.
+ * \return         A negative error code on failure.
  */
 int mbedtls_blowfish_crypt_cbc( mbedtls_blowfish_context *ctx,
                         int mode,
@@ -145,7 +168,7 @@
 
 #if defined(MBEDTLS_CIPHER_MODE_CFB)
 /**
- * \brief          Blowfish CFB buffer encryption/decryption.
+ * \brief          Perform a Blowfish CFB buffer encryption/decryption operation.
  *
  * \note           Upon exit, the content of the IV is updated so that you can
  *                 call the function same function again on the following
@@ -155,15 +178,25 @@
  *                 IV, you should either save it manually or use the cipher
  *                 module instead.
  *
- * \param ctx      Blowfish context
- * \param mode     MBEDTLS_BLOWFISH_ENCRYPT or MBEDTLS_BLOWFISH_DECRYPT
- * \param length   length of the input data
- * \param iv_off   offset in IV (updated after use)
- * \param iv       initialization vector (updated after use)
- * \param input    buffer holding the input data
- * \param output   buffer holding the output data
+ * \param ctx      The Blowfish context to use. This must be initialized
+ *                 and bound to a key.
+ * \param mode     The mode of operation. Possible values are
+ *                 #MBEDTLS_BLOWFISH_ENCRYPT for encryption, or
+ *                 #MBEDTLS_BLOWFISH_DECRYPT for decryption.
+ * \param length   The length of the input data in Bytes.
+ * \param iv_off   The offset in the initialiation vector.
+ *                 The value pointed to must be smaller than \c 8 Bytes.
+ *                 It is updated by this function to support the aforementioned
+ *                 streaming usage.
+ * \param iv       The initialization vector. This must be a read/write buffer
+ *                 of size \c 8 Bytes. It is updated after use.
+ * \param input    The input data. This must be a readable buffer of length
+ *                 \p length Bytes.
+ * \param output   The output data. This must be a writable buffer of length
+ *                 \p length Bytes.
  *
- * \return         0 if successful
+ * \return         \c 0 if successful.
+ * \return         A negative error code on failure.
  */
 int mbedtls_blowfish_crypt_cfb64( mbedtls_blowfish_context *ctx,
                           int mode,
@@ -176,7 +209,7 @@
 
 #if defined(MBEDTLS_CIPHER_MODE_CTR)
 /**
- * \brief               Blowfish-CTR buffer encryption/decryption
+ * \brief      Perform a Blowfish-CTR buffer encryption/decryption operation.
  *
  * \warning    You must never reuse a nonce value with the same key. Doing so
  *             would void the encryption for the two messages encrypted with
@@ -219,18 +252,24 @@
  *             content must not be written to insecure storage and should be
  *             securely discarded as soon as it's no longer needed.
  *
- * \param ctx           Blowfish context
- * \param length        The length of the data
+ * \param ctx           The Blowfish context to use. This must be initialized
+ *                      and bound to a key.
+ * \param length        The length of the input data in Bytes.
  * \param nc_off        The offset in the current stream_block (for resuming
- *                      within current cipher stream). The offset pointer to
- *                      should be 0 at the start of a stream.
- * \param nonce_counter The 64-bit nonce and counter.
- * \param stream_block  The saved stream-block for resuming. Is overwritten
- *                      by the function.
- * \param input         The input data stream
- * \param output        The output data stream
+ *                      within current cipher stream). The offset pointer
+ *                      should be \c 0 at the start of a stream and must be
+ *                      smaller than \c 8. It is updated by this function.
+ * \param nonce_counter The 64-bit nonce and counter. This must point to a
+ *                      read/write buffer of length \c 8 Bytes.
+ * \param stream_block  The saved stream-block for resuming. This must point to
+ *                      a read/write buffer of length \c 8 Bytes.
+ * \param input         The input data. This must be a readable buffer of
+ *                      length \p length Bytes.
+ * \param output        The output data. This must be a writable buffer of
+ *                      length \p length Bytes.
  *
- * \return         0 if successful
+ * \return              \c 0 if successful.
+ * \return              A negative error code on failure.
  */
 int mbedtls_blowfish_crypt_ctr( mbedtls_blowfish_context *ctx,
                         size_t length,
diff --git a/include/mbedtls/bn_mul.h b/include/mbedtls/bn_mul.h
index 0af694c..c33bd8d 100644
--- a/include/mbedtls/bn_mul.h
+++ b/include/mbedtls/bn_mul.h
@@ -38,6 +38,12 @@
 #ifndef MBEDTLS_BN_MUL_H
 #define MBEDTLS_BN_MUL_H
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
 #include "bignum.h"
 
 #if defined(MBEDTLS_HAVE_ASM)
@@ -170,19 +176,19 @@
 
 #define MULADDC_INIT                        \
     asm(                                    \
-        "xorq   %%r8, %%r8          \n\t"
+        "xorq   %%r8, %%r8\n"
 
 #define MULADDC_CORE                        \
-        "movq   (%%rsi), %%rax      \n\t"   \
-        "mulq   %%rbx               \n\t"   \
-        "addq   $8,      %%rsi      \n\t"   \
-        "addq   %%rcx,   %%rax      \n\t"   \
-        "movq   %%r8,    %%rcx      \n\t"   \
-        "adcq   $0,      %%rdx      \n\t"   \
-        "nop                        \n\t"   \
-        "addq   %%rax,   (%%rdi)    \n\t"   \
-        "adcq   %%rdx,   %%rcx      \n\t"   \
-        "addq   $8,      %%rdi      \n\t"
+        "movq   (%%rsi), %%rax\n"           \
+        "mulq   %%rbx\n"                    \
+        "addq   $8, %%rsi\n"                \
+        "addq   %%rcx, %%rax\n"             \
+        "movq   %%r8, %%rcx\n"              \
+        "adcq   $0, %%rdx\n"                \
+        "nop    \n"                         \
+        "addq   %%rax, (%%rdi)\n"           \
+        "adcq   %%rdx, %%rcx\n"             \
+        "addq   $8, %%rdi\n"
 
 #define MULADDC_STOP                        \
         : "+c" (c), "+D" (d), "+S" (s)      \
@@ -750,7 +756,7 @@
         "sw     $10, %2         \n\t"   \
         : "=m" (c), "=m" (d), "=m" (s)                      \
         : "m" (s), "m" (d), "m" (c), "m" (b)                \
-        : "$9", "$10", "$11", "$12", "$13", "$14", "$15"    \
+        : "$9", "$10", "$11", "$12", "$13", "$14", "$15", "lo", "hi" \
     );
 
 #endif /* MIPS */
diff --git a/include/mbedtls/camellia.h b/include/mbedtls/camellia.h
index 1555867..3eeb663 100644
--- a/include/mbedtls/camellia.h
+++ b/include/mbedtls/camellia.h
@@ -33,11 +33,17 @@
 #include <stddef.h>
 #include <stdint.h>
 
+#include "platform_util.h"
+
 #define MBEDTLS_CAMELLIA_ENCRYPT     1
 #define MBEDTLS_CAMELLIA_DECRYPT     0
 
-#define MBEDTLS_ERR_CAMELLIA_INVALID_KEY_LENGTH           -0x0024  /**< Invalid key length. */
-#define MBEDTLS_ERR_CAMELLIA_INVALID_INPUT_LENGTH         -0x0026  /**< Invalid data input length. */
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#define MBEDTLS_ERR_CAMELLIA_INVALID_KEY_LENGTH   MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( -0x0024 )
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
+#define MBEDTLS_ERR_CAMELLIA_BAD_INPUT_DATA -0x0024 /**< Bad input data. */
+
+#define MBEDTLS_ERR_CAMELLIA_INVALID_INPUT_LENGTH -0x0026 /**< Invalid data input length. */
 
 /* MBEDTLS_ERR_CAMELLIA_HW_ACCEL_FAILED is deprecated and should not be used.
  */
@@ -66,52 +72,68 @@
 #endif /* MBEDTLS_CAMELLIA_ALT */
 
 /**
- * \brief          Initialize CAMELLIA context
+ * \brief          Initialize a CAMELLIA context.
  *
- * \param ctx      CAMELLIA context to be initialized
+ * \param ctx      The CAMELLIA context to be initialized.
+ *                 This must not be \c NULL.
  */
 void mbedtls_camellia_init( mbedtls_camellia_context *ctx );
 
 /**
- * \brief          Clear CAMELLIA context
+ * \brief          Clear a CAMELLIA context.
  *
- * \param ctx      CAMELLIA context to be cleared
+ * \param ctx      The CAMELLIA context to be cleared. This may be \c NULL,
+ *                 in which case this function returns immediately. If it is not
+ *                 \c NULL, it must be initialized.
  */
 void mbedtls_camellia_free( mbedtls_camellia_context *ctx );
 
 /**
- * \brief          CAMELLIA key schedule (encryption)
+ * \brief          Perform a CAMELLIA key schedule operation for encryption.
  *
- * \param ctx      CAMELLIA context to be initialized
- * \param key      encryption key
- * \param keybits  must be 128, 192 or 256
+ * \param ctx      The CAMELLIA context to use. This must be initialized.
+ * \param key      The encryption key to use. This must be a readable buffer
+ *                 of size \p keybits Bits.
+ * \param keybits  The length of \p key in Bits. This must be either \c 128,
+ *                 \c 192 or \c 256.
  *
- * \return         0 if successful, or MBEDTLS_ERR_CAMELLIA_INVALID_KEY_LENGTH
+ * \return         \c 0 if successful.
+ * \return         A negative error code on failure.
  */
-int mbedtls_camellia_setkey_enc( mbedtls_camellia_context *ctx, const unsigned char *key,
-                         unsigned int keybits );
+int mbedtls_camellia_setkey_enc( mbedtls_camellia_context *ctx,
+                                 const unsigned char *key,
+                                 unsigned int keybits );
 
 /**
- * \brief          CAMELLIA key schedule (decryption)
+ * \brief          Perform a CAMELLIA key schedule operation for decryption.
  *
- * \param ctx      CAMELLIA context to be initialized
- * \param key      decryption key
- * \param keybits  must be 128, 192 or 256
+ * \param ctx      The CAMELLIA context to use. This must be initialized.
+ * \param key      The decryption key. This must be a readable buffer
+ *                 of size \p keybits Bits.
+ * \param keybits  The length of \p key in Bits. This must be either \c 128,
+ *                 \c 192 or \c 256.
  *
- * \return         0 if successful, or MBEDTLS_ERR_CAMELLIA_INVALID_KEY_LENGTH
+ * \return         \c 0 if successful.
+ * \return         A negative error code on failure.
  */
-int mbedtls_camellia_setkey_dec( mbedtls_camellia_context *ctx, const unsigned char *key,
-                         unsigned int keybits );
+int mbedtls_camellia_setkey_dec( mbedtls_camellia_context *ctx,
+                                 const unsigned char *key,
+                                 unsigned int keybits );
 
 /**
- * \brief          CAMELLIA-ECB block encryption/decryption
+ * \brief          Perform a CAMELLIA-ECB block encryption/decryption operation.
  *
- * \param ctx      CAMELLIA context
- * \param mode     MBEDTLS_CAMELLIA_ENCRYPT or MBEDTLS_CAMELLIA_DECRYPT
- * \param input    16-byte input block
- * \param output   16-byte output block
+ * \param ctx      The CAMELLIA context to use. This must be initialized
+ *                 and bound to a key.
+ * \param mode     The mode of operation. This must be either
+ *                 #MBEDTLS_CAMELLIA_ENCRYPT or #MBEDTLS_CAMELLIA_DECRYPT.
+ * \param input    The input block. This must be a readable buffer
+ *                 of size \c 16 Bytes.
+ * \param output   The output block. This must be a writable buffer
+ *                 of size \c 16 Bytes.
  *
- * \return         0 if successful
+ * \return         \c 0 if successful.
+ * \return         A negative error code on failure.
  */
 int mbedtls_camellia_crypt_ecb( mbedtls_camellia_context *ctx,
                     int mode,
@@ -120,9 +142,7 @@
 
 #if defined(MBEDTLS_CIPHER_MODE_CBC)
 /**
- * \brief          CAMELLIA-CBC buffer encryption/decryption
- *                 Length should be a multiple of the block
- *                 size (16 bytes)
+ * \brief          Perform a CAMELLIA-CBC buffer encryption/decryption operation.
  *
  * \note           Upon exit, the content of the IV is updated so that you can
  *                 call the function same function again on the following
@@ -132,15 +152,22 @@
  *                 IV, you should either save it manually or use the cipher
  *                 module instead.
  *
- * \param ctx      CAMELLIA context
- * \param mode     MBEDTLS_CAMELLIA_ENCRYPT or MBEDTLS_CAMELLIA_DECRYPT
- * \param length   length of the input data
- * \param iv       initialization vector (updated after use)
- * \param input    buffer holding the input data
- * \param output   buffer holding the output data
+ * \param ctx      The CAMELLIA context to use. This must be initialized
+ *                 and bound to a key.
+ * \param mode     The mode of operation. This must be either
+ *                 #MBEDTLS_CAMELLIA_ENCRYPT or #MBEDTLS_CAMELLIA_DECRYPT.
+ * \param length   The length in Bytes of the input data \p input.
+ *                 This must be a multiple of \c 16 Bytes.
+ * \param iv       The initialization vector. This must be a read/write buffer
+ *                 of length \c 16 Bytes. It is updated to allow streaming
+ *                 use as explained above.
+ * \param input    The buffer holding the input data. This must point to a
+ *                 readable buffer of length \p length Bytes.
+ * \param output   The buffer holding the output data. This must point to a
+ *                 writable buffer of length \p length Bytes.
  *
- * \return         0 if successful, or
- *                 MBEDTLS_ERR_CAMELLIA_INVALID_INPUT_LENGTH
+ * \return         \c 0 if successful.
+ * \return         A negative error code on failure.
  */
 int mbedtls_camellia_crypt_cbc( mbedtls_camellia_context *ctx,
                     int mode,
@@ -152,11 +179,14 @@
 
 #if defined(MBEDTLS_CIPHER_MODE_CFB)
 /**
- * \brief          CAMELLIA-CFB128 buffer encryption/decryption
+ * \brief          Perform a CAMELLIA-CFB128 buffer encryption/decryption
+ *                 operation.
  *
- * Note: Due to the nature of CFB you should use the same key schedule for
- * both encryption and decryption. So a context initialized with
- * mbedtls_camellia_setkey_enc() for both MBEDTLS_CAMELLIA_ENCRYPT and CAMELLIE_DECRYPT.
+ * \note           Due to the nature of CFB mode, you should use the same
+ *                 key for both encryption and decryption. In particular, calls
+ *                 to this function should be preceded by a key-schedule via
+ *                 mbedtls_camellia_setkey_enc() regardless of whether \p mode
+ *                 is #MBEDTLS_CAMELLIA_ENCRYPT or #MBEDTLS_CAMELLIA_DECRYPT.
  *
  * \note           Upon exit, the content of the IV is updated so that you can
  *                 call the function same function again on the following
@@ -166,16 +196,24 @@
  *                 IV, you should either save it manually or use the cipher
  *                 module instead.
  *
- * \param ctx      CAMELLIA context
- * \param mode     MBEDTLS_CAMELLIA_ENCRYPT or MBEDTLS_CAMELLIA_DECRYPT
- * \param length   length of the input data
- * \param iv_off   offset in IV (updated after use)
- * \param iv       initialization vector (updated after use)
- * \param input    buffer holding the input data
- * \param output   buffer holding the output data
+ * \param ctx      The CAMELLIA context to use. This must be initialized
+ *                 and bound to a key.
+ * \param mode     The mode of operation. This must be either
+ *                 #MBEDTLS_CAMELLIA_ENCRYPT or #MBEDTLS_CAMELLIA_DECRYPT.
+ * \param length   The length of the input data \p input. Any value is allowed.
+ * \param iv_off   The current offset in the IV. This must be smaller
+ *                 than \c 16 Bytes. It is updated after this call to allow
+ *                 the aforementioned streaming usage.
+ * \param iv       The initialization vector. This must be a read/write buffer
+ *                 of length \c 16 Bytes. It is updated after this call to
+ *                 allow the aforementioned streaming usage.
+ * \param input    The buffer holding the input data. This must be a readable
+ *                 buffer of size \p length Bytes.
+ * \param output   The buffer to hold the output data. This must be a writable
+ *                 buffer of length \p length Bytes.
  *
- * \return         0 if successful, or
- *                 MBEDTLS_ERR_CAMELLIA_INVALID_INPUT_LENGTH
+ * \return         \c 0 if successful.
+ * \return         A negative error code on failure.
  */
 int mbedtls_camellia_crypt_cfb128( mbedtls_camellia_context *ctx,
                        int mode,
@@ -188,11 +226,13 @@
 
 #if defined(MBEDTLS_CIPHER_MODE_CTR)
 /**
- * \brief               CAMELLIA-CTR buffer encryption/decryption
+ * \brief      Perform a CAMELLIA-CTR buffer encryption/decryption operation.
  *
- * Note: Due to the nature of CTR you should use the same key schedule for
- * both encryption and decryption. So a context initialized with
- * mbedtls_camellia_setkey_enc() for both MBEDTLS_CAMELLIA_ENCRYPT and MBEDTLS_CAMELLIA_DECRYPT.
+ * *note       Due to the nature of CTR mode, you should use the same
+ *             key for both encryption and decryption. In particular, calls
+ *             to this function should be preceded by a key-schedule via
+ *             mbedtls_camellia_setkey_enc() regardless of whether \p mode
+ *             is #MBEDTLS_CAMELLIA_ENCRYPT or #MBEDTLS_CAMELLIA_DECRYPT.
  *
  * \warning    You must never reuse a nonce value with the same key. Doing so
  *             would void the encryption for the two messages encrypted with
@@ -215,41 +255,49 @@
  *             per-message nonce, handled by yourself, and the second one
  *             updated by this function internally.
  *
- *             For example, you might reserve the first 12 bytes for the
- *             per-message nonce, and the last 4 bytes for internal use. In that
- *             case, before calling this function on a new message you need to
- *             set the first 12 bytes of \p nonce_counter to your chosen nonce
- *             value, the last 4 to 0, and \p nc_off to 0 (which will cause \p
- *             stream_block to be ignored). That way, you can encrypt at most
- *             2**96 messages of up to 2**32 blocks each with the same key.
+ *             For example, you might reserve the first \c 12 Bytes for the
+ *             per-message nonce, and the last \c 4 Bytes for internal use.
+ *             In that case, before calling this function on a new message you
+ *             need to set the first \c 12 Bytes of \p nonce_counter to your
+ *             chosen nonce value, the last four to \c 0, and \p nc_off to \c 0
+ *             (which will cause \p stream_block to be ignored). That way, you
+ *             can encrypt at most \c 2**96 messages of up to \c 2**32 blocks
+ *             each  with the same key.
  *
  *             The per-message nonce (or information sufficient to reconstruct
- *             it) needs to be communicated with the ciphertext and must be unique.
- *             The recommended way to ensure uniqueness is to use a message
- *             counter. An alternative is to generate random nonces, but this
- *             limits the number of messages that can be securely encrypted:
- *             for example, with 96-bit random nonces, you should not encrypt
- *             more than 2**32 messages with the same key.
+ *             it) needs to be communicated with the ciphertext and must be
+ *             unique. The recommended way to ensure uniqueness is to use a
+ *             message counter. An alternative is to generate random nonces,
+ *             but this limits the number of messages that can be securely
+ *             encrypted: for example, with 96-bit random nonces, you should
+ *             not encrypt more than 2**32 messages with the same key.
  *
  *             Note that for both stategies, sizes are measured in blocks and
- *             that a CAMELLIA block is 16 bytes.
+ *             that a CAMELLIA block is \c 16 Bytes.
  *
  * \warning    Upon return, \p stream_block contains sensitive data. Its
  *             content must not be written to insecure storage and should be
  *             securely discarded as soon as it's no longer needed.
  *
- * \param ctx           CAMELLIA context
- * \param length        The length of the data
- * \param nc_off        The offset in the current stream_block (for resuming
+ * \param ctx           The CAMELLIA context to use. This must be initialized
+ *                      and bound to a key.
+ * \param length        The length of the input data \p input in Bytes.
+ *                      Any value is allowed.
+ * \param nc_off        The offset in the current \p stream_block (for resuming
  *                      within current cipher stream). The offset pointer to
- *                      should be 0 at the start of a stream.
- * \param nonce_counter The 128-bit nonce and counter.
- * \param stream_block  The saved stream-block for resuming. Is overwritten
- *                      by the function.
- * \param input         The input data stream
- * \param output        The output data stream
+ *                      should be \c 0 at the start of a stream. It is updated
+ *                      at the end of this call.
+ * \param nonce_counter The 128-bit nonce and counter. This must be a read/write
+ *                      buffer of length \c 16 Bytes.
+ * \param stream_block  The saved stream-block for resuming. This must be a
+ *                      read/write buffer of length \c 16 Bytes.
+ * \param input         The input data stream. This must be a readable buffer of
+ *                      size \p length Bytes.
+ * \param output        The output data stream. This must be a writable buffer
+ *                      of size \p length Bytes.
  *
- * \return         0 if successful
+ * \return              \c 0 if successful.
+ * \return              A negative error code on failure.
  */
 int mbedtls_camellia_crypt_ctr( mbedtls_camellia_context *ctx,
                        size_t length,
@@ -260,6 +308,8 @@
                        unsigned char *output );
 #endif /* MBEDTLS_CIPHER_MODE_CTR */
 
+#if defined(MBEDTLS_SELF_TEST)
+
 /**
  * \brief          Checkup routine
  *
@@ -267,6 +317,8 @@
  */
 int mbedtls_camellia_self_test( int verbose );
 
+#endif /* MBEDTLS_SELF_TEST */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h
index dfb1b5e..f03e3b5 100644
--- a/include/mbedtls/ccm.h
+++ b/include/mbedtls/ccm.h
@@ -49,6 +49,12 @@
 #ifndef MBEDTLS_CCM_H
 #define MBEDTLS_CCM_H
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
 #include "cipher.h"
 
 #define MBEDTLS_ERR_CCM_BAD_INPUT       -0x000D /**< Bad input parameters to the function. */
@@ -57,7 +63,6 @@
 /* MBEDTLS_ERR_CCM_HW_ACCEL_FAILED is deprecated and should not be used. */
 #define MBEDTLS_ERR_CCM_HW_ACCEL_FAILED -0x0011 /**< CCM hardware accelerator failed. */
 
-
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -85,7 +90,7 @@
  *                  to make references valid, and prepare the context
  *                  for mbedtls_ccm_setkey() or mbedtls_ccm_free().
  *
- * \param ctx       The CCM context to initialize.
+ * \param ctx       The CCM context to initialize. This must not be \c NULL.
  */
 void mbedtls_ccm_init( mbedtls_ccm_context *ctx );
 
@@ -93,9 +98,10 @@
  * \brief           This function initializes the CCM context set in the
  *                  \p ctx parameter and sets the encryption key.
  *
- * \param ctx       The CCM context to initialize.
+ * \param ctx       The CCM context to initialize. This must be an initialized
+ *                  context.
  * \param cipher    The 128-bit block cipher to use.
- * \param key       The encryption key.
+ * \param key       The encryption key. This must not be \c NULL.
  * \param keybits   The key size in bits. This must be acceptable by the cipher.
  *
  * \return          \c 0 on success.
@@ -110,7 +116,8 @@
  * \brief   This function releases and clears the specified CCM context
  *          and underlying cipher sub-context.
  *
- * \param ctx       The CCM context to clear.
+ * \param ctx       The CCM context to clear. If this is \c NULL, the function
+ *                  has no effect. Otherwise, this must be initialized.
  */
 void mbedtls_ccm_free( mbedtls_ccm_context *ctx );
 
@@ -123,19 +130,27 @@
  *                  \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 ctx       The CCM context to use for encryption. This must be
+ *                  initialized and bound to a key.
  * \param length    The length of the input data in Bytes.
- * \param iv        Initialization vector (nonce).
+ * \param iv        The initialization vector (nonce). This must be a readable
+ *                  buffer of at least \p iv_len Bytes.
  * \param iv_len    The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12,
  *                  or 13. The length L of the message length field is
  *                  15 - \p iv_len.
- * \param add       The additional data field.
+ * \param add       The additional data field. If \p add_len is greater than
+ *                  zero, \p add must be a readable buffer of at least that
+ *                  length.
  * \param add_len   The length of additional data in Bytes.
- *                  Must be less than 2^16 - 2^8.
- * \param input     The buffer holding the input data.
- * \param output    The buffer holding the output data.
- *                  Must be at least \p length Bytes wide.
- * \param tag       The buffer holding the authentication field.
+ *                  This must be less than `2^16 - 2^8`.
+ * \param input     The buffer holding the input data. If \p length is greater
+ *                  than zero, \p input must be a readable buffer of at least
+ *                  that length.
+ * \param output    The buffer holding the output data. If \p length is greater
+ *                  than zero, \p output must be a writable buffer of at least
+ *                  that length.
+ * \param tag       The buffer holding the authentication field. This must be a
+ *                  readable buffer of at least \p tag_len Bytes.
  * \param tag_len   The length of the authentication field to generate in Bytes:
  *                  4, 6, 8, 10, 12, 14 or 16.
  *
@@ -161,23 +176,30 @@
  *                  the tag length has to be encoded into the \p iv passed to
  *                  this function.
  *
- * \param ctx       The CCM context to use for encryption.
+ * \param ctx       The CCM context to use for encryption. This must be
+ *                  initialized and bound to a key.
  * \param length    The length of the input data in Bytes.
- * \param iv        Initialization vector (nonce).
+ * \param iv        The initialization vector (nonce). This must be a readable
+ *                  buffer of at least \p iv_len Bytes.
  * \param iv_len    The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12,
  *                  or 13. The length L of the message length field is
  *                  15 - \p iv_len.
- * \param add       The additional data field.
+ * \param add       The additional data field. This must be a readable buffer of
+ *                  at least \p add_len Bytes.
  * \param add_len   The length of additional data in Bytes.
- *                  Must be less than 2^16 - 2^8.
- * \param input     The buffer holding the input data.
- * \param output    The buffer holding the output data.
- *                  Must be at least \p length Bytes wide.
- * \param tag       The buffer holding the authentication field.
+ *                  This must be less than 2^16 - 2^8.
+ * \param input     The buffer holding the input data. If \p length is greater
+ *                  than zero, \p input must be a readable buffer of at least
+ *                  that length.
+ * \param output    The buffer holding the output data. If \p length is greater
+ *                  than zero, \p output must be a writable buffer of at least
+ *                  that length.
+ * \param tag       The buffer holding the authentication field. This must be a
+ *                  readable buffer of at least \p tag_len Bytes.
  * \param tag_len   The length of the authentication field to generate in Bytes:
  *                  0, 4, 6, 8, 10, 12, 14 or 16.
  *
- * \warning         Passing 0 as \p tag_len means that the message is no
+ * \warning         Passing \c 0 as \p tag_len means that the message is no
  *                  longer authenticated.
  *
  * \return          \c 0 on success.
@@ -193,20 +215,27 @@
  * \brief           This function performs a CCM authenticated decryption of a
  *                  buffer.
  *
- * \param ctx       The CCM context to use for decryption.
+ * \param ctx       The CCM context to use for decryption. This must be
+ *                  initialized and bound to a key.
  * \param length    The length of the input data in Bytes.
- * \param iv        Initialization vector (nonce).
+ * \param iv        The initialization vector (nonce). This must be a readable
+ *                  buffer of at least \p iv_len Bytes.
  * \param iv_len    The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12,
  *                  or 13. The length L of the message length field is
  *                  15 - \p iv_len.
- * \param add       The additional data field.
+ * \param add       The additional data field. This must be a readable buffer
+ *                  of at least that \p add_len Bytes..
  * \param add_len   The length of additional data in Bytes.
- *                  Must be less than 2^16 - 2^8.
- * \param input     The buffer holding the input data.
- * \param output    The buffer holding the output data.
- *                  Must be at least \p length Bytes wide.
- * \param tag       The buffer holding the authentication field.
- * \param tag_len   The length of the authentication field in Bytes.
+ *                  This must be less than 2^16 - 2^8.
+ * \param input     The buffer holding the input data. If \p length is greater
+ *                  than zero, \p input must be a readable buffer of at least
+ *                  that length.
+ * \param output    The buffer holding the output data. If \p length is greater
+ *                  than zero, \p output must be a writable buffer of at least
+ *                  that length.
+ * \param tag       The buffer holding the authentication field. This must be a
+ *                  readable buffer of at least \p tag_len Bytes.
+ * \param tag_len   The length of the authentication field to generate in Bytes:
  *                  4, 6, 8, 10, 12, 14 or 16.
  *
  * \return          \c 0 on success. This indicates that the message is authentic.
@@ -228,23 +257,30 @@
  *                  this function as \p tag_len. (\p tag needs to be adjusted
  *                  accordingly.)
  *
- * \param ctx       The CCM context to use for decryption.
+ * \param ctx       The CCM context to use for decryption. This must be
+ *                  initialized and bound to a key.
  * \param length    The length of the input data in Bytes.
- * \param iv        Initialization vector (nonce).
+ * \param iv        The initialization vector (nonce). This must be a readable
+ *                  buffer of at least \p iv_len Bytes.
  * \param iv_len    The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12,
  *                  or 13. The length L of the message length field is
  *                  15 - \p iv_len.
- * \param add       The additional data field.
+ * \param add       The additional data field. This must be a readable buffer of
+ *                  at least that \p add_len Bytes.
  * \param add_len   The length of additional data in Bytes.
- *                  Must be less than 2^16 - 2^8.
- * \param input     The buffer holding the input data.
- * \param output    The buffer holding the output data.
- *                  Must be at least \p length Bytes wide.
- * \param tag       The buffer holding the authentication field.
+ *                  This must be less than 2^16 - 2^8.
+ * \param input     The buffer holding the input data. If \p length is greater
+ *                  than zero, \p input must be a readable buffer of at least
+ *                  that length.
+ * \param output    The buffer holding the output data. If \p length is greater
+ *                  than zero, \p output must be a writable buffer of at least
+ *                  that length.
+ * \param tag       The buffer holding the authentication field. This must be a
+ *                  readable buffer of at least \p tag_len Bytes.
  * \param tag_len   The length of the authentication field in Bytes.
  *                  0, 4, 6, 8, 10, 12, 14 or 16.
  *
- * \warning         Passing 0 as \p tag_len means that the message is no
+ * \warning         Passing \c 0 as \p tag_len means that the message is nos
  *                  longer authenticated.
  *
  * \return          \c 0 on success.
diff --git a/include/mbedtls/certs.h b/include/mbedtls/certs.h
index 8dab7b5..b7c5708 100644
--- a/include/mbedtls/certs.h
+++ b/include/mbedtls/certs.h
@@ -24,6 +24,12 @@
 #ifndef MBEDTLS_CERTS_H
 #define MBEDTLS_CERTS_H
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
 #include <stddef.h>
 
 #ifdef __cplusplus
diff --git a/include/mbedtls/chacha20.h b/include/mbedtls/chacha20.h
index 529f22d..2ae5e6e 100644
--- a/include/mbedtls/chacha20.h
+++ b/include/mbedtls/chacha20.h
@@ -83,13 +83,18 @@
  *                  \c mbedtls_chacha20_free().
  *
  * \param ctx       The ChaCha20 context to initialize.
+ *                  This must not be \c NULL.
  */
 void mbedtls_chacha20_init( mbedtls_chacha20_context *ctx );
 
 /**
- * \brief           This function releases and clears the specified ChaCha20 context.
+ * \brief           This function releases and clears the specified
+ *                  ChaCha20 context.
  *
- * \param ctx       The ChaCha20 context to clear.
+ * \param ctx       The ChaCha20 context to clear. This may be \c NULL,
+ *                  in which case this function is a no-op. If it is not
+ *                  \c NULL, it must point to an initialized context.
+ *
  */
 void mbedtls_chacha20_free( mbedtls_chacha20_context *ctx );
 
@@ -102,7 +107,9 @@
  *                  \c mbedtls_chacha_update().
  *
  * \param ctx       The ChaCha20 context to which the key should be bound.
- * \param key       The encryption/decryption key. Must be 32 bytes in length.
+ *                  It must be initialized.
+ * \param key       The encryption/decryption key. This must be \c 32 Bytes
+ *                  in length.
  *
  * \return          \c 0 on success.
  * \return          #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or key is NULL.
@@ -121,8 +128,9 @@
  *                  messages encrypted with the same nonce and key.
  *
  * \param ctx       The ChaCha20 context to which the nonce should be bound.
- * \param nonce     The nonce. Must be 12 bytes in size.
- * \param counter   The initial counter value. This is usually 0.
+ *                  It must be initialized and bound to a key.
+ * \param nonce     The nonce. This must be \c 12 Bytes in size.
+ * \param counter   The initial counter value. This is usually \c 0.
  *
  * \return          \c 0 on success.
  * \return          #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or nonce is
@@ -150,16 +158,16 @@
  *                  key and nonce.
  *
  * \param ctx       The ChaCha20 context to use for encryption or decryption.
- * \param size      The length of the input data in bytes.
+ *                  It must be initialized and bound to a key and nonce.
+ * \param size      The length of the input data in Bytes.
  * \param input     The buffer holding the input data.
- *                  This pointer can be NULL if size == 0.
+ *                  This pointer can be \c NULL if `size == 0`.
  * \param output    The buffer holding the output data.
- *                  Must be able to hold \p size bytes.
- *                  This pointer can be NULL if size == 0.
+ *                  This must be able to hold \p size Bytes.
+ *                  This pointer can be \c NULL if `size == 0`.
  *
  * \return          \c 0 on success.
- * \return          #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if the ctx, input, or
- *                  output pointers are NULL.
+ * \return          A negative error code on failure.
  */
 int mbedtls_chacha20_update( mbedtls_chacha20_context *ctx,
                              size_t size,
@@ -180,19 +188,19 @@
  * \note            The \p input and \p output pointers must either be equal or
  *                  point to non-overlapping buffers.
  *
- * \param key       The encryption/decryption key. Must be 32 bytes in length.
- * \param nonce     The nonce. Must be 12 bytes in size.
- * \param counter   The initial counter value. This is usually 0.
- * \param size      The length of the input data in bytes.
+ * \param key       The encryption/decryption key.
+ *                  This must be \c 32 Bytes in length.
+ * \param nonce     The nonce. This must be \c 12 Bytes in size.
+ * \param counter   The initial counter value. This is usually \c 0.
+ * \param size      The length of the input data in Bytes.
  * \param input     The buffer holding the input data.
- *                  This pointer can be NULL if size == 0.
+ *                  This pointer can be \c NULL if `size == 0`.
  * \param output    The buffer holding the output data.
- *                  Must be able to hold \p size bytes.
- *                  This pointer can be NULL if size == 0.
+ *                  This must be able to hold \p size Bytes.
+ *                  This pointer can be \c NULL if `size == 0`.
  *
  * \return          \c 0 on success.
- * \return          #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if key, nonce, input,
- *                  or output is NULL.
+ * \return          A negative error code on failure.
  */
 int mbedtls_chacha20_crypt( const unsigned char key[32],
                             const unsigned char nonce[12],
diff --git a/include/mbedtls/chachapoly.h b/include/mbedtls/chachapoly.h
index 7de6f4e..49e615d 100644
--- a/include/mbedtls/chachapoly.h
+++ b/include/mbedtls/chachapoly.h
@@ -115,27 +115,29 @@
  *                  all previous outputs of \c mbedtls_chachapoly_update(),
  *                  otherwise you can now safely use the plaintext.
  *
- * \param ctx       The ChachaPoly context to initialize.
+ * \param ctx       The ChachaPoly context to initialize. Must not be \c NULL.
  */
 void mbedtls_chachapoly_init( mbedtls_chachapoly_context *ctx );
 
 /**
- * \brief           This function releases and clears the specified ChaCha20-Poly1305 context.
+ * \brief           This function releases and clears the specified
+ *                  ChaCha20-Poly1305 context.
  *
- * \param ctx       The ChachaPoly context to clear.
+ * \param ctx       The ChachaPoly context to clear. This may be \c NULL, in which
+ *                  case this function is a no-op.
  */
 void mbedtls_chachapoly_free( mbedtls_chachapoly_context *ctx );
 
 /**
- * \brief           This function sets the ChaCha20-Poly1305 symmetric encryption key.
+ * \brief           This function sets the ChaCha20-Poly1305
+ *                  symmetric encryption key.
  *
  * \param ctx       The ChaCha20-Poly1305 context to which the key should be
- *                  bound.
- * \param key       The 256-bit (32 bytes) key.
+ *                  bound. This must be initialized.
+ * \param key       The \c 256 Bit (\c 32 Bytes) key.
  *
  * \return          \c 0 on success.
- * \return          #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
- *                  if \p ctx or \p key are NULL.
+ * \return          A negative error code on failure.
  */
 int mbedtls_chachapoly_setkey( mbedtls_chachapoly_context *ctx,
                                const unsigned char key[32] );
@@ -155,14 +157,15 @@
  * \warning         Decryption with the piecewise API is discouraged, see the
  *                  warning on \c mbedtls_chachapoly_init().
  *
- * \param ctx       The ChaCha20-Poly1305 context.
- * \param nonce     The nonce/IV to use for the message. Must be 12 bytes.
+ * \param ctx       The ChaCha20-Poly1305 context. This must be initialized
+ *                  and bound to a key.
+ * \param nonce     The nonce/IV to use for the message.
+ *                  This must be a redable buffer of length \c 12 Bytes.
  * \param mode      The operation to perform: #MBEDTLS_CHACHAPOLY_ENCRYPT or
  *                  #MBEDTLS_CHACHAPOLY_DECRYPT (discouraged, see warning).
  *
  * \return          \c 0 on success.
- * \return          #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
- *                  if \p ctx or \p mac are NULL.
+ * \return          A negative error code on failure.
  */
 int mbedtls_chachapoly_starts( mbedtls_chachapoly_context *ctx,
                                const unsigned char nonce[12],
@@ -193,11 +196,12 @@
  * \warning         Decryption with the piecewise API is discouraged, see the
  *                  warning on \c mbedtls_chachapoly_init().
  *
- * \param ctx       The ChaCha20-Poly1305 context to use.
- * \param aad_len   The length (in bytes) of the AAD. The length has no
+ * \param ctx       The ChaCha20-Poly1305 context. This must be initialized
+ *                  and bound to a key.
+ * \param aad_len   The length in Bytes of the AAD. The length has no
  *                  restrictions.
  * \param aad       Buffer containing the AAD.
- *                  This pointer can be NULL if aad_len == 0.
+ *                  This pointer can be \c NULL if `aad_len == 0`.
  *
  * \return          \c 0 on success.
  * \return          #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
@@ -227,20 +231,19 @@
  * \warning         Decryption with the piecewise API is discouraged, see the
  *                  warning on \c mbedtls_chachapoly_init().
  *
- * \param ctx       The ChaCha20-Poly1305 context to use.
+ * \param ctx       The ChaCha20-Poly1305 context to use. This must be initialized.
  * \param len       The length (in bytes) of the data to encrypt or decrypt.
  * \param input     The buffer containing the data to encrypt or decrypt.
- *                  This pointer can be NULL if len == 0.
- * \param output    The buffer to where the encrypted or decrypted data is written.
- *                  Must be able to hold \p len bytes.
- *                  This pointer can be NULL if len == 0.
+ *                  This pointer can be \c NULL if `len == 0`.
+ * \param output    The buffer to where the encrypted or decrypted data is
+ *                  written. This must be able to hold \p len bytes.
+ *                  This pointer can be \c NULL if `len == 0`.
  *
  * \return          \c 0 on success.
- * \return          #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
- *                  if \p ctx, \p input, or \p output are NULL.
  * \return          #MBEDTLS_ERR_CHACHAPOLY_BAD_STATE
  *                  if the operation has not been started or has been
  *                  finished.
+ * \return          Another negative error code on other kinds of failure.
  */
 int mbedtls_chachapoly_update( mbedtls_chachapoly_context *ctx,
                                size_t len,
@@ -251,18 +254,17 @@
  * \brief           This function finished the ChaCha20-Poly1305 operation and
  *                  generates the MAC (authentication tag).
  *
- * \param ctx       The ChaCha20-Poly1305 context to use.
+ * \param ctx       The ChaCha20-Poly1305 context to use. This must be initialized.
  * \param mac       The buffer to where the 128-bit (16 bytes) MAC is written.
  *
  * \warning         Decryption with the piecewise API is discouraged, see the
  *                  warning on \c mbedtls_chachapoly_init().
  *
  * \return          \c 0 on success.
- * \return          #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
- *                  if \p ctx or \p mac are NULL.
  * \return          #MBEDTLS_ERR_CHACHAPOLY_BAD_STATE
  *                  if the operation has not been started or has been
  *                  finished.
+ * \return          Another negative error code on other kinds of failure.
  */
 int mbedtls_chachapoly_finish( mbedtls_chachapoly_context *ctx,
                                unsigned char mac[16] );
@@ -280,20 +282,21 @@
  *                  and key.
  *
  * \param ctx       The ChaCha20-Poly1305 context to use (holds the key).
+ *                  This must be initialized.
  * \param length    The length (in bytes) of the data to encrypt or decrypt.
  * \param nonce     The 96-bit (12 bytes) nonce/IV to use.
- * \param aad       The buffer containing the additional authenticated data (AAD).
- *                  This pointer can be NULL if aad_len == 0.
+ * \param aad       The buffer containing the additional authenticated
+ *                  data (AAD). This pointer can be \c NULL if `aad_len == 0`.
  * \param aad_len   The length (in bytes) of the AAD data to process.
  * \param input     The buffer containing the data to encrypt or decrypt.
- *                  This pointer can be NULL if ilen == 0.
- * \param output    The buffer to where the encrypted or decrypted data is written.
- *                  This pointer can be NULL if ilen == 0.
- * \param tag       The buffer to where the computed 128-bit (16 bytes) MAC is written.
+ *                  This pointer can be \c NULL if `ilen == 0`.
+ * \param output    The buffer to where the encrypted or decrypted data
+ *                  is written. This pointer can be \c NULL if `ilen == 0`.
+ * \param tag       The buffer to where the computed 128-bit (16 bytes) MAC
+ *                  is written. This must not be \c NULL.
  *
  * \return          \c 0 on success.
- * \return          #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
- *                  if one or more of the required parameters are NULL.
+ * \return          A negative error code on failure.
  */
 int mbedtls_chachapoly_encrypt_and_tag( mbedtls_chachapoly_context *ctx,
                                         size_t length,
@@ -312,22 +315,22 @@
  *                  \c mbedtls_chachapoly_setkey().
  *
  * \param ctx       The ChaCha20-Poly1305 context to use (holds the key).
- * \param length    The length (in bytes) of the data to decrypt.
- * \param nonce     The 96-bit (12 bytes) nonce/IV to use.
+ * \param length    The length (in Bytes) of the data to decrypt.
+ * \param nonce     The \c 96 Bit (\c 12 bytes) nonce/IV to use.
  * \param aad       The buffer containing the additional authenticated data (AAD).
- *                  This pointer can be NULL if aad_len == 0.
+ *                  This pointer can be \c NULL if `aad_len == 0`.
  * \param aad_len   The length (in bytes) of the AAD data to process.
  * \param tag       The buffer holding the authentication tag.
+ *                  This must be a readable buffer of length \c 16 Bytes.
  * \param input     The buffer containing the data to decrypt.
- *                  This pointer can be NULL if ilen == 0.
+ *                  This pointer can be \c NULL if `ilen == 0`.
  * \param output    The buffer to where the decrypted data is written.
- *                  This pointer can be NULL if ilen == 0.
+ *                  This pointer can be \c NULL if `ilen == 0`.
  *
  * \return          \c 0 on success.
- * \return          #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
- *                  if one or more of the required parameters are NULL.
  * \return          #MBEDTLS_ERR_CHACHAPOLY_AUTH_FAILED
  *                  if the data was not authentic.
+ * \return          Another negative error code on other kinds of failure.
  */
 int mbedtls_chachapoly_auth_decrypt( mbedtls_chachapoly_context *ctx,
                                      size_t length,
diff --git a/include/mbedtls/check_config.h b/include/mbedtls/check_config.h
index 508c00a..0fa74f0 100644
--- a/include/mbedtls/check_config.h
+++ b/include/mbedtls/check_config.h
@@ -50,6 +50,11 @@
     !defined(MBEDTLS_PLATFORM_SNPRINTF_MACRO)
 #define MBEDTLS_PLATFORM_SNPRINTF_ALT
 #endif
+
+#if !defined(MBEDTLS_PLATFORM_VSNPRINTF_ALT) && \
+    !defined(MBEDTLS_PLATFORM_VSNPRINTF_MACRO)
+#define MBEDTLS_PLATFORM_VSNPRINTF_ALT
+#endif
 #endif /* _WIN32 */
 
 #if defined(TARGET_LIKE_MBED) && \
@@ -109,13 +114,20 @@
 #endif
 
 #if defined(MBEDTLS_ECP_RESTARTABLE)           && \
-    ( defined(MBEDTLS_ECDH_COMPUTE_SHARED_ALT) || \
+    ( defined(MBEDTLS_USE_PSA_CRYPTO)          || \
+      defined(MBEDTLS_ECDH_COMPUTE_SHARED_ALT) || \
       defined(MBEDTLS_ECDH_GEN_PUBLIC_ALT)     || \
       defined(MBEDTLS_ECDSA_SIGN_ALT)          || \
       defined(MBEDTLS_ECDSA_VERIFY_ALT)        || \
       defined(MBEDTLS_ECDSA_GENKEY_ALT)        || \
+      defined(MBEDTLS_ECP_INTERNAL_ALT)        || \
       defined(MBEDTLS_ECP_ALT) )
-#error "MBEDTLS_ECP_RESTARTABLE defined, but it cannot coexist with an alternative ECP implementation"
+#error "MBEDTLS_ECP_RESTARTABLE defined, but it cannot coexist with an alternative or PSA-based ECP implementation"
+#endif
+
+#if defined(MBEDTLS_ECP_RESTARTABLE)           && \
+    ! defined(MBEDTLS_ECDH_LEGACY_CONTEXT)
+#error "MBEDTLS_ECP_RESTARTABLE defined, but not MBEDTLS_ECDH_LEGACY_CONTEXT"
 #endif
 
 #if defined(MBEDTLS_ECDSA_DETERMINISTIC) && !defined(MBEDTLS_HMAC_DRBG_C)
@@ -137,6 +149,10 @@
 #error "MBEDTLS_ECP_C defined, but not all prerequisites"
 #endif
 
+#if defined(MBEDTLS_PK_PARSE_C) && !defined(MBEDTLS_ASN1_PARSE_C)
+#error "MBEDTLS_PK_PARSE_C defined, but not all prerequesites"
+#endif
+
 #if defined(MBEDTLS_ENTROPY_C) && (!defined(MBEDTLS_SHA512_C) &&      \
                                     !defined(MBEDTLS_SHA256_C))
 #error "MBEDTLS_ENTROPY_C defined, but not all prerequisites"
@@ -269,6 +285,14 @@
 #error "MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED defined, but not all prerequisites"
 #endif
 
+#if defined(MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED) &&        \
+    !defined(MBEDTLS_SSL_KEEP_PEER_CERTIFICATE) &&              \
+    ( !defined(MBEDTLS_SHA256_C) &&                             \
+      !defined(MBEDTLS_SHA512_C) &&                             \
+      !defined(MBEDTLS_SHA1_C) )
+#error "!MBEDTLS_SSL_KEEP_PEER_CERTIFICATE requires MBEDTLS_SHA512_C, MBEDTLS_SHA256_C or MBEDTLS_SHA1_C"
+#endif
+
 #if defined(MBEDTLS_MEMORY_BUFFER_ALLOC_C) &&                          \
     ( !defined(MBEDTLS_PLATFORM_C) || !defined(MBEDTLS_PLATFORM_MEMORY) )
 #error "MBEDTLS_MEMORY_BUFFER_ALLOC_C defined, but not all prerequisites"
@@ -506,26 +530,25 @@
 #error "MBEDTLS_PSA_CRYPTO_SPM defined, but not all prerequisites"
 #endif
 
-#if defined(MBEDTLS_PSA_CRYPTO_STORAGE_FILE_C) && defined(MBEDTLS_PSA_CRYPTO_STORAGE_ITS_C)
-#error "Only one of MBEDTLS_PSA_CRYPTO_STORAGE_FILE_C or MBEDTLS_PSA_CRYPTO_STORAGE_ITS_C can be defined"
-#endif
-
 #if defined(MBEDTLS_PSA_CRYPTO_STORAGE_C) &&            \
-    !( defined(MBEDTLS_PSA_CRYPTO_C) &&                 \
-       ( defined(MBEDTLS_PSA_CRYPTO_STORAGE_FILE_C) ||  \
-         defined(MBEDTLS_PSA_CRYPTO_STORAGE_ITS_C) ) )
+    ! defined(MBEDTLS_PSA_CRYPTO_C)
 #error "MBEDTLS_PSA_CRYPTO_STORAGE_C defined, but not all prerequisites"
 #endif
 
-#if defined(MBEDTLS_PSA_CRYPTO_STORAGE_FILE_C) &&            \
-    !( defined(MBEDTLS_PSA_CRYPTO_STORAGE_C) &&           \
-       defined(MBEDTLS_FS_IO) )
-#error "MBEDTLS_PSA_CRYPTO_STORAGE_FILE_C defined, but not all prerequisites"
+#if defined(MBEDTLS_PSA_INJECT_ENTROPY) &&      \
+    !( defined(MBEDTLS_PSA_CRYPTO_STORAGE_C) && \
+       defined(MBEDTLS_ENTROPY_NV_SEED) )
+#error "MBEDTLS_PSA_INJECT_ENTROPY defined, but not all prerequisites"
 #endif
 
-#if defined(MBEDTLS_PSA_CRYPTO_STORAGE_ITS_C) &&             \
-    ! defined(MBEDTLS_PSA_CRYPTO_STORAGE_C)
-#error "MBEDTLS_PSA_CRYPTO_STORAGE_ITS_C defined, but not all prerequisites"
+#if defined(MBEDTLS_PSA_INJECT_ENTROPY) &&              \
+    !defined(MBEDTLS_NO_DEFAULT_ENTROPY_SOURCES)
+#error "MBEDTLS_PSA_INJECT_ENTROPY is not compatible with actual entropy sources"
+#endif
+
+#if defined(MBEDTLS_PSA_ITS_FILE_C) && \
+    !defined(MBEDTLS_FS_IO)
+#error "MBEDTLS_PSA_ITS_FILE_C defined, but not all prerequisites"
 #endif
 
 #if defined(MBEDTLS_RSA_C) && ( !defined(MBEDTLS_BIGNUM_C) ||         \
@@ -722,7 +745,7 @@
 /*
  * Avoid warning from -pedantic. This is a convenient place for this
  * workaround since this is included by every single file before the
- * #if defined(MBEDTLS_xxx_C) that results in emtpy translation units.
+ * #if defined(MBEDTLS_xxx_C) that results in empty translation units.
  */
 typedef int mbedtls_iso_c_forbids_empty_translation_units;
 
diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h
index d6ecac6..2d609db 100644
--- a/include/mbedtls/cipher.h
+++ b/include/mbedtls/cipher.h
@@ -36,6 +36,7 @@
 #endif
 
 #include <stddef.h>
+#include "platform_util.h"
 
 #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CCM_C) || defined(MBEDTLS_CHACHAPOLY_C)
 #define MBEDTLS_CIPHER_MODE_AEAD
@@ -354,11 +355,12 @@
  * \brief               This function retrieves the cipher-information
  *                      structure associated with the given cipher name.
  *
- * \param cipher_name   Name of the cipher to search for.
+ * \param cipher_name   Name of the cipher to search for. This must not be
+ *                      \c NULL.
  *
  * \return              The cipher information structure associated with the
  *                      given \p cipher_name.
- * \return              NULL if the associated cipher information is not found.
+ * \return              \c NULL if the associated cipher information is not found.
  */
 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_string( const char *cipher_name );
 
@@ -370,7 +372,7 @@
  *
  * \return              The cipher information structure associated with the
  *                      given \p cipher_type.
- * \return              NULL if the associated cipher information is not found.
+ * \return              \c 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 );
 
@@ -386,7 +388,7 @@
  *
  * \return              The cipher information structure associated with the
  *                      given \p cipher_id.
- * \return              NULL if the associated cipher information is not found.
+ * \return              \c 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,
@@ -394,6 +396,8 @@
 
 /**
  * \brief               This function initializes a \p cipher_context as NONE.
+ *
+ * \param ctx           The context to be initialized. This must not be \c NULL.
  */
 void mbedtls_cipher_init( mbedtls_cipher_context_t *ctx );
 
@@ -401,6 +405,10 @@
  * \brief               This function frees and clears the cipher-specific
  *                      context of \p ctx. Freeing \p ctx itself remains the
  *                      responsibility of the caller.
+ *
+ * \param ctx           The context to be freed. If this is \c NULL, the
+ *                      function has no effect, otherwise this must point to an
+ *                      initialized context.
  */
 void mbedtls_cipher_free( mbedtls_cipher_context_t *ctx );
 
@@ -409,7 +417,7 @@
  * \brief               This function initializes a cipher context for
  *                      use with the given cipher primitive.
  *
- * \param ctx           The context to initialize. May not be NULL.
+ * \param ctx           The context to initialize. This must be initialized.
  * \param cipher_info   The cipher to use.
  *
  * \return              \c 0 on success.
@@ -455,15 +463,16 @@
 /**
  * \brief        This function returns the block size of the given cipher.
  *
- * \param ctx    The context of the cipher. Must be initialized.
+ * \param ctx    The context of the cipher. This must be initialized.
  *
- * \return       The size of the blocks of the cipher.
- * \return       0 if \p ctx has not been initialized.
+ * \return       The block size of the underlying cipher.
+ * \return       \c 0 if \p ctx has not been initialized.
  */
 static inline unsigned int mbedtls_cipher_get_block_size(
     const mbedtls_cipher_context_t *ctx )
 {
-    if( NULL == ctx || NULL == ctx->cipher_info )
+    MBEDTLS_INTERNAL_VALIDATE_RET( ctx != NULL, 0 );
+    if( ctx->cipher_info == NULL )
         return 0;
 
     return ctx->cipher_info->block_size;
@@ -473,7 +482,7 @@
  * \brief        This function returns the mode of operation for
  *               the cipher. For example, MBEDTLS_MODE_CBC.
  *
- * \param ctx    The context of the cipher. Must be initialized.
+ * \param ctx    The context of the cipher. This must be initialized.
  *
  * \return       The mode of operation.
  * \return       #MBEDTLS_MODE_NONE if \p ctx has not been initialized.
@@ -481,7 +490,8 @@
 static inline mbedtls_cipher_mode_t mbedtls_cipher_get_cipher_mode(
     const mbedtls_cipher_context_t *ctx )
 {
-    if( NULL == ctx || NULL == ctx->cipher_info )
+    MBEDTLS_INTERNAL_VALIDATE_RET( ctx != NULL, MBEDTLS_MODE_NONE );
+    if( ctx->cipher_info == NULL )
         return MBEDTLS_MODE_NONE;
 
     return ctx->cipher_info->mode;
@@ -491,7 +501,7 @@
  * \brief       This function returns the size of the IV or nonce
  *              of the cipher, in Bytes.
  *
- * \param ctx   The context of the cipher. Must be initialized.
+ * \param ctx   The context of the cipher. This must be initialized.
  *
  * \return      The recommended IV size if no IV has been set.
  * \return      \c 0 for ciphers not using an IV or a nonce.
@@ -500,7 +510,8 @@
 static inline int mbedtls_cipher_get_iv_size(
     const mbedtls_cipher_context_t *ctx )
 {
-    if( NULL == ctx || NULL == ctx->cipher_info )
+    MBEDTLS_INTERNAL_VALIDATE_RET( ctx != NULL, 0 );
+    if( ctx->cipher_info == NULL )
         return 0;
 
     if( ctx->iv_size != 0 )
@@ -512,7 +523,7 @@
 /**
  * \brief               This function returns the type of the given cipher.
  *
- * \param ctx           The context of the cipher. Must be initialized.
+ * \param ctx           The context of the cipher. This must be initialized.
  *
  * \return              The type of the cipher.
  * \return              #MBEDTLS_CIPHER_NONE if \p ctx has not been initialized.
@@ -520,7 +531,9 @@
 static inline mbedtls_cipher_type_t mbedtls_cipher_get_type(
     const mbedtls_cipher_context_t *ctx )
 {
-    if( NULL == ctx || NULL == ctx->cipher_info )
+    MBEDTLS_INTERNAL_VALIDATE_RET(
+        ctx != NULL, MBEDTLS_CIPHER_NONE );
+    if( ctx->cipher_info == NULL )
         return MBEDTLS_CIPHER_NONE;
 
     return ctx->cipher_info->type;
@@ -530,7 +543,7 @@
  * \brief               This function returns the name of the given cipher
  *                      as a string.
  *
- * \param ctx           The context of the cipher. Must be initialized.
+ * \param ctx           The context of the cipher. This must be initialized.
  *
  * \return              The name of the cipher.
  * \return              NULL if \p ctx has not been not initialized.
@@ -538,7 +551,8 @@
 static inline const char *mbedtls_cipher_get_name(
     const mbedtls_cipher_context_t *ctx )
 {
-    if( NULL == ctx || NULL == ctx->cipher_info )
+    MBEDTLS_INTERNAL_VALIDATE_RET( ctx != NULL, 0 );
+    if( ctx->cipher_info == NULL )
         return 0;
 
     return ctx->cipher_info->name;
@@ -547,7 +561,7 @@
 /**
  * \brief               This function returns the key length of the cipher.
  *
- * \param ctx           The context of the cipher. Must be initialized.
+ * \param ctx           The context of the cipher. This must be initialized.
  *
  * \return              The key length of the cipher in bits.
  * \return              #MBEDTLS_KEY_LENGTH_NONE if ctx \p has not been
@@ -556,7 +570,9 @@
 static inline int mbedtls_cipher_get_key_bitlen(
     const mbedtls_cipher_context_t *ctx )
 {
-    if( NULL == ctx || NULL == ctx->cipher_info )
+    MBEDTLS_INTERNAL_VALIDATE_RET(
+        ctx != NULL, MBEDTLS_KEY_LENGTH_NONE );
+    if( ctx->cipher_info == NULL )
         return MBEDTLS_KEY_LENGTH_NONE;
 
     return (int) ctx->cipher_info->key_bitlen;
@@ -565,7 +581,7 @@
 /**
  * \brief          This function returns the operation of the given cipher.
  *
- * \param ctx      The context of the cipher. Must be initialized.
+ * \param ctx      The context of the cipher. This must be initialized.
  *
  * \return         The type of operation: #MBEDTLS_ENCRYPT or #MBEDTLS_DECRYPT.
  * \return         #MBEDTLS_OPERATION_NONE if \p ctx has not been initialized.
@@ -573,7 +589,9 @@
 static inline mbedtls_operation_t mbedtls_cipher_get_operation(
     const mbedtls_cipher_context_t *ctx )
 {
-    if( NULL == ctx || NULL == ctx->cipher_info )
+    MBEDTLS_INTERNAL_VALIDATE_RET(
+        ctx != NULL, MBEDTLS_OPERATION_NONE );
+    if( ctx->cipher_info == NULL )
         return MBEDTLS_OPERATION_NONE;
 
     return ctx->operation;
@@ -582,11 +600,11 @@
 /**
  * \brief               This function sets the key to use with the given context.
  *
- * \param ctx           The generic cipher context. May not be NULL. Must have
- *                      been initialized using mbedtls_cipher_info_from_type()
- *                      or mbedtls_cipher_info_from_string().
- * \param key           The key to use.
- * \param key_bitlen    The key length to use, in bits.
+ * \param ctx           The generic cipher context. This must be initialized and
+ *                      bound to a cipher information structure.
+ * \param key           The key to use. This must be a readable buffer of at
+ *                      least \p key_bitlen Bits.
+ * \param key_bitlen    The key length to use, in Bits.
  * \param operation     The operation that the key will be used for:
  *                      #MBEDTLS_ENCRYPT or #MBEDTLS_DECRYPT.
  *
@@ -607,7 +625,8 @@
  *
  *                      The default passing mode is PKCS7 padding.
  *
- * \param ctx           The generic cipher context.
+ * \param ctx           The generic cipher context. This must be initialized and
+ *                      bound to a cipher information structure.
  * \param mode          The padding mode.
  *
  * \return              \c 0 on success.
@@ -627,8 +646,10 @@
  * \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 ctx       The generic cipher context. This must be initialized and
+ *                  bound to a cipher information structure.
+ * \param iv        The IV to use, or NONCE_COUNTER for CTR-mode ciphers. This
+ *                  must be a readable buffer of at least \p iv_len Bytes.
  * \param iv_len    The IV length for ciphers with variable-size IV.
  *                  This parameter is discarded by ciphers with fixed-size IV.
  *
@@ -637,12 +658,13 @@
  *                  parameter-verification failure.
  */
 int mbedtls_cipher_set_iv( mbedtls_cipher_context_t *ctx,
-                           const unsigned char *iv, size_t iv_len );
+                           const unsigned char *iv,
+                           size_t iv_len );
 
 /**
  * \brief         This function resets the cipher state.
  *
- * \param ctx     The generic cipher context.
+ * \param ctx     The generic cipher context. This must be initialized.
  *
  * \return        \c 0 on success.
  * \return        #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
@@ -652,16 +674,18 @@
 
 #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CHACHAPOLY_C)
 /**
- * \brief             This function adds additional data for AEAD ciphers.
- *                    Currently supported with GCM and ChaCha20+Poly1305.
- *                    Must be called exactly once, after mbedtls_cipher_reset().
+ * \brief               This function adds additional data for AEAD ciphers.
+ *                      Currently supported with GCM and ChaCha20+Poly1305.
+ *                      This must be called exactly once, after
+ *                      mbedtls_cipher_reset().
  *
- * \param ctx         The generic cipher context.
- * \param ad          The additional data to use.
- * \param ad_len      the Length of \p ad.
+ * \param ctx           The generic cipher context. This must be initialized.
+ * \param ad            The additional data to use. This must be a readable
+ *                      buffer of at least \p ad_len Bytes.
+ * \param ad_len        The length of \p ad in Bytes.
  *
- * \return            \c 0 on success.
- * \return            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 );
@@ -682,14 +706,17 @@
  *                      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 ctx           The generic cipher context. This must be initialized and
+ *                      bound to a key.
+ * \param input         The buffer holding the input data. This must be a
+ *                      readable buffer of at least \p ilen Bytes.
  * \param ilen          The length of the input data.
- * \param output        The buffer for the output data. Must be able to hold at
- *                      least \p ilen + block_size. Must not be the same buffer
- *                      as input.
+ * \param output        The buffer for the output data. This must be able to
+ *                      hold at least `ilen + block_size`. This must not be the
+ *                      same buffer as \p input.
  * \param olen          The length of the output data, to be updated with the
- *                      actual number of Bytes written.
+ *                      actual number of Bytes written. This must not be
+ *                      \c NULL.
  *
  * \return              \c 0 on success.
  * \return              #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
@@ -709,9 +736,12 @@
  *                      contained in it is padded to the size of
  *                      the last block, and written to the \p output buffer.
  *
- * \param ctx           The generic cipher context.
- * \param output        The buffer to write data to. Needs block_size available.
+ * \param ctx           The generic cipher context. This must be initialized and
+ *                      bound to a key.
+ * \param output        The buffer to write data to. This needs to be a writable
+ *                      buffer of at least \p block_size Bytes.
  * \param olen          The length of the data written to the \p output buffer.
+ *                      This may not be \c NULL.
  *
  * \return              \c 0 on success.
  * \return              #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
@@ -729,10 +759,14 @@
 /**
  * \brief               This function writes a tag for AEAD ciphers.
  *                      Currently supported with GCM and ChaCha20+Poly1305.
- *                      Must be called after mbedtls_cipher_finish().
+ *                      This must be called after mbedtls_cipher_finish().
  *
- * \param ctx           The generic cipher context.
- * \param tag           The buffer to write the tag to.
+ * \param ctx           The generic cipher context. This must be initialized,
+ *                      bound to a key, and have just completed a cipher
+ *                      operation through mbedtls_cipher_finish() the tag for
+ *                      which should be written.
+ * \param tag           The buffer to write the tag to. This must be a writable
+ *                      buffer of at least \p tag_len Bytes.
  * \param tag_len       The length of the tag to write.
  *
  * \return              \c 0 on success.
@@ -744,10 +778,11 @@
 /**
  * \brief               This function checks the tag for AEAD ciphers.
  *                      Currently supported with GCM and ChaCha20+Poly1305.
- *                      Must be called after mbedtls_cipher_finish().
+ *                      This must be called after mbedtls_cipher_finish().
  *
- * \param ctx           The generic cipher context.
- * \param tag           The buffer holding the tag.
+ * \param ctx           The generic cipher context. This must be initialized.
+ * \param tag           The buffer holding the tag. This must be a readable
+ *                      buffer of at least \p tag_len Bytes.
  * \param tag_len       The length of the tag to check.
  *
  * \return              \c 0 on success.
@@ -761,18 +796,22 @@
  * \brief               The generic all-in-one encryption/decryption function,
  *                      for all ciphers except AEAD constructs.
  *
- * \param ctx           The generic cipher context.
+ * \param ctx           The generic cipher context. This must be initialized.
  * \param iv            The IV to use, or NONCE_COUNTER for CTR-mode ciphers.
+ *                      This must be a readable buffer of at least \p iv_len
+ *                      Bytes.
  * \param iv_len        The IV length for ciphers with variable-size IV.
  *                      This parameter is discarded by ciphers with fixed-size
  *                      IV.
- * \param input         The buffer holding the input data.
- * \param ilen          The length of the input data.
- * \param output        The buffer for the output data. Must be able to hold at
- *                      least \p ilen + block_size. Must not be the same buffer
- *                      as input.
+ * \param input         The buffer holding the input data. This must be a
+ *                      readable buffer of at least \p ilen Bytes.
+ * \param ilen          The length of the input data in Bytes.
+ * \param output        The buffer for the output data. This must be able to
+ *                      hold at least `ilen + block_size`. This must not be the
+ *                      same buffer as \p input.
  * \param olen          The length of the output data, to be updated with the
- *                      actual number of Bytes written.
+ *                      actual number of Bytes written. This must not be
+ *                      \c NULL.
  *
  * \note                Some ciphers do not use IVs nor nonce. For these
  *                      ciphers, use \p iv = NULL and \p iv_len = 0.
@@ -793,27 +832,34 @@
 
 #if defined(MBEDTLS_CIPHER_MODE_AEAD)
 /**
- * \brief             The generic autenticated encryption (AEAD) function.
+ * \brief               The generic autenticated encryption (AEAD) function.
  *
- * \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.
- * \param ad          The additional data to authenticate.
- * \param ad_len      The length of \p ad.
- * \param input       The buffer holding the input data.
- * \param ilen        The length of the input data.
- * \param output      The buffer for the output data.
- *                    Must be able to hold at least \p ilen.
- * \param olen        The length of the output data, to be updated with the
- *                    actual number of Bytes written.
- * \param tag         The buffer for the authentication tag.
- * \param tag_len     The desired length of the authentication tag.
+ * \param ctx           The generic cipher context. This must be initialized and
+ *                      bound to a key.
+ * \param iv            The IV to use, or NONCE_COUNTER for CTR-mode ciphers.
+ *                      This must be a readable buffer of at least \p iv_len
+ *                      Bytes.
+ * \param iv_len        The IV length for ciphers with variable-size IV.
+ *                      This parameter is discarded by ciphers with fixed-size IV.
+ * \param ad            The additional data to authenticate. This must be a
+ *                      readable buffer of at least \p ad_len Bytes.
+ * \param ad_len        The length of \p ad.
+ * \param input         The buffer holding the input data. This must be a
+ *                      readable buffer of at least \p ilen Bytes.
+ * \param ilen          The length of the input data.
+ * \param output        The buffer for the output data. This must be able to
+ *                      hold at least \p ilen Bytes.
+ * \param olen          The length of the output data, to be updated with the
+ *                      actual number of Bytes written. This must not be
+ *                      \c NULL.
+ * \param tag           The buffer for the authentication tag. This must be a
+ *                      writable buffer of at least \p tag_len Bytes.
+ * \param tag_len       The desired length of the authentication tag.
  *
- * \return            \c 0 on success.
- * \return            #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
- *                    parameter-verification failure.
- * \return            A cipher-specific error code on failure.
+ * \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,
@@ -823,32 +869,39 @@
                          unsigned char *tag, size_t tag_len );
 
 /**
- * \brief             The generic autenticated decryption (AEAD) function.
+ * \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.
+ * \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.
- *                    This parameter is discarded by ciphers with fixed-size IV.
- * \param ad          The additional data to be authenticated.
- * \param ad_len      The length of \p ad.
- * \param input       The buffer holding the input data.
- * \param ilen        The length of the input data.
- * \param output      The buffer for the output data.
- *                    Must be able to hold at least \p ilen.
- * \param olen        The length of the output data, to be updated with the
- *                    actual number of Bytes written.
- * \param tag         The buffer holding the authentication tag.
- * \param tag_len     The length of the authentication tag.
+ * \param ctx           The generic cipher context. This must be initialized and
+ *                      and bound to a key.
+ * \param iv            The IV to use, or NONCE_COUNTER for CTR-mode ciphers.
+ *                      This must be a readable buffer of at least \p iv_len
+ *                      Bytes.
+ * \param iv_len        The IV length for ciphers with variable-size IV.
+ *                      This parameter is discarded by ciphers with fixed-size IV.
+ * \param ad            The additional data to be authenticated. This must be a
+ *                      readable buffer of at least \p ad_len Bytes.
+ * \param ad_len        The length of \p ad.
+ * \param input         The buffer holding the input data. This must be a
+ *                      readable buffer of at least \p ilen Bytes.
+ * \param ilen          The length of the input data.
+ * \param output        The buffer for the output data.
+ *                      This must be able to hold at least \p ilen Bytes.
+ * \param olen          The length of the output data, to be updated with the
+ *                      actual number of Bytes written. This must not be
+ *                      \c NULL.
+ * \param tag           The buffer holding the authentication tag. This must be
+ *                      a readable buffer of at least \p tag_len Bytes.
+ * \param tag_len       The length of the authentication tag.
  *
- * \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.
+ * \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/cipher_internal.h b/include/mbedtls/cipher_internal.h
index 6687b36..d711339 100644
--- a/include/mbedtls/cipher_internal.h
+++ b/include/mbedtls/cipher_internal.h
@@ -137,7 +137,7 @@
 typedef struct
 {
     psa_algorithm_t alg;
-    psa_key_slot_t slot;
+    psa_key_handle_t slot;
     mbedtls_cipher_psa_key_ownership slot_state;
 } mbedtls_cipher_context_psa;
 #endif /* MBEDTLS_USE_PSA_CRYPTO */
diff --git a/include/mbedtls/cmac.h b/include/mbedtls/cmac.h
index c196793..9d42b3f 100644
--- a/include/mbedtls/cmac.h
+++ b/include/mbedtls/cmac.h
@@ -28,6 +28,12 @@
 #ifndef MBEDTLS_CMAC_H
 #define MBEDTLS_CMAC_H
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
 #include "cipher.h"
 
 #ifdef __cplusplus
diff --git a/include/mbedtls/compat-1.3.h b/include/mbedtls/compat-1.3.h
index 213b691..a58b4724 100644
--- a/include/mbedtls/compat-1.3.h
+++ b/include/mbedtls/compat-1.3.h
@@ -25,6 +25,12 @@
  *  This file is part of mbed TLS (https://tls.mbed.org)
  */
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
 #if ! defined(MBEDTLS_DEPRECATED_REMOVED)
 
 #if defined(MBEDTLS_DEPRECATED_WARNING)
diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h
index 1f37d08..de63146 100644
--- a/include/mbedtls/config.h
+++ b/include/mbedtls/config.h
@@ -139,7 +139,7 @@
  *
  * System has time.h, time(), and an implementation for
  * mbedtls_platform_gmtime_r() (see below).
- * The time needs to be correct (not necesarily very accurate, but at least
+ * The time needs to be correct (not necessarily very accurate, but at least
  * the date should be correct). This is used to verify the validity period of
  * X.509 certificates.
  *
@@ -226,6 +226,7 @@
 //#define MBEDTLS_PLATFORM_FPRINTF_ALT
 //#define MBEDTLS_PLATFORM_PRINTF_ALT
 //#define MBEDTLS_PLATFORM_SNPRINTF_ALT
+//#define MBEDTLS_PLATFORM_VSNPRINTF_ALT
 //#define MBEDTLS_PLATFORM_NV_SEED_ALT
 //#define MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT
 
@@ -256,6 +257,48 @@
  */
 //#define MBEDTLS_DEPRECATED_REMOVED
 
+/**
+ * \def MBEDTLS_CHECK_PARAMS
+ *
+ * This configuration option controls whether the library validates more of
+ * the parameters passed to it.
+ *
+ * When this flag is not defined, the library only attempts to validate an
+ * input parameter if: (1) they may come from the outside world (such as the
+ * network, the filesystem, etc.) or (2) not validating them could result in
+ * internal memory errors such as overflowing a buffer controlled by the
+ * library. On the other hand, it doesn't attempt to validate parameters whose
+ * values are fully controlled by the application (such as pointers).
+ *
+ * When this flag is defined, the library additionally attempts to validate
+ * parameters that are fully controlled by the application, and should always
+ * be valid if the application code is fully correct and trusted.
+ *
+ * For example, when a function accepts as input a pointer to a buffer that may
+ * contain untrusted data, and its documentation mentions that this pointer
+ * must not be NULL:
+ * - the pointer is checked to be non-NULL only if this option is enabled
+ * - the content of the buffer is always validated
+ *
+ * When this flag is defined, if a library function receives a parameter that
+ * is invalid, it will:
+ * - invoke the macro MBEDTLS_PARAM_FAILED() which by default expands to a
+ *   call to the function mbedtls_param_failed()
+ * - immediately return (with a specific error code unless the function
+ *   returns void and can't communicate an error).
+ *
+ * When defining this flag, you also need to:
+ * - either provide a definition of the function mbedtls_param_failed() in
+ *   your application (see platform_util.h for its prototype) as the library
+ *   calls that function, but does not provide a default definition for it,
+ * - or provide a different definition of the macro MBEDTLS_PARAM_FAILED()
+ *   below if the above mechanism is not flexible enough to suit your needs.
+ *   See the documentation of this macro later in this file.
+ *
+ * Uncomment to enable validation of application-controlled parameters.
+ */
+//#define MBEDTLS_CHECK_PARAMS
+
 /* \} name SECTION: System support */
 
 /**
@@ -359,7 +402,7 @@
  * \note Because of a signature change, the core AES encryption and decryption routines are
  *       currently named mbedtls_aes_internal_encrypt and mbedtls_aes_internal_decrypt,
  *       respectively. When setting up alternative implementations, these functions should
- *       be overriden, but the wrapper functions mbedtls_aes_decrypt and mbedtls_aes_encrypt
+ *       be overridden, but the wrapper functions mbedtls_aes_decrypt and mbedtls_aes_encrypt
  *       must stay untouched.
  *
  * \note If you use the AES_xxx_ALT macros, then is is recommended to also set
@@ -414,11 +457,11 @@
  *      unsigned char mbedtls_internal_ecp_grp_capable(
  *          const mbedtls_ecp_group *grp )
  *      int  mbedtls_internal_ecp_init( const mbedtls_ecp_group *grp )
- *      void mbedtls_internal_ecp_deinit( const mbedtls_ecp_group *grp )
+ *      void mbedtls_internal_ecp_free( const mbedtls_ecp_group *grp )
  * The mbedtls_internal_ecp_grp_capable function should return 1 if the
  * replacement functions implement arithmetic for the given group and 0
  * otherwise.
- * The functions mbedtls_internal_ecp_init and mbedtls_internal_ecp_deinit are
+ * The functions mbedtls_internal_ecp_init and mbedtls_internal_ecp_free are
  * called before and after each point operation and provide an opportunity to
  * implement optimized set up and tear down instructions.
  *
@@ -645,6 +688,26 @@
 #define MBEDTLS_REMOVE_ARC4_CIPHERSUITES
 
 /**
+ * \def MBEDTLS_REMOVE_3DES_CIPHERSUITES
+ *
+ * Remove 3DES ciphersuites by default in SSL / TLS.
+ * This flag removes the ciphersuites based on 3DES from the default list as
+ * returned by mbedtls_ssl_list_ciphersuites(). However, it is still possible
+ * to enable (some of) them with mbedtls_ssl_conf_ciphersuites() by including
+ * them explicitly.
+ *
+ * A man-in-the-browser attacker can recover authentication tokens sent through
+ * a TLS connection using a 3DES based cipher suite (see "On the Practical
+ * (In-)Security of 64-bit Block Ciphers" by Karthikeyan Bhargavan and Gaëtan
+ * Leurent, see https://sweet32.info/SWEET32_CCS16.pdf). If this attack falls
+ * in your threat model or you are unsure, then you should keep this option
+ * enabled to remove 3DES based cipher suites.
+ *
+ * Comment this macro to keep 3DES in the default ciphersuite list.
+ */
+#define MBEDTLS_REMOVE_3DES_CIPHERSUITES
+
+/**
  * \def MBEDTLS_ECP_DP_SECP192R1_ENABLED
  *
  * MBEDTLS_ECP_XXXX_ENABLED: Enables specific curves within the Elliptic Curve
@@ -683,11 +746,11 @@
  * Enable "non-blocking" ECC operations that can return early and be resumed.
  *
  * This allows various functions to pause by returning
- * #MBEDTLS_ERR_ECP_IN_PROGRESS (or, for functions in the SSL module,
- * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS) and then be called later again in
- * order to further progress and eventually complete their operation. This is
- * controlled through mbedtls_ecp_set_max_ops() which limits the maximum
- * number of ECC operations a function may perform before pausing; see
+ * #MBEDTLS_ERR_ECP_IN_PROGRESS (or, for functions in Mbed TLS's SSL module,
+ * MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS) and then be called later again in order
+ * to further progress and eventually complete their operation. This is
+ * controlled through mbedtls_ecp_set_max_ops() which limits the maximum number
+ * of ECC operations a function may perform before pausing; see
  * mbedtls_ecp_set_max_ops() for more information.
  *
  * This is useful in non-threaded environments if you want to avoid blocking
@@ -697,11 +760,40 @@
  *
  * \note  This option only works with the default software implementation of
  *        elliptic curve functionality. It is incompatible with
- *        MBEDTLS_ECP_ALT, MBEDTLS_ECDH_XXX_ALT and MBEDTLS_ECDSA_XXX_ALT.
+ *        MBEDTLS_ECP_ALT, MBEDTLS_ECDH_XXX_ALT, MBEDTLS_ECDSA_XXX_ALT
+ *        and MBEDTLS_ECDH_LEGACY_CONTEXT.
  */
 //#define MBEDTLS_ECP_RESTARTABLE
 
 /**
+ * \def MBEDTLS_ECDH_LEGACY_CONTEXT
+ *
+ * Use a backward compatible ECDH context.
+ *
+ * Mbed TLS supports two formats for ECDH contexts (#mbedtls_ecdh_context
+ * defined in `ecdh.h`). For most applications, the choice of format makes
+ * no difference, since all library functions can work with either format,
+ * except that the new format is incompatible with MBEDTLS_ECP_RESTARTABLE.
+
+ * The new format used when this option is disabled is smaller
+ * (56 bytes on a 32-bit platform). In future versions of the library, it
+ * will support alternative implementations of ECDH operations.
+ * The new format is incompatible with applications that access
+ * context fields directly and with restartable ECP operations.
+ *
+ * Define this macro if you enable MBEDTLS_ECP_RESTARTABLE or if you
+ * want to access ECDH context fields directly. Otherwise you should
+ * comment out this macro definition.
+ *
+ * This option has no effect if #MBEDTLS_ECDH_C is not enabled.
+ *
+ * \note This configuration option is experimental. Future versions of the
+ *       library may modify the way the ECDH context layout is configured
+ *       and may modify the layout of the new context type.
+ */
+#define MBEDTLS_ECDH_LEGACY_CONTEXT
+
+/**
  * \def MBEDTLS_ECDSA_DETERMINISTIC
  *
  * Enable deterministic ECDSA (RFC 6979).
@@ -1103,15 +1195,20 @@
  */
 //#define MBEDTLS_ENTROPY_NV_SEED
 
-/**
- * \def MBEDTLS_PSA_HAS_ITS_IO
+/* MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER
  *
- * Enable the non-volatile secure storage usage.
+ * In PSA key storage, encode the owner of the key.
  *
- * This is crucial on systems that do not have a HW TRNG support.
+ * This is only meaningful when building the library as part of a
+ * multi-client service. When you activate this option, you must provide
+ * an implementation of the type psa_key_owner_id_t and a translation
+ * from psa_key_file_id_t to file name in all the storage backends that
+ * you wish to support.
  *
+ * Note that this option is meant for internal use only and may be removed
+ * without notice.
  */
-//#define MBEDTLS_PSA_HAS_ITS_IO
+//#define MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER
 
 /**
  * \def MBEDTLS_MEMORY_DEBUG
@@ -1184,14 +1281,17 @@
 //#define MBEDTLS_PSA_CRYPTO_SPM
 
 /**
- * \def MBEDTLS_PSA_HAS_ITS_IO
+ * \def MBEDTLS_PSA_INJECT_ENTROPY
  *
- * Enable the non-volatile secure storage usage.
+ * Enable support for entropy injection at first boot. This feature is
+ * required on systems that do not have a built-in entropy source (TRNG).
+ * This feature is currently not supported on systems that have a built-in
+ * entropy source.
  *
- * This is crucial on systems that do not have a HW TRNG support.
+ * Requires: MBEDTLS_PSA_CRYPTO_STORAGE_C, MBEDTLS_ENTROPY_NV_SEED
  *
  */
-//#define MBEDTLS_PSA_HAS_ITS_IO
+//#define MBEDTLS_PSA_INJECT_ENTROPY
 
 /**
  * \def MBEDTLS_RSA_NO_CRT
@@ -1322,6 +1422,28 @@
 #define MBEDTLS_SSL_FALLBACK_SCSV
 
 /**
+ * \def MBEDTLS_SSL_KEEP_PEER_CERTIFICATE
+ *
+ * This option controls the availability of the API mbedtls_ssl_get_peer_cert()
+ * giving access to the peer's certificate after completion of the handshake.
+ *
+ * Unless you need mbedtls_ssl_peer_cert() in your application, it is
+ * recommended to disable this option for reduced RAM usage.
+ *
+ * \note If this option is disabled, mbedtls_ssl_get_peer_cert() is still
+ *       defined, but always returns \c NULL.
+ *
+ * \note This option has no influence on the protection against the
+ *       triple handshake attack. Even if it is disabled, Mbed TLS will
+ *       still ensure that certificates do not change during renegotiation,
+ *       for exaple by keeping a hash of the peer's certificate.
+ *
+ * Comment this macro to disable storing the peer's certificate
+ * after the handshake.
+ */
+#define MBEDTLS_SSL_KEEP_PEER_CERTIFICATE
+
+/**
  * \def MBEDTLS_SSL_HW_RECORD_ACCEL
  *
  * Enable hooking functions in SSL module for hardware acceleration of
@@ -1530,7 +1652,7 @@
  * \def MBEDTLS_SSL_SESSION_TICKETS
  *
  * Enable support for RFC 5077 session tickets in SSL.
- * Client-side, provides full support for session tickets (maintainance of a
+ * Client-side, provides full support for session tickets (maintenance of a
  * session store remains the responsibility of the application, though).
  * Server-side, you also need to provide callbacks for writing and parsing
  * tickets, including authenticated encryption and key management. Example
@@ -1714,7 +1836,7 @@
  *
  * \warning TLS-level compression MAY REDUCE SECURITY! See for example the
  * CRIME attack. Before enabling this option, you should examine with care if
- * CRIME or similar exploits may be a applicable to your use case.
+ * CRIME or similar exploits may be applicable to your use case.
  *
  * \note Currently compression can't be used with DTLS.
  *
@@ -2661,38 +2783,23 @@
  *
  * Module:  library/psa_crypto_storage.c
  *
- * Requires: MBEDTLS_PSA_CRYPTO_C and one of either
- * MBEDTLS_PSA_CRYPTO_STORAGE_FILE_C or MBEDTLS_PSA_CRYPTO_STORAGE_ITS_C
- * (but not both)
- *
+ * Requires: MBEDTLS_PSA_CRYPTO_C,
+ *           either MBEDTLS_PSA_ITS_FILE_C or a native implementation of
+ *           the PSA ITS interface
  */
 #define MBEDTLS_PSA_CRYPTO_STORAGE_C
 
 /**
- * \def MBEDTLS_PSA_CRYPTO_STORAGE_FILE_C
+ * \def MBEDTLS_PSA_ITS_FILE_C
  *
- * Enable persistent key storage over files for the
- * Platform Security Architecture cryptography API.
+ * Enable the emulation of the Platform Security Architecture
+ * Internal Trusted Storage (PSA ITS) over files.
  *
- * Module:  library/psa_crypto_storage_file.c
+ * Module:  library/psa_its_file.c
  *
- * Requires: MBEDTLS_PSA_CRYPTO_C, MBEDTLS_FS_IO
- *
+ * Requires: MBEDTLS_FS_IO
  */
-#define MBEDTLS_PSA_CRYPTO_STORAGE_FILE_C
-
-/**
- * \def MBEDTLS_PSA_CRYPTO_STORAGE_ITS_C
- *
- * Enable persistent key storage over PSA ITS for the
- * Platform Security Architecture cryptography API.
- *
- * Module:  library/psa_crypto_storage_its.c
- *
- * Requires: MBEDTLS_PSA_CRYPTO_C, MBEDTLS_PSA_HAS_ITS_IO
- *
- */
-//#define MBEDTLS_PSA_CRYPTO_STORAGE_ITS_C
+#define MBEDTLS_PSA_ITS_FILE_C
 
 /**
  * \def MBEDTLS_RIPEMD160_C
@@ -3078,7 +3185,7 @@
 //#define MBEDTLS_PLATFORM_STD_TIME            time /**< Default time to use, can be undefined. MBEDTLS_HAVE_TIME must be enabled */
 //#define MBEDTLS_PLATFORM_STD_FPRINTF      fprintf /**< Default fprintf to use, can be undefined */
 //#define MBEDTLS_PLATFORM_STD_PRINTF        printf /**< Default printf to use, can be undefined */
-/* Note: your snprintf must correclty zero-terminate the buffer! */
+/* Note: your snprintf must correctly zero-terminate the buffer! */
 //#define MBEDTLS_PLATFORM_STD_SNPRINTF    snprintf /**< Default snprintf to use, can be undefined */
 //#define MBEDTLS_PLATFORM_STD_EXIT_SUCCESS       0 /**< Default exit value to use, can be undefined */
 //#define MBEDTLS_PLATFORM_STD_EXIT_FAILURE       1 /**< Default exit value to use, can be undefined */
@@ -3095,11 +3202,42 @@
 //#define MBEDTLS_PLATFORM_TIME_TYPE_MACRO       time_t /**< Default time macro to use, can be undefined. MBEDTLS_HAVE_TIME must be enabled */
 //#define MBEDTLS_PLATFORM_FPRINTF_MACRO      fprintf /**< Default fprintf macro to use, can be undefined */
 //#define MBEDTLS_PLATFORM_PRINTF_MACRO        printf /**< Default printf macro to use, can be undefined */
-/* Note: your snprintf must correclty zero-terminate the buffer! */
+/* Note: your snprintf must correctly zero-terminate the buffer! */
 //#define MBEDTLS_PLATFORM_SNPRINTF_MACRO    snprintf /**< Default snprintf macro to use, can be undefined */
+//#define MBEDTLS_PLATFORM_VSNPRINTF_MACRO    vsnprintf /**< Default vsnprintf macro to use, can be undefined */
 //#define MBEDTLS_PLATFORM_NV_SEED_READ_MACRO   mbedtls_platform_std_nv_seed_read /**< Default nv_seed_read function to use, can be undefined */
 //#define MBEDTLS_PLATFORM_NV_SEED_WRITE_MACRO  mbedtls_platform_std_nv_seed_write /**< Default nv_seed_write function to use, can be undefined */
 
+/**
+ * \brief       This macro is invoked by the library when an invalid parameter
+ *              is detected that is only checked with MBEDTLS_CHECK_PARAMS
+ *              (see the documentation of that option for context).
+ *
+ *              When you leave this undefined here, a default definition is
+ *              provided that invokes the function mbedtls_param_failed(),
+ *              which is declared in platform_util.h for the benefit of the
+ *              library, but that you need to define in your application.
+ *
+ *              When you define this here, this replaces the default
+ *              definition in platform_util.h (which no longer declares the
+ *              function mbedtls_param_failed()) and it is your responsibility
+ *              to make sure this macro expands to something suitable (in
+ *              particular, that all the necessary declarations are visible
+ *              from within the library - you can ensure that by providing
+ *              them in this file next to the macro definition).
+ *
+ *              Note that you may define this macro to expand to nothing, in
+ *              which case you don't have to worry about declarations or
+ *              definitions. However, you will then be notified about invalid
+ *              parameters only in non-void functions, and void function will
+ *              just silently return early on invalid parameters, which
+ *              partially negates the benefits of enabling
+ *              #MBEDTLS_CHECK_PARAMS in the first place, so is discouraged.
+ *
+ * \param cond  The expression that should evaluate to true, but doesn't.
+ */
+//#define MBEDTLS_PARAM_FAILED( cond )               assert( cond )
+
 /* SSL Cache options */
 //#define MBEDTLS_SSL_CACHE_DEFAULT_TIMEOUT       86400 /**< 1 day  */
 //#define MBEDTLS_SSL_CACHE_DEFAULT_MAX_ENTRIES      50 /**< Maximum entries in cache */
@@ -3108,31 +3246,65 @@
 
 /** \def MBEDTLS_SSL_MAX_CONTENT_LEN
  *
- * Maximum fragment length in bytes.
+ * Maximum length (in bytes) of incoming and outgoing plaintext fragments.
  *
- * Determines the size of both the incoming and outgoing TLS I/O buffers.
+ * This determines the size of both the incoming and outgoing TLS I/O buffers
+ * in such a way that both are capable of holding the specified amount of
+ * plaintext data, regardless of the protection mechanism used.
  *
- * Uncommenting MBEDTLS_SSL_IN_CONTENT_LEN and/or MBEDTLS_SSL_OUT_CONTENT_LEN
- * will override this length by setting maximum incoming and/or outgoing
- * fragment length, respectively.
+ * To configure incoming and outgoing I/O buffers separately, use
+ * #MBEDTLS_SSL_IN_CONTENT_LEN and #MBEDTLS_SSL_OUT_CONTENT_LEN,
+ * which overwrite the value set by this option.
+ *
+ * \note When using a value less than the default of 16KB on the client, it is
+ *       recommended to use the Maximum Fragment Length (MFL) extension to
+ *       inform the server about this limitation. On the server, there
+ *       is no supported, standardized way of informing the client about
+ *       restriction on the maximum size of incoming messages, and unless
+ *       the limitation has been communicated by other means, it is recommended
+ *       to only change the outgoing buffer size #MBEDTLS_SSL_OUT_CONTENT_LEN
+ *       while keeping the default value of 16KB for the incoming buffer.
+ *
+ * Uncomment to set the maximum plaintext size of both
+ * incoming and outgoing I/O buffers.
  */
 //#define MBEDTLS_SSL_MAX_CONTENT_LEN             16384
 
 /** \def MBEDTLS_SSL_IN_CONTENT_LEN
  *
- * Maximum incoming fragment length in bytes.
+ * Maximum length (in bytes) of incoming plaintext fragments.
  *
- * Uncomment to set the size of the inward TLS buffer independently of the
- * outward buffer.
+ * This determines the size of the incoming TLS I/O buffer in such a way
+ * that it is capable of holding the specified amount of plaintext data,
+ * regardless of the protection mechanism used.
+ *
+ * If this option is undefined, it inherits its value from
+ * #MBEDTLS_SSL_MAX_CONTENT_LEN.
+ *
+ * \note When using a value less than the default of 16KB on the client, it is
+ *       recommended to use the Maximum Fragment Length (MFL) extension to
+ *       inform the server about this limitation. On the server, there
+ *       is no supported, standardized way of informing the client about
+ *       restriction on the maximum size of incoming messages, and unless
+ *       the limitation has been communicated by other means, it is recommended
+ *       to only change the outgoing buffer size #MBEDTLS_SSL_OUT_CONTENT_LEN
+ *       while keeping the default value of 16KB for the incoming buffer.
+ *
+ * Uncomment to set the maximum plaintext size of the incoming I/O buffer
+ * independently of the outgoing I/O buffer.
  */
 //#define MBEDTLS_SSL_IN_CONTENT_LEN              16384
 
 /** \def MBEDTLS_SSL_OUT_CONTENT_LEN
  *
- * Maximum outgoing fragment length in bytes.
+ * Maximum length (in bytes) of outgoing plaintext fragments.
  *
- * Uncomment to set the size of the outward TLS buffer independently of the
- * inward buffer.
+ * This determines the size of the outgoing TLS I/O buffer in such a way
+ * that it is capable of holding the specified amount of plaintext data,
+ * regardless of the protection mechanism used.
+ *
+ * If this option undefined, it inherits its value from
+ * #MBEDTLS_SSL_MAX_CONTENT_LEN.
  *
  * It is possible to save RAM by setting a smaller outward buffer, while keeping
  * the default inward 16384 byte buffer to conform to the TLS specification.
@@ -3142,11 +3314,8 @@
  * The specific size requirement depends on the configured ciphers and any
  * certificate data which is sent during the handshake.
  *
- * For absolute minimum RAM usage, it's best to enable
- * MBEDTLS_SSL_MAX_FRAGMENT_LENGTH and reduce MBEDTLS_SSL_MAX_CONTENT_LEN. This
- * reduces both incoming and outgoing buffer sizes. However this is only
- * guaranteed if the other end of the connection also supports the TLS
- * max_fragment_len extension. Otherwise the connection may fail.
+ * Uncomment to set the maximum plaintext size of the outgoing I/O buffer
+ * independently of the incoming I/O buffer.
  */
 //#define MBEDTLS_SSL_OUT_CONTENT_LEN             16384
 
diff --git a/include/mbedtls/ctr_drbg.h b/include/mbedtls/ctr_drbg.h
index c91ca58..cc3df7b 100644
--- a/include/mbedtls/ctr_drbg.h
+++ b/include/mbedtls/ctr_drbg.h
@@ -36,6 +36,12 @@
 #ifndef MBEDTLS_CTR_DRBG_H
 #define MBEDTLS_CTR_DRBG_H
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
 #include "aes.h"
 
 #if defined(MBEDTLS_THREADING_C)
@@ -239,18 +245,20 @@
 /**
  * \brief              This function updates the state of the CTR_DRBG context.
  *
- * \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.
+ * \param add_len      Length of \p additional in bytes. This must be at
+ *                     most #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
  *
+ * \return             \c 0 on success.
+ * \return             #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG if
+ *                     \p add_len is more than
+ *                     #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT.
+ * \return             An error from the underlying AES cipher on failure.
  */
-void mbedtls_ctr_drbg_update( mbedtls_ctr_drbg_context *ctx,
-                      const unsigned char *additional, size_t add_len );
+int mbedtls_ctr_drbg_update_ret( mbedtls_ctr_drbg_context *ctx,
+                                 const unsigned char *additional,
+                                 size_t add_len );
 
 /**
  * \brief   This function updates a CTR_DRBG instance with additional
@@ -290,6 +298,35 @@
 int mbedtls_ctr_drbg_random( void *p_rng,
                      unsigned char *output, size_t output_len );
 
+
+#if ! defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED    __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+/**
+ * \brief              This function updates the state of the CTR_DRBG context.
+ *
+ * \deprecated         Superseded by mbedtls_ctr_drbg_update_ret()
+ *                     in 2.16.0.
+ *
+ * \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.
+ */
+MBEDTLS_DEPRECATED void mbedtls_ctr_drbg_update(
+    mbedtls_ctr_drbg_context *ctx,
+    const unsigned char *additional,
+    size_t add_len );
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
+
 #if defined(MBEDTLS_FS_IO)
 /**
  * \brief               This function writes a seed file.
@@ -319,6 +356,8 @@
 int mbedtls_ctr_drbg_update_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
 #endif /* MBEDTLS_FS_IO */
 
+#if defined(MBEDTLS_SELF_TEST)
+
 /**
  * \brief               The CTR_DRBG checkup routine.
  *
@@ -327,6 +366,8 @@
  */
 int mbedtls_ctr_drbg_self_test( int verbose );
 
+#endif /* MBEDTLS_SELF_TEST */
+
 /* Internal functions (do not call directly) */
 int mbedtls_ctr_drbg_seed_entropy_len( mbedtls_ctr_drbg_context *,
                                int (*)(void *, unsigned char *, size_t), void *,
diff --git a/include/mbedtls/debug.h b/include/mbedtls/debug.h
index ef8db67..736444b 100644
--- a/include/mbedtls/debug.h
+++ b/include/mbedtls/debug.h
@@ -65,6 +65,11 @@
     mbedtls_debug_print_crt( ssl, level, __FILE__, __LINE__, text, crt )
 #endif
 
+#if defined(MBEDTLS_ECDH_C)
+#define MBEDTLS_SSL_DEBUG_ECDH( level, ecdh, attr )               \
+    mbedtls_debug_printf_ecdh( ssl, level, __FILE__, __LINE__, ecdh, attr )
+#endif
+
 #else /* MBEDTLS_DEBUG_C */
 
 #define MBEDTLS_SSL_DEBUG_MSG( level, args )            do { } while( 0 )
@@ -73,6 +78,7 @@
 #define MBEDTLS_SSL_DEBUG_MPI( level, text, X )         do { } while( 0 )
 #define MBEDTLS_SSL_DEBUG_ECP( level, text, X )         do { } while( 0 )
 #define MBEDTLS_SSL_DEBUG_CRT( level, text, crt )       do { } while( 0 )
+#define MBEDTLS_SSL_DEBUG_ECDH( level, ecdh, attr )     do { } while( 0 )
 
 #endif /* MBEDTLS_DEBUG_C */
 
@@ -221,6 +227,36 @@
                       const char *text, const mbedtls_x509_crt *crt );
 #endif
 
+#if defined(MBEDTLS_ECDH_C)
+typedef enum
+{
+    MBEDTLS_DEBUG_ECDH_Q,
+    MBEDTLS_DEBUG_ECDH_QP,
+    MBEDTLS_DEBUG_ECDH_Z,
+} mbedtls_debug_ecdh_attr;
+
+/**
+ * \brief   Print a field of the ECDH structure in the SSL context to the debug
+ *          output. This function is always used through the
+ *          MBEDTLS_SSL_DEBUG_ECDH() macro, which supplies the ssl context, file
+ *          and line number parameters.
+ *
+ * \param ssl       SSL context
+ * \param level     error level of the debug message
+ * \param file      file the error has occurred in
+ * \param line      line number the error has occurred in
+ * \param ecdh      the ECDH context
+ * \param attr      the identifier of the attribute being output
+ *
+ * \attention       This function is intended for INTERNAL usage within the
+ *                  library only.
+ */
+void mbedtls_debug_printf_ecdh( const mbedtls_ssl_context *ssl, int level,
+                                const char *file, int line,
+                                const mbedtls_ecdh_context *ecdh,
+                                mbedtls_debug_ecdh_attr attr );
+#endif
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/mbedtls/des.h b/include/mbedtls/des.h
index d62042d..54e6b78 100644
--- a/include/mbedtls/des.h
+++ b/include/mbedtls/des.h
@@ -338,6 +338,8 @@
 void mbedtls_des_setkey( uint32_t SK[32],
                          const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
 
+#if defined(MBEDTLS_SELF_TEST)
+
 /**
  * \brief          Checkup routine
  *
@@ -345,6 +347,8 @@
  */
 int mbedtls_des_self_test( int verbose );
 
+#endif /* MBEDTLS_SELF_TEST */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/mbedtls/dhm.h b/include/mbedtls/dhm.h
index 8e2d020..98cd4e2 100644
--- a/include/mbedtls/dhm.h
+++ b/include/mbedtls/dhm.h
@@ -127,9 +127,15 @@
 void mbedtls_dhm_init( mbedtls_dhm_context *ctx );
 
 /**
- * \brief          This function parses the ServerKeyExchange parameters.
+ * \brief          This function parses the DHM parameters in a
+ *                 TLS ServerKeyExchange handshake message
+ *                 (DHM modulus, generator, and public key).
  *
- * \param ctx      The DHM context.
+ * \note           In a TLS handshake, this is the how the client
+ *                 sets up its DHM context from the server's public
+ *                 DHM key material.
+ *
+ * \param ctx      The DHM context to use. This must be initialized.
  * \param p        On input, *p must be the start of the input buffer.
  *                 On output, *p is updated to point to the end of the data
  *                 that has been read. On success, this is the first byte
@@ -143,31 +149,37 @@
  * \return         An \c MBEDTLS_ERR_DHM_XXX error code on failure.
  */
 int mbedtls_dhm_read_params( mbedtls_dhm_context *ctx,
-                     unsigned char **p,
-                     const unsigned char *end );
+                             unsigned char **p,
+                             const unsigned char *end );
 
 /**
- * \brief          This function sets up and writes the ServerKeyExchange
- *                 parameters.
+ * \brief          This function generates a DHM key pair and exports its
+ *                 public part together with the DHM parameters in the format
+ *                 used in a TLS ServerKeyExchange handshake message.
  *
- * \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.
- *                 It is the responsibility of the caller to ensure that enough
- *                 space is available. Refer to \c mbedtls_mpi_size to computing
- *                 the byte-size of an MPI.
- *
- * \note           This function assumes that \c ctx->P and \c ctx->G
- *                 have already been properly set. For that, use
+ * \note           This function assumes that the DHM parameters \c ctx->P
+ *                 and \c ctx->G have already been properly set. For that, use
  *                 mbedtls_dhm_set_group() below in conjunction with
  *                 mbedtls_mpi_read_binary() and mbedtls_mpi_read_string().
  *
- * \param ctx      The DHM context.
+ * \note           In a TLS handshake, this is the how the server generates
+ *                 and exports its DHM key material.
+ *
+ * \param ctx      The DHM context to use. This must be initialized
+ *                 and have the DHM parameters set. It may or may not
+ *                 already have imported the peer's public key.
  * \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.
+ * \param olen     The address at which to store the number of Bytes
+ *                 written on success. This must not be \c NULL.
+ * \param output   The destination buffer. This must be a writable buffer of
+ *                 sufficient size to hold the reduced binary presentation of
+ *                 the modulus, the generator and the public key, each wrapped
+ *                 with a 2-byte length field. It is the responsibility of the
+ *                 caller to ensure that enough space is available. Refer to
+ *                 mbedtls_mpi_size() to computing the byte-size of an MPI.
+ * \param f_rng    The RNG function. Must not be \c NULL.
+ * \param p_rng    The RNG context to be passed to \p f_rng. This may be
+ *                 \c NULL if \p f_rng doesn't need a context parameter.
  *
  * \return         \c 0 on success.
  * \return         An \c MBEDTLS_ERR_DHM_XXX error code on failure.
@@ -180,12 +192,14 @@
 /**
  * \brief          This function sets the prime modulus and generator.
  *
- * \note           This function can be used to set \p P, \p G
+ * \note           This function can be used to set \c ctx->P, \c ctx->G
  *                 in preparation for mbedtls_dhm_make_params().
  *
- * \param ctx      The DHM context.
- * \param P        The MPI holding the DHM prime modulus.
- * \param G        The MPI holding the DHM generator.
+ * \param ctx      The DHM context to configure. This must be initialized.
+ * \param P        The MPI holding the DHM prime modulus. This must be
+ *                 an initialized MPI.
+ * \param G        The MPI holding the DHM generator. This must be an
+ *                 initialized MPI.
  *
  * \return         \c 0 if successful.
  * \return         An \c MBEDTLS_ERR_DHM_XXX error code on failure.
@@ -195,11 +209,17 @@
                            const mbedtls_mpi *G );
 
 /**
- * \brief          This function imports the public value of the peer, G^Y.
+ * \brief          This function imports the raw public value of the peer.
  *
- * \param ctx      The DHM context.
- * \param input    The input buffer containing the G^Y value of the peer.
- * \param ilen     The size of the input buffer.
+ * \note           In a TLS handshake, this is the how the server imports
+ *                 the Client's public DHM key.
+ *
+ * \param ctx      The DHM context to use. This must be initialized and have
+ *                 its DHM parameters set, e.g. via mbedtls_dhm_set_group().
+ *                 It may or may not already have generated its own private key.
+ * \param input    The input buffer containing the \c G^Y value of the peer.
+ *                 This must be a readable buffer of size \p ilen Bytes.
+ * \param ilen     The size of the input buffer \p input in Bytes.
  *
  * \return         \c 0 on success.
  * \return         An \c MBEDTLS_ERR_DHM_XXX error code on failure.
@@ -208,21 +228,25 @@
                      const unsigned char *input, size_t ilen );
 
 /**
- * \brief          This function creates its own private key, \c X, and
- *                 exports \c G^X.
+ * \brief          This function creates a DHM key pair and exports
+ *                 the raw public key in big-endian format.
  *
  * \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
+ *                 If it is larger than \c ctx->len, it is padded accordingly
  *                 with zero-bytes at the beginning.
  *
- * \param ctx      The DHM context.
+ * \param ctx      The DHM context to use. This must be initialized and
+ *                 have the DHM parameters set. It may or may not already
+ *                 have imported the peer's public key.
  * \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).
- * \param f_rng    The RNG function.
- * \param p_rng    The RNG context.
+ * \param output   The destination buffer. This must be a writable buffer of
+ *                 size \p olen Bytes.
+ * \param olen     The length of the destination buffer. This must be at least
+ *                 equal to `ctx->len` (the size of \c P).
+ * \param f_rng    The RNG function. This must not be \c NULL.
+ * \param p_rng    The RNG context to be passed to \p f_rng. This may be \c NULL
+ *                 if \p f_rng doesn't need a context argument.
  *
  * \return         \c 0 on success.
  * \return         An \c MBEDTLS_ERR_DHM_XXX error code on failure.
@@ -233,22 +257,27 @@
                      void *p_rng );
 
 /**
- * \brief               This function derives and exports the shared secret
- *                      \c (G^Y)^X mod \c P.
+ * \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.
+ * \note           If \p f_rng is not \c 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 \c P).
+ * \param ctx           The DHM context to use. This must be initialized
+ *                      and have its own private key generated and the peer's
+ *                      public key imported.
+ * \param output        The buffer to write the generated shared key to. This
+ *                      must be a writable buffer of size \p output_size Bytes.
+ * \param output_size   The size of the destination buffer. This must be at
+ *                      least the size of \c 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 context.
+ * \param f_rng         The RNG function, for blinding purposes. This may
+ *                      b \c NULL if blinding isn't needed.
+ * \param p_rng         The RNG context. This may be \c NULL if \p f_rng
+ *                      doesn't need a context argument.
  *
  * \return              \c 0 on success.
  * \return              An \c MBEDTLS_ERR_DHM_XXX error code on failure.
@@ -259,9 +288,12 @@
                      void *p_rng );
 
 /**
- * \brief          This function frees and clears the components of a DHM context.
+ * \brief          This function frees and clears the components
+ *                 of a DHM context.
  *
- * \param ctx      The DHM context to free and clear.
+ * \param ctx      The DHM context to free and clear. This may be \c NULL,
+ *                 in which case this function is a no-op. If it is not \c NULL,
+ *                 it must point to an initialized DHM context.
  */
 void mbedtls_dhm_free( mbedtls_dhm_context *ctx );
 
@@ -270,17 +302,19 @@
 /**
  * \brief             This function parses DHM parameters in PEM or DER format.
  *
- * \param dhm         The DHM context to initialize.
- * \param dhmin       The input buffer.
- * \param dhminlen    The size of the buffer, including the terminating null
- *                    Byte for PEM data.
+ * \param dhm         The DHM context to import the DHM parameters into.
+ *                    This must be initialized.
+ * \param dhmin       The input buffer. This must be a readable buffer of
+ *                    length \p dhminlen Bytes.
+ * \param dhminlen    The size of the input buffer \p dhmin, including the
+ *                    terminating \c NULL Byte for PEM data.
  *
  * \return            \c 0 on success.
- * \return            An \c MBEDTLS_ERR_DHM_XXX or \c MBEDTLS_ERR_PEM_XXX error code
- *                    error code on failure.
+ * \return            An \c MBEDTLS_ERR_DHM_XXX or \c MBEDTLS_ERR_PEM_XXX error
+ *                    code on failure.
  */
 int mbedtls_dhm_parse_dhm( mbedtls_dhm_context *dhm, const unsigned char *dhmin,
-                   size_t dhminlen );
+                           size_t dhminlen );
 
 #if defined(MBEDTLS_FS_IO)
 /** \ingroup x509_module */
@@ -288,16 +322,20 @@
  * \brief          This function loads and parses DHM parameters from a file.
  *
  * \param dhm      The DHM context to load the parameters to.
+ *                 This must be initialized.
  * \param path     The filename to read the DHM parameters from.
+ *                 This must not be \c NULL.
  *
  * \return         \c 0 on success.
- * \return            An \c MBEDTLS_ERR_DHM_XXX or \c MBEDTLS_ERR_PEM_XXX error code
- *                    error code on failure.
+ * \return         An \c MBEDTLS_ERR_DHM_XXX or \c MBEDTLS_ERR_PEM_XXX
+ *                 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 */
 
+#if defined(MBEDTLS_SELF_TEST)
+
 /**
  * \brief          The DMH checkup routine.
  *
@@ -306,16 +344,16 @@
  */
 int mbedtls_dhm_self_test( int verbose );
 
+#endif /* MBEDTLS_SELF_TEST */
 #ifdef __cplusplus
 }
 #endif
 
 /**
- * RFC 3526, RFC 5114 and RFC 7919 standardize a number of
- * Diffie-Hellman groups, some of which are included here
- * for use within the SSL/TLS module and the user's convenience
- * when configuring the Diffie-Hellman parameters by hand
- * through \c mbedtls_ssl_conf_dh_param.
+ * RFC 3526, RFC 5114 and RFC 7919 standardize a number of Diffie-Hellman
+ * groups, some of which are included here for use by Mbed TLS's SSL/TLS module
+ * and the user's convenience when configuring the Diffie-Hellman parameters by
+ * hand through Mbed TLS's \c mbedtls_ssl_conf_dh_param.
  *
  * The following lists the source of the above groups in the standards:
  * - RFC 5114 section 2.2:  2048-bit MODP Group with 224-bit Prime Order Subgroup
@@ -353,15 +391,6 @@
 
 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
 
-#if defined(MBEDTLS_DEPRECATED_WARNING)
-#define MBEDTLS_DEPRECATED __attribute__((deprecated))
-MBEDTLS_DEPRECATED typedef char const * mbedtls_deprecated_constant_t;
-#define MBEDTLS_DEPRECATED_STRING_CONSTANT( VAL )       \
-    ( (mbedtls_deprecated_constant_t) ( VAL ) )
-#else
-#define MBEDTLS_DEPRECATED_STRING_CONSTANT( VAL ) VAL
-#endif /* ! MBEDTLS_DEPRECATED_WARNING */
-
 /**
  * \warning The origin of the primes in RFC 5114 is not documented and
  *          their use therefore constitutes a security risk!
diff --git a/include/mbedtls/ecdh.h b/include/mbedtls/ecdh.h
index 27f2ffc..384c3dc 100644
--- a/include/mbedtls/ecdh.h
+++ b/include/mbedtls/ecdh.h
@@ -34,6 +34,12 @@
 #ifndef MBEDTLS_ECDH_H
 #define MBEDTLS_ECDH_H
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
 #include "ecp.h"
 
 #ifdef __cplusplus
@@ -49,6 +55,39 @@
     MBEDTLS_ECDH_THEIRS, /**< The key of the peer. */
 } mbedtls_ecdh_side;
 
+#if !defined(MBEDTLS_ECDH_LEGACY_CONTEXT)
+/**
+ * Defines the ECDH implementation used.
+ *
+ * Later versions of the library may add new variants, therefore users should
+ * not make any assumptions about them.
+ */
+typedef enum
+{
+    MBEDTLS_ECDH_VARIANT_NONE = 0,   /*!< Implementation not defined. */
+    MBEDTLS_ECDH_VARIANT_MBEDTLS_2_0,/*!< The default Mbed TLS implementation */
+} mbedtls_ecdh_variant;
+
+/**
+ * The context used by the default ECDH implementation.
+ *
+ * Later versions might change the structure of this context, therefore users
+ * should not make any assumptions about the structure of
+ * mbedtls_ecdh_context_mbed.
+ */
+typedef struct mbedtls_ecdh_context_mbed
+{
+    mbedtls_ecp_group grp;   /*!< The elliptic curve used. */
+    mbedtls_mpi d;           /*!< The private key. */
+    mbedtls_ecp_point Q;     /*!< The public key. */
+    mbedtls_ecp_point Qp;    /*!< The value of the public key of the peer. */
+    mbedtls_mpi z;           /*!< The shared secret. */
+#if defined(MBEDTLS_ECP_RESTARTABLE)
+    mbedtls_ecp_restart_ctx rs; /*!< The restart context for EC computations. */
+#endif
+} mbedtls_ecdh_context_mbed;
+#endif
+
 /**
  *
  * \warning         Performing multiple operations concurrently on the same
@@ -58,6 +97,7 @@
  */
 typedef struct mbedtls_ecdh_context
 {
+#if defined(MBEDTLS_ECDH_LEGACY_CONTEXT)
     mbedtls_ecp_group grp;   /*!< The elliptic curve used. */
     mbedtls_mpi d;           /*!< The private key. */
     mbedtls_ecp_point Q;     /*!< The public key. */
@@ -70,7 +110,26 @@
 #if defined(MBEDTLS_ECP_RESTARTABLE)
     int restart_enabled;        /*!< The flag for restartable mode. */
     mbedtls_ecp_restart_ctx rs; /*!< The restart context for EC computations. */
-#endif
+#endif /* MBEDTLS_ECP_RESTARTABLE */
+#else
+    uint8_t point_format;       /*!< The format of point export in TLS messages
+                                  as defined in RFC 4492. */
+    mbedtls_ecp_group_id grp_id;/*!< The elliptic curve used. */
+    mbedtls_ecdh_variant var;   /*!< The ECDH implementation/structure used. */
+    union
+    {
+        mbedtls_ecdh_context_mbed   mbed_ecdh;
+    } ctx;                      /*!< Implementation-specific context. The
+                                  context in use is specified by the \c var
+                                  field. */
+#if defined(MBEDTLS_ECP_RESTARTABLE)
+    uint8_t restart_enabled;    /*!< The flag for restartable mode. Functions of
+                                  an alternative implementation not supporting
+                                  restartable mode must return
+                                  MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED error
+                                  if this flag is set. */
+#endif /* MBEDTLS_ECP_RESTARTABLE */
+#endif /* MBEDTLS_ECDH_LEGACY_CONTEXT */
 }
 mbedtls_ecdh_context;
 
@@ -84,11 +143,16 @@
  *
  * \see             ecp.h
  *
- * \param grp       The ECP group.
+ * \param grp       The ECP group to use. This must be initialized and have
+ *                  domain parameters loaded, for example through
+ *                  mbedtls_ecp_load() or mbedtls_ecp_tls_read_group().
  * \param d         The destination MPI (private key).
+ *                  This must be initialized.
  * \param Q         The destination point (public key).
- * \param f_rng     The RNG function.
- * \param p_rng     The RNG context.
+ *                  This must be initialized.
+ * \param f_rng     The RNG function to use. This must not be \c NULL.
+ * \param p_rng     The RNG context to be passed to \p f_rng. This may be
+ *                  \c NULL in case \p f_rng doesn't need a context argument.
  *
  * \return          \c 0 on success.
  * \return          Another \c MBEDTLS_ERR_ECP_XXX or
@@ -111,12 +175,22 @@
  *                  countermeasures against side-channel attacks.
  *                  For more information, see mbedtls_ecp_mul().
  *
- * \param grp       The ECP group.
+ * \param grp       The ECP group to use. This must be initialized and have
+ *                  domain parameters loaded, for example through
+ *                  mbedtls_ecp_load() or mbedtls_ecp_tls_read_group().
  * \param z         The destination MPI (shared secret).
+ *                  This must be initialized.
  * \param Q         The public key from another party.
+ *                  This must be initialized.
  * \param d         Our secret exponent (private key).
- * \param f_rng     The RNG function.
- * \param p_rng     The RNG context.
+ *                  This must be initialized.
+ * \param f_rng     The RNG function. This may be \c NULL if randomization
+ *                  of intermediate results during the ECP computations is
+ *                  not needed (discouraged). See the documentation of
+ *                  mbedtls_ecp_mul() for more.
+ * \param p_rng     The RNG context to be passed to \p f_rng. This may be
+ *                  \c NULL if \p f_rng is \c NULL or doesn't need a
+ *                  context argument.
  *
  * \return          \c 0 on success.
  * \return          Another \c MBEDTLS_ERR_ECP_XXX or
@@ -130,36 +204,57 @@
 /**
  * \brief           This function initializes an ECDH context.
  *
- * \param ctx       The ECDH context to initialize.
+ * \param ctx       The ECDH context to initialize. This must not be \c NULL.
  */
 void mbedtls_ecdh_init( mbedtls_ecdh_context *ctx );
 
 /**
- * \brief           This function frees a context.
+ * \brief           This function sets up the ECDH context with the information
+ *                  given.
  *
- * \param ctx       The context to free.
- */
-void mbedtls_ecdh_free( mbedtls_ecdh_context *ctx );
-
-/**
- * \brief           This function generates a public key and a TLS
- *                  ServerKeyExchange payload.
+ *                  This function should be called after mbedtls_ecdh_init() but
+ *                  before mbedtls_ecdh_make_params(). There is no need to call
+ *                  this function before mbedtls_ecdh_read_params().
  *
  *                  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().
+ * \param ctx       The ECDH context to set up. This must be initialized.
+ * \param grp_id    The group id of the group to set up the context for.
+ *
+ * \return          \c 0 on success.
+ */
+int mbedtls_ecdh_setup( mbedtls_ecdh_context *ctx,
+                        mbedtls_ecp_group_id grp_id );
+
+/**
+ * \brief           This function frees a context.
+ *
+ * \param ctx       The context to free. This may be \c NULL, in which
+ *                  case this function does nothing. If it is not \c NULL,
+ *                  it must point to an initialized ECDH context.
+ */
+void mbedtls_ecdh_free( mbedtls_ecdh_context *ctx );
+
+/**
+ * \brief           This function generates an EC key pair and exports its
+ *                  in the format used in a TLS ServerKeyExchange handshake
+ *                  message.
+ *
+ *                  This is the second function used by a TLS server for ECDHE
+ *                  ciphersuites. (It is called after mbedtls_ecdh_setup().)
  *
  * \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 context.
+ * \param ctx       The ECDH context to use. This must be initialized
+ *                  and bound to a group, for example via mbedtls_ecdh_setup().
+ * \param olen      The address at which to store the number of Bytes written.
+ * \param buf       The destination buffer. This must be a writable buffer of
+ *                  length \p blen Bytes.
+ * \param blen      The length of the destination buffer \p buf in Bytes.
+ * \param f_rng     The RNG function to use. This must not be \c NULL.
+ * \param p_rng     The RNG context to be passed to \p f_rng. This may be
+ *                  \c NULL in case \p f_rng doesn't need a context argument.
  *
  * \return          \c 0 on success.
  * \return          #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
@@ -172,24 +267,32 @@
                       void *p_rng );
 
 /**
- * \brief           This function parses and processes a TLS ServerKeyExhange
- *                  payload.
+ * \brief           This function parses the ECDHE parameters in a
+ *                  TLS ServerKeyExchange handshake message.
  *
- *                  This is the first function used by a TLS client for ECDHE
- *                  ciphersuites.
+ * \note            In a TLS handshake, this is the how the client
+ *                  sets up its ECDHE context from the server's public
+ *                  ECDHE key material.
  *
  * \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.
+ * \param ctx       The ECDHE context to use. This must be initialized.
+ * \param buf       On input, \c *buf must be the start of the input buffer.
+ *                  On output, \c *buf is updated to point to the end of the
+ *                  data that has been read. On success, this is the first byte
+ *                  past the end of the ServerKeyExchange parameters.
+ *                  On error, this is the point at which an error has been
+ *                  detected, which is usually not useful except to debug
+ *                  failures.
+ * \param end       The end of the input buffer.
  *
  * \return          \c 0 on success.
  * \return          An \c MBEDTLS_ERR_ECP_XXX error code on failure.
  *
  */
 int mbedtls_ecdh_read_params( mbedtls_ecdh_context *ctx,
-                      const unsigned char **buf, const unsigned char *end );
+                              const unsigned char **buf,
+                              const unsigned char *end );
 
 /**
  * \brief           This function sets up an ECDH context from an EC key.
@@ -200,33 +303,40 @@
  *
  * \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: 1: Our key, or
- *                  0: The key of the peer.
+ * \param ctx       The ECDH context to set up. This must be initialized.
+ * \param key       The EC key to use. This must be initialized.
+ * \param side      Defines the source of the key. Possible values are:
+ *                  - #MBEDTLS_ECDH_OURS: The key is ours.
+ *                  - #MBEDTLS_ECDH_THEIRS: The key is that of the peer.
  *
  * \return          \c 0 on success.
  * \return          Another \c MBEDTLS_ERR_ECP_XXX error code on failure.
  *
  */
-int mbedtls_ecdh_get_params( mbedtls_ecdh_context *ctx, const mbedtls_ecp_keypair *key,
-                     mbedtls_ecdh_side side );
+int mbedtls_ecdh_get_params( mbedtls_ecdh_context *ctx,
+                             const mbedtls_ecp_keypair *key,
+                             mbedtls_ecdh_side side );
 
 /**
- * \brief           This function generates a public key and a TLS
- *                  ClientKeyExchange payload.
+ * \brief           This function generates a public key and exports it
+ *                  as a TLS ClientKeyExchange payload.
  *
  *                  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 context.
+ * \param ctx       The ECDH context to use. This must be initialized
+ *                  and bound to a group, the latter usually by
+ *                  mbedtls_ecdh_read_params().
+ * \param olen      The address at which to store the number of Bytes written.
+ *                  This must not be \c NULL.
+ * \param buf       The destination buffer. This must be a writable buffer
+ *                  of length \p blen Bytes.
+ * \param blen      The size of the destination buffer \p buf in Bytes.
+ * \param f_rng     The RNG function to use. This must not be \c NULL.
+ * \param p_rng     The RNG context to be passed to \p f_rng. This may be
+ *                  \c NULL in case \p f_rng doesn't need a context argument.
  *
  * \return          \c 0 on success.
  * \return          #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
@@ -239,23 +349,26 @@
                       void *p_rng );
 
 /**
- * \brief       This function parses and processes a TLS ClientKeyExchange
- *              payload.
+ * \brief       This function parses and processes the ECDHE payload of a
+ *              TLS ClientKeyExchange message.
  *
- *              This is the second function used by a TLS server for ECDH(E)
- *              ciphersuites.
+ *              This is the third function used by a TLS server for ECDH(E)
+ *              ciphersuites. (It is called after mbedtls_ecdh_setup() and
+ *              mbedtls_ecdh_make_params().)
  *
  * \see         ecp.h
  *
- * \param ctx   The ECDH context.
- * \param buf   The start of the input buffer.
- * \param blen  The length of the input buffer.
+ * \param ctx   The ECDH context to use. This must be initialized
+ *              and bound to a group, for example via mbedtls_ecdh_setup().
+ * \param buf   The pointer to the ClientKeyExchange payload. This must
+ *              be a readable buffer of length \p blen Bytes.
+ * \param blen  The length of the input buffer \p buf in Bytes.
  *
  * \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 );
+                              const unsigned char *buf, size_t blen );
 
 /**
  * \brief           This function derives and exports the shared secret.
@@ -268,13 +381,19 @@
  *                  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 context.
+
+ * \param ctx       The ECDH context to use. This must be initialized
+ *                  and have its own private key generated and the peer's
+ *                  public key imported.
+ * \param olen      The address at which to store the total number of
+ *                  Bytes written on success. This must not be \c NULL.
+ * \param buf       The buffer to write the generated shared key to. This
+ *                  must be a writable buffer of size \p blen Bytes.
+ * \param blen      The length of the destination buffer \p buf in Bytes.
+ * \param f_rng     The RNG function, for blinding purposes. This may
+ *                  b \c NULL if blinding isn't needed.
+ * \param p_rng     The RNG context. This may be \c NULL if \p f_rng
+ *                  doesn't need a context argument.
  *
  * \return          \c 0 on success.
  * \return          #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
@@ -297,7 +416,7 @@
  *                  computations once enabled, except by free-ing the context,
  *                  which cancels possible in-progress operations.
  *
- * \param ctx       The ECDH context.
+ * \param ctx       The ECDH context to use. This must be initialized.
  */
 void mbedtls_ecdh_enable_restart( mbedtls_ecdh_context *ctx );
 #endif /* MBEDTLS_ECP_RESTARTABLE */
diff --git a/include/mbedtls/ecdsa.h b/include/mbedtls/ecdsa.h
index 5245c6e..2943945 100644
--- a/include/mbedtls/ecdsa.h
+++ b/include/mbedtls/ecdsa.h
@@ -32,6 +32,12 @@
 #ifndef MBEDTLS_ECDSA_H
 #define MBEDTLS_ECDSA_H
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
 #include "ecp.h"
 #include "md.h"
 
@@ -123,7 +129,8 @@
  * \brief           This function computes the ECDSA signature of a
  *                  previously-hashed message.
  *
- * \note            The deterministic version is usually preferred.
+ * \note            The deterministic version implemented in
+ *                  mbedtls_ecdsa_sign_det() 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
@@ -133,14 +140,22 @@
  *
  * \see             ecp.h
  *
- * \param grp       The ECP group.
- * \param r         The first output integer.
- * \param s         The second output integer.
- * \param d         The private signing key.
- * \param buf       The message hash.
- * \param blen      The length of \p buf.
- * \param f_rng     The RNG function.
- * \param p_rng     The RNG context.
+ * \param grp       The context for the elliptic curve to use.
+ *                  This must be initialized and have group parameters
+ *                  set, for example through mbedtls_ecp_group_load().
+ * \param r         The MPI context in which to store the first part
+ *                  the signature. This must be initialized.
+ * \param s         The MPI context in which to store the second part
+ *                  the signature. This must be initialized.
+ * \param d         The private signing key. This must be initialized.
+ * \param buf       The content to be signed. This is usually the hash of
+ *                  the original data to be signed. This must be a readable
+ *                  buffer of length \p blen Bytes. It may be \c NULL if
+ *                  \p blen is zero.
+ * \param blen      The length of \p buf in Bytes.
+ * \param f_rng     The RNG function. This must not be \c NULL.
+ * \param p_rng     The RNG context to be passed to \p f_rng. This may be
+ *                  \c NULL if \p f_rng doesn't need a context parameter.
  *
  * \return          \c 0 on success.
  * \return          An \c MBEDTLS_ERR_ECP_XXX
@@ -167,21 +182,29 @@
  *
  * \see             ecp.h
  *
- * \param grp       The ECP group.
- * \param r         The first output integer.
- * \param s         The second output integer.
- * \param d         The private signing key.
- * \param buf       The message hash.
- * \param blen      The length of \p buf.
- * \param md_alg    The MD algorithm used to hash the message.
+ * \param grp       The context for the elliptic curve to use.
+ *                  This must be initialized and have group parameters
+ *                  set, for example through mbedtls_ecp_group_load().
+ * \param r         The MPI context in which to store the first part
+ *                  the signature. This must be initialized.
+ * \param s         The MPI context in which to store the second part
+ *                  the signature. This must be initialized.
+ * \param d         The private signing key. This must be initialized
+ *                  and setup, for example through mbedtls_ecp_gen_privkey().
+ * \param buf       The hashed content to be signed. This must be a readable
+ *                  buffer of length \p blen Bytes. It may be \c NULL if
+ *                  \p blen is zero.
+ * \param blen      The length of \p buf in Bytes.
+ * \param md_alg    The hash algorithm used to hash the original data.
  *
  * \return          \c 0 on success.
  * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
  *                  error code on failure.
  */
-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,
-                    mbedtls_md_type_t md_alg );
+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,
+                            mbedtls_md_type_t md_alg );
 #endif /* MBEDTLS_ECDSA_DETERMINISTIC */
 
 /**
@@ -196,12 +219,19 @@
  *
  * \see             ecp.h
  *
- * \param grp       The ECP group.
- * \param buf       The message hash.
- * \param blen      The length of \p buf.
- * \param Q         The public key to use for verification.
+ * \param grp       The ECP group to use.
+ *                  This must be initialized and have group parameters
+ *                  set, for example through mbedtls_ecp_group_load().
+ * \param buf       The hashed content that was signed. This must be a readable
+ *                  buffer of length \p blen Bytes. It may be \c NULL if
+ *                  \p blen is zero.
+ * \param blen      The length of \p buf in Bytes.
+ * \param Q         The public key to use for verification. This must be
+ *                  initialized and setup.
  * \param r         The first integer of the signature.
+ *                  This must be initialized.
  * \param s         The second integer of the signature.
+ *                  This must be initialized.
  *
  * \return          \c 0 on success.
  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the signature
@@ -210,8 +240,9 @@
  *                  error code on failure for any other reason.
  */
 int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp,
-                  const unsigned char *buf, size_t blen,
-                  const mbedtls_ecp_point *Q, const mbedtls_mpi *r, const mbedtls_mpi *s);
+                          const unsigned char *buf, size_t blen,
+                          const mbedtls_ecp_point *Q, const mbedtls_mpi *r,
+                          const mbedtls_mpi *s);
 
 /**
  * \brief           This function computes the ECDSA signature and writes it
@@ -228,11 +259,6 @@
  *                  of the Digital Signature Algorithm (DSA) and Elliptic
  *                  Curve Digital Signature Algorithm (ECDSA)</em>.
  *
- * \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
- *                  #MBEDTLS_ECDSA_MAX_LEN is always safe.
- *
  * \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
@@ -241,20 +267,32 @@
  *
  * \see             ecp.h
  *
- * \param ctx       The ECDSA context.
+ * \param ctx       The ECDSA context to use. This must be initialized
+ *                  and have a group and private key bound to it, for example
+ *                  via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair().
  * \param md_alg    The message digest that was used to hash the message.
- * \param hash      The message hash.
- * \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.
+ * \param hash      The message hash to be signed. This must be a readable
+ *                  buffer of length \p blen Bytes.
+ * \param hlen      The length of the hash \p hash in Bytes.
+ * \param sig       The buffer to which to write the signature. This must be a
+ *                  writable buffer of length at least twice as large as the
+ *                  size of the curve used, plus 9. For example, 73 Bytes if
+ *                  a 256-bit curve is used. A buffer length of
+ *                  #MBEDTLS_ECDSA_MAX_LEN is always safe.
+ * \param slen      The address at which to store the actual length of
+ *                  the signature written. Must not be \c NULL.
+ * \param f_rng     The RNG function. This must not be \c NULL if
+ *                  #MBEDTLS_ECDSA_DETERMINISTIC is unset. Otherwise,
+ *                  it is unused and may be set to \c NULL.
+ * \param p_rng     The RNG context to be passed to \p f_rng. This may be
+ *                  \c NULL if \p f_rng is \c NULL or doesn't use a 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,
+int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx,
+                                   mbedtls_md_type_t md_alg,
                            const unsigned char *hash, size_t hlen,
                            unsigned char *sig, size_t *slen,
                            int (*f_rng)(void *, unsigned char *, size_t),
@@ -270,15 +308,28 @@
  *                  but it can return early and restart according to the limit
  *                  set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
  *
- * \param ctx       The ECDSA context.
+ * \param ctx       The ECDSA context to use. This must be initialized
+ *                  and have a group and private key bound to it, for example
+ *                  via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair().
  * \param md_alg    The message digest that was used to hash the message.
- * \param hash      The message hash.
- * \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.
- * \param rs_ctx    The restart context (NULL disables restart).
+ * \param hash      The message hash to be signed. This must be a readable
+ *                  buffer of length \p blen Bytes.
+ * \param hlen      The length of the hash \p hash in Bytes.
+ * \param sig       The buffer to which to write the signature. This must be a
+ *                  writable buffer of length at least twice as large as the
+ *                  size of the curve used, plus 9. For example, 73 Bytes if
+ *                  a 256-bit curve is used. A buffer length of
+ *                  #MBEDTLS_ECDSA_MAX_LEN is always safe.
+ * \param slen      The address at which to store the actual length of
+ *                  the signature written. Must not be \c NULL.
+ * \param f_rng     The RNG function. This must not be \c NULL if
+ *                  #MBEDTLS_ECDSA_DETERMINISTIC is unset. Otherwise,
+ *                  it is unused and may be set to \c NULL.
+ * \param p_rng     The RNG context to be passed to \p f_rng. This may be
+ *                  \c NULL if \p f_rng is \c NULL or doesn't use a context.
+ * \param rs_ctx    The restart context to use. This may be \c NULL to disable
+ *                  restarting. If it is not \c NULL, it must point to an
+ *                  initialized restart context.
  *
  * \return          \c 0 on success.
  * \return          #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
@@ -314,11 +365,6 @@
  * \warning         It is not thread-safe to use the same context in
  *                  multiple threads.
  *
- * \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
- *                  #MBEDTLS_ECDSA_MAX_LEN is always safe.
- *
  * \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
@@ -330,12 +376,20 @@
  * \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.
+ * \param ctx       The ECDSA context to use. This must be initialized
+ *                  and have a group and private key bound to it, for example
+ *                  via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair().
+ * \param hash      The message hash to be signed. This must be a readable
+ *                  buffer of length \p blen Bytes.
+ * \param hlen      The length of the hash \p hash in Bytes.
+ * \param sig       The buffer to which to write the signature. This must be a
+ *                  writable buffer of length at least twice as large as the
+ *                  size of the curve used, plus 9. For example, 73 Bytes if
+ *                  a 256-bit curve is used. A buffer length of
+ *                  #MBEDTLS_ECDSA_MAX_LEN is always safe.
+ * \param slen      The address at which to store the actual length of
+ *                  the signature written. Must not be \c NULL.
+ * \param md_alg    The message digest that was used to hash the message.
  *
  * \return          \c 0 on success.
  * \return          An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
@@ -360,11 +414,14 @@
  *
  * \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.
+ * \param ctx       The ECDSA context to use. This must be initialized
+ *                  and have a group and public key bound to it.
+ * \param hash      The message hash that was signed. This must be a readable
+ *                  buffer of length \p size Bytes.
+ * \param hlen      The size of the hash \p hash.
+ * \param sig       The signature to read and verify. This must be a readable
+ *                  buffer of length \p slen Bytes.
+ * \param slen      The size of \p sig in Bytes.
  *
  * \return          \c 0 on success.
  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid.
@@ -387,12 +444,17 @@
  *                  but it can return early and restart according to the limit
  *                  set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
  *
- * \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.
- * \param rs_ctx    The restart context (NULL disables restart).
+ * \param ctx       The ECDSA context to use. This must be initialized
+ *                  and have a group and public key bound to it.
+ * \param hash      The message hash that was signed. This must be a readable
+ *                  buffer of length \p size Bytes.
+ * \param hlen      The size of the hash \p hash.
+ * \param sig       The signature to read and verify. This must be a readable
+ *                  buffer of length \p slen Bytes.
+ * \param slen      The size of \p sig in Bytes.
+ * \param rs_ctx    The restart context to use. This may be \c NULL to disable
+ *                  restarting. If it is not \c NULL, it must point to an
+ *                  initialized restart context.
  *
  * \return          \c 0 on success.
  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid.
@@ -414,10 +476,12 @@
  * \see            ecp.h
  *
  * \param ctx      The ECDSA context to store the keypair in.
+ *                 This must be initialized.
  * \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 context.
+ * \param f_rng    The RNG function to use. This must not be \c NULL.
+ * \param p_rng    The RNG context to be passed to \p f_rng. This may be
+ *                 \c NULL if \p f_rng doesn't need a context argument.
  *
  * \return         \c 0 on success.
  * \return         An \c MBEDTLS_ERR_ECP_XXX code on failure.
@@ -426,40 +490,55 @@
                   int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
 
 /**
- * \brief           This function sets an ECDSA context from an EC key pair.
+ * \brief           This function sets up 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.
+ * \param ctx       The ECDSA context to setup. This must be initialized.
+ * \param key       The EC key to use. This must be initialized and hold
+ *                  a private-public key pair or a public key. In the former
+ *                  case, the ECDSA context may be used for signature creation
+ *                  and verification after this call. In the latter case, it
+ *                  may be used for signature verification.
  *
  * \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 );
+int mbedtls_ecdsa_from_keypair( mbedtls_ecdsa_context *ctx,
+                                const mbedtls_ecp_keypair *key );
 
 /**
  * \brief           This function initializes an ECDSA context.
  *
  * \param ctx       The ECDSA context to initialize.
+ *                  This must not be \c NULL.
  */
 void mbedtls_ecdsa_init( mbedtls_ecdsa_context *ctx );
 
 /**
  * \brief           This function frees an ECDSA context.
  *
- * \param ctx       The ECDSA context to free.
+ * \param ctx       The ECDSA context to free. This may be \c NULL,
+ *                  in which case this function does nothing. If it
+ *                  is not \c NULL, it must be initialized.
  */
 void mbedtls_ecdsa_free( mbedtls_ecdsa_context *ctx );
 
 #if defined(MBEDTLS_ECP_RESTARTABLE)
 /**
- * \brief           Initialize a restart context
+ * \brief           Initialize a restart context.
+ *
+ * \param ctx       The restart context to initialize.
+ *                  This must not be \c NULL.
  */
 void mbedtls_ecdsa_restart_init( mbedtls_ecdsa_restart_ctx *ctx );
 
 /**
- * \brief           Free the components of a restart context
+ * \brief           Free the components of a restart context.
+ *
+ * \param ctx       The restart context to free. This may be \c NULL,
+ *                  in which case this function does nothing. If it
+ *                  is not \c NULL, it must be initialized.
  */
 void mbedtls_ecdsa_restart_free( mbedtls_ecdsa_restart_ctx *ctx );
 #endif /* MBEDTLS_ECP_RESTARTABLE */
diff --git a/include/mbedtls/ecjpake.h b/include/mbedtls/ecjpake.h
index 59d12f0..3d8d02a 100644
--- a/include/mbedtls/ecjpake.h
+++ b/include/mbedtls/ecjpake.h
@@ -40,6 +40,11 @@
  * The payloads are serialized in a way suitable for use in TLS, but could
  * also be use outside TLS.
  */
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
 
 #include "ecp.h"
 #include "md.h"
@@ -92,28 +97,33 @@
 #endif /* MBEDTLS_ECJPAKE_ALT */
 
 /**
- * \brief           Initialize a context
- *                  (just makes it ready for setup() or free()).
+ * \brief           Initialize an ECJPAKE context.
  *
- * \param ctx       context to initialize
+ * \param ctx       The ECJPAKE context to initialize.
+ *                  This must not be \c NULL.
  */
 void mbedtls_ecjpake_init( mbedtls_ecjpake_context *ctx );
 
 /**
- * \brief           Set up a context for use
+ * \brief           Set up an ECJPAKE context for use.
  *
  * \note            Currently the only values for hash/curve allowed by the
- *                  standard are MBEDTLS_MD_SHA256/MBEDTLS_ECP_DP_SECP256R1.
+ *                  standard are #MBEDTLS_MD_SHA256/#MBEDTLS_ECP_DP_SECP256R1.
  *
- * \param ctx       context to set up
- * \param role      Our role: client or server
- * \param hash      hash function to use (MBEDTLS_MD_XXX)
- * \param curve     elliptic curve identifier (MBEDTLS_ECP_DP_XXX)
- * \param secret    pre-shared secret (passphrase)
- * \param len       length of the shared secret
+ * \param ctx       The ECJPAKE context to set up. This must be initialized.
+ * \param role      The role of the caller. This must be either
+ *                  #MBEDTLS_ECJPAKE_CLIENT or #MBEDTLS_ECJPAKE_SERVER.
+ * \param hash      The identifier of the hash function to use,
+ *                  for example #MBEDTLS_MD_SHA256.
+ * \param curve     The identifier of the elliptic curve to use,
+ *                  for example #MBEDTLS_ECP_DP_SECP256R1.
+ * \param secret    The pre-shared secret (passphrase). This must be
+ *                  a readable buffer of length \p len Bytes. It need
+ *                  only be valid for the duration of this call.
+ * \param len       The length of the pre-shared secret \p secret.
  *
- * \return          0 if successfull,
- *                  a negative error code otherwise
+ * \return          \c 0 if successful.
+ * \return          A negative error code on failure.
  */
 int mbedtls_ecjpake_setup( mbedtls_ecjpake_context *ctx,
                            mbedtls_ecjpake_role role,
@@ -123,29 +133,34 @@
                            size_t len );
 
 /**
- * \brief           Check if a context is ready for use
+ * \brief           Check if an ECJPAKE context is ready for use.
  *
- * \param ctx       Context to check
+ * \param ctx       The ECJPAKE context to check. This must be
+ *                  initialized.
  *
- * \return          0 if the context is ready for use,
- *                  MBEDTLS_ERR_ECP_BAD_INPUT_DATA otherwise
+ * \return          \c 0 if the context is ready for use.
+ * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA otherwise.
  */
 int mbedtls_ecjpake_check( const mbedtls_ecjpake_context *ctx );
 
 /**
  * \brief           Generate and write the first round message
  *                  (TLS: contents of the Client/ServerHello extension,
- *                  excluding extension type and length bytes)
+ *                  excluding extension type and length bytes).
  *
- * \param ctx       Context to use
- * \param buf       Buffer to write the contents to
- * \param len       Buffer size
- * \param olen      Will be updated with the number of bytes written
- * \param f_rng     RNG function
- * \param p_rng     RNG parameter
+ * \param ctx       The ECJPAKE context to use. This must be
+ *                  initialized and set up.
+ * \param buf       The buffer to write the contents to. This must be a
+ *                  writable buffer of length \p len Bytes.
+ * \param len       The length of \p buf in Bytes.
+ * \param olen      The address at which to store the total number
+ *                  of Bytes written to \p buf. This must not be \c NULL.
+ * \param f_rng     The RNG function to use. This must not be \c NULL.
+ * \param p_rng     The RNG parameter to be passed to \p f_rng. This
+ *                  may be \c NULL if \p f_rng doesn't use a context.
  *
- * \return          0 if successfull,
- *                  a negative error code otherwise
+ * \return          \c 0 if successful.
+ * \return          A negative error code on failure.
  */
 int mbedtls_ecjpake_write_round_one( mbedtls_ecjpake_context *ctx,
                             unsigned char *buf, size_t len, size_t *olen,
@@ -155,14 +170,16 @@
 /**
  * \brief           Read and process the first round message
  *                  (TLS: contents of the Client/ServerHello extension,
- *                  excluding extension type and length bytes)
+ *                  excluding extension type and length bytes).
  *
- * \param ctx       Context to use
- * \param buf       Pointer to extension contents
- * \param len       Extension length
+ * \param ctx       The ECJPAKE context to use. This must be initialized
+ *                  and set up.
+ * \param buf       The buffer holding the first round message. This must
+ *                  be a readable buffer of length \p len Bytes.
+ * \param len       The length in Bytes of \p buf.
  *
- * \return          0 if successfull,
- *                  a negative error code otherwise
+ * \return          \c 0 if successful.
+ * \return          A negative error code on failure.
  */
 int mbedtls_ecjpake_read_round_one( mbedtls_ecjpake_context *ctx,
                                     const unsigned char *buf,
@@ -170,17 +187,21 @@
 
 /**
  * \brief           Generate and write the second round message
- *                  (TLS: contents of the Client/ServerKeyExchange)
+ *                  (TLS: contents of the Client/ServerKeyExchange).
  *
- * \param ctx       Context to use
- * \param buf       Buffer to write the contents to
- * \param len       Buffer size
- * \param olen      Will be updated with the number of bytes written
- * \param f_rng     RNG function
- * \param p_rng     RNG parameter
+ * \param ctx       The ECJPAKE context to use. This must be initialized,
+ *                  set up, and already have performed round one.
+ * \param buf       The buffer to write the round two contents to.
+ *                  This must be a writable buffer of length \p len Bytes.
+ * \param len       The size of \p buf in Bytes.
+ * \param olen      The address at which to store the total number of Bytes
+ *                  written to \p buf. This must not be \c NULL.
+ * \param f_rng     The RNG function to use. This must not be \c NULL.
+ * \param p_rng     The RNG parameter to be passed to \p f_rng. This
+ *                  may be \c NULL if \p f_rng doesn't use a context.
  *
- * \return          0 if successfull,
- *                  a negative error code otherwise
+ * \return          \c 0 if successful.
+ * \return          A negative error code on failure.
  */
 int mbedtls_ecjpake_write_round_two( mbedtls_ecjpake_context *ctx,
                             unsigned char *buf, size_t len, size_t *olen,
@@ -189,14 +210,16 @@
 
 /**
  * \brief           Read and process the second round message
- *                  (TLS: contents of the Client/ServerKeyExchange)
+ *                  (TLS: contents of the Client/ServerKeyExchange).
  *
- * \param ctx       Context to use
- * \param buf       Pointer to the message
- * \param len       Message length
+ * \param ctx       The ECJPAKE context to use. This must be initialized
+ *                  and set up and already have performed round one.
+ * \param buf       The buffer holding the second round message. This must
+ *                  be a readable buffer of length \p len Bytes.
+ * \param len       The length in Bytes of \p buf.
  *
- * \return          0 if successfull,
- *                  a negative error code otherwise
+ * \return          \c 0 if successful.
+ * \return          A negative error code on failure.
  */
 int mbedtls_ecjpake_read_round_two( mbedtls_ecjpake_context *ctx,
                                     const unsigned char *buf,
@@ -204,17 +227,21 @@
 
 /**
  * \brief           Derive the shared secret
- *                  (TLS: Pre-Master Secret)
+ *                  (TLS: Pre-Master Secret).
  *
- * \param ctx       Context to use
- * \param buf       Buffer to write the contents to
- * \param len       Buffer size
- * \param olen      Will be updated with the number of bytes written
- * \param f_rng     RNG function
- * \param p_rng     RNG parameter
+ * \param ctx       The ECJPAKE context to use. This must be initialized,
+ *                  set up and have performed both round one and two.
+ * \param buf       The buffer to write the derived secret to. This must
+ *                  be a writable buffer of length \p len Bytes.
+ * \param len       The length of \p buf in Bytes.
+ * \param olen      The address at which to store the total number of Bytes
+ *                  written to \p buf. This must not be \c NULL.
+ * \param f_rng     The RNG function to use. This must not be \c NULL.
+ * \param p_rng     The RNG parameter to be passed to \p f_rng. This
+ *                  may be \c NULL if \p f_rng doesn't use a context.
  *
- * \return          0 if successfull,
- *                  a negative error code otherwise
+ * \return          \c 0 if successful.
+ * \return          A negative error code on failure.
  */
 int mbedtls_ecjpake_derive_secret( mbedtls_ecjpake_context *ctx,
                             unsigned char *buf, size_t len, size_t *olen,
@@ -222,14 +249,15 @@
                             void *p_rng );
 
 /**
- * \brief           Free a context's content
+ * \brief           This clears an ECJPAKE context and frees any
+ *                  embedded data structure.
  *
- * \param ctx       context to free
+ * \param ctx       The ECJPAKE context to free. This may be \c NULL,
+ *                  in which case this function does nothing. If it is not
+ *                  \c NULL, it must point to an initialized ECJPAKE context.
  */
 void mbedtls_ecjpake_free( mbedtls_ecjpake_context *ctx );
 
-
-
 #if defined(MBEDTLS_SELF_TEST)
 
 /**
diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h
index 2fb1af4..1a6ec13 100644
--- a/include/mbedtls/ecp.h
+++ b/include/mbedtls/ecp.h
@@ -36,6 +36,12 @@
 #ifndef MBEDTLS_ECP_H
 #define MBEDTLS_ECP_H
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
 #include "bignum.h"
 
 /*
@@ -93,6 +99,16 @@
  */
 #define MBEDTLS_ECP_DP_MAX     12
 
+/*
+ * Curve types
+ */
+typedef enum
+{
+    MBEDTLS_ECP_TYPE_NONE = 0,
+    MBEDTLS_ECP_TYPE_SHORT_WEIERSTRASS,    /* y^2 = x^3 + a x + b      */
+    MBEDTLS_ECP_TYPE_MONTGOMERY,           /* y^2 = x^3 + a x^2 + x    */
+} mbedtls_ecp_curve_type;
+
 /**
  * Curve information, for use by other modules.
  */
@@ -159,6 +175,10 @@
  * additions or subtractions. Therefore, it is only an approximative modular
  * reduction. It must return 0 on success and non-zero on failure.
  *
+ * \note        Alternative implementations must keep the group IDs distinct. If
+ *              two group structures have the same ID, then they must be
+ *              identical.
+ *
  */
 typedef struct mbedtls_ecp_group
 {
@@ -185,6 +205,68 @@
 }
 mbedtls_ecp_group;
 
+/**
+ * \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 using the compiler command line.
+ * \{
+ */
+
+#if !defined(MBEDTLS_ECP_MAX_BITS)
+/**
+ * The maximum size of the groups, that is, of \c N and \c P.
+ */
+#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 )
+#define MBEDTLS_ECP_MAX_PT_LEN   ( 2 * MBEDTLS_ECP_MAX_BYTES + 1 )
+
+#if !defined(MBEDTLS_ECP_WINDOW_SIZE)
+/*
+ * Maximum "window" size used for point multiplication.
+ * Default: 6.
+ * Minimum value: 2. Maximum value: 7.
+ *
+ * Result is an array of at most ( 1 << ( MBEDTLS_ECP_WINDOW_SIZE - 1 ) )
+ * points used for point multiplication. This value is directly tied to EC
+ * peak memory usage, so decreasing it by one should roughly cut memory usage
+ * by two (if large curves are in use).
+ *
+ * Reduction in size may reduce speed, but larger curves are impacted first.
+ * Sample performances (in ECDHE handshakes/s, with FIXED_POINT_OPTIM = 1):
+ *      w-size:     6       5       4       3       2
+ *      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   /**< The maximum window size used. */
+#endif /* MBEDTLS_ECP_WINDOW_SIZE */
+
+#if !defined(MBEDTLS_ECP_FIXED_POINT_OPTIM)
+/*
+ * Trade memory for speed on fixed-point multiplication.
+ *
+ * This speeds up repeated multiplication of the generator (that is, the
+ * multiplication in ECDSA signatures, and half of the multiplications in
+ * ECDSA verification and ECDHE) by a factor roughly 3 to 4.
+ *
+ * The cost is increasing EC peak memory usage by a factor roughly 2.
+ *
+ * Change this value to 0 to reduce peak memory usage.
+ */
+#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 */
+
 #if defined(MBEDTLS_ECP_RESTARTABLE)
 
 /**
@@ -250,68 +332,6 @@
 #endif /* MBEDTLS_ECP_RESTARTABLE */
 
 /**
- * \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 using the compiler command line.
- * \{
- */
-
-#if !defined(MBEDTLS_ECP_MAX_BITS)
-/**
- * The maximum size of the groups, that is, of \c N and \c P.
- */
-#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 )
-#define MBEDTLS_ECP_MAX_PT_LEN   ( 2 * MBEDTLS_ECP_MAX_BYTES + 1 )
-
-#if !defined(MBEDTLS_ECP_WINDOW_SIZE)
-/*
- * Maximum "window" size used for point multiplication.
- * Default: 6.
- * Minimum value: 2. Maximum value: 7.
- *
- * Result is an array of at most ( 1 << ( MBEDTLS_ECP_WINDOW_SIZE - 1 ) )
- * points used for point multiplication. This value is directly tied to EC
- * peak memory usage, so decreasing it by one should roughly cut memory usage
- * by two (if large curves are in use).
- *
- * Reduction in size may reduce speed, but larger curves are impacted first.
- * Sample performances (in ECDHE handshakes/s, with FIXED_POINT_OPTIM = 1):
- *      w-size:     6       5       4       3       2
- *      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   /**< The maximum window size used. */
-#endif /* MBEDTLS_ECP_WINDOW_SIZE */
-
-#if !defined(MBEDTLS_ECP_FIXED_POINT_OPTIM)
-/*
- * Trade memory for speed on fixed-point multiplication.
- *
- * This speeds up repeated multiplication of the generator (that is, the
- * multiplication in ECDSA signatures, and half of the multiplications in
- * ECDSA verification and ECDHE) by a factor roughly 3 to 4.
- *
- * The cost is increasing EC peak memory usage by a factor roughly 2.
- *
- * Change this value to 0 to reduce peak memory usage.
- */
-#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.
@@ -355,19 +375,19 @@
  *                  same; they must not be used until the function finally
  *                  returns 0.
  *
- *                  This only applies to functions whose documentation
- *                  mentions they may return #MBEDTLS_ERR_ECP_IN_PROGRESS (or
- *                  #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS for functions in the
- *                  SSL module). For functions that accept a "restart context"
- *                  argument, passing NULL disables restart and makes the
- *                  function equivalent to the function with the same name
+ *                  This only applies to functions whose documentation mentions
+ *                  they may return #MBEDTLS_ERR_ECP_IN_PROGRESS (or
+ *                  `MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS` for functions in the
+ *                  Mbed TLS SSL module). For functions that accept a "restart
+ *                  context" argument, passing NULL disables restart and makes
+ *                  the function equivalent to the function with the same name
  *                  with \c _restartable removed. For functions in the ECDH
- *                  module, restart is disabled unless the function accepts
- *                  an "ECDH context" argument and
- *                  mbedtls_ecdh_enable_restart() was previously called on
- *                  that context. For function in the SSL module, restart is
- *                  only enabled for specific sides and key exchanges
- *                  (currently only for clients and ECDHE-ECDSA).
+ *                  module, restart is disabled unless the function accepts an
+ *                  "ECDH context" argument and mbedtls_ecdh_enable_restart()
+ *                  was previously called on that context. For function in the
+ *                  Mbed TLS SSL module, restart is only enabled for specific
+ *                  sides and key exchanges (currently only for clients and
+ *                  ECDHE-ECDSA).
  *
  * \param max_ops   Maximum number of basic operations done in a row.
  *                  Default: 0 (unlimited).
@@ -407,6 +427,11 @@
 int mbedtls_ecp_restart_is_enabled( void );
 #endif /* MBEDTLS_ECP_RESTARTABLE */
 
+/*
+ * Get the type of a curve
+ */
+mbedtls_ecp_curve_type mbedtls_ecp_get_type( const mbedtls_ecp_group *grp );
+
 /**
  * \brief           This function retrieves the information defined in
  *                  mbedtls_ecp_curve_info() for all supported curves in order
@@ -472,7 +497,7 @@
  *
  * \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()
+ *                  mbedtls_ecp_group_load() or mbedtls_ecp_tls_read_group()
  *                  functions.
  */
 void mbedtls_ecp_group_init( mbedtls_ecp_group *grp );
@@ -493,24 +518,37 @@
 
 /**
  * \brief           This function frees the components of an ECP group.
- * \param grp       The group to free.
+ *
+ * \param grp       The group to free. This may be \c NULL, in which
+ *                  case this function returns immediately. If it is not
+ *                  \c NULL, it must point to an initialized ECP group.
  */
 void mbedtls_ecp_group_free( mbedtls_ecp_group *grp );
 
 /**
  * \brief           This function frees the components of a key pair.
- * \param key       The key pair to free.
+ *
+ * \param key       The key pair to free. This may be \c NULL, in which
+ *                  case this function returns immediately. If it is not
+ *                  \c NULL, it must point to an initialized ECP key pair.
  */
 void mbedtls_ecp_keypair_free( mbedtls_ecp_keypair *key );
 
 #if defined(MBEDTLS_ECP_RESTARTABLE)
 /**
- * \brief           Initialize a restart context
+ * \brief           Initialize a restart context.
+ *
+ * \param ctx       The restart context to initialize. This must
+ *                  not be \c NULL.
  */
 void mbedtls_ecp_restart_init( mbedtls_ecp_restart_ctx *ctx );
 
 /**
- * \brief           Free the components of a restart context
+ * \brief           Free the components of a restart context.
+ *
+ * \param ctx       The restart context to free. This may be \c NULL, in which
+ *                  case this function returns immediately. If it is not
+ *                  \c NULL, it must point to an initialized restart context.
  */
 void mbedtls_ecp_restart_free( mbedtls_ecp_restart_ctx *ctx );
 #endif /* MBEDTLS_ECP_RESTARTABLE */
@@ -519,11 +557,12 @@
  * \brief           This function copies the contents of point \p Q into
  *                  point \p P.
  *
- * \param P         The destination point.
- * \param Q         The source point.
+ * \param P         The destination point. This must be initialized.
+ * \param Q         The source point. This must be initialized.
  *
  * \return          \c 0 on success.
  * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
+ * \return          Another negative error code for other kinds of failure.
  */
 int mbedtls_ecp_copy( mbedtls_ecp_point *P, const mbedtls_ecp_point *Q );
 
@@ -531,31 +570,35 @@
  * \brief           This function copies the contents of group \p src into
  *                  group \p dst.
  *
- * \param dst       The destination group.
- * \param src       The source group.
+ * \param dst       The destination group. This must be initialized.
+ * \param src       The source group. This must be initialized.
  *
  * \return          \c 0 on success.
  * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
+ * \return          Another negative error code on other kinds of failure.
  */
-int mbedtls_ecp_group_copy( mbedtls_ecp_group *dst, const mbedtls_ecp_group *src );
+int mbedtls_ecp_group_copy( mbedtls_ecp_group *dst,
+                            const mbedtls_ecp_group *src );
 
 /**
- * \brief           This function sets a point to zero.
+ * \brief           This function sets a point to the point at infinity.
  *
- * \param pt        The point to set.
+ * \param pt        The point to set. This must be initialized.
  *
  * \return          \c 0 on success.
  * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
+ * \return          Another negative error code on other kinds of failure.
  */
 int mbedtls_ecp_set_zero( mbedtls_ecp_point *pt );
 
 /**
- * \brief           This function checks if a point is zero.
+ * \brief           This function checks if a point is the point at infinity.
  *
- * \param pt        The point to test.
+ * \param pt        The point to test. This must be initialized.
  *
  * \return          \c 1 if the point is zero.
  * \return          \c 0 if the point is non-zero.
+ * \return          A negative error code on failure.
  */
 int mbedtls_ecp_is_zero( mbedtls_ecp_point *pt );
 
@@ -565,8 +608,8 @@
  * \note            This assumes that the points are normalized. Otherwise,
  *                  they may compare as "not equal" even if they are.
  *
- * \param P         The first point to compare.
- * \param Q         The second point to compare.
+ * \param P         The first point to compare. This must be initialized.
+ * \param Q         The second point to compare. This must be initialized.
  *
  * \return          \c 0 if the points are equal.
  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the points are not equal.
@@ -578,7 +621,7 @@
  * \brief           This function imports a non-zero point from two ASCII
  *                  strings.
  *
- * \param P         The destination point.
+ * \param P         The destination point. This must be initialized.
  * \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.
@@ -593,19 +636,31 @@
  * \brief           This function exports a point into unsigned binary data.
  *
  * \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.
+ *                  This must be initialized and have group parameters
+ *                  set, for example through mbedtls_ecp_group_load().
+ * \param P         The point to export. This must be initialized.
+ * \param format    The point format. This must be either
+ *                  #MBEDTLS_ECP_PF_COMPRESSED or #MBEDTLS_ECP_PF_UNCOMPRESSED.
+ *                  (For groups without these formats, this parameter is
+ *                  ignored. But it still has to be either of the above
+ *                  values.)
+ * \param olen      The address at which to store the length of
+ *                  the output in Bytes. This must not be \c NULL.
+ * \param buf       The output buffer. This must be a writable buffer
+ *                  of length \p buflen Bytes.
+ * \param buflen    The length of the output buffer \p buf in Bytes.
  *
  * \return          \c 0 on success.
- * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA
- *                  or #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL on failure.
+ * \return          #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the output buffer
+ *                  is too small to hold the point.
+ * \return          #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format
+ *                  or the export for the given group is not implemented.
+ * \return          Another negative error code on other kinds of 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 );
+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           This function imports a point from unsigned binary data.
@@ -615,108 +670,158 @@
  *                  for that.
  *
  * \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.
+ *                  This must be initialized and have group parameters
+ *                  set, for example through mbedtls_ecp_group_load().
+ * \param P         The destination context to import the point to.
+ *                  This must be initialized.
+ * \param buf       The input buffer. This must be a readable buffer
+ *                  of length \p ilen Bytes.
+ * \param ilen      The length of the input buffer \p buf in Bytes.
  *
  * \return          \c 0 on success.
- * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
+ * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the 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.
- *
+ * \return          #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the import for the
+ *                  given group is not implemented.
  */
-int mbedtls_ecp_point_read_binary( const mbedtls_ecp_group *grp, mbedtls_ecp_point *P,
-                           const unsigned char *buf, size_t ilen );
+int mbedtls_ecp_point_read_binary( const mbedtls_ecp_group *grp,
+                                   mbedtls_ecp_point *P,
+                                   const unsigned char *buf, size_t ilen );
 
 /**
  * \brief           This function imports a point from a TLS ECPoint record.
  *
- * \note            On function return, \p buf is updated to point to immediately
+ * \note            On function return, \p *buf is updated to point immediately
  *                  after the ECPoint record.
  *
- * \param grp       The ECP group used.
+ * \param grp       The ECP group to use.
+ *                  This must be initialized and have group parameters
+ *                  set, for example through mbedtls_ecp_group_load().
  * \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          \c 0 on success.
- * \return          An \c MBEDTLS_ERR_MPI_XXX error code on initialization failure.
+ * \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 );
+int mbedtls_ecp_tls_read_point( const mbedtls_ecp_group *grp,
+                                mbedtls_ecp_point *pt,
+                                const unsigned char **buf, size_t len );
 
 /**
- * \brief           This function exports a point as a TLS ECPoint record.
+ * \brief           This function exports a point as a TLS ECPoint record
+ *                  defined in RFC 4492, Section 5.4.
  *
- * \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.
+ * \param grp       The ECP group to use.
+ *                  This must be initialized and have group parameters
+ *                  set, for example through mbedtls_ecp_group_load().
+ * \param pt        The point to be exported. This must be initialized.
+ * \param format    The point format to use. This must be either
+ *                  #MBEDTLS_ECP_PF_COMPRESSED or #MBEDTLS_ECP_PF_UNCOMPRESSED.
+ * \param olen      The address at which to store the length in Bytes
+ *                  of the data written.
+ * \param buf       The target buffer. This must be a writable buffer of
+ *                  length \p blen Bytes.
+ * \param blen      The length of the target buffer \p buf in Bytes.
  *
  * \return          \c 0 on success.
- * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA or
- *                  #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL on failure.
+ * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the input is invalid.
+ * \return          #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the target buffer
+ *                  is too small to hold the exported point.
+ * \return          Another negative error code on other kinds of 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 );
+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           This function sets a group using standardized domain parameters.
+ * \brief           This function sets up an ECP group context
+ *                  from a standardized set of 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.
  *
- * \param grp       The destination group.
+ * \param grp       The group context to setup. This must be initialized.
  * \param id        The identifier of the domain parameter set to load.
  *
- * \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.
-
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if \p id doesn't
+ *                  correspond to a known group.
+ * \return          Another negative error code on other kinds of failure.
  */
 int mbedtls_ecp_group_load( mbedtls_ecp_group *grp, mbedtls_ecp_group_id id );
 
 /**
- * \brief           This function sets a group from a TLS ECParameters record.
+ * \brief           This function sets up an ECP group context from a TLS
+ *                  ECParameters record as defined in RFC 4492, Section 5.4.
  *
- * \note            \p buf is updated to point right after the ECParameters record
- *                  on exit.
+ * \note            The read pointer \p buf is updated to point right after
+ *                  the ECParameters record on exit.
  *
- * \param grp       The destination group.
+ * \param grp       The group context to setup. This must be initialized.
  * \param buf       The address of the pointer to the start of the input buffer.
- * \param len       The length of the buffer.
+ * \param len       The length of the input buffer \c *buf in Bytes.
  *
  * \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.
+ * \return          #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the group is not
+ *                  recognized.
+ * \return          Another negative error code on other kinds of failure.
  */
-int mbedtls_ecp_tls_read_group( mbedtls_ecp_group *grp, const unsigned char **buf, size_t len );
+int mbedtls_ecp_tls_read_group( mbedtls_ecp_group *grp,
+                                const unsigned char **buf, size_t len );
 
 /**
- * \brief           This function writes the TLS ECParameters record for a group.
+ * \brief           This function extracts an elliptic curve group ID from a
+ *                  TLS ECParameters record as defined in RFC 4492, Section 5.4.
  *
- * \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.
+ * \note            The read pointer \p buf is updated to point right after
+ *                  the ECParameters record on exit.
+ *
+ * \param grp       The address at which to store the group id.
+ *                  This must not be \c NULL.
+ * \param buf       The address of the pointer to the start of the input buffer.
+ * \param len       The length of the input buffer \c *buf in Bytes.
  *
  * \return          \c 0 on success.
- * \return          #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL on failure.
+ * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
+ * \return          #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the group is not
+ *                  recognized.
+ * \return          Another negative error code on other kinds of failure.
  */
-int mbedtls_ecp_tls_write_group( const mbedtls_ecp_group *grp, size_t *olen,
-                         unsigned char *buf, size_t blen );
+int mbedtls_ecp_tls_read_group_id( mbedtls_ecp_group_id *grp,
+                                   const unsigned char **buf,
+                                   size_t len );
+/**
+ * \brief           This function exports an elliptic curve as a TLS
+ *                  ECParameters record as defined in RFC 4492, Section 5.4.
+ *
+ * \param grp       The ECP group to be exported.
+ *                  This must be initialized and have group parameters
+ *                  set, for example through mbedtls_ecp_group_load().
+ * \param olen      The address at which to store the number of Bytes written.
+ *                  This must not be \c NULL.
+ * \param buf       The buffer to write to. This must be a writable buffer
+ *                  of length \p blen Bytes.
+ * \param blen      The length of the output buffer \p buf in Bytes.
+ *
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the output
+ *                  buffer is too small to hold the exported group.
+ * \return          Another negative error code on other kinds of failure.
+ */
+int mbedtls_ecp_tls_write_group( const mbedtls_ecp_group *grp,
+                                 size_t *olen,
+                                 unsigned char *buf, size_t blen );
 
 /**
- * \brief           This function performs multiplication of a point by
- *                  an integer: \p R = \p m * \p P.
+ * \brief           This function performs a scalar multiplication of a point
+ *                  by an integer: \p R = \p m * \p P.
  *
  *                  It is not thread-safe to use same group in multiple threads.
  *
@@ -730,17 +835,22 @@
  *                  targeting these results. We recommend always providing
  *                  a non-NULL \p f_rng. The overhead is negligible.
  *
- * \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.
+ * \param grp       The ECP group to use.
+ *                  This must be initialized and have group parameters
+ *                  set, for example through mbedtls_ecp_group_load().
+ * \param R         The point in which to store the result of the calculation.
+ *                  This must be initialized.
+ * \param m         The integer by which to multiply. This must be initialized.
+ * \param P         The point to multiply. This must be initialized.
+ * \param f_rng     The RNG function. This may be \c NULL if randomization
+ *                  of intermediate results isn't desired (discouraged).
+ * \param p_rng     The RNG context to be passed to \p p_rng.
  *
  * \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.
+ * \return          Another negative error code on other kinds of failure.
  */
 int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
              const mbedtls_mpi *m, const mbedtls_ecp_point *P,
@@ -756,12 +866,16 @@
  *                  it can return early and restart according to the limit set
  *                  with \c mbedtls_ecp_set_max_ops() to reduce blocking.
  *
- * \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.
+ * \param grp       The ECP group to use.
+ *                  This must be initialized and have group parameters
+ *                  set, for example through mbedtls_ecp_group_load().
+ * \param R         The point in which to store the result of the calculation.
+ *                  This must be initialized.
+ * \param m         The integer by which to multiply. This must be initialized.
+ * \param P         The point to multiply. This must be initialized.
+ * \param f_rng     The RNG function. This may be \c NULL if randomization
+ *                  of intermediate results isn't desired (discouraged).
+ * \param p_rng     The RNG context to be passed to \p p_rng.
  * \param rs_ctx    The restart context (NULL disables restart).
  *
  * \return          \c 0 on success.
@@ -770,6 +884,7 @@
  * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
  * \return          #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
  *                  operations was reached: see \c mbedtls_ecp_set_max_ops().
+ * \return          Another negative error code on other kinds of failure.
  */
 int mbedtls_ecp_mul_restartable( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
              const mbedtls_mpi *m, const mbedtls_ecp_point *P,
@@ -785,18 +900,25 @@
  * \note            In contrast to mbedtls_ecp_mul(), this function does not
  *                  guarantee a constant execution flow and timing.
  *
- * \param grp       The ECP group.
- * \param R         The destination point.
+ * \param grp       The ECP group to use.
+ *                  This must be initialized and have group parameters
+ *                  set, for example through mbedtls_ecp_group_load().
+ * \param R         The point in which to store the result of the calculation.
+ *                  This must be initialized.
  * \param m         The integer by which to multiply \p P.
- * \param P         The point to multiply by \p m.
+ *                  This must be initialized.
+ * \param P         The point to multiply by \p m. This must be initialized.
  * \param n         The integer by which to multiply \p Q.
+ *                  This must be initialized.
  * \param Q         The point to be multiplied by \p n.
+ *                  This must be initialized.
  *
  * \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.
+ * \return          Another negative error code on other kinds of failure.
  */
 int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
              const mbedtls_mpi *m, const mbedtls_ecp_point *P,
@@ -813,12 +935,18 @@
  *                  but it can return early and restart according to the limit
  *                  set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
  *
- * \param grp       The ECP group.
- * \param R         The destination point.
+ * \param grp       The ECP group to use.
+ *                  This must be initialized and have group parameters
+ *                  set, for example through mbedtls_ecp_group_load().
+ * \param R         The point in which to store the result of the calculation.
+ *                  This must be initialized.
  * \param m         The integer by which to multiply \p P.
- * \param P         The point to multiply by \p m.
+ *                  This must be initialized.
+ * \param P         The point to multiply by \p m. This must be initialized.
  * \param n         The integer by which to multiply \p Q.
+ *                  This must be initialized.
  * \param Q         The point to be multiplied by \p n.
+ *                  This must be initialized.
  * \param rs_ctx    The restart context (NULL disables restart).
  *
  * \return          \c 0 on success.
@@ -828,6 +956,7 @@
  * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
  * \return          #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
  *                  operations was reached: see \c mbedtls_ecp_set_max_ops().
+ * \return          Another negative error code on other kinds of failure.
  */
 int mbedtls_ecp_muladd_restartable(
              mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
@@ -852,38 +981,51 @@
  *                  structures, such as ::mbedtls_ecdh_context or
  *                  ::mbedtls_ecdsa_context.
  *
- * \param grp       The curve the point should lie on.
- * \param pt        The point to check.
+ * \param grp       The ECP group the point should belong to.
+ *                  This must be initialized and have group parameters
+ *                  set, for example through mbedtls_ecp_group_load().
+ * \param pt        The point to check. This must be initialized.
  *
  * \return          \c 0 if the point is a valid public key.
- * \return          #MBEDTLS_ERR_ECP_INVALID_KEY on failure.
+ * \return          #MBEDTLS_ERR_ECP_INVALID_KEY if the point is not
+ *                  a valid public key for the given curve.
+ * \return          Another negative error code on other kinds of failure.
  */
-int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *pt );
+int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp,
+                              const mbedtls_ecp_point *pt );
 
 /**
- * \brief           This function checks that an \p 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.
  *
  * \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.
  *
- * \param grp       The group used.
- * \param d         The integer to check.
+ * \param grp       The ECP group the private key should belong to.
+ *                  This must be initialized and have group parameters
+ *                  set, for example through mbedtls_ecp_group_load().
+ * \param d         The integer to check. This must be initialized.
  *
  * \return          \c 0 if the point is a valid private key.
- * \return          #MBEDTLS_ERR_ECP_INVALID_KEY on failure.
+ * \return          #MBEDTLS_ERR_ECP_INVALID_KEY if the point is not a valid
+ *                  private key for the given curve.
+ * \return          Another negative error code on other kinds of failure.
  */
-int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp, const mbedtls_mpi *d );
+int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp,
+                               const mbedtls_mpi *d );
 
 /**
  * \brief           This function generates a private key.
  *
- * \param grp       The ECP group.
- * \param d         The destination MPI (secret part).
- * \param f_rng     The RNG function.
- * \param p_rng     The RNG parameter.
+ * \param grp       The ECP group to generate a private key for.
+ *                  This must be initialized and have group parameters
+ *                  set, for example through mbedtls_ecp_group_load().
+ * \param d         The destination MPI (secret part). This must be initialized.
+ * \param f_rng     The RNG function. This must not be \c NULL.
+ * \param p_rng     The RNG parameter to be passed to \p f_rng. This may be
+ *                  \c NULL if \p f_rng doesn't need a context argument.
  *
  * \return          \c 0 on success.
  * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
@@ -903,22 +1045,29 @@
  *                  structures, such as ::mbedtls_ecdh_context or
  *                  ::mbedtls_ecdsa_context.
  *
- * \param grp       The ECP group.
- * \param G         The chosen base point.
+ * \param grp       The ECP group to generate a key pair for.
+ *                  This must be initialized and have group parameters
+ *                  set, for example through mbedtls_ecp_group_load().
+ * \param G         The base point to use. This must be initialized
+ *                  and belong to \p grp. It replaces the default base
+ *                  point \c grp->G used by mbedtls_ecp_gen_keypair().
  * \param d         The destination MPI (secret part).
+ *                  This must be initialized.
  * \param Q         The destination point (public part).
- * \param f_rng     The RNG function.
- * \param p_rng     The RNG context.
+ *                  This must be initialized.
+ * \param f_rng     The RNG function. This must not be \c NULL.
+ * \param p_rng     The RNG context to be passed to \p f_rng. This may
+ *                  be \c NULL if \p f_rng doesn't need a context argument.
  *
  * \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,
-                     mbedtls_mpi *d, mbedtls_ecp_point *Q,
-                     int (*f_rng)(void *, unsigned char *, size_t),
-                     void *p_rng );
+                                  const mbedtls_ecp_point *G,
+                                  mbedtls_mpi *d, mbedtls_ecp_point *Q,
+                                  int (*f_rng)(void *, unsigned char *, size_t),
+                                  void *p_rng );
 
 /**
  * \brief           This function generates an ECP keypair.
@@ -928,51 +1077,82 @@
  *                  structures, such as ::mbedtls_ecdh_context or
  *                  ::mbedtls_ecdsa_context.
  *
- * \param grp       The ECP group.
+ * \param grp       The ECP group to generate a key pair for.
+ *                  This must be initialized and have group parameters
+ *                  set, for example through mbedtls_ecp_group_load().
  * \param d         The destination MPI (secret part).
+ *                  This must be initialized.
  * \param Q         The destination point (public part).
- * \param f_rng     The RNG function.
- * \param p_rng     The RNG context.
+ *                  This must be initialized.
+ * \param f_rng     The RNG function. This must not be \c NULL.
+ * \param p_rng     The RNG context to be passed to \p f_rng. This may
+ *                  be \c NULL if \p f_rng doesn't need a context argument.
  *
  * \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 );
+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           This function generates an ECP key.
  *
  * \param grp_id    The ECP group identifier.
- * \param key       The destination key.
- * \param f_rng     The RNG function.
- * \param p_rng     The RNG context.
+ * \param key       The destination key. This must be initialized.
+ * \param f_rng     The RNG function to use. This must not be \c NULL.
+ * \param p_rng     The RNG context to be passed to \p f_rng. This may
+ *                  be \c NULL if \p f_rng doesn't need a context argument.
  *
  * \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 );
+                         int (*f_rng)(void *, unsigned char *, size_t),
+                         void *p_rng );
 
 /**
+ * \brief           This function reads an elliptic curve private key.
+ *
+ * \param grp_id    The ECP group identifier.
+ * \param key       The destination key.
+ * \param buf       The the buffer containing the binary representation of the
+ *                  key. (Big endian integer for Weierstrass curves, byte
+ *                  string for Montgomery curves.)
+ * \param buflen    The length of the buffer in bytes.
+ *
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_ECP_INVALID_KEY error if the key is
+ *                  invalid.
+ * \return          #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
+ * \return          #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the operation for
+ *                  the group is not implemented.
+ * \return          Another negative error code on different kinds of failure.
+ */
+int mbedtls_ecp_read_key( mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key,
+                          const unsigned char *buf, size_t buflen );
+/**
  * \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       The keypair structure holding the public key.
- *                  If it contains a private key, that part is ignored.
+ * \param pub       The keypair structure holding the public key. This
+ *                  must be initialized. If it contains a private key, that
+ *                  part is ignored.
  * \param prv       The keypair structure holding the full keypair.
+ *                  This must be initialized.
  *
  * \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 );
+int mbedtls_ecp_check_pub_priv( const mbedtls_ecp_keypair *pub,
+                                const mbedtls_ecp_keypair *prv );
 
 #if defined(MBEDTLS_SELF_TEST)
 
diff --git a/include/mbedtls/ecp_internal.h b/include/mbedtls/ecp_internal.h
index 1804069..7625ed4 100644
--- a/include/mbedtls/ecp_internal.h
+++ b/include/mbedtls/ecp_internal.h
@@ -61,6 +61,12 @@
 #ifndef MBEDTLS_ECP_INTERNAL_H
 #define MBEDTLS_ECP_INTERNAL_H
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
 #if defined(MBEDTLS_ECP_INTERNAL_ALT)
 
 /**
diff --git a/include/mbedtls/error.h b/include/mbedtls/error.h
index 0c38889..bee0fe4 100644
--- a/include/mbedtls/error.h
+++ b/include/mbedtls/error.h
@@ -24,6 +24,12 @@
 #ifndef MBEDTLS_ERROR_H
 #define MBEDTLS_ERROR_H
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
 #include <stddef.h>
 
 /**
@@ -74,9 +80,9 @@
  * MD4       1                  0x002D-0x002D
  * MD5       1                  0x002F-0x002F
  * RIPEMD160 1                  0x0031-0x0031
- * SHA1      1                  0x0035-0x0035
- * SHA256    1                  0x0037-0x0037
- * SHA512    1                  0x0039-0x0039
+ * SHA1      1                  0x0035-0x0035 0x0073-0x0073
+ * SHA256    1                  0x0037-0x0037 0x0074-0x0074
+ * SHA512    1                  0x0039-0x0039 0x0075-0x0075
  * CHACHA20  3                  0x0051-0x0055
  * POLY1305  3                  0x0057-0x005B
  * CHACHAPOLY 2 0x0054-0x0056
diff --git a/include/mbedtls/gcm.h b/include/mbedtls/gcm.h
index 93d15ee..fd130ab 100644
--- a/include/mbedtls/gcm.h
+++ b/include/mbedtls/gcm.h
@@ -33,6 +33,12 @@
 #ifndef MBEDTLS_GCM_H
 #define MBEDTLS_GCM_H
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
 #include "cipher.h"
 
 #include <stdint.h>
@@ -85,7 +91,7 @@
  *                  cipher, nor set the key. For this purpose, use
  *                  mbedtls_gcm_setkey().
  *
- * \param ctx       The GCM context to initialize.
+ * \param ctx       The GCM context to initialize. This must not be \c NULL.
  */
 void mbedtls_gcm_init( mbedtls_gcm_context *ctx );
 
@@ -93,9 +99,10 @@
  * \brief           This function associates a GCM context with a
  *                  cipher algorithm and a key.
  *
- * \param ctx       The GCM context to initialize.
+ * \param ctx       The GCM context. This must be initialized.
  * \param cipher    The 128-bit block cipher to use.
- * \param key       The encryption key.
+ * \param key       The encryption key. This must be a readable buffer of at
+ *                  least \p keybits bits.
  * \param keybits   The key size in bits. Valid options are:
  *                  <ul><li>128 bits</li>
  *                  <li>192 bits</li>
@@ -122,7 +129,8 @@
  *                  authentic. You should use this function to perform encryption
  *                  only. For decryption, use mbedtls_gcm_auth_decrypt() instead.
  *
- * \param ctx       The GCM context to use for encryption or decryption.
+ * \param ctx       The GCM context to use for encryption or decryption. This
+ *                  must be initialized.
  * \param mode      The operation to perform:
  *                  - #MBEDTLS_GCM_ENCRYPT to perform authenticated encryption.
  *                    The ciphertext is written to \p output and the
@@ -136,21 +144,27 @@
  *                    calling this function in decryption mode.
  * \param length    The length of the input data, which is equal to the length
  *                  of the output data.
- * \param iv        The initialization vector.
+ * \param iv        The initialization vector. This must be a readable buffer of
+ *                  at least \p iv_len Bytes.
  * \param iv_len    The length of the IV.
- * \param add       The buffer holding the additional data.
+ * \param add       The buffer holding the additional data. This must be of at
+ *                  least that size in Bytes.
  * \param add_len   The length of the additional data.
- * \param input     The buffer holding the input data. Its size is \b length.
- * \param output    The buffer for holding the output data. It must have room
- *                  for \b length bytes.
+ * \param input     The buffer holding the input data. If \p length is greater
+ *                  than zero, this must be a readable buffer of at least that
+ *                  size in Bytes.
+ * \param output    The buffer for holding the output data. If \p length is greater
+ *                  than zero, this must be a writable buffer of at least that
+ *                  size in Bytes.
  * \param tag_len   The length of the tag to generate.
- * \param tag       The buffer for holding the tag.
+ * \param tag       The buffer for holding the tag. This must be a readable
+ *                  buffer of at least \p tag_len Bytes.
  *
  * \return          \c 0 if the encryption or decryption was performed
  *                  successfully. Note that in #MBEDTLS_GCM_DECRYPT mode,
  *                  this does not indicate that the data is authentic.
- * \return          #MBEDTLS_ERR_GCM_BAD_INPUT if the lengths are not valid or
- *                  a cipher-specific error code if the encryption
+ * \return          #MBEDTLS_ERR_GCM_BAD_INPUT if the lengths or pointers are
+ *                  not valid or a cipher-specific error code if the encryption
  *                  or decryption failed.
  */
 int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx,
@@ -173,23 +187,30 @@
  *                  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 ctx       The GCM context. This must be initialized.
  * \param length    The length of the ciphertext to decrypt, which is also
  *                  the length of the decrypted plaintext.
- * \param iv        The initialization vector.
+ * \param iv        The initialization vector. This must be a readable buffer
+ *                  of at least \p iv_len Bytes.
  * \param iv_len    The length of the IV.
- * \param add       The buffer holding the additional data.
+ * \param add       The buffer holding the additional data. This must be of at
+ *                  least that size in Bytes.
  * \param add_len   The length of the additional data.
- * \param tag       The buffer holding the tag to verify.
+ * \param tag       The buffer holding the tag to verify. This must be a
+ *                  readable buffer of at least \p tag_len Bytes.
  * \param tag_len   The length of the tag to verify.
- * \param input     The buffer holding the ciphertext. Its size is \b length.
- * \param output    The buffer for holding the decrypted plaintext. It must
- *                  have room for \b length bytes.
+ * \param input     The buffer holding the ciphertext. If \p length is greater
+ *                  than zero, this must be a readable buffer of at least that
+ *                  size.
+ * \param output    The buffer for holding the decrypted plaintext. If \p length
+ *                  is greater than zero, this must be a writable buffer of at
+ *                  least that size.
  *
  * \return          \c 0 if successful and authenticated.
  * \return          #MBEDTLS_ERR_GCM_AUTH_FAILED if the tag does not match.
- * \return          #MBEDTLS_ERR_GCM_BAD_INPUT if the lengths are not valid or
- *                  a cipher-specific error code if the decryption failed.
+ * \return          #MBEDTLS_ERR_GCM_BAD_INPUT if the lengths or pointers are
+ *                  not valid or a cipher-specific error code if the decryption
+ *                  failed.
  */
 int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx,
                       size_t length,
@@ -206,15 +227,16 @@
  * \brief           This function starts a GCM encryption or decryption
  *                  operation.
  *
- * \param ctx       The GCM context.
+ * \param ctx       The GCM context. This must be initialized.
  * \param mode      The operation to perform: #MBEDTLS_GCM_ENCRYPT or
  *                  #MBEDTLS_GCM_DECRYPT.
- * \param iv        The initialization vector.
+ * \param iv        The initialization vector. This must be a readable buffer of
+ *                  at least \p iv_len Bytes.
  * \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 \c NULL
+ *                  if \p add_len is \c 0.
+ * \param add_len   The length of the additional data. If \c 0,
+ *                  \p add may be \c NULL.
  *
  * \return          \c 0 on success.
  */
@@ -237,11 +259,15 @@
  *                  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 ctx       The GCM context. This must be initialized.
  * \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.
+ * \param input     The buffer holding the input data. If \p length is greater
+ *                  than zero, this must be a readable buffer of at least that
+ *                  size in Bytes.
+ * \param output    The buffer for holding the output data. If \p length is
+ *                  greater than zero, this must be a writable buffer of at
+ *                  least that size in Bytes.
  *
  * \return         \c 0 on success.
  * \return         #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
@@ -258,9 +284,11 @@
  *                  It wraps up the GCM stream, and generates the
  *                  tag. The tag can have a maximum length of 16 Bytes.
  *
- * \param ctx       The GCM context.
- * \param tag       The buffer for holding the tag.
- * \param tag_len   The length of the tag to generate. Must be at least four.
+ * \param ctx       The GCM context. This must be initialized.
+ * \param tag       The buffer for holding the tag. This must be a readable
+ *                  buffer of at least \p tag_len Bytes.
+ * \param tag_len   The length of the tag to generate. This must be at least
+ *                  four.
  *
  * \return          \c 0 on success.
  * \return          #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
@@ -273,10 +301,13 @@
  * \brief           This function clears a GCM context and the underlying
  *                  cipher sub-context.
  *
- * \param ctx       The GCM context to clear.
+ * \param ctx       The GCM context to clear. If this is \c NULL, the call has
+ *                  no effect. Otherwise, this must be initialized.
  */
 void mbedtls_gcm_free( mbedtls_gcm_context *ctx );
 
+#if defined(MBEDTLS_SELF_TEST)
+
 /**
  * \brief          The GCM checkup routine.
  *
@@ -285,6 +316,8 @@
  */
 int mbedtls_gcm_self_test( int verbose );
 
+#endif /* MBEDTLS_SELF_TEST */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/mbedtls/havege.h b/include/mbedtls/havege.h
index 57e8c40..4c1c860 100644
--- a/include/mbedtls/havege.h
+++ b/include/mbedtls/havege.h
@@ -24,6 +24,12 @@
 #ifndef MBEDTLS_HAVEGE_H
 #define MBEDTLS_HAVEGE_H
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
 #include <stddef.h>
 
 #define MBEDTLS_HAVEGE_COLLECT_SIZE 1024
diff --git a/include/mbedtls/hkdf.h b/include/mbedtls/hkdf.h
index e6ed7cd..40ee64e 100644
--- a/include/mbedtls/hkdf.h
+++ b/include/mbedtls/hkdf.h
@@ -27,6 +27,12 @@
 #ifndef MBEDTLS_HKDF_H
 #define MBEDTLS_HKDF_H
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
 #include "md.h"
 
 /**
diff --git a/include/mbedtls/hmac_drbg.h b/include/mbedtls/hmac_drbg.h
index 3bc675e..f1289cb 100644
--- a/include/mbedtls/hmac_drbg.h
+++ b/include/mbedtls/hmac_drbg.h
@@ -24,6 +24,12 @@
 #ifndef MBEDTLS_HMAC_DRBG_H
 #define MBEDTLS_HMAC_DRBG_H
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
 #include "md.h"
 
 #if defined(MBEDTLS_THREADING_C)
@@ -76,7 +82,7 @@
  */
 typedef struct mbedtls_hmac_drbg_context
 {
-    /* Working state: the key K is not stored explicitely,
+    /* Working state: the key K is not stored explicitly,
      * but is implied by the HMAC context */
     mbedtls_md_context_t md_ctx;                    /*!< HMAC context (inc. K)  */
     unsigned char V[MBEDTLS_MD_MAX_SIZE];  /*!< V in the spec          */
@@ -195,10 +201,13 @@
  * \param additional    Additional data to update state with, or NULL
  * \param add_len       Length of additional data, or 0
  *
+ * \return              \c 0 on success, or an error from the underlying
+ *                      hash calculation.
+ *
  * \note                Additional data is optional, pass NULL and 0 as second
  *                      third argument if no additional data is being used.
  */
-void mbedtls_hmac_drbg_update( mbedtls_hmac_drbg_context *ctx,
+int mbedtls_hmac_drbg_update_ret( mbedtls_hmac_drbg_context *ctx,
                        const unsigned char *additional, size_t add_len );
 
 /**
@@ -257,6 +266,31 @@
  */
 void mbedtls_hmac_drbg_free( mbedtls_hmac_drbg_context *ctx );
 
+#if ! defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED    __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+/**
+ * \brief               HMAC_DRBG update state
+ *
+ * \deprecated          Superseded by mbedtls_hmac_drbg_update_ret()
+ *                      in 2.16.0.
+ *
+ * \param ctx           HMAC_DRBG context
+ * \param additional    Additional data to update state with, or NULL
+ * \param add_len       Length of additional data, or 0
+ *
+ * \note                Additional data is optional, pass NULL and 0 as second
+ *                      third argument if no additional data is being used.
+ */
+MBEDTLS_DEPRECATED void mbedtls_hmac_drbg_update(
+    mbedtls_hmac_drbg_context *ctx,
+    const unsigned char *additional, size_t add_len );
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
+
 #if defined(MBEDTLS_FS_IO)
 /**
  * \brief               Write a seed file
diff --git a/include/mbedtls/md2.h b/include/mbedtls/md2.h
index f9bd98f..fe97cf0 100644
--- a/include/mbedtls/md2.h
+++ b/include/mbedtls/md2.h
@@ -283,6 +283,8 @@
 #undef MBEDTLS_DEPRECATED
 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
 
+#if defined(MBEDTLS_SELF_TEST)
+
 /**
  * \brief          Checkup routine
  *
@@ -295,6 +297,8 @@
  */
 int mbedtls_md2_self_test( int verbose );
 
+#endif /* MBEDTLS_SELF_TEST */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/mbedtls/md4.h b/include/mbedtls/md4.h
index dc3c048..ce703c0 100644
--- a/include/mbedtls/md4.h
+++ b/include/mbedtls/md4.h
@@ -288,6 +288,8 @@
 #undef MBEDTLS_DEPRECATED
 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
 
+#if defined(MBEDTLS_SELF_TEST)
+
 /**
  * \brief          Checkup routine
  *
@@ -300,6 +302,8 @@
  */
 int mbedtls_md4_self_test( int verbose );
 
+#endif /* MBEDTLS_SELF_TEST */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/mbedtls/md5.h b/include/mbedtls/md5.h
index 6c3354f..6eed6cc 100644
--- a/include/mbedtls/md5.h
+++ b/include/mbedtls/md5.h
@@ -288,6 +288,8 @@
 #undef MBEDTLS_DEPRECATED
 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
 
+#if defined(MBEDTLS_SELF_TEST)
+
 /**
  * \brief          Checkup routine
  *
@@ -300,6 +302,8 @@
  */
 int mbedtls_md5_self_test( int verbose );
 
+#endif /* MBEDTLS_SELF_TEST */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/mbedtls/net.h b/include/mbedtls/net.h
index 6c13b53..8cead58 100644
--- a/include/mbedtls/net.h
+++ b/include/mbedtls/net.h
@@ -23,6 +23,11 @@
  *
  *  This file is part of mbed TLS (https://tls.mbed.org)
  */
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
 
 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
 #include "net_sockets.h"
diff --git a/include/mbedtls/nist_kw.h b/include/mbedtls/nist_kw.h
index 5a0f656..3b67b59 100644
--- a/include/mbedtls/nist_kw.h
+++ b/include/mbedtls/nist_kw.h
@@ -37,6 +37,12 @@
 #ifndef MBEDTLS_NIST_KW_H
 #define MBEDTLS_NIST_KW_H
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
 #include "cipher.h"
 
 #ifdef __cplusplus
diff --git a/include/mbedtls/oid.h b/include/mbedtls/oid.h
index 6fbd018..342ef75 100644
--- a/include/mbedtls/oid.h
+++ b/include/mbedtls/oid.h
@@ -43,13 +43,31 @@
 #include "md.h"
 #endif
 
-#if defined(MBEDTLS_X509_USE_C) || defined(MBEDTLS_X509_CREATE_C)
-#include "x509.h"
-#endif
-
 #define MBEDTLS_ERR_OID_NOT_FOUND                         -0x002E  /**< OID is not found. */
 #define MBEDTLS_ERR_OID_BUF_TOO_SMALL                     -0x000B  /**< output buffer is too small */
 
+/* This is for the benefit of X.509, but defined here in order to avoid
+ * having a "backwards" include of x.509.h here */
+/*
+ * X.509 extension types (internal, arbitrary values for bitsets)
+ */
+#define MBEDTLS_OID_X509_EXT_AUTHORITY_KEY_IDENTIFIER    (1 << 0)
+#define MBEDTLS_OID_X509_EXT_SUBJECT_KEY_IDENTIFIER      (1 << 1)
+#define MBEDTLS_OID_X509_EXT_KEY_USAGE                   (1 << 2)
+#define MBEDTLS_OID_X509_EXT_CERTIFICATE_POLICIES        (1 << 3)
+#define MBEDTLS_OID_X509_EXT_POLICY_MAPPINGS             (1 << 4)
+#define MBEDTLS_OID_X509_EXT_SUBJECT_ALT_NAME            (1 << 5)
+#define MBEDTLS_OID_X509_EXT_ISSUER_ALT_NAME             (1 << 6)
+#define MBEDTLS_OID_X509_EXT_SUBJECT_DIRECTORY_ATTRS     (1 << 7)
+#define MBEDTLS_OID_X509_EXT_BASIC_CONSTRAINTS           (1 << 8)
+#define MBEDTLS_OID_X509_EXT_NAME_CONSTRAINTS            (1 << 9)
+#define MBEDTLS_OID_X509_EXT_POLICY_CONSTRAINTS          (1 << 10)
+#define MBEDTLS_OID_X509_EXT_EXTENDED_KEY_USAGE          (1 << 11)
+#define MBEDTLS_OID_X509_EXT_CRL_DISTRIBUTION_POINTS     (1 << 12)
+#define MBEDTLS_OID_X509_EXT_INIHIBIT_ANYPOLICY          (1 << 13)
+#define MBEDTLS_OID_X509_EXT_FRESHEST_CRL                (1 << 14)
+#define MBEDTLS_OID_X509_EXT_NS_CERT_TYPE                (1 << 16)
+
 /*
  * Top level OID tuples
  */
@@ -150,6 +168,11 @@
 #define MBEDTLS_OID_FRESHEST_CRL                MBEDTLS_OID_ID_CE "\x2E" /**< id-ce-freshestCRL OBJECT IDENTIFIER ::=  { id-ce 46 } */
 
 /*
+ * Certificate policies
+ */
+#define MBEDTLS_OID_ANY_POLICY              MBEDTLS_OID_CERTIFICATE_POLICIES "\x00" /**< anyPolicy OBJECT IDENTIFIER ::= { id-ce-certificatePolicies 0 } */
+
+/*
  * Netscape certificate extensions
  */
 #define MBEDTLS_OID_NS_CERT                 MBEDTLS_OID_NETSCAPE "\x01"
@@ -424,7 +447,6 @@
  */
 int mbedtls_oid_get_numeric_string( char *buf, size_t size, const mbedtls_asn1_buf *oid );
 
-#if defined(MBEDTLS_X509_USE_C) || defined(MBEDTLS_X509_CREATE_C)
 /**
  * \brief          Translate an X.509 extension OID into local values
  *
@@ -434,7 +456,6 @@
  * \return         0 if successful, or MBEDTLS_ERR_OID_NOT_FOUND
  */
 int mbedtls_oid_get_x509_ext_type( const mbedtls_asn1_buf *oid, int *ext_type );
-#endif
 
 /**
  * \brief          Translate an X.509 attribute type OID into the short name
@@ -561,6 +582,16 @@
 int mbedtls_oid_get_extended_key_usage( const mbedtls_asn1_buf *oid, const char **desc );
 
 /**
+ * \brief          Translate certificate policies OID into description
+ *
+ * \param oid      OID to use
+ * \param desc     place to store string pointer
+ *
+ * \return         0 if successful, or MBEDTLS_ERR_OID_NOT_FOUND
+ */
+int mbedtls_oid_get_certificate_policies( const mbedtls_asn1_buf *oid, const char **desc );
+
+/**
  * \brief          Translate md_type into hash algorithm OID
  *
  * \param md_alg   message digest algorithm
diff --git a/include/mbedtls/padlock.h b/include/mbedtls/padlock.h
index 677936e..f05b72b 100644
--- a/include/mbedtls/padlock.h
+++ b/include/mbedtls/padlock.h
@@ -3,6 +3,9 @@
  *
  * \brief VIA PadLock ACE for HW encryption/decryption supported by some
  *        processors
+ *
+ * \warning These functions are only for internal use by other library
+ *          functions; you must not call them directly.
  */
 /*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
@@ -25,6 +28,12 @@
 #ifndef MBEDTLS_PADLOCK_H
 #define MBEDTLS_PADLOCK_H
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
 #include "aes.h"
 
 #define MBEDTLS_ERR_PADLOCK_DATA_MISALIGNED               -0x0030  /**< Input data should be aligned. */
@@ -57,7 +66,10 @@
 #endif
 
 /**
- * \brief          PadLock detection routine
+ * \brief          Internal PadLock detection routine
+ *
+ * \note           This function is only for internal use by other library
+ *                 functions; you must not call it directly.
  *
  * \param feature  The feature to detect
  *
@@ -66,7 +78,10 @@
 int mbedtls_padlock_has_support( int feature );
 
 /**
- * \brief          PadLock AES-ECB block en(de)cryption
+ * \brief          Internal PadLock AES-ECB block en(de)cryption
+ *
+ * \note           This function is only for internal use by other library
+ *                 functions; you must not call it directly.
  *
  * \param ctx      AES context
  * \param mode     MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT
@@ -76,12 +91,15 @@
  * \return         0 if success, 1 if operation failed
  */
 int mbedtls_padlock_xcryptecb( mbedtls_aes_context *ctx,
-                       int mode,
-                       const unsigned char input[16],
-                       unsigned char output[16] );
+                               int mode,
+                               const unsigned char input[16],
+                               unsigned char output[16] );
 
 /**
- * \brief          PadLock AES-CBC buffer en(de)cryption
+ * \brief          Internal PadLock AES-CBC buffer en(de)cryption
+ *
+ * \note           This function is only for internal use by other library
+ *                 functions; you must not call it directly.
  *
  * \param ctx      AES context
  * \param mode     MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT
@@ -93,11 +111,11 @@
  * \return         0 if success, 1 if operation failed
  */
 int mbedtls_padlock_xcryptcbc( mbedtls_aes_context *ctx,
-                       int mode,
-                       size_t length,
-                       unsigned char iv[16],
-                       const unsigned char *input,
-                       unsigned char *output );
+                               int mode,
+                               size_t length,
+                               unsigned char iv[16],
+                               const unsigned char *input,
+                               unsigned char *output );
 
 #ifdef __cplusplus
 }
diff --git a/include/mbedtls/pem.h b/include/mbedtls/pem.h
index fa82f7b..a29e9ce 100644
--- a/include/mbedtls/pem.h
+++ b/include/mbedtls/pem.h
@@ -24,6 +24,12 @@
 #ifndef MBEDTLS_PEM_H
 #define MBEDTLS_PEM_H
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
 #include <stddef.h>
 
 /**
diff --git a/include/mbedtls/pk.h b/include/mbedtls/pk.h
index 862065e..24951a6 100644
--- a/include/mbedtls/pk.h
+++ b/include/mbedtls/pk.h
@@ -202,12 +202,18 @@
 const mbedtls_pk_info_t *mbedtls_pk_info_from_type( mbedtls_pk_type_t pk_type );
 
 /**
- * \brief           Initialize a mbedtls_pk_context (as NONE)
+ * \brief           Initialize a #mbedtls_pk_context (as NONE).
+ *
+ * \param ctx       The context to initialize.
+ *                  This must not be \c NULL.
  */
 void mbedtls_pk_init( mbedtls_pk_context *ctx );
 
 /**
- * \brief           Free a mbedtls_pk_context
+ * \brief           Free the components of a #mbedtls_pk_context.
+ *
+ * \param ctx       The context to clear. It must have been initialized.
+ *                  If this is \c NULL, this function does nothing.
  *
  * \note            For contexts that have been set up with
  *                  mbedtls_pk_setup_opaque(), this does not free the underlying
@@ -219,11 +225,17 @@
 #if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
 /**
  * \brief           Initialize a restart context
+ *
+ * \param ctx       The context to initialize.
+ *                  This must not be \c NULL.
  */
 void mbedtls_pk_restart_init( mbedtls_pk_restart_ctx *ctx );
 
 /**
  * \brief           Free the components of a restart context
+ *
+ * \param ctx       The context to clear. It must have been initialized.
+ *                  If this is \c NULL, this function does nothing.
  */
 void mbedtls_pk_restart_free( mbedtls_pk_restart_ctx *ctx );
 #endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
@@ -232,7 +244,8 @@
  * \brief           Initialize a PK context with the information given
  *                  and allocates the type-specific PK subcontext.
  *
- * \param ctx       Context to initialize. Must be empty (type NONE).
+ * \param ctx       Context to initialize. It must not have been set
+ *                  up yet (type #MBEDTLS_PK_NONE).
  * \param info      Information to use
  *
  * \return          0 on success,
@@ -273,14 +286,15 @@
  *                  ECC key pair.
  * \return          #MBEDTLS_ERR_PK_ALLOC_FAILED on allocation failure.
  */
-int mbedtls_pk_setup_opaque( mbedtls_pk_context *ctx, const psa_key_slot_t key );
+int mbedtls_pk_setup_opaque( mbedtls_pk_context *ctx, const psa_key_handle_t key );
 #endif /* MBEDTLS_USE_PSA_CRYPTO */
 
 #if defined(MBEDTLS_PK_RSA_ALT_SUPPORT)
 /**
  * \brief           Initialize an RSA-alt context
  *
- * \param ctx       Context to initialize. Must be empty (type NONE).
+ * \param ctx       Context to initialize. It must not have been set
+ *                  up yet (type #MBEDTLS_PK_NONE).
  * \param key       RSA key pointer
  * \param decrypt_func  Decryption function
  * \param sign_func     Signing function
@@ -300,7 +314,7 @@
 /**
  * \brief           Get the size in bits of the underlying key
  *
- * \param ctx       Context to use
+ * \param ctx       The context to query. It must have been initialized.
  *
  * \return          Key size in bits, or 0 on error
  */
@@ -308,7 +322,8 @@
 
 /**
  * \brief           Get the length in bytes of the underlying key
- * \param ctx       Context to use
+ *
+ * \param ctx       The context to query. It must have been initialized.
  *
  * \return          Key length in bytes, or 0 on error
  */
@@ -320,18 +335,21 @@
 /**
  * \brief           Tell if a context can do the operation given by type
  *
- * \param ctx       Context to test
- * \param type      Target type
+ * \param ctx       The context to query. It must have been initialized.
+ * \param type      The desired type.
  *
- * \return          0 if context can't do the operations,
- *                  1 otherwise.
+ * \return          1 if the context can do operations on the given type.
+ * \return          0 if the context cannot do the operations on the given
+ *                  type. This is always the case for a context that has
+ *                  been initialized but not set up, or that has been
+ *                  cleared with mbedtls_pk_free().
  */
 int mbedtls_pk_can_do( const mbedtls_pk_context *ctx, mbedtls_pk_type_t type );
 
 /**
  * \brief           Verify signature (including padding if relevant).
  *
- * \param ctx       PK context to use
+ * \param ctx       The PK context to use. It must have been set up.
  * \param md_alg    Hash algorithm used (see notes)
  * \param hash      Hash of the message to sign
  * \param hash_len  Hash length or 0 (see notes)
@@ -364,7 +382,7 @@
  *                  \c mbedtls_ecp_set_max_ops() to reduce blocking for ECC
  *                  operations. For RSA, same as \c mbedtls_pk_verify().
  *
- * \param ctx       PK context to use
+ * \param ctx       The PK context to use. It must have been set up.
  * \param md_alg    Hash algorithm used (see notes)
  * \param hash      Hash of the message to sign
  * \param hash_len  Hash length or 0 (see notes)
@@ -388,7 +406,7 @@
  *
  * \param type      Signature type (inc. possible padding type) to verify
  * \param options   Pointer to type-specific options, or NULL
- * \param ctx       PK context to use
+ * \param ctx       The PK context to use. It must have been set up.
  * \param md_alg    Hash algorithm used (see notes)
  * \param hash      Hash of the message to sign
  * \param hash_len  Hash length or 0 (see notes)
@@ -419,7 +437,8 @@
 /**
  * \brief           Make signature, including padding if relevant.
  *
- * \param ctx       PK context to use - must hold a private key
+ * \param ctx       The PK context to use. It must have been set up
+ *                  with a private key.
  * \param md_alg    Hash algorithm used (see notes)
  * \param hash      Hash of the message to sign
  * \param hash_len  Hash length or 0 (see notes)
@@ -453,7 +472,8 @@
  *                  \c mbedtls_ecp_set_max_ops() to reduce blocking for ECC
  *                  operations. For RSA, same as \c mbedtls_pk_sign().
  *
- * \param ctx       PK context to use - must hold a private key
+ * \param ctx       The PK context to use. It must have been set up
+ *                  with a private key.
  * \param md_alg    Hash algorithm used (see notes)
  * \param hash      Hash of the message to sign
  * \param hash_len  Hash length or 0 (see notes)
@@ -477,7 +497,8 @@
 /**
  * \brief           Decrypt message (including padding if relevant).
  *
- * \param ctx       PK context to use - must hold a private key
+ * \param ctx       The PK context to use. It must have been set up
+ *                  with a private key.
  * \param input     Input to decrypt
  * \param ilen      Input size
  * \param output    Decrypted output
@@ -498,7 +519,7 @@
 /**
  * \brief           Encrypt message (including padding if relevant).
  *
- * \param ctx       PK context to use
+ * \param ctx       The PK context to use. It must have been set up.
  * \param input     Message to encrypt
  * \param ilen      Message size
  * \param output    Encrypted output
@@ -533,7 +554,7 @@
 /**
  * \brief           Export debug information
  *
- * \param ctx       Context to use
+ * \param ctx       The PK context to use. It must have been initialized.
  * \param items     Place to write debug items
  *
  * \return          0 on success or MBEDTLS_ERR_PK_BAD_INPUT_DATA
@@ -543,7 +564,7 @@
 /**
  * \brief           Access the type name
  *
- * \param ctx       Context to use
+ * \param ctx       The PK context to use. It must have been initialized.
  *
  * \return          Type name on success, or "invalid PK"
  */
@@ -552,9 +573,10 @@
 /**
  * \brief           Get the key type
  *
- * \param ctx       Context to use
+ * \param ctx       The PK context to use. It must have been initialized.
  *
- * \return          Type on success, or MBEDTLS_PK_NONE
+ * \return          Type on success.
+ * \return          #MBEDTLS_PK_NONE for a context that has not been set up.
  */
 mbedtls_pk_type_t mbedtls_pk_get_type( const mbedtls_pk_context *ctx );
 
@@ -563,12 +585,22 @@
 /**
  * \brief           Parse a private key in PEM or DER format
  *
- * \param ctx       key to be initialized
- * \param key       input buffer
- * \param keylen    size of the buffer
- *                  (including the terminating null byte for PEM data)
- * \param pwd       password for decryption (optional)
- * \param pwdlen    size of the password
+ * \param ctx       The PK context to fill. It must have been initialized
+ *                  but not set up.
+ * \param key       Input buffer to parse.
+ *                  The buffer must contain the input exactly, with no
+ *                  extra trailing material. For PEM, the buffer must
+ *                  contain a null-terminated string.
+ * \param keylen    Size of \b key in bytes.
+ *                  For PEM data, this includes the terminating null byte,
+ *                  so \p keylen must be equal to `strlen(key) + 1`.
+ * \param pwd       Optional password for decryption.
+ *                  Pass \c NULL if expecting a non-encrypted key.
+ *                  Pass a string of \p pwdlen bytes if expecting an encrypted
+ *                  key; a non-encrypted key will also be accepted.
+ *                  The empty password is not supported.
+ * \param pwdlen    Size of the password in bytes.
+ *                  Ignored if \p pwd is \c NULL.
  *
  * \note            On entry, ctx must be empty, either freshly initialised
  *                  with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
@@ -586,10 +618,15 @@
 /**
  * \brief           Parse a public key in PEM or DER format
  *
- * \param ctx       key to be initialized
- * \param key       input buffer
- * \param keylen    size of the buffer
- *                  (including the terminating null byte for PEM data)
+ * \param ctx       The PK context to fill. It must have been initialized
+ *                  but not set up.
+ * \param key       Input buffer to parse.
+ *                  The buffer must contain the input exactly, with no
+ *                  extra trailing material. For PEM, the buffer must
+ *                  contain a null-terminated string.
+ * \param keylen    Size of \b key in bytes.
+ *                  For PEM data, this includes the terminating null byte,
+ *                  so \p keylen must be equal to `strlen(key) + 1`.
  *
  * \note            On entry, ctx must be empty, either freshly initialised
  *                  with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
@@ -607,9 +644,14 @@
 /**
  * \brief           Load and parse a private key
  *
- * \param ctx       key to be initialized
+ * \param ctx       The PK context to fill. It must have been initialized
+ *                  but not set up.
  * \param path      filename to read the private key from
- * \param password  password to decrypt the file (can be NULL)
+ * \param password  Optional password to decrypt the file.
+ *                  Pass \c NULL if expecting a non-encrypted key.
+ *                  Pass a null-terminated string if expecting an encrypted
+ *                  key; a non-encrypted key will also be accepted.
+ *                  The empty password is not supported.
  *
  * \note            On entry, ctx must be empty, either freshly initialised
  *                  with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
@@ -626,7 +668,8 @@
 /**
  * \brief           Load and parse a public key
  *
- * \param ctx       key to be initialized
+ * \param ctx       The PK context to fill. It must have been initialized
+ *                  but not set up.
  * \param path      filename to read the public key from
  *
  * \note            On entry, ctx must be empty, either freshly initialised
@@ -649,7 +692,7 @@
  *                        return value to determine where you should start
  *                        using the buffer
  *
- * \param ctx       private to write away
+ * \param ctx       PK context which must contain a valid private key.
  * \param buf       buffer to write to
  * \param size      size of the buffer
  *
@@ -664,7 +707,7 @@
  *                        return value to determine where you should start
  *                        using the buffer
  *
- * \param ctx       public key to write away
+ * \param ctx       PK context which must contain a valid public or private key.
  * \param buf       buffer to write to
  * \param size      size of the buffer
  *
@@ -677,9 +720,10 @@
 /**
  * \brief           Write a public key to a PEM string
  *
- * \param ctx       public key to write away
- * \param buf       buffer to write to
- * \param size      size of the buffer
+ * \param ctx       PK context which must contain a valid public or private key.
+ * \param buf       Buffer to write to. The output includes a
+ *                  terminating null byte.
+ * \param size      Size of the buffer in bytes.
  *
  * \return          0 if successful, or a specific error code
  */
@@ -688,9 +732,10 @@
 /**
  * \brief           Write a private key to a PKCS#1 or SEC1 PEM string
  *
- * \param ctx       private to write away
- * \param buf       buffer to write to
- * \param size      size of the buffer
+ * \param ctx       PK context which must contain a valid private key.
+ * \param buf       Buffer to write to. The output includes a
+ *                  terminating null byte.
+ * \param size      Size of the buffer in bytes.
  *
  * \return          0 if successful, or a specific error code
  */
@@ -709,7 +754,8 @@
  *
  * \param p         the position in the ASN.1 data
  * \param end       end of the buffer
- * \param pk        the key to fill
+ * \param pk        The PK context to fill. It must have been initialized
+ *                  but not set up.
  *
  * \return          0 if successful, or a specific PK error code
  */
@@ -724,7 +770,7 @@
  *
  * \param p         reference to current position pointer
  * \param start     start of the buffer (for bounds-checking)
- * \param key       public key to write away
+ * \param key       PK context which must contain a valid public or private key.
  *
  * \return          the length written or a negative error code
  */
@@ -761,7 +807,7 @@
  * \return          An Mbed TLS error code otherwise.
  */
 int mbedtls_pk_wrap_as_opaque( mbedtls_pk_context *pk,
-                               psa_key_slot_t *slot,
+                               psa_key_handle_t *slot,
                                psa_algorithm_t hash_alg );
 #endif /* MBEDTLS_USE_PSA_CRYPTO */
 
diff --git a/include/mbedtls/pkcs12.h b/include/mbedtls/pkcs12.h
index a621ef5..d441357 100644
--- a/include/mbedtls/pkcs12.h
+++ b/include/mbedtls/pkcs12.h
@@ -24,6 +24,12 @@
 #ifndef MBEDTLS_PKCS12_H
 #define MBEDTLS_PKCS12_H
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
 #include "md.h"
 #include "cipher.h"
 #include "asn1.h"
@@ -46,6 +52,8 @@
 extern "C" {
 #endif
 
+#if defined(MBEDTLS_ASN1_PARSE_C)
+
 /**
  * \brief            PKCS12 Password Based function (encryption / decryption)
  *                   for pbeWithSHAAnd128BitRC4
@@ -87,6 +95,8 @@
                 const unsigned char *input, size_t len,
                 unsigned char *output );
 
+#endif /* MBEDTLS_ASN1_PARSE_C */
+
 /**
  * \brief            The PKCS#12 derivation function uses a password and a salt
  *                   to produce pseudo-random bits for a particular "purpose".
diff --git a/include/mbedtls/pkcs5.h b/include/mbedtls/pkcs5.h
index 9a3c9fd..c92185f 100644
--- a/include/mbedtls/pkcs5.h
+++ b/include/mbedtls/pkcs5.h
@@ -26,6 +26,12 @@
 #ifndef MBEDTLS_PKCS5_H
 #define MBEDTLS_PKCS5_H
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
 #include "asn1.h"
 #include "md.h"
 
@@ -44,6 +50,8 @@
 extern "C" {
 #endif
 
+#if defined(MBEDTLS_ASN1_PARSE_C)
+
 /**
  * \brief          PKCS#5 PBES2 function
  *
@@ -62,6 +70,8 @@
                  const unsigned char *data, size_t datalen,
                  unsigned char *output );
 
+#endif /* MBEDTLS_ASN1_PARSE_C */
+
 /**
  * \brief          PKCS#5 PBKDF2 using HMAC
  *
@@ -81,6 +91,8 @@
                        unsigned int iteration_count,
                        uint32_t key_length, unsigned char *output );
 
+#if defined(MBEDTLS_SELF_TEST)
+
 /**
  * \brief          Checkup routine
  *
@@ -88,6 +100,8 @@
  */
 int mbedtls_pkcs5_self_test( int verbose );
 
+#endif /* MBEDTLS_SELF_TEST */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/mbedtls/platform.h b/include/mbedtls/platform.h
index 89fe8a7..801a948 100644
--- a/include/mbedtls/platform.h
+++ b/include/mbedtls/platform.h
@@ -58,17 +58,33 @@
  * \{
  */
 
+/* The older Microsoft Windows common runtime provides non-conforming
+ * implementations of some standard library functions, including snprintf
+ * and vsnprintf. This affects MSVC and MinGW builds.
+ */
+#if defined(__MINGW32__) || (defined(_MSC_VER) && _MSC_VER <= 1900)
+#define MBEDTLS_PLATFORM_HAS_NON_CONFORMING_SNPRINTF
+#define MBEDTLS_PLATFORM_HAS_NON_CONFORMING_VSNPRINTF
+#endif
+
 #if !defined(MBEDTLS_PLATFORM_NO_STD_FUNCTIONS)
 #include <stdio.h>
 #include <stdlib.h>
 #include <time.h>
 #if !defined(MBEDTLS_PLATFORM_STD_SNPRINTF)
-#if defined(_WIN32)
+#if defined(MBEDTLS_PLATFORM_HAS_NON_CONFORMING_SNPRINTF)
 #define MBEDTLS_PLATFORM_STD_SNPRINTF   mbedtls_platform_win32_snprintf /**< The default \c snprintf function to use.  */
 #else
 #define MBEDTLS_PLATFORM_STD_SNPRINTF   snprintf /**< The default \c snprintf function to use.  */
 #endif
 #endif
+#if !defined(MBEDTLS_PLATFORM_STD_VSNPRINTF)
+#if defined(MBEDTLS_PLATFORM_HAS_NON_CONFORMING_VSNPRINTF)
+#define MBEDTLS_PLATFORM_STD_VSNPRINTF   mbedtls_platform_win32_vsnprintf /**< The default \c vsnprintf function to use.  */
+#else
+#define MBEDTLS_PLATFORM_STD_VSNPRINTF   vsnprintf /**< The default \c vsnprintf function to use.  */
+#endif
+#endif
 #if !defined(MBEDTLS_PLATFORM_STD_PRINTF)
 #define MBEDTLS_PLATFORM_STD_PRINTF   printf /**< The default \c printf function to use. */
 #endif
@@ -204,7 +220,7 @@
  * - however it is acceptable to return -1 instead of the required length when
  *   the destination buffer is too short.
  */
-#if defined(_WIN32)
+#if defined(MBEDTLS_PLATFORM_HAS_NON_CONFORMING_SNPRINTF)
 /* For Windows (inc. MSYS2), we provide our own fixed implementation */
 int mbedtls_platform_win32_snprintf( char *s, size_t n, const char *fmt, ... );
 #endif
@@ -231,6 +247,41 @@
 #endif /* MBEDTLS_PLATFORM_SNPRINTF_ALT */
 
 /*
+ * The function pointers for vsnprintf
+ *
+ * The vsnprintf implementation should conform to C99:
+ * - it *must* always correctly zero-terminate the buffer
+ *   (except when n == 0, then it must leave the buffer untouched)
+ * - however it is acceptable to return -1 instead of the required length when
+ *   the destination buffer is too short.
+ */
+#if defined(MBEDTLS_PLATFORM_HAS_NON_CONFORMING_VSNPRINTF)
+/* For Older Windows (inc. MSYS2), we provide our own fixed implementation */
+int mbedtls_platform_win32_vsnprintf( char *s, size_t n, const char *fmt, va_list arg );
+#endif
+
+#if defined(MBEDTLS_PLATFORM_VSNPRINTF_ALT)
+#include <stdarg.h>
+extern int (*mbedtls_vsnprintf)( char * s, size_t n, const char * format, va_list arg );
+
+/**
+ * \brief   Set your own snprintf function pointer
+ *
+ * \param   vsnprintf_func   The \c vsnprintf function implementation
+ *
+ * \return  \c 0
+ */
+int mbedtls_platform_set_vsnprintf( int (*vsnprintf_func)( char * s, size_t n,
+                                                 const char * format, va_list arg ) );
+#else /* MBEDTLS_PLATFORM_VSNPRINTF_ALT */
+#if defined(MBEDTLS_PLATFORM_VSNPRINTF_MACRO)
+#define mbedtls_vsnprintf   MBEDTLS_PLATFORM_VSNPRINTF_MACRO
+#else
+#define mbedtls_vsnprintf   vsnprintf
+#endif /* MBEDTLS_PLATFORM_VSNPRINTF_MACRO */
+#endif /* MBEDTLS_PLATFORM_VSNPRINTF_ALT */
+
+/*
  * The function pointers for exit
  */
 #if defined(MBEDTLS_PLATFORM_EXIT_ALT)
diff --git a/include/mbedtls/platform_util.h b/include/mbedtls/platform_util.h
index 164a1a0..dba6d45 100644
--- a/include/mbedtls/platform_util.h
+++ b/include/mbedtls/platform_util.h
@@ -26,14 +26,14 @@
 #define MBEDTLS_PLATFORM_UTIL_H
 
 #if !defined(MBEDTLS_CONFIG_FILE)
-#include "mbedtls/config.h"
+#include "config.h"
 #else
 #include MBEDTLS_CONFIG_FILE
 #endif
 
 #include <stddef.h>
 #if defined(MBEDTLS_HAVE_TIME_DATE)
-#include "mbedtls/platform_time.h"
+#include "platform_time.h"
 #include <time.h>
 #endif /* MBEDTLS_HAVE_TIME_DATE */
 
@@ -41,6 +41,88 @@
 extern "C" {
 #endif
 
+#if defined(MBEDTLS_CHECK_PARAMS)
+
+#if defined(MBEDTLS_PARAM_FAILED)
+/** An alternative definition of MBEDTLS_PARAM_FAILED has been set in config.h.
+ *
+ * This flag can be used to check whether it is safe to assume that
+ * MBEDTLS_PARAM_FAILED() will expand to a call to mbedtls_param_failed().
+ */
+#define MBEDTLS_PARAM_FAILED_ALT
+#else /* MBEDTLS_PARAM_FAILED */
+#define MBEDTLS_PARAM_FAILED( cond ) \
+    mbedtls_param_failed( #cond, __FILE__, __LINE__ )
+
+/**
+ * \brief       User supplied callback function for parameter validation failure.
+ *              See #MBEDTLS_CHECK_PARAMS for context.
+ *
+ *              This function will be called unless an alternative treatement
+ *              is defined through the #MBEDTLS_PARAM_FAILED macro.
+ *
+ *              This function can return, and the operation will be aborted, or
+ *              alternatively, through use of setjmp()/longjmp() can resume
+ *              execution in the application code.
+ *
+ * \param failure_condition The assertion that didn't hold.
+ * \param file  The file where the assertion failed.
+ * \param line  The line in the file where the assertion failed.
+ */
+void mbedtls_param_failed( const char *failure_condition,
+                           const char *file,
+                           int line );
+#endif /* MBEDTLS_PARAM_FAILED */
+
+/* Internal macro meant to be called only from within the library. */
+#define MBEDTLS_INTERNAL_VALIDATE_RET( cond, ret )  \
+    do {                                            \
+        if( !(cond) )                               \
+        {                                           \
+            MBEDTLS_PARAM_FAILED( cond );           \
+            return( ret );                          \
+        }                                           \
+    } while( 0 )
+
+/* Internal macro meant to be called only from within the library. */
+#define MBEDTLS_INTERNAL_VALIDATE( cond )           \
+    do {                                            \
+        if( !(cond) )                               \
+        {                                           \
+            MBEDTLS_PARAM_FAILED( cond );           \
+            return;                                 \
+        }                                           \
+    } while( 0 )
+
+#else /* MBEDTLS_CHECK_PARAMS */
+
+/* Internal macros meant to be called only from within the library. */
+#define MBEDTLS_INTERNAL_VALIDATE_RET( cond, ret )  do { } while( 0 )
+#define MBEDTLS_INTERNAL_VALIDATE( cond )           do { } while( 0 )
+
+#endif /* MBEDTLS_CHECK_PARAMS */
+
+/* Internal helper macros for deprecating API constants. */
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+/* Deliberately don't (yet) export MBEDTLS_DEPRECATED here
+ * to avoid conflict with other headers which define and use
+ * it, too. We might want to move all these definitions here at
+ * some point for uniformity. */
+#define MBEDTLS_DEPRECATED __attribute__((deprecated))
+MBEDTLS_DEPRECATED typedef char const * mbedtls_deprecated_string_constant_t;
+#define MBEDTLS_DEPRECATED_STRING_CONSTANT( VAL )       \
+    ( (mbedtls_deprecated_string_constant_t) ( VAL ) )
+MBEDTLS_DEPRECATED typedef int mbedtls_deprecated_numeric_constant_t;
+#define MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( VAL )       \
+    ( (mbedtls_deprecated_numeric_constant_t) ( VAL ) )
+#undef MBEDTLS_DEPRECATED
+#else /* MBEDTLS_DEPRECATED_WARNING */
+#define MBEDTLS_DEPRECATED_STRING_CONSTANT( VAL ) VAL
+#define MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( VAL ) VAL
+#endif /* MBEDTLS_DEPRECATED_WARNING */
+#endif /* MBEDTLS_DEPRECATED_REMOVED */
+
 /**
  * \brief       Securely zeroize a buffer
  *
diff --git a/include/mbedtls/poly1305.h b/include/mbedtls/poly1305.h
index b02f968..f0ec44c 100644
--- a/include/mbedtls/poly1305.h
+++ b/include/mbedtls/poly1305.h
@@ -34,7 +34,7 @@
 #define MBEDTLS_POLY1305_H
 
 #if !defined(MBEDTLS_CONFIG_FILE)
-#include "mbedtls/config.h"
+#include "config.h"
 #else
 #include MBEDTLS_CONFIG_FILE
 #endif
@@ -84,14 +84,18 @@
  *                  \c mbedtls_poly1305_finish(), then finally
  *                  \c mbedtls_poly1305_free().
  *
- * \param ctx       The Poly1305 context to initialize.
+ * \param ctx       The Poly1305 context to initialize. This must
+ *                  not be \c NULL.
  */
 void mbedtls_poly1305_init( mbedtls_poly1305_context *ctx );
 
 /**
- * \brief           This function releases and clears the specified Poly1305 context.
+ * \brief           This function releases and clears the specified
+ *                  Poly1305 context.
  *
- * \param ctx       The Poly1305 context to clear.
+ * \param ctx       The Poly1305 context to clear. This may be \c NULL, in which
+ *                  case this function is a no-op. If it is not \c NULL, it must
+ *                  point to an initialized Poly1305 context.
  */
 void mbedtls_poly1305_free( mbedtls_poly1305_context *ctx );
 
@@ -102,11 +106,11 @@
  *                  invocation of Poly1305.
  *
  * \param ctx       The Poly1305 context to which the key should be bound.
- * \param key       The buffer containing the 256-bit key.
+ *                  This must be initialized.
+ * \param key       The buffer containing the \c 32 Byte (\c 256 Bit) key.
  *
  * \return          \c 0 on success.
- * \return          #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
- *                  if ctx or key are NULL.
+ * \return          A negative error code on failure.
  */
 int mbedtls_poly1305_starts( mbedtls_poly1305_context *ctx,
                              const unsigned char key[32] );
@@ -120,13 +124,14 @@
  *                  It can be called repeatedly to process a stream of data.
  *
  * \param ctx       The Poly1305 context to use for the Poly1305 operation.
- * \param ilen      The length of the input data (in bytes). Any value is accepted.
+ *                  This must be initialized and bound to a key.
+ * \param ilen      The length of the input data in Bytes.
+ *                  Any value is accepted.
  * \param input     The buffer holding the input data.
- *                  This pointer can be NULL if ilen == 0.
+ *                  This pointer can be \c NULL if `ilen == 0`.
  *
  * \return          \c 0 on success.
- * \return          #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
- *                  if ctx or input are NULL.
+ * \return          A negative error code on failure.
  */
 int mbedtls_poly1305_update( mbedtls_poly1305_context *ctx,
                              const unsigned char *input,
@@ -137,12 +142,12 @@
  *                  Authentication Code (MAC).
  *
  * \param ctx       The Poly1305 context to use for the Poly1305 operation.
- * \param mac       The buffer to where the MAC is written. Must be big enough
- *                  to hold the 16-byte MAC.
+ *                  This must be initialized and bound to a key.
+ * \param mac       The buffer to where the MAC is written. This must
+ *                  be a writable buffer of length \c 16 Bytes.
  *
  * \return          \c 0 on success.
- * \return          #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
- *                  if ctx or mac are NULL.
+ * \return          A negative error code on failure.
  */
 int mbedtls_poly1305_finish( mbedtls_poly1305_context *ctx,
                              unsigned char mac[16] );
@@ -154,16 +159,16 @@
  * \warning         The key must be unique and unpredictable for each
  *                  invocation of Poly1305.
  *
- * \param key       The buffer containing the 256-bit key.
- * \param ilen      The length of the input data (in bytes). Any value is accepted.
+ * \param key       The buffer containing the \c 32 Byte (\c 256 Bit) key.
+ * \param ilen      The length of the input data in Bytes.
+ *                  Any value is accepted.
  * \param input     The buffer holding the input data.
- *                  This pointer can be NULL if ilen == 0.
- * \param mac       The buffer to where the MAC is written. Must be big enough
- *                  to hold the 16-byte MAC.
+ *                  This pointer can be \c NULL if `ilen == 0`.
+ * \param mac       The buffer to where the MAC is written. This must be
+ *                  a writable buffer of length \c 16 Bytes.
  *
  * \return          \c 0 on success.
- * \return          #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
- *                  if key, input, or mac are NULL.
+ * \return          A negative error code on failure.
  */
 int mbedtls_poly1305_mac( const unsigned char key[32],
                           const unsigned char *input,
diff --git a/include/mbedtls/psa_util.h b/include/mbedtls/psa_util.h
index 5766133..b0c0428 100644
--- a/include/mbedtls/psa_util.h
+++ b/include/mbedtls/psa_util.h
@@ -41,21 +41,9 @@
 #include "ecp.h"
 #include "md.h"
 #include "pk.h"
+#include "oid.h"
 
-/* Slot allocation */
-
-static inline psa_status_t mbedtls_psa_get_free_key_slot( psa_key_slot_t *key )
-{
-    for( psa_key_slot_t slot = 1; slot <= 32; slot++ )
-    {
-        if( psa_get_key_information( slot, NULL, NULL ) == PSA_ERROR_EMPTY_SLOT )
-        {
-            *key = slot;
-            return( PSA_SUCCESS );
-        }
-    }
-    return( PSA_ERROR_INSUFFICIENT_MEMORY );
-}
+#include <string.h>
 
 /* Translations for symmetric crypto. */
 
@@ -105,6 +93,7 @@
             if( taglen == 0 )
                 return( PSA_ALG_CBC_NO_PADDING );
             /* Intentional fallthrough for taglen != 0 */
+            /* fallthrough */
         default:
             return( 0 );
     }
@@ -170,6 +159,162 @@
 
 /* Translations for ECC. */
 
+static inline int mbedtls_psa_get_ecc_oid_from_id(
+    psa_ecc_curve_t curve, char const **oid, size_t *oid_len )
+{
+    switch( curve )
+    {
+#if defined(MBEDTLS_ECP_DP_SECP192R1_ENABLED)
+        case PSA_ECC_CURVE_SECP192R1:
+            *oid = MBEDTLS_OID_EC_GRP_SECP192R1;
+            *oid_len = MBEDTLS_OID_SIZE( MBEDTLS_OID_EC_GRP_SECP192R1 );
+            return( 0 );
+#endif /* MBEDTLS_ECP_DP_SECP192R1_ENABLED */
+#if defined(MBEDTLS_ECP_DP_SECP224R1_ENABLED)
+        case PSA_ECC_CURVE_SECP224R1:
+            *oid = MBEDTLS_OID_EC_GRP_SECP224R1;
+            *oid_len = MBEDTLS_OID_SIZE( MBEDTLS_OID_EC_GRP_SECP224R1 );
+            return( 0 );
+#endif /* MBEDTLS_ECP_DP_SECP224R1_ENABLED */
+#if defined(MBEDTLS_ECP_DP_SECP256R1_ENABLED)
+        case PSA_ECC_CURVE_SECP256R1:
+            *oid = MBEDTLS_OID_EC_GRP_SECP256R1;
+            *oid_len = MBEDTLS_OID_SIZE( MBEDTLS_OID_EC_GRP_SECP256R1 );
+            return( 0 );
+#endif /* MBEDTLS_ECP_DP_SECP256R1_ENABLED */
+#if defined(MBEDTLS_ECP_DP_SECP384R1_ENABLED)
+        case PSA_ECC_CURVE_SECP384R1:
+            *oid = MBEDTLS_OID_EC_GRP_SECP384R1;
+            *oid_len = MBEDTLS_OID_SIZE( MBEDTLS_OID_EC_GRP_SECP384R1 );
+            return( 0 );
+#endif /* MBEDTLS_ECP_DP_SECP384R1_ENABLED */
+#if defined(MBEDTLS_ECP_DP_SECP521R1_ENABLED)
+        case PSA_ECC_CURVE_SECP521R1:
+            *oid = MBEDTLS_OID_EC_GRP_SECP521R1;
+            *oid_len = MBEDTLS_OID_SIZE( MBEDTLS_OID_EC_GRP_SECP521R1 );
+            return( 0 );
+#endif /* MBEDTLS_ECP_DP_SECP521R1_ENABLED */
+#if defined(MBEDTLS_ECP_DP_SECP192K1_ENABLED)
+        case PSA_ECC_CURVE_SECP192K1:
+            *oid = MBEDTLS_OID_EC_GRP_SECP192K1;
+            *oid_len = MBEDTLS_OID_SIZE( MBEDTLS_OID_EC_GRP_SECP192K1 );
+            return( 0 );
+#endif /* MBEDTLS_ECP_DP_SECP192K1_ENABLED */
+#if defined(MBEDTLS_ECP_DP_SECP224K1_ENABLED)
+        case PSA_ECC_CURVE_SECP224K1:
+            *oid = MBEDTLS_OID_EC_GRP_SECP224K1;
+            *oid_len = MBEDTLS_OID_SIZE( MBEDTLS_OID_EC_GRP_SECP224K1 );
+            return( 0 );
+#endif /* MBEDTLS_ECP_DP_SECP224K1_ENABLED */
+#if defined(MBEDTLS_ECP_DP_SECP256K1_ENABLED)
+        case PSA_ECC_CURVE_SECP256K1:
+            *oid = MBEDTLS_OID_EC_GRP_SECP256K1;
+            *oid_len = MBEDTLS_OID_SIZE( MBEDTLS_OID_EC_GRP_SECP256K1 );
+            return( 0 );
+#endif /* MBEDTLS_ECP_DP_SECP256K1_ENABLED */
+#if defined(MBEDTLS_ECP_DP_BP256R1_ENABLED)
+        case PSA_ECC_CURVE_BRAINPOOL_P256R1:
+            *oid = MBEDTLS_OID_EC_GRP_BP256R1;
+            *oid_len = MBEDTLS_OID_SIZE( MBEDTLS_OID_EC_GRP_BP256R1 );
+            return( 0 );
+#endif /* MBEDTLS_ECP_DP_BP256R1_ENABLED */
+#if defined(MBEDTLS_ECP_DP_BP384R1_ENABLED)
+        case PSA_ECC_CURVE_BRAINPOOL_P384R1:
+            *oid = MBEDTLS_OID_EC_GRP_BP384R1;
+            *oid_len = MBEDTLS_OID_SIZE( MBEDTLS_OID_EC_GRP_BP384R1 );
+            return( 0 );
+#endif /* MBEDTLS_ECP_DP_BP384R1_ENABLED */
+#if defined(MBEDTLS_ECP_DP_BP512R1_ENABLED)
+        case PSA_ECC_CURVE_BRAINPOOL_P512R1:
+            *oid = MBEDTLS_OID_EC_GRP_BP512R1;
+            *oid_len = MBEDTLS_OID_SIZE( MBEDTLS_OID_EC_GRP_BP512R1 );
+            return( 0 );
+#endif /* MBEDTLS_ECP_DP_BP512R1_ENABLED */
+    }
+
+     return( -1 );
+}
+
+#define MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH 1
+
+#if defined(MBEDTLS_ECP_DP_SECP192R1_ENABLED)
+#if MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH < ( 2 * ( ( 192 + 7 ) / 8 ) + 1 )
+#undef MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH
+#define MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH ( 2 * ( ( 192 + 7 ) / 8 ) + 1 )
+#endif
+#endif /* MBEDTLS_ECP_DP_SECP192R1_ENABLED */
+
+#if defined(MBEDTLS_ECP_DP_SECP224R1_ENABLED)
+#if MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH < ( 2 * ( ( 224 + 7 ) / 8 ) + 1 )
+#undef MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH
+#define MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH ( 2 * ( ( 224 + 7 ) / 8 ) + 1 )
+#endif
+#endif /* MBEDTLS_ECP_DP_SECP224R1_ENABLED */
+
+#if defined(MBEDTLS_ECP_DP_SECP256R1_ENABLED)
+#if MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH < ( 2 * ( ( 256 + 7 ) / 8 ) + 1 )
+#undef MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH
+#define MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH ( 2 * ( ( 256 + 7 ) / 8 ) + 1 )
+#endif
+#endif /* MBEDTLS_ECP_DP_SECP256R1_ENABLED */
+
+#if defined(MBEDTLS_ECP_DP_SECP384R1_ENABLED)
+#if MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH < ( 2 * ( ( 384 + 7 ) / 8 ) + 1 )
+#undef MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH
+#define MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH ( 2 * ( ( 384 + 7 ) / 8 ) + 1 )
+#endif
+#endif /* MBEDTLS_ECP_DP_SECP384R1_ENABLED */
+
+#if defined(MBEDTLS_ECP_DP_SECP521R1_ENABLED)
+#if MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH < ( 2 * ( ( 521 + 7 ) / 8 ) + 1 )
+#undef MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH
+#define MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH ( 2 * ( ( 521 + 7 ) / 8 ) + 1 )
+#endif
+#endif /* MBEDTLS_ECP_DP_SECP521R1_ENABLED */
+
+#if defined(MBEDTLS_ECP_DP_SECP192K1_ENABLED)
+#if MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH < ( 2 * ( ( 192 + 7 ) / 8 ) + 1 )
+#undef MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH
+#define MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH ( 2 * ( ( 192 + 7 ) / 8 ) + 1 )
+#endif
+#endif /* MBEDTLS_ECP_DP_SECP192K1_ENABLED */
+
+#if defined(MBEDTLS_ECP_DP_SECP224K1_ENABLED)
+#if MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH < ( 2 * ( ( 224 + 7 ) / 8 ) + 1 )
+#undef MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH
+#define MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH ( 2 * ( ( 224 + 7 ) / 8 ) + 1 )
+#endif
+#endif /* MBEDTLS_ECP_DP_SECP224K1_ENABLED */
+
+#if defined(MBEDTLS_ECP_DP_SECP256K1_ENABLED)
+#if MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH < ( 2 * ( ( 256 + 7 ) / 8 ) + 1 )
+#undef MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH
+#define MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH ( 2 * ( ( 256 + 7 ) / 8 ) + 1 )
+#endif
+#endif /* MBEDTLS_ECP_DP_SECP256K1_ENABLED */
+
+#if defined(MBEDTLS_ECP_DP_BP256R1_ENABLED)
+#if MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH < ( 2 * ( ( 256 + 7 ) / 8 ) + 1 )
+#undef MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH
+#define MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH ( 2 * ( ( 256 + 7 ) / 8 ) + 1 )
+#endif
+#endif /* MBEDTLS_ECP_DP_BP256R1_ENABLED */
+
+#if defined(MBEDTLS_ECP_DP_BP384R1_ENABLED)
+#if MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH < ( 2 * ( ( 384 + 7 ) / 8 ) + 1 )
+#undef MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH
+#define MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH ( 2 * ( ( 384 + 7 ) / 8 ) + 1 )
+#endif
+#endif /* MBEDTLS_ECP_DP_BP384R1_ENABLED */
+
+#if defined(MBEDTLS_ECP_DP_BP512R1_ENABLED)
+#if MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH < ( 2 * ( ( 512 + 7 ) / 8 ) + 1 )
+#undef MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH
+#define MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH ( 2 * ( ( 512 + 7 ) / 8 ) + 1 )
+#endif
+#endif /* MBEDTLS_ECP_DP_BP512R1_ENABLED */
+
+
 static inline psa_ecc_curve_t mbedtls_psa_translate_ecc_group( mbedtls_ecp_group_id grpid )
 {
     switch( grpid )
@@ -231,6 +376,24 @@
     }
 }
 
+
+#define MBEDTLS_PSA_ECC_KEY_BITS_OF_CURVE( curve )                \
+    ( curve == PSA_ECC_CURVE_SECP192R1        ? 192 :             \
+      curve == PSA_ECC_CURVE_SECP224R1        ? 224 :             \
+      curve == PSA_ECC_CURVE_SECP256R1        ? 256 :             \
+      curve == PSA_ECC_CURVE_SECP384R1        ? 384 :             \
+      curve == PSA_ECC_CURVE_SECP521R1        ? 521 :             \
+      curve == PSA_ECC_CURVE_SECP192K1        ? 192 :             \
+      curve == PSA_ECC_CURVE_SECP224K1        ? 224 :             \
+      curve == PSA_ECC_CURVE_SECP256K1        ? 256 :             \
+      curve == PSA_ECC_CURVE_BRAINPOOL_P256R1 ? 256 :             \
+      curve == PSA_ECC_CURVE_BRAINPOOL_P384R1 ? 384 :             \
+      curve == PSA_ECC_CURVE_BRAINPOOL_P512R1 ? 512 :             \
+      0 )
+
+#define MBEDTLS_PSA_ECC_KEY_BYTES_OF_CURVE( curve )                \
+    ( ( MBEDTLS_PSA_ECC_KEY_BITS_OF_CURVE( curve ) + 7 ) / 8 )
+
 /* Translations for PK layer */
 
 static inline int mbedtls_psa_err_translate_pk( psa_status_t status )
@@ -259,6 +422,61 @@
     }
 }
 
+/* Translations for ECC */
+
+/* This function transforms an ECC group identifier from
+ * https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8
+ * into a PSA ECC group identifier. */
+static inline psa_ecc_curve_t mbedtls_psa_parse_tls_ecc_group(
+    uint16_t tls_ecc_grp_reg_id )
+{
+    /* The PSA identifiers are currently aligned with those from
+     * the TLS Supported Groups registry, so no conversion is necessary. */
+    return( (psa_ecc_curve_t) tls_ecc_grp_reg_id );
+}
+
+/* This function takes a buffer holding an EC public key
+ * exported through psa_export_public_key(), and converts
+ * it into an ECPoint structure to be put into a ClientKeyExchange
+ * message in an ECDHE exchange.
+ *
+ * Both the present and the foreseeable future format of EC public keys
+ * used by PSA have the ECPoint structure contained in the exported key
+ * as a subbuffer, and the function merely selects this subbuffer instead
+ * of making a copy.
+ */
+static inline int mbedtls_psa_tls_psa_ec_to_ecpoint( unsigned char *src,
+                                                     size_t srclen,
+                                                     unsigned char **dst,
+                                                     size_t *dstlen )
+{
+    *dst = src;
+    *dstlen = srclen;
+    return( 0 );
+}
+
+/* This function takes a buffer holding an ECPoint structure
+ * (as contained in a TLS ServerKeyExchange message for ECDHE
+ * exchanges) and converts it into a format that the PSA key
+ * agreement API understands.
+ */
+static inline int mbedtls_psa_tls_ecpoint_to_psa_ec( psa_ecc_curve_t curve,
+                                                     unsigned char const *src,
+                                                     size_t srclen,
+                                                     unsigned char *dst,
+                                                     size_t dstlen,
+                                                     size_t *olen )
+{
+    ((void) curve);
+
+    if( srclen > dstlen )
+        return( MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL );
+
+    memcpy( dst, src, srclen );
+    *olen = srclen;
+    return( 0 );
+}
+
 #endif /* MBEDTLS_USE_PSA_CRYPTO */
 
 #endif /* MBEDTLS_PSA_UTIL_H */
diff --git a/include/mbedtls/ripemd160.h b/include/mbedtls/ripemd160.h
index c74b7d2..b42f6d2 100644
--- a/include/mbedtls/ripemd160.h
+++ b/include/mbedtls/ripemd160.h
@@ -219,6 +219,8 @@
 #undef MBEDTLS_DEPRECATED
 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
 
+#if defined(MBEDTLS_SELF_TEST)
+
 /**
  * \brief          Checkup routine
  *
@@ -226,6 +228,8 @@
  */
 int mbedtls_ripemd160_self_test( int verbose );
 
+#endif /* MBEDTLS_SELF_TEST */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/mbedtls/rsa.h b/include/mbedtls/rsa.h
index 406a317..489f2ed 100644
--- a/include/mbedtls/rsa.h
+++ b/include/mbedtls/rsa.h
@@ -150,23 +150,24 @@
  * \note           The choice of padding mode is strictly enforced for private key
  *                 operations, since there might be security concerns in
  *                 mixing padding modes. For public key operations it is
- *                 a default value, which can be overriden by calling specific
+ *                 a default value, which can be overridden by calling specific
  *                 \c rsa_rsaes_xxx or \c rsa_rsassa_xxx functions.
  *
  * \note           The hash selected in \p hash_id is always used for OEAP
  *                 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.
+ *                 making signatures, but can be overridden for verifying them.
+ *                 If set to #MBEDTLS_MD_NONE, it is always overridden.
  *
- * \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.
+ * \param ctx      The RSA context to initialize. This must not be \c NULL.
+ * \param padding  The padding mode to use. This must be either
+ *                 #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. It is unused
+ *                 otherwise.
  */
 void mbedtls_rsa_init( mbedtls_rsa_context *ctx,
                        int padding,
-                       int hash_id);
+                       int hash_id );
 
 /**
  * \brief          This function imports a set of core parameters into an
@@ -188,11 +189,11 @@
  *                 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 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.
+ * \param N        The RSA modulus. This may be \c NULL.
+ * \param P        The first prime factor of \p N. This may be \c NULL.
+ * \param Q        The second prime factor of \p N. This may be \c NULL.
+ * \param D        The private exponent. This may be \c NULL.
+ * \param E        The public exponent. This may be \c NULL.
  *
  * \return         \c 0 on success.
  * \return         A non-zero error code on failure.
@@ -222,16 +223,16 @@
  *                 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.
- * \param P        The first prime factor of \p N, or NULL.
- * \param P_len    The Byte length of \p P, ignored if \p P == NULL.
- * \param Q        The second prime factor of \p N, or NULL.
- * \param Q_len    The Byte length of \p Q, ignored if \p Q == NULL.
- * \param D        The private exponent, or NULL.
- * \param D_len    The Byte length of \p D, ignored if \p D == NULL.
- * \param E        The public exponent, or NULL.
- * \param E_len    The Byte length of \p E, ignored if \p E == NULL.
+ * \param N        The RSA modulus. This may be \c NULL.
+ * \param N_len    The Byte length of \p N; it is ignored if \p N == NULL.
+ * \param P        The first prime factor of \p N. This may be \c NULL.
+ * \param P_len    The Byte length of \p P; it ns ignored if \p P == NULL.
+ * \param Q        The second prime factor of \p N. This may be \c NULL.
+ * \param Q_len    The Byte length of \p Q; it is ignored if \p Q == NULL.
+ * \param D        The private exponent. This may be \c NULL.
+ * \param D_len    The Byte length of \p D; it is ignored if \p D == NULL.
+ * \param E        The public exponent. This may be \c NULL.
+ * \param E_len    The Byte length of \p E; it is ignored if \p E == NULL.
  *
  * \return         \c 0 on success.
  * \return         A non-zero error code on failure.
@@ -299,11 +300,16 @@
  *                 the RSA context stays intact and remains usable.
  *
  * \param ctx      The initialized RSA context.
- * \param N        The MPI to hold the RSA modulus, or NULL.
- * \param P        The MPI to hold the first prime factor of \p N, or NULL.
- * \param Q        The MPI to hold the second prime factor of \p N, or NULL.
- * \param D        The MPI to hold the private exponent, or NULL.
- * \param E        The MPI to hold the public exponent, or NULL.
+ * \param N        The MPI to hold the RSA modulus.
+ *                 This may be \c NULL if this field need not be exported.
+ * \param P        The MPI to hold the first prime factor of \p N.
+ *                 This may be \c NULL if this field need not be exported.
+ * \param Q        The MPI to hold the second prime factor of \p N.
+ *                 This may be \c NULL if this field need not be exported.
+ * \param D        The MPI to hold the private exponent.
+ *                 This may be \c NULL if this field need not be exported.
+ * \param E        The MPI to hold the public exponent.
+ *                 This may be \c NULL if this field need not be exported.
  *
  * \return         \c 0 on success.
  * \return         #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED if exporting the
@@ -341,17 +347,20 @@
  *                 buffer pointers are NULL.
  *
  * \param ctx      The initialized RSA context.
- * \param N        The Byte array to store the RSA modulus, or NULL.
+ * \param N        The Byte array to store the RSA modulus,
+ *                 or \c NULL if this field need not be exported.
  * \param N_len    The size of the buffer for the modulus.
- * \param P        The Byte array to hold the first prime factor of \p N, or
- *                 NULL.
+ * \param P        The Byte array to hold the first prime factor of \p N,
+ *                 or \c NULL if this field need not be exported.
  * \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.
+ * \param Q        The Byte array to hold the second prime factor of \p N,
+ *                 or \c NULL if this field need not be exported.
  * \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        The Byte array to hold the private exponent,
+ *                 or \c NULL if this field need not be exported.
  * \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        The Byte array to hold the public exponent,
+ *                 or \c NULL if this field need not be exported.
  * \param E_len    The size of the buffer for the public exponent.
  *
  * \return         \c 0 on success.
@@ -375,9 +384,12 @@
  *                 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.
+ * \param DP       The MPI to hold \c D modulo `P-1`,
+ *                 or \c NULL if it need not be exported.
+ * \param DQ       The MPI to hold \c D modulo `Q-1`,
+ *                 or \c NULL if it need not be exported.
+ * \param QP       The MPI to hold modular inverse of \c Q modulo \c P,
+ *                 or \c NULL if it need not be exported.
  *
  * \return         \c 0 on success.
  * \return         A non-zero error code on failure.
@@ -390,13 +402,13 @@
  * \brief          This function sets padding for an already initialized RSA
  *                 context. See mbedtls_rsa_init() for details.
  *
- * \param ctx      The RSA context to be set.
- * \param padding  Selects padding mode: #MBEDTLS_RSA_PKCS_V15 or
- *                 #MBEDTLS_RSA_PKCS_V21.
+ * \param ctx      The initialized RSA context to be configured.
+ * \param padding  The padding mode to use. This must be either
+ *                 #MBEDTLS_RSA_PKCS_V15 or #MBEDTLS_RSA_PKCS_V21.
  * \param hash_id  The #MBEDTLS_RSA_PKCS_V21 hash identifier.
  */
 void mbedtls_rsa_set_padding( mbedtls_rsa_context *ctx, int padding,
-                              int hash_id);
+                              int hash_id );
 
 /**
  * \brief          This function retrieves the length of RSA modulus in Bytes.
@@ -414,11 +426,14 @@
  * \note           mbedtls_rsa_init() must be called before this function,
  *                 to set up the RSA context.
  *
- * \param ctx      The RSA context used to hold the key.
- * \param f_rng    The RNG function.
- * \param p_rng    The RNG context.
+ * \param ctx      The initialized RSA context used to hold the key.
+ * \param f_rng    The RNG function to be used for key generation.
+ *                 This must not be \c NULL.
+ * \param p_rng    The RNG context to be passed to \p f_rng.
+ *                 This may be \c NULL if \p f_rng doesn't need a context.
  * \param nbits    The size of the public key in bits.
- * \param exponent The public exponent. For example, 65537.
+ * \param exponent The public exponent to use. For example, \c 65537.
+ *                 This must be odd and greater than \c 1.
  *
  * \return         \c 0 on success.
  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -436,7 +451,7 @@
  *                 enough information is present to perform an RSA public key
  *                 operation using mbedtls_rsa_public().
  *
- * \param ctx      The RSA context to check.
+ * \param ctx      The initialized RSA context to check.
  *
  * \return         \c 0 on success.
  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -475,7 +490,7 @@
  *             parameters, which goes beyond what is effectively checkable
  *             by the library.</li></ul>
  *
- * \param ctx  The RSA context to check.
+ * \param ctx  The initialized RSA context to check.
  *
  * \return     \c 0 on success.
  * \return     An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -487,8 +502,8 @@
  *
  *                 It checks each of the contexts, and makes sure they match.
  *
- * \param pub      The RSA context holding the public key.
- * \param prv      The RSA context holding the private key.
+ * \param pub      The initialized RSA context holding the public key.
+ * \param prv      The initialized RSA context holding the private key.
  *
  * \return         \c 0 on success.
  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -499,18 +514,19 @@
 /**
  * \brief          This function performs an RSA public key operation.
  *
+ * \param ctx      The initialized RSA context to use.
+ * \param input    The input buffer. This must be a readable buffer
+ *                 of length \c ctx->len Bytes. For example, \c 256 Bytes
+ *                 for an 2048-bit RSA modulus.
+ * \param output   The output buffer. This must be a writable buffer
+ *                 of length \c ctx->len Bytes. For example, \c 256 Bytes
+ *                 for an 2048-bit RSA modulus.
+ *
  * \note           This function does not handle message padding.
  *
  * \note           Make sure to set \p input[0] = 0 or ensure that
  *                 input is smaller than \p N.
  *
- * \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.
  */
@@ -521,9 +537,6 @@
 /**
  * \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
@@ -535,11 +548,18 @@
  *                 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 context.
- * \param input    The input buffer.
- * \param output   The output buffer.
+ * \param ctx      The initialized RSA context to use.
+ * \param f_rng    The RNG function, used for blinding. It is discouraged
+ *                 and deprecated to pass \c NULL here, in which case
+ *                 blinding will be omitted.
+ * \param p_rng    The RNG context to pass to \p f_rng. This may be \c NULL
+ *                 if \p f_rng is \c NULL or if \p f_rng doesn't need a context.
+ * \param input    The input buffer. This must be a readable buffer
+ *                 of length \c ctx->len Bytes. For example, \c 256 Bytes
+ *                 for an 2048-bit RSA modulus.
+ * \param output   The output buffer. This must be a writable buffer
+ *                 of length \c ctx->len Bytes. For example, \c 256 Bytes
+ *                 for an 2048-bit RSA modulus.
  *
  * \return         \c 0 on success.
  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -558,9 +578,6 @@
  *                 It is the generic wrapper for performing a PKCS#1 encryption
  *                 operation using the \p mode from the context.
  *
- * \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
  *                 are likely to remove the \p mode argument and have it
@@ -570,14 +587,25 @@
  *                 mode being set to #MBEDTLS_RSA_PRIVATE and might instead
  *                 return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
  *
- * \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.
+ * \param ctx      The initialized RSA context to use.
+ * \param f_rng    The RNG to use. It is mandatory for PKCS#1 v2.1 padding
+ *                 encoding, and for PKCS#1 v1.5 padding encoding when used
+ *                 with \p mode set to #MBEDTLS_RSA_PUBLIC. For PKCS#1 v1.5
+ *                 padding encoding and \p mode set to #MBEDTLS_RSA_PRIVATE,
+ *                 it is used for blinding and should be provided in this
+ *                 case; see mbedtls_rsa_private() for more.
+ * \param p_rng    The RNG context to be passed to \p f_rng. May be
+ *                 \c NULL if \p f_rng is \c NULL or if \p f_rng doesn't
+ *                 need a context argument.
+ * \param mode     The mode of operation. This must be either
+ *                 #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).
+ * \param ilen     The length of the plaintext in Bytes.
+ * \param input    The input data to encrypt. This must be a readable
+ *                 buffer of size \p ilen Bytes. It may be \c NULL if
+ *                 `ilen == 0`.
+ * \param output   The output buffer. This must be a writable buffer
+ *                 of length \c ctx->len Bytes. For example, \c 256 Bytes
+ *                 for an 2048-bit RSA modulus.
  *
  * \return         \c 0 on success.
  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -593,9 +621,6 @@
  * \brief          This function performs a PKCS#1 v1.5 encryption operation
  *                 (RSAES-PKCS1-v1_5-ENCRYPT).
  *
- * \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
  *                 are likely to remove the \p mode argument and have it
@@ -605,14 +630,23 @@
  *                 mode being set to #MBEDTLS_RSA_PRIVATE and might instead
  *                 return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
  *
- * \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.
+ * \param ctx      The initialized RSA context to use.
+ * \param f_rng    The RNG function to use. It is needed for padding generation
+ *                 if \p mode is #MBEDTLS_RSA_PUBLIC. If \p mode is
+ *                 #MBEDTLS_RSA_PRIVATE (discouraged), it is used for
+ *                 blinding and should be provided; see mbedtls_rsa_private().
+ * \param p_rng    The RNG context to be passed to \p f_rng. This may
+ *                 be \c NULL if \p f_rng is \c NULL or if \p f_rng
+ *                 doesn't need a context argument.
+ * \param mode     The mode of operation. This must be either
+ *                 #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).
+ * \param ilen     The length of the plaintext in Bytes.
+ * \param input    The input data to encrypt. This must be a readable
+ *                 buffer of size \p ilen Bytes. It may be \c NULL if
+ *                 `ilen == 0`.
+ * \param output   The output buffer. This must be a writable buffer
+ *                 of length \c ctx->len Bytes. For example, \c 256 Bytes
+ *                 for an 2048-bit RSA modulus.
  *
  * \return         \c 0 on success.
  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -640,16 +674,24 @@
  *                   mode being set to #MBEDTLS_RSA_PRIVATE and might instead
  *                   return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
  *
- * \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 context.
- * \param mode       #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param ctx        The initnialized RSA context to use.
+ * \param f_rng      The RNG function to use. This is needed for padding
+ *                   generation and must be provided.
+ * \param p_rng      The RNG context to be passed to \p f_rng. This may
+ *                   be \c NULL if \p f_rng doesn't need a context argument.
+ * \param mode       The mode of operation. This must be either
+ *                   #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).
  * \param label      The buffer holding the custom label to use.
- * \param label_len  The length of the label.
- * \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.
+ *                   This must be a readable buffer of length \p label_len
+ *                   Bytes. It may be \c NULL if \p label_len is \c 0.
+ * \param label_len  The length of the label in Bytes.
+ * \param ilen       The length of the plaintext buffer \p input in Bytes.
+ * \param input      The input data to encrypt. This must be a readable
+ *                   buffer of size \p ilen Bytes. It may be \c NULL if
+ *                   `ilen == 0`.
+ * \param output     The output buffer. This must be a writable buffer
+ *                   of length \c ctx->len Bytes. For example, \c 256 Bytes
+ *                   for an 2048-bit RSA modulus.
  *
  * \return           \c 0 on success.
  * \return           An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -677,9 +719,6 @@
  *                 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
  *                 are likely to remove the \p mode argument and have it
@@ -689,14 +728,23 @@
  *                 mode being set to #MBEDTLS_RSA_PUBLIC and might instead
  *                 return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
  *
- * \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.
+ * \param ctx      The initialized RSA context to use.
+ * \param f_rng    The RNG function. If \p mode is #MBEDTLS_RSA_PRIVATE,
+ *                 this is used for blinding and should be provided; see
+ *                 mbedtls_rsa_private() for more. If \p mode is
+ *                 #MBEDTLS_RSA_PUBLIC, it is ignored.
+ * \param p_rng    The RNG context to be passed to \p f_rng. This may be
+ *                 \c NULL if \p f_rng is \c NULL or doesn't need a context.
+ * \param mode     The mode of operation. This must be either
+ *                 #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).
+ * \param olen     The address at which to store the length of
+ *                 the plaintext. This must not be \c NULL.
+ * \param input    The ciphertext buffer. This must be a readable buffer
+ *                 of length \c ctx->len Bytes. For example, \c 256 Bytes
+ *                 for an 2048-bit RSA modulus.
+ * \param output   The buffer used to hold the plaintext. This must
+ *                 be a writable buffer of length \p output_max_len Bytes.
+ * \param output_max_len The length in Bytes of the output buffer \p output.
  *
  * \return         \c 0 on success.
  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -720,9 +768,6 @@
  *                 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
@@ -732,14 +777,23 @@
  *                 mode being set to #MBEDTLS_RSA_PUBLIC and might instead
  *                 return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
  *
- * \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.
+ * \param ctx      The initialized RSA context to use.
+ * \param f_rng    The RNG function. If \p mode is #MBEDTLS_RSA_PRIVATE,
+ *                 this is used for blinding and should be provided; see
+ *                 mbedtls_rsa_private() for more. If \p mode is
+ *                 #MBEDTLS_RSA_PUBLIC, it is ignored.
+ * \param p_rng    The RNG context to be passed to \p f_rng. This may be
+ *                 \c NULL if \p f_rng is \c NULL or doesn't need a context.
+ * \param mode     The mode of operation. This must be either
+ *                 #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).
+ * \param olen     The address at which to store the length of
+ *                 the plaintext. This must not be \c NULL.
+ * \param input    The ciphertext buffer. This must be a readable buffer
+ *                 of length \c ctx->len Bytes. For example, \c 256 Bytes
+ *                 for an 2048-bit RSA modulus.
+ * \param output   The buffer used to hold the plaintext. This must
+ *                 be a writable buffer of length \p output_max_len Bytes.
+ * \param output_max_len The length in Bytes of the output buffer \p output.
  *
  * \return         \c 0 on success.
  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -765,9 +819,6 @@
  *                   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
@@ -777,16 +828,27 @@
  *                   mode being set to #MBEDTLS_RSA_PUBLIC and might instead
  *                   return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
  *
- * \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 ctx        The initialized RSA context to use.
+ * \param f_rng      The RNG function. If \p mode is #MBEDTLS_RSA_PRIVATE,
+ *                   this is used for blinding and should be provided; see
+ *                   mbedtls_rsa_private() for more. If \p mode is
+ *                   #MBEDTLS_RSA_PUBLIC, it is ignored.
+ * \param p_rng      The RNG context to be passed to \p f_rng. This may be
+ *                   \c NULL if \p f_rng is \c NULL or doesn't need a context.
+ * \param mode       The mode of operation. This must be either
+ *                   #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).
  * \param label      The buffer holding the custom label to use.
- * \param label_len  The length of the label.
- * \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.
+ *                   This must be a readable buffer of length \p label_len
+ *                   Bytes. It may be \c NULL if \p label_len is \c 0.
+ * \param label_len  The length of the label in Bytes.
+ * \param olen       The address at which to store the length of
+ *                   the plaintext. This must not be \c NULL.
+ * \param input      The ciphertext buffer. This must be a readable buffer
+ *                   of length \c ctx->len Bytes. For example, \c 256 Bytes
+ *                   for an 2048-bit RSA modulus.
+ * \param output     The buffer used to hold the plaintext. This must
+ *                   be a writable buffer of length \p output_max_len Bytes.
+ * \param output_max_len The length in Bytes of the output buffer \p output.
  *
  * \return         \c 0 on success.
  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -824,16 +886,28 @@
  *                 mode being set to #MBEDTLS_RSA_PUBLIC and might instead
  *                 return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
  *
- * \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 ctx      The initialized RSA context to use.
+ * \param f_rng    The RNG function to use. If the padding mode is PKCS#1 v2.1,
+ *                 this must be provided. If the padding mode is PKCS#1 v1.5 and
+ *                 \p mode is #MBEDTLS_RSA_PRIVATE, it is used for blinding
+ *                 and should be provided; see mbedtls_rsa_private() for more
+ *                 more. It is ignored otherwise.
+ * \param p_rng    The RNG context to be passed to \p f_rng. This may be \c NULL
+ *                 if \p f_rng is \c NULL or doesn't need a context argument.
+ * \param mode     The mode of operation. This must be either
+ *                 #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).
  * \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.
+ * \param hashlen  The length of the message digest.
+ *                 Ths is only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash     The buffer holding the message digest or raw data.
+ *                 If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable
+ *                 buffer of length \p hashlen Bytes. If \p md_alg is not
+ *                 #MBEDTLS_MD_NONE, it must be a readable buffer of length
+ *                 the size of the hash corresponding to \p md_alg.
+ * \param sig      The buffer to hold the signature. This must be a writable
+ *                 buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
+ *                 for an 2048-bit RSA modulus.
  *
  * \return         \c 0 if the signing operation was successful.
  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -851,9 +925,6 @@
  * \brief          This function performs a PKCS#1 v1.5 signature
  *                 operation (RSASSA-PKCS1-v1_5-SIGN).
  *
- * \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
  *                 are likely to remove the \p mode argument and have it
@@ -863,15 +934,27 @@
  *                 mode being set to #MBEDTLS_RSA_PUBLIC and might instead
  *                 return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
  *
- * \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 ctx      The initialized RSA context to use.
+ * \param f_rng    The RNG function. If \p mode is #MBEDTLS_RSA_PRIVATE,
+ *                 this is used for blinding and should be provided; see
+ *                 mbedtls_rsa_private() for more. If \p mode is
+ *                 #MBEDTLS_RSA_PUBLIC, it is ignored.
+ * \param p_rng    The RNG context to be passed to \p f_rng. This may be \c NULL
+ *                 if \p f_rng is \c NULL or doesn't need a context argument.
+ * \param mode     The mode of operation. This must be either
+ *                 #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).
  * \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.
+ * \param hashlen  The length of the message digest.
+ *                 Ths is only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash     The buffer holding the message digest or raw data.
+ *                 If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable
+ *                 buffer of length \p hashlen Bytes. If \p md_alg is not
+ *                 #MBEDTLS_MD_NONE, it must be a readable buffer of length
+ *                 the size of the hash corresponding to \p md_alg.
+ * \param sig      The buffer to hold the signature. This must be a writable
+ *                 buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
+ *                 for an 2048-bit RSA modulus.
  *
  * \return         \c 0 if the signing operation was successful.
  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -889,9 +972,6 @@
  * \brief          This function performs a PKCS#1 v2.1 PSS signature
  *                 operation (RSASSA-PSS-SIGN).
  *
- * \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
@@ -918,16 +998,24 @@
  *                 mode being set to #MBEDTLS_RSA_PUBLIC and might instead
  *                 return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
  *
- * \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 ctx      The initialized RSA context to use.
+ * \param f_rng    The RNG function. It must not be \c NULL.
+ * \param p_rng    The RNG context to be passed to \p f_rng. This may be \c NULL
+ *                 if \p f_rng doesn't need a context argument.
+ * \param mode     The mode of operation. This must be either
+ *                 #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).
  * \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.
+ * \param hashlen  The length of the message digest.
+ *                 Ths is only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash     The buffer holding the message digest or raw data.
+ *                 If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable
+ *                 buffer of length \p hashlen Bytes. If \p md_alg is not
+ *                 #MBEDTLS_MD_NONE, it must be a readable buffer of length
+ *                 the size of the hash corresponding to \p md_alg.
+ * \param sig      The buffer to hold the signature. This must be a writable
+ *                 buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
+ *                 for an 2048-bit RSA modulus.
  *
  * \return         \c 0 if the signing operation was successful.
  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -948,9 +1036,6 @@
  *                 This is the generic wrapper for performing a PKCS#1
  *                 verification using the mode from the context.
  *
- * \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.
@@ -964,15 +1049,26 @@
  *                 mode being set to #MBEDTLS_RSA_PRIVATE and might instead
  *                 return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
  *
- * \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 ctx      The initialized RSA public key context to use.
+ * \param f_rng    The RNG function to use. If \p mode is #MBEDTLS_RSA_PRIVATE,
+ *                 this is used for blinding and should be provided; see
+ *                 mbedtls_rsa_private() for more. Otherwise, it is ignored.
+ * \param p_rng    The RNG context to be passed to \p f_rng. This may be
+ *                 \c NULL if \p f_rng is \c NULL or doesn't need a context.
+ * \param mode     The mode of operation. This must be either
+ *                 #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).
  * \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.
+ * \param hashlen  The length of the message digest.
+ *                 This is only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash     The buffer holding the message digest or raw data.
+ *                 If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable
+ *                 buffer of length \p hashlen Bytes. If \p md_alg is not
+ *                 #MBEDTLS_MD_NONE, it must be a readable buffer of length
+ *                 the size of the hash corresponding to \p md_alg.
+ * \param sig      The buffer holding the signature. This must be a readable
+ *                 buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
+ *                 for an 2048-bit RSA modulus.
  *
  * \return         \c 0 if the verify operation was successful.
  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -990,9 +1086,6 @@
  * \brief          This function performs a PKCS#1 v1.5 verification
  *                 operation (RSASSA-PKCS1-v1_5-VERIFY).
  *
- * \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
  *                 are likely to remove the \p mode argument and have it
@@ -1002,15 +1095,26 @@
  *                 mode being set to #MBEDTLS_RSA_PRIVATE and might instead
  *                 return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
  *
- * \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 ctx      The initialized RSA public key context to use.
+ * \param f_rng    The RNG function to use. If \p mode is #MBEDTLS_RSA_PRIVATE,
+ *                 this is used for blinding and should be provided; see
+ *                 mbedtls_rsa_private() for more. Otherwise, it is ignored.
+ * \param p_rng    The RNG context to be passed to \p f_rng. This may be
+ *                 \c NULL if \p f_rng is \c NULL or doesn't need a context.
+ * \param mode     The mode of operation. This must be either
+ *                 #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).
  * \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.
+ * \param hashlen  The length of the message digest.
+ *                 This is only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash     The buffer holding the message digest or raw data.
+ *                 If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable
+ *                 buffer of length \p hashlen Bytes. If \p md_alg is not
+ *                 #MBEDTLS_MD_NONE, it must be a readable buffer of length
+ *                 the size of the hash corresponding to \p md_alg.
+ * \param sig      The buffer holding the signature. This must be a readable
+ *                 buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
+ *                 for an 2048-bit RSA modulus.
  *
  * \return         \c 0 if the verify operation was successful.
  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -1031,9 +1135,6 @@
  *                 The hash function for the MGF mask generating function
  *                 is that specified in the RSA context.
  *
- * \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
  *                 verification. \p md_alg in the function call is the type of
  *                 hash that is verified. According to <em>RFC-3447: Public-Key
@@ -1051,15 +1152,26 @@
  *                 mode being set to #MBEDTLS_RSA_PRIVATE and might instead
  *                 return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
  *
- * \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 ctx      The initialized RSA public key context to use.
+ * \param f_rng    The RNG function to use. If \p mode is #MBEDTLS_RSA_PRIVATE,
+ *                 this is used for blinding and should be provided; see
+ *                 mbedtls_rsa_private() for more. Otherwise, it is ignored.
+ * \param p_rng    The RNG context to be passed to \p f_rng. This may be
+ *                 \c NULL if \p f_rng is \c NULL or doesn't need a context.
+ * \param mode     The mode of operation. This must be either
+ *                 #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).
  * \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.
+ * \param hashlen  The length of the message digest.
+ *                 This is only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash     The buffer holding the message digest or raw data.
+ *                 If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable
+ *                 buffer of length \p hashlen Bytes. If \p md_alg is not
+ *                 #MBEDTLS_MD_NONE, it must be a readable buffer of length
+ *                 the size of the hash corresponding to \p md_alg.
+ * \param sig      The buffer holding the signature. This must be a readable
+ *                 buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
+ *                 for an 2048-bit RSA modulus.
  *
  * \return         \c 0 if the verify operation was successful.
  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -1085,19 +1197,29 @@
  *
  * \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 ctx      The initialized RSA public key context to use.
+ * \param f_rng    The RNG function to use. If \p mode is #MBEDTLS_RSA_PRIVATE,
+ *                 this is used for blinding and should be provided; see
+ *                 mbedtls_rsa_private() for more. Otherwise, it is ignored.
+ * \param p_rng    The RNG context to be passed to \p f_rng. This may be
+ *                 \c NULL if \p f_rng is \c NULL or doesn't need a context.
+ * \param mode     The mode of operation. This must be either
+ *                 #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.
+ * \param hashlen  The length of the message digest.
+ *                 This is only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash     The buffer holding the message digest or raw data.
+ *                 If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable
+ *                 buffer of length \p hashlen Bytes. If \p md_alg is not
+ *                 #MBEDTLS_MD_NONE, it must be a readable buffer of length
+ *                 the size of the hash corresponding to \p md_alg.
+ * \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 signature. This must be a readable
+ *                 buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
+ *                 for an 2048-bit RSA modulus.
  *
  * \return         \c 0 if the verify operation was successful.
  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
@@ -1116,8 +1238,8 @@
 /**
  * \brief          This function copies the components of an RSA context.
  *
- * \param dst      The destination context.
- * \param src      The source context.
+ * \param dst      The destination context. This must be initialized.
+ * \param src      The source context. This must be initialized.
  *
  * \return         \c 0 on success.
  * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure.
@@ -1127,10 +1249,14 @@
 /**
  * \brief          This function frees the components of an RSA key.
  *
- * \param ctx      The RSA Context to free.
+ * \param ctx      The RSA context to free. May be \c NULL, in which case
+ *                 this function is a no-op. If it is not \c NULL, it must
+ *                 point to an initialized RSA context.
  */
 void mbedtls_rsa_free( mbedtls_rsa_context *ctx );
 
+#if defined(MBEDTLS_SELF_TEST)
+
 /**
  * \brief          The RSA checkup routine.
  *
@@ -1139,6 +1265,8 @@
  */
 int mbedtls_rsa_self_test( int verbose );
 
+#endif /* MBEDTLS_SELF_TEST */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/mbedtls/sha1.h b/include/mbedtls/sha1.h
index bcaeab5..bb6ecf0 100644
--- a/include/mbedtls/sha1.h
+++ b/include/mbedtls/sha1.h
@@ -42,6 +42,7 @@
 
 /* MBEDTLS_ERR_SHA1_HW_ACCEL_FAILED is deprecated and should not be used. */
 #define MBEDTLS_ERR_SHA1_HW_ACCEL_FAILED                  -0x0035  /**< SHA-1 hardware accelerator failed */
+#define MBEDTLS_ERR_SHA1_BAD_INPUT_DATA                   -0x0073  /**< SHA-1 input data was malformed. */
 
 #ifdef __cplusplus
 extern "C" {
@@ -79,6 +80,7 @@
  *                 stronger message digests instead.
  *
  * \param ctx      The SHA-1 context to initialize.
+ *                 This must not be \c NULL.
  *
  */
 void mbedtls_sha1_init( mbedtls_sha1_context *ctx );
@@ -90,7 +92,10 @@
  *                 constitutes a security risk. We recommend considering
  *                 stronger message digests instead.
  *
- * \param ctx      The SHA-1 context to clear.
+ * \param ctx      The SHA-1 context to clear. This may be \c NULL,
+ *                 in which case this function does nothing. If it is
+ *                 not \c NULL, it must point to an initialized
+ *                 SHA-1 context.
  *
  */
 void mbedtls_sha1_free( mbedtls_sha1_context *ctx );
@@ -102,8 +107,8 @@
  *                 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.
+ * \param dst      The SHA-1 context to clone to. This must be initialized.
+ * \param src      The SHA-1 context to clone from. This must be initialized.
  *
  */
 void mbedtls_sha1_clone( mbedtls_sha1_context *dst,
@@ -116,9 +121,10 @@
  *                 constitutes a security risk. We recommend considering
  *                 stronger message digests instead.
  *
- * \param ctx      The SHA-1 context to initialize.
+ * \param ctx      The SHA-1 context to initialize. This must be initialized.
  *
  * \return         \c 0 on success.
+ * \return         A negative error code on failure.
  *
  */
 int mbedtls_sha1_starts_ret( mbedtls_sha1_context *ctx );
@@ -131,11 +137,14 @@
  *                 constitutes a security risk. We recommend considering
  *                 stronger message digests instead.
  *
- * \param ctx      The SHA-1 context.
+ * \param ctx      The SHA-1 context. This must be initialized
+ *                 and have a hash operation started.
  * \param input    The buffer holding the input data.
- * \param ilen     The length of the input data.
+ *                 This must be a readable buffer of length \p ilen Bytes.
+ * \param ilen     The length of the input data \p input in Bytes.
  *
  * \return         \c 0 on success.
+ * \return         A negative error code on failure.
  */
 int mbedtls_sha1_update_ret( mbedtls_sha1_context *ctx,
                              const unsigned char *input,
@@ -149,10 +158,13 @@
  *                 constitutes a security risk. We recommend considering
  *                 stronger message digests instead.
  *
- * \param ctx      The SHA-1 context.
- * \param output   The SHA-1 checksum result.
+ * \param ctx      The SHA-1 context to use. This must be initialized and
+ *                 have a hash operation started.
+ * \param output   The SHA-1 checksum result. This must be a writable
+ *                 buffer of length \c 20 Bytes.
  *
  * \return         \c 0 on success.
+ * \return         A negative error code on failure.
  */
 int mbedtls_sha1_finish_ret( mbedtls_sha1_context *ctx,
                              unsigned char output[20] );
@@ -164,10 +176,12 @@
  *                 constitutes a security risk. We recommend considering
  *                 stronger message digests instead.
  *
- * \param ctx      The SHA-1 context.
- * \param data     The data block being processed.
+ * \param ctx      The SHA-1 context to use. This must be initialized.
+ * \param data     The data block being processed. This must be a
+ *                 readable buffer of length \c 64 Bytes.
  *
  * \return         \c 0 on success.
+ * \return         A negative error code on failure.
  *
  */
 int mbedtls_internal_sha1_process( mbedtls_sha1_context *ctx,
@@ -188,7 +202,7 @@
  *
  * \deprecated     Superseded by mbedtls_sha1_starts_ret() in 2.7.0.
  *
- * \param ctx      The SHA-1 context to initialize.
+ * \param ctx      The SHA-1 context to initialize. This must be initialized.
  *
  */
 MBEDTLS_DEPRECATED void mbedtls_sha1_starts( mbedtls_sha1_context *ctx );
@@ -203,9 +217,11 @@
  *
  * \deprecated     Superseded by mbedtls_sha1_update_ret() in 2.7.0.
  *
- * \param ctx      The SHA-1 context.
+ * \param ctx      The SHA-1 context. This must be initialized and
+ *                 have a hash operation started.
  * \param input    The buffer holding the input data.
- * \param ilen     The length of the input data.
+ *                 This must be a readable buffer of length \p ilen Bytes.
+ * \param ilen     The length of the input data \p input in Bytes.
  *
  */
 MBEDTLS_DEPRECATED void mbedtls_sha1_update( mbedtls_sha1_context *ctx,
@@ -222,9 +238,10 @@
  *
  * \deprecated     Superseded by mbedtls_sha1_finish_ret() in 2.7.0.
  *
- * \param ctx      The SHA-1 context.
+ * \param ctx      The SHA-1 context. This must be initialized and
+ *                 have a hash operation started.
  * \param output   The SHA-1 checksum result.
- *
+ *                 This must be a writable buffer of length \c 20 Bytes.
  */
 MBEDTLS_DEPRECATED void mbedtls_sha1_finish( mbedtls_sha1_context *ctx,
                                              unsigned char output[20] );
@@ -238,8 +255,9 @@
  *
  * \deprecated     Superseded by mbedtls_internal_sha1_process() in 2.7.0.
  *
- * \param ctx      The SHA-1 context.
+ * \param ctx      The SHA-1 context. This must be initialized.
  * \param data     The data block being processed.
+ *                 This must be a readable buffer of length \c 64 bytes.
  *
  */
 MBEDTLS_DEPRECATED void mbedtls_sha1_process( mbedtls_sha1_context *ctx,
@@ -262,10 +280,13 @@
  *                 stronger message digests instead.
  *
  * \param input    The buffer holding the input data.
- * \param ilen     The length of the input data.
+ *                 This must be a readable buffer of length \p ilen Bytes.
+ * \param ilen     The length of the input data \p input in Bytes.
  * \param output   The SHA-1 checksum result.
+ *                 This must be a writable buffer of length \c 20 Bytes.
  *
  * \return         \c 0 on success.
+ * \return         A negative error code on failure.
  *
  */
 int mbedtls_sha1_ret( const unsigned char *input,
@@ -294,8 +315,10 @@
  * \deprecated     Superseded by mbedtls_sha1_ret() in 2.7.0
  *
  * \param input    The buffer holding the input data.
- * \param ilen     The length of the input data.
- * \param output   The SHA-1 checksum result.
+ *                 This must be a readable buffer of length \p ilen Bytes.
+ * \param ilen     The length of the input data \p input in Bytes.
+ * \param output   The SHA-1 checksum result. This must be a writable
+ *                 buffer of size \c 20 Bytes.
  *
  */
 MBEDTLS_DEPRECATED void mbedtls_sha1( const unsigned char *input,
@@ -305,6 +328,8 @@
 #undef MBEDTLS_DEPRECATED
 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
 
+#if defined(MBEDTLS_SELF_TEST)
+
 /**
  * \brief          The SHA-1 checkup routine.
  *
@@ -318,6 +343,8 @@
  */
 int mbedtls_sha1_self_test( int verbose );
 
+#endif /* MBEDTLS_SELF_TEST */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/mbedtls/sha256.h b/include/mbedtls/sha256.h
index 47a31e8..d647398 100644
--- a/include/mbedtls/sha256.h
+++ b/include/mbedtls/sha256.h
@@ -38,6 +38,7 @@
 
 /* MBEDTLS_ERR_SHA256_HW_ACCEL_FAILED is deprecated and should not be used. */
 #define MBEDTLS_ERR_SHA256_HW_ACCEL_FAILED                -0x0037  /**< SHA-256 hardware accelerator failed */
+#define MBEDTLS_ERR_SHA256_BAD_INPUT_DATA                 -0x0074  /**< SHA-256 input data was malformed. */
 
 #ifdef __cplusplus
 extern "C" {
@@ -71,22 +72,24 @@
 /**
  * \brief          This function initializes a SHA-256 context.
  *
- * \param ctx      The SHA-256 context to initialize.
+ * \param ctx      The SHA-256 context to initialize. This must not be \c NULL.
  */
 void mbedtls_sha256_init( mbedtls_sha256_context *ctx );
 
 /**
  * \brief          This function clears a SHA-256 context.
  *
- * \param ctx      The SHA-256 context to clear.
+ * \param ctx      The SHA-256 context to clear. This may be \c NULL, in which
+ *                 case this function returns immediately. If it is not \c NULL,
+ *                 it must point to an initialized SHA-256 context.
  */
 void mbedtls_sha256_free( mbedtls_sha256_context *ctx );
 
 /**
  * \brief          This function clones the state of a SHA-256 context.
  *
- * \param dst      The destination context.
- * \param src      The context to clone.
+ * \param dst      The destination context. This must be initialized.
+ * \param src      The context to clone. This must be initialized.
  */
 void mbedtls_sha256_clone( mbedtls_sha256_context *dst,
                            const mbedtls_sha256_context *src );
@@ -95,11 +98,12 @@
  * \brief          This function starts a SHA-224 or SHA-256 checksum
  *                 calculation.
  *
- * \param ctx      The context to initialize.
- * \param is224    Determines which function to use:
- *                 0: Use SHA-256, or 1: Use SHA-224.
+ * \param ctx      The context to use. This must be initialized.
+ * \param is224    This determines which function to use. This must be
+ *                 either \c 0 for SHA-256, or \c 1 for SHA-224.
  *
  * \return         \c 0 on success.
+ * \return         A negative error code on failure.
  */
 int mbedtls_sha256_starts_ret( mbedtls_sha256_context *ctx, int is224 );
 
@@ -107,11 +111,14 @@
  * \brief          This function feeds an input buffer into an ongoing
  *                 SHA-256 checksum calculation.
  *
- * \param ctx      The SHA-256 context.
- * \param input    The buffer holding the data.
- * \param ilen     The length of the input data.
+ * \param ctx      The SHA-256 context. This must be initialized
+ *                 and have a hash operation started.
+ * \param input    The buffer holding the data. This must be a readable
+ *                 buffer of length \p ilen Bytes.
+ * \param ilen     The length of the input data in Bytes.
  *
  * \return         \c 0 on success.
+ * \return         A negative error code on failure.
  */
 int mbedtls_sha256_update_ret( mbedtls_sha256_context *ctx,
                                const unsigned char *input,
@@ -121,10 +128,13 @@
  * \brief          This function finishes the SHA-256 operation, and writes
  *                 the result to the output buffer.
  *
- * \param ctx      The SHA-256 context.
+ * \param ctx      The SHA-256 context. This must be initialized
+ *                 and have a hash operation started.
  * \param output   The SHA-224 or SHA-256 checksum result.
+ *                 This must be a writable buffer of length \c 32 Bytes.
  *
  * \return         \c 0 on success.
+ * \return         A negative error code on failure.
  */
 int mbedtls_sha256_finish_ret( mbedtls_sha256_context *ctx,
                                unsigned char output[32] );
@@ -134,10 +144,12 @@
  *                 the ongoing SHA-256 computation. This function is for
  *                 internal use only.
  *
- * \param ctx      The SHA-256 context.
- * \param data     The buffer holding one block of data.
+ * \param ctx      The SHA-256 context. This must be initialized.
+ * \param data     The buffer holding one block of data. This must
+ *                 be a readable buffer of length \c 64 Bytes.
  *
  * \return         \c 0 on success.
+ * \return         A negative error code on failure.
  */
 int mbedtls_internal_sha256_process( mbedtls_sha256_context *ctx,
                                      const unsigned char data[64] );
@@ -152,12 +164,11 @@
  * \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 context to initialize.
- * \param is224    Determines which function to use:
- *                 0: Use SHA-256, or 1: Use SHA-224.
+ * \param ctx      The context to use. This must be initialized.
+ * \param is224    Determines which function to use. This must be
+ *                 either \c 0 for SHA-256, or \c 1 for SHA-224.
  */
 MBEDTLS_DEPRECATED void mbedtls_sha256_starts( mbedtls_sha256_context *ctx,
                                                int is224 );
@@ -168,9 +179,11 @@
  *
  * \deprecated     Superseded by mbedtls_sha256_update_ret() in 2.7.0.
  *
- * \param ctx      The SHA-256 context to initialize.
- * \param input    The buffer holding the data.
- * \param ilen     The length of the input data.
+ * \param ctx      The SHA-256 context to use. This must be
+ *                 initialized and have a hash operation started.
+ * \param input    The buffer holding the data. This must be a readable
+ *                 buffer of length \p ilen Bytes.
+ * \param ilen     The length of the input data in Bytes.
  */
 MBEDTLS_DEPRECATED void mbedtls_sha256_update( mbedtls_sha256_context *ctx,
                                                const unsigned char *input,
@@ -182,8 +195,10 @@
  *
  * \deprecated     Superseded by mbedtls_sha256_finish_ret() in 2.7.0.
  *
- * \param ctx      The SHA-256 context.
- * \param output   The SHA-224 or SHA-256 checksum result.
+ * \param ctx      The SHA-256 context. This must be initialized and
+ *                 have a hash operation started.
+ * \param output   The SHA-224 or SHA-256 checksum result. This must be
+ *                 a writable buffer of length \c 32 Bytes.
  */
 MBEDTLS_DEPRECATED void mbedtls_sha256_finish( mbedtls_sha256_context *ctx,
                                                unsigned char output[32] );
@@ -195,8 +210,9 @@
  *
  * \deprecated     Superseded by mbedtls_internal_sha256_process() in 2.7.0.
  *
- * \param ctx      The SHA-256 context.
- * \param data     The buffer holding one block of data.
+ * \param ctx      The SHA-256 context. This must be initialized.
+ * \param data     The buffer holding one block of data. This must be
+ *                 a readable buffer of size \c 64 Bytes.
  */
 MBEDTLS_DEPRECATED void mbedtls_sha256_process( mbedtls_sha256_context *ctx,
                                                 const unsigned char data[64] );
@@ -214,11 +230,13 @@
  *                 The SHA-256 result is calculated as
  *                 output = SHA-256(input buffer).
  *
- * \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:
- *                 0: Use SHA-256, or 1: Use SHA-224.
+ * \param input    The buffer holding the data. This must be a readable
+ *                 buffer of length \p ilen Bytes.
+ * \param ilen     The length of the input data in Bytes.
+ * \param output   The SHA-224 or SHA-256 checksum result. This must
+ *                 be a writable buffer of length \c 32 Bytes.
+ * \param is224    Determines which function to use. This must be
+ *                 either \c 0 for SHA-256, or \c 1 for SHA-224.
  */
 int mbedtls_sha256_ret( const unsigned char *input,
                         size_t ilen,
@@ -244,11 +262,13 @@
  *
  * \deprecated     Superseded by mbedtls_sha256_ret() in 2.7.0.
  *
- * \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:
- *                 0: Use SHA-256, or 1: Use SHA-224.
+ * \param input    The buffer holding the data. This must be a readable
+ *                 buffer of length \p ilen Bytes.
+ * \param ilen     The length of the input data in Bytes.
+ * \param output   The SHA-224 or SHA-256 checksum result. This must be
+ *                 a writable buffer of length \c 32 Bytes.
+ * \param is224    Determines which function to use. This must be either
+ *                 \c 0 for SHA-256, or \c 1 for SHA-224.
  */
 MBEDTLS_DEPRECATED void mbedtls_sha256( const unsigned char *input,
                                         size_t ilen,
@@ -258,6 +278,8 @@
 #undef MBEDTLS_DEPRECATED
 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
 
+#if defined(MBEDTLS_SELF_TEST)
+
 /**
  * \brief          The SHA-224 and SHA-256 checkup routine.
  *
@@ -266,6 +288,8 @@
  */
 int mbedtls_sha256_self_test( int verbose );
 
+#endif /* MBEDTLS_SELF_TEST */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/mbedtls/sha512.h b/include/mbedtls/sha512.h
index 020f95d..c06ceed 100644
--- a/include/mbedtls/sha512.h
+++ b/include/mbedtls/sha512.h
@@ -37,6 +37,7 @@
 
 /* MBEDTLS_ERR_SHA512_HW_ACCEL_FAILED is deprecated and should not be used. */
 #define MBEDTLS_ERR_SHA512_HW_ACCEL_FAILED                -0x0039  /**< SHA-512 hardware accelerator failed */
+#define MBEDTLS_ERR_SHA512_BAD_INPUT_DATA                 -0x0075  /**< SHA-512 input data was malformed. */
 
 #ifdef __cplusplus
 extern "C" {
@@ -70,22 +71,26 @@
 /**
  * \brief          This function initializes a SHA-512 context.
  *
- * \param ctx      The SHA-512 context to initialize.
+ * \param ctx      The SHA-512 context to initialize. This must
+ *                 not be \c NULL.
  */
 void mbedtls_sha512_init( mbedtls_sha512_context *ctx );
 
 /**
  * \brief          This function clears a SHA-512 context.
  *
- * \param ctx      The SHA-512 context to clear.
+ * \param ctx      The SHA-512 context to clear. This may be \c NULL,
+ *                 in which case this function does nothing. If it
+ *                 is not \c NULL, it must point to an initialized
+ *                 SHA-512 context.
  */
 void mbedtls_sha512_free( mbedtls_sha512_context *ctx );
 
 /**
  * \brief          This function clones the state of a SHA-512 context.
  *
- * \param dst      The destination context.
- * \param src      The context to clone.
+ * \param dst      The destination context. This must be initialized.
+ * \param src      The context to clone. This must be initialized.
  */
 void mbedtls_sha512_clone( mbedtls_sha512_context *dst,
                            const mbedtls_sha512_context *src );
@@ -94,11 +99,12 @@
  * \brief          This function starts a SHA-384 or SHA-512 checksum
  *                 calculation.
  *
- * \param ctx      The SHA-512 context to initialize.
- * \param is384    Determines which function to use:
- *                 0: Use SHA-512, or 1: Use SHA-384.
+ * \param ctx      The SHA-512 context to use. This must be initialized.
+ * \param is384    Determines which function to use. This must be
+ *                 either \c for SHA-512, or \c 1 for SHA-384.
  *
  * \return         \c 0 on success.
+ * \return         A negative error code on failure.
  */
 int mbedtls_sha512_starts_ret( mbedtls_sha512_context *ctx, int is384 );
 
@@ -106,11 +112,14 @@
  * \brief          This function feeds an input buffer into an ongoing
  *                 SHA-512 checksum calculation.
  *
- * \param ctx      The SHA-512 context.
- * \param input    The buffer holding the input data.
- * \param ilen     The length of the input data.
+ * \param ctx      The SHA-512 context. This must be initialized
+ *                 and have a hash operation started.
+ * \param input    The buffer holding the input data. This must
+ *                 be a readable buffer of length \p ilen Bytes.
+ * \param ilen     The length of the input data in Bytes.
  *
  * \return         \c 0 on success.
+ * \return         A negative error code on failure.
  */
 int mbedtls_sha512_update_ret( mbedtls_sha512_context *ctx,
                     const unsigned char *input,
@@ -121,10 +130,13 @@
  *                 the result to the output buffer. This function is for
  *                 internal use only.
  *
- * \param ctx      The SHA-512 context.
+ * \param ctx      The SHA-512 context. This must be initialized
+ *                 and have a hash operation started.
  * \param output   The SHA-384 or SHA-512 checksum result.
+ *                 This must be a writable buffer of length \c 64 Bytes.
  *
  * \return         \c 0 on success.
+ * \return         A negative error code on failure.
  */
 int mbedtls_sha512_finish_ret( mbedtls_sha512_context *ctx,
                                unsigned char output[64] );
@@ -133,10 +145,12 @@
  * \brief          This function processes a single data block within
  *                 the ongoing SHA-512 computation.
  *
- * \param ctx      The SHA-512 context.
- * \param data     The buffer holding one block of data.
+ * \param ctx      The SHA-512 context. This must be initialized.
+ * \param data     The buffer holding one block of data. This
+ *                 must be a readable buffer of length \c 128 Bytes.
  *
  * \return         \c 0 on success.
+ * \return         A negative error code on failure.
  */
 int mbedtls_internal_sha512_process( mbedtls_sha512_context *ctx,
                                      const unsigned char data[128] );
@@ -152,9 +166,9 @@
  *
  * \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:
- *                 0: Use SHA-512, or 1: Use SHA-384.
+ * \param ctx      The SHA-512 context to use. This must be initialized.
+ * \param is384    Determines which function to use. This must be either
+ *                 \c 0 for SHA-512 or \c 1 for SHA-384.
  */
 MBEDTLS_DEPRECATED void mbedtls_sha512_starts( mbedtls_sha512_context *ctx,
                                                int is384 );
@@ -165,9 +179,11 @@
  *
  * \deprecated     Superseded by mbedtls_sha512_update_ret() in 2.7.0.
  *
- * \param ctx      The SHA-512 context.
- * \param input    The buffer holding the data.
- * \param ilen     The length of the input data.
+ * \param ctx      The SHA-512 context. This must be initialized
+ *                 and have a hash operation started.
+ * \param input    The buffer holding the data. This must be a readable
+ *                 buffer of length \p ilen Bytes.
+ * \param ilen     The length of the input data in Bytes.
  */
 MBEDTLS_DEPRECATED void mbedtls_sha512_update( mbedtls_sha512_context *ctx,
                                                const unsigned char *input,
@@ -179,8 +195,10 @@
  *
  * \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.
+ * \param ctx      The SHA-512 context. This must be initialized
+ *                 and have a hash operation started.
+ * \param output   The SHA-384 or SHA-512 checksum result. This must
+ *                 be a writable buffer of size \c 64 Bytes.
  */
 MBEDTLS_DEPRECATED void mbedtls_sha512_finish( mbedtls_sha512_context *ctx,
                                                unsigned char output[64] );
@@ -192,8 +210,9 @@
  *
  * \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.
+ * \param ctx      The SHA-512 context. This must be initialized.
+ * \param data     The buffer holding one block of data. This must be
+ *                 a readable buffer of length \c 128 Bytes.
  */
 MBEDTLS_DEPRECATED void mbedtls_sha512_process(
                                             mbedtls_sha512_context *ctx,
@@ -212,13 +231,16 @@
  *                 The SHA-512 result is calculated as
  *                 output = SHA-512(input buffer).
  *
- * \param input    The buffer holding the input data.
- * \param ilen     The length of the input data.
+ * \param input    The buffer holding the input data. This must be
+ *                 a readable buffer of length \p ilen Bytes.
+ * \param ilen     The length of the input data in Bytes.
  * \param output   The SHA-384 or SHA-512 checksum result.
- * \param is384    Determines which function to use:
- *                 0: Use SHA-512, or 1: Use SHA-384.
+ *                 This must be a writable buffer of length \c 64 Bytes.
+ * \param is384    Determines which function to use. This must be either
+ *                 \c 0 for SHA-512, or \c 1 for SHA-384.
  *
  * \return         \c 0 on success.
+ * \return         A negative error code on failure.
  */
 int mbedtls_sha512_ret( const unsigned char *input,
                         size_t ilen,
@@ -231,6 +253,7 @@
 #else
 #define MBEDTLS_DEPRECATED
 #endif
+
 /**
  * \brief          This function calculates the SHA-512 or SHA-384
  *                 checksum of a buffer.
@@ -243,11 +266,13 @@
  *
  * \deprecated     Superseded by mbedtls_sha512_ret() in 2.7.0
  *
- * \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:
- *                 0: Use SHA-512, or 1: Use SHA-384.
+ * \param input    The buffer holding the data. This must be a
+ *                 readable buffer of length \p ilen Bytes.
+ * \param ilen     The length of the input data in Bytes.
+ * \param output   The SHA-384 or SHA-512 checksum result. This must
+ *                 be a writable buffer of length \c 64 Bytes.
+ * \param is384    Determines which function to use. This must be either
+ *                 \c 0 for SHA-512, or \c 1 for SHA-384.
  */
 MBEDTLS_DEPRECATED void mbedtls_sha512( const unsigned char *input,
                                         size_t ilen,
@@ -256,6 +281,9 @@
 
 #undef MBEDTLS_DEPRECATED
 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
+
+#if defined(MBEDTLS_SELF_TEST)
+
  /**
  * \brief          The SHA-384 or SHA-512 checkup routine.
  *
@@ -263,6 +291,7 @@
  * \return         \c 1 on failure.
  */
 int mbedtls_sha512_self_test( int verbose );
+#endif /* MBEDTLS_SELF_TEST */
 
 #ifdef __cplusplus
 }
diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index f7c9d93..b793ac0 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -787,6 +787,25 @@
 typedef void mbedtls_ssl_async_cancel_t( mbedtls_ssl_context *ssl );
 #endif /* MBEDTLS_SSL_ASYNC_PRIVATE */
 
+#if defined(MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED) &&        \
+    !defined(MBEDTLS_SSL_KEEP_PEER_CERTIFICATE)
+#define MBEDTLS_SSL_PEER_CERT_DIGEST_MAX_LEN  48
+#if defined(MBEDTLS_SHA256_C)
+#define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_TYPE MBEDTLS_MD_SHA256
+#define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_LEN  32
+#elif defined(MBEDTLS_SHA512_C)
+#define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_TYPE MBEDTLS_MD_SHA384
+#define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_LEN  48
+#elif defined(MBEDTLS_SHA1_C)
+#define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_TYPE MBEDTLS_MD_SHA1
+#define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_LEN  20
+#else
+/* This is already checked in check_config.h, but be sure. */
+#error "Bad configuration - need SHA-1, SHA-256 or SHA-512 enabled to compute digest of peer CRT."
+#endif
+#endif /* MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED &&
+          !MBEDTLS_SSL_KEEP_PEER_CERTIFICATE */
+
 /*
  * This structure is used for storing current session data.
  */
@@ -802,7 +821,15 @@
     unsigned char master[48];   /*!< the master secret  */
 
 #if defined(MBEDTLS_X509_CRT_PARSE_C)
-    mbedtls_x509_crt *peer_cert;        /*!< peer X.509 cert chain */
+#if defined(MBEDTLS_SSL_KEEP_PEER_CERTIFICATE)
+    mbedtls_x509_crt *peer_cert;       /*!< peer X.509 cert chain */
+#else /* MBEDTLS_SSL_KEEP_PEER_CERTIFICATE */
+    /*! The digest of the peer's end-CRT. This must be kept to detect CRT
+     *  changes during renegotiation, mitigating the triple handshake attack. */
+    unsigned char *peer_cert_digest;
+    size_t peer_cert_digest_len;
+    mbedtls_md_type_t peer_cert_digest_type;
+#endif /* !MBEDTLS_SSL_KEEP_PEER_CERTIFICATE */
 #endif /* MBEDTLS_X509_CRT_PARSE_C */
     uint32_t verify_result;          /*!<  verification result     */
 
@@ -929,11 +956,11 @@
 #if defined(MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED)
 
 #if defined(MBEDTLS_USE_PSA_CRYPTO)
-    psa_key_slot_t psk_opaque; /*!< PSA key slot holding opaque PSK.
-                                *   This field should only be set via
-                                *   mbedtls_ssl_conf_psk_opaque().
-                                *   If either no PSK or a raw PSK have
-                                *   been configured, this has value \c 0. */
+    psa_key_handle_t psk_opaque; /*!< PSA key slot holding opaque PSK.
+                                  *   This field should only be set via
+                                  *   mbedtls_ssl_conf_psk_opaque().
+                                  *   If either no PSK or a raw PSK have
+                                  *   been configured, this has value \c 0. */
 #endif /* MBEDTLS_USE_PSA_CRYPTO */
 
     unsigned char *psk;      /*!< The raw pre-shared key. This field should
@@ -2055,7 +2082,7 @@
  *                 provision more than one cert/key pair (eg one ECDSA, one
  *                 RSA with SHA-256, one RSA with SHA-1). An adequate
  *                 certificate will be selected according to the client's
- *                 advertised capabilities. In case mutliple certificates are
+ *                 advertised capabilities. In case multiple certificates are
  *                 adequate, preference is given to the one set by the first
  *                 call to this function, then second, etc.
  *
@@ -2066,6 +2093,14 @@
  *                 whether it matches those preferences - the server can then
  *                 decide what it wants to do with it.
  *
+ * \note           The provided \p pk_key needs to match the public key in the
+ *                 first certificate in \p own_cert, or all handshakes using
+ *                 that certificate will fail. It is your responsibility
+ *                 to ensure that; this function will not perform any check.
+ *                 You may use mbedtls_pk_check_pair() in order to perform
+ *                 this check yourself, but be aware that this function can
+ *                 be computationally expensive on some key types.
+ *
  * \param conf     SSL configuration
  * \param own_cert own public certificate chain
  * \param pk_key   own private key
@@ -2129,7 +2164,7 @@
  * \param psk      The identifier of the key slot holding the PSK.
  *                 Until \p conf is destroyed or this function is successfully
  *                 called again, the key slot \p psk must be populated with a
- *                 key of type #PSA_ALG_CATEGORY_KEY_DERIVATION whose policy
+ *                 key of type PSA_ALG_CATEGORY_KEY_DERIVATION whose policy
  *                 allows its use for the key derivation algorithm applied
  *                 in the handshake.
  * \param psk_identity      The pointer to the pre-shared key identity.
@@ -2144,7 +2179,7 @@
  * \return         An \c MBEDTLS_ERR_SSL_XXX error code on failure.
  */
 int mbedtls_ssl_conf_psk_opaque( mbedtls_ssl_config *conf,
-                                 psa_key_slot_t psk,
+                                 psa_key_handle_t psk,
                                  const unsigned char *psk_identity,
                                  size_t psk_identity_len );
 #endif /* MBEDTLS_USE_PSA_CRYPTO */
@@ -2176,7 +2211,7 @@
  * \param psk      The identifier of the key slot holding the PSK.
  *                 For the duration of the current handshake, the key slot
  *                 must be populated with a key of type
- *                 #PSA_ALG_CATEGORY_KEY_DERIVATION whose policy allows its
+ *                 PSA_ALG_CATEGORY_KEY_DERIVATION whose policy allows its
  *                 use for the key derivation algorithm
  *                 applied in the handshake.
   *
@@ -2184,7 +2219,7 @@
  * \return         An \c MBEDTLS_ERR_SSL_XXX error code on failure.
  */
 int mbedtls_ssl_set_hs_psk_opaque( mbedtls_ssl_context *ssl,
-                                   psa_key_slot_t psk );
+                                   psa_key_handle_t psk );
 #endif /* MBEDTLS_USE_PSA_CRYPTO */
 
 /**
@@ -2964,18 +2999,34 @@
 
 #if defined(MBEDTLS_X509_CRT_PARSE_C)
 /**
- * \brief          Return the peer certificate from the current connection
+ * \brief          Return the peer certificate from the current connection.
  *
- *                 Note: Can be NULL in case no certificate was sent during
- *                 the handshake. Different calls for the same connection can
- *                 return the same or different pointers for the same
- *                 certificate and even a different certificate altogether.
- *                 The peer cert CAN change in a single connection if
- *                 renegotiation is performed.
+ * \param  ssl     The SSL context to use. This must be initialized and setup.
  *
- * \param ssl      SSL context
+ * \return         The current peer certificate, if available.
+ *                 The returned certificate is owned by the SSL context and
+ *                 is valid only until the next call to the SSL API.
+ * \return         \c NULL if no peer certificate is available. This might
+ *                 be because the chosen ciphersuite doesn't use CRTs
+ *                 (PSK-based ciphersuites, for example), or because
+ *                 #MBEDTLS_SSL_KEEP_PEER_CERTIFICATE has been disabled,
+ *                 allowing the stack to free the peer's CRT to save memory.
  *
- * \return         the current peer certificate
+ * \note           For one-time inspection of the peer's certificate during
+ *                 the handshake, consider registering an X.509 CRT verification
+ *                 callback through mbedtls_ssl_conf_verify() instead of calling
+ *                 this function. Using mbedtls_ssl_conf_verify() also comes at
+ *                 the benefit of allowing you to influence the verification
+ *                 process, for example by masking expected and tolerated
+ *                 verification failures.
+ *
+ * \warning        You must not use the pointer returned by this function
+ *                 after any further call to the SSL API, including
+ *                 mbedtls_ssl_read() and mbedtls_ssl_write(); this is
+ *                 because the pointer might change during renegotiation,
+ *                 which happens transparently to the user.
+ *                 If you want to use the certificate across API calls,
+ *                 you must make a copy.
  */
 const mbedtls_x509_crt *mbedtls_ssl_get_peer_cert( const mbedtls_ssl_context *ssl );
 #endif /* MBEDTLS_X509_CRT_PARSE_C */
@@ -3292,7 +3343,7 @@
  *                 mbedtls_ssl_config_defaults() or mbedtls_ssl_config_free().
  *
  * \note           You need to call mbedtls_ssl_config_defaults() unless you
- *                 manually set all of the relevent fields yourself.
+ *                 manually set all of the relevant fields yourself.
  *
  * \param conf     SSL configuration context
  */
diff --git a/include/mbedtls/ssl_cache.h b/include/mbedtls/ssl_cache.h
index ec081e6..84254d3 100644
--- a/include/mbedtls/ssl_cache.h
+++ b/include/mbedtls/ssl_cache.h
@@ -24,6 +24,12 @@
 #ifndef MBEDTLS_SSL_CACHE_H
 #define MBEDTLS_SSL_CACHE_H
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
 #include "ssl.h"
 
 #if defined(MBEDTLS_THREADING_C)
@@ -64,7 +70,8 @@
     mbedtls_time_t timestamp;           /*!< entry timestamp    */
 #endif
     mbedtls_ssl_session session;        /*!< entry session      */
-#if defined(MBEDTLS_X509_CRT_PARSE_C)
+#if defined(MBEDTLS_X509_CRT_PARSE_C) && \
+    defined(MBEDTLS_SSL_KEEP_PEER_CERTIFICATE)
     mbedtls_x509_buf peer_cert;         /*!< entry peer_cert    */
 #endif
     mbedtls_ssl_cache_entry *next;      /*!< chain pointer      */
diff --git a/include/mbedtls/ssl_ciphersuites.h b/include/mbedtls/ssl_ciphersuites.h
index cda8b48..7126783 100644
--- a/include/mbedtls/ssl_ciphersuites.h
+++ b/include/mbedtls/ssl_ciphersuites.h
@@ -24,6 +24,12 @@
 #ifndef MBEDTLS_SSL_CIPHERSUITES_H
 #define MBEDTLS_SSL_CIPHERSUITES_H
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
 #include "pk.h"
 #include "cipher.h"
 #include "md.h"
@@ -480,6 +486,24 @@
     }
 }
 
+static inline int mbedtls_ssl_ciphersuite_uses_srv_cert( const mbedtls_ssl_ciphersuite_t *info )
+{
+    switch( info->key_exchange )
+    {
+        case MBEDTLS_KEY_EXCHANGE_RSA:
+        case MBEDTLS_KEY_EXCHANGE_RSA_PSK:
+        case MBEDTLS_KEY_EXCHANGE_DHE_RSA:
+        case MBEDTLS_KEY_EXCHANGE_ECDH_RSA:
+        case MBEDTLS_KEY_EXCHANGE_ECDHE_RSA:
+        case MBEDTLS_KEY_EXCHANGE_ECDH_ECDSA:
+        case MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA:
+            return( 1 );
+
+        default:
+            return( 0 );
+    }
+}
+
 #if defined(MBEDTLS_KEY_EXCHANGE__SOME__DHE_ENABLED)
 static inline int mbedtls_ssl_ciphersuite_uses_dhe( const mbedtls_ssl_ciphersuite_t *info )
 {
diff --git a/include/mbedtls/ssl_cookie.h b/include/mbedtls/ssl_cookie.h
index 6a0ad4f..e34760a 100644
--- a/include/mbedtls/ssl_cookie.h
+++ b/include/mbedtls/ssl_cookie.h
@@ -24,6 +24,12 @@
 #ifndef MBEDTLS_SSL_COOKIE_H
 #define MBEDTLS_SSL_COOKIE_H
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
 #include "ssl.h"
 
 #if defined(MBEDTLS_THREADING_C)
diff --git a/include/mbedtls/ssl_internal.h b/include/mbedtls/ssl_internal.h
index 318d13f..5dde239 100644
--- a/include/mbedtls/ssl_internal.h
+++ b/include/mbedtls/ssl_internal.h
@@ -24,9 +24,19 @@
 #ifndef MBEDTLS_SSL_INTERNAL_H
 #define MBEDTLS_SSL_INTERNAL_H
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
 #include "ssl.h"
 #include "cipher.h"
 
+#if defined(MBEDTLS_USE_PSA_CRYPTO)
+#include "psa/crypto.h"
+#endif
+
 #if defined(MBEDTLS_MD5_C)
 #include "md5.h"
 #endif
@@ -47,6 +57,11 @@
 #include "ecjpake.h"
 #endif
 
+#if defined(MBEDTLS_USE_PSA_CRYPTO)
+#include "psa/crypto.h"
+#include "psa_util.h"
+#endif /* MBEDTLS_USE_PSA_CRYPTO */
+
 #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
     !defined(inline) && !defined(__cplusplus)
 #define inline __inline
@@ -270,7 +285,15 @@
 #endif
 #if defined(MBEDTLS_ECDH_C)
     mbedtls_ecdh_context ecdh_ctx;              /*!<  ECDH key exchange       */
-#endif
+
+#if defined(MBEDTLS_USE_PSA_CRYPTO)
+    psa_ecc_curve_t ecdh_psa_curve;
+    psa_key_handle_t ecdh_psa_privkey;
+    unsigned char ecdh_psa_peerkey[MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH];
+    size_t ecdh_psa_peerkey_len;
+#endif /* MBEDTLS_USE_PSA_CRYPTO */
+#endif /* MBEDTLS_ECDH_C */
+
 #if defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED)
     mbedtls_ecjpake_context ecjpake_ctx;        /*!< EC J-PAKE key exchange */
 #if defined(MBEDTLS_SSL_CLI_C)
@@ -284,7 +307,7 @@
 #endif
 #if defined(MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED)
 #if defined(MBEDTLS_USE_PSA_CRYPTO)
-    psa_key_slot_t psk_opaque;          /*!< Opaque PSK from the callback   */
+    psa_key_handle_t psk_opaque;        /*!< Opaque PSK from the callback   */
 #endif /* MBEDTLS_USE_PSA_CRYPTO */
     unsigned char *psk;                 /*!<  PSK from the callback         */
     size_t psk_len;                     /*!<  Length of PSK from callback   */
@@ -308,8 +331,13 @@
         ssl_ecrs_cke_ecdh_calc_secret,  /*!< ClientKeyExchange: ECDH step 2 */
         ssl_ecrs_crt_vrfy_sign,         /*!< CertificateVerify: pk_sign()   */
     } ecrs_state;                       /*!< current (or last) operation    */
+    mbedtls_x509_crt *ecrs_peer_cert;   /*!< The peer's CRT chain.          */
     size_t ecrs_n;                      /*!< place for saving a length      */
 #endif
+#if defined(MBEDTLS_X509_CRT_PARSE_C) && \
+    !defined(MBEDTLS_SSL_KEEP_PEER_CERTIFICATE)
+    mbedtls_pk_context peer_pubkey;     /*!< The public key from the peer.  */
+#endif /* MBEDTLS_X509_CRT_PARSE_C && !MBEDTLS_SSL_KEEP_PEER_CERTIFICATE */
 #if defined(MBEDTLS_SSL_PROTO_DTLS)
     unsigned int out_msg_seq;           /*!<  Outgoing handshake sequence number */
     unsigned int in_msg_seq;            /*!<  Incoming handshake sequence number */
@@ -370,11 +398,19 @@
 #endif
 #if defined(MBEDTLS_SSL_PROTO_TLS1_2)
 #if defined(MBEDTLS_SHA256_C)
+#if defined(MBEDTLS_USE_PSA_CRYPTO)
+    psa_hash_operation_t fin_sha256_psa;
+#else
     mbedtls_sha256_context fin_sha256;
 #endif
+#endif
 #if defined(MBEDTLS_SHA512_C)
+#if defined(MBEDTLS_USE_PSA_CRYPTO)
+    psa_hash_operation_t fin_sha384_psa;
+#else
     mbedtls_sha512_context fin_sha512;
 #endif
+#endif
 #endif /* MBEDTLS_SSL_PROTO_TLS1_2 */
 
     void (*update_checksum)(mbedtls_ssl_context *, const unsigned char *, size_t);
@@ -735,6 +771,9 @@
 void mbedtls_ssl_dtls_replay_update( mbedtls_ssl_context *ssl );
 #endif
 
+int mbedtls_ssl_session_copy( mbedtls_ssl_session *dst,
+                              const mbedtls_ssl_session *src );
+
 /* constant-time buffer comparison */
 static inline int mbedtls_ssl_safer_memcmp( const void *a, const void *b, size_t n )
 {
@@ -765,6 +804,7 @@
 
 #if defined(MBEDTLS_SSL_PROTO_TLS1) || defined(MBEDTLS_SSL_PROTO_TLS1_1) || \
     defined(MBEDTLS_SSL_PROTO_TLS1_2)
+/* The hash buffer must have at least MBEDTLS_MD_MAX_SIZE bytes of length. */
 int mbedtls_ssl_get_key_exchange_md_tls1_2( mbedtls_ssl_context *ssl,
                                             unsigned char *hash, size_t *hashlen,
                                             unsigned char *data, size_t data_len,
diff --git a/include/mbedtls/ssl_ticket.h b/include/mbedtls/ssl_ticket.h
index b2686df..774a007 100644
--- a/include/mbedtls/ssl_ticket.h
+++ b/include/mbedtls/ssl_ticket.h
@@ -24,6 +24,12 @@
 #ifndef MBEDTLS_SSL_TICKET_H
 #define MBEDTLS_SSL_TICKET_H
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
 /*
  * This implementation of the session ticket callbacks includes key
  * management, rotating the keys periodically in order to preserve forward
@@ -111,14 +117,14 @@
 /**
  * \brief           Implementation of the ticket write callback
  *
- * \note            See \c mbedlts_ssl_ticket_write_t for description
+ * \note            See \c mbedtls_ssl_ticket_write_t for description
  */
 mbedtls_ssl_ticket_write_t mbedtls_ssl_ticket_write;
 
 /**
  * \brief           Implementation of the ticket parse callback
  *
- * \note            See \c mbedlts_ssl_ticket_parse_t for description
+ * \note            See \c mbedtls_ssl_ticket_parse_t for description
  */
 mbedtls_ssl_ticket_parse_t mbedtls_ssl_ticket_parse;
 
diff --git a/include/mbedtls/version.h b/include/mbedtls/version.h
index 492fde3..79b42b2 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  14
+#define MBEDTLS_VERSION_MINOR  17
 #define MBEDTLS_VERSION_PATCH  0
 
 /**
@@ -47,9 +47,9 @@
  *    MMNNPP00
  *    Major version | Minor version | Patch version
  */
-#define MBEDTLS_VERSION_NUMBER         0x020E0000
-#define MBEDTLS_VERSION_STRING         "2.14.0"
-#define MBEDTLS_VERSION_STRING_FULL    "mbed TLS 2.14.0"
+#define MBEDTLS_VERSION_NUMBER         0x02110000
+#define MBEDTLS_VERSION_STRING         "2.17.0"
+#define MBEDTLS_VERSION_STRING_FULL    "mbed TLS 2.17.0"
 
 #if defined(MBEDTLS_VERSION_C)
 
diff --git a/include/mbedtls/x509.h b/include/mbedtls/x509.h
index d6db9c6..b63e864 100644
--- a/include/mbedtls/x509.h
+++ b/include/mbedtls/x509.h
@@ -77,7 +77,7 @@
 #define MBEDTLS_ERR_X509_ALLOC_FAILED                     -0x2880  /**< Allocation of memory failed. */
 #define MBEDTLS_ERR_X509_FILE_IO_ERROR                    -0x2900  /**< Read/write of file failed. */
 #define MBEDTLS_ERR_X509_BUFFER_TOO_SMALL                 -0x2980  /**< Destination buffer is too small. */
-#define MBEDTLS_ERR_X509_FATAL_ERROR                      -0x3000  /**< A fatal error occured, eg the chain is too long or the vrfy callback failed. */
+#define MBEDTLS_ERR_X509_FATAL_ERROR                      -0x3000  /**< A fatal error occurred, eg the chain is too long or the vrfy callback failed. */
 /* \} name */
 
 /**
@@ -142,24 +142,26 @@
  *
  * Comments refer to the status for using certificates. Status can be
  * different for writing certificates or reading CRLs or CSRs.
+ *
+ * Those are defined in oid.h as oid.c needs them in a data structure. Since
+ * these were previously defined here, let's have aliases for compatibility.
  */
-#define MBEDTLS_X509_EXT_AUTHORITY_KEY_IDENTIFIER    (1 << 0)
-#define MBEDTLS_X509_EXT_SUBJECT_KEY_IDENTIFIER      (1 << 1)
-#define MBEDTLS_X509_EXT_KEY_USAGE                   (1 << 2)
-#define MBEDTLS_X509_EXT_CERTIFICATE_POLICIES        (1 << 3)
-#define MBEDTLS_X509_EXT_POLICY_MAPPINGS             (1 << 4)
-#define MBEDTLS_X509_EXT_SUBJECT_ALT_NAME            (1 << 5)    /* Supported (DNS) */
-#define MBEDTLS_X509_EXT_ISSUER_ALT_NAME             (1 << 6)
-#define MBEDTLS_X509_EXT_SUBJECT_DIRECTORY_ATTRS     (1 << 7)
-#define MBEDTLS_X509_EXT_BASIC_CONSTRAINTS           (1 << 8)    /* Supported */
-#define MBEDTLS_X509_EXT_NAME_CONSTRAINTS            (1 << 9)
-#define MBEDTLS_X509_EXT_POLICY_CONSTRAINTS          (1 << 10)
-#define MBEDTLS_X509_EXT_EXTENDED_KEY_USAGE          (1 << 11)
-#define MBEDTLS_X509_EXT_CRL_DISTRIBUTION_POINTS     (1 << 12)
-#define MBEDTLS_X509_EXT_INIHIBIT_ANYPOLICY          (1 << 13)
-#define MBEDTLS_X509_EXT_FRESHEST_CRL                (1 << 14)
-
-#define MBEDTLS_X509_EXT_NS_CERT_TYPE                (1 << 16)
+#define MBEDTLS_X509_EXT_AUTHORITY_KEY_IDENTIFIER MBEDTLS_OID_X509_EXT_AUTHORITY_KEY_IDENTIFIER
+#define MBEDTLS_X509_EXT_SUBJECT_KEY_IDENTIFIER   MBEDTLS_OID_X509_EXT_SUBJECT_KEY_IDENTIFIER
+#define MBEDTLS_X509_EXT_KEY_USAGE                MBEDTLS_OID_X509_EXT_KEY_USAGE
+#define MBEDTLS_X509_EXT_CERTIFICATE_POLICIES     MBEDTLS_OID_X509_EXT_CERTIFICATE_POLICIES
+#define MBEDTLS_X509_EXT_POLICY_MAPPINGS          MBEDTLS_OID_X509_EXT_POLICY_MAPPINGS
+#define MBEDTLS_X509_EXT_SUBJECT_ALT_NAME         MBEDTLS_OID_X509_EXT_SUBJECT_ALT_NAME         /* Supported (DNS) */
+#define MBEDTLS_X509_EXT_ISSUER_ALT_NAME          MBEDTLS_OID_X509_EXT_ISSUER_ALT_NAME
+#define MBEDTLS_X509_EXT_SUBJECT_DIRECTORY_ATTRS  MBEDTLS_OID_X509_EXT_SUBJECT_DIRECTORY_ATTRS
+#define MBEDTLS_X509_EXT_BASIC_CONSTRAINTS        MBEDTLS_OID_X509_EXT_BASIC_CONSTRAINTS        /* Supported */
+#define MBEDTLS_X509_EXT_NAME_CONSTRAINTS         MBEDTLS_OID_X509_EXT_NAME_CONSTRAINTS
+#define MBEDTLS_X509_EXT_POLICY_CONSTRAINTS       MBEDTLS_OID_X509_EXT_POLICY_CONSTRAINTS
+#define MBEDTLS_X509_EXT_EXTENDED_KEY_USAGE       MBEDTLS_OID_X509_EXT_EXTENDED_KEY_USAGE
+#define MBEDTLS_X509_EXT_CRL_DISTRIBUTION_POINTS  MBEDTLS_OID_X509_EXT_CRL_DISTRIBUTION_POINTS
+#define MBEDTLS_X509_EXT_INIHIBIT_ANYPOLICY       MBEDTLS_OID_X509_EXT_INIHIBIT_ANYPOLICY
+#define MBEDTLS_X509_EXT_FRESHEST_CRL             MBEDTLS_OID_X509_EXT_FRESHEST_CRL
+#define MBEDTLS_X509_EXT_NS_CERT_TYPE             MBEDTLS_OID_X509_EXT_NS_CERT_TYPE
 
 /*
  * Storage format identifiers
@@ -250,7 +252,7 @@
  *
  * \param to       mbedtls_x509_time to check
  *
- * \return         1 if the given time is in the past or an error occured,
+ * \return         1 if the given time is in the past or an error occurred,
  *                 0 otherwise.
  */
 int mbedtls_x509_time_is_past( const mbedtls_x509_time *to );
@@ -264,11 +266,13 @@
  *
  * \param from     mbedtls_x509_time to check
  *
- * \return         1 if the given time is in the future or an error occured,
+ * \return         1 if the given time is in the future or an error occurred,
  *                 0 otherwise.
  */
 int mbedtls_x509_time_is_future( const mbedtls_x509_time *from );
 
+#if defined(MBEDTLS_SELF_TEST)
+
 /**
  * \brief          Checkup routine
  *
@@ -276,6 +280,8 @@
  */
 int mbedtls_x509_self_test( int verbose );
 
+#endif /* MBEDTLS_SELF_TEST */
+
 /*
  * Internal module functions. You probably do not want to use these unless you
  * know you do.
diff --git a/include/mbedtls/x509_crl.h b/include/mbedtls/x509_crl.h
index 08a4283..fa838d6 100644
--- a/include/mbedtls/x509_crl.h
+++ b/include/mbedtls/x509_crl.h
@@ -111,7 +111,7 @@
 /**
  * \brief          Parse one or more CRLs and append them to the chained list
  *
- * \note           Mutliple CRLs are accepted only if using PEM format
+ * \note           Multiple CRLs are accepted only if using PEM format
  *
  * \param chain    points to the start of the chain
  * \param buf      buffer holding the CRL data in PEM or DER format
@@ -126,7 +126,7 @@
 /**
  * \brief          Load one or more CRLs and append them to the chained list
  *
- * \note           Mutliple CRLs are accepted only if using PEM format
+ * \note           Multiple CRLs are accepted only if using PEM format
  *
  * \param chain    points to the start of the chain
  * \param path     filename to read the CRLs from (in PEM or DER encoding)
diff --git a/include/mbedtls/x509_crt.h b/include/mbedtls/x509_crt.h
index afeefca..b3f27be 100644
--- a/include/mbedtls/x509_crt.h
+++ b/include/mbedtls/x509_crt.h
@@ -52,6 +52,8 @@
  */
 typedef struct mbedtls_x509_crt
 {
+    int own_buffer;                     /**< Indicates if \c raw is owned
+                                         *   by the structure or not.        */
     mbedtls_x509_buf raw;               /**< The raw certificate data (DER). */
     mbedtls_x509_buf tbs;               /**< The raw certificate body (DER). The part that is To Be Signed. */
 
@@ -68,6 +70,7 @@
     mbedtls_x509_time valid_from;       /**< Start time of certificate validity. */
     mbedtls_x509_time valid_to;         /**< End time of certificate validity. */
 
+    mbedtls_x509_buf pk_raw;
     mbedtls_pk_context pk;              /**< Container for the public key context. */
 
     mbedtls_x509_buf issuer_id;         /**< Optional X.509 v2/v3 issuer unique identifier. */
@@ -220,31 +223,88 @@
 
 /**
  * \brief          Parse a single DER formatted certificate and add it
- *                 to the chained list.
+ *                 to the end of the provided chained list.
  *
- * \param chain    points to the start of the chain
- * \param buf      buffer holding the certificate DER data
- * \param buflen   size of the buffer
+ * \param chain    The pointer to the start of the CRT chain to attach to.
+ *                 When parsing the first CRT in a chain, this should point
+ *                 to an instance of ::mbedtls_x509_crt initialized through
+ *                 mbedtls_x509_crt_init().
+ * \param buf      The buffer holding the DER encoded certificate.
+ * \param buflen   The size in Bytes of \p buf.
  *
- * \return         0 if successful, or a specific X509 or PEM error code
+ * \note           This function makes an internal copy of the CRT buffer
+ *                 \p buf. In particular, \p buf may be destroyed or reused
+ *                 after this call returns. To avoid duplicating the CRT
+ *                 buffer (at the cost of stricter lifetime constraints),
+ *                 use mbedtls_x509_crt_parse_der_nocopy() instead.
+ *
+ * \return         \c 0 if successful.
+ * \return         A negative error code on failure.
  */
-int mbedtls_x509_crt_parse_der( mbedtls_x509_crt *chain, const unsigned char *buf,
-                        size_t buflen );
+int mbedtls_x509_crt_parse_der( mbedtls_x509_crt *chain,
+                                const unsigned char *buf,
+                                size_t buflen );
 
 /**
- * \brief          Parse one or more certificates and add them
- *                 to the chained list. Parses permissively. If some
- *                 certificates can be parsed, the result is the number
- *                 of failed certificates it encountered. If none complete
- *                 correctly, the first error is returned.
+ * \brief          Parse a single DER formatted certificate and add it
+ *                 to the end of the provided chained list. This is a
+ *                 variant of mbedtls_x509_crt_parse_der() which takes
+ *                 temporary ownership of the CRT buffer until the CRT
+ *                 is destroyed.
  *
- * \param chain    points to the start of the chain
- * \param buf      buffer holding the certificate data in PEM or DER format
- * \param buflen   size of the buffer
- *                 (including the terminating null byte for PEM data)
+ * \param chain    The pointer to the start of the CRT chain to attach to.
+ *                 When parsing the first CRT in a chain, this should point
+ *                 to an instance of ::mbedtls_x509_crt initialized through
+ *                 mbedtls_x509_crt_init().
+ * \param buf      The address of the readable buffer holding the DER encoded
+ *                 certificate to use. On success, this buffer must be
+ *                 retained and not be changed for the liftetime of the
+ *                 CRT chain \p chain, that is, until \p chain is destroyed
+ *                 through a call to mbedtls_x509_crt_free().
+ * \param buflen   The size in Bytes of \p buf.
  *
- * \return         0 if all certificates parsed successfully, a positive number
- *                 if partly successful or a specific X509 or PEM error code
+ * \note           This call is functionally equivalent to
+ *                 mbedtls_x509_crt_parse_der(), but it avoids creating a
+ *                 copy of the input buffer at the cost of stronger lifetime
+ *                 constraints. This is useful in constrained environments
+ *                 where duplication of the CRT cannot be tolerated.
+ *
+ * \return         \c 0 if successful.
+ * \return         A negative error code on failure.
+ */
+int mbedtls_x509_crt_parse_der_nocopy( mbedtls_x509_crt *chain,
+                                       const unsigned char *buf,
+                                       size_t buflen );
+
+/**
+ * \brief          Parse one DER-encoded or one or more concatenated PEM-encoded
+ *                 certificates and add them to the chained list.
+ *
+ *                 For CRTs in PEM encoding, the function parses permissively:
+ *                 if at least one certificate can be parsed, the function
+ *                 returns the number of certificates for which parsing failed
+ *                 (hence \c 0 if all certificates were parsed successfully).
+ *                 If no certificate could be parsed, the function returns
+ *                 the first (negative) error encountered during parsing.
+ *
+ *                 PEM encoded certificates may be interleaved by other data
+ *                 such as human readable descriptions of their content, as
+ *                 long as the certificates are enclosed in the PEM specific
+ *                 '-----{BEGIN/END} CERTIFICATE-----' delimiters.
+ *
+ * \param chain    The chain to which to add the parsed certificates.
+ * \param buf      The buffer holding the certificate data in PEM or DER format.
+ *                 For certificates in PEM encoding, this may be a concatenation
+ *                 of multiple certificates; for DER encoding, the buffer must
+ *                 comprise exactly one certificate.
+ * \param buflen   The size of \p buf, including the terminating \c NULL byte
+ *                 in case of PEM encoded data.
+ *
+ * \return         \c 0 if all certificates were parsed successfully.
+ * \return         The (positive) number of certificates that couldn't
+ *                 be parsed if parsing was partly successful (see above).
+ * \return         A negative X509 or PEM error code otherwise.
+ *
  */
 int mbedtls_x509_crt_parse( mbedtls_x509_crt *chain, const unsigned char *buf, size_t buflen );
 
diff --git a/include/mbedtls/x509_csr.h b/include/mbedtls/x509_csr.h
index 0c6ccad..a3c2804 100644
--- a/include/mbedtls/x509_csr.h
+++ b/include/mbedtls/x509_csr.h
@@ -205,6 +205,14 @@
  * \param key_usage key usage flags to set
  *
  * \return          0 if successful, or MBEDTLS_ERR_X509_ALLOC_FAILED
+ *
+ * \note            The <code>decipherOnly</code> flag from the Key Usage
+ *                  extension is represented by bit 8 (i.e.
+ *                  <code>0x8000</code>), which cannot typically be represented
+ *                  in an unsigned char. Therefore, the flag
+ *                  <code>decipherOnly</code> (i.e.
+ *                  #MBEDTLS_X509_KU_DECIPHER_ONLY) cannot be set using this
+ *                  function.
  */
 int mbedtls_x509write_csr_set_key_usage( mbedtls_x509write_csr *ctx, unsigned char key_usage );
 
diff --git a/include/mbedtls/xtea.h b/include/mbedtls/xtea.h
index 6430c13..b47f553 100644
--- a/include/mbedtls/xtea.h
+++ b/include/mbedtls/xtea.h
@@ -121,6 +121,8 @@
                     unsigned char *output);
 #endif /* MBEDTLS_CIPHER_MODE_CBC */
 
+#if defined(MBEDTLS_SELF_TEST)
+
 /**
  * \brief          Checkup routine
  *
@@ -128,6 +130,8 @@
  */
 int mbedtls_xtea_self_test( int verbose );
 
+#endif /* MBEDTLS_SELF_TEST */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index bdbbc1f..6a7bce8 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -193,7 +193,7 @@
  *         the policy has been saved to persistent storage. Implementations
  *         may defer saving the policy until the key material is created.
  * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_OCCUPIED_SLOT
+ * \retval #PSA_ERROR_ALREADY_EXISTS
  * \retval #PSA_ERROR_NOT_SUPPORTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
@@ -285,7 +285,7 @@
  *         Success. The application can now use the value of `*handle`
  *         to access the newly allocated key slot.
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  *         \p lifetime is invalid, for example #PSA_KEY_LIFETIME_VOLATILE.
  * \retval #PSA_ERROR_INVALID_ARGUMENT
@@ -322,7 +322,7 @@
  *         to access the newly allocated key slot.
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
- * \retval #PSA_ERROR_OCCUPIED_SLOT
+ * \retval #PSA_ERROR_ALREADY_EXISTS
  *         There is already a key with the identifier \p id in the storage
  *         area designated by \p lifetime.
  * \retval #PSA_ERROR_INVALID_ARGUMENT
@@ -404,7 +404,7 @@
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  *         The key slot is invalid,
  *         or the key data is not correctly formatted.
- * \retval #PSA_ERROR_OCCUPIED_SLOT
+ * \retval #PSA_ERROR_ALREADY_EXISTS
  *         There is already a key in the specified slot.
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
@@ -476,7 +476,7 @@
  *
  * \retval #PSA_SUCCESS
  * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
  *         The handle is to a key slot which does not contain key material yet.
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
@@ -655,7 +655,7 @@
  *
  * \retval #PSA_SUCCESS
  * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_NOT_SUPPORTED
  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
@@ -723,7 +723,7 @@
  *
  * \retval #PSA_SUCCESS
  * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  *         The key is neither a public key nor a key pair.
  * \retval #PSA_ERROR_NOT_SUPPORTED
@@ -750,8 +750,9 @@
  *
  * Copy key material from one location to another.
  *
- * This function is primarily useful to copy a key from one lifetime
- * to another. The target key retains its lifetime and location.
+ * This function is primarily useful to copy a key from one location
+ * to another, since it populates a key using the material from
+ * another key which may have a different lifetime.
  *
  * In an implementation where slots have different ownerships,
  * this function may be used to share a key with a different party,
@@ -791,9 +792,9 @@
  *
  * \retval #PSA_SUCCESS
  * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_OCCUPIED_SLOT
+ * \retval #PSA_ERROR_ALREADY_EXISTS
  *         \p target_handle already contains key material.
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
  *         \p source_handle does not contain key material.
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  *         The policy constraints on the source, on the target and
@@ -956,6 +957,9 @@
  *         Success.
  * \retval #PSA_ERROR_NOT_SUPPORTED
  *         \p alg is not supported or is not a hash algorithm.
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The operation state is not valid (already set up and not
+ *         subsequently completed).
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
@@ -1291,7 +1295,7 @@
  * \retval #PSA_SUCCESS
  *         Success.
  * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  *         \p handle is not compatible with \p alg.
@@ -1302,6 +1306,9 @@
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_TAMPERING_DETECTED
  * \retval #PSA_ERROR_BAD_STATE
+ *         The operation state is not valid (already set up and not
+ *         subsequently completed).
+ * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.
@@ -1348,7 +1355,7 @@
  * \retval #PSA_SUCCESS
  *         Success.
  * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  *         \c key is not compatible with \c alg.
@@ -1359,6 +1366,9 @@
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_TAMPERING_DETECTED
  * \retval #PSA_ERROR_BAD_STATE
+ *         The operation state is not valid (already set up and not
+ *         subsequently completed).
+ * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.
@@ -1677,7 +1687,7 @@
  * \retval #PSA_SUCCESS
  *         Success.
  * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  *         \p handle is not compatible with \p alg.
@@ -1688,6 +1698,9 @@
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_TAMPERING_DETECTED
  * \retval #PSA_ERROR_BAD_STATE
+ *         The operation state is not valid (already set up and not
+ *         subsequently completed).
+ * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.
@@ -1736,7 +1749,7 @@
  * \retval #PSA_SUCCESS
  *         Success.
  * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  *         \p handle is not compatible with \p alg.
@@ -1747,6 +1760,9 @@
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_TAMPERING_DETECTED
  * \retval #PSA_ERROR_BAD_STATE
+ *         The operation state is not valid (already set up and not
+ *         subsequently completed).
+ * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.
@@ -1964,7 +1980,7 @@
  * \retval #PSA_SUCCESS
  *         Success.
  * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  *         \p handle is not compatible with \p alg.
@@ -2020,7 +2036,7 @@
  * \retval #PSA_SUCCESS
  *         Success.
  * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
  * \retval #PSA_ERROR_INVALID_SIGNATURE
  *         The ciphertext is not authentic.
  * \retval #PSA_ERROR_NOT_PERMITTED
@@ -2861,7 +2877,7 @@
  * \param output_length     Number of bytes to output.
  *
  * \retval #PSA_SUCCESS
- * \retval #PSA_ERROR_INSUFFICIENT_CAPACITY
+ * \retval #PSA_ERROR_INSUFFICIENT_DATA
  *                          There were fewer than \p output_length bytes
  *                          in the generator. Note that in this case, no
  *                          output is written to the output buffer.
@@ -2968,7 +2984,7 @@
  *         Success.
  *         If the key is persistent, the key material and the key's metadata
  *         have been saved to persistent storage.
- * \retval #PSA_ERROR_INSUFFICIENT_CAPACITY
+ * \retval #PSA_ERROR_INSUFFICIENT_DATA
  *         There was not enough data to create the desired key.
  *         Note that in this case, no output is written to the output buffer.
  *         The generator's capacity is set to 0, thus subsequent calls to
@@ -2978,7 +2994,7 @@
  *         implementation in general or in this particular slot.
  * \retval #PSA_ERROR_BAD_STATE
  * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_OCCUPIED_SLOT
+ * \retval #PSA_ERROR_ALREADY_EXISTS
  *         There is already a key in the specified slot.
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
@@ -3140,7 +3156,7 @@
  * \retval #PSA_SUCCESS
  *         Success.
  * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  *         \c step is not compatible with the generator's algorithm.
@@ -3201,7 +3217,7 @@
  * \retval #PSA_SUCCESS
  *         Success.
  * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  *         \c private_key is not compatible with \c alg,
@@ -3368,7 +3384,7 @@
  *         If the key is persistent, the key material and the key's metadata
  *         have been saved to persistent storage.
  * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_OCCUPIED_SLOT
+ * \retval #PSA_ERROR_ALREADY_EXISTS
  *         There is already a key in the specified slot.
  * \retval #PSA_ERROR_NOT_SUPPORTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
diff --git a/include/psa/crypto_accel_driver.h b/include/psa/crypto_accel_driver.h
index b752fed..4a540f0 100644
--- a/include/psa/crypto_accel_driver.h
+++ b/include/psa/crypto_accel_driver.h
@@ -38,12 +38,13 @@
 extern "C" {
 #endif
 
-/** \defgroup driver_digest Message Digests
+/** \defgroup driver_digest Hardware-Accelerated Message Digests
  *
  * Generation and authentication of Message Digests (aka hashes) must be done
  * in parts using the following sequence:
  * - `psa_drv_hash_setup_t`
  * - `psa_drv_hash_update_t`
+ * - `psa_drv_hash_update_t`
  * - ...
  * - `psa_drv_hash_finish_t`
  *
@@ -64,7 +65,7 @@
 /** \brief The function prototype for the start operation of a hash (message
  * digest) operation
  *
- *  Functions that implement the prototype should be named in the following
+ *  Functions that implement this prototype should be named in the following
  * convention:
  * ~~~~~~~~~~~~~{.c}
  * psa_drv_hash_<ALGO>_setup
@@ -81,7 +82,7 @@
 /** \brief The function prototype for the update operation of a hash (message
  * digest) operation
  *
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
  * convention:
  * ~~~~~~~~~~~~~{.c}
  * psa_drv_hash_<ALGO>_update
@@ -99,10 +100,10 @@
                                               const uint8_t *p_input,
                                               size_t input_length);
 
-/** \brief  The prototype for the finish operation of a hash (message digest)
- * operation
+/** \brief  The function prototype for the finish operation of a hash (message
+ * digest) operation
  *
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
  * convention:
  * ~~~~~~~~~~~~~{.c}
  * psa_drv_hash_<ALGO>_finish
@@ -130,7 +131,7 @@
 /** \brief The function prototype for the abort operation of a hash (message
  * digest) operation
  *
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
  * convention:
  * ~~~~~~~~~~~~~{.c}
  * psa_drv_hash_<ALGO>_abort
@@ -144,39 +145,39 @@
 
 /**@}*/
 
-/** \defgroup transparent_mac Transparent Message Authentication Code
+/** \defgroup accel_mac Hardware-Accelerated Message Authentication Code
  * Generation and authentication of Message Authentication Codes (MACs) using
- * transparent keys can be done either as a single function call (via the
- * `psa_drv_mac_transparent_generate_t` or `psa_drv_mac_transparent_verify_t`
+ * cryptographic accelerators can be done either as a single function call (via the
+ * `psa_drv_accel_mac_generate_t` or `psa_drv_accel_mac_verify_t`
  * functions), or in parts using the following sequence:
- * - `psa_drv_mac_transparent_setup_t`
- * - `psa_drv_mac_transparent_update_t`
- * - `psa_drv_mac_transparent_update_t`
+ * - `psa_drv_accel_mac_setup_t`
+ * - `psa_drv_accel_mac_update_t`
+ * - `psa_drv_accel_mac_update_t`
  * - ...
- * - `psa_drv_mac_transparent_finish_t` or `psa_drv_mac_transparent_finish_verify_t`
+ * - `psa_drv_accel_mac_finish_t` or `psa_drv_accel_mac_finish_verify_t`
  *
- * If a previously started Transparent MAC operation needs to be terminated, it
- * should be done so by the `psa_drv_mac_transparent_abort_t`. Failure to do so may
+ * If a previously started MAC operation needs to be terminated, it
+ * should be done so by the `psa_drv_accel_mac_abort_t`. Failure to do so may
  * result in allocated resources not being freed or in other undefined
  * behavior.
  *
  */
 /**@{*/
 
-/** \brief The hardware-specific transparent-key MAC context structure
+/** \brief The hardware-accelerator-specific MAC context structure
  *
  * The contents of this structure are implementation dependent and are
  * therefore not described here.
  */
-typedef struct psa_drv_mac_transparent_context_s psa_drv_mac_transparent_context_t;
+typedef struct psa_drv_accel_mac_context_s psa_drv_accel_mac_context_t;
 
 /** \brief The function prototype for the setup operation of a
- * transparent-key MAC operation
+ * hardware-accelerated MAC operation
  *
- *  Functions that implement the prototype should be named in the following
+ *  Functions that implement this prototype should be named in the following
  * convention:
  * ~~~~~~~~~~~~~{.c}
- * psa_drv_mac_transparent_<ALGO>_<MAC_VARIANT>_setup
+ * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_setup
  * ~~~~~~~~~~~~~
  * Where `ALGO` is the name of the underlying primitive, and `MAC_VARIANT`
  * is the specific variant of a MAC operation (such as HMAC or CMAC)
@@ -190,17 +191,17 @@
  * \retval  PSA_SUCCESS
  *          Success.
  */
-typedef psa_status_t (*psa_drv_mac_transparent_setup_t)(psa_drv_mac_transparent_context_t *p_context,
-                                                        const uint8_t *p_key,
-                                                        size_t key_length);
+typedef psa_status_t (*psa_drv_accel_mac_setup_t)(psa_drv_accel_mac_context_t *p_context,
+                                                  const uint8_t *p_key,
+                                                  size_t key_length);
 
 /** \brief The function prototype for the update operation of a
- * transparent-key MAC operation
+ * hardware-accelerated MAC operation
  *
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
  * convention:
  * ~~~~~~~~~~~~~{.c}
- * psa_drv_mac_transparent_<ALGO>_<MAC_VARIANT>_update
+ * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_update
  * ~~~~~~~~~~~~~
  * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT`
  * is the specific variant of a MAC operation (such as HMAC or CMAC)
@@ -212,17 +213,17 @@
  *                              to the MAC operation
  * \param[in] input_length      The size in bytes of the input message buffer
  */
-typedef psa_status_t (*psa_drv_mac_transparent_update_t)(psa_drv_mac_transparent_context_t *p_context,
-                                                         const uint8_t *p_input,
-                                                         size_t input_length);
+typedef psa_status_t (*psa_drv_accel_mac_update_t)(psa_drv_accel_mac_context_t *p_context,
+                                                   const uint8_t *p_input,
+                                                   size_t input_length);
 
 /** \brief  The function prototype for the finish operation of a
- * transparent-key MAC operation
+ * hardware-accelerated MAC operation
  *
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
  *  convention:
  * ~~~~~~~~~~~~~{.c}
- * psa_drv_mac_transparent_<ALGO>_<MAC_VARIANT>_finish
+ * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_finish
  * ~~~~~~~~~~~~~
  * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is
  * the specific variant of a MAC operation (such as HMAC or CMAC)
@@ -237,17 +238,17 @@
  * \retval PSA_SUCCESS
  *          Success.
  */
-typedef psa_status_t (*psa_drv_mac_transparent_finish_t)(psa_drv_mac_transparent_context_t *p_context,
-                                                         uint8_t *p_mac,
-                                                         size_t mac_length);
+typedef psa_status_t (*psa_drv_accel_mac_finish_t)(psa_drv_accel_mac_context_t *p_context,
+                                                   uint8_t *p_mac,
+                                                   size_t mac_length);
 
 /** \brief The function prototype for the finish and verify operation of a
- * transparent-key MAC operation
+ * hardware-accelerated MAC operation
  *
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
  * convention:
  * ~~~~~~~~~~~~~{.c}
- * psa_drv_mac_transparent_<ALGO>_<MAC_VARIANT>_finish_verify
+ * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_finish_verify
  * ~~~~~~~~~~~~~
  * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is
  * the specific variant of a MAC operation (such as HMAC or CMAC)
@@ -263,17 +264,17 @@
  * \retval PSA_SUCCESS
  *          The operation completed successfully and the comparison matched
  */
-typedef psa_status_t (*psa_drv_mac_transparent_finish_verify_t)(psa_drv_mac_transparent_context_t *p_context,
-                                                                const uint8_t *p_mac,
-                                                                size_t mac_length);
+typedef psa_status_t (*psa_drv_accel_mac_finish_verify_t)(psa_drv_accel_mac_context_t *p_context,
+                                                          const uint8_t *p_mac,
+                                                          size_t mac_length);
 
 /** \brief The function prototype for the abort operation for a previously
- * started transparent-key MAC operation
+ * started hardware-accelerated MAC operation
  *
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
  * convention:
  * ~~~~~~~~~~~~~{.c}
- * psa_drv_mac_transparent_<ALGO>_<MAC_VARIANT>_abort
+ * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_abort
  * ~~~~~~~~~~~~~
  * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is
  * the specific variant of a MAC operation (such as HMAC or CMAC)
@@ -283,15 +284,15 @@
  *                              aborted
  *
  */
-typedef psa_status_t (*psa_drv_mac_transparent_abort_t)(psa_drv_mac_transparent_context_t *p_context);
+typedef psa_status_t (*psa_drv_accel_mac_abort_t)(psa_drv_accel_mac_context_t *p_context);
 
-/** \brief The function prototype for a one-shot operation of a transparent-key
- * MAC operation
+/** \brief The function prototype for the one-shot operation of a
+ * hardware-accelerated MAC operation
  *
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
  * convention:
  * ~~~~~~~~~~~~~{.c}
- * psa_drv_mac_transparent_<ALGO>_<MAC_VARIANT>
+ * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>
  * ~~~~~~~~~~~~~
  * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is
  * the specific variant of a MAC operation (such as HMAC or CMAC)
@@ -306,21 +307,21 @@
  *                           upon success
  * \param[in] mac_length     The length in bytes of the `p_mac` buffer
  */
-typedef psa_status_t (*psa_drv_mac_transparent_t)(const uint8_t *p_input,
-                                                  size_t input_length,
-                                                  const uint8_t *p_key,
-                                                  size_t key_length,
-                                                  psa_algorithm_t alg,
-                                                  uint8_t *p_mac,
-                                                  size_t mac_length);
+typedef psa_status_t (*psa_drv_accel_mac_t)(const uint8_t *p_input,
+                                            size_t input_length,
+                                            const uint8_t *p_key,
+                                            size_t key_length,
+                                            psa_algorithm_t alg,
+                                            uint8_t *p_mac,
+                                            size_t mac_length);
 
-/** \brief The function prototype for a one-shot operation of a transparent-key
- * MAC Verify operation
+/** \brief The function prototype for the one-shot hardware-accelerated MAC
+ * Verify operation
  *
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
  * convention:
  * ~~~~~~~~~~~~~{.c}
- * psa_drv_mac_transparent_<ALGO>_<MAC_VARIANT>_verify
+ * psa_drv_accel_mac_<ALGO>_<MAC_VARIANT>_verify
  * ~~~~~~~~~~~~~
  * Where `ALGO` is the name of the underlying algorithm, and `MAC_VARIANT` is
  * the specific variant of a MAC operation (such as HMAC or CMAC)
@@ -337,51 +338,53 @@
  * \retval PSA_SUCCESS
  *  The operation completed successfully and the comparison matched
  */
-typedef psa_status_t (*psa_drv_mac_transparent_verify_t)(const uint8_t *p_input,
-                                                         size_t input_length,
-                                                         const uint8_t *p_key,
-                                                         size_t key_length,
-                                                         psa_algorithm_t alg,
-                                                         const uint8_t *p_mac,
-                                                         size_t mac_length);
+typedef psa_status_t (*psa_drv_accel_mac_verify_t)(const uint8_t *p_input,
+                                                   size_t input_length,
+                                                   const uint8_t *p_key,
+                                                   size_t key_length,
+                                                   psa_algorithm_t alg,
+                                                   const uint8_t *p_mac,
+                                                   size_t mac_length);
 /**@}*/
 
-/** \defgroup transparent_cipher Transparent Block Cipher
- * Encryption and Decryption using transparent keys in block modes other than
- * ECB must be done in multiple parts, using the following flow:
- * - `psa_drv_cipher_transparent_setup_t`
- * - `psa_drv_cipher_transparent_set_iv_t` (optional depending upon block mode)
- * - `psa_drv_cipher_transparent_update_t`
+/** \defgroup accel_cipher Hardware-Accelerated Block Ciphers
+ * Encryption and Decryption using hardware-acceleration in block modes other
+ * than ECB must be done in multiple parts, using the following flow:
+ * - `psa_drv_accel_ciphersetup_t`
+ * - `psa_drv_accel_cipher_set_iv_t` (optional depending upon block mode)
+ * - `psa_drv_accel_cipher_update_t`
+ * - `psa_drv_accel_cipher_update_t`
  * - ...
- * - `psa_drv_cipher_transparent_finish_t`
-
- * If a previously started Transparent Cipher operation needs to be terminated,
- * it should be done so by the `psa_drv_cipher_transparent_abort_t`. Failure to do
- * so may result in allocated resources not being freed or in other undefined
- * behavior.
+ * - `psa_drv_accel_cipher_finish_t`
+ *
+ * If a previously started hardware-accelerated Cipher operation needs to be
+ * terminated, it should be done so by the `psa_drv_accel_cipher_abort_t`.
+ * Failure to do so may result in allocated resources not being freed or in
+ * other undefined behavior.
  */
 /**@{*/
 
-/** \brief The hardware-specific transparent-key Cipher context structure
+/** \brief The hardware-accelerator-specific cipher context structure
  *
  * The contents of this structure are implementation dependent and are
  * therefore not described here.
  */
-typedef struct psa_drv_cipher_transparent_context_s psa_drv_cipher_transparent_context_t;
+typedef struct psa_drv_accel_cipher_context_s psa_drv_accel_cipher_context_t;
 
-/** \brief The function prototype for the setup operation of transparent-key
- * block cipher operations.
- *  Functions that implement the prototype should be named in the following
+/** \brief The function prototype for the setup operation of
+ * hardware-accelerated block cipher operations.
+ *  Functions that implement this prototype should be named in the following
  * conventions:
  * ~~~~~~~~~~~~~{.c}
- * psa_drv_cipher_transparent_setup_<CIPHER_NAME>_<MODE>
+ * psa_drv_accel_cipher_setup_<CIPHER_NAME>_<MODE>
  * ~~~~~~~~~~~~~
  * Where
  * - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES)
  * - `MODE` is the block mode of the cipher operation (i.e. CBC or CTR)
- * or for stream ciphers:
+ *
+ * For stream ciphers:
  * ~~~~~~~~~~~~~{.c}
- * psa_drv_cipher_transparent_setup_<CIPHER_NAME>
+ * psa_drv_accel_cipher_setup_<CIPHER_NAME>
  * ~~~~~~~~~~~~~
  * Where `CIPHER_NAME` is the name of a stream cipher (i.e. RC4)
  *
@@ -395,17 +398,17 @@
  *
  * \retval PSA_SUCCESS
  */
-typedef psa_status_t (*psa_drv_cipher_transparent_setup_t)(psa_drv_cipher_transparent_context_t *p_context,
-                                                           psa_encrypt_or_decrypt_t direction,
-                                                           const uint8_t *p_key_data,
-                                                           size_t key_data_size);
+typedef psa_status_t (*psa_drv_accel_cipher_setup_t)(psa_drv_accel_cipher_context_t *p_context,
+                                                     psa_encrypt_or_decrypt_t direction,
+                                                     const uint8_t *p_key_data,
+                                                     size_t key_data_size);
 
 /** \brief The function prototype for the set initialization vector operation
- * of transparent-key block cipher operations
- * Functions that implement the prototype should be named in the following
+ * of hardware-accelerated block cipher operations
+ * Functions that implement this prototype should be named in the following
  * convention:
  * ~~~~~~~~~~~~~{.c}
- * psa_drv_cipher_transparent_set_iv_<CIPHER_NAME>_<MODE>
+ * psa_drv_accel_cipher_set_iv_<CIPHER_NAME>_<MODE>
  * ~~~~~~~~~~~~~
  * Where
  * - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES)
@@ -418,17 +421,17 @@
  *
  * \retval PSA_SUCCESS
  */
-typedef psa_status_t (*psa_drv_cipher_transparent_set_iv_t)(psa_drv_cipher_transparent_context_t *p_context,
-                                                            const uint8_t *p_iv,
-                                                            size_t iv_length);
+typedef psa_status_t (*psa_drv_accel_cipher_set_iv_t)(psa_drv_accel_cipher_context_t *p_context,
+                                                      const uint8_t *p_iv,
+                                                      size_t iv_length);
 
-/** \brief The function prototype for the update operation of transparent-key
- * block cipher operations.
+/** \brief The function prototype for the update operation of
+ * hardware-accelerated block cipher operations.
  *
- *  Functions that implement the prototype should be named in the following
+ *  Functions that implement this prototype should be named in the following
  * convention:
  * ~~~~~~~~~~~~~{.c}
- * psa_drv_cipher_transparent_update_<CIPHER_NAME>_<MODE>
+ * psa_drv_accel_cipher_update_<CIPHER_NAME>_<MODE>
  * ~~~~~~~~~~~~~
  * Where
  * - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES)
@@ -447,20 +450,20 @@
  *
  * \retval PSA_SUCCESS
  */
-typedef psa_status_t (*psa_drv_cipher_transparent_update_t)(psa_drv_cipher_transparent_context_t *p_context,
-                                                            const uint8_t *p_input,
-                                                            size_t input_size,
-                                                            uint8_t *p_output,
-                                                            size_t output_size,
-                                                            size_t *p_output_length);
+typedef psa_status_t (*psa_drv_accel_cipher_update_t)(psa_drv_accel_cipher_context_t *p_context,
+                                                      const uint8_t *p_input,
+                                                      size_t input_size,
+                                                      uint8_t *p_output,
+                                                      size_t output_size,
+                                                      size_t *p_output_length);
 
-/** \brief The function prototype for the finish operation of transparent-key
- * block cipher operations.
+/** \brief The function prototype for the finish operation of
+ * hardware-accelerated block cipher operations.
  *
- *  Functions that implement the prototype should be named in the following
+ *  Functions that implement this prototype should be named in the following
  * convention:
  * ~~~~~~~~~~~~~{.c}
- * psa_drv_cipher_transparent_finish_<CIPHER_NAME>_<MODE>
+ * psa_drv_accel_cipher_finish_<CIPHER_NAME>_<MODE>
  * ~~~~~~~~~~~~~
  * Where
  * - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES)
@@ -476,18 +479,18 @@
  *
  * \retval PSA_SUCCESS
  */
-typedef psa_status_t (*psa_drv_cipher_transparent_finish_t)(psa_drv_cipher_transparent_context_t *p_context,
-                                                            uint8_t *p_output,
-                                                            size_t output_size,
-                                                            size_t *p_output_length);
+typedef psa_status_t (*psa_drv_accel_cipher_finish_t)(psa_drv_accel_cipher_context_t *p_context,
+                                                      uint8_t *p_output,
+                                                      size_t output_size,
+                                                      size_t *p_output_length);
 
-/** \brief The function prototype for the abort operation of transparent-key
- * block cipher operations.
+/** \brief The function prototype for the abort operation of
+ * hardware-accelerated block cipher operations.
  *
  *  Functions that implement the following prototype should be named in the
  * following convention:
  * ~~~~~~~~~~~~~{.c}
- * psa_drv_cipher_transparent_abort_<CIPHER_NAME>_<MODE>
+ * psa_drv_accel_cipher_abort_<CIPHER_NAME>_<MODE>
  * ~~~~~~~~~~~~~
  * Where
  * - `CIPHER_NAME` is the name of the underlying block cipher (i.e. AES or DES)
@@ -498,27 +501,27 @@
  *
  * \retval PSA_SUCCESS
  */
-typedef psa_status_t (*psa_drv_cipher_transparent_abort_t)(psa_drv_cipher_transparent_context_t *p_context);
+typedef psa_status_t (*psa_drv_accel_cipher_abort_t)(psa_drv_accel_cipher_context_t *p_context);
 
 /**@}*/
 
-/** \defgroup aead_transparent AEAD Transparent
+/** \defgroup accel_aead Hardware-Accelerated Authenticated Encryption with Additional Data
  *
- * Authenticated Encryption with Additional Data (AEAD) operations with
- * transparent keys must be done in one function call. While this creates a
- * burden for implementers as there must be sufficient space in memory for the
- * entire message, it prevents decrypted data from being made available before
- * the authentication operation is complete and the data is known to be
- * authentic.
+ * Hardware-accelerated Authenticated Encryption with Additional Data (AEAD)
+ * operations must be done in one function call. While this creates a burden
+ * for implementers as there must be sufficient space in memory for the entire
+ * message, it prevents decrypted data from being made available before the
+ * authentication operation is complete and the data is known to be authentic.
  */
 /**@{*/
 
-/** Process an authenticated encryption operation using an opaque key.
+/** \brief The function prototype for the hardware-accelerated authenticated
+ * encryption operation.
  *
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
  * convention:
  * ~~~~~~~~~~~~~{.c}
- * psa_drv_aead_<ALGO>_encrypt
+ * psa_drv_accel_aead_<ALGO>_encrypt
  * ~~~~~~~~~~~~~
  * Where `ALGO` is the name of the AEAD algorithm
  *
@@ -551,27 +554,28 @@
  *                                      the `ciphertext` buffer
  *
  * \retval #PSA_SUCCESS
-
- */
-typedef psa_status_t (*psa_drv_aead_transparent_encrypt_t)(const uint8_t *p_key,
-                                                           size_t key_length,
-                                                           psa_algorithm_t alg,
-                                                           const uint8_t *nonce,
-                                                           size_t nonce_length,
-                                                           const uint8_t *additional_data,
-                                                           size_t additional_data_length,
-                                                           const uint8_t *plaintext,
-                                                           size_t plaintext_length,
-                                                           uint8_t *ciphertext,
-                                                           size_t ciphertext_size,
-                                                           size_t *ciphertext_length);
-
-/** Process an authenticated decryption operation using an opaque key.
  *
- * Functions that implement the prototype should be named in the following
+ */
+typedef psa_status_t (*psa_drv_accel_aead_encrypt_t)(const uint8_t *p_key,
+                                                     size_t key_length,
+                                                     psa_algorithm_t alg,
+                                                     const uint8_t *nonce,
+                                                     size_t nonce_length,
+                                                     const uint8_t *additional_data,
+                                                     size_t additional_data_length,
+                                                     const uint8_t *plaintext,
+                                                     size_t plaintext_length,
+                                                     uint8_t *ciphertext,
+                                                     size_t ciphertext_size,
+                                                     size_t *ciphertext_length);
+
+/** \brief The function prototype for the hardware-accelerated authenticated
+ * decryption operation.
+ *
+ * Functions that implement this prototype should be named in the following
  * convention:
  * ~~~~~~~~~~~~~{.c}
- * psa_drv_aead_<ALGO>_decrypt
+ * psa_drv_accel_aead_<ALGO>_decrypt
  * ~~~~~~~~~~~~~
  * Where `ALGO` is the name of the AEAD algorithm
  * \param[in] p_key                     A pointer to the key material
@@ -604,41 +608,45 @@
  * \retval #PSA_SUCCESS
  *         Success.
  */
-typedef psa_status_t (*psa_drv_aead_transparent_decrypt_t)(const uint8_t *p_key,
-                                                           size_t key_length,
-                                                           psa_algorithm_t alg,
-                                                           const uint8_t *nonce,
-                                                           size_t nonce_length,
-                                                           const uint8_t *additional_data,
-                                                           size_t additional_data_length,
-                                                           const uint8_t *ciphertext,
-                                                           size_t ciphertext_length,
-                                                           uint8_t *plaintext,
-                                                           size_t plaintext_size,
-                                                           size_t *plaintext_length);
+typedef psa_status_t (*psa_drv_accel_aead_decrypt_t)(const uint8_t *p_key,
+                                                     size_t key_length,
+                                                     psa_algorithm_t alg,
+                                                     const uint8_t *nonce,
+                                                     size_t nonce_length,
+                                                     const uint8_t *additional_data,
+                                                     size_t additional_data_length,
+                                                     const uint8_t *ciphertext,
+                                                     size_t ciphertext_length,
+                                                     uint8_t *plaintext,
+                                                     size_t plaintext_size,
+                                                     size_t *plaintext_length);
 
 /**@}*/
 
-/** \defgroup transparent_asymmetric Transparent Asymmetric Cryptography
+/** \defgroup accel_asymmetric Hardware-Accelerated Asymmetric Cryptography
  *
  * Since the amount of data that can (or should) be encrypted or signed using
- * asymmetric keys is limited by the key size, asymmetric key operations using
- * transparent keys must be done in single function calls.
+ * asymmetric keys is limited by the key size, hardware-accelerated asymmetric
+ * key operations must be done in single function calls.
  */
 /**@{*/
 
 
 /**
- * \brief A function that signs a hash or short message with a transparent
- * asymmetric private key
+ * \brief The function prototype for the hardware-accelerated asymmetric sign
+ * operation.
  *
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
  * convention:
  * ~~~~~~~~~~~~~{.c}
- * psa_drv_asymmetric_<ALGO>_sign
+ * psa_drv_accel_asymmetric_<ALGO>_sign
  * ~~~~~~~~~~~~~
  * Where `ALGO` is the name of the signing algorithm
  *
+ * This function supports any asymmetric-key output from psa_export_key() as
+ * the buffer in \p p_key. Refer to the documentation of \ref
+ * psa_export_key() for the formats.
+ *
  * \param[in] p_key                 A buffer containing the private key
  *                                  material
  * \param[in] key_size              The size in bytes of the `p_key` data
@@ -653,26 +661,32 @@
  *
  * \retval PSA_SUCCESS
  */
-typedef psa_status_t (*psa_drv_asymmetric_transparent_sign_t)(const uint8_t *p_key,
-                                                              size_t key_size,
-                                                              psa_algorithm_t alg,
-                                                              const uint8_t *p_hash,
-                                                              size_t hash_length,
-                                                              uint8_t *p_signature,
-                                                              size_t signature_size,
-                                                              size_t *p_signature_length);
+typedef psa_status_t (*psa_drv_accel_asymmetric_sign_t)(const uint8_t *p_key,
+                                                        size_t key_size,
+                                                        psa_algorithm_t alg,
+                                                        psa_key_type_t key_type,
+                                                        const uint8_t *p_hash,
+                                                        size_t hash_length,
+                                                        uint8_t *p_signature,
+                                                        size_t signature_size,
+                                                        size_t *p_signature_length);
 
 /**
- * \brief A function that verifies the signature a hash or short message using
- * a transparent asymmetric public key
+ * \brief The function prototype for the hardware-accelerated signature verify
+ * operation
  *
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
  * convention:
  * ~~~~~~~~~~~~~{.c}
- * psa_drv_asymmetric_<ALGO>_verify
+ * psa_drv_accel_asymmetric_<ALGO>_verify
  * ~~~~~~~~~~~~~
  * Where `ALGO` is the name of the signing algorithm
  *
+ * This function supports any output from \ref psa_export_public_key() as the
+ * buffer in \p p_key. Refer to the documentation of \ref
+ * psa_export_public_key() for the format of public keys and to the
+ * documentation of \ref psa_export_key() for the format for other key types.
+ *
  * \param[in] p_key             A buffer containing the public key material
  * \param[in] key_size          The size in bytes of the `p_key` data
  * \param[in] alg               A signature algorithm that is compatible with
@@ -686,25 +700,31 @@
  * \retval PSA_SUCCESS
  *         The signature is valid.
  */
-typedef psa_status_t (*psa_drv_asymmetric_transparent_verify_t)(const uint8_t *p_key,
-                                                                size_t key_size,
-                                                                psa_algorithm_t alg,
-                                                                const uint8_t *p_hash,
-                                                                size_t hash_length,
-                                                                const uint8_t *p_signature,
-                                                                size_t signature_length);
+typedef psa_status_t (*psa_drv_accel_asymmetric_verify_t)(const uint8_t *p_key,
+                                                          size_t key_size,
+                                                          psa_algorithm_t alg,
+                                                          psa_key_type_t key_type,
+                                                          const uint8_t *p_hash,
+                                                          size_t hash_length,
+                                                          const uint8_t *p_signature,
+                                                          size_t signature_length);
 
 /**
- * \brief A function that encrypts a short message with a transparent
- * asymmetric public key
+ * \brief The function prototype for the hardware-accelerated asymmetric
+ * encrypt operation
  *
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
  * convention:
  * ~~~~~~~~~~~~~{.c}
- * psa_drv_asymmetric_<ALGO>_encrypt
+ * psa_drv_accel_asymmetric_<ALGO>_encrypt
  * ~~~~~~~~~~~~~
  * Where `ALGO` is the name of the encryption algorithm
  *
+ * This function supports any output from \ref psa_export_public_key() as the
+ * buffer in \p p_key. Refer to the documentation of \ref
+ * psa_export_public_key() for the format of public keys and to the
+ * documentation of \ref psa_export_key() for the format for other key types.
+ *
  * \param[in] p_key             A buffer containing the public key material
  * \param[in] key_size          The size in bytes of the `p_key` data
  * \param[in] alg               An asymmetric encryption algorithm that is
@@ -730,27 +750,33 @@
  *
  * \retval PSA_SUCCESS
  */
-typedef psa_status_t (*psa_drv_asymmetric_transparent_encrypt_t)(const uint8_t *p_key,
-                                                                 size_t key_size,
-                                                                 psa_algorithm_t alg,
-                                                                 const uint8_t *p_input,
-                                                                 size_t input_length,
-                                                                 const uint8_t *p_salt,
-                                                                 size_t salt_length,
-                                                                 uint8_t *p_output,
-                                                                 size_t output_size,
-                                                                 size_t *p_output_length);
+typedef psa_status_t (*psa_drv_accel_asymmetric_encrypt_t)(const uint8_t *p_key,
+                                                           size_t key_size,
+                                                           psa_algorithm_t alg,
+                                                           psa_key_type_t key_type,
+                                                           const uint8_t *p_input,
+                                                           size_t input_length,
+                                                           const uint8_t *p_salt,
+                                                           size_t salt_length,
+                                                           uint8_t *p_output,
+                                                           size_t output_size,
+                                                           size_t *p_output_length);
 
 /**
- * \brief Decrypt a short message with a transparent asymmetric private key
+ * \brief The function prototype for the hardware=acce;erated asymmetric
+ * decrypt operation
  *
- * Functions that implement the prototype should be named in the following
+ * Functions that implement this prototype should be named in the following
  * convention:
  * ~~~~~~~~~~~~~{.c}
- * psa_drv_asymmetric_<ALGO>_decrypt
+ * psa_drv_accel_asymmetric_<ALGO>_decrypt
  * ~~~~~~~~~~~~~
  * Where `ALGO` is the name of the encryption algorithm
  *
+ * This function supports any asymmetric-key output from psa_export_key() as
+ * the buffer in \p p_key. Refer to the documentation of \ref
+ * psa_export_key() for the formats.
+ *
  * \param[in] p_key             A buffer containing the private key material
  * \param[in] key_size          The size in bytes of the `p_key` data
  * \param[in] alg               An asymmetric encryption algorithm that is
@@ -776,16 +802,17 @@
  *
  * \retval PSA_SUCCESS
  */
-typedef psa_status_t (*psa_drv_asymmetric_transparent_decrypt_t)(const uint8_t *p_key,
-                                                                 size_t key_size,
-                                                                 psa_algorithm_t alg,
-                                                                 const uint8_t *p_input,
-                                                                 size_t input_length,
-                                                                 const uint8_t *p_salt,
-                                                                 size_t salt_length,
-                                                                 uint8_t *p_output,
-                                                                 size_t output_size,
-                                                                 size_t *p_output_length);
+typedef psa_status_t (*psa_drv_accel_asymmetric_decrypt_t)(const uint8_t *p_key,
+                                                           size_t key_size,
+                                                           psa_algorithm_t alg,
+                                                           psa_key_type_t key_type,
+                                                           const uint8_t *p_input,
+                                                           size_t input_length,
+                                                           const uint8_t *p_salt,
+                                                           size_t salt_length,
+                                                           uint8_t *p_output,
+                                                           size_t output_size,
+                                                           size_t *p_output_length);
 
 /**@}*/
 
diff --git a/include/psa/crypto_entropy_driver.h b/include/psa/crypto_entropy_driver.h
index f5e383e..f596b6b 100644
--- a/include/psa/crypto_entropy_driver.h
+++ b/include/psa/crypto_entropy_driver.h
@@ -40,10 +40,6 @@
  */
 /**@{*/
 
-/** \brief A hardware-specific structure for a entropy providing hardware
- */
-typedef struct psa_drv_entropy_context_s psa_drv_entropy_context_t;
-
 /** \brief Initialize an entropy driver
  *
  *
@@ -53,7 +49,7 @@
  *
  * \retval PSA_SUCCESS
  */
-typedef psa_status_t (*psa_drv_entropy_init_t)(psa_drv_entropy_context_t *p_context);
+typedef psa_status_t (*psa_drv_entropy_init_t)(void *p_context);
 
 /** \brief Get a specified number of bits from the entropy source
  *
@@ -81,7 +77,7 @@
  *
  * \retval PSA_SUCCESS
  */
-typedef psa_status_t (*psa_drv_entropy_get_bits_t)(psa_drv_entropy_context_t *p_context,
+typedef psa_status_t (*psa_drv_entropy_get_bits_t)(void *p_context,
                                                    uint8_t *p_buffer,
                                                    uint32_t buffer_size,
                                                    uint32_t *p_received_entropy_bits);
@@ -96,11 +92,12 @@
  * If one of the functions is not implemented, it should be set to NULL.
  */
 typedef struct {
+    /** The driver-specific size of the entropy context */
+    const size_t                context_size;
     /** Function that performs initialization for the entropy source */
-    psa_drv_entropy_init_t *p_init;
-    /** Function that performs the get_bits operation for the entropy source
-    */
-    psa_drv_entropy_get_bits_t *p_get_bits;
+    psa_drv_entropy_init_t      p_init;
+    /** Function that performs the get_bits operation for the entropy source */
+    psa_drv_entropy_get_bits_t  p_get_bits;
 } psa_drv_entropy_t;
 /**@}*/
 
diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index d14edd9..093355d 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -30,6 +30,8 @@
 #ifndef PSA_CRYPTO_EXTRA_H
 #define PSA_CRYPTO_EXTRA_H
 
+#include "mbedtls/platform_util.h"
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -37,6 +39,29 @@
 /* UID for secure storage seed */
 #define PSA_CRYPTO_ITS_RANDOM_SEED_UID 0xFFFFFF52
 
+/*
+ * Deprecated PSA Crypto error code definitions
+ */
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#define PSA_ERROR_UNKNOWN_ERROR \
+    MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_GENERIC_ERROR )
+#endif
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#define PSA_ERROR_OCCUPIED_SLOT \
+    MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_ALREADY_EXISTS )
+#endif
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#define PSA_ERROR_EMPTY_SLOT \
+    MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_DOES_NOT_EXIST )
+#endif
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#define PSA_ERROR_INSUFFICIENT_CAPACITY \
+    MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( PSA_ERROR_INSUFFICIENT_DATA )
+#endif
+
 /**
  * \brief Library deinitialization.
  *
@@ -89,10 +114,9 @@
  * This is an Mbed TLS extension.
  *
  * \note This function is only available on the following platforms:
- * * If the compile-time options MBEDTLS_ENTROPY_NV_SEED and
- *   MBEDTLS_PSA_HAS_ITS_IO are both enabled. Note that you
- *   must provide compatible implementations of mbedtls_nv_seed_read
- *   and mbedtls_nv_seed_write.
+ * * If the compile-time option MBEDTLS_PSA_INJECT_ENTROPY is enabled.
+ *   Note that you must provide compatible implementations of
+ *   mbedtls_nv_seed_read and mbedtls_nv_seed_write.
  * * In a client-server integration of PSA Cryptography, on the client side,
  *   if the server supports this feature.
  * \param[in] seed          Buffer containing the seed value to inject.
@@ -111,7 +135,6 @@
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  *         \p seed_size is out of range.
  * \retval #PSA_ERROR_STORAGE_FAILURE
- * \retval `PSA_ITS_ERROR_XXX`
  *         There was a failure reading or writing from storage.
  * \retval #PSA_ERROR_NOT_PERMITTED
  *         The library has already been initialized. It is no longer
diff --git a/include/psa/crypto_platform.h b/include/psa/crypto_platform.h
index 50ca546..42cdad3 100644
--- a/include/psa/crypto_platform.h
+++ b/include/psa/crypto_platform.h
@@ -49,4 +49,53 @@
 /* Integral type representing a key handle. */
 typedef uint16_t psa_key_handle_t;
 
+/* This implementation distinguishes *application key identifiers*, which
+ * are the key identifiers specified by the application, from
+ * *key file identifiers*, which are the key identifiers that the library
+ * sees internally. The two types can be different if there is a remote
+ * call layer between the application and the library which supports
+ * multiple client applications that do not have access to each others'
+ * keys. The point of having different types is that the key file
+ * identifier may encode not only the key identifier specified by the
+ * application, but also the the identity of the application.
+ *
+ * Note that this is an internal concept of the library and the remote
+ * call layer. The application itself never sees anything other than
+ * #psa_app_key_id_t with its standard definition.
+ */
+
+/* The application key identifier is always what the application sees as
+ * #psa_key_id_t. */
+typedef uint32_t psa_app_key_id_t;
+
+#if defined(MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER)
+
+#if defined(PSA_CRYPTO_SECURE)
+/* Building for the PSA Crypto service on a PSA platform. */
+/* A key owner is a PSA partition identifier. */
+typedef int32_t psa_key_owner_id_t;
+#endif
+
+typedef struct
+{
+    uint32_t key_id;
+    psa_key_owner_id_t owner;
+} psa_key_file_id_t;
+#define PSA_KEY_FILE_GET_KEY_ID( file_id ) ( ( file_id ).key_id )
+
+/* Since crypto.h is used as part of the PSA Cryptography API specification,
+ * it must use standard types for things like the argument of psa_open_key().
+ * If it wasn't for that constraint, psa_open_key() would take a
+ * `psa_key_file_id_t` argument. As a workaround, make `psa_key_id_t` an
+ * alias for `psa_key_file_id_t` when building for a multi-client service. */
+typedef psa_key_file_id_t psa_key_id_t;
+
+#else /* !MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER */
+
+/* By default, a key file identifier is just the application key identifier. */
+typedef psa_app_key_id_t psa_key_file_id_t;
+#define PSA_KEY_FILE_GET_KEY_ID( id ) ( id )
+
+#endif /* !MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER */
+
 #endif /* PSA_CRYPTO_PLATFORM_H */
diff --git a/include/psa/crypto_se_driver.h b/include/psa/crypto_se_driver.h
index 0578664..5fb7bc3 100644
--- a/include/psa/crypto_se_driver.h
+++ b/include/psa/crypto_se_driver.h
@@ -3,10 +3,10 @@
  * \brief PSA external cryptoprocessor driver module
  *
  * This header declares types and function signatures for cryptography
- * drivers that access key material via opaque references. This is
- * meant for cryptoprocessors that have a separate key storage from the
+ * drivers that access key material via opaque references.
+ * This is meant for cryptoprocessors that have a separate key storage from the
  * space in which the PSA Crypto implementation runs, typically secure
- * elements.
+ * elements (SEs).
  *
  * This file is part of the PSA Crypto Driver Model, containing functions for
  * driver developers to implement to enable hardware to be called in a
@@ -43,27 +43,27 @@
 /** An internal designation of a key slot between the core part of the
  * PSA Crypto implementation and the driver. The meaning of this value
  * is driver-dependent. */
-typedef uint32_t psa_key_slot_t;
+typedef uint32_t psa_key_slot_number_t; // Change this to psa_key_slot_t after psa_key_slot_t is removed from Mbed crypto
 
-/** \defgroup opaque_mac Opaque Message Authentication Code
+/** \defgroup se_mac Secure Element Message Authentication Codes
  * Generation and authentication of Message Authentication Codes (MACs) using
- * opaque keys can be done either as a single function call (via the
- * `psa_drv_mac_opaque_generate_t` or `psa_drv_mac_opaque_verify_t` functions), or in
+ * a secure element can be done either as a single function call (via the
+ * `psa_drv_se_mac_generate_t` or `psa_drv_se_mac_verify_t` functions), or in
  * parts using the following sequence:
- * - `psa_drv_mac_opaque_setup_t`
- * - `psa_drv_mac_opaque_update_t`
- * - `psa_drv_mac_opaque_update_t`
+ * - `psa_drv_se_mac_setup_t`
+ * - `psa_drv_se_mac_update_t`
+ * - `psa_drv_se_mac_update_t`
  * - ...
- * - `psa_drv_mac_opaque_finish_t` or `psa_drv_mac_opaque_finish_verify_t`
+ * - `psa_drv_se_mac_finish_t` or `psa_drv_se_mac_finish_verify_t`
  *
- * If a previously started Opaque MAC operation needs to be terminated, it
- * should be done so by the `psa_drv_mac_opaque_abort_t`. Failure to do so may
+ * If a previously started secure element MAC operation needs to be terminated,
+ * it should be done so by the `psa_drv_se_mac_abort_t`. Failure to do so may
  * result in allocated resources not being freed or in other undefined
  * behavior.
  */
 /**@{*/
-/** \brief A function that starts a MAC operation for a PSA Crypto Driver
- * implementation using an opaque key
+/** \brief A function that starts a secure element  MAC operation for a PSA
+ * Crypto Driver implementation
  *
  * \param[in,out] p_context     A structure that will contain the
  *                              hardware-specific MAC context
@@ -75,26 +75,26 @@
  * \retval  PSA_SUCCESS
  *          Success.
  */
-typedef psa_status_t (*psa_drv_mac_opaque_setup_t)(void *p_context,
-                                                   psa_key_slot_t key_slot,
-                                                   psa_algorithm_t algorithm);
+typedef psa_status_t (*psa_drv_se_mac_setup_t)(void *p_context,
+                                               psa_key_slot_number_t key_slot,
+                                               psa_algorithm_t algorithm);
 
-/** \brief A function that continues a previously started MAC operation using
- * an opaque key
+/** \brief A function that continues a previously started secure element MAC
+ * operation
  *
  * \param[in,out] p_context     A hardware-specific structure for the
  *                              previously-established MAC operation to be
- *                              continued
+ *                              updated
  * \param[in] p_input           A buffer containing the message to be appended
  *                              to the MAC operation
  * \param[in] input_length  The size in bytes of the input message buffer
  */
-typedef psa_status_t (*psa_drv_mac_opaque_update_t)(void *p_context,
-                                                    const uint8_t *p_input,
-                                                    size_t input_length);
+typedef psa_status_t (*psa_drv_se_mac_update_t)(void *p_context,
+                                                const uint8_t *p_input,
+                                                size_t input_length);
 
-/** \brief a function that completes a previously started MAC operation by
- * returning the resulting MAC using an opaque key
+/** \brief a function that completes a previously started secure element MAC
+ * operation by returning the resulting MAC.
  *
  * \param[in,out] p_context     A hardware-specific structure for the
  *                              previously started MAC operation to be
@@ -109,13 +109,13 @@
  * \retval PSA_SUCCESS
  *          Success.
  */
-typedef psa_status_t (*psa_drv_mac_opaque_finish_t)(void *p_context,
-                                                    uint8_t *p_mac,
-                                                    size_t mac_size,
-                                                    size_t *p_mac_length);
+typedef psa_status_t (*psa_drv_se_mac_finish_t)(void *p_context,
+                                                uint8_t *p_mac,
+                                                size_t mac_size,
+                                                size_t *p_mac_length);
 
-/** \brief A function that completes a previously started MAC operation by
- * comparing the resulting MAC against a known value using an opaque key
+/** \brief A function that completes a previously started secure element MAC
+ * operation by comparing the resulting MAC against a provided value
  *
  * \param[in,out] p_context A hardware-specific structure for the previously
  *                          started MAC operation to be fiinished
@@ -130,19 +130,20 @@
  *         The operation completed successfully, but the calculated MAC did
  *         not match the provided MAC
  */
-typedef psa_status_t (*psa_drv_mac_opaque_finish_verify_t)(void *p_context,
-                                                           const uint8_t *p_mac,
-                                                           size_t mac_length);
+typedef psa_status_t (*psa_drv_se_mac_finish_verify_t)(void *p_context,
+                                                       const uint8_t *p_mac,
+                                                       size_t mac_length);
 
-/** \brief A function that aborts a previous started opaque-key MAC operation
-
+/** \brief A function that aborts a previous started secure element MAC
+ * operation
+ *
  * \param[in,out] p_context A hardware-specific structure for the previously
  *                          started MAC operation to be aborted
  */
-typedef psa_status_t (*psa_drv_mac_opaque_abort_t)(void *p_context);
+typedef psa_status_t (*psa_drv_se_mac_abort_t)(void *p_context);
 
-/** \brief A function that performs a MAC operation in one command and returns
- * the calculated MAC using an opaque key
+/** \brief A function that performs a secure element MAC operation in one
+ * command and returns the calculated MAC
  *
  * \param[in] p_input           A buffer containing the message to be MACed
  * \param[in] input_length      The size in bytes of `p_input`
@@ -158,16 +159,16 @@
  * \retval PSA_SUCCESS
  *         Success.
  */
-typedef psa_status_t (*psa_drv_mac_opaque_generate_t)(const uint8_t *p_input,
-                                                      size_t input_length,
-                                                      psa_key_slot_t key_slot,
-                                                      psa_algorithm_t alg,
-                                                      uint8_t *p_mac,
-                                                      size_t mac_size,
-                                                      size_t *p_mac_length);
+typedef psa_status_t (*psa_drv_se_mac_generate_t)(const uint8_t *p_input,
+                                                  size_t input_length,
+                                                  psa_key_slot_number_t key_slot,
+                                                  psa_algorithm_t alg,
+                                                  uint8_t *p_mac,
+                                                  size_t mac_size,
+                                                  size_t *p_mac_length);
 
-/** \brief A function that performs an MAC operation in one command and
- * compare the resulting MAC against a known value using an opaque key
+/** \brief A function that performs a secure element MAC operation in one
+ * command and compares the resulting MAC against a provided value
  *
  * \param[in] p_input       A buffer containing the message to be MACed
  * \param[in] input_length  The size in bytes of `input`
@@ -185,21 +186,21 @@
  *         The operation completed successfully, but the calculated MAC did
  *         not match the provided MAC
  */
-typedef psa_status_t (*psa_drv_mac_opaque_verify_t)(const uint8_t *p_input,
-                                                    size_t input_length,
-                                                    psa_key_slot_t key_slot,
-                                                    psa_algorithm_t alg,
-                                                    const uint8_t *p_mac,
-                                                    size_t mac_length);
+typedef psa_status_t (*psa_drv_se_mac_verify_t)(const uint8_t *p_input,
+                                                size_t input_length,
+                                                psa_key_slot_number_t key_slot,
+                                                psa_algorithm_t alg,
+                                                const uint8_t *p_mac,
+                                                size_t mac_length);
 
 /** \brief A struct containing all of the function pointers needed to
- * implement MAC operations using opaque keys.
+ * perform secure element MAC operations
  *
  * PSA Crypto API implementations should populate the table as appropriate
  * upon startup.
  *
  * If one of the functions is not implemented (such as
- * `psa_drv_mac_opaque_generate_t`), it should be set to NULL.
+ * `psa_drv_se_mac_generate_t`), it should be set to NULL.
  *
  * Driver implementers should ensure that they implement all of the functions
  * that make sense for their hardware, and that they provide a full solution
@@ -208,57 +209,59 @@
  *
  */
 typedef struct {
-    /**The size in bytes of the hardware-specific Opaque-MAC Context structure
+    /**The size in bytes of the hardware-specific secure element MAC context
+     * structure
     */
-    size_t                              context_size;
-    /** Function that performs the setup operation
+    size_t                    context_size;
+    /** Function that performs a MAC setup operation
      */
-    psa_drv_mac_opaque_setup_t          *p_setup;
-    /** Function that performs the update operation
+    psa_drv_se_mac_setup_t          p_setup;
+    /** Function that performs a MAC update operation
      */
-    psa_drv_mac_opaque_update_t         *p_update;
-    /** Function that completes the operation
+    psa_drv_se_mac_update_t         p_update;
+    /** Function that completes a MAC operation
      */
-    psa_drv_mac_opaque_finish_t         *p_finish;
-    /** Function that completed a MAC operation with a verify check
+    psa_drv_se_mac_finish_t         p_finish;
+    /** Function that completes a MAC operation with a verify check
      */
-    psa_drv_mac_opaque_finish_verify_t  *p_finish_verify;
-    /** Function that aborts a previoustly started operation
+    psa_drv_se_mac_finish_verify_t  p_finish_verify;
+    /** Function that aborts a previoustly started MAC operation
      */
-    psa_drv_mac_opaque_abort_t          *p_abort;
-    /** Function that performs the MAC operation in one call
+    psa_drv_se_mac_abort_t          p_abort;
+    /** Function that performs a MAC operation in one call
      */
-    psa_drv_mac_opaque_generate_t       *p_mac;
-    /** Function that performs the MAC and verify operation in one call
+    psa_drv_se_mac_generate_t       p_mac;
+    /** Function that performs a MAC and verify operation in one call
      */
-    psa_drv_mac_opaque_verify_t         *p_mac_verify;
-} psa_drv_mac_opaque_t;
+    psa_drv_se_mac_verify_t         p_mac_verify;
+} psa_drv_se_mac_t;
 /**@}*/
 
-/** \defgroup opaque_cipher Opaque Symmetric Ciphers
+/** \defgroup se_cipher Secure Element Symmetric Ciphers
  *
- * Encryption and Decryption using opaque keys in block modes other than ECB
- * must be done in multiple parts, using the following flow:
- * - `psa_drv_cipher_opaque_setup_t`
- * - `psa_drv_cipher_opaque_set_iv_t` (optional depending upon block mode)
- * - `psa_drv_cipher_opaque_update_t`
+ * Encryption and Decryption using secure element keys in block modes other
+ * than ECB must be done in multiple parts, using the following flow:
+ * - `psa_drv_se_cipher_setup_t`
+ * - `psa_drv_se_cipher_set_iv_t` (optional depending upon block mode)
+ * - `psa_drv_se_cipher_update_t`
+ * - `psa_drv_se_cipher_update_t`
  * - ...
- * - `psa_drv_cipher_opaque_finish_t`
-
- * If a previously started Opaque Cipher operation needs to be terminated, it
- * should be done so by the `psa_drv_cipher_opaque_abort_t`. Failure to do so may
- * result in allocated resources not being freed or in other undefined
- * behavior.
+ * - `psa_drv_se_cipher_finish_t`
+ *
+ * If a previously started secure element Cipher operation needs to be
+ * terminated, it should be done so by the `psa_drv_se_cipher_abort_t`. Failure
+ * to do so may result in allocated resources not being freed or in other
+ * undefined behavior.
  *
  * In situations where a PSA Cryptographic API implementation is using a block
  * mode not-supported by the underlying hardware or driver, it can construct
- * the block mode itself, while calling the `psa_drv_cipher_opaque_ecb_t` function
- * pointer for the cipher operations.
+ * the block mode itself, while calling the `psa_drv_se_cipher_ecb_t` function
+ * for the cipher operations.
  */
 /**@{*/
 
-/** \brief A function pointer that provides the cipher setup function for
- * opaque-key operations
+/** \brief A function that provides the cipher setup function for a
+ * secure element driver
  *
  * \param[in,out] p_context     A structure that will contain the
  *                              hardware-specific cipher context.
@@ -272,16 +275,16 @@
  * \retval PSA_SUCCESS
  * \retval PSA_ERROR_NOT_SUPPORTED
  */
-typedef psa_status_t (*psa_drv_cipher_opaque_setup_t)(void *p_context,
-                                                      psa_key_slot_t key_slot,
-                                                      psa_algorithm_t algorithm,
-                                                      psa_encrypt_or_decrypt_t direction);
+typedef psa_status_t (*psa_drv_se_cipher_setup_t)(void *p_context,
+                                                  psa_key_slot_number_t key_slot,
+                                                  psa_algorithm_t algorithm,
+                                                  psa_encrypt_or_decrypt_t direction);
 
-/** \brief A function pointer that sets the initialization vector (if
- * necessary) for an opaque cipher operation
+/** \brief A function that sets the initialization vector (if
+ * necessary) for an secure element cipher operation
  *
- * Rationale: The `psa_cipher_*` function in the PSA Cryptographic API has two
- * IV functions: one to set the IV, and one to generate it internally. The
+ * Rationale: The `psa_se_cipher_*` operation in the PSA Cryptographic API has
+ * two IV functions: one to set the IV, and one to generate it internally. The
  * generate function is not necessary for the drivers to implement as the PSA
  * Crypto implementation can do the generation using its RNG features.
  *
@@ -292,11 +295,11 @@
  *
  * \retval PSA_SUCCESS
  */
-typedef psa_status_t (*psa_drv_cipher_opaque_set_iv_t)(void *p_context,
-                                                       const uint8_t *p_iv,
-                                                       size_t iv_length);
+typedef psa_status_t (*psa_drv_se_cipher_set_iv_t)(void *p_context,
+                                                   const uint8_t *p_iv,
+                                                   size_t iv_length);
 
-/** \brief A function that continues a previously started opaque-key cipher
+/** \brief A function that continues a previously started secure element cipher
  * operation
  *
  * \param[in,out] p_context         A hardware-specific structure for the
@@ -314,14 +317,14 @@
  *
  * \retval PSA_SUCCESS
  */
-typedef psa_status_t (*psa_drv_cipher_opaque_update_t)(void *p_context,
-                                                       const uint8_t *p_input,
-                                                       size_t input_size,
-                                                       uint8_t *p_output,
-                                                       size_t output_size,
-                                                       size_t *p_output_length);
+typedef psa_status_t (*psa_drv_se_cipher_update_t)(void *p_context,
+                                                   const uint8_t *p_input,
+                                                   size_t input_size,
+                                                   uint8_t *p_output,
+                                                   size_t output_size,
+                                                   size_t *p_output_length);
 
-/** \brief A function that completes a previously started opaque-key cipher
+/** \brief A function that completes a previously started secure element cipher
  * operation
  *
  * \param[in,out] p_context     A hardware-specific structure for the
@@ -335,21 +338,21 @@
  *
  * \retval PSA_SUCCESS
  */
-typedef psa_status_t (*psa_drv_cipher_opaque_finish_t)(void *p_context,
-                                                       uint8_t *p_output,
-                                                       size_t output_size,
-                                                       size_t *p_output_length);
+typedef psa_status_t (*psa_drv_se_cipher_finish_t)(void *p_context,
+                                                   uint8_t *p_output,
+                                                   size_t output_size,
+                                                   size_t *p_output_length);
 
-/** \brief A function that aborts a previously started opaque-key cipher
+/** \brief A function that aborts a previously started secure element cipher
  * operation
  *
  * \param[in,out] p_context     A hardware-specific structure for the
  *                              previously started cipher operation
  */
-typedef psa_status_t (*psa_drv_cipher_opaque_abort_t)(void *p_context);
+typedef psa_status_t (*psa_drv_se_cipher_abort_t)(void *p_context);
 
-/** \brief A function that performs the ECB block mode for opaque-key cipher
- * operations
+/** \brief A function that performs the ECB block mode for secure element
+ * cipher operations
  *
  * Note: this function should only be used with implementations that do not
  * provide a needed higher-level operation.
@@ -370,58 +373,59 @@
  * \retval PSA_SUCCESS
  * \retval PSA_ERROR_NOT_SUPPORTED
  */
-typedef psa_status_t (*psa_drv_cipher_opaque_ecb_t)(psa_key_slot_t key_slot,
-                                                    psa_algorithm_t algorithm,
-                                                    psa_encrypt_or_decrypt_t direction,
-                                                    const uint8_t *p_input,
-                                                    size_t input_size,
-                                                    uint8_t *p_output,
-                                                    size_t output_size);
+typedef psa_status_t (*psa_drv_se_cipher_ecb_t)(psa_key_slot_number_t key_slot,
+                                                psa_algorithm_t algorithm,
+                                                psa_encrypt_or_decrypt_t direction,
+                                                const uint8_t *p_input,
+                                                size_t input_size,
+                                                uint8_t *p_output,
+                                                size_t output_size);
 
 /**
  * \brief A struct containing all of the function pointers needed to implement
- * cipher operations using opaque keys.
+ * cipher operations using secure elements.
  *
  * PSA Crypto API implementations should populate instances of the table as
- * appropriate upon startup.
+ * appropriate upon startup or at build time.
  *
  * If one of the functions is not implemented (such as
- * `psa_drv_cipher_opaque_ecb_t`), it should be set to NULL.
+ * `psa_drv_se_cipher_ecb_t`), it should be set to NULL.
  */
 typedef struct {
-    /** The size in bytes of the hardware-specific Opaque Cipher context
-     * structure
+    /** The size in bytes of the hardware-specific secure element cipher
+     * context structure
      */
-    size_t                         size;
-    /** Function that performs the setup operation */
-    psa_drv_cipher_opaque_setup_t  *p_setup;
-    /** Function that sets the IV (if necessary) */
-    psa_drv_cipher_opaque_set_iv_t *p_set_iv;
-    /** Function that performs the update operation */
-    psa_drv_cipher_opaque_update_t *p_update;
-    /** Function that completes the operation */
-    psa_drv_cipher_opaque_finish_t *p_finish;
-    /** Function that aborts the operation */
-    psa_drv_cipher_opaque_abort_t  *p_abort;
-    /** Function that performs ECB mode for the cipher
+    size_t               context_size;
+    /** Function that performs a cipher setup operation */
+    psa_drv_se_cipher_setup_t  p_setup;
+    /** Function that sets a cipher IV (if necessary) */
+    psa_drv_se_cipher_set_iv_t p_set_iv;
+    /** Function that performs a cipher update operation */
+    psa_drv_se_cipher_update_t p_update;
+    /** Function that completes a cipher operation */
+    psa_drv_se_cipher_finish_t p_finish;
+    /** Function that aborts a cipher operation */
+    psa_drv_se_cipher_abort_t  p_abort;
+    /** Function that performs ECB mode for a cipher operation
      * (Danger: ECB mode should not be used directly by clients of the PSA
      * Crypto Client API)
      */
-    psa_drv_cipher_opaque_ecb_t    *p_ecb;
-} psa_drv_cipher_opaque_t;
+    psa_drv_se_cipher_ecb_t    p_ecb;
+} psa_drv_se_cipher_t;
 
 /**@}*/
 
-/** \defgroup opaque_asymmetric Opaque Asymmetric Cryptography
+/** \defgroup se_asymmetric Secure Element Asymmetric Cryptography
  *
  * Since the amount of data that can (or should) be encrypted or signed using
  * asymmetric keys is limited by the key size, asymmetric key operations using
- * opaque keys must be done in single function calls.
+ * keys in a secure element must be done in single function calls.
  */
 /**@{*/
 
 /**
- * \brief A function that signs a hash or short message with a private key
+ * \brief A function that signs a hash or short message with a private key in
+ * a secure element
  *
  * \param[in] key_slot              Key slot of an asymmetric key pair
  * \param[in] alg                   A signature algorithm that is compatible
@@ -435,17 +439,17 @@
  *
  * \retval PSA_SUCCESS
  */
-typedef psa_status_t (*psa_drv_asymmetric_opaque_sign_t)(psa_key_slot_t key_slot,
-                                                         psa_algorithm_t alg,
-                                                         const uint8_t *p_hash,
-                                                         size_t hash_length,
-                                                         uint8_t *p_signature,
-                                                         size_t signature_size,
-                                                         size_t *p_signature_length);
+typedef psa_status_t (*psa_drv_se_asymmetric_sign_t)(psa_key_slot_number_t key_slot,
+                                                     psa_algorithm_t alg,
+                                                     const uint8_t *p_hash,
+                                                     size_t hash_length,
+                                                     uint8_t *p_signature,
+                                                     size_t signature_size,
+                                                     size_t *p_signature_length);
 
 /**
  * \brief A function that verifies the signature a hash or short message using
- * an asymmetric public key
+ * an asymmetric public key in a secure element
  *
  * \param[in] key_slot          Key slot of a public key or an asymmetric key
  *                              pair
@@ -459,16 +463,16 @@
  * \retval PSA_SUCCESS
  *         The signature is valid.
  */
-typedef psa_status_t (*psa_drv_asymmetric_opaque_verify_t)(psa_key_slot_t key_slot,
-                                                           psa_algorithm_t alg,
-                                                           const uint8_t *p_hash,
-                                                           size_t hash_length,
-                                                           const uint8_t *p_signature,
-                                                           size_t signature_length);
+typedef psa_status_t (*psa_drv_se_asymmetric_verify_t)(psa_key_slot_number_t key_slot,
+                                                       psa_algorithm_t alg,
+                                                       const uint8_t *p_hash,
+                                                       size_t hash_length,
+                                                       const uint8_t *p_signature,
+                                                       size_t signature_length);
 
 /**
  * \brief A function that encrypts a short message with an asymmetric public
- * key
+ * key in a secure element
  *
  * \param[in] key_slot          Key slot of a public key or an asymmetric key
  *                              pair
@@ -495,18 +499,19 @@
  *
  * \retval PSA_SUCCESS
  */
-typedef psa_status_t (*psa_drv_asymmetric_opaque_encrypt_t)(psa_key_slot_t key_slot,
-                                                            psa_algorithm_t alg,
-                                                            const uint8_t *p_input,
-                                                            size_t input_length,
-                                                            const uint8_t *p_salt,
-                                                            size_t salt_length,
-                                                            uint8_t *p_output,
-                                                            size_t output_size,
-                                                            size_t *p_output_length);
+typedef psa_status_t (*psa_drv_se_asymmetric_encrypt_t)(psa_key_slot_number_t key_slot,
+                                                        psa_algorithm_t alg,
+                                                        const uint8_t *p_input,
+                                                        size_t input_length,
+                                                        const uint8_t *p_salt,
+                                                        size_t salt_length,
+                                                        uint8_t *p_output,
+                                                        size_t output_size,
+                                                        size_t *p_output_length);
 
 /**
- * \brief Decrypt a short message with an asymmetric private key.
+ * \brief A function that decrypts a short message with an asymmetric private
+ * key in a secure element.
  *
  * \param[in] key_slot          Key slot of an asymmetric key pair
  * \param[in] alg               An asymmetric encryption algorithm that is
@@ -532,48 +537,49 @@
  *
  * \retval PSA_SUCCESS
  */
-typedef psa_status_t (*psa_drv_asymmetric_opaque_decrypt_t)(psa_key_slot_t key_slot,
-                                                            psa_algorithm_t alg,
-                                                            const uint8_t *p_input,
-                                                            size_t input_length,
-                                                            const uint8_t *p_salt,
-                                                            size_t salt_length,
-                                                            uint8_t *p_output,
-                                                            size_t output_size,
-                                                            size_t *p_output_length);
+typedef psa_status_t (*psa_drv_se_asymmetric_decrypt_t)(psa_key_slot_number_t key_slot,
+                                                        psa_algorithm_t alg,
+                                                        const uint8_t *p_input,
+                                                        size_t input_length,
+                                                        const uint8_t *p_salt,
+                                                        size_t salt_length,
+                                                        uint8_t *p_output,
+                                                        size_t output_size,
+                                                        size_t *p_output_length);
 
 /**
  * \brief A struct containing all of the function pointers needed to implement
- * asymmetric cryptographic operations using opaque keys.
+ * asymmetric cryptographic operations using secure elements.
  *
  * PSA Crypto API implementations should populate instances of the table as
- * appropriate upon startup.
+ * appropriate upon startup or at build time.
  *
  * If one of the functions is not implemented, it should be set to NULL.
  */
 typedef struct {
-    /** Function that performs the asymmetric sign operation */
-    psa_drv_asymmetric_opaque_sign_t    *p_sign;
-    /** Function that performs the asymmetric verify operation */
-    psa_drv_asymmetric_opaque_verify_t  *p_verify;
-    /** Function that performs the asymmetric encrypt operation */
-    psa_drv_asymmetric_opaque_encrypt_t *p_encrypt;
-    /** Function that performs the asymmetric decrypt operation */
-    psa_drv_asymmetric_opaque_decrypt_t *p_decrypt;
-} psa_drv_asymmetric_opaque_t;
+    /** Function that performs an asymmetric sign operation */
+    psa_drv_se_asymmetric_sign_t    p_sign;
+    /** Function that performs an asymmetric verify operation */
+    psa_drv_se_asymmetric_verify_t  p_verify;
+    /** Function that performs an asymmetric encrypt operation */
+    psa_drv_se_asymmetric_encrypt_t p_encrypt;
+    /** Function that performs an asymmetric decrypt operation */
+    psa_drv_se_asymmetric_decrypt_t p_decrypt;
+} psa_drv_se_asymmetric_t;
 
 /**@}*/
 
-/** \defgroup aead_opaque AEAD Opaque
- * Authenticated Encryption with Additional Data (AEAD) operations with opaque
- * keys must be done in one function call. While this creates a burden for
+/** \defgroup se_aead Secure Element Authenticated Encryption with Additional Data
+ * Authenticated Encryption with Additional Data (AEAD) operations with secure
+ * elements must be done in one function call. While this creates a burden for
  * implementers as there must be sufficient space in memory for the entire
  * message, it prevents decrypted data from being made available before the
  * authentication operation is complete and the data is known to be authentic.
  */
 /**@{*/
 
-/** \brief Process an authenticated encryption operation using an opaque key
+/** \brief A function that performs a secure element authenticated encryption
+ * operation
  *
  * \param[in] key_slot                  Slot containing the key to use.
  * \param[in] algorithm                 The AEAD algorithm to compute
@@ -602,19 +608,19 @@
  * \retval #PSA_SUCCESS
  *         Success.
  */
-typedef psa_status_t (*psa_drv_aead_opaque_encrypt_t)(psa_key_slot_t key_slot,
-                                                      psa_algorithm_t algorithm,
-                                                      const uint8_t *p_nonce,
-                                                      size_t nonce_length,
-                                                      const uint8_t *p_additional_data,
-                                                      size_t additional_data_length,
-                                                      const uint8_t *p_plaintext,
-                                                      size_t plaintext_length,
-                                                      uint8_t *p_ciphertext,
-                                                      size_t ciphertext_size,
-                                                      size_t *p_ciphertext_length);
+typedef psa_status_t (*psa_drv_se_aead_encrypt_t)(psa_key_slot_number_t key_slot,
+                                                  psa_algorithm_t algorithm,
+                                                  const uint8_t *p_nonce,
+                                                  size_t nonce_length,
+                                                  const uint8_t *p_additional_data,
+                                                  size_t additional_data_length,
+                                                  const uint8_t *p_plaintext,
+                                                  size_t plaintext_length,
+                                                  uint8_t *p_ciphertext,
+                                                  size_t ciphertext_size,
+                                                  size_t *p_ciphertext_length);
 
-/** Process an authenticated decryption operation using an opaque key
+/** A function that peforms a secure element authenticated decryption operation
  *
  * \param[in] key_slot                  Slot containing the key to use
  * \param[in] algorithm                 The AEAD algorithm to compute
@@ -642,21 +648,21 @@
  * \retval #PSA_SUCCESS
  *         Success.
  */
-typedef psa_status_t (*psa_drv_aead_opaque_decrypt_t)(psa_key_slot_t key_slot,
-                                                      psa_algorithm_t algorithm,
-                                                      const uint8_t *p_nonce,
-                                                      size_t nonce_length,
-                                                      const uint8_t *p_additional_data,
-                                                      size_t additional_data_length,
-                                                      const uint8_t *p_ciphertext,
-                                                      size_t ciphertext_length,
-                                                      uint8_t *p_plaintext,
-                                                      size_t plaintext_size,
-                                                      size_t *p_plaintext_length);
+typedef psa_status_t (*psa_drv_se_aead_decrypt_t)(psa_key_slot_number_t key_slot,
+                                                  psa_algorithm_t algorithm,
+                                                  const uint8_t *p_nonce,
+                                                  size_t nonce_length,
+                                                  const uint8_t *p_additional_data,
+                                                  size_t additional_data_length,
+                                                  const uint8_t *p_ciphertext,
+                                                  size_t ciphertext_length,
+                                                  uint8_t *p_plaintext,
+                                                  size_t plaintext_size,
+                                                  size_t *p_plaintext_length);
 
 /**
  * \brief A struct containing all of the function pointers needed to implement
- * Authenticated Encryption with Additional Data operations using opaque keys
+ * secure element Authenticated Encryption with Additional Data operations
  *
  * PSA Crypto API implementations should populate instances of the table as
  * appropriate upon startup.
@@ -665,13 +671,13 @@
  */
 typedef struct {
     /** Function that performs the AEAD encrypt operation */
-    psa_drv_aead_opaque_encrypt_t *p_encrypt;
+    psa_drv_se_aead_encrypt_t p_encrypt;
     /** Function that performs the AEAD decrypt operation */
-    psa_drv_aead_opaque_decrypt_t *p_decrypt;
-} psa_drv_aead_opaque_t;
+    psa_drv_se_aead_decrypt_t p_decrypt;
+} psa_drv_se_aead_t;
 /**@}*/
 
-/** \defgroup driver_key_management Key Management
+/** \defgroup se_key_management Secure Element Key Management
  * Currently, key management is limited to importing keys in the clear,
  * destroying keys, and exporting keys in the clear.
  * Whether a key may be exported is determined by the key policies in place
@@ -679,7 +685,7 @@
  */
 /**@{*/
 
-/** \brief Import a key in binary format
+/** \brief A function that imports a key into a secure element in binary format
  *
  * This function can support any output from psa_export_key(). Refer to the
  * documentation of psa_export_key() for the format for each key type.
@@ -687,6 +693,7 @@
  * \param[in] key_slot      Slot where the key will be stored
  *                          This must be a valid slot for a key of the chosen
  *                          type. It must be unoccupied.
+ * \param[in] lifetime      The required lifetime of the key storage
  * \param[in] type          Key type (a \c PSA_KEY_TYPE_XXX value)
  * \param[in] algorithm     Key algorithm (a \c PSA_ALG_XXX value)
  * \param[in] usage         The allowed uses of the key
@@ -696,33 +703,33 @@
  * \retval #PSA_SUCCESS
  *         Success.
  */
-typedef psa_status_t (*psa_drv_opaque_import_key_t)(psa_key_slot_t key_slot,
-                                                    psa_key_type_t type,
-                                                    psa_algorithm_t algorithm,
-                                                    psa_key_usage_t usage,
-                                                    const uint8_t *p_data,
-                                                    size_t data_length);
+typedef psa_status_t (*psa_drv_se_import_key_t)(psa_key_slot_number_t key_slot,
+                                                psa_key_lifetime_t lifetime,
+                                                psa_key_type_t type,
+                                                psa_algorithm_t algorithm,
+                                                psa_key_usage_t usage,
+                                                const uint8_t *p_data,
+                                                size_t data_length);
 
 /**
- * \brief Destroy a key and restore the slot to its default state
+ * \brief A function that destroys a secure element key and restore the slot to
+ * its default state
  *
- * This function destroys the content of the key slot from both volatile
- * memory and, if applicable, non-volatile storage. Implementations shall
- * make a best effort to ensure that any previous content of the slot is
- * unrecoverable.
+ * This function destroys the content of the key from a secure element.
+ * Implementations shall make a best effort to ensure that any previous content
+ * of the slot is unrecoverable.
  *
- * This function also erases any metadata such as policies. It returns the
- * specified slot to its default state.
+ * This function returns the specified slot to its default state.
  *
  * \param[in] key_slot        The key slot to erase.
  *
  * \retval #PSA_SUCCESS
  *         The slot's content, if any, has been erased.
  */
-typedef psa_status_t (*psa_drv_destroy_key_t)(psa_key_slot_t key);
+typedef psa_status_t (*psa_drv_se_destroy_key_t)(psa_key_slot_number_t key);
 
 /**
- * \brief Export a key in binary format
+ * \brief A function that exports a secure element key in binary format
  *
  * The output of this function can be passed to psa_import_key() to
  * create an equivalent object.
@@ -732,19 +739,9 @@
  * identical: the implementation may choose a different representation
  * of the same key if the format permits it.
  *
- * For standard key types, the output format is as follows:
- *
- * - For symmetric keys (including MAC keys), the format is the
- *   raw bytes of the key.
- * - For DES, the key data consists of 8 bytes. The parity bits must be
- *   correct.
- * - For Triple-DES, the format is the concatenation of the
- *   two or three DES keys.
- * - For RSA key pairs (#PSA_KEY_TYPE_RSA_KEYPAIR), the format
- *   is the non-encrypted DER representation defined by PKCS\#1 (RFC 8017)
- *   as RSAPrivateKey.
- * - For RSA public keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY), the format
- *   is the DER representation defined by RFC 5280 as SubjectPublicKeyInfo.
+ * This function should generate output in the same format that
+ * `psa_export_key()` does. Refer to the
+ * documentation of `psa_export_key()` for the format for each key type.
  *
  * \param[in] key               Slot whose content is to be exported. This must
  *                              be an occupied key slot.
@@ -754,67 +751,79 @@
  *                              that make up the key data.
  *
  * \retval #PSA_SUCCESS
- * \retval #PSA_ERROR_EMPTY_SLOT
+ * \retval #PSA_ERROR_DOES_NOT_EXIST
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_NOT_SUPPORTED
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_TAMPERING_DETECTED
  */
-typedef psa_status_t (*psa_drv_export_key_t)(psa_key_slot_t key,
-                                             uint8_t *p_data,
-                                             size_t data_size,
-                                             size_t *p_data_length);
+typedef psa_status_t (*psa_drv_se_export_key_t)(psa_key_slot_number_t key,
+                                                uint8_t *p_data,
+                                                size_t data_size,
+                                                size_t *p_data_length);
 
 /**
- * \brief Export a public key or the public part of a key pair in binary format
+ * \brief A function that generates a symmetric or asymmetric key on a secure
+ * element
  *
- * The output of this function can be passed to psa_import_key() to
- * create an object that is equivalent to the public key.
+ * If \p type is asymmetric (`#PSA_KEY_TYPE_IS_ASYMMETRIC(\p type) == 1`),
+ * the public component of the generated key will be placed in `p_pubkey_out`.
+ * The format of the public key information will match the format specified for
+ * the psa_export_key() function for the key type.
  *
- * For standard key types, the output format is as follows:
- *
- * - For RSA keys (#PSA_KEY_TYPE_RSA_KEYPAIR or #PSA_KEY_TYPE_RSA_PUBLIC_KEY),
- *   the format is the DER representation of the public key defined by RFC 5280
- *   as SubjectPublicKeyInfo.
- *
- * \param[in] key_slot          Slot whose content is to be exported. This must
- *                              be an occupied key slot.
- * \param[out] p_data           Buffer where the key data is to be written.
- * \param[in] data_size         Size of the `data` buffer in bytes.
- * \param[out] p_data_length    On success, the number of bytes
- *                              that make up the key data.
- *
- * \retval #PSA_SUCCESS
+ * \param[in] key_slot      Slot where the generated key will be placed
+ * \param[in] type          The type of the key to be generated
+ * \param[in] usage         The prescribed usage of the generated key
+ *                          Note: Not all Secure Elements support the same
+ *                          restrictions that PSA Crypto does (and vice versa).
+ *                          Driver developers should endeavor to match the
+ *                          usages as close as possible.
+ * \param[in] bits          The size in bits of the key to be generated.
+ * \param[in] extra         Extra parameters for key generation. The
+ *                          interpretation of this parameter should match the
+ *                          interpretation in the `extra` parameter is the
+ *                          `psa_generate_key` function
+ * \param[in] extra_size    The size in bytes of the \p extra buffer
+ * \param[out] p_pubkey_out The buffer where the public key information will
+ *                          be placed
+ * \param[in] pubkey_out_size   The size in bytes of the `p_pubkey_out` buffer
+ * \param[out] p_pubkey_length  Upon successful completion, will contain the
+ *                              size of the data placed in `p_pubkey_out`.
  */
-typedef psa_status_t (*psa_drv_export_public_key_t)(psa_key_slot_t key,
-                                                    uint8_t *p_data,
-                                                    size_t data_size,
-                                                    size_t *p_data_length);
+typedef psa_status_t (*psa_drv_se_generate_key_t)(psa_key_slot_number_t key_slot,
+                                                  psa_key_type_t type,
+                                                  psa_key_usage_t usage,
+                                                  size_t bits,
+                                                  const void *extra,
+                                                  size_t extra_size,
+                                                  uint8_t *p_pubkey_out,
+                                                  size_t pubkey_out_size,
+                                                  size_t *p_pubkey_length);
 
 /**
- * \brief A struct containing all of the function pointers needed to for key
- * management using opaque keys
+ * \brief A struct containing all of the function pointers needed to for secure
+ * element key management
  *
  * PSA Crypto API implementations should populate instances of the table as
- * appropriate upon startup.
+ * appropriate upon startup or at build time.
  *
  * If one of the functions is not implemented, it should be set to NULL.
  */
 typedef struct {
-    /** Function that performs the key import operation */
-    psa_drv_opaque_import_key_t *p_import;
-    /** Function that performs the key destroy operation */
-    psa_drv_destroy_key_t       *p_destroy;
-    /** Function that performs the key export operation */
-    psa_drv_export_key_t        *p_export;
-    /** Function that perforsm the public key export operation */
-    psa_drv_export_public_key_t *p_export_public;
-} psa_drv_key_management_t;
+    /** Function that performs a key import operation */
+    psa_drv_se_import_key_t     p_import;
+    /** Function that performs a generation */
+    psa_drv_se_generate_key_t   p_generate;
+    /** Function that performs a key destroy operation */
+    psa_drv_se_destroy_key_t    p_destroy;
+    /** Function that performs a key export operation */
+    psa_drv_se_export_key_t     p_export;
+} psa_drv_se_key_management_t;
 
 /**@}*/
 
-/** \defgroup driver_derivation Key Derivation and Agreement
+/** \defgroup driver_derivation Secure Element Key Derivation and Agreement
  * Key derivation is the process of generating new key material using an
  * existing key and additional parameters, iterating through a basic
  * cryptographic function, such as a hash.
@@ -825,53 +834,46 @@
  * for both of the flows.
  *
  * There are two different final functions for the flows,
- * `psa_drv_key_derivation_derive` and `psa_drv_key_derivation_export`.
- * `psa_drv_key_derivation_derive` is used when the key material should be placed
- * in a slot on the hardware and not exposed to the caller.
- * `psa_drv_key_derivation_export` is used when the key material should be returned
- * to the PSA Cryptographic API implementation.
+ * `psa_drv_se_key_derivation_derive` and `psa_drv_se_key_derivation_export`.
+ * `psa_drv_se_key_derivation_derive` is used when the key material should be
+ * placed in a slot on the hardware and not exposed to the caller.
+ * `psa_drv_se_key_derivation_export` is used when the key material should be
+ * returned to the PSA Cryptographic API implementation.
  *
  * Different key derivation algorithms require a different number of inputs.
  * Instead of having an API that takes as input variable length arrays, which
  * can be problemmatic to manage on embedded platforms, the inputs are passed
- * to the driver via a function, `psa_drv_key_derivation_collateral`, that is
- * called multiple times with different `collateral_id`s. Thus, for a key
+ * to the driver via a function, `psa_drv_se_key_derivation_collateral`, that
+ * is called multiple times with different `collateral_id`s. Thus, for a key
  * derivation algorithm that required 3 paramter inputs, the flow would look
  * something like:
  * ~~~~~~~~~~~~~{.c}
- * psa_drv_key_derivation_setup(kdf_algorithm, source_key, dest_key_size_bytes);
- * psa_drv_key_derivation_collateral(kdf_algorithm_collateral_id_0,
- *                                   p_collateral_0,
- *                                   collateral_0_size);
- * psa_drv_key_derivation_collateral(kdf_algorithm_collateral_id_1,
- *                                   p_collateral_1,
- *                                   collateral_1_size);
- * psa_drv_key_derivation_collateral(kdf_algorithm_collateral_id_2,
- *                                   p_collateral_2,
- *                                   collateral_2_size);
- * psa_drv_key_derivation_derive();
+ * psa_drv_se_key_derivation_setup(kdf_algorithm, source_key, dest_key_size_bytes);
+ * psa_drv_se_key_derivation_collateral(kdf_algorithm_collateral_id_0,
+ *                                      p_collateral_0,
+ *                                      collateral_0_size);
+ * psa_drv_se_key_derivation_collateral(kdf_algorithm_collateral_id_1,
+ *                                      p_collateral_1,
+ *                                      collateral_1_size);
+ * psa_drv_se_key_derivation_collateral(kdf_algorithm_collateral_id_2,
+ *                                      p_collateral_2,
+ *                                      collateral_2_size);
+ * psa_drv_se_key_derivation_derive();
  * ~~~~~~~~~~~~~
  *
  * key agreement example:
  * ~~~~~~~~~~~~~{.c}
- * psa_drv_key_derivation_setup(alg, source_key. dest_key_size_bytes);
- * psa_drv_key_derivation_collateral(DHE_PUBKEY, p_pubkey, pubkey_size);
- * psa_drv_key_derivation_export(p_session_key,
- *                               session_key_size,
- *                               &session_key_length);
+ * psa_drv_se_key_derivation_setup(alg, source_key. dest_key_size_bytes);
+ * psa_drv_se_key_derivation_collateral(DHE_PUBKEY, p_pubkey, pubkey_size);
+ * psa_drv_se_key_derivation_export(p_session_key,
+ *                                  session_key_size,
+ *                                  &session_key_length);
  * ~~~~~~~~~~~~~
  */
 /**@{*/
 
-/** \brief The hardware-specific key derivation context structure
- *
- * The contents of this structure are implementation dependent and are
- * therefore not described here
- */
-typedef struct psa_drv_key_derivation_context_s psa_drv_key_derivation_context_t;
-
-/** \brief Set up a key derivation operation by specifying the algorithm and
- * the source key sot
+/** \brief A function that Sets up a secure element key derivation operation by
+ * specifying the algorithm and the source key sot
  *
  * \param[in,out] p_context A hardware-specific structure containing any
  *                          context information for the implementation
@@ -881,12 +883,12 @@
  *
  * \retval PSA_SUCCESS
  */
-typedef psa_status_t (*psa_drv_key_derivation_setup_t)(psa_drv_key_derivation_context_t *p_context,
-                                                       psa_algorithm_t kdf_alg,
-                                                       psa_key_slot_t source_key);
+typedef psa_status_t (*psa_drv_se_key_derivation_setup_t)(void *p_context,
+                                                          psa_algorithm_t kdf_alg,
+                                                          psa_key_slot_number_t source_key);
 
-/** \brief Provide collateral (parameters) needed for a key derivation or key
- * agreement operation
+/** \brief A function that provides collateral (parameters) needed for a secure
+ * element key derivation or key agreement operation
  *
  * Since many key derivation algorithms require multiple parameters, it is
  * expeced that this function may be called multiple times for the same
@@ -900,13 +902,14 @@
  *
  * \retval PSA_SUCCESS
  */
-typedef psa_status_t (*psa_drv_key_derivation_collateral_t)(psa_drv_key_derivation_context_t *p_context,
-                                                            uint32_t collateral_id,
-                                                            const uint8_t *p_collateral,
-                                                            size_t collateral_size);
+typedef psa_status_t (*psa_drv_se_key_derivation_collateral_t)(void *p_context,
+                                                               uint32_t collateral_id,
+                                                               const uint8_t *p_collateral,
+                                                               size_t collateral_size);
 
-/** \brief Perform the final key derivation step and place the generated key
- * material in a slot
+/** \brief A function that performs the final secure element key derivation
+ * step and place the generated key material in a slot
+ *
  * \param[in,out] p_context     A hardware-specific structure containing any
  *                              context information for the implementation
  * \param[in] dest_key          The slot where the generated key material
@@ -914,11 +917,11 @@
  *
  * \retval PSA_SUCCESS
  */
-typedef psa_status_t (*psa_drv_key_derivation_derive_t)(psa_drv_key_derivation_context_t *p_context,
-                                                        psa_key_slot_t dest_key);
+typedef psa_status_t (*psa_drv_se_key_derivation_derive_t)(void *p_context,
+                                                          psa_key_slot_number_t dest_key);
 
-/** \brief Perform the final step of a key agreement and place the generated
- * key material in a buffer
+/** \brief A function that performs the final step of a secure element key
+ * agreement and place the generated key material in a buffer
  *
  * \param[out] p_output         Buffer in which to place the generated key
  *                              material
@@ -928,13 +931,14 @@
  *
  * \retval PSA_SUCCESS
  */
-typedef psa_status_t (*psa_drv_key_derivation_export_t)(uint8_t *p_output,
-                                                        size_t output_size,
-                                                        size_t *p_output_length);
+typedef psa_status_t (*psa_drv_se_key_derivation_export_t)(void *p_context,
+                                                           uint8_t *p_output,
+                                                           size_t output_size,
+                                                           size_t *p_output_length);
 
 /**
- * \brief A struct containing all of the function pointers needed to for key
- * derivation and agreement
+ * \brief A struct containing all of the function pointers needed to for secure
+ * element key derivation and agreement
  *
  * PSA Crypto API implementations should populate instances of the table as
  * appropriate upon startup.
@@ -942,16 +946,18 @@
  * If one of the functions is not implemented, it should be set to NULL.
  */
 typedef struct {
-    /** Function that performs the key derivation setup */
-    psa_drv_key_derivation_setup_t      *p_setup;
-    /** Function that sets the key derivation collateral */
-    psa_drv_key_derivation_collateral_t *p_collateral;
-    /** Function that performs the final key derivation step */
-    psa_drv_key_derivation_derive_t     *p_derive;
-    /** Function that perforsm the final key derivation or agreement and
+    /** The driver-specific size of the key derivation context */
+    size_t                           context_size;
+    /** Function that performs a key derivation setup */
+    psa_drv_se_key_derivation_setup_t      p_setup;
+    /** Function that sets key derivation collateral */
+    psa_drv_se_key_derivation_collateral_t p_collateral;
+    /** Function that performs a final key derivation step */
+    psa_drv_se_key_derivation_derive_t     p_derive;
+    /** Function that perforsm a final key derivation or agreement and
      * exports the key */
-    psa_drv_key_derivation_export_t     *p_export;
-} psa_drv_key_derivation_t;
+    psa_drv_se_key_derivation_export_t     p_export;
+} psa_drv_se_key_derivation_t;
 
 /**@}*/
 
diff --git a/include/psa/crypto_sizes.h b/include/psa/crypto_sizes.h
index e1ac630..3c879e8 100644
--- a/include/psa/crypto_sizes.h
+++ b/include/psa/crypto_sizes.h
@@ -313,9 +313,9 @@
      (plaintext_length) - PSA_AEAD_TAG_LENGTH(alg) :              \
      0)
 
-#define PSA_RSA_MINIMUM_PADDING_SIZE(alg)                               \
-    (PSA_ALG_IS_RSA_OAEP(alg) ?                                         \
-     2 * PSA_HASH_FINAL_SIZE(PSA_ALG_RSA_OAEP_GET_HASH(alg)) + 1 :      \
+#define PSA_RSA_MINIMUM_PADDING_SIZE(alg)                         \
+    (PSA_ALG_IS_RSA_OAEP(alg) ?                                   \
+     2 * PSA_HASH_SIZE(PSA_ALG_RSA_OAEP_GET_HASH(alg)) + 1 :      \
      11 /*PKCS#1v1.5*/)
 
 /**
@@ -438,25 +438,16 @@
 /* Maximum size of the export encoding of an RSA public key.
  * Assumes that the public exponent is less than 2^32.
  *
- * SubjectPublicKeyInfo  ::=  SEQUENCE  {
- *      algorithm            AlgorithmIdentifier,
- *      subjectPublicKey     BIT STRING  } -- contains RSAPublicKey
- * AlgorithmIdentifier  ::=  SEQUENCE  {
- *      algorithm               OBJECT IDENTIFIER,
- *      parameters              NULL  }
  * RSAPublicKey  ::=  SEQUENCE  {
  *    modulus            INTEGER,    -- n
  *    publicExponent     INTEGER  }  -- e
  *
- * - 3 * 4 bytes of SEQUENCE overhead;
- * - 1 + 1 + 9 bytes of algorithm (RSA OID);
- * - 2 bytes of NULL;
- * - 4 bytes of BIT STRING overhead;
+ * - 4 bytes of SEQUENCE overhead;
  * - n : INTEGER;
  * - 7 bytes for the public exponent.
  */
 #define PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE(key_bits)        \
-    (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) + 36)
+    (PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE(key_bits) + 11)
 
 /* Maximum size of the export encoding of an RSA key pair.
  * Assumes thatthe public exponent is less than 2^32 and that the size
@@ -523,26 +514,16 @@
 
 /* Maximum size of the export encoding of an ECC public key.
  *
- * SubjectPublicKeyInfo  ::=  SEQUENCE  {
- *      algorithm            AlgorithmIdentifier,
- *      subjectPublicKey     BIT STRING  } -- contains ECPoint
- * AlgorithmIdentifier  ::=  SEQUENCE  {
- *      algorithm               OBJECT IDENTIFIER,
- *      parameters              OBJECT IDENTIFIER } -- namedCurve
- * ECPoint ::= ...
- *    -- first 8 bits: 0x04;
- *    -- then x_P as a `ceiling(m/8)`-byte string, big endian;
- *    -- then y_P as a `ceiling(m/8)`-byte string, big endian;
- *    -- where `m` is the bit size associated with the curve.
+ * The representation of an ECC public key is:
+ *      - The byte 0x04;
+ *      - `x_P` as a `ceiling(m/8)`-byte string, big-endian;
+ *      - `y_P` as a `ceiling(m/8)`-byte string, big-endian;
+ *      - where m is the bit size associated with the curve.
  *
- * - 2 * 4 bytes of SEQUENCE overhead;
- * - 1 + 1 + 7 bytes of algorithm (id-ecPublicKey OID);
- * - 1 + 1 + 12 bytes of namedCurve OID;
- * - 4 bytes of BIT STRING overhead;
- * - 1 byte + 2 * point size in ECPoint.
+ * - 1 byte + 2 * point size.
  */
 #define PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(key_bits)        \
-    (2 * PSA_BITS_TO_BYTES(key_bits) + 36)
+    (2 * PSA_BITS_TO_BYTES(key_bits) + 1)
 
 /* Maximum size of the export encoding of an ECC key pair.
  *
diff --git a/include/psa/crypto_types.h b/include/psa/crypto_types.h
index 637e07c..7054de7 100644
--- a/include/psa/crypto_types.h
+++ b/include/psa/crypto_types.h
@@ -47,8 +47,13 @@
  * This is either #PSA_SUCCESS (which is zero), indicating success,
  * or a nonzero value indicating that an error occurred. Errors are
  * encoded as one of the \c PSA_ERROR_xxx values defined here.
+ * If #PSA_SUCCESS is already defined, it means that #psa_status_t
+ * is also defined in an external header, so prevent its multiple
+ * definition.
  */
+#ifndef PSA_SUCCESS
 typedef int32_t psa_status_t;
+#endif
 
 /**@}*/
 
@@ -85,7 +90,14 @@
 
 /** Encoding of identifiers of persistent keys.
  */
+/* Implementation-specific quirk: The Mbed Crypto library can be built as
+ * part of a multi-client service that exposes the PSA Crypto API in each
+ * client and encodes the client identity in the key id argument of functions
+ * such as psa_open_key(). In this build configuration, we define
+ * psa_key_id_t in crypto_platform.h instead of here. */
+#if !defined(MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER)
 typedef uint32_t psa_key_id_t;
+#endif
 
 /**@}*/
 
diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h
index f6ce04e..f9ac00a 100644
--- a/include/psa/crypto_values.h
+++ b/include/psa/crypto_values.h
@@ -40,25 +40,17 @@
  * @{
  */
 
-#if !defined(PSA_SUCCESS)
-/* If PSA_SUCCESS is defined, assume that PSA crypto is being used
- * together with PSA IPC, which also defines the identifier
- * PSA_SUCCESS. We must not define PSA_SUCCESS ourselves in that case;
- * the other error code names don't clash. This is a temporary hack
- * until we unify error reporting in PSA IPC and PSA crypto.
- *
- * Note that psa_defs.h must be included before this header!
- */
+/* PSA error codes */
+
 /** The action was completed successfully. */
 #define PSA_SUCCESS ((psa_status_t)0)
-#endif /* !defined(PSA_SUCCESS) */
 
 /** An error occurred that does not correspond to any defined
  * failure cause.
  *
  * Implementations may use this error code if none of the other standard
  * error codes are applicable. */
-#define PSA_ERROR_UNKNOWN_ERROR         ((psa_status_t)1)
+#define PSA_ERROR_GENERIC_ERROR         ((psa_status_t)-132)
 
 /** The requested operation or a parameter is not supported
  * by this implementation.
@@ -67,7 +59,7 @@
  * parameter such as a key type, algorithm, etc. is not recognized.
  * If a combination of parameters is recognized and identified as
  * not valid, return #PSA_ERROR_INVALID_ARGUMENT instead. */
-#define PSA_ERROR_NOT_SUPPORTED         ((psa_status_t)2)
+#define PSA_ERROR_NOT_SUPPORTED         ((psa_status_t)-134)
 
 /** The requested action is denied by a policy.
  *
@@ -80,7 +72,7 @@
  * not valid or not supported, it is unspecified whether the function
  * returns #PSA_ERROR_NOT_PERMITTED, #PSA_ERROR_NOT_SUPPORTED or
  * #PSA_ERROR_INVALID_ARGUMENT. */
-#define PSA_ERROR_NOT_PERMITTED         ((psa_status_t)3)
+#define PSA_ERROR_NOT_PERMITTED         ((psa_status_t)-133)
 
 /** An output buffer is too small.
  *
@@ -92,23 +84,19 @@
  * buffer would succeed. However implementations may return this
  * error if a function has invalid or unsupported parameters in addition
  * to the parameters that determine the necessary output buffer size. */
-#define PSA_ERROR_BUFFER_TOO_SMALL      ((psa_status_t)4)
+#define PSA_ERROR_BUFFER_TOO_SMALL      ((psa_status_t)-138)
 
-/** A slot is occupied, but must be empty to carry out the
- * requested action.
+/** Asking for an item that already exists
  *
- * If a handle is invalid, it does not designate an occupied slot.
- * The error for an invalid handle is #PSA_ERROR_INVALID_HANDLE.
- */
-#define PSA_ERROR_OCCUPIED_SLOT         ((psa_status_t)5)
+ * Implementations should return this error, when attempting
+ * to write an item (like a key) that already exists. */
+#define PSA_ERROR_ALREADY_EXISTS        ((psa_status_t)-139)
 
-/** A slot is empty, but must be occupied to carry out the
- * requested action.
+/** Asking for an item that doesn't exist
  *
- * If a handle is invalid, it does not designate an empty slot.
- * The error for an invalid handle is #PSA_ERROR_INVALID_HANDLE.
- */
-#define PSA_ERROR_EMPTY_SLOT            ((psa_status_t)6)
+ * Implementations should return this error, if a requested item (like
+ * a key) does not exist. */
+#define PSA_ERROR_DOES_NOT_EXIST        ((psa_status_t)-140)
 
 /** The requested action cannot be performed in the current state.
  *
@@ -118,9 +106,9 @@
  *
  * Implementations shall not return this error code to indicate
  * that a key slot is occupied when it needs to be free or vice versa,
- * but shall return #PSA_ERROR_OCCUPIED_SLOT or #PSA_ERROR_EMPTY_SLOT
+ * but shall return #PSA_ERROR_ALREADY_EXISTS or #PSA_ERROR_DOES_NOT_EXIST
  * as applicable. */
-#define PSA_ERROR_BAD_STATE             ((psa_status_t)7)
+#define PSA_ERROR_BAD_STATE             ((psa_status_t)-137)
 
 /** The parameters passed to the function are invalid.
  *
@@ -129,20 +117,20 @@
  *
  * Implementations shall not return this error code to indicate
  * that a key slot is occupied when it needs to be free or vice versa,
- * but shall return #PSA_ERROR_OCCUPIED_SLOT or #PSA_ERROR_EMPTY_SLOT
+ * but shall return #PSA_ERROR_ALREADY_EXISTS or #PSA_ERROR_DOES_NOT_EXIST
  * as applicable.
  *
  * Implementation shall not return this error code to indicate that a
  * key handle is invalid, but shall return #PSA_ERROR_INVALID_HANDLE
  * instead.
  */
-#define PSA_ERROR_INVALID_ARGUMENT      ((psa_status_t)8)
+#define PSA_ERROR_INVALID_ARGUMENT      ((psa_status_t)-135)
 
 /** There is not enough runtime memory.
  *
  * If the action is carried out across multiple security realms, this
  * error can refer to available memory in any of the security realms. */
-#define PSA_ERROR_INSUFFICIENT_MEMORY   ((psa_status_t)9)
+#define PSA_ERROR_INSUFFICIENT_MEMORY   ((psa_status_t)-141)
 
 /** There is not enough persistent storage.
  *
@@ -151,7 +139,7 @@
  * many functions that do not otherwise access storage may return this
  * error code if the implementation requires a mandatory log entry for
  * the requested action and the log storage space is full. */
-#define PSA_ERROR_INSUFFICIENT_STORAGE  ((psa_status_t)10)
+#define PSA_ERROR_INSUFFICIENT_STORAGE  ((psa_status_t)-142)
 
 /** There was a communication failure inside the implementation.
  *
@@ -168,7 +156,7 @@
  * cryptoprocessor but there was a breakdown of communication before
  * the cryptoprocessor could report the status to the application.
  */
-#define PSA_ERROR_COMMUNICATION_FAILURE ((psa_status_t)11)
+#define PSA_ERROR_COMMUNICATION_FAILURE ((psa_status_t)-145)
 
 /** There was a storage failure that may have led to data loss.
  *
@@ -193,13 +181,13 @@
  * permanent storage corruption. However application writers should
  * keep in mind that transient errors while reading the storage may be
  * reported using this error code. */
-#define PSA_ERROR_STORAGE_FAILURE       ((psa_status_t)12)
+#define PSA_ERROR_STORAGE_FAILURE       ((psa_status_t)-146)
 
 /** A hardware failure was detected.
  *
  * A hardware failure may be transient or permanent depending on the
  * cause. */
-#define PSA_ERROR_HARDWARE_FAILURE      ((psa_status_t)13)
+#define PSA_ERROR_HARDWARE_FAILURE      ((psa_status_t)-147)
 
 /** A tampering attempt was detected.
  *
@@ -230,7 +218,7 @@
  * This error indicates an attack against the application. Implementations
  * shall not return this error code as a consequence of the behavior of
  * the application itself. */
-#define PSA_ERROR_TAMPERING_DETECTED    ((psa_status_t)14)
+#define PSA_ERROR_TAMPERING_DETECTED    ((psa_status_t)-151)
 
 /** There is not enough entropy to generate random data needed
  * for the requested action.
@@ -249,7 +237,7 @@
  * secure pseudorandom generator (PRNG). However implementations may return
  * this error at any time if a policy requires the PRNG to be reseeded
  * during normal operation. */
-#define PSA_ERROR_INSUFFICIENT_ENTROPY  ((psa_status_t)15)
+#define PSA_ERROR_INSUFFICIENT_ENTROPY  ((psa_status_t)-148)
 
 /** The signature, MAC or hash is incorrect.
  *
@@ -259,7 +247,7 @@
  *
  * If the value to verify has an invalid size, implementations may return
  * either #PSA_ERROR_INVALID_ARGUMENT or #PSA_ERROR_INVALID_SIGNATURE. */
-#define PSA_ERROR_INVALID_SIGNATURE     ((psa_status_t)16)
+#define PSA_ERROR_INVALID_SIGNATURE     ((psa_status_t)-149)
 
 /** The decrypted padding is incorrect.
  *
@@ -275,17 +263,15 @@
  * as close as possible to indistinguishable to an external observer.
  * In particular, the timing of a decryption operation should not
  * depend on the validity of the padding. */
-#define PSA_ERROR_INVALID_PADDING       ((psa_status_t)17)
+#define PSA_ERROR_INVALID_PADDING       ((psa_status_t)-150)
 
-/** The generator has insufficient capacity left.
- *
- * Once a function returns this error, attempts to read from the
- * generator will always return this error. */
-#define PSA_ERROR_INSUFFICIENT_CAPACITY ((psa_status_t)18)
+/** Return this error when there's insufficient data when attempting
+ * to read from a resource. */
+#define PSA_ERROR_INSUFFICIENT_DATA     ((psa_status_t)-143)
 
 /** The key handle is not valid.
  */
-#define PSA_ERROR_INVALID_HANDLE        ((psa_status_t)19)
+#define PSA_ERROR_INVALID_HANDLE        ((psa_status_t)-136)
 
 /**@}*/
 
@@ -663,15 +649,18 @@
 /** SHA3-512 */
 #define PSA_ALG_SHA3_512                        ((psa_algorithm_t)0x01000013)
 
-/** Allow any hash algorithm.
+/** In a hash-and-sign algorithm policy, allow any hash algorithm.
  *
- * This value may only be used to form the algorithm usage field of a policy
- * for a signature algorithm that is parametrized by a hash. That is,
- * suppose that `PSA_xxx_SIGNATURE` is one of the following macros:
+ * This value may be used to form the algorithm usage field of a policy
+ * for a signature algorithm that is parametrized by a hash. The key
+ * may then be used to perform operations using the same signature
+ * algorithm parametrized with any supported hash.
+ *
+ * That is, suppose that `PSA_xxx_SIGNATURE` is one of the following macros:
  * - #PSA_ALG_RSA_PKCS1V15_SIGN, #PSA_ALG_RSA_PSS,
  * - #PSA_ALG_DSA, #PSA_ALG_DETERMINISTIC_DSA,
  * - #PSA_ALG_ECDSA, #PSA_ALG_DETERMINISTIC_ECDSA.
- * Then you may create a key as follows:
+ * Then you may create and use a key as follows:
  * - Set the key usage field using #PSA_ALG_ANY_HASH, for example:
  *   ```
  *   psa_key_policy_set_usage(&policy,
@@ -758,7 +747,7 @@
  *          algorithm is considered identical to the untruncated algorithm
  *          for policy comparison purposes.
  *
- * \param alg           A MAC algorithm identifier (value of type
+ * \param mac_alg       A MAC algorithm identifier (value of type
  *                      #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p alg)
  *                      is true). This may be a truncated or untruncated
  *                      MAC algorithm.
@@ -774,14 +763,14 @@
  *                      MAC algorithm or if \p mac_length is too small or
  *                      too large for the specified MAC algorithm.
  */
-#define PSA_ALG_TRUNCATED_MAC(alg, mac_length)                          \
-    (((alg) & ~PSA_ALG_MAC_TRUNCATION_MASK) |                           \
+#define PSA_ALG_TRUNCATED_MAC(mac_alg, mac_length)                      \
+    (((mac_alg) & ~PSA_ALG_MAC_TRUNCATION_MASK) |                       \
      ((mac_length) << PSA_MAC_TRUNCATION_OFFSET & PSA_ALG_MAC_TRUNCATION_MASK))
 
 /** Macro to build the base MAC algorithm corresponding to a truncated
  * MAC algorithm.
  *
- * \param alg           A MAC algorithm identifier (value of type
+ * \param mac_alg       A MAC algorithm identifier (value of type
  *                      #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p alg)
  *                      is true). This may be a truncated or untruncated
  *                      MAC algorithm.
@@ -790,12 +779,12 @@
  * \return              Unspecified if \p alg is not a supported
  *                      MAC algorithm.
  */
-#define PSA_ALG_FULL_LENGTH_MAC(alg)            \
-    ((alg) & ~PSA_ALG_MAC_TRUNCATION_MASK)
+#define PSA_ALG_FULL_LENGTH_MAC(mac_alg)        \
+    ((mac_alg) & ~PSA_ALG_MAC_TRUNCATION_MASK)
 
 /** Length to which a MAC algorithm is truncated.
  *
- * \param alg           A MAC algorithm identifier (value of type
+ * \param mac_alg       A MAC algorithm identifier (value of type
  *                      #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p alg)
  *                      is true).
  *
@@ -804,8 +793,8 @@
  * \return              Unspecified if \p alg is not a supported
  *                      MAC algorithm.
  */
-#define PSA_MAC_TRUNCATED_LENGTH(alg)           \
-    (((alg) & PSA_ALG_MAC_TRUNCATION_MASK) >> PSA_MAC_TRUNCATION_OFFSET)
+#define PSA_MAC_TRUNCATED_LENGTH(mac_alg)                               \
+    (((mac_alg) & PSA_ALG_MAC_TRUNCATION_MASK) >> PSA_MAC_TRUNCATION_OFFSET)
 
 #define PSA_ALG_CIPHER_MAC_BASE                 ((psa_algorithm_t)0x02c00000)
 #define PSA_ALG_CBC_MAC                         ((psa_algorithm_t)0x02c00001)
@@ -907,7 +896,7 @@
  * Depending on the algorithm, the tag length may affect the calculation
  * of the ciphertext.
  *
- * \param alg           A AEAD algorithm identifier (value of type
+ * \param aead_alg      An AEAD algorithm identifier (value of type
  *                      #psa_algorithm_t such that #PSA_ALG_IS_AEAD(\p alg)
  *                      is true).
  * \param tag_length    Desired length of the authentication tag in bytes.
@@ -918,26 +907,26 @@
  *                      AEAD algorithm or if \p tag_length is not valid
  *                      for the specified AEAD algorithm.
  */
-#define PSA_ALG_AEAD_WITH_TAG_LENGTH(alg, tag_length)                   \
-    (((alg) & ~PSA_ALG_AEAD_TAG_LENGTH_MASK) |                          \
+#define PSA_ALG_AEAD_WITH_TAG_LENGTH(aead_alg, tag_length)              \
+    (((aead_alg) & ~PSA_ALG_AEAD_TAG_LENGTH_MASK) |                     \
      ((tag_length) << PSA_AEAD_TAG_LENGTH_OFFSET &                      \
       PSA_ALG_AEAD_TAG_LENGTH_MASK))
 
 /** Calculate the corresponding AEAD algorithm with the default tag length.
  *
- * \param alg   An AEAD algorithm (\c PSA_ALG_XXX value such that
- *              #PSA_ALG_IS_AEAD(\p alg) is true).
+ * \param aead_alg      An AEAD algorithm (\c PSA_ALG_XXX value such that
+ *                      #PSA_ALG_IS_AEAD(\p alg) is true).
  *
- * \return      The corresponding AEAD algorithm with the default tag length
- *              for that algorithm.
+ * \return              The corresponding AEAD algorithm with the default
+ *                      tag length for that algorithm.
  */
-#define PSA_ALG_AEAD_WITH_DEFAULT_TAG_LENGTH(alg)                       \
+#define PSA_ALG_AEAD_WITH_DEFAULT_TAG_LENGTH(aead_alg)                  \
     (                                                                   \
-        PSA__ALG_AEAD_WITH_DEFAULT_TAG_LENGTH__CASE(alg, PSA_ALG_CCM)   \
-        PSA__ALG_AEAD_WITH_DEFAULT_TAG_LENGTH__CASE(alg, PSA_ALG_GCM)   \
+        PSA__ALG_AEAD_WITH_DEFAULT_TAG_LENGTH__CASE(aead_alg, PSA_ALG_CCM) \
+        PSA__ALG_AEAD_WITH_DEFAULT_TAG_LENGTH__CASE(aead_alg, PSA_ALG_GCM) \
         0)
-#define PSA__ALG_AEAD_WITH_DEFAULT_TAG_LENGTH__CASE(alg, ref) \
-    PSA_ALG_AEAD_WITH_TAG_LENGTH(alg, 0) == \
+#define PSA__ALG_AEAD_WITH_DEFAULT_TAG_LENGTH__CASE(aead_alg, ref)      \
+    PSA_ALG_AEAD_WITH_TAG_LENGTH(aead_alg, 0) ==                        \
     PSA_ALG_AEAD_WITH_TAG_LENGTH(ref, 0) ?  \
     ref :