diff --git a/CMakeLists.txt b/CMakeLists.txt
index 3e47224..ca4cba2 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -126,8 +126,8 @@
 endif()
 
 ADD_CUSTOM_TARGET(apidoc
-    COMMAND doxygen doxygen/mbedtls.doxyfile
-    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
+    COMMAND doxygen mbedtls.doxyfile
+    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/doxygen)
 
 if(ENABLE_TESTING)
     enable_testing()
diff --git a/ChangeLog b/ChangeLog
index d77e284..13fd5d7 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,16 +1,64 @@
 mbed TLS ChangeLog (Sorted per branch, date)
 
-= mbed TLS x.x.x branch released xxxx-xx-xx
+= mbed TLS 2.7.x branch released 2018-xx-xx
+
+Bugfix
+   * Fix the name of a DHE parameter that was accidentally changed in 2.7.0.
+     Fixes #1358.
+   * Fix test_suite_pk to work on 64-bit ILP32 systems. #849
+
+Changes
+   * Fix tag lengths and value ranges in the documentation of CCM encryption.
+     Contributed by Mathieu Briand.
+   * Fix typo in a comment ctr_drbg.c. Contributed by Paul Sokolovsky.
+   * Remove support for the library reference configuration for picocoin.
+
+= mbed TLS 2.7.0 branch released 2018-02-03
 
 Security
-   * Fix a potential heap buffer overflow in mbedtls_ssl_write. When the (by
+   * Fix a heap corruption issue in the implementation of the truncated HMAC
+     extension. When the truncated HMAC extension is enabled and CBC is used,
+     sending a malicious application packet could be used to selectively corrupt
+     6 bytes on the peer's heap, which could potentially lead to crash or remote
+     code execution. The issue could be triggered remotely from either side in
+     both TLS and DTLS. CVE-2018-0488
+   * Fix a buffer overflow in RSA-PSS verification when the hash was too large
+     for the key size, which could potentially lead to crash or remote code
+     execution. Found by Seth Terashima, Qualcomm Product Security Initiative,
+     Qualcomm Technologies Inc. CVE-2018-0487
+   * Fix buffer overflow in RSA-PSS verification when the unmasked data is all
+     zeros.
+   * Fix an unsafe bounds check in ssl_parse_client_psk_identity() when adding
+     64 KiB to the address of the SSL buffer and causing a wrap around.
+   * Fix a potential heap buffer overflow in mbedtls_ssl_write(). When the (by
      default enabled) maximum fragment length extension is disabled in the
      config and the application data buffer passed to mbedtls_ssl_write
      is larger than the internal message buffer (16384 bytes by default), the
      latter overflows. The exploitability of this issue depends on whether the
      application layer can be forced into sending such large packets. The issue
      was independently reported by Tim Nordell via e-mail and by Florin Petriuc
-     and sjorsdewit on GitHub. Fix proposed by Florin Petriuc in #1022. Fixes #707.
+     and sjorsdewit on GitHub. Fix proposed by Florin Petriuc in #1022.
+     Fixes #707.
+   * Add a provision to prevent compiler optimizations breaking the time
+     constancy of mbedtls_ssl_safer_memcmp().
+   * Ensure that buffers are cleared after use if they contain sensitive data.
+     Changes were introduced in multiple places in the library.
+   * Set PEM buffer to zero before freeing it, to avoid decoded private keys
+     being leaked to memory after release.
+   * Fix dhm_check_range() failing to detect trivial subgroups and potentially
+     leaking 1 bit of the private key. Reported by prashantkspatil.
+   * Make mbedtls_mpi_read_binary() constant-time with respect to the input
+     data. Previously, trailing zero bytes were detected and omitted for the
+     sake of saving memory, but potentially leading to slight timing
+     differences. Reported by Marco Macchetti, Kudelski Group.
+   * Wipe stack buffer temporarily holding EC private exponent
+     after keypair generation.
+   * Fix a potential heap buffer over-read in ALPN extension parsing
+     (server-side). Could result in application crash, but only if an ALPN
+     name larger than 16 bytes had been configured on the server.
+   * Change default choice of DHE parameters from untrustworthy RFC 5114
+     to RFC 3526 containing parameters generated in a nothing-up-my-sleeve
+     manner.
 
 Features
    * Allow comments in test data files.
@@ -19,7 +67,7 @@
    * New unit tests for timing. Improve the self-test to be more robust
      when run on a heavily-loaded machine.
    * Add alternative implementation support for CCM and CMAC (MBEDTLS_CCM_ALT,
-     MBEDTLS_CMAC_ALT). Submitted by Steve Cooreman, Silicon Labs.
+     MBEDTLS_CMAC_ALT). Submitted by Steven Cooreman, Silicon Labs.
    * Add support for alternative implementations of GCM, selected by the
      configuration flag MBEDTLS_GCM_ALT.
    * Add support for alternative implementations for ECDSA, controlled by new
@@ -28,29 +76,53 @@
      The following functions from the ECDSA module can be replaced
      with alternative implementation:
      mbedtls_ecdsa_sign(), mbedtls_ecdsa_verify() and mbedtls_ecdsa_genkey().
-   * Add support for alternative implementation for ECDH, controlled by new
-     configuration flags MBEDTLS_ECDH_COMPUTE_SHARED_ALT and
+   * Add support for alternative implementation of ECDH, controlled by the
+     new configuration flags MBEDTLS_ECDH_COMPUTE_SHARED_ALT and
      MBEDTLS_ECDH_GEN_PUBLIC_ALT in config.h.
      The following functions from the ECDH module can be replaced
      with an alternative implementation:
      mbedtls_ecdh_gen_public() and mbedtls_ecdh_compute_shared().
-
-New deprecations
-   * Deprecate usage of RSA primitives with non-matching key-type
-     (e.g., signing with a public key).
-   * Direct manipulation of structure fields of RSA contexts is deprecated.
-     Users are advised to use the extended RSA API instead.
+   * Add support for alternative implementation of ECJPAKE, controlled by
+     the new configuration flag MBEDTLS_ECJPAKE_ALT.
+   * Add mechanism to provide alternative implementation of the DHM module.
 
 API Changes
    * Extend RSA interface by multiple functions allowing structure-
      independent setup and export of RSA contexts. Most notably,
-     mbedtls_rsa_import and mbedtls_rsa_complete are introduced for setting
+     mbedtls_rsa_import() and mbedtls_rsa_complete() are introduced for setting
      up RSA contexts from partial key material and having them completed to the
      needs of the implementation automatically. This allows to setup private RSA
      contexts from keys consisting of N,D,E only, even if P,Q are needed for the
      purpose or CRT and/or blinding.
    * The configuration option MBEDTLS_RSA_ALT can be used to define alternative
      implementations of the RSA interface declared in rsa.h.
+   * The following functions in the message digest modules (MD2, MD4, MD5,
+     SHA1, SHA256, SHA512) have been deprecated and replaced as shown below.
+     The new functions change the return type from void to int to allow
+     returning error codes when using MBEDTLS_<MODULE>_ALT.
+     mbedtls_<MODULE>_starts() -> mbedtls_<MODULE>_starts_ret()
+     mbedtls_<MODULE>_update() -> mbedtls_<MODULE>_update_ret()
+     mbedtls_<MODULE>_finish() -> mbedtls_<MODULE>_finish_ret()
+     mbedtls_<MODULE>_process() -> mbedtls_internal_<MODULE>_process()
+
+New deprecations
+   * Deprecate usage of RSA primitives with non-matching key-type
+     (e.g. signing with a public key).
+   * Direct manipulation of structure fields of RSA contexts is deprecated.
+     Users are advised to use the extended RSA API instead.
+   * Deprecate usage of message digest functions that return void
+     (mbedtls_<MODULE>_starts, mbedtls_<MODULE>_update,
+     mbedtls_<MODULE>_finish and mbedtls_<MODULE>_process where <MODULE> is
+     any of MD2, MD4, MD5, SHA1, SHA256, SHA512) in favor of functions
+     that can return an error code.
+   * Deprecate untrustworthy DHE parameters from RFC 5114. Superseded by
+     parameters from RFC 3526 or the newly added parameters from RFC 7919.
+   * Deprecate hex string DHE constants MBEDTLS_DHM_RFC3526_MODP_2048_P etc.
+     Supserseded by binary encoded constants MBEDTLS_DHM_RFC3526_MODP_2048_P_BIN
+     etc.
+   * Deprecate mbedtls_ssl_conf_dh_param() for setting default DHE parameters
+     from hex strings. Superseded by mbedtls_ssl_conf_dh_param_bin()
+     accepting DHM parameters in binary form, matching the new constants.
 
 Bugfix
    * Fix ssl_parse_record_header() to silently discard invalid DTLS records
@@ -64,6 +136,8 @@
    * Fix leap year calculation in x509_date_is_valid() to ensure that invalid
      dates on leap years with 100 and 400 intervals are handled correctly. Found
      by Nicholas Wilson. #694
+   * Fix some invalid RSA-PSS signatures with keys of size 8N+1 that were
+     accepted. Generating these signatures required the private key.
    * Fix out-of-memory problem when parsing 4096-bit PKCS8-encrypted RSA keys.
      Found independently by Florian in the mbed TLS forum and by Mishamax.
      #878, #1019.
@@ -83,27 +157,45 @@
    * Don't print X.509 version tag for v1 CRT's, and omit extensions for
      non-v3 CRT's.
    * Fix bugs in RSA test suite under MBEDTLS_NO_PLATFORM_ENTROPY. #1023 #1024
-   * Fix net_would_block to avoid modification by errno through fcntl call.
+   * Fix net_would_block() to avoid modification by errno through fcntl() call.
      Found by nkolban. Fixes #845.
-   * Fix handling of handshake messages in mbedtls_ssl_read in case
+   * Fix handling of handshake messages in mbedtls_ssl_read() in case
      MBEDTLS_SSL_RENEGOTIATION is disabled. Found by erja-gp.
-   * Add a check for invalid private parameters in mbedtls_ecdsa_sign.
+   * Add a check for invalid private parameters in mbedtls_ecdsa_sign().
      Reported by Yolan Romailler.
    * Fix word size check in in pk.c to not depend on MBEDTLS_HAVE_INT64.
    * Fix incorrect unit in benchmark output. #850
+   * Add size-checks for record and handshake message content, securing
+     fragile yet non-exploitable code-paths.
    * Fix crash when calling mbedtls_ssl_cache_free() twice. Found by
      MilenkoMitrovic, #1104
-   * Fix mbedtls_timing_alarm(0) on Unix.
-   * Fix use of uninitialized memory in mbedtls_timing_get_timer when reset=1.
+   * Fix mbedtls_timing_alarm(0) on Unix and MinGW.
+   * Fix use of uninitialized memory in mbedtls_timing_get_timer() when reset=1.
    * Fix possible memory leaks in mbedtls_gcm_self_test().
    * Added missing return code checks in mbedtls_aes_self_test().
    * Fix issues in RSA key generation program programs/x509/rsa_genkey and the
      RSA test suite where the failure of CTR DRBG initialization lead to
      freeing an RSA context and several MPI's without proper initialization
      beforehand.
+   * Fix error message in programs/pkey/gen_key.c. Found and fixed by Chris Xue.
+   * Fix programs/pkey/dh_server.c so that it actually works with dh_client.c.
+     Found and fixed by Martijn de Milliano.
+   * Fix an issue in the cipher decryption with the mode
+     MBEDTLS_PADDING_ONE_AND_ZEROS that sometimes accepted invalid padding.
+     Note, this padding mode is not used by the TLS protocol. Found and fixed by
+     Micha Kraus.
+   * Fix the entropy.c module to not call mbedtls_sha256_starts() or
+     mbedtls_sha512_starts() in the mbedtls_entropy_init() function.
+   * Fix the entropy.c module to ensure that mbedtls_sha256_init() or
+     mbedtls_sha512_init() is called before operating on the relevant context
+     structure. Do not assume that zeroizing a context is a correct way to
+     reset it. Found independently by ccli8 on Github.
+   * In mbedtls_entropy_free(), properly free the message digest context.
+   * Fix status handshake status message in programs/ssl/dtls_client.c. Found
+     and fixed by muddog.
 
 Changes
-   * Extend cert_write example program by options to set the CRT version
+   * Extend cert_write example program by options to set the certificate version
      and the message digest. Further, allow enabling/disabling of authority
      identifier, subject identifier and basic constraints extensions.
    * Only check for necessary RSA structure fields in `mbedtls_rsa_private`. In
@@ -113,7 +205,16 @@
    * Only run AES-192 self-test if AES-192 is available. Fixes #963.
    * Tighten the RSA PKCS#1 v1.5 signature verification code and remove the
      undeclared dependency of the RSA module on the ASN.1 module.
-   * Remove support for the library reference configuration for picocoin.
+   * Update all internal usage of deprecated message digest functions to the
+     new ones with return codes. In particular, this modifies the
+     mbedtls_md_info_t structure. Propagate errors from these functions
+     everywhere except some locations in the ssl_tls.c module.
+   * Improve CTR_DRBG error handling by propagating underlying AES errors.
+   * Add MBEDTLS_ERR_XXX_HW_ACCEL_FAILED error codes for all cryptography
+     modules where the software implementation can be replaced by a hardware
+     implementation.
+   * Add explicit warnings for the use of MD2, MD4, MD5, SHA-1, DES and ARC4
+     throughout the library.
 
 = mbed TLS 2.6.0 branch released 2017-08-10
 
diff --git a/Makefile b/Makefile
index d475868..c18b99b 100644
--- a/Makefile
+++ b/Makefile
@@ -103,7 +103,7 @@
 
 apidoc:
 	mkdir -p apidoc
-	doxygen doxygen/mbedtls.doxyfile
+	cd doxygen && doxygen mbedtls.doxyfile
 
 apidoc_clean:
 	rm -rf apidoc
diff --git a/configs/config-ccm-psk-tls1_2.h b/configs/config-ccm-psk-tls1_2.h
index aee10b8..a783e6b 100644
--- a/configs/config-ccm-psk-tls1_2.h
+++ b/configs/config-ccm-psk-tls1_2.h
@@ -1,6 +1,9 @@
-/*
- *  Minimal configuration for TLS 1.2 with PSK and AES-CCM ciphersuites
+/**
+ * \file config-ccm-psk-tls1_2.h
  *
+ * \brief Minimal configuration for TLS 1.2 with PSK and AES-CCM ciphersuites
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/configs/config-mini-tls1_1.h b/configs/config-mini-tls1_1.h
index e22363d..013bc03 100644
--- a/configs/config-mini-tls1_1.h
+++ b/configs/config-mini-tls1_1.h
@@ -1,6 +1,9 @@
-/*
- *  Minimal configuration for TLS 1.1 (RFC 4346)
+/**
+ * \file config-mini-tls1_1.h
  *
+ * \brief Minimal configuration for TLS 1.1 (RFC 4346)
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/configs/config-no-entropy.h b/configs/config-no-entropy.h
index 7375860..b4a0930 100644
--- a/configs/config-no-entropy.h
+++ b/configs/config-no-entropy.h
@@ -1,6 +1,9 @@
 /**
- *  Minimal configuration of features that do not require an entropy source
+ * \file config-no-entropy.h
  *
+ * \brief Minimal configuration of features that do not require an entropy source
+ */
+/*
  *  Copyright (C) 2016, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/configs/config-suite-b.h b/configs/config-suite-b.h
index 3c4804c..18e2c40 100644
--- a/configs/config-suite-b.h
+++ b/configs/config-suite-b.h
@@ -1,6 +1,9 @@
-/*
- *  Minimal configuration for TLS NSA Suite B Profile (RFC 6460)
+/**
+ * \file config-suite-b.h
  *
+ * \brief Minimal configuration for TLS NSA Suite B Profile (RFC 6460)
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/configs/config-thread.h b/configs/config-thread.h
index 990fe08..25db16b 100644
--- a/configs/config-thread.h
+++ b/configs/config-thread.h
@@ -1,6 +1,9 @@
-/*
- *  Minimal configuration for using TLS as part of Thread
+/**
+ * \file config-thread.h
  *
+ * \brief Minimal configuration for using TLS as part of Thread
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/doxygen/input/doc_encdec.h b/doxygen/input/doc_encdec.h
index 9538ed2..b1281cb 100644
--- a/doxygen/input/doc_encdec.h
+++ b/doxygen/input/doc_encdec.h
@@ -1,6 +1,9 @@
 /**
- * @file
- * Encryption/decryption module documentation file.
+ * \file doc_encdec.h
+ *
+ * \brief Encryption/decryption module documentation file.
+ */
+/*
  *
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
diff --git a/doxygen/input/doc_hashing.h b/doxygen/input/doc_hashing.h
index 49f15ea..e54b28e 100644
--- a/doxygen/input/doc_hashing.h
+++ b/doxygen/input/doc_hashing.h
@@ -1,6 +1,9 @@
 /**
- * @file
- * Hashing module documentation file.
+ * \file doc_hashing.h
+ *
+ * \brief Hashing module documentation file.
+ */
+/*
  *
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
diff --git a/doxygen/input/doc_mainpage.h b/doxygen/input/doc_mainpage.h
index 87b5041..641d5c4 100644
--- a/doxygen/input/doc_mainpage.h
+++ b/doxygen/input/doc_mainpage.h
@@ -1,6 +1,9 @@
 /**
- * @file
- * Main page documentation file.
+ * \file doc_mainpage.h
+ *
+ * \brief Main page documentation file.
+ */
+/*
  *
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
@@ -21,7 +24,7 @@
  */
 
 /**
- * @mainpage mbed TLS v2.6.0 source code documentation
+ * @mainpage mbed TLS v2.7.0 source code documentation
  *
  * This documentation describes the internal structure of mbed TLS.  It was
  * automatically generated from specially formatted comment blocks in
diff --git a/doxygen/input/doc_rng.h b/doxygen/input/doc_rng.h
index 0159ef3..0f212e0 100644
--- a/doxygen/input/doc_rng.h
+++ b/doxygen/input/doc_rng.h
@@ -1,6 +1,9 @@
 /**
- * @file
- * Random number generator (RNG) module documentation file.
+ * \file doc_rng.h
+ *
+ * \brief Random number generator (RNG) module documentation file.
+ */
+/*
  *
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
diff --git a/doxygen/input/doc_ssltls.h b/doxygen/input/doc_ssltls.h
index 7f104bd..4addfb3 100644
--- a/doxygen/input/doc_ssltls.h
+++ b/doxygen/input/doc_ssltls.h
@@ -1,6 +1,9 @@
 /**
- * @file
- * SSL/TLS communication module documentation file.
+ * \file doc_ssltls.h
+ *
+ * \brief SSL/TLS communication module documentation file.
+ */
+/*
  *
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
diff --git a/doxygen/input/doc_tcpip.h b/doxygen/input/doc_tcpip.h
index 34d3ca1..95f4586 100644
--- a/doxygen/input/doc_tcpip.h
+++ b/doxygen/input/doc_tcpip.h
@@ -1,6 +1,9 @@
 /**
- * @file
- * TCP/IP communication module documentation file.
+ * \file doc_tcpip.h
+ *
+ * \brief TCP/IP communication module documentation file.
+ */
+/*
  *
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
diff --git a/doxygen/input/doc_x509.h b/doxygen/input/doc_x509.h
index 315f0e3..9b52569 100644
--- a/doxygen/input/doc_x509.h
+++ b/doxygen/input/doc_x509.h
@@ -1,6 +1,9 @@
 /**
- * @file
- * X.509 module documentation file.
+ * \file doc_x509.h
+ *
+ * \brief X.509 module documentation file.
+ */
+/*
  *
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
diff --git a/doxygen/mbedtls.doxyfile b/doxygen/mbedtls.doxyfile
index 5df1c93..cbe0db4 100644
--- a/doxygen/mbedtls.doxyfile
+++ b/doxygen/mbedtls.doxyfile
@@ -28,7 +28,7 @@
 # identify the project. Note that if you do not use Doxywizard you need
 # to put quotes around the project name if it contains spaces.
 
-PROJECT_NAME           = "mbed TLS v2.6.0"
+PROJECT_NAME           = "mbed TLS v2.7.0"
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number.
 # This could be handy for archiving the generated documentation or
@@ -54,7 +54,7 @@
 # If a relative path is entered, it will be relative to the location
 # where doxygen was started. If left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = apidoc/
+OUTPUT_DIRECTORY       = ../apidoc/
 
 # If the CREATE_SUBDIRS tag is set to YES, then doxygen will create
 # 4096 sub-directories (in 2 levels) under the output directory of each output
@@ -165,7 +165,7 @@
 # comments will behave just like regular Qt-style comments
 # (thus requiring an explicit @brief command for a brief description.)
 
-JAVADOC_AUTOBRIEF      = YES
+JAVADOC_AUTOBRIEF      = NO
 
 # If the QT_AUTOBRIEF tag is set to YES then Doxygen will
 # interpret the first line (until the first dot) of a Qt-style
@@ -664,7 +664,7 @@
 # directories like "/usr/src/myproject". Separate the files or directories
 # with spaces.
 
-INPUT                  = .
+INPUT                  = ..
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
@@ -696,7 +696,7 @@
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = configs yotta/module
+EXCLUDE                = ../configs ../yotta/module
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
diff --git a/include/mbedtls/aes.h b/include/mbedtls/aes.h
index c8dd0f3..46016dc 100644
--- a/include/mbedtls/aes.h
+++ b/include/mbedtls/aes.h
@@ -1,9 +1,18 @@
 /**
  * \file aes.h
  *
- * \brief AES block cipher
+ * \brief   The Advanced Encryption Standard (AES) specifies a FIPS-approved
+ *          cryptographic algorithm that can be used to protect electronic
+ *          data.
  *
- *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ *          The AES algorithm is a symmetric block cipher that can
+ *          encrypt and decrypt information. For more information, see
+ *          <em>FIPS Publication 197: Advanced Encryption Standard</em> and
+ *          <em>ISO/IEC 18033-2:2006: Information technology -- Security
+ *          techniques -- Encryption algorithms -- Part 2: Asymmetric
+ *          ciphers</em>.
+ */
+/*  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved.
  *  SPDX-License-Identifier: Apache-2.0
  *
  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
@@ -18,8 +27,9 @@
  *  See the License for the specific language governing permissions and
  *  limitations under the License.
  *
- *  This file is part of mbed TLS (https://tls.mbed.org)
+ *  This file is part of Mbed TLS (https://tls.mbed.org)
  */
+
 #ifndef MBEDTLS_AES_H
 #define MBEDTLS_AES_H
 
@@ -33,15 +43,16 @@
 #include <stdint.h>
 
 /* padlock.c and aesni.c rely on these values! */
-#define MBEDTLS_AES_ENCRYPT     1
-#define MBEDTLS_AES_DECRYPT     0
+#define MBEDTLS_AES_ENCRYPT     1 /**< AES encryption. */
+#define MBEDTLS_AES_DECRYPT     0 /**< AES decryption. */
 
 /* Error codes in range 0x0020-0x0022 */
 #define MBEDTLS_ERR_AES_INVALID_KEY_LENGTH                -0x0020  /**< Invalid key length. */
 #define MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH              -0x0022  /**< Invalid data input length. */
 
-/* Error codes in range 0x0023-0x0023 */
-#define MBEDTLS_ERR_AES_FEATURE_UNAVAILABLE               -0x0023  /**< Feature not available, e.g. unsupported AES key size. */
+/* Error codes in range 0x0023-0x0025 */
+#define MBEDTLS_ERR_AES_FEATURE_UNAVAILABLE               -0x0023  /**< Feature not available. For example, an unsupported AES key size. */
+#define MBEDTLS_ERR_AES_HW_ACCEL_FAILED                   -0x0025  /**< AES hardware accelerator failed. */
 
 #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
     !defined(inline) && !defined(__cplusplus)
@@ -57,68 +68,90 @@
 #endif
 
 /**
- * \brief          AES context structure
- *
- * \note           buf is able to hold 32 extra bytes, which can be used:
- *                 - for alignment purposes if VIA padlock is used, and/or
- *                 - to simplify key expansion in the 256-bit case by
- *                 generating an extra round key
+ * \brief The AES context-type definition.
  */
 typedef struct
 {
-    int nr;                     /*!<  number of rounds  */
-    uint32_t *rk;               /*!<  AES round keys    */
-    uint32_t buf[68];           /*!<  unaligned data    */
+    int nr;                     /*!< The number of rounds. */
+    uint32_t *rk;               /*!< AES round keys. */
+    uint32_t buf[68];           /*!< Unaligned data buffer. This buffer can
+                                     hold 32 extra Bytes, which can be used for
+                                     one of the following purposes:
+                                     <ul><li>Alignment if VIA padlock is
+                                             used.</li>
+                                     <li>Simplifying key expansion in the 256-bit
+                                         case by generating an extra round key.
+                                         </li></ul> */
 }
 mbedtls_aes_context;
 
 /**
- * \brief          Initialize AES context
+ * \brief          This function initializes the specified AES context.
  *
- * \param ctx      AES context to be initialized
+ *                 It must be the first API called before using
+ *                 the context.
+ *
+ * \param ctx      The AES context to initialize.
  */
 void mbedtls_aes_init( mbedtls_aes_context *ctx );
 
 /**
- * \brief          Clear AES context
+ * \brief          This function releases and clears the specified AES context.
  *
- * \param ctx      AES context to be cleared
+ * \param ctx      The AES context to clear.
  */
 void mbedtls_aes_free( mbedtls_aes_context *ctx );
 
 /**
- * \brief          AES key schedule (encryption)
+ * \brief          This function sets the encryption key.
  *
- * \param ctx      AES context to be initialized
- * \param key      encryption key
- * \param keybits  must be 128, 192 or 256
+ * \param ctx      The AES 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:
+ *                 <ul><li>128 bits</li>
+ *                 <li>192 bits</li>
+ *                 <li>256 bits</li></ul>
  *
- * \return         0 if successful, or MBEDTLS_ERR_AES_INVALID_KEY_LENGTH
+ * \return         \c 0 on success or #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH
+ *                 on failure.
  */
 int mbedtls_aes_setkey_enc( mbedtls_aes_context *ctx, const unsigned char *key,
                     unsigned int keybits );
 
 /**
- * \brief          AES key schedule (decryption)
+ * \brief          This function sets the decryption key.
  *
- * \param ctx      AES context to be initialized
- * \param key      decryption key
- * \param keybits  must be 128, 192 or 256
+ * \param ctx      The AES context to which the key should be bound.
+ * \param key      The decryption key.
+ * \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         0 if successful, or MBEDTLS_ERR_AES_INVALID_KEY_LENGTH
+ * \return         \c 0 on success, or #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure.
  */
 int mbedtls_aes_setkey_dec( mbedtls_aes_context *ctx, const unsigned char *key,
                     unsigned int keybits );
 
 /**
- * \brief          AES-ECB block encryption/decryption
+ * \brief          This function performs an AES single-block encryption or
+ *                 decryption operation.
  *
- * \param ctx      AES context
- * \param mode     MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT
- * \param input    16-byte input block
- * \param output   16-byte output block
+ *                 It performs the operation defined in the \p mode parameter
+ *                 (encrypt or decrypt), on the input data buffer defined in
+ *                 the \p input parameter.
  *
- * \return         0 if successful
+ *                 mbedtls_aes_init(), and either mbedtls_aes_setkey_enc() or
+ *                 mbedtls_aes_setkey_dec() must be called before the first
+ *                 call to this API with the same context.
+ *
+ * \param ctx      The AES context to use for encryption or decryption.
+ * \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.
+
+ * \return         \c 0 on success.
  */
 int mbedtls_aes_crypt_ecb( mbedtls_aes_context *ctx,
                     int mode,
@@ -127,26 +160,40 @@
 
 #if defined(MBEDTLS_CIPHER_MODE_CBC)
 /**
- * \brief          AES-CBC buffer encryption/decryption
- *                 Length should be a multiple of the block
- *                 size (16 bytes)
+ * \brief  This function performs an AES-CBC encryption or decryption operation
+ *         on full blocks.
  *
- * \note           Upon exit, the content of the IV is updated so that you can
- *                 call the function same function again on the following
- *                 block(s) of data and get the same result as if it was
- *                 encrypted in one call. This allows a "streaming" usage.
- *                 If on the other hand you need to retain the contents of the
- *                 IV, you should either save it manually or use the cipher
- *                 module instead.
+ *         It performs the operation defined in the \p mode
+ *         parameter (encrypt/decrypt), on the input data buffer defined in
+ *         the \p input parameter.
  *
- * \param ctx      AES context
- * \param mode     MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_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
+ *         It can be called as many times as needed, until all the input
+ *         data is processed. mbedtls_aes_init(), and either
+ *         mbedtls_aes_setkey_enc() or mbedtls_aes_setkey_dec() must be called
+ *         before the first call to this API with the same context.
  *
- * \return         0 if successful, or MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH
+ * \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   Upon exit, the content of the IV is updated so that you can
+ *         call the same function again on the next
+ *         block(s) of data and get the same result as if it was
+ *         encrypted in one call. This allows a "streaming" usage.
+ *         If you need to retain the contents of the IV, you should
+ *         either save it manually or use the cipher module instead.
+ *
+ *
+ * \param ctx      The AES context to use for encryption or decryption.
+ * \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).
+ * \param iv       Initialization vector (updated after use).
+ * \param input    The buffer holding the input data.
+ * \param output   The buffer holding the output data.
+ *
+ * \return         \c 0 on success, or #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH
+ *                 on failure.
  */
 int mbedtls_aes_crypt_cbc( mbedtls_aes_context *ctx,
                     int mode,
@@ -158,29 +205,38 @@
 
 #if defined(MBEDTLS_CIPHER_MODE_CFB)
 /**
- * \brief          AES-CFB128 buffer encryption/decryption.
+ * \brief This function performs an AES-CFB128 encryption or 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_aes_setkey_enc() for both MBEDTLS_AES_ENCRYPT and MBEDTLS_AES_DECRYPT.
+ *        It performs the operation defined in the \p mode
+ *        parameter (encrypt or decrypt), on the input data buffer
+ *        defined in the \p input parameter.
  *
- * \note           Upon exit, the content of the IV is updated so that you can
- *                 call the function same function again on the following
- *                 block(s) of data and get the same result as if it was
- *                 encrypted in one call. This allows a "streaming" usage.
- *                 If on the other hand you need to retain the contents of the
- *                 IV, you should either save it manually or use the cipher
- *                 module instead.
+ *        For CFB, you must set up the context with mbedtls_aes_setkey_enc(),
+ *        regardless of whether you are performing an encryption or decryption
+ *        operation, that is, regardless of the \p mode parameter. This is
+ *        because CFB mode uses the same key schedule for encryption and
+ *        decryption.
  *
- * \param ctx      AES context
- * \param mode     MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_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
+ * \note  Upon exit, the content of the IV is updated so that you can
+ *        call the same function again on the next
+ *        block(s) of data and get the same result as if it was
+ *        encrypted in one call. This allows a "streaming" usage.
+ *        If you need to retain the contents of the
+ *        IV, you must either save it manually or use the cipher
+ *        module instead.
  *
- * \return         0 if successful
+ *
+ * \param ctx      The AES context to use for encryption or decryption.
+ * \param mode     The AES operation: #MBEDTLS_AES_ENCRYPT or
+ *                 #MBEDTLS_AES_DECRYPT.
+ * \param length   The length of the input data.
+ * \param iv_off   The offset in IV (updated after use).
+ * \param iv       The initialization vector (updated after use).
+ * \param input    The buffer holding the input data.
+ * \param output   The buffer holding the output data.
+ *
+ * \return         \c 0 on success.
  */
 int mbedtls_aes_crypt_cfb128( mbedtls_aes_context *ctx,
                        int mode,
@@ -191,28 +247,36 @@
                        unsigned char *output );
 
 /**
- * \brief          AES-CFB8 buffer encryption/decryption.
+ * \brief This function performs an AES-CFB8 encryption or 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_aes_setkey_enc() for both MBEDTLS_AES_ENCRYPT and MBEDTLS_AES_DECRYPT.
+ *        It performs the operation defined in the \p mode
+ *        parameter (encrypt/decrypt), on the input data buffer defined
+ *        in the \p input parameter.
  *
- * \note           Upon exit, the content of the IV is updated so that you can
- *                 call the function same function again on the following
- *                 block(s) of data and get the same result as if it was
- *                 encrypted in one call. This allows a "streaming" usage.
- *                 If on the other hand you need to retain the contents of the
- *                 IV, you should either save it manually or use the cipher
- *                 module instead.
+ *        Due to the nature of CFB, you must use the same key schedule for
+ *        both encryption and decryption operations. Therefore, you must
+ *        use the context initialized with mbedtls_aes_setkey_enc() for
+ *        both #MBEDTLS_AES_ENCRYPT and #MBEDTLS_AES_DECRYPT.
  *
- * \param ctx      AES context
- * \param mode     MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_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
+ * \note  Upon exit, the content of the IV is updated so that you can
+ *        call the same function again on the next
+ *        block(s) of data and get the same result as if it was
+ *        encrypted in one call. This allows a "streaming" usage.
+ *        If you need to retain the contents of the
+ *        IV, you should either save it manually or use the cipher
+ *        module instead.
  *
- * \return         0 if successful
+ *
+ * \param ctx      The AES context to use for encryption or decryption.
+ * \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).
+ * \param input    The buffer holding the input data.
+ * \param output   The buffer holding the output data.
+ *
+ * \return         \c 0 on success.
  */
 int mbedtls_aes_crypt_cfb8( mbedtls_aes_context *ctx,
                     int mode,
@@ -224,26 +288,32 @@
 
 #if defined(MBEDTLS_CIPHER_MODE_CTR)
 /**
- * \brief               AES-CTR buffer encryption/decryption
+ * \brief      This function performs an AES-CTR encryption or decryption
+ *             operation.
  *
- * Warning: You have to keep the maximum use of your counter in mind!
+ *             This function performs the operation defined in the \p mode
+ *             parameter (encrypt/decrypt), on the input data buffer
+ *             defined in the \p input parameter.
  *
- * 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_aes_setkey_enc() for both MBEDTLS_AES_ENCRYPT and MBEDTLS_AES_DECRYPT.
+ *             Due to the nature of CTR, you must use the same key schedule
+ *             for both encryption and decryption operations. Therefore, you
+ *             must use the context initialized with mbedtls_aes_setkey_enc()
+ *             for both #MBEDTLS_AES_ENCRYPT and #MBEDTLS_AES_DECRYPT.
  *
- * \param ctx           AES context
- * \param length        The length of the data
- * \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 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
+ * \warning    You must keep the maximum use of your counter in mind.
  *
- * \return         0 if successful
+ * \param ctx              The AES 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.
+ *
+ * \return     \c 0 on success.
  */
 int mbedtls_aes_crypt_ctr( mbedtls_aes_context *ctx,
                        size_t length,
@@ -255,30 +325,30 @@
 #endif /* MBEDTLS_CIPHER_MODE_CTR */
 
 /**
- * \brief           Internal AES block encryption function
- *                  (Only exposed to allow overriding it,
- *                  see MBEDTLS_AES_ENCRYPT_ALT)
+ * \brief           Internal AES block encryption function. This is only
+ *                  exposed to allow overriding it using
+ *                  \c MBEDTLS_AES_ENCRYPT_ALT.
  *
- * \param ctx       AES context
- * \param input     Plaintext block
- * \param output    Output (ciphertext) block
+ * \param ctx       The AES context to use for encryption.
+ * \param input     The plaintext block.
+ * \param output    The output (ciphertext) block.
  *
- * \return          0 if successful
+ * \return          \c 0 on success.
  */
 int mbedtls_internal_aes_encrypt( mbedtls_aes_context *ctx,
                                   const unsigned char input[16],
                                   unsigned char output[16] );
 
 /**
- * \brief           Internal AES block decryption function
- *                  (Only exposed to allow overriding it,
- *                  see MBEDTLS_AES_DECRYPT_ALT)
+ * \brief           Internal AES block decryption function. This is only
+ *                  exposed to allow overriding it using see
+ *                  \c MBEDTLS_AES_DECRYPT_ALT.
  *
- * \param ctx       AES context
- * \param input     Ciphertext block
- * \param output    Output (plaintext) block
+ * \param ctx       The AES context to use for decryption.
+ * \param input     The ciphertext block.
+ * \param output    The output (plaintext) block.
  *
- * \return          0 if successful
+ * \return          \c 0 on success.
  */
 int mbedtls_internal_aes_decrypt( mbedtls_aes_context *ctx,
                                   const unsigned char input[16],
@@ -294,11 +364,11 @@
  * \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_aes_encrypt_ext() in 2.5.0.
  *
- * \param ctx       AES context
- * \param input     Plaintext block
- * \param output    Output (ciphertext) block
+ * \param ctx       The AES context to use for encryption.
+ * \param input     Plaintext block.
+ * \param output    Output (ciphertext) block.
  */
 MBEDTLS_DEPRECATED void mbedtls_aes_encrypt( mbedtls_aes_context *ctx,
                                              const unsigned char input[16],
@@ -308,11 +378,11 @@
  * \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_aes_decrypt_ext() in 2.5.0.
  *
- * \param ctx       AES context
- * \param input     Ciphertext block
- * \param output    Output (plaintext) block
+ * \param ctx       The AES context to use for decryption.
+ * \param input     Ciphertext block.
+ * \param output    Output (plaintext) block.
  */
 MBEDTLS_DEPRECATED void mbedtls_aes_decrypt( mbedtls_aes_context *ctx,
                                              const unsigned char input[16],
@@ -334,9 +404,9 @@
 #endif
 
 /**
- * \brief          Checkup routine
+ * \brief          Checkup routine.
  *
- * \return         0 if successful, or 1 if the test failed
+ * \return         \c 0 on success, or \c 1 on failure.
  */
 int mbedtls_aes_self_test( int verbose );
 
diff --git a/include/mbedtls/aesni.h b/include/mbedtls/aesni.h
index b1b7f1c..746baa0 100644
--- a/include/mbedtls/aesni.h
+++ b/include/mbedtls/aesni.h
@@ -2,7 +2,8 @@
  * \file aesni.h
  *
  * \brief AES-NI for hardware AES acceleration on some Intel processors
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/arc4.h b/include/mbedtls/arc4.h
index 5fc5395..f9d93f8 100644
--- a/include/mbedtls/arc4.h
+++ b/include/mbedtls/arc4.h
@@ -3,6 +3,10 @@
  *
  * \brief The ARCFOUR stream cipher
  *
+ * \warning   ARC4 is considered a weak cipher and its use constitutes a
+ *            security risk. We recommend considering stronger ciphers instead.
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
@@ -19,6 +23,7 @@
  *  limitations under the License.
  *
  *  This file is part of mbed TLS (https://tls.mbed.org)
+ *
  */
 #ifndef MBEDTLS_ARC4_H
 #define MBEDTLS_ARC4_H
@@ -31,6 +36,8 @@
 
 #include <stddef.h>
 
+#define MBEDTLS_ERR_ARC4_HW_ACCEL_FAILED                  -0x0019  /**< ARC4 hardware accelerator failed. */
+
 #if !defined(MBEDTLS_ARC4_ALT)
 // Regular implementation
 //
@@ -40,7 +47,11 @@
 #endif
 
 /**
- * \brief          ARC4 context structure
+ * \brief     ARC4 context structure
+ *
+ * \warning   ARC4 is considered a weak cipher and its use constitutes a
+ *            security risk. We recommend considering stronger ciphers instead.
+ *
  */
 typedef struct
 {
@@ -54,6 +65,11 @@
  * \brief          Initialize ARC4 context
  *
  * \param ctx      ARC4 context to be initialized
+ *
+ * \warning        ARC4 is considered a weak cipher and its use constitutes a
+ *                 security risk. We recommend considering stronger ciphers
+ *                 instead.
+ *
  */
 void mbedtls_arc4_init( mbedtls_arc4_context *ctx );
 
@@ -61,6 +77,11 @@
  * \brief          Clear ARC4 context
  *
  * \param ctx      ARC4 context to be cleared
+ *
+ * \warning        ARC4 is considered a weak cipher and its use constitutes a
+ *                 security risk. We recommend considering stronger ciphers
+ *                 instead.
+ *
  */
 void mbedtls_arc4_free( mbedtls_arc4_context *ctx );
 
@@ -70,6 +91,11 @@
  * \param ctx      ARC4 context to be setup
  * \param key      the secret key
  * \param keylen   length of the key, in bytes
+ *
+ * \warning        ARC4 is considered a weak cipher and its use constitutes a
+ *                 security risk. We recommend considering stronger ciphers
+ *                 instead.
+ *
  */
 void mbedtls_arc4_setup( mbedtls_arc4_context *ctx, const unsigned char *key,
                  unsigned int keylen );
@@ -83,6 +109,11 @@
  * \param output   buffer for the output data
  *
  * \return         0 if successful
+ *
+ * \warning        ARC4 is considered a weak cipher and its use constitutes a
+ *                 security risk. We recommend considering stronger ciphers
+ *                 instead.
+ *
  */
 int mbedtls_arc4_crypt( mbedtls_arc4_context *ctx, size_t length, const unsigned char *input,
                 unsigned char *output );
@@ -103,6 +134,11 @@
  * \brief          Checkup routine
  *
  * \return         0 if successful, or 1 if the test failed
+ *
+ * \warning        ARC4 is considered a weak cipher and its use constitutes a
+ *                 security risk. We recommend considering stronger ciphers
+ *                 instead.
+ *
  */
 int mbedtls_arc4_self_test( int verbose );
 
diff --git a/include/mbedtls/asn1.h b/include/mbedtls/asn1.h
index e159e57..fde328a 100644
--- a/include/mbedtls/asn1.h
+++ b/include/mbedtls/asn1.h
@@ -2,7 +2,8 @@
  * \file asn1.h
  *
  * \brief Generic ASN.1 parsing
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/asn1write.h b/include/mbedtls/asn1write.h
index 73ff32b..f76fc80 100644
--- a/include/mbedtls/asn1write.h
+++ b/include/mbedtls/asn1write.h
@@ -2,7 +2,8 @@
  * \file asn1write.h
  *
  * \brief ASN.1 buffer writing functionality
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/base64.h b/include/mbedtls/base64.h
index 352c652..7a64f52 100644
--- a/include/mbedtls/base64.h
+++ b/include/mbedtls/base64.h
@@ -2,7 +2,8 @@
  * \file base64.h
  *
  * \brief RFC 1521 base64 encoding/decoding
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/bignum.h b/include/mbedtls/bignum.h
index 0b40015..3bf02a7 100644
--- a/include/mbedtls/bignum.h
+++ b/include/mbedtls/bignum.h
@@ -1,8 +1,9 @@
 /**
  * \file bignum.h
  *
- * \brief  Multi-precision integer library
- *
+ * \brief Multi-precision integer library
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
@@ -683,6 +684,10 @@
  *
  * \return         0 if successful,
  *                 MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
+ *
+ * \note           The bytes obtained from the PRNG are interpreted
+ *                 as a big-endian representation of an MPI; this can
+ *                 be relevant in applications like deterministic ECDSA.
  */
 int mbedtls_mpi_fill_random( mbedtls_mpi *X, size_t size,
                      int (*f_rng)(void *, unsigned char *, size_t),
diff --git a/include/mbedtls/blowfish.h b/include/mbedtls/blowfish.h
index 34626ee..c0ef5a0 100644
--- a/include/mbedtls/blowfish.h
+++ b/include/mbedtls/blowfish.h
@@ -2,7 +2,8 @@
  * \file blowfish.h
  *
  * \brief Blowfish block cipher
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
@@ -40,6 +41,7 @@
 #define MBEDTLS_BLOWFISH_BLOCKSIZE   8          /* Blowfish uses 64 bit blocks */
 
 #define MBEDTLS_ERR_BLOWFISH_INVALID_KEY_LENGTH                -0x0016  /**< Invalid key length. */
+#define MBEDTLS_ERR_BLOWFISH_HW_ACCEL_FAILED                   -0x0017  /**< Blowfish hardware accelerator failed. */
 #define MBEDTLS_ERR_BLOWFISH_INVALID_INPUT_LENGTH              -0x0018  /**< Invalid data input length. */
 
 #if !defined(MBEDTLS_BLOWFISH_ALT)
diff --git a/include/mbedtls/bn_mul.h b/include/mbedtls/bn_mul.h
index cac3f14..354c1cc 100644
--- a/include/mbedtls/bn_mul.h
+++ b/include/mbedtls/bn_mul.h
@@ -1,8 +1,9 @@
 /**
  * \file bn_mul.h
  *
- * \brief  Multi-precision integer library
- *
+ * \brief Multi-precision integer library
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/camellia.h b/include/mbedtls/camellia.h
index 0424d62..cf07629 100644
--- a/include/mbedtls/camellia.h
+++ b/include/mbedtls/camellia.h
@@ -2,7 +2,8 @@
  * \file camellia.h
  *
  * \brief Camellia block cipher
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
@@ -37,6 +38,7 @@
 
 #define MBEDTLS_ERR_CAMELLIA_INVALID_KEY_LENGTH           -0x0024  /**< Invalid key length. */
 #define MBEDTLS_ERR_CAMELLIA_INVALID_INPUT_LENGTH         -0x0026  /**< Invalid data input length. */
+#define MBEDTLS_ERR_CAMELLIA_HW_ACCEL_FAILED              -0x0027  /**< Camellia hardware accelerator failed. */
 
 #if !defined(MBEDTLS_CAMELLIA_ALT)
 // Regular implementation
diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h
index 579402f..630b7fd 100644
--- a/include/mbedtls/ccm.h
+++ b/include/mbedtls/ccm.h
@@ -1,9 +1,19 @@
 /**
  * \file ccm.h
  *
- * \brief Counter with CBC-MAC (CCM) for 128-bit block ciphers
+ * \brief CCM combines Counter mode encryption with CBC-MAC authentication
+ *        for 128-bit block ciphers.
  *
- *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ * Input to CCM includes the following elements:
+ * <ul><li>Payload - data that is both authenticated and encrypted.</li>
+ * <li>Associated data (Adata) - data that is authenticated but not
+ * encrypted, For example, a header.</li>
+ * <li>Nonce - A unique value that is assigned to the payload and the
+ * associated data.</li></ul>
+ *
+ */
+/*
+ *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
@@ -18,15 +28,17 @@
  *  See the License for the specific language governing permissions and
  *  limitations under the License.
  *
- *  This file is part of mbed TLS (https://tls.mbed.org)
+ *  This file is part of Mbed TLS (https://tls.mbed.org)
  */
+
 #ifndef MBEDTLS_CCM_H
 #define MBEDTLS_CCM_H
 
 #include "cipher.h"
 
-#define MBEDTLS_ERR_CCM_BAD_INPUT      -0x000D /**< Bad input parameters to function. */
-#define MBEDTLS_ERR_CCM_AUTH_FAILED    -0x000F /**< Authenticated decryption failed. */
+#define MBEDTLS_ERR_CCM_BAD_INPUT       -0x000D /**< Bad input parameters to the function. */
+#define MBEDTLS_ERR_CCM_AUTH_FAILED     -0x000F /**< Authenticated decryption failed. */
+#define MBEDTLS_ERR_CCM_HW_ACCEL_FAILED -0x0011 /**< CCM hardware accelerator failed. */
 
 #if !defined(MBEDTLS_CCM_ALT)
 // Regular implementation
@@ -37,31 +49,33 @@
 #endif
 
 /**
- * \brief          CCM context structure
+ * \brief    The CCM context-type definition. The CCM context is passed
+ *           to the APIs called.
  */
 typedef struct {
-    mbedtls_cipher_context_t cipher_ctx;    /*!< cipher context used */
+    mbedtls_cipher_context_t cipher_ctx;    /*!< The cipher context used. */
 }
 mbedtls_ccm_context;
 
 /**
- * \brief           Initialize CCM context (just makes references valid)
- *                  Makes the context ready for mbedtls_ccm_setkey() or
- *                  mbedtls_ccm_free().
+ * \brief           This function initializes the specified CCM context,
+ *                  to make references valid, and prepare the context
+ *                  for mbedtls_ccm_setkey() or mbedtls_ccm_free().
  *
- * \param ctx       CCM context to initialize
+ * \param ctx       The CCM context to initialize.
  */
 void mbedtls_ccm_init( mbedtls_ccm_context *ctx );
 
 /**
- * \brief           CCM initialization (encryption and decryption)
+ * \brief           This function initializes the CCM context set in the
+ *                  \p ctx parameter and sets the encryption key.
  *
- * \param ctx       CCM context to be initialized
- * \param cipher    cipher to use (a 128-bit block cipher)
- * \param key       encryption key
- * \param keybits   key size in bits (must be acceptable by the cipher)
+ * \param ctx       The CCM context to initialize.
+ * \param cipher    The 128-bit block cipher to use.
+ * \param key       The encryption key.
+ * \param keybits   The key size in bits. This must be acceptable by the cipher.
  *
- * \return          0 if successful, or a cipher specific error code
+ * \return          \c 0 on success, or a cipher-specific error code.
  */
 int mbedtls_ccm_setkey( mbedtls_ccm_context *ctx,
                         mbedtls_cipher_id_t cipher,
@@ -69,36 +83,37 @@
                         unsigned int keybits );
 
 /**
- * \brief           Free a CCM context and underlying cipher sub-context
+ * \brief   This function releases and clears the specified CCM context
+ *          and underlying cipher sub-context.
  *
- * \param ctx       CCM context to free
+ * \param ctx       The CCM context to clear.
  */
 void mbedtls_ccm_free( mbedtls_ccm_context *ctx );
 
 /**
- * \brief           CCM buffer encryption
+ * \brief           This function encrypts a buffer using CCM.
  *
- * \param ctx       CCM context
- * \param length    length of the input data in bytes
- * \param iv        nonce (initialization vector)
- * \param iv_len    length of IV in bytes
- *                  must be 2, 3, 4, 5, 6, 7 or 8
- * \param add       additional data
- * \param add_len   length of additional data in bytes
- *                  must be less than 2^16 - 2^8
- * \param input     buffer holding the input data
- * \param output    buffer for holding the output data
- *                  must be at least 'length' bytes wide
- * \param tag       buffer for holding the tag
- * \param tag_len   length of the tag to generate in bytes
- *                  must be 4, 6, 8, 10, 14 or 16
+ * \param ctx       The CCM context to use for encryption.
+ * \param length    The length of the input data in Bytes.
+ * \param iv        Initialization vector (nonce).
+ * \param iv_len    The length of the IV in Bytes: 7, 8, 9, 10, 11, 12, or 13.
+ * \param add       The additional data field.
+ * \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 tag.
+ * \param tag_len   The length of the tag to generate in Bytes:
+ *                  4, 6, 8, 10, 12, 14 or 16.
  *
- * \note            The tag is written to a separate buffer. To get the tag
- *                  concatenated with the output as in the CCM spec, use
- *                  tag = output + length and make sure the output buffer is
- *                  at least length + tag_len wide.
+ * \note            The tag is written to a separate buffer. To concatenate
+ *                  the \p tag with the \p output, as done in <em>RFC-3610:
+ *                  Counter with CBC-MAC (CCM)</em>, use
+ *                  \p tag = \p output + \p length, and make sure that the
+ *                  output buffer is at least \p length + \p tag_len wide.
  *
- * \return          0 if successful
+ * \return          \c 0 on success.
  */
 int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length,
                          const unsigned char *iv, size_t iv_len,
@@ -107,21 +122,25 @@
                          unsigned char *tag, size_t tag_len );
 
 /**
- * \brief           CCM buffer authenticated decryption
+ * \brief           This function performs a CCM authenticated decryption of a
+ *                  buffer.
  *
- * \param ctx       CCM context
- * \param length    length of the input data
- * \param iv        initialization vector
- * \param iv_len    length of IV
- * \param add       additional data
- * \param add_len   length of additional data
- * \param input     buffer holding the input data
- * \param output    buffer for holding the output data
- * \param tag       buffer holding the tag
- * \param tag_len   length of the tag
+ * \param ctx       The CCM context to use for decryption.
+ * \param length    The length of the input data in Bytes.
+ * \param iv        Initialization vector.
+ * \param iv_len    The length of the IV in Bytes: 7, 8, 9, 10, 11, 12, or 13.
+ * \param add       The additional data field.
+ * \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 tag.
+ * \param tag_len   The length of the tag in Bytes.
+ *                  4, 6, 8, 10, 12, 14 or 16.
  *
- * \return         0 if successful and authenticated,
- *                 MBEDTLS_ERR_CCM_AUTH_FAILED if tag does not match
+ * \return          0 if successful and authenticated, or
+ *                  #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match.
  */
 int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length,
                       const unsigned char *iv, size_t iv_len,
@@ -133,9 +152,9 @@
 }
 #endif
 
-#else  /* !MBEDTLS_CCM_ALT */
+#else  /* MBEDTLS_CCM_ALT */
 #include "ccm_alt.h"
-#endif /* !MBEDTLS_CCM_ALT */
+#endif /* MBEDTLS_CCM_ALT */
 
 #ifdef __cplusplus
 extern "C" {
@@ -143,9 +162,9 @@
 
 #if defined(MBEDTLS_SELF_TEST) && defined(MBEDTLS_AES_C)
 /**
- * \brief          Checkup routine
+ * \brief          The CCM checkup routine.
  *
- * \return         0 if successful, or 1 if the test failed
+ * \return         \c 0 on success, or \c 1 on failure.
  */
 int mbedtls_ccm_self_test( int verbose );
 #endif /* MBEDTLS_SELF_TEST && MBEDTLS_AES_C */
diff --git a/include/mbedtls/certs.h b/include/mbedtls/certs.h
index ca49086..8dab7b5 100644
--- a/include/mbedtls/certs.h
+++ b/include/mbedtls/certs.h
@@ -2,7 +2,8 @@
  * \file certs.h
  *
  * \brief Sample certificates and DHM parameters for testing
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/check_config.h b/include/mbedtls/check_config.h
index fa72454..1143aa2 100644
--- a/include/mbedtls/check_config.h
+++ b/include/mbedtls/check_config.h
@@ -2,7 +2,8 @@
  * \file check_config.h
  *
  * \brief Consistency checks for configuration options
- *
+ */
+/*
  *  Copyright (C) 2006-2016, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h
index b12e388..d1f4efe 100644
--- a/include/mbedtls/cipher.h
+++ b/include/mbedtls/cipher.h
@@ -1,11 +1,12 @@
 /**
  * \file cipher.h
  *
- * \brief Generic cipher wrapper.
+ * \brief The generic cipher wrapper.
  *
  * \author Adriaan de Jong <dejong@fox-it.com>
- *
- *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ */
+/*
+ *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
@@ -20,7 +21,7 @@
  *  See the License for the specific language governing permissions and
  *  limitations under the License.
  *
- *  This file is part of mbed TLS (https://tls.mbed.org)
+ *  This file is part of Mbed TLS (https://tls.mbed.org)
  */
 
 #ifndef MBEDTLS_CIPHER_H
@@ -51,21 +52,29 @@
 #define inline __inline
 #endif
 
-#define MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE            -0x6080  /**< The selected feature is not available. */
-#define MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA                 -0x6100  /**< Bad input parameters to function. */
-#define MBEDTLS_ERR_CIPHER_ALLOC_FAILED                   -0x6180  /**< Failed to allocate memory. */
-#define MBEDTLS_ERR_CIPHER_INVALID_PADDING                -0x6200  /**< Input data contains invalid padding and is rejected. */
-#define MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED            -0x6280  /**< Decryption of block requires a full block. */
-#define MBEDTLS_ERR_CIPHER_AUTH_FAILED                    -0x6300  /**< Authentication failed (for AEAD modes). */
-#define MBEDTLS_ERR_CIPHER_INVALID_CONTEXT              -0x6380  /**< The context is invalid, eg because it was free()ed. */
+#define MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE  -0x6080  /**< The selected feature is not available. */
+#define MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA       -0x6100  /**< Bad input parameters. */
+#define MBEDTLS_ERR_CIPHER_ALLOC_FAILED         -0x6180  /**< Failed to allocate memory. */
+#define MBEDTLS_ERR_CIPHER_INVALID_PADDING      -0x6200  /**< Input data contains invalid padding and is rejected. */
+#define MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED  -0x6280  /**< Decryption of block requires a full block. */
+#define MBEDTLS_ERR_CIPHER_AUTH_FAILED          -0x6300  /**< Authentication failed (for AEAD modes). */
+#define MBEDTLS_ERR_CIPHER_INVALID_CONTEXT      -0x6380  /**< The context is invalid. For example, because it was freed. */
+#define MBEDTLS_ERR_CIPHER_HW_ACCEL_FAILED      -0x6400  /**< Cipher hardware accelerator failed. */
 
-#define MBEDTLS_CIPHER_VARIABLE_IV_LEN     0x01    /**< Cipher accepts IVs of variable length */
-#define MBEDTLS_CIPHER_VARIABLE_KEY_LEN    0x02    /**< Cipher accepts keys of variable length */
+#define MBEDTLS_CIPHER_VARIABLE_IV_LEN     0x01    /**< Cipher accepts IVs of variable length. */
+#define MBEDTLS_CIPHER_VARIABLE_KEY_LEN    0x02    /**< Cipher accepts keys of variable length. */
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/**
+ * \brief     An enumeration of supported ciphers.
+ *
+ * \warning   ARC4 and DES are considered weak ciphers and their use
+ *            constitutes a security risk. We recommend considering stronger
+ *            ciphers instead.
+ */
 typedef enum {
     MBEDTLS_CIPHER_ID_NONE = 0,
     MBEDTLS_CIPHER_ID_NULL,
@@ -77,6 +86,13 @@
     MBEDTLS_CIPHER_ID_ARC4,
 } mbedtls_cipher_id_t;
 
+/**
+ * \brief     An enumeration of supported (cipher, mode) pairs.
+ *
+ * \warning   ARC4 and DES are considered weak ciphers and their use
+ *            constitutes a security risk. We recommend considering stronger
+ *            ciphers instead.
+ */
 typedef enum {
     MBEDTLS_CIPHER_NONE = 0,
     MBEDTLS_CIPHER_NULL,
@@ -129,6 +145,7 @@
     MBEDTLS_CIPHER_CAMELLIA_256_CCM,
 } mbedtls_cipher_type_t;
 
+/** Supported cipher modes. */
 typedef enum {
     MBEDTLS_MODE_NONE = 0,
     MBEDTLS_MODE_ECB,
@@ -141,14 +158,16 @@
     MBEDTLS_MODE_CCM,
 } mbedtls_cipher_mode_t;
 
+/** Supported cipher padding types. */
 typedef enum {
-    MBEDTLS_PADDING_PKCS7 = 0,     /**< PKCS7 padding (default)        */
-    MBEDTLS_PADDING_ONE_AND_ZEROS, /**< ISO/IEC 7816-4 padding         */
-    MBEDTLS_PADDING_ZEROS_AND_LEN, /**< ANSI X.923 padding             */
-    MBEDTLS_PADDING_ZEROS,         /**< zero padding (not reversible!) */
-    MBEDTLS_PADDING_NONE,          /**< never pad (full blocks only)   */
+    MBEDTLS_PADDING_PKCS7 = 0,     /**< PKCS7 padding (default).        */
+    MBEDTLS_PADDING_ONE_AND_ZEROS, /**< ISO/IEC 7816-4 padding.         */
+    MBEDTLS_PADDING_ZEROS_AND_LEN, /**< ANSI X.923 padding.             */
+    MBEDTLS_PADDING_ZEROS,         /**< zero padding (not reversible). */
+    MBEDTLS_PADDING_NONE,          /**< never pad (full blocks only).   */
 } mbedtls_cipher_padding_t;
 
+/** Type of operation. */
 typedef enum {
     MBEDTLS_OPERATION_NONE = -1,
     MBEDTLS_DECRYPT = 0,
@@ -156,19 +175,19 @@
 } mbedtls_operation_t;
 
 enum {
-    /** Undefined key length */
+    /** Undefined key length. */
     MBEDTLS_KEY_LENGTH_NONE = 0,
-    /** Key length, in bits (including parity), for DES keys */
+    /** Key length, in bits (including parity), for DES keys. */
     MBEDTLS_KEY_LENGTH_DES  = 64,
-    /** Key length, in bits (including parity), for DES in two key EDE */
+    /** Key length in bits, including parity, for DES in two-key EDE. */
     MBEDTLS_KEY_LENGTH_DES_EDE = 128,
-    /** Key length, in bits (including parity), for DES in three-key EDE */
+    /** Key length in bits, including parity, for DES in three-key EDE. */
     MBEDTLS_KEY_LENGTH_DES_EDE3 = 192,
 };
 
-/** Maximum length of any IV, in bytes */
+/** Maximum length of any IV, in Bytes. */
 #define MBEDTLS_MAX_IV_LENGTH      16
-/** Maximum block size of any cipher, in bytes */
+/** Maximum block size of any cipher, in Bytes. */
 #define MBEDTLS_MAX_BLOCK_LENGTH   16
 
 /**
@@ -182,33 +201,40 @@
 typedef struct mbedtls_cmac_context_t mbedtls_cmac_context_t;
 
 /**
- * Cipher information. Allows cipher functions to be called in a generic way.
+ * Cipher information. Allows calling cipher functions
+ * in a generic way.
  */
 typedef struct {
-    /** Full cipher identifier (e.g. MBEDTLS_CIPHER_AES_256_CBC) */
+    /** Full cipher identifier. For example,
+     * MBEDTLS_CIPHER_AES_256_CBC.
+     */
     mbedtls_cipher_type_t type;
 
-    /** Cipher mode (e.g. MBEDTLS_MODE_CBC) */
+    /** The cipher mode. For example, MBEDTLS_MODE_CBC. */
     mbedtls_cipher_mode_t mode;
 
-    /** Cipher key length, in bits (default length for variable sized ciphers)
-     *  (Includes parity bits for ciphers like DES) */
+    /** The cipher key length, in bits. This is the
+     * default length for variable sized ciphers.
+     * Includes parity bits for ciphers like DES.
+     */
     unsigned int key_bitlen;
 
-    /** Name of the cipher */
+    /** Name of the cipher. */
     const char * name;
 
-    /** IV/NONCE size, in bytes.
-     *  For cipher that accept many sizes: recommended size */
+    /** IV or nonce size, in Bytes.
+     * For ciphers that accept variable IV sizes,
+     * this is the recommended size.
+     */
     unsigned int iv_size;
 
-    /** Flags for variable IV size, variable key size, etc. */
+    /** Flags to set. For example, if the cipher supports variable IV sizes or variable key sizes. */
     int flags;
 
-    /** block size, in bytes */
+    /** The block size, in Bytes. */
     unsigned int block_size;
 
-    /** Base cipher information and functions */
+    /** Struct for base cipher information and functions. */
     const mbedtls_cipher_base_t *base;
 
 } mbedtls_cipher_info_t;
@@ -217,125 +243,133 @@
  * Generic cipher context.
  */
 typedef struct {
-    /** Information about the associated cipher */
+    /** Information about the associated cipher. */
     const mbedtls_cipher_info_t *cipher_info;
 
-    /** Key length to use */
+    /** Key length to use. */
     int key_bitlen;
 
-    /** Operation that the context's key has been initialised for */
+    /** Operation that the key of the context has been
+     * initialized for.
+     */
     mbedtls_operation_t operation;
 
 #if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING)
-    /** Padding functions to use, if relevant for cipher mode */
+    /** Padding functions to use, if relevant for
+     * the specific cipher mode.
+     */
     void (*add_padding)( unsigned char *output, size_t olen, size_t data_len );
     int (*get_padding)( unsigned char *input, size_t ilen, size_t *data_len );
 #endif
 
-    /** Buffer for data that hasn't been encrypted yet */
+    /** Buffer for input that has not been processed yet. */
     unsigned char unprocessed_data[MBEDTLS_MAX_BLOCK_LENGTH];
 
-    /** Number of bytes that still need processing */
+    /** Number of Bytes that have not been processed yet. */
     size_t unprocessed_len;
 
-    /** Current IV or NONCE_COUNTER for CTR-mode */
+    /** Current IV or NONCE_COUNTER for CTR-mode. */
     unsigned char iv[MBEDTLS_MAX_IV_LENGTH];
 
-    /** IV size in bytes (for ciphers with variable-length IVs) */
+    /** IV size in Bytes, for ciphers with variable-length IVs. */
     size_t iv_size;
 
-    /** Cipher-specific context */
+    /** The cipher-specific context. */
     void *cipher_ctx;
 
 #if defined(MBEDTLS_CMAC_C)
-    /** CMAC Specific context */
+    /** CMAC-specific context. */
     mbedtls_cmac_context_t *cmac_ctx;
 #endif
 } mbedtls_cipher_context_t;
 
 /**
- * \brief Returns the list of ciphers supported by the generic cipher module.
+ * \brief This function retrieves the list of ciphers supported by the generic
+ * cipher module.
  *
- * \return              a statically allocated array of ciphers, the last entry
- *                      is 0.
+ * \return      A statically-allocated array of ciphers. The last entry
+ *              is zero.
  */
 const int *mbedtls_cipher_list( void );
 
 /**
- * \brief               Returns the cipher information structure associated
- *                      with the given cipher name.
+ * \brief               This function retrieves the cipher-information
+ *                      structure associated with the given cipher name.
  *
  * \param cipher_name   Name of the cipher to search for.
  *
- * \return              the cipher information structure associated with the
- *                      given cipher_name, or NULL if not found.
+ * \return              The cipher information structure associated with the
+ *                      given \p cipher_name, or NULL if not found.
  */
 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_string( const char *cipher_name );
 
 /**
- * \brief               Returns the cipher information structure associated
- *                      with the given cipher type.
+ * \brief               This function retrieves the cipher-information
+ *                      structure associated with the given cipher type.
  *
  * \param cipher_type   Type of the cipher to search for.
  *
- * \return              the cipher information structure associated with the
- *                      given cipher_type, or NULL if not found.
+ * \return              The cipher information structure associated with the
+ *                      given \p cipher_type, or NULL if not found.
  */
 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_type( const mbedtls_cipher_type_t cipher_type );
 
 /**
- * \brief               Returns the cipher information structure associated
- *                      with the given cipher id, key size and mode.
+ * \brief               This function retrieves the cipher-information
+ *                      structure associated with the given cipher ID,
+ *                      key size and mode.
  *
- * \param cipher_id     Id of the cipher to search for
- *                      (e.g. MBEDTLS_CIPHER_ID_AES)
- * \param key_bitlen    Length of the key in bits
- * \param mode          Cipher mode (e.g. MBEDTLS_MODE_CBC)
+ * \param cipher_id     The ID of the cipher to search for. For example,
+ *                      #MBEDTLS_CIPHER_ID_AES.
+ * \param key_bitlen    The length of the key in bits.
+ * \param mode          The cipher mode. For example, #MBEDTLS_MODE_CBC.
  *
- * \return              the cipher information structure associated with the
- *                      given cipher_type, or NULL if not found.
+ * \return              The cipher information structure associated with the
+ *                      given \p cipher_id, or NULL if not found.
  */
 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_values( const mbedtls_cipher_id_t cipher_id,
                                               int key_bitlen,
                                               const mbedtls_cipher_mode_t mode );
 
 /**
- * \brief               Initialize a cipher_context (as NONE)
+ * \brief               This function initializes a \p cipher_context as NONE.
  */
 void mbedtls_cipher_init( mbedtls_cipher_context_t *ctx );
 
 /**
- * \brief               Free and clear the cipher-specific context of ctx.
- *                      Freeing ctx itself remains the responsibility of the
- *                      caller.
+ * \brief               This function frees and clears the cipher-specific
+ *                      context of \p ctx. Freeing \p ctx itself remains the
+ *                      responsibility of the caller.
  */
 void mbedtls_cipher_free( mbedtls_cipher_context_t *ctx );
 
+
 /**
- * \brief               Initialises and fills the cipher context structure with
- *                      the appropriate values.
+ * \brief               This function initializes and fills the cipher-context
+ *                      structure with the appropriate values. It also clears
+ *                      the structure.
  *
- * \note                Currently also clears structure. In future versions you
- *                      will be required to call mbedtls_cipher_init() on the structure
- *                      first.
+ * \param ctx           The context to initialize. May not be NULL.
+ * \param cipher_info   The cipher to use.
  *
- * \param ctx           context to initialise. May not be NULL.
- * \param cipher_info   cipher to use.
- *
- * \return              0 on success,
- *                      MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on parameter failure,
- *                      MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the
+ * \return              \c 0 on success,
+ *                      #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on parameter failure,
+ *                      #MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the
  *                      cipher-specific context failed.
+ *
+ * \internal Currently, the function also clears the structure.
+ * In future versions, the caller will be required to call
+ * mbedtls_cipher_init() on the structure first.
  */
 int mbedtls_cipher_setup( mbedtls_cipher_context_t *ctx, const mbedtls_cipher_info_t *cipher_info );
 
 /**
- * \brief               Returns the block size of the given cipher.
+ * \brief        This function returns the block size of the given cipher.
  *
- * \param ctx           cipher's context. Must have been initialised.
+ * \param ctx    The context of the cipher. Must be initialized.
  *
- * \return              size of the cipher's blocks, or 0 if ctx has not been
- *                      initialised.
+ * \return       The size of the blocks of the cipher, or zero if \p ctx
+ *               has not been initialized.
  */
 static inline unsigned int mbedtls_cipher_get_block_size( const mbedtls_cipher_context_t *ctx )
 {
@@ -346,13 +380,13 @@
 }
 
 /**
- * \brief               Returns the mode of operation for the cipher.
- *                      (e.g. MBEDTLS_MODE_CBC)
+ * \brief        This function returns the mode of operation for
+ *               the cipher. For example, MBEDTLS_MODE_CBC.
  *
- * \param ctx           cipher's context. Must have been initialised.
+ * \param ctx    The context of the cipher. Must be initialized.
  *
- * \return              mode of operation, or MBEDTLS_MODE_NONE if ctx
- *                      has not been initialised.
+ * \return       The mode of operation, or #MBEDTLS_MODE_NONE if
+ *               \p ctx has not been initialized.
  */
 static inline mbedtls_cipher_mode_t mbedtls_cipher_get_cipher_mode( const mbedtls_cipher_context_t *ctx )
 {
@@ -363,13 +397,14 @@
 }
 
 /**
- * \brief               Returns the size of the cipher's IV/NONCE in bytes.
+ * \brief       This function returns the size of the IV or nonce
+ *              of the cipher, in Bytes.
  *
- * \param ctx           cipher's context. Must have been initialised.
+ * \param ctx   The context of the cipher. Must be initialized.
  *
- * \return              If IV has not been set yet: (recommended) IV size
- *                      (0 for ciphers not using IV/NONCE).
- *                      If IV has already been set: actual size.
+ * \return      <ul><li>If no IV has been set: the recommended IV size.
+ *              0 for ciphers not using IV or nonce.</li>
+ *              <li>If IV has already been set: the actual size.</li></ul>
  */
 static inline int mbedtls_cipher_get_iv_size( const mbedtls_cipher_context_t *ctx )
 {
@@ -383,12 +418,12 @@
 }
 
 /**
- * \brief               Returns the type of the given cipher.
+ * \brief               This function returns the type of the given cipher.
  *
- * \param ctx           cipher's context. Must have been initialised.
+ * \param ctx           The context of the cipher. Must be initialized.
  *
- * \return              type of the cipher, or MBEDTLS_CIPHER_NONE if ctx has
- *                      not been initialised.
+ * \return              The type of the cipher, or #MBEDTLS_CIPHER_NONE if
+ *                      \p ctx has not been initialized.
  */
 static inline mbedtls_cipher_type_t mbedtls_cipher_get_type( const mbedtls_cipher_context_t *ctx )
 {
@@ -399,11 +434,13 @@
 }
 
 /**
- * \brief               Returns the name of the given cipher, as a string.
+ * \brief               This function returns the name of the given cipher
+ *                      as a string.
  *
- * \param ctx           cipher's context. Must have been initialised.
+ * \param ctx           The context of the cipher. Must be initialized.
  *
- * \return              name of the cipher, or NULL if ctx was not initialised.
+ * \return              The name of the cipher, or NULL if \p ctx has not
+ *                      been not initialized.
  */
 static inline const char *mbedtls_cipher_get_name( const mbedtls_cipher_context_t *ctx )
 {
@@ -414,13 +451,13 @@
 }
 
 /**
- * \brief               Returns the key length of the cipher.
+ * \brief               This function returns the key length of the cipher.
  *
- * \param ctx           cipher's context. Must have been initialised.
+ * \param ctx           The context of the cipher. Must be initialized.
  *
- * \return              cipher's key length, in bits, or
- *                      MBEDTLS_KEY_LENGTH_NONE if ctx has not been
- *                      initialised.
+ * \return              The key length of the cipher in bits, or
+ *                      #MBEDTLS_KEY_LENGTH_NONE if ctx \p has not been
+ *                      initialized.
  */
 static inline int mbedtls_cipher_get_key_bitlen( const mbedtls_cipher_context_t *ctx )
 {
@@ -431,13 +468,13 @@
 }
 
 /**
- * \brief               Returns the operation of the given cipher.
+ * \brief          This function returns the operation of the given cipher.
  *
- * \param ctx           cipher's context. Must have been initialised.
+ * \param ctx      The context of the cipher. Must be initialized.
  *
- * \return              operation (MBEDTLS_ENCRYPT or MBEDTLS_DECRYPT),
- *                      or MBEDTLS_OPERATION_NONE if ctx has not been
- *                      initialised.
+ * \return         The type of operation: #MBEDTLS_ENCRYPT or
+ *                 #MBEDTLS_DECRYPT, or #MBEDTLS_OPERATION_NONE if \p ctx
+ *                 has not been initialized.
  */
 static inline mbedtls_operation_t mbedtls_cipher_get_operation( const mbedtls_cipher_context_t *ctx )
 {
@@ -448,18 +485,18 @@
 }
 
 /**
- * \brief               Set the key to use with the given context.
+ * \brief               This function sets the key to use with the given context.
  *
- * \param ctx           generic cipher context. May not be NULL. Must have been
- *                      initialised using cipher_context_from_type or
- *                      cipher_context_from_string.
+ * \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    key length to use, in bits.
- * \param operation     Operation that the key will be used for, either
- *                      MBEDTLS_ENCRYPT or MBEDTLS_DECRYPT.
+ * \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.
  *
- * \returns             0 on success, MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
- *                      parameter verification fails or a cipher specific
+ * \returns             \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
+ *                      parameter verification fails, or a cipher-specific
  *                      error code.
  */
 int mbedtls_cipher_setkey( mbedtls_cipher_context_t *ctx, const unsigned char *key,
@@ -467,170 +504,176 @@
 
 #if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING)
 /**
- * \brief               Set padding mode, for cipher modes that use padding.
- *                      (Default: PKCS7 padding.)
+ * \brief               This function sets the padding mode, for cipher modes
+ *                      that use padding.
  *
- * \param ctx           generic cipher context
- * \param mode          padding mode
+ *                      The default passing mode is PKCS7 padding.
  *
- * \returns             0 on success, MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE
- *                      if selected padding mode is not supported, or
- *                      MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode
+ * \param ctx           The generic cipher context.
+ * \param mode          The padding mode.
+ *
+ * \returns             \c 0 on success, #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE
+ *                      if the selected padding mode is not supported, or
+ *                      #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode
  *                      does not support padding.
  */
 int mbedtls_cipher_set_padding_mode( mbedtls_cipher_context_t *ctx, mbedtls_cipher_padding_t mode );
 #endif /* MBEDTLS_CIPHER_MODE_WITH_PADDING */
 
 /**
- * \brief               Set the initialization vector (IV) or nonce
+ * \brief           This function sets the initialization vector (IV)
+ *                  or nonce.
  *
- * \param ctx           generic cipher context
- * \param iv            IV to use (or NONCE_COUNTER for CTR-mode ciphers)
- * \param iv_len        IV length for ciphers with variable-size IV;
- *                      discarded by ciphers with fixed-size IV.
+ * \param ctx       The generic cipher context.
+ * \param iv        The IV to use, or NONCE_COUNTER for CTR-mode ciphers.
+ * \param iv_len    The IV length for ciphers with variable-size IV.
+ *                  This parameter is discarded by ciphers with fixed-size IV.
  *
- * \returns             0 on success, or MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA
+ * \returns         \c 0 on success, or #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA
  *
- * \note                Some ciphers don't use IVs nor NONCE. For these
- *                      ciphers, this function has no effect.
+ * \note            Some ciphers do not use IVs nor nonce. For these
+ *                  ciphers, this function has no effect.
  */
 int mbedtls_cipher_set_iv( mbedtls_cipher_context_t *ctx,
                    const unsigned char *iv, size_t iv_len );
 
 /**
- * \brief               Finish preparation of the given context
+ * \brief         This function resets the cipher state.
  *
- * \param ctx           generic cipher context
+ * \param ctx     The generic cipher context.
  *
- * \returns             0 on success, MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA
- *                      if parameter verification fails.
+ * \returns       \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA
+ *                if parameter verification fails.
  */
 int mbedtls_cipher_reset( mbedtls_cipher_context_t *ctx );
 
 #if defined(MBEDTLS_GCM_C)
 /**
- * \brief               Add additional data (for AEAD ciphers).
- *                      Currently only supported with GCM.
- *                      Must be called exactly once, after mbedtls_cipher_reset().
+ * \brief               This function adds additional data for AEAD ciphers.
+ *                      Only supported with GCM. Must be called
+ *                      exactly once, after mbedtls_cipher_reset().
  *
- * \param ctx           generic cipher context
- * \param ad            Additional data to use.
- * \param ad_len        Length of ad.
+ * \param ctx           The generic cipher context.
+ * \param ad            The additional data to use.
+ * \param ad_len        the Length of \p ad.
  *
- * \return              0 on success, or a specific error code.
+ * \return              \c 0 on success, or a specific error code on failure.
  */
 int mbedtls_cipher_update_ad( mbedtls_cipher_context_t *ctx,
                       const unsigned char *ad, size_t ad_len );
 #endif /* MBEDTLS_GCM_C */
 
 /**
- * \brief               Generic cipher update function. Encrypts/decrypts
- *                      using the given cipher context. Writes as many block
- *                      size'd blocks of data as possible to output. Any data
- *                      that cannot be written immediately will either be added
- *                      to the next block, or flushed when cipher_final is
- *                      called.
- *                      Exception: for MBEDTLS_MODE_ECB, expects single block
- *                                 in size (e.g. 16 bytes for AES)
+ * \brief               The generic cipher update function. It encrypts or
+ *                      decrypts using the given cipher context. Writes as
+ *                      many block-sized blocks of data as possible to output.
+ *                      Any data that cannot be written immediately is either
+ *                      added to the next block, or flushed when
+ *                      mbedtls_cipher_finish() is called.
+ *                      Exception: For MBEDTLS_MODE_ECB, expects a single block
+ *                      in size. For example, 16 Bytes for AES.
  *
- * \param ctx           generic cipher context
- * \param input         buffer holding the input data
- * \param ilen          length of the input data
- * \param output        buffer for the output data. Should be able to hold at
- *                      least ilen + block_size. Cannot be the same buffer as
- *                      input!
- * \param olen          length of the output data, will be filled with the
- *                      actual number of bytes written.
+ * \param ctx           The generic cipher context.
+ * \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 olen          The length of the output data, to be updated with the
+ *                      actual number of Bytes written.
  *
- * \returns             0 on success, MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
+ * \returns             \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
  *                      parameter verification fails,
- *                      MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE on an
- *                      unsupported mode for a cipher or a cipher specific
+ *                      #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE on an
+ *                      unsupported mode for a cipher, or a cipher-specific
  *                      error code.
  *
  * \note                If the underlying cipher is GCM, all calls to this
- *                      function, except the last one before mbedtls_cipher_finish(),
- *                      must have ilen a multiple of the block size.
+ *                      function, except the last one before
+ *                      mbedtls_cipher_finish(). Must have \p ilen as a
+ *                      multiple of the block_size.
  */
 int mbedtls_cipher_update( mbedtls_cipher_context_t *ctx, const unsigned char *input,
                    size_t ilen, unsigned char *output, size_t *olen );
 
 /**
- * \brief               Generic cipher finalisation function. If data still
- *                      needs to be flushed from an incomplete block, data
- *                      contained within it will be padded with the size of
- *                      the last block, and written to the output buffer.
+ * \brief               The generic cipher finalization function. If data still
+ *                      needs to be flushed from an incomplete block, the data
+ *                      contained in it is padded to the size of
+ *                      the last block, and written to the \p output buffer.
  *
- * \param ctx           Generic cipher context
- * \param output        buffer to write data to. Needs block_size available.
- * \param olen          length of the data written to the output buffer.
+ * \param ctx           The generic cipher context.
+ * \param output        The buffer to write data to. Needs block_size available.
+ * \param olen          The length of the data written to the \p output buffer.
  *
- * \returns             0 on success, MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
+ * \returns             \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
  *                      parameter verification fails,
- *                      MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption
+ *                      #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption
  *                      expected a full block but was not provided one,
- *                      MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
- *                      while decrypting or a cipher specific error code.
+ *                      #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
+ *                      while decrypting, or a cipher-specific error code
+ *                      on failure for any other reason.
  */
 int mbedtls_cipher_finish( mbedtls_cipher_context_t *ctx,
                    unsigned char *output, size_t *olen );
 
 #if defined(MBEDTLS_GCM_C)
 /**
- * \brief               Write tag for AEAD ciphers.
- *                      Currently only supported with GCM.
+ * \brief               This function writes a tag for AEAD ciphers.
+ *                      Only supported with GCM.
  *                      Must be called after mbedtls_cipher_finish().
  *
- * \param ctx           Generic cipher context
- * \param tag           buffer to write the tag
- * \param tag_len       Length of the tag to write
+ * \param ctx           The generic cipher context.
+ * \param tag           The buffer to write the tag to.
+ * \param tag_len       The length of the tag to write.
  *
- * \return              0 on success, or a specific error code.
+ * \return              \c 0 on success, or a specific error code on failure.
  */
 int mbedtls_cipher_write_tag( mbedtls_cipher_context_t *ctx,
                       unsigned char *tag, size_t tag_len );
 
 /**
- * \brief               Check tag for AEAD ciphers.
- *                      Currently only supported with GCM.
+ * \brief               This function checks the tag for AEAD ciphers.
+ *                      Only supported with GCM.
  *                      Must be called after mbedtls_cipher_finish().
  *
- * \param ctx           Generic cipher context
- * \param tag           Buffer holding the tag
- * \param tag_len       Length of the tag to check
+ * \param ctx           The generic cipher context.
+ * \param tag           The buffer holding the tag.
+ * \param tag_len       The length of the tag to check.
  *
- * \return              0 on success, or a specific error code.
+ * \return              \c 0 on success, or a specific error code on failure.
  */
 int mbedtls_cipher_check_tag( mbedtls_cipher_context_t *ctx,
                       const unsigned char *tag, size_t tag_len );
 #endif /* MBEDTLS_GCM_C */
 
 /**
- * \brief               Generic all-in-one encryption/decryption
- *                      (for all ciphers except AEAD constructs).
+ * \brief               The generic all-in-one encryption/decryption function,
+ *                      for all ciphers except AEAD constructs.
  *
- * \param ctx           generic cipher context
- * \param iv            IV to use (or NONCE_COUNTER for CTR-mode ciphers)
- * \param iv_len        IV length for ciphers with variable-size IV;
- *                      discarded by ciphers with fixed-size IV.
- * \param input         buffer holding the input data
- * \param ilen          length of the input data
- * \param output        buffer for the output data. Should be able to hold at
- *                      least ilen + block_size. Cannot be the same buffer as
- *                      input!
- * \param olen          length of the output data, will be filled with the
- *                      actual number of bytes written.
+ * \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 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 olen          The length of the output data, to be updated with the
+ *                      actual number of Bytes written.
  *
- * \note                Some ciphers don't use IVs nor NONCE. For these
- *                      ciphers, use iv = NULL and iv_len = 0.
+ * \note                Some ciphers do not use IVs nor nonce. For these
+ *                      ciphers, use \p iv = NULL and \p iv_len = 0.
  *
- * \returns             0 on success, or
- *                      MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
- *                      MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption
+ * \returns             \c 0 on success, or
+ *                      #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
+ *                      #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption
  *                      expected a full block but was not provided one, or
- *                      MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
- *                      while decrypting, or
- *                      a cipher specific error code.
+ *                      #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
+ *                      while decrypting, or a cipher-specific error code on
+ *                      failure for any other reason.
  */
 int mbedtls_cipher_crypt( mbedtls_cipher_context_t *ctx,
                   const unsigned char *iv, size_t iv_len,
@@ -639,26 +682,26 @@
 
 #if defined(MBEDTLS_CIPHER_MODE_AEAD)
 /**
- * \brief               Generic autenticated encryption (AEAD ciphers).
+ * \brief               The generic autenticated encryption (AEAD) function.
  *
- * \param ctx           generic cipher context
- * \param iv            IV to use (or NONCE_COUNTER for CTR-mode ciphers)
- * \param iv_len        IV length for ciphers with variable-size IV;
- *                      discarded by ciphers with fixed-size IV.
- * \param ad            Additional data to authenticate.
- * \param ad_len        Length of ad.
- * \param input         buffer holding the input data
- * \param ilen          length of the input data
- * \param output        buffer for the output data.
- *                      Should be able to hold at least ilen.
- * \param olen          length of the output data, will be filled with the
- *                      actual number of bytes written.
- * \param tag           buffer for the authentication tag
- * \param tag_len       desired tag length
+ * \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.
  *
- * \returns             0 on success, or
- *                      MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
- *                      a cipher specific error code.
+ * \returns             \c 0 on success, or
+ *                      #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
+ *                      a cipher-specific error code.
  */
 int mbedtls_cipher_auth_encrypt( mbedtls_cipher_context_t *ctx,
                          const unsigned char *iv, size_t iv_len,
@@ -668,31 +711,31 @@
                          unsigned char *tag, size_t tag_len );
 
 /**
- * \brief               Generic autenticated decryption (AEAD ciphers).
+ * \brief               The generic autenticated decryption (AEAD) function.
  *
- * \param ctx           generic cipher context
- * \param iv            IV to use (or NONCE_COUNTER for CTR-mode ciphers)
- * \param iv_len        IV length for ciphers with variable-size IV;
- *                      discarded by ciphers with fixed-size IV.
- * \param ad            Additional data to be authenticated.
- * \param ad_len        Length of ad.
- * \param input         buffer holding the input data
- * \param ilen          length of the input data
- * \param output        buffer for the output data.
- *                      Should be able to hold at least ilen.
- * \param olen          length of the output data, will be filled with the
- *                      actual number of bytes written.
- * \param tag           buffer holding the authentication tag
- * \param tag_len       length of the authentication tag
+ * \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.
  *
- * \returns             0 on success, or
- *                      MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
- *                      MBEDTLS_ERR_CIPHER_AUTH_FAILED if data isn't authentic,
- *                      or a cipher specific error code.
+ * \returns             \c 0 on success, or
+ *                      #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
+ *                      #MBEDTLS_ERR_CIPHER_AUTH_FAILED if data is not authentic,
+ *                      or a cipher-specific error code on failure for any other reason.
  *
  * \note                If the data is not authentic, then the output buffer
- *                      is zeroed out to prevent the unauthentic plaintext to
- *                      be used by mistake, making this interface safer.
+ *                      is zeroed out to prevent the unauthentic plaintext being
+ *                      used, making this interface safer.
  */
 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 6c58bcc..969ff9c 100644
--- a/include/mbedtls/cipher_internal.h
+++ b/include/mbedtls/cipher_internal.h
@@ -4,7 +4,8 @@
  * \brief Cipher wrappers.
  *
  * \author Adriaan de Jong <dejong@fox-it.com>
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/cmac.h b/include/mbedtls/cmac.h
index 4d3f2d2..628c9da 100644
--- a/include/mbedtls/cmac.h
+++ b/include/mbedtls/cmac.h
@@ -1,10 +1,11 @@
 /**
  * \file cmac.h
  *
- * \brief Cipher-based Message Authentication Code (CMAC) Mode for
- *        Authentication
- *
- *  Copyright (C) 2015-2016, ARM Limited, All Rights Reserved
+ * \brief The Cipher-based Message Authentication Code (CMAC) Mode for
+ *        Authentication.
+ */
+/*
+ *  Copyright (C) 2015-2018, Arm Limited (or its affiliates), All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
@@ -19,8 +20,9 @@
  *  See the License for the specific language governing permissions and
  *  limitations under the License.
  *
- *  This file is part of mbed TLS (https://tls.mbed.org)
+ *  This file is part of Mbed TLS (https://tls.mbed.org)
  */
+
 #ifndef MBEDTLS_CMAC_H
 #define MBEDTLS_CMAC_H
 
@@ -30,108 +32,125 @@
 extern "C" {
 #endif
 
+#define MBEDTLS_ERR_CMAC_HW_ACCEL_FAILED -0x007A  /**< CMAC hardware accelerator failed. */
+
 #define MBEDTLS_AES_BLOCK_SIZE          16
 #define MBEDTLS_DES3_BLOCK_SIZE         8
 
 #if defined(MBEDTLS_AES_C)
-#define MBEDTLS_CIPHER_BLKSIZE_MAX      16  /* longest used by CMAC is AES */
+#define MBEDTLS_CIPHER_BLKSIZE_MAX      16  /* The longest block used by CMAC is that of AES. */
 #else
-#define MBEDTLS_CIPHER_BLKSIZE_MAX      8   /* longest used by CMAC is 3DES */
+#define MBEDTLS_CIPHER_BLKSIZE_MAX      8   /* The longest block used by CMAC is that of 3DES. */
 #endif
 
 #if !defined(MBEDTLS_CMAC_ALT)
 
 /**
- * CMAC context structure - Contains internal state information only
+ * The CMAC context structure.
  */
 struct mbedtls_cmac_context_t
 {
-    /** Internal state of the CMAC algorithm  */
+    /** The internal state of the CMAC algorithm.  */
     unsigned char       state[MBEDTLS_CIPHER_BLKSIZE_MAX];
 
     /** Unprocessed data - either data that was not block aligned and is still
-     *  pending to be processed, or the final block */
+     *  pending processing, or the final block. */
     unsigned char       unprocessed_block[MBEDTLS_CIPHER_BLKSIZE_MAX];
 
-    /** Length of data pending to be processed */
+    /** The length of data pending processing. */
     size_t              unprocessed_len;
 };
 
 /**
- * \brief               Set the CMAC key and prepare to authenticate the input
- *                      data.
- *                      Should be called with an initialized cipher context.
+ * \brief               This function sets the CMAC key, and prepares to authenticate
+ *                      the input data.
+ *                      Must be called with an initialized cipher context.
  *
- * \param ctx           Cipher context. This should be a cipher context,
- *                      initialized to be one of the following types:
- *                      MBEDTLS_CIPHER_AES_128_ECB, MBEDTLS_CIPHER_AES_192_ECB,
- *                      MBEDTLS_CIPHER_AES_256_ECB or
- *                      MBEDTLS_CIPHER_DES_EDE3_ECB.
- * \param key           CMAC key
- * \param keybits       length of the CMAC key in bits
- *                      (must be acceptable by the cipher)
+ * \param ctx           The cipher context used for the CMAC operation, initialized
+ *                      as one of the following types:<ul>
+ *                      <li>MBEDTLS_CIPHER_AES_128_ECB</li>
+ *                      <li>MBEDTLS_CIPHER_AES_192_ECB</li>
+ *                      <li>MBEDTLS_CIPHER_AES_256_ECB</li>
+ *                      <li>MBEDTLS_CIPHER_DES_EDE3_ECB</li></ul>
+ * \param key           The CMAC key.
+ * \param keybits       The length of the CMAC key in bits.
+ *                      Must be supported by the cipher.
  *
- * \return              0 if successful, or a cipher specific error code
+ * \return              \c 0 on success, or a cipher-specific error code.
  */
 int mbedtls_cipher_cmac_starts( mbedtls_cipher_context_t *ctx,
                                 const unsigned char *key, size_t keybits );
 
 /**
- * \brief               Generic CMAC process buffer.
- *                      Called between mbedtls_cipher_cmac_starts() or
- *                      mbedtls_cipher_cmac_reset() and
- *                      mbedtls_cipher_cmac_finish().
- *                      May be called repeatedly.
+ * \brief               This function feeds an input buffer into an ongoing CMAC
+ *                      computation.
  *
- * \param ctx           CMAC context
- * \param input         buffer holding the  data
- * \param ilen          length of the input data
+ *                      It is called between mbedtls_cipher_cmac_starts() or
+ *                      mbedtls_cipher_cmac_reset(), and mbedtls_cipher_cmac_finish().
+ *                      Can be called repeatedly.
  *
- * \returns             0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- *                      verification fails.
+ * \param ctx           The cipher context used for the CMAC operation.
+ * \param input         The buffer holding the input data.
+ * \param ilen          The length of the input data.
+ *
+ * \returns             \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
+ *                      if parameter verification fails.
  */
 int mbedtls_cipher_cmac_update( mbedtls_cipher_context_t *ctx,
                                 const unsigned char *input, size_t ilen );
 
 /**
- * \brief               Output CMAC.
- *                      Called after mbedtls_cipher_cmac_update().
- *                      Usually followed by mbedtls_cipher_cmac_reset(), then
- *                      mbedtls_cipher_cmac_starts(), or mbedtls_cipher_free().
+ * \brief               This function finishes the CMAC operation, and writes
+ *                      the result to the output buffer.
  *
- * \param ctx           CMAC context
- * \param output        Generic CMAC checksum result
+ *                      It is called after mbedtls_cipher_cmac_update().
+ *                      It can be followed by mbedtls_cipher_cmac_reset() and
+ *                      mbedtls_cipher_cmac_update(), or mbedtls_cipher_free().
  *
- * \returns             0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- *                      verification fails.
+ * \param ctx           The cipher context used for the CMAC operation.
+ * \param output        The output buffer for the CMAC checksum result.
+ *
+ * \returns             \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
+ *                      if parameter verification fails.
  */
 int mbedtls_cipher_cmac_finish( mbedtls_cipher_context_t *ctx,
                                 unsigned char *output );
 
 /**
- * \brief               Prepare to authenticate a new message with the same key.
- *                      Called after mbedtls_cipher_cmac_finish() and before
- *                      mbedtls_cipher_cmac_update().
+ * \brief               This function prepares the authentication of another
+ *                      message with the same key as the previous CMAC
+ *                      operation.
  *
- * \param ctx           CMAC context to be reset
+ *                      It is called after mbedtls_cipher_cmac_finish()
+ *                      and before mbedtls_cipher_cmac_update().
  *
- * \returns             0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- *                      verification fails.
+ * \param ctx           The cipher context used for the CMAC operation.
+ *
+ * \returns             \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
+ *                      if parameter verification fails.
  */
 int mbedtls_cipher_cmac_reset( mbedtls_cipher_context_t *ctx );
 
 /**
- * \brief               Output = Generic_CMAC( cmac key, input buffer )
+ * \brief               This function calculates the full generic CMAC
+ *                      on the input buffer with the provided key.
  *
- * \param cipher_info   message digest info
- * \param key           CMAC key
- * \param keylen        length of the CMAC key in bits
- * \param input         buffer holding the  data
- * \param ilen          length of the input data
- * \param output        Generic CMAC-result
+ *                      The function allocates the context, performs the
+ *                      calculation, and frees the context.
  *
- * \returns             0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- *                      verification fails.
+ *                      The CMAC result is calculated as
+ *                      output = generic CMAC(cmac key, input buffer).
+ *
+ *
+ * \param cipher_info   The cipher information.
+ * \param key           The CMAC key.
+ * \param keylen        The length of the CMAC key in bits.
+ * \param input         The buffer holding the input data.
+ * \param ilen          The length of the input data.
+ * \param output        The buffer for the generic CMAC result.
+ *
+ * \returns             \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
+ *                      if parameter verification fails.
  */
 int mbedtls_cipher_cmac( const mbedtls_cipher_info_t *cipher_info,
                          const unsigned char *key, size_t keylen,
@@ -140,16 +159,21 @@
 
 #if defined(MBEDTLS_AES_C)
 /**
- * \brief           AES-CMAC-128-PRF
- *                  Implementation of (AES-CMAC-PRF-128), as defined in RFC 4615
+ * \brief           This function implements the AES-CMAC-PRF-128 pseudorandom
+ *                  function, as defined in
+ *                  <em>RFC-4615: The Advanced Encryption Standard-Cipher-based
+ *                  Message Authentication Code-Pseudo-Random Function-128
+ *                  (AES-CMAC-PRF-128) Algorithm for the Internet Key
+ *                  Exchange Protocol (IKE).</em>
  *
- * \param key       PRF key
- * \param key_len   PRF key length in bytes
- * \param input     buffer holding the input data
- * \param in_len    length of the input data in bytes
- * \param output    buffer holding the generated pseudorandom output (16 bytes)
+ * \param key       The key to use.
+ * \param key_len   The key length in Bytes.
+ * \param input     The buffer holding the input data.
+ * \param in_len    The length of the input data in Bytes.
+ * \param output    The buffer holding the generated 16 Bytes of
+ *                  pseudorandom output.
  *
- * \return          0 if successful
+ * \return          \c 0 on success.
  */
 int mbedtls_aes_cmac_prf_128( const unsigned char *key, size_t key_len,
                               const unsigned char *input, size_t in_len,
@@ -170,9 +194,9 @@
 
 #if defined(MBEDTLS_SELF_TEST) && ( defined(MBEDTLS_AES_C) || defined(MBEDTLS_DES_C) )
 /**
- * \brief          Checkup routine
+ * \brief          The CMAC checkup routine.
  *
- * \return         0 if successful, or 1 if the test failed
+ * \return         \c 0 on success, or \c 1 on failure.
  */
 int mbedtls_cmac_self_test( int verbose );
 #endif /* MBEDTLS_SELF_TEST && ( MBEDTLS_AES_C || MBEDTLS_DES_C ) */
diff --git a/include/mbedtls/compat-1.3.h b/include/mbedtls/compat-1.3.h
index bba1d2c..600a0f1 100644
--- a/include/mbedtls/compat-1.3.h
+++ b/include/mbedtls/compat-1.3.h
@@ -5,7 +5,8 @@
  *  for the PolarSSL naming conventions.
  *
  * \deprecated Use the new names directly instead
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h
index 4933108..79eedff 100644
--- a/include/mbedtls/config.h
+++ b/include/mbedtls/config.h
@@ -6,7 +6,8 @@
  *  This set of compile-time options may be used to enable
  *  or disable features selectively, and reduce the global
  *  memory footprint.
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
@@ -261,6 +262,12 @@
  *
  * Uncomment a macro to enable alternate implementation of the corresponding
  * module.
+ *
+ * \warning   MD2, MD4, MD5, ARC4, DES and SHA-1 are considered weak and their
+ *            use constitutes a security risk. If possible, we recommend
+ *            avoiding dependencies on them, and considering stronger message
+ *            digests and ciphers instead.
+ *
  */
 //#define MBEDTLS_AES_ALT
 //#define MBEDTLS_ARC4_ALT
@@ -269,6 +276,8 @@
 //#define MBEDTLS_CCM_ALT
 //#define MBEDTLS_CMAC_ALT
 //#define MBEDTLS_DES_ALT
+//#define MBEDTLS_DHM_ALT
+//#define MBEDTLS_ECJPAKE_ALT
 //#define MBEDTLS_GCM_ALT
 //#define MBEDTLS_MD2_ALT
 //#define MBEDTLS_MD4_ALT
@@ -318,6 +327,12 @@
  *
  * Uncomment a macro to enable alternate implementation of the corresponding
  * function.
+ *
+ * \warning   MD2, MD4, MD5, DES and SHA-1 are considered weak and their use
+ *            constitutes a security risk. If possible, we recommend avoiding
+ *            dependencies on them, and considering stronger message digests
+ *            and ciphers instead.
+ *
  */
 //#define MBEDTLS_MD2_PROCESS_ALT
 //#define MBEDTLS_MD4_PROCESS_ALT
@@ -522,6 +537,9 @@
  *      MBEDTLS_TLS_DHE_RSA_WITH_DES_CBC_SHA
  *
  * Uncomment this macro to enable weak ciphersuites
+ *
+ * \warning   DES is considered a weak cipher and its use constitutes a
+ *            security risk. We recommend considering stronger ciphers instead.
  */
 //#define MBEDTLS_ENABLE_WEAK_CIPHERSUITES
 
@@ -627,6 +645,13 @@
  *      MBEDTLS_TLS_DHE_PSK_WITH_CAMELLIA_128_CBC_SHA256
  *      MBEDTLS_TLS_DHE_PSK_WITH_3DES_EDE_CBC_SHA
  *      MBEDTLS_TLS_DHE_PSK_WITH_RC4_128_SHA
+ *
+ * \warning    Using DHE constitutes a security risk as it
+ *             is not possible to validate custom DH parameters.
+ *             If possible, it is recommended users should consider
+ *             preferring other methods of key exchange.
+ *             See dhm.h for more details.
+ *
  */
 #define MBEDTLS_KEY_EXCHANGE_DHE_PSK_ENABLED
 
@@ -726,6 +751,13 @@
  *      MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA256
  *      MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA
  *      MBEDTLS_TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA
+ *
+ * \warning    Using DHE constitutes a security risk as it
+ *             is not possible to validate custom DH parameters.
+ *             If possible, it is recommended users should consider
+ *             preferring other methods of key exchange.
+ *             See dhm.h for more details.
+ *
  */
 #define MBEDTLS_KEY_EXCHANGE_DHE_RSA_ENABLED
 
@@ -1612,6 +1644,11 @@
  *      MBEDTLS_TLS_RSA_WITH_RC4_128_MD5
  *      MBEDTLS_TLS_RSA_PSK_WITH_RC4_128_SHA
  *      MBEDTLS_TLS_PSK_WITH_RC4_128_SHA
+ *
+ * \warning   ARC4 is considered a weak cipher and its use constitutes a
+ *            security risk. If possible, we recommend avoidng dependencies on
+ *            it, and considering stronger ciphers instead.
+ *
  */
 #define MBEDTLS_ARC4_C
 
@@ -1838,6 +1875,9 @@
  *      MBEDTLS_TLS_PSK_WITH_3DES_EDE_CBC_SHA
  *
  * PEM_PARSE uses DES/3DES for decrypting encrypted keys.
+ *
+ * \warning   DES is considered a weak cipher and its use constitutes a
+ *            security risk. We recommend considering stronger ciphers instead.
  */
 #define MBEDTLS_DES_C
 
@@ -1852,6 +1892,13 @@
  *
  * This module is used by the following key exchanges:
  *      DHE-RSA, DHE-PSK
+ *
+ * \warning    Using DHE constitutes a security risk as it
+ *             is not possible to validate custom DH parameters.
+ *             If possible, it is recommended users should consider
+ *             preferring other methods of key exchange.
+ *             See dhm.h for more details.
+ *
  */
 #define MBEDTLS_DHM_C
 
@@ -2017,6 +2064,11 @@
  * Caller:
  *
  * Uncomment to enable support for (rare) MD2-signed X.509 certs.
+ *
+ * \warning   MD2 is considered a weak message digest and its use constitutes a
+ *            security risk. If possible, we recommend avoiding dependencies on
+ *            it, and considering stronger message digests instead.
+ *
  */
 //#define MBEDTLS_MD2_C
 
@@ -2029,6 +2081,11 @@
  * Caller:
  *
  * Uncomment to enable support for (rare) MD4-signed X.509 certs.
+ *
+ * \warning   MD4 is considered a weak message digest and its use constitutes a
+ *            security risk. If possible, we recommend avoiding dependencies on
+ *            it, and considering stronger message digests instead.
+ *
  */
 //#define MBEDTLS_MD4_C
 
@@ -2042,8 +2099,15 @@
  *          library/pem.c
  *          library/ssl_tls.c
  *
- * This module is required for SSL/TLS and X.509.
- * PEM_PARSE uses MD5 for decrypting encrypted keys.
+ * This module is required for SSL/TLS up to version 1.1, and for TLS 1.2
+ * depending on the handshake parameters. Further, it is used for checking
+ * MD5-signed certificates, and for PBKDF1 when decrypting PEM-encoded
+ * encrypted keys.
+ *
+ * \warning   MD5 is considered a weak message digest and its use constitutes a
+ *            security risk. If possible, we recommend avoiding dependencies on
+ *            it, and considering stronger message digests instead.
+ *
  */
 #define MBEDTLS_MD5_C
 
@@ -2306,6 +2370,11 @@
  *
  * This module is required for SSL/TLS up to version 1.1, for TLS 1.2
  * depending on the handshake parameters, and for SHA1-signed certificates.
+ *
+ * \warning   SHA-1 is considered a weak message digest and its use constitutes
+ *            a security risk. If possible, we recommend avoiding dependencies
+ *            on it, and considering stronger message digests instead.
+ *
  */
 #define MBEDTLS_SHA1_C
 
@@ -2694,8 +2763,13 @@
  * Allow SHA-1 in the default TLS configuration for certificate signing.
  * Without this build-time option, SHA-1 support must be activated explicitly
  * through mbedtls_ssl_conf_cert_profile. Turning on this option is not
- * recommended because of it is possible to generte SHA-1 collisions, however
+ * recommended because of it is possible to generate SHA-1 collisions, however
  * this may be safe for legacy infrastructure where additional controls apply.
+ *
+ * \warning   SHA-1 is considered a weak message digest and its use constitutes
+ *            a security risk. If possible, we recommend avoiding dependencies
+ *            on it, and considering stronger message digests instead.
+ *
  */
 // #define MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES
 
@@ -2706,7 +2780,13 @@
  * The use of SHA-1 in TLS <= 1.1 and in HMAC-SHA-1 is always allowed by
  * default. At the time of writing, there is no practical attack on the use
  * of SHA-1 in handshake signatures, hence this option is turned on by default
- * for compatibility with existing peers.
+ * to preserve compatibility with existing peers, but the general
+ * warning applies nonetheless:
+ *
+ * \warning   SHA-1 is considered a weak message digest and its use constitutes
+ *            a security risk. If possible, we recommend avoiding dependencies
+ *            on it, and considering stronger message digests instead.
+ *
  */
 #define MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_KEY_EXCHANGE
 
diff --git a/include/mbedtls/ctr_drbg.h b/include/mbedtls/ctr_drbg.h
index 059d3c5..121575a 100644
--- a/include/mbedtls/ctr_drbg.h
+++ b/include/mbedtls/ctr_drbg.h
@@ -1,9 +1,13 @@
 /**
  * \file ctr_drbg.h
  *
- * \brief CTR_DRBG based on AES-256 (NIST SP 800-90)
+ * \brief    CTR_DRBG is based on AES-256, as defined in <em>NIST SP 800-90A:
+ *           Recommendation for Random Number Generation Using Deterministic
+ *           Random Bit Generators</em>.
  *
- *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ */
+/*
+ *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
@@ -18,8 +22,9 @@
  *  See the License for the specific language governing permissions and
  *  limitations under the License.
  *
- *  This file is part of mbed TLS (https://tls.mbed.org)
+ *  This file is part of Mbed TLS (https://tls.mbed.org)
  */
+
 #ifndef MBEDTLS_CTR_DRBG_H
 #define MBEDTLS_CTR_DRBG_H
 
@@ -30,78 +35,95 @@
 #endif
 
 #define MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED        -0x0034  /**< The entropy source failed. */
-#define MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG              -0x0036  /**< Too many random requested in single call. */
-#define MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG                -0x0038  /**< Input too large (Entropy + additional). */
-#define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR                -0x003A  /**< Read/write error in file. */
+#define MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG              -0x0036  /**< The requested random buffer length is too big. */
+#define MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG                -0x0038  /**< The input (entropy + additional data) is too large. */
+#define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR                -0x003A  /**< Read or write error in file. */
 
-#define MBEDTLS_CTR_DRBG_BLOCKSIZE          16      /**< Block size used by the cipher                  */
-#define MBEDTLS_CTR_DRBG_KEYSIZE            32      /**< Key size used by the cipher                    */
-#define MBEDTLS_CTR_DRBG_KEYBITS            ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 )
-#define MBEDTLS_CTR_DRBG_SEEDLEN            ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE )
-                                            /**< The seed length (counter + AES key)            */
+#define MBEDTLS_CTR_DRBG_BLOCKSIZE          16 /**< The block size used by the cipher. */
+#define MBEDTLS_CTR_DRBG_KEYSIZE            32 /**< The key size used by the cipher. */
+#define MBEDTLS_CTR_DRBG_KEYBITS            ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 ) /**< The key size for the DRBG operation, in bits. */
+#define MBEDTLS_CTR_DRBG_SEEDLEN            ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE ) /**< The seed length, calculated as (counter + AES key). */
 
 /**
  * \name SECTION: Module settings
  *
  * The configuration options you can set for this module are in this section.
- * Either change them in config.h or define them on the compiler command line.
+ * Either change them in config.h or define them using the compiler command
+ * line.
  * \{
  */
 
 #if !defined(MBEDTLS_CTR_DRBG_ENTROPY_LEN)
 #if defined(MBEDTLS_SHA512_C) && !defined(MBEDTLS_ENTROPY_FORCE_SHA256)
-#define MBEDTLS_CTR_DRBG_ENTROPY_LEN        48      /**< Amount of entropy used per seed by default (48 with SHA-512, 32 with SHA-256) */
+#define MBEDTLS_CTR_DRBG_ENTROPY_LEN        48
+/**< The amount of entropy used per seed by default:
+ * <ul><li>48 with SHA-512.</li>
+ * <li>32 with SHA-256.</li></ul>
+ */
 #else
-#define MBEDTLS_CTR_DRBG_ENTROPY_LEN        32      /**< Amount of entropy used per seed by default (48 with SHA-512, 32 with SHA-256) */
+#define MBEDTLS_CTR_DRBG_ENTROPY_LEN        32
+/**< Amount of entropy used per seed by default:
+ * <ul><li>48 with SHA-512.</li>
+ * <li>32 with SHA-256.</li></ul>
+ */
 #endif
 #endif
 
 #if !defined(MBEDTLS_CTR_DRBG_RESEED_INTERVAL)
-#define MBEDTLS_CTR_DRBG_RESEED_INTERVAL    10000   /**< Interval before reseed is performed by default */
+#define MBEDTLS_CTR_DRBG_RESEED_INTERVAL    10000
+/**< The interval before reseed is performed by default. */
 #endif
 
 #if !defined(MBEDTLS_CTR_DRBG_MAX_INPUT)
-#define MBEDTLS_CTR_DRBG_MAX_INPUT          256     /**< Maximum number of additional input bytes */
+#define MBEDTLS_CTR_DRBG_MAX_INPUT          256
+/**< The maximum number of additional input Bytes. */
 #endif
 
 #if !defined(MBEDTLS_CTR_DRBG_MAX_REQUEST)
-#define MBEDTLS_CTR_DRBG_MAX_REQUEST        1024    /**< Maximum number of requested bytes per call */
+#define MBEDTLS_CTR_DRBG_MAX_REQUEST        1024
+/**< The maximum number of requested Bytes per call. */
 #endif
 
 #if !defined(MBEDTLS_CTR_DRBG_MAX_SEED_INPUT)
-#define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT     384     /**< Maximum size of (re)seed buffer */
+#define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT     384
+/**< The maximum size of seed or reseed buffer. */
 #endif
 
 /* \} name SECTION: Module settings */
 
-#define MBEDTLS_CTR_DRBG_PR_OFF             0       /**< No prediction resistance       */
-#define MBEDTLS_CTR_DRBG_PR_ON              1       /**< Prediction resistance enabled  */
+#define MBEDTLS_CTR_DRBG_PR_OFF             0
+/**< Prediction resistance is disabled. */
+#define MBEDTLS_CTR_DRBG_PR_ON              1
+/**< Prediction resistance is enabled. */
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /**
- * \brief          CTR_DRBG context structure
+ * \brief          The CTR_DRBG context structure.
  */
 typedef struct
 {
-    unsigned char counter[16];  /*!<  counter (V)       */
-    int reseed_counter;         /*!<  reseed counter    */
-    int prediction_resistance;  /*!<  enable prediction resistance (Automatic
-                                      reseed before every random generation)  */
-    size_t entropy_len;         /*!<  amount of entropy grabbed on each
-                                      (re)seed          */
-    int reseed_interval;        /*!<  reseed interval   */
+    unsigned char counter[16];  /*!< The counter (V). */
+    int reseed_counter;         /*!< The reseed counter. */
+    int prediction_resistance;  /*!< This determines whether prediction
+                                     resistance is enabled, that is
+                                     whether to systematically reseed before
+                                     each random generation. */
+    size_t entropy_len;         /*!< The amount of entropy grabbed on each
+                                     seed or reseed operation. */
+    int reseed_interval;        /*!< The reseed interval. */
 
-    mbedtls_aes_context aes_ctx;        /*!<  AES context       */
+    mbedtls_aes_context aes_ctx;        /*!< The AES context. */
 
     /*
      * Callbacks (Entropy)
      */
     int (*f_entropy)(void *, unsigned char *, size_t);
+                                /*!< The entropy callback function. */
 
-    void *p_entropy;            /*!<  context for the entropy function */
+    void *p_entropy;            /*!< The context for the entropy function. */
 
 #if defined(MBEDTLS_THREADING_C)
     mbedtls_threading_mutex_t mutex;
@@ -110,31 +132,32 @@
 mbedtls_ctr_drbg_context;
 
 /**
- * \brief               CTR_DRBG context initialization
- *                      Makes the context ready for mbedtls_ctr_drbg_seed() or
- *                      mbedtls_ctr_drbg_free().
+ * \brief               This function initializes the CTR_DRBG context,
+ *                      and prepares it for mbedtls_ctr_drbg_seed()
+ *                      or mbedtls_ctr_drbg_free().
  *
- * \param ctx           CTR_DRBG context to be initialized
+ * \param ctx           The CTR_DRBG context to initialize.
  */
 void mbedtls_ctr_drbg_init( mbedtls_ctr_drbg_context *ctx );
 
 /**
- * \brief               CTR_DRBG initial seeding
- *                      Seed and setup entropy source for future reseeds.
+ * \brief               This function seeds and sets up the CTR_DRBG
+ *                      entropy source for future reseeds.
  *
- * Note: Personalization data can be provided in addition to the more generic
- *       entropy source to make this instantiation as unique as possible.
+ * \note Personalization data can be provided in addition to the more generic
+ *       entropy source, to make this instantiation as unique as possible.
  *
- * \param ctx           CTR_DRBG context to be seeded
- * \param f_entropy     Entropy callback (p_entropy, buffer to fill, buffer
- *                      length)
- * \param p_entropy     Entropy context
- * \param custom        Personalization data (Device specific identifiers)
- *                      (Can be NULL)
- * \param len           Length of personalization data
+ * \param ctx           The CTR_DRBG context to seed.
+ * \param f_entropy     The entropy callback, taking as arguments the
+ *                      \p p_entropy context, the buffer to fill, and the
+                        length of the buffer.
+ * \param p_entropy     The entropy context.
+ * \param custom        Personalization data, that is device-specific
+                        identifiers. Can be NULL.
+ * \param len           The length of the personalization data.
  *
- * \return              0 if successful, or
- *                      MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED
+ * \return              \c 0 on success, or
+ *                      #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
  */
 int mbedtls_ctr_drbg_seed( mbedtls_ctr_drbg_context *ctx,
                    int (*f_entropy)(void *, unsigned char *, size_t),
@@ -143,138 +166,147 @@
                    size_t len );
 
 /**
- * \brief               Clear CTR_CRBG context data
+ * \brief               This function clears CTR_CRBG context data.
  *
- * \param ctx           CTR_DRBG context to clear
+ * \param ctx           The CTR_DRBG context to clear.
  */
 void mbedtls_ctr_drbg_free( mbedtls_ctr_drbg_context *ctx );
 
 /**
- * \brief               Enable / disable prediction resistance (Default: Off)
+ * \brief               This function turns prediction resistance on or off.
+ *                      The default value is off.
  *
- * Note: If enabled, entropy is used for ctx->entropy_len before each call!
- *       Only use this if you have ample supply of good entropy!
+ * \note                If enabled, entropy is gathered at the beginning of
+ *                      every call to mbedtls_ctr_drbg_random_with_add().
+ *                      Only use this if your entropy source has sufficient
+ *                      throughput.
  *
- * \param ctx           CTR_DRBG context
- * \param resistance    MBEDTLS_CTR_DRBG_PR_ON or MBEDTLS_CTR_DRBG_PR_OFF
+ * \param ctx           The CTR_DRBG context.
+ * \param resistance    #MBEDTLS_CTR_DRBG_PR_ON or #MBEDTLS_CTR_DRBG_PR_OFF.
  */
 void mbedtls_ctr_drbg_set_prediction_resistance( mbedtls_ctr_drbg_context *ctx,
                                          int resistance );
 
 /**
- * \brief               Set the amount of entropy grabbed on each (re)seed
- *                      (Default: MBEDTLS_CTR_DRBG_ENTROPY_LEN)
+ * \brief               This function sets the amount of entropy grabbed on each
+ *                      seed or reseed. The default value is
+ *                      #MBEDTLS_CTR_DRBG_ENTROPY_LEN.
  *
- * \param ctx           CTR_DRBG context
- * \param len           Amount of entropy to grab
+ * \param ctx           The CTR_DRBG context.
+ * \param len           The amount of entropy to grab.
  */
 void mbedtls_ctr_drbg_set_entropy_len( mbedtls_ctr_drbg_context *ctx,
                                size_t len );
 
 /**
- * \brief               Set the reseed interval
- *                      (Default: MBEDTLS_CTR_DRBG_RESEED_INTERVAL)
+ * \brief               This function sets the reseed interval.
+ *                      The default value is #MBEDTLS_CTR_DRBG_RESEED_INTERVAL.
  *
- * \param ctx           CTR_DRBG context
- * \param interval      Reseed interval
+ * \param ctx           The CTR_DRBG context.
+ * \param interval      The reseed interval.
  */
 void mbedtls_ctr_drbg_set_reseed_interval( mbedtls_ctr_drbg_context *ctx,
                                    int interval );
 
 /**
- * \brief               CTR_DRBG reseeding (extracts data from entropy source)
+ * \brief               This function reseeds the CTR_DRBG context, that is
+ *                      extracts data from the entropy source.
  *
- * \param ctx           CTR_DRBG context
- * \param additional    Additional data to add to state (Can be NULL)
- * \param len           Length of additional data
+ * \param ctx           The CTR_DRBG context.
+ * \param additional    Additional data to add to the state. Can be NULL.
+ * \param len           The length of the additional data.
  *
- * \return              0 if successful, or
- *                      MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED
+ * \return   \c 0 on success, or
+ *           #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
  */
 int mbedtls_ctr_drbg_reseed( mbedtls_ctr_drbg_context *ctx,
                      const unsigned char *additional, size_t len );
 
 /**
- * \brief               CTR_DRBG update state
+ * \brief               This function updates the state of the CTR_DRBG context.
  *
- * \param ctx           CTR_DRBG context
- * \param additional    Additional data to update state with
- * \param add_len       Length of additional data
+ * \param ctx           The CTR_DRBG context.
+ * \param additional    The data to update the state with.
+ * \param add_len       Length of \p additional data.
  *
- * \note                If 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 ones are silently discarded.
+ * \note     If \p add_len is greater than #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT,
+ *           only the first #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT Bytes are used.
+ *           The remaining Bytes are silently discarded.
  */
 void mbedtls_ctr_drbg_update( mbedtls_ctr_drbg_context *ctx,
                       const unsigned char *additional, size_t add_len );
 
 /**
- * \brief               CTR_DRBG generate random with additional update input
+ * \brief   This function updates a CTR_DRBG instance with additional
+ *          data and uses it to generate random data.
  *
- * Note: Automatically reseeds if reseed_counter is reached.
+ * \note    The function automatically reseeds if the reseed counter is exceeded.
  *
- * \param p_rng         CTR_DRBG context
- * \param output        Buffer to fill
- * \param output_len    Length of the buffer
- * \param additional    Additional data to update with (Can be NULL)
- * \param add_len       Length of additional data
+ * \param p_rng         The CTR_DRBG context. This must be a pointer to a
+ *                      #mbedtls_ctr_drbg_context structure.
+ * \param output        The buffer to fill.
+ * \param output_len    The length of the buffer.
+ * \param additional    Additional data to update. Can be NULL.
+ * \param add_len       The length of the additional data.
  *
- * \return              0 if successful, or
- *                      MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED, or
- *                      MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG
+ * \return    \c 0 on success, or
+ *            #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
+ *            #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
  */
 int mbedtls_ctr_drbg_random_with_add( void *p_rng,
                               unsigned char *output, size_t output_len,
                               const unsigned char *additional, size_t add_len );
 
 /**
- * \brief               CTR_DRBG generate random
+ * \brief   This function uses CTR_DRBG to generate random data.
  *
- * Note: Automatically reseeds if reseed_counter is reached.
+ * \note    The function automatically reseeds if the reseed counter is exceeded.
  *
- * \param p_rng         CTR_DRBG context
- * \param output        Buffer to fill
- * \param output_len    Length of the buffer
+ * \param p_rng         The CTR_DRBG context. This must be a pointer to a
+ *                      #mbedtls_ctr_drbg_context structure.
+ * \param output        The buffer to fill.
+ * \param output_len    The length of the buffer.
  *
- * \return              0 if successful, or
- *                      MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED, or
- *                      MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG
+ * \return              \c 0 on success, or
+ *                      #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
+ *                      #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
  */
 int mbedtls_ctr_drbg_random( void *p_rng,
                      unsigned char *output, size_t output_len );
 
 #if defined(MBEDTLS_FS_IO)
 /**
- * \brief               Write a seed file
+ * \brief               This function writes a seed file.
  *
- * \param ctx           CTR_DRBG context
- * \param path          Name of the file
+ * \param ctx           The CTR_DRBG context.
+ * \param path          The name of the file.
  *
- * \return              0 if successful,
- *                      MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error, or
- *                      MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED
+ * \return              \c 0 on success,
+ *                      #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error, or
+ *                      #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on
+ *                      failure.
  */
 int mbedtls_ctr_drbg_write_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
 
 /**
- * \brief               Read and update a seed file. Seed is added to this
- *                      instance
+ * \brief               This function reads and updates a seed file. The seed
+ *                      is added to this instance.
  *
- * \param ctx           CTR_DRBG context
- * \param path          Name of the file
+ * \param ctx           The CTR_DRBG context.
+ * \param path          The name of the file.
  *
- * \return              0 if successful,
- *                      MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error,
- *                      MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
- *                      MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG
+ * \return              \c 0 on success,
+ *                      #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error,
+ *                      #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
+ *                      #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG on failure.
  */
 int mbedtls_ctr_drbg_update_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
 #endif /* MBEDTLS_FS_IO */
 
 /**
- * \brief               Checkup routine
+ * \brief               The CTR_DRBG checkup routine.
  *
- * \return              0 if successful, or 1 if the test failed
+ * \return              \c 0 on success, or \c 1 on failure.
  */
 int mbedtls_ctr_drbg_self_test( int verbose );
 
diff --git a/include/mbedtls/debug.h b/include/mbedtls/debug.h
index 2957996..ef8db67 100644
--- a/include/mbedtls/debug.h
+++ b/include/mbedtls/debug.h
@@ -2,7 +2,8 @@
  * \file debug.h
  *
  * \brief Functions for controlling and providing debug output from the library.
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/des.h b/include/mbedtls/des.h
index 5ca2ecf..5a1a636 100644
--- a/include/mbedtls/des.h
+++ b/include/mbedtls/des.h
@@ -3,6 +3,11 @@
  *
  * \brief DES block cipher
  *
+ * \warning   DES is considered a weak cipher and its use constitutes a
+ *            security risk. We recommend considering stronger ciphers
+ *            instead.
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
@@ -19,6 +24,7 @@
  *  limitations under the License.
  *
  *  This file is part of mbed TLS (https://tls.mbed.org)
+ *
  */
 #ifndef MBEDTLS_DES_H
 #define MBEDTLS_DES_H
@@ -36,6 +42,7 @@
 #define MBEDTLS_DES_DECRYPT     0
 
 #define MBEDTLS_ERR_DES_INVALID_INPUT_LENGTH              -0x0032  /**< The data input has an invalid length. */
+#define MBEDTLS_ERR_DES_HW_ACCEL_FAILED                   -0x0033  /**< DES hardware accelerator failed. */
 
 #define MBEDTLS_DES_KEY_SIZE    8
 
@@ -49,6 +56,10 @@
 
 /**
  * \brief          DES context structure
+ *
+ * \warning        DES is considered a weak cipher and its use constitutes a
+ *                 security risk. We recommend considering stronger ciphers
+ *                 instead.
  */
 typedef struct
 {
@@ -69,6 +80,10 @@
  * \brief          Initialize DES context
  *
  * \param ctx      DES context to be initialized
+ *
+ * \warning        DES is considered a weak cipher and its use constitutes a
+ *                 security risk. We recommend considering stronger ciphers
+ *                 instead.
  */
 void mbedtls_des_init( mbedtls_des_context *ctx );
 
@@ -76,6 +91,10 @@
  * \brief          Clear DES context
  *
  * \param ctx      DES context to be cleared
+ *
+ * \warning        DES is considered a weak cipher and its use constitutes a
+ *                 security risk. We recommend considering stronger ciphers
+ *                 instead.
  */
 void mbedtls_des_free( mbedtls_des_context *ctx );
 
@@ -100,6 +119,10 @@
  *                 a parity bit to allow verification.
  *
  * \param key      8-byte secret key
+ *
+ * \warning        DES is considered a weak cipher and its use constitutes a
+ *                 security risk. We recommend considering stronger ciphers
+ *                 instead.
  */
 void mbedtls_des_key_set_parity( unsigned char key[MBEDTLS_DES_KEY_SIZE] );
 
@@ -112,6 +135,10 @@
  * \param key      8-byte secret key
  *
  * \return         0 is parity was ok, 1 if parity was not correct.
+ *
+ * \warning        DES is considered a weak cipher and its use constitutes a
+ *                 security risk. We recommend considering stronger ciphers
+ *                 instead.
  */
 int mbedtls_des_key_check_key_parity( const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
 
@@ -121,6 +148,10 @@
  * \param key      8-byte secret key
  *
  * \return         0 if no weak key was found, 1 if a weak key was identified.
+ *
+ * \warning        DES is considered a weak cipher and its use constitutes a
+ *                 security risk. We recommend considering stronger ciphers
+ *                 instead.
  */
 int mbedtls_des_key_check_weak( const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
 
@@ -131,6 +162,10 @@
  * \param key      8-byte secret key
  *
  * \return         0
+ *
+ * \warning        DES is considered a weak cipher and its use constitutes a
+ *                 security risk. We recommend considering stronger ciphers
+ *                 instead.
  */
 int mbedtls_des_setkey_enc( mbedtls_des_context *ctx, const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
 
@@ -141,6 +176,10 @@
  * \param key      8-byte secret key
  *
  * \return         0
+ *
+ * \warning        DES is considered a weak cipher and its use constitutes a
+ *                 security risk. We recommend considering stronger ciphers
+ *                 instead.
  */
 int mbedtls_des_setkey_dec( mbedtls_des_context *ctx, const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
 
@@ -196,6 +235,10 @@
  * \param output   64-bit output block
  *
  * \return         0 if successful
+ *
+ * \warning        DES is considered a weak cipher and its use constitutes a
+ *                 security risk. We recommend considering stronger ciphers
+ *                 instead.
  */
 int mbedtls_des_crypt_ecb( mbedtls_des_context *ctx,
                     const unsigned char input[8],
@@ -219,6 +262,10 @@
  * \param iv       initialization vector (updated after use)
  * \param input    buffer holding the input data
  * \param output   buffer holding the output data
+ *
+ * \warning        DES is considered a weak cipher and its use constitutes a
+ *                 security risk. We recommend considering stronger ciphers
+ *                 instead.
  */
 int mbedtls_des_crypt_cbc( mbedtls_des_context *ctx,
                     int mode,
@@ -277,6 +324,10 @@
  *
  * \param SK       Round keys
  * \param key      Base key
+ *
+ * \warning        DES is considered a weak cipher and its use constitutes a
+ *                 security risk. We recommend considering stronger ciphers
+ *                 instead.
  */
 void mbedtls_des_setkey( uint32_t SK[32],
                          const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
diff --git a/include/mbedtls/dhm.h b/include/mbedtls/dhm.h
index d7ab152..00fafd8 100644
--- a/include/mbedtls/dhm.h
+++ b/include/mbedtls/dhm.h
@@ -1,9 +1,44 @@
 /**
  * \file dhm.h
  *
- * \brief Diffie-Hellman-Merkle key exchange
+ * \brief Diffie-Hellman-Merkle key exchange.
  *
- *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ * <em>RFC-3526: More Modular Exponential (MODP) Diffie-Hellman groups for
+ * Internet Key Exchange (IKE)</em> defines a number of standardized
+ * Diffie-Hellman groups for IKE.
+ *
+ * <em>RFC-5114: Additional Diffie-Hellman Groups for Use with IETF
+ * Standards</em> defines a number of standardized Diffie-Hellman
+ * groups that can be used.
+ *
+ * \warning  The security of the DHM key exchange relies on the proper choice
+ *           of prime modulus - optimally, it should be a safe prime. The usage
+ *           of non-safe primes both decreases the difficulty of the underlying
+ *           discrete logarithm problem and can lead to small subgroup attacks
+ *           leaking private exponent bits when invalid public keys are used
+ *           and not detected. This is especially relevant if the same DHM
+ *           parameters are reused for multiple key exchanges as in static DHM,
+ *           while the criticality of small-subgroup attacks is lower for
+ *           ephemeral DHM.
+ *
+ * \warning  For performance reasons, the code does neither perform primality
+ *           nor safe primality tests, nor the expensive checks for invalid
+ *           subgroups. Moreover, even if these were performed, non-standardized
+ *           primes cannot be trusted because of the possibility of backdoors
+ *           that can't be effectively checked for.
+ *
+ * \warning  Diffie-Hellman-Merkle is therefore a security risk when not using
+ *           standardized primes generated using a trustworthy ("nothing up
+ *           my sleeve") method, such as the RFC 3526 / 7919 primes. In the TLS
+ *           protocol, DH parameters need to be negotiated, so using the default
+ *           primes systematically is not always an option. If possible, use
+ *           Elliptic Curve Diffie-Hellman (ECDH), which has better performance,
+ *           and for which the TLS protocol mandates the use of standard
+ *           parameters.
+ *
+ */
+/*
+ *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
@@ -18,17 +53,24 @@
  *  See the License for the specific language governing permissions and
  *  limitations under the License.
  *
- *  This file is part of mbed TLS (https://tls.mbed.org)
+ *  This file is part of Mbed TLS (https://tls.mbed.org)
  */
+
 #ifndef MBEDTLS_DHM_H
 #define MBEDTLS_DHM_H
 
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
 #include "bignum.h"
+#if !defined(MBEDTLS_DHM_ALT)
 
 /*
  * DHM Error codes
  */
-#define MBEDTLS_ERR_DHM_BAD_INPUT_DATA                    -0x3080  /**< Bad input parameters to function. */
+#define MBEDTLS_ERR_DHM_BAD_INPUT_DATA                    -0x3080  /**< Bad input parameters. */
 #define MBEDTLS_ERR_DHM_READ_PARAMS_FAILED                -0x3100  /**< Reading of the DHM parameters failed. */
 #define MBEDTLS_ERR_DHM_MAKE_PARAMS_FAILED                -0x3180  /**< Making of the DHM parameters failed. */
 #define MBEDTLS_ERR_DHM_READ_PUBLIC_FAILED                -0x3200  /**< Reading of the public values failed. */
@@ -36,167 +78,85 @@
 #define MBEDTLS_ERR_DHM_CALC_SECRET_FAILED                -0x3300  /**< Calculation of the DHM secret failed. */
 #define MBEDTLS_ERR_DHM_INVALID_FORMAT                    -0x3380  /**< The ASN.1 data is not formatted correctly. */
 #define MBEDTLS_ERR_DHM_ALLOC_FAILED                      -0x3400  /**< Allocation of memory failed. */
-#define MBEDTLS_ERR_DHM_FILE_IO_ERROR                     -0x3480  /**< Read/write of file failed. */
-
-/**
- * RFC 3526 defines a number of standardized Diffie-Hellman groups
- * for IKE.
- * RFC 5114 defines a number of standardized Diffie-Hellman groups
- * that can be used.
- *
- * Some are included here for convenience.
- *
- * Included are:
- *  RFC 3526 3.    2048-bit MODP Group
- *  RFC 3526 4.    3072-bit MODP Group
- *  RFC 3526 5.    4096-bit MODP Group
- *  RFC 5114 2.2.  2048-bit MODP Group with 224-bit Prime Order Subgroup
- */
-#define MBEDTLS_DHM_RFC3526_MODP_2048_P               \
-    "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1" \
-    "29024E088A67CC74020BBEA63B139B22514A08798E3404DD" \
-    "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245" \
-    "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED" \
-    "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D" \
-    "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F" \
-    "83655D23DCA3AD961C62F356208552BB9ED529077096966D" \
-    "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B" \
-    "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9" \
-    "DE2BCBF6955817183995497CEA956AE515D2261898FA0510" \
-    "15728E5A8AACAA68FFFFFFFFFFFFFFFF"
-
-#define MBEDTLS_DHM_RFC3526_MODP_2048_G          "02"
-
-#define MBEDTLS_DHM_RFC3526_MODP_3072_P               \
-    "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1" \
-    "29024E088A67CC74020BBEA63B139B22514A08798E3404DD" \
-    "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245" \
-    "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED" \
-    "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D" \
-    "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F" \
-    "83655D23DCA3AD961C62F356208552BB9ED529077096966D" \
-    "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B" \
-    "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9" \
-    "DE2BCBF6955817183995497CEA956AE515D2261898FA0510" \
-    "15728E5A8AAAC42DAD33170D04507A33A85521ABDF1CBA64" \
-    "ECFB850458DBEF0A8AEA71575D060C7DB3970F85A6E1E4C7" \
-    "ABF5AE8CDB0933D71E8C94E04A25619DCEE3D2261AD2EE6B" \
-    "F12FFA06D98A0864D87602733EC86A64521F2B18177B200C" \
-    "BBE117577A615D6C770988C0BAD946E208E24FA074E5AB31" \
-    "43DB5BFCE0FD108E4B82D120A93AD2CAFFFFFFFFFFFFFFFF"
-
-#define MBEDTLS_DHM_RFC3526_MODP_3072_G          "02"
-
-#define MBEDTLS_DHM_RFC3526_MODP_4096_P                \
-    "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1" \
-    "29024E088A67CC74020BBEA63B139B22514A08798E3404DD" \
-    "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245" \
-    "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED" \
-    "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D" \
-    "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F" \
-    "83655D23DCA3AD961C62F356208552BB9ED529077096966D" \
-    "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B" \
-    "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9" \
-    "DE2BCBF6955817183995497CEA956AE515D2261898FA0510" \
-    "15728E5A8AAAC42DAD33170D04507A33A85521ABDF1CBA64" \
-    "ECFB850458DBEF0A8AEA71575D060C7DB3970F85A6E1E4C7" \
-    "ABF5AE8CDB0933D71E8C94E04A25619DCEE3D2261AD2EE6B" \
-    "F12FFA06D98A0864D87602733EC86A64521F2B18177B200C" \
-    "BBE117577A615D6C770988C0BAD946E208E24FA074E5AB31" \
-    "43DB5BFCE0FD108E4B82D120A92108011A723C12A787E6D7" \
-    "88719A10BDBA5B2699C327186AF4E23C1A946834B6150BDA" \
-    "2583E9CA2AD44CE8DBBBC2DB04DE8EF92E8EFC141FBECAA6" \
-    "287C59474E6BC05D99B2964FA090C3A2233BA186515BE7ED" \
-    "1F612970CEE2D7AFB81BDD762170481CD0069127D5B05AA9" \
-    "93B4EA988D8FDDC186FFB7DC90A6C08F4DF435C934063199" \
-    "FFFFFFFFFFFFFFFF"
-
-#define MBEDTLS_DHM_RFC3526_MODP_4096_G          "02"
-
-#define MBEDTLS_DHM_RFC5114_MODP_2048_P               \
-    "AD107E1E9123A9D0D660FAA79559C51FA20D64E5683B9FD1" \
-    "B54B1597B61D0A75E6FA141DF95A56DBAF9A3C407BA1DF15" \
-    "EB3D688A309C180E1DE6B85A1274A0A66D3F8152AD6AC212" \
-    "9037C9EDEFDA4DF8D91E8FEF55B7394B7AD5B7D0B6C12207" \
-    "C9F98D11ED34DBF6C6BA0B2C8BBC27BE6A00E0A0B9C49708" \
-    "B3BF8A317091883681286130BC8985DB1602E714415D9330" \
-    "278273C7DE31EFDC7310F7121FD5A07415987D9ADC0A486D" \
-    "CDF93ACC44328387315D75E198C641A480CD86A1B9E587E8" \
-    "BE60E69CC928B2B9C52172E413042E9B23F10B0E16E79763" \
-    "C9B53DCF4BA80A29E3FB73C16B8E75B97EF363E2FFA31F71" \
-    "CF9DE5384E71B81C0AC4DFFE0C10E64F"
-
-#define MBEDTLS_DHM_RFC5114_MODP_2048_G              \
-    "AC4032EF4F2D9AE39DF30B5C8FFDAC506CDEBE7B89998CAF"\
-    "74866A08CFE4FFE3A6824A4E10B9A6F0DD921F01A70C4AFA"\
-    "AB739D7700C29F52C57DB17C620A8652BE5E9001A8D66AD7"\
-    "C17669101999024AF4D027275AC1348BB8A762D0521BC98A"\
-    "E247150422EA1ED409939D54DA7460CDB5F6C6B250717CBE"\
-    "F180EB34118E98D119529A45D6F834566E3025E316A330EF"\
-    "BB77A86F0C1AB15B051AE3D428C8F8ACB70A8137150B8EEB"\
-    "10E183EDD19963DDD9E263E4770589EF6AA21E7F5F2FF381"\
-    "B539CCE3409D13CD566AFBB48D6C019181E1BCFE94B30269"\
-    "EDFE72FE9B6AA4BD7B5A0F1C71CFFF4C19C418E1F6EC0179"\
-    "81BC087F2A7065B384B890D3191F2BFA"
+#define MBEDTLS_ERR_DHM_FILE_IO_ERROR                     -0x3480  /**< Read or write of file failed. */
+#define MBEDTLS_ERR_DHM_HW_ACCEL_FAILED                   -0x3500  /**< DHM hardware accelerator failed. */
+#define MBEDTLS_ERR_DHM_SET_GROUP_FAILED                  -0x3580  /**< Setting the modulus and generator failed. */
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /**
- * \brief          DHM context structure
+ * \brief          The DHM context structure.
  */
 typedef struct
 {
-    size_t len; /*!<  size(P) in chars  */
-    mbedtls_mpi P;      /*!<  prime modulus     */
-    mbedtls_mpi G;      /*!<  generator         */
-    mbedtls_mpi X;      /*!<  secret value      */
-    mbedtls_mpi GX;     /*!<  self = G^X mod P  */
-    mbedtls_mpi GY;     /*!<  peer = G^Y mod P  */
-    mbedtls_mpi K;      /*!<  key = GY^X mod P  */
-    mbedtls_mpi RP;     /*!<  cached R^2 mod P  */
-    mbedtls_mpi Vi;     /*!<  blinding value    */
-    mbedtls_mpi Vf;     /*!<  un-blinding value */
-    mbedtls_mpi pX;     /*!<  previous X        */
+    size_t len;         /*!<  The size of \p P in Bytes. */
+    mbedtls_mpi P;      /*!<  The prime modulus. */
+    mbedtls_mpi G;      /*!<  The generator. */
+    mbedtls_mpi X;      /*!<  Our secret value. */
+    mbedtls_mpi GX;     /*!<  Our public key = \c G^X mod \c P. */
+    mbedtls_mpi GY;     /*!<  The public key of the peer = \c G^Y mod \c P. */
+    mbedtls_mpi K;      /*!<  The shared secret = \c G^(XY) mod \c P. */
+    mbedtls_mpi RP;     /*!<  The cached value = \c R^2 mod \c P. */
+    mbedtls_mpi Vi;     /*!<  The blinding value. */
+    mbedtls_mpi Vf;     /*!<  The unblinding value. */
+    mbedtls_mpi pX;     /*!<  The previous \c X. */
 }
 mbedtls_dhm_context;
 
 /**
- * \brief          Initialize DHM context
+ * \brief          This function initializes the DHM context.
  *
- * \param ctx      DHM context to be initialized
+ * \param ctx      The DHM context to initialize.
  */
 void mbedtls_dhm_init( mbedtls_dhm_context *ctx );
 
 /**
- * \brief          Parse the ServerKeyExchange parameters
+ * \brief          This function parses the ServerKeyExchange parameters.
  *
- * \param ctx      DHM context
- * \param p        &(start of input buffer)
- * \param end      end of buffer
+ * \param ctx      The DHM context.
+ * \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
+ *                 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         0 if successful, or an MBEDTLS_ERR_DHM_XXX error code
+ * \return         \c 0 on success, or 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 );
 
 /**
- * \brief          Setup and write the ServerKeyExchange parameters
+ * \brief          This function sets up and writes the ServerKeyExchange
+ *                 parameters.
  *
- * \param ctx      DHM context
- * \param x_size   private value size in bytes
- * \param output   destination buffer
- * \param olen     number of chars written
- * \param f_rng    RNG function
- * \param p_rng    RNG parameter
+ * \param ctx      The DHM context.
+ * \param x_size   The private value size in Bytes.
+ * \param olen     The number of characters written.
+ * \param output   The destination buffer.
+ * \param f_rng    The RNG function.
+ * \param p_rng    The RNG parameter.
  *
- * \note           This function assumes that ctx->P and ctx->G
- *                 have already been properly set (for example
- *                 using mbedtls_mpi_read_string or mbedtls_mpi_read_binary).
+ * \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.
  *
- * \return         0 if successful, or an MBEDTLS_ERR_DHM_XXX error code
+ * \note           This function assumes that \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().
+ *
+ * \return         \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
+ *                 on failure.
  */
 int mbedtls_dhm_make_params( mbedtls_dhm_context *ctx, int x_size,
                      unsigned char *output, size_t *olen,
@@ -204,28 +164,54 @@
                      void *p_rng );
 
 /**
- * \brief          Import the peer's public value G^Y
+ * \brief          Set prime modulus and generator
  *
- * \param ctx      DHM context
- * \param input    input buffer
- * \param ilen     size of buffer
+ * \param ctx      The DHM context.
+ * \param P        The MPI holding DHM prime modulus.
+ * \param G        The MPI holding DHM generator.
  *
- * \return         0 if successful, or an MBEDTLS_ERR_DHM_XXX error code
+ * \note           This function can be used to set P, G
+ *                 in preparation for \c mbedtls_dhm_make_params.
+ *
+ * \return         \c 0 if successful, or an \c MBEDTLS_ERR_DHM_XXX error code
+ *                 on failure.
+ */
+int mbedtls_dhm_set_group( mbedtls_dhm_context *ctx,
+                           const mbedtls_mpi *P,
+                           const mbedtls_mpi *G );
+
+/**
+ * \brief          This function imports the public value G^Y of the peer.
+ *
+ * \param ctx      The DHM context.
+ * \param input    The input buffer.
+ * \param ilen     The size of the input buffer.
+ *
+ * \return         \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
+ *                 on failure.
  */
 int mbedtls_dhm_read_public( mbedtls_dhm_context *ctx,
                      const unsigned char *input, size_t ilen );
 
 /**
- * \brief          Create own private value X and export G^X
+ * \brief          This function creates its own private value \c X and
+ *                 exports \c G^X.
  *
- * \param ctx      DHM context
- * \param x_size   private value size in bytes
- * \param output   destination buffer
- * \param olen     must be at least equal to the size of P, ctx->len
- * \param f_rng    RNG function
- * \param p_rng    RNG parameter
+ * \param ctx      The DHM context.
+ * \param x_size   The private value 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 parameter.
  *
- * \return         0 if successful, or an MBEDTLS_ERR_DHM_XXX error code
+ * \note           The destination buffer will always be fully written
+ *                 so as to contain a big-endian presentation of G^X mod P.
+ *                 If it is larger than ctx->len, it will accordingly be
+ *                 padded with zero-bytes in the beginning.
+ *
+ * \return         \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
+ *                 on failure.
  */
 int mbedtls_dhm_make_public( mbedtls_dhm_context *ctx, int x_size,
                      unsigned char *output, size_t olen,
@@ -233,22 +219,25 @@
                      void *p_rng );
 
 /**
- * \brief          Derive and export the shared secret (G^Y)^X mod P
+ * \brief               This function derives and exports the shared secret
+ *                      \c (G^Y)^X mod \c P.
  *
- * \param ctx      DHM context
- * \param output   destination buffer
- * \param output_size   size of the destination buffer
- * \param olen     on exit, holds the actual number of bytes written
- * \param f_rng    RNG function, for blinding purposes
- * \param p_rng    RNG parameter
+ * \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.
+ * \param olen          On exit, holds the actual number of Bytes written.
+ * \param f_rng         The RNG function, for blinding purposes.
+ * \param p_rng         The RNG parameter.
  *
- * \return         0 if successful, or an MBEDTLS_ERR_DHM_XXX error code
+ * \return         \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
+ *                 on failure.
  *
- * \note           If non-NULL, f_rng is used to blind the input as
- *                 countermeasure against timing attacks. Blinding is
- *                 automatically used if and only if our secret value X is
- *                 re-used and costs nothing otherwise, so it is recommended
- *                 to always pass a non-NULL f_rng argument.
+ * \note           If non-NULL, \p f_rng is used to blind the input as
+ *                 a countermeasure against timing attacks. Blinding is used
+ *                 only if our secret value \p X is re-used and omitted
+ *                 otherwise. Therefore, we recommend always passing a
+ *                 non-NULL \p f_rng argument.
  */
 int mbedtls_dhm_calc_secret( mbedtls_dhm_context *ctx,
                      unsigned char *output, size_t output_size, size_t *olen,
@@ -256,23 +245,24 @@
                      void *p_rng );
 
 /**
- * \brief          Free and clear the components of a DHM key
+ * \brief          This function frees and clears the components of a DHM key.
  *
- * \param ctx      DHM context to free and clear
+ * \param ctx      The DHM context to free and clear.
  */
 void mbedtls_dhm_free( mbedtls_dhm_context *ctx );
 
 #if defined(MBEDTLS_ASN1_PARSE_C)
 /** \ingroup x509_module */
 /**
- * \brief          Parse DHM parameters in PEM or DER format
+ * \brief             This function parses DHM parameters in PEM or DER format.
  *
- * \param dhm      DHM context to be initialized
- * \param dhmin    input buffer
- * \param dhminlen size of the buffer
- *                 (including the terminating null byte for PEM data)
+ * \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.
  *
- * \return         0 if successful, or a specific DHM or PEM error code
+ * \return            \c 0 on success, or a specific DHM or PEM error code
+ *                    on failure.
  */
 int mbedtls_dhm_parse_dhm( mbedtls_dhm_context *dhm, const unsigned char *dhmin,
                    size_t dhminlen );
@@ -280,21 +270,34 @@
 #if defined(MBEDTLS_FS_IO)
 /** \ingroup x509_module */
 /**
- * \brief          Load and parse DHM parameters
+ * \brief          This function loads and parses DHM parameters from a file.
  *
- * \param dhm      DHM context to be initialized
- * \param path     filename to read the DHM Parameters from
+ * \param dhm      The DHM context to load the parameters to.
+ * \param path     The filename to read the DHM parameters from.
  *
- * \return         0 if successful, or a specific DHM or PEM error code
+ * \return         \c 0 on success, or a specific DHM or PEM error code
+ *                 on failure.
  */
 int mbedtls_dhm_parse_dhmfile( mbedtls_dhm_context *dhm, const char *path );
 #endif /* MBEDTLS_FS_IO */
 #endif /* MBEDTLS_ASN1_PARSE_C */
 
+#ifdef __cplusplus
+}
+#endif
+
+#else /* MBEDTLS_DHM_ALT */
+#include "dhm_alt.h"
+#endif /* MBEDTLS_DHM_ALT */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 /**
- * \brief          Checkup routine
+ * \brief          The DMH checkup routine.
  *
- * \return         0 if successful, or 1 if the test failed
+ * \return         \c 0 on success, or \c 1 on failure.
  */
 int mbedtls_dhm_self_test( int verbose );
 
@@ -302,4 +305,757 @@
 }
 #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.
+ *
+ * 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
+ * - RFC 3526 section 3:    2048-bit MODP Group
+ * - RFC 3526 section 4:    3072-bit MODP Group
+ * - RFC 3526 section 5:    4096-bit MODP Group
+ * - RFC 7919 section A.1:  ffdhe2048
+ * - RFC 7919 section A.2:  ffdhe3072
+ * - RFC 7919 section A.3:  ffdhe4096
+ * - RFC 7919 section A.4:  ffdhe6144
+ * - RFC 7919 section A.5:  ffdhe8192
+ *
+ * The constants with suffix "_p" denote the chosen prime moduli, while
+ * the constants with suffix "_g" denote the chosen generator
+ * of the associated prime field.
+ *
+ * The constants further suffixed with "_bin" are provided in binary format,
+ * while all other constants represent null-terminated strings holding the
+ * hexadecimal presentation of the respective numbers.
+ *
+ * The primes from RFC 3526 and RFC 7919 have been generating by the following
+ * trust-worthy procedure:
+ * - Fix N in { 2048, 3072, 4096, 6144, 8192 } and consider the N-bit number
+ *   the first and last 64 bits are all 1, and the remaining N - 128 bits of
+ *   which are 0x7ff...ff.
+ * - Add the smallest multiple of the first N - 129 bits of the binary expansion
+ *   of pi (for RFC 5236) or e (for RFC 7919) to this intermediate bit-string
+ *   such that the resulting integer is a safe-prime.
+ * - The result is the respective RFC 3526 / 7919 prime, and the corresponding
+ *   generator is always chosen to be 2 (which is a square for these prime,
+ *   hence the corresponding subgroup has order (p-1)/2 and avoids leaking a
+ *   bit in the private exponent).
+ *
+ */
+
+#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!
+ *
+ * \deprecated The hex-encoded primes from RFC 5114 are deprecated and are
+ *             likely to be removed in a future version of the library without
+ *             replacement.
+ */
+
+/**
+ * The hexadecimal presentation of the prime underlying the
+ * 2048-bit MODP Group with 224-bit Prime Order Subgroup, as defined
+ * in <em>RFC-5114: Additional Diffie-Hellman Groups for Use with
+ * IETF Standards</em>.
+ */
+#define MBEDTLS_DHM_RFC5114_MODP_2048_P                         \
+    MBEDTLS_DEPRECATED_STRING_CONSTANT(                         \
+        "AD107E1E9123A9D0D660FAA79559C51FA20D64E5683B9FD1"      \
+        "B54B1597B61D0A75E6FA141DF95A56DBAF9A3C407BA1DF15"      \
+        "EB3D688A309C180E1DE6B85A1274A0A66D3F8152AD6AC212"      \
+        "9037C9EDEFDA4DF8D91E8FEF55B7394B7AD5B7D0B6C12207"      \
+        "C9F98D11ED34DBF6C6BA0B2C8BBC27BE6A00E0A0B9C49708"      \
+        "B3BF8A317091883681286130BC8985DB1602E714415D9330"      \
+        "278273C7DE31EFDC7310F7121FD5A07415987D9ADC0A486D"      \
+        "CDF93ACC44328387315D75E198C641A480CD86A1B9E587E8"      \
+        "BE60E69CC928B2B9C52172E413042E9B23F10B0E16E79763"      \
+        "C9B53DCF4BA80A29E3FB73C16B8E75B97EF363E2FFA31F71"      \
+        "CF9DE5384E71B81C0AC4DFFE0C10E64F" )
+
+/**
+ * The hexadecimal presentation of the chosen generator of the 2048-bit MODP
+ * Group with 224-bit Prime Order Subgroup, as defined in <em>RFC-5114:
+ * Additional Diffie-Hellman Groups for Use with IETF Standards</em>.
+ */
+#define MBEDTLS_DHM_RFC5114_MODP_2048_G                         \
+    MBEDTLS_DEPRECATED_STRING_CONSTANT(                         \
+        "AC4032EF4F2D9AE39DF30B5C8FFDAC506CDEBE7B89998CAF"      \
+        "74866A08CFE4FFE3A6824A4E10B9A6F0DD921F01A70C4AFA"      \
+        "AB739D7700C29F52C57DB17C620A8652BE5E9001A8D66AD7"      \
+        "C17669101999024AF4D027275AC1348BB8A762D0521BC98A"      \
+        "E247150422EA1ED409939D54DA7460CDB5F6C6B250717CBE"      \
+        "F180EB34118E98D119529A45D6F834566E3025E316A330EF"      \
+        "BB77A86F0C1AB15B051AE3D428C8F8ACB70A8137150B8EEB"      \
+        "10E183EDD19963DDD9E263E4770589EF6AA21E7F5F2FF381"      \
+        "B539CCE3409D13CD566AFBB48D6C019181E1BCFE94B30269"      \
+        "EDFE72FE9B6AA4BD7B5A0F1C71CFFF4C19C418E1F6EC0179"      \
+        "81BC087F2A7065B384B890D3191F2BFA" )
+
+/**
+ * The hexadecimal presentation of the prime underlying the 2048-bit MODP
+ * Group, as defined in <em>RFC-3526: More Modular Exponential (MODP)
+ * Diffie-Hellman groups for Internet Key Exchange (IKE)</em>.
+ *
+ * \deprecated The hex-encoded primes from RFC 3625 are deprecated and
+ *             superseded by the corresponding macros providing them as
+ *             binary constants. Their hex-encoded constants are likely
+ *             to be removed in a future version of the library.
+ *
+ */
+#define MBEDTLS_DHM_RFC3526_MODP_2048_P                         \
+    MBEDTLS_DEPRECATED_STRING_CONSTANT(                         \
+        "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1"      \
+        "29024E088A67CC74020BBEA63B139B22514A08798E3404DD"      \
+        "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245"      \
+        "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED"      \
+        "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D"      \
+        "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F"      \
+        "83655D23DCA3AD961C62F356208552BB9ED529077096966D"      \
+        "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B"      \
+        "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9"      \
+        "DE2BCBF6955817183995497CEA956AE515D2261898FA0510"      \
+        "15728E5A8AACAA68FFFFFFFFFFFFFFFF" )
+
+/**
+ * The hexadecimal presentation of the chosen generator of the 2048-bit MODP
+ * Group, as defined in <em>RFC-3526: More Modular Exponential (MODP)
+ * Diffie-Hellman groups for Internet Key Exchange (IKE)</em>.
+ */
+#define MBEDTLS_DHM_RFC3526_MODP_2048_G                         \
+    MBEDTLS_DEPRECATED_STRING_CONSTANT( "02" )
+
+/**
+ * The hexadecimal presentation of the prime underlying the 3072-bit MODP
+ * Group, as defined in <em>RFC-3072: More Modular Exponential (MODP)
+ * Diffie-Hellman groups for Internet Key Exchange (IKE)</em>.
+ */
+#define MBEDTLS_DHM_RFC3526_MODP_3072_P                         \
+    MBEDTLS_DEPRECATED_STRING_CONSTANT(                         \
+        "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1"      \
+        "29024E088A67CC74020BBEA63B139B22514A08798E3404DD"      \
+        "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245"      \
+        "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED"      \
+        "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D"      \
+        "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F"      \
+        "83655D23DCA3AD961C62F356208552BB9ED529077096966D"      \
+        "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B"      \
+        "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9"      \
+        "DE2BCBF6955817183995497CEA956AE515D2261898FA0510"      \
+        "15728E5A8AAAC42DAD33170D04507A33A85521ABDF1CBA64"      \
+        "ECFB850458DBEF0A8AEA71575D060C7DB3970F85A6E1E4C7"      \
+        "ABF5AE8CDB0933D71E8C94E04A25619DCEE3D2261AD2EE6B"      \
+        "F12FFA06D98A0864D87602733EC86A64521F2B18177B200C"      \
+        "BBE117577A615D6C770988C0BAD946E208E24FA074E5AB31"      \
+        "43DB5BFCE0FD108E4B82D120A93AD2CAFFFFFFFFFFFFFFFF" )
+
+/**
+ * The hexadecimal presentation of the chosen generator of the 3072-bit MODP
+ * Group, as defined in <em>RFC-3526: More Modular Exponential (MODP)
+ * Diffie-Hellman groups for Internet Key Exchange (IKE)</em>.
+ */
+#define MBEDTLS_DHM_RFC3526_MODP_3072_G                      \
+    MBEDTLS_DEPRECATED_STRING_CONSTANT( "02" )
+
+/**
+ * The hexadecimal presentation of the prime underlying the 4096-bit MODP
+ * Group, as defined in <em>RFC-3526: More Modular Exponential (MODP)
+ * Diffie-Hellman groups for Internet Key Exchange (IKE)</em>.
+ */
+#define MBEDTLS_DHM_RFC3526_MODP_4096_P                      \
+    MBEDTLS_DEPRECATED_STRING_CONSTANT(                      \
+        "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1"   \
+        "29024E088A67CC74020BBEA63B139B22514A08798E3404DD"   \
+        "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245"   \
+        "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED"   \
+        "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D"   \
+        "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F"   \
+        "83655D23DCA3AD961C62F356208552BB9ED529077096966D"   \
+        "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B"   \
+        "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9"   \
+        "DE2BCBF6955817183995497CEA956AE515D2261898FA0510"   \
+        "15728E5A8AAAC42DAD33170D04507A33A85521ABDF1CBA64"   \
+        "ECFB850458DBEF0A8AEA71575D060C7DB3970F85A6E1E4C7"   \
+        "ABF5AE8CDB0933D71E8C94E04A25619DCEE3D2261AD2EE6B"   \
+        "F12FFA06D98A0864D87602733EC86A64521F2B18177B200C"   \
+        "BBE117577A615D6C770988C0BAD946E208E24FA074E5AB31"   \
+        "43DB5BFCE0FD108E4B82D120A92108011A723C12A787E6D7"   \
+        "88719A10BDBA5B2699C327186AF4E23C1A946834B6150BDA"   \
+        "2583E9CA2AD44CE8DBBBC2DB04DE8EF92E8EFC141FBECAA6"   \
+        "287C59474E6BC05D99B2964FA090C3A2233BA186515BE7ED"   \
+        "1F612970CEE2D7AFB81BDD762170481CD0069127D5B05AA9"   \
+        "93B4EA988D8FDDC186FFB7DC90A6C08F4DF435C934063199"   \
+        "FFFFFFFFFFFFFFFF" )
+
+/**
+ * The hexadecimal presentation of the chosen generator of the 4096-bit MODP
+ * Group, as defined in <em>RFC-3526: More Modular Exponential (MODP)
+ * Diffie-Hellman groups for Internet Key Exchange (IKE)</em>.
+ */
+#define MBEDTLS_DHM_RFC3526_MODP_4096_G                      \
+    MBEDTLS_DEPRECATED_STRING_CONSTANT( "02" )
+
+#endif /* MBEDTLS_DEPRECATED_REMOVED */
+
+/*
+ * Trustworthy DHM parameters in binary form
+ */
+
+#define MBEDTLS_DHM_RFC3526_MODP_2048_P_BIN {        \
+     0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, \
+     0xC9, 0x0F, 0xDA, 0xA2, 0x21, 0x68, 0xC2, 0x34, \
+     0xC4, 0xC6, 0x62, 0x8B, 0x80, 0xDC, 0x1C, 0xD1, \
+     0x29, 0x02, 0x4E, 0x08, 0x8A, 0x67, 0xCC, 0x74, \
+     0x02, 0x0B, 0xBE, 0xA6, 0x3B, 0x13, 0x9B, 0x22, \
+     0x51, 0x4A, 0x08, 0x79, 0x8E, 0x34, 0x04, 0xDD, \
+     0xEF, 0x95, 0x19, 0xB3, 0xCD, 0x3A, 0x43, 0x1B, \
+     0x30, 0x2B, 0x0A, 0x6D, 0xF2, 0x5F, 0x14, 0x37, \
+     0x4F, 0xE1, 0x35, 0x6D, 0x6D, 0x51, 0xC2, 0x45, \
+     0xE4, 0x85, 0xB5, 0x76, 0x62, 0x5E, 0x7E, 0xC6, \
+     0xF4, 0x4C, 0x42, 0xE9, 0xA6, 0x37, 0xED, 0x6B, \
+     0x0B, 0xFF, 0x5C, 0xB6, 0xF4, 0x06, 0xB7, 0xED, \
+     0xEE, 0x38, 0x6B, 0xFB, 0x5A, 0x89, 0x9F, 0xA5, \
+     0xAE, 0x9F, 0x24, 0x11, 0x7C, 0x4B, 0x1F, 0xE6, \
+     0x49, 0x28, 0x66, 0x51, 0xEC, 0xE4, 0x5B, 0x3D, \
+     0xC2, 0x00, 0x7C, 0xB8, 0xA1, 0x63, 0xBF, 0x05, \
+     0x98, 0xDA, 0x48, 0x36, 0x1C, 0x55, 0xD3, 0x9A, \
+     0x69, 0x16, 0x3F, 0xA8, 0xFD, 0x24, 0xCF, 0x5F, \
+     0x83, 0x65, 0x5D, 0x23, 0xDC, 0xA3, 0xAD, 0x96, \
+     0x1C, 0x62, 0xF3, 0x56, 0x20, 0x85, 0x52, 0xBB, \
+     0x9E, 0xD5, 0x29, 0x07, 0x70, 0x96, 0x96, 0x6D, \
+     0x67, 0x0C, 0x35, 0x4E, 0x4A, 0xBC, 0x98, 0x04, \
+     0xF1, 0x74, 0x6C, 0x08, 0xCA, 0x18, 0x21, 0x7C, \
+     0x32, 0x90, 0x5E, 0x46, 0x2E, 0x36, 0xCE, 0x3B, \
+     0xE3, 0x9E, 0x77, 0x2C, 0x18, 0x0E, 0x86, 0x03, \
+     0x9B, 0x27, 0x83, 0xA2, 0xEC, 0x07, 0xA2, 0x8F, \
+     0xB5, 0xC5, 0x5D, 0xF0, 0x6F, 0x4C, 0x52, 0xC9, \
+     0xDE, 0x2B, 0xCB, 0xF6, 0x95, 0x58, 0x17, 0x18, \
+     0x39, 0x95, 0x49, 0x7C, 0xEA, 0x95, 0x6A, 0xE5, \
+     0x15, 0xD2, 0x26, 0x18, 0x98, 0xFA, 0x05, 0x10, \
+     0x15, 0x72, 0x8E, 0x5A, 0x8A, 0xAC, 0xAA, 0x68, \
+     0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF }
+
+#define MBEDTLS_DHM_RFC3526_MODP_2048_G_BIN { 0x02 }
+
+#define MBEDTLS_DHM_RFC3526_MODP_3072_P_BIN {       \
+    0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, \
+    0xC9, 0x0F, 0xDA, 0xA2, 0x21, 0x68, 0xC2, 0x34, \
+    0xC4, 0xC6, 0x62, 0x8B, 0x80, 0xDC, 0x1C, 0xD1, \
+    0x29, 0x02, 0x4E, 0x08, 0x8A, 0x67, 0xCC, 0x74, \
+    0x02, 0x0B, 0xBE, 0xA6, 0x3B, 0x13, 0x9B, 0x22, \
+    0x51, 0x4A, 0x08, 0x79, 0x8E, 0x34, 0x04, 0xDD, \
+    0xEF, 0x95, 0x19, 0xB3, 0xCD, 0x3A, 0x43, 0x1B, \
+    0x30, 0x2B, 0x0A, 0x6D, 0xF2, 0x5F, 0x14, 0x37, \
+    0x4F, 0xE1, 0x35, 0x6D, 0x6D, 0x51, 0xC2, 0x45, \
+    0xE4, 0x85, 0xB5, 0x76, 0x62, 0x5E, 0x7E, 0xC6, \
+    0xF4, 0x4C, 0x42, 0xE9, 0xA6, 0x37, 0xED, 0x6B, \
+    0x0B, 0xFF, 0x5C, 0xB6, 0xF4, 0x06, 0xB7, 0xED, \
+    0xEE, 0x38, 0x6B, 0xFB, 0x5A, 0x89, 0x9F, 0xA5, \
+    0xAE, 0x9F, 0x24, 0x11, 0x7C, 0x4B, 0x1F, 0xE6, \
+    0x49, 0x28, 0x66, 0x51, 0xEC, 0xE4, 0x5B, 0x3D, \
+    0xC2, 0x00, 0x7C, 0xB8, 0xA1, 0x63, 0xBF, 0x05, \
+    0x98, 0xDA, 0x48, 0x36, 0x1C, 0x55, 0xD3, 0x9A, \
+    0x69, 0x16, 0x3F, 0xA8, 0xFD, 0x24, 0xCF, 0x5F, \
+    0x83, 0x65, 0x5D, 0x23, 0xDC, 0xA3, 0xAD, 0x96, \
+    0x1C, 0x62, 0xF3, 0x56, 0x20, 0x85, 0x52, 0xBB, \
+    0x9E, 0xD5, 0x29, 0x07, 0x70, 0x96, 0x96, 0x6D, \
+    0x67, 0x0C, 0x35, 0x4E, 0x4A, 0xBC, 0x98, 0x04, \
+    0xF1, 0x74, 0x6C, 0x08, 0xCA, 0x18, 0x21, 0x7C, \
+    0x32, 0x90, 0x5E, 0x46, 0x2E, 0x36, 0xCE, 0x3B, \
+    0xE3, 0x9E, 0x77, 0x2C, 0x18, 0x0E, 0x86, 0x03, \
+    0x9B, 0x27, 0x83, 0xA2, 0xEC, 0x07, 0xA2, 0x8F, \
+    0xB5, 0xC5, 0x5D, 0xF0, 0x6F, 0x4C, 0x52, 0xC9, \
+    0xDE, 0x2B, 0xCB, 0xF6, 0x95, 0x58, 0x17, 0x18, \
+    0x39, 0x95, 0x49, 0x7C, 0xEA, 0x95, 0x6A, 0xE5, \
+    0x15, 0xD2, 0x26, 0x18, 0x98, 0xFA, 0x05, 0x10, \
+    0x15, 0x72, 0x8E, 0x5A, 0x8A, 0xAA, 0xC4, 0x2D, \
+    0xAD, 0x33, 0x17, 0x0D, 0x04, 0x50, 0x7A, 0x33, \
+    0xA8, 0x55, 0x21, 0xAB, 0xDF, 0x1C, 0xBA, 0x64, \
+    0xEC, 0xFB, 0x85, 0x04, 0x58, 0xDB, 0xEF, 0x0A, \
+    0x8A, 0xEA, 0x71, 0x57, 0x5D, 0x06, 0x0C, 0x7D, \
+    0xB3, 0x97, 0x0F, 0x85, 0xA6, 0xE1, 0xE4, 0xC7, \
+    0xAB, 0xF5, 0xAE, 0x8C, 0xDB, 0x09, 0x33, 0xD7, \
+    0x1E, 0x8C, 0x94, 0xE0, 0x4A, 0x25, 0x61, 0x9D, \
+    0xCE, 0xE3, 0xD2, 0x26, 0x1A, 0xD2, 0xEE, 0x6B, \
+    0xF1, 0x2F, 0xFA, 0x06, 0xD9, 0x8A, 0x08, 0x64, \
+    0xD8, 0x76, 0x02, 0x73, 0x3E, 0xC8, 0x6A, 0x64, \
+    0x52, 0x1F, 0x2B, 0x18, 0x17, 0x7B, 0x20, 0x0C, \
+    0xBB, 0xE1, 0x17, 0x57, 0x7A, 0x61, 0x5D, 0x6C, \
+    0x77, 0x09, 0x88, 0xC0, 0xBA, 0xD9, 0x46, 0xE2, \
+    0x08, 0xE2, 0x4F, 0xA0, 0x74, 0xE5, 0xAB, 0x31, \
+    0x43, 0xDB, 0x5B, 0xFC, 0xE0, 0xFD, 0x10, 0x8E, \
+    0x4B, 0x82, 0xD1, 0x20, 0xA9, 0x3A, 0xD2, 0xCA, \
+    0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF }
+
+#define MBEDTLS_DHM_RFC3526_MODP_3072_G_BIN { 0x02 }
+
+#define MBEDTLS_DHM_RFC3526_MODP_4096_P_BIN  {       \
+    0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,  \
+    0xC9, 0x0F, 0xDA, 0xA2, 0x21, 0x68, 0xC2, 0x34,  \
+    0xC4, 0xC6, 0x62, 0x8B, 0x80, 0xDC, 0x1C, 0xD1,  \
+    0x29, 0x02, 0x4E, 0x08, 0x8A, 0x67, 0xCC, 0x74,  \
+    0x02, 0x0B, 0xBE, 0xA6, 0x3B, 0x13, 0x9B, 0x22,  \
+    0x51, 0x4A, 0x08, 0x79, 0x8E, 0x34, 0x04, 0xDD,  \
+    0xEF, 0x95, 0x19, 0xB3, 0xCD, 0x3A, 0x43, 0x1B,  \
+    0x30, 0x2B, 0x0A, 0x6D, 0xF2, 0x5F, 0x14, 0x37,  \
+    0x4F, 0xE1, 0x35, 0x6D, 0x6D, 0x51, 0xC2, 0x45,  \
+    0xE4, 0x85, 0xB5, 0x76, 0x62, 0x5E, 0x7E, 0xC6,  \
+    0xF4, 0x4C, 0x42, 0xE9, 0xA6, 0x37, 0xED, 0x6B,  \
+    0x0B, 0xFF, 0x5C, 0xB6, 0xF4, 0x06, 0xB7, 0xED,  \
+    0xEE, 0x38, 0x6B, 0xFB, 0x5A, 0x89, 0x9F, 0xA5,  \
+    0xAE, 0x9F, 0x24, 0x11, 0x7C, 0x4B, 0x1F, 0xE6,  \
+    0x49, 0x28, 0x66, 0x51, 0xEC, 0xE4, 0x5B, 0x3D,  \
+    0xC2, 0x00, 0x7C, 0xB8, 0xA1, 0x63, 0xBF, 0x05,  \
+    0x98, 0xDA, 0x48, 0x36, 0x1C, 0x55, 0xD3, 0x9A,  \
+    0x69, 0x16, 0x3F, 0xA8, 0xFD, 0x24, 0xCF, 0x5F,  \
+    0x83, 0x65, 0x5D, 0x23, 0xDC, 0xA3, 0xAD, 0x96,  \
+    0x1C, 0x62, 0xF3, 0x56, 0x20, 0x85, 0x52, 0xBB,  \
+    0x9E, 0xD5, 0x29, 0x07, 0x70, 0x96, 0x96, 0x6D,  \
+    0x67, 0x0C, 0x35, 0x4E, 0x4A, 0xBC, 0x98, 0x04,  \
+    0xF1, 0x74, 0x6C, 0x08, 0xCA, 0x18, 0x21, 0x7C,  \
+    0x32, 0x90, 0x5E, 0x46, 0x2E, 0x36, 0xCE, 0x3B,  \
+    0xE3, 0x9E, 0x77, 0x2C, 0x18, 0x0E, 0x86, 0x03,  \
+    0x9B, 0x27, 0x83, 0xA2, 0xEC, 0x07, 0xA2, 0x8F,  \
+    0xB5, 0xC5, 0x5D, 0xF0, 0x6F, 0x4C, 0x52, 0xC9,  \
+    0xDE, 0x2B, 0xCB, 0xF6, 0x95, 0x58, 0x17, 0x18,  \
+    0x39, 0x95, 0x49, 0x7C, 0xEA, 0x95, 0x6A, 0xE5,  \
+    0x15, 0xD2, 0x26, 0x18, 0x98, 0xFA, 0x05, 0x10,  \
+    0x15, 0x72, 0x8E, 0x5A, 0x8A, 0xAA, 0xC4, 0x2D,  \
+    0xAD, 0x33, 0x17, 0x0D, 0x04, 0x50, 0x7A, 0x33,  \
+    0xA8, 0x55, 0x21, 0xAB, 0xDF, 0x1C, 0xBA, 0x64,  \
+    0xEC, 0xFB, 0x85, 0x04, 0x58, 0xDB, 0xEF, 0x0A,  \
+    0x8A, 0xEA, 0x71, 0x57, 0x5D, 0x06, 0x0C, 0x7D,  \
+    0xB3, 0x97, 0x0F, 0x85, 0xA6, 0xE1, 0xE4, 0xC7,  \
+    0xAB, 0xF5, 0xAE, 0x8C, 0xDB, 0x09, 0x33, 0xD7,  \
+    0x1E, 0x8C, 0x94, 0xE0, 0x4A, 0x25, 0x61, 0x9D,  \
+    0xCE, 0xE3, 0xD2, 0x26, 0x1A, 0xD2, 0xEE, 0x6B,  \
+    0xF1, 0x2F, 0xFA, 0x06, 0xD9, 0x8A, 0x08, 0x64,  \
+    0xD8, 0x76, 0x02, 0x73, 0x3E, 0xC8, 0x6A, 0x64,  \
+    0x52, 0x1F, 0x2B, 0x18, 0x17, 0x7B, 0x20, 0x0C,  \
+    0xBB, 0xE1, 0x17, 0x57, 0x7A, 0x61, 0x5D, 0x6C,  \
+    0x77, 0x09, 0x88, 0xC0, 0xBA, 0xD9, 0x46, 0xE2,  \
+    0x08, 0xE2, 0x4F, 0xA0, 0x74, 0xE5, 0xAB, 0x31,  \
+    0x43, 0xDB, 0x5B, 0xFC, 0xE0, 0xFD, 0x10, 0x8E,  \
+    0x4B, 0x82, 0xD1, 0x20, 0xA9, 0x21, 0x08, 0x01,  \
+    0x1A, 0x72, 0x3C, 0x12, 0xA7, 0x87, 0xE6, 0xD7,  \
+    0x88, 0x71, 0x9A, 0x10, 0xBD, 0xBA, 0x5B, 0x26,  \
+    0x99, 0xC3, 0x27, 0x18, 0x6A, 0xF4, 0xE2, 0x3C,  \
+    0x1A, 0x94, 0x68, 0x34, 0xB6, 0x15, 0x0B, 0xDA,  \
+    0x25, 0x83, 0xE9, 0xCA, 0x2A, 0xD4, 0x4C, 0xE8,  \
+    0xDB, 0xBB, 0xC2, 0xDB, 0x04, 0xDE, 0x8E, 0xF9,  \
+    0x2E, 0x8E, 0xFC, 0x14, 0x1F, 0xBE, 0xCA, 0xA6,  \
+    0x28, 0x7C, 0x59, 0x47, 0x4E, 0x6B, 0xC0, 0x5D,  \
+    0x99, 0xB2, 0x96, 0x4F, 0xA0, 0x90, 0xC3, 0xA2,  \
+    0x23, 0x3B, 0xA1, 0x86, 0x51, 0x5B, 0xE7, 0xED,  \
+    0x1F, 0x61, 0x29, 0x70, 0xCE, 0xE2, 0xD7, 0xAF,  \
+    0xB8, 0x1B, 0xDD, 0x76, 0x21, 0x70, 0x48, 0x1C,  \
+    0xD0, 0x06, 0x91, 0x27, 0xD5, 0xB0, 0x5A, 0xA9,  \
+    0x93, 0xB4, 0xEA, 0x98, 0x8D, 0x8F, 0xDD, 0xC1,  \
+    0x86, 0xFF, 0xB7, 0xDC, 0x90, 0xA6, 0xC0, 0x8F,  \
+    0x4D, 0xF4, 0x35, 0xC9, 0x34, 0x06, 0x31, 0x99,  \
+    0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF }
+
+#define MBEDTLS_DHM_RFC3526_MODP_4096_G_BIN { 0x02 }
+
+#define MBEDTLS_DHM_RFC7919_FFDHE2048_P_BIN {        \
+     0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, \
+     0xAD, 0xF8, 0x54, 0x58, 0xA2, 0xBB, 0x4A, 0x9A, \
+     0xAF, 0xDC, 0x56, 0x20, 0x27, 0x3D, 0x3C, 0xF1, \
+     0xD8, 0xB9, 0xC5, 0x83, 0xCE, 0x2D, 0x36, 0x95, \
+     0xA9, 0xE1, 0x36, 0x41, 0x14, 0x64, 0x33, 0xFB, \
+     0xCC, 0x93, 0x9D, 0xCE, 0x24, 0x9B, 0x3E, 0xF9, \
+     0x7D, 0x2F, 0xE3, 0x63, 0x63, 0x0C, 0x75, 0xD8, \
+     0xF6, 0x81, 0xB2, 0x02, 0xAE, 0xC4, 0x61, 0x7A, \
+     0xD3, 0xDF, 0x1E, 0xD5, 0xD5, 0xFD, 0x65, 0x61, \
+     0x24, 0x33, 0xF5, 0x1F, 0x5F, 0x06, 0x6E, 0xD0, \
+     0x85, 0x63, 0x65, 0x55, 0x3D, 0xED, 0x1A, 0xF3, \
+     0xB5, 0x57, 0x13, 0x5E, 0x7F, 0x57, 0xC9, 0x35, \
+     0x98, 0x4F, 0x0C, 0x70, 0xE0, 0xE6, 0x8B, 0x77, \
+     0xE2, 0xA6, 0x89, 0xDA, 0xF3, 0xEF, 0xE8, 0x72, \
+     0x1D, 0xF1, 0x58, 0xA1, 0x36, 0xAD, 0xE7, 0x35, \
+     0x30, 0xAC, 0xCA, 0x4F, 0x48, 0x3A, 0x79, 0x7A, \
+     0xBC, 0x0A, 0xB1, 0x82, 0xB3, 0x24, 0xFB, 0x61, \
+     0xD1, 0x08, 0xA9, 0x4B, 0xB2, 0xC8, 0xE3, 0xFB, \
+     0xB9, 0x6A, 0xDA, 0xB7, 0x60, 0xD7, 0xF4, 0x68, \
+     0x1D, 0x4F, 0x42, 0xA3, 0xDE, 0x39, 0x4D, 0xF4, \
+     0xAE, 0x56, 0xED, 0xE7, 0x63, 0x72, 0xBB, 0x19, \
+     0x0B, 0x07, 0xA7, 0xC8, 0xEE, 0x0A, 0x6D, 0x70, \
+     0x9E, 0x02, 0xFC, 0xE1, 0xCD, 0xF7, 0xE2, 0xEC, \
+     0xC0, 0x34, 0x04, 0xCD, 0x28, 0x34, 0x2F, 0x61, \
+     0x91, 0x72, 0xFE, 0x9C, 0xE9, 0x85, 0x83, 0xFF, \
+     0x8E, 0x4F, 0x12, 0x32, 0xEE, 0xF2, 0x81, 0x83, \
+     0xC3, 0xFE, 0x3B, 0x1B, 0x4C, 0x6F, 0xAD, 0x73, \
+     0x3B, 0xB5, 0xFC, 0xBC, 0x2E, 0xC2, 0x20, 0x05, \
+     0xC5, 0x8E, 0xF1, 0x83, 0x7D, 0x16, 0x83, 0xB2, \
+     0xC6, 0xF3, 0x4A, 0x26, 0xC1, 0xB2, 0xEF, 0xFA, \
+     0x88, 0x6B, 0x42, 0x38, 0x61, 0x28, 0x5C, 0x97, \
+     0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, }
+
+#define MBEDTLS_DHM_RFC7919_FFDHE2048_G_BIN { 0x02 }
+
+#define MBEDTLS_DHM_RFC7919_FFDHE3072_P_BIN { \
+     0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, \
+     0xAD, 0xF8, 0x54, 0x58, 0xA2, 0xBB, 0x4A, 0x9A, \
+     0xAF, 0xDC, 0x56, 0x20, 0x27, 0x3D, 0x3C, 0xF1, \
+     0xD8, 0xB9, 0xC5, 0x83, 0xCE, 0x2D, 0x36, 0x95, \
+     0xA9, 0xE1, 0x36, 0x41, 0x14, 0x64, 0x33, 0xFB, \
+     0xCC, 0x93, 0x9D, 0xCE, 0x24, 0x9B, 0x3E, 0xF9, \
+     0x7D, 0x2F, 0xE3, 0x63, 0x63, 0x0C, 0x75, 0xD8, \
+     0xF6, 0x81, 0xB2, 0x02, 0xAE, 0xC4, 0x61, 0x7A, \
+     0xD3, 0xDF, 0x1E, 0xD5, 0xD5, 0xFD, 0x65, 0x61, \
+     0x24, 0x33, 0xF5, 0x1F, 0x5F, 0x06, 0x6E, 0xD0, \
+     0x85, 0x63, 0x65, 0x55, 0x3D, 0xED, 0x1A, 0xF3, \
+     0xB5, 0x57, 0x13, 0x5E, 0x7F, 0x57, 0xC9, 0x35, \
+     0x98, 0x4F, 0x0C, 0x70, 0xE0, 0xE6, 0x8B, 0x77, \
+     0xE2, 0xA6, 0x89, 0xDA, 0xF3, 0xEF, 0xE8, 0x72, \
+     0x1D, 0xF1, 0x58, 0xA1, 0x36, 0xAD, 0xE7, 0x35, \
+     0x30, 0xAC, 0xCA, 0x4F, 0x48, 0x3A, 0x79, 0x7A, \
+     0xBC, 0x0A, 0xB1, 0x82, 0xB3, 0x24, 0xFB, 0x61, \
+     0xD1, 0x08, 0xA9, 0x4B, 0xB2, 0xC8, 0xE3, 0xFB, \
+     0xB9, 0x6A, 0xDA, 0xB7, 0x60, 0xD7, 0xF4, 0x68, \
+     0x1D, 0x4F, 0x42, 0xA3, 0xDE, 0x39, 0x4D, 0xF4, \
+     0xAE, 0x56, 0xED, 0xE7, 0x63, 0x72, 0xBB, 0x19, \
+     0x0B, 0x07, 0xA7, 0xC8, 0xEE, 0x0A, 0x6D, 0x70, \
+     0x9E, 0x02, 0xFC, 0xE1, 0xCD, 0xF7, 0xE2, 0xEC, \
+     0xC0, 0x34, 0x04, 0xCD, 0x28, 0x34, 0x2F, 0x61, \
+     0x91, 0x72, 0xFE, 0x9C, 0xE9, 0x85, 0x83, 0xFF, \
+     0x8E, 0x4F, 0x12, 0x32, 0xEE, 0xF2, 0x81, 0x83, \
+     0xC3, 0xFE, 0x3B, 0x1B, 0x4C, 0x6F, 0xAD, 0x73, \
+     0x3B, 0xB5, 0xFC, 0xBC, 0x2E, 0xC2, 0x20, 0x05, \
+     0xC5, 0x8E, 0xF1, 0x83, 0x7D, 0x16, 0x83, 0xB2, \
+     0xC6, 0xF3, 0x4A, 0x26, 0xC1, 0xB2, 0xEF, 0xFA, \
+     0x88, 0x6B, 0x42, 0x38, 0x61, 0x1F, 0xCF, 0xDC, \
+     0xDE, 0x35, 0x5B, 0x3B, 0x65, 0x19, 0x03, 0x5B, \
+     0xBC, 0x34, 0xF4, 0xDE, 0xF9, 0x9C, 0x02, 0x38, \
+     0x61, 0xB4, 0x6F, 0xC9, 0xD6, 0xE6, 0xC9, 0x07, \
+     0x7A, 0xD9, 0x1D, 0x26, 0x91, 0xF7, 0xF7, 0xEE, \
+     0x59, 0x8C, 0xB0, 0xFA, 0xC1, 0x86, 0xD9, 0x1C, \
+     0xAE, 0xFE, 0x13, 0x09, 0x85, 0x13, 0x92, 0x70, \
+     0xB4, 0x13, 0x0C, 0x93, 0xBC, 0x43, 0x79, 0x44, \
+     0xF4, 0xFD, 0x44, 0x52, 0xE2, 0xD7, 0x4D, 0xD3, \
+     0x64, 0xF2, 0xE2, 0x1E, 0x71, 0xF5, 0x4B, 0xFF, \
+     0x5C, 0xAE, 0x82, 0xAB, 0x9C, 0x9D, 0xF6, 0x9E, \
+     0xE8, 0x6D, 0x2B, 0xC5, 0x22, 0x36, 0x3A, 0x0D, \
+     0xAB, 0xC5, 0x21, 0x97, 0x9B, 0x0D, 0xEA, 0xDA, \
+     0x1D, 0xBF, 0x9A, 0x42, 0xD5, 0xC4, 0x48, 0x4E, \
+     0x0A, 0xBC, 0xD0, 0x6B, 0xFA, 0x53, 0xDD, 0xEF, \
+     0x3C, 0x1B, 0x20, 0xEE, 0x3F, 0xD5, 0x9D, 0x7C, \
+     0x25, 0xE4, 0x1D, 0x2B, 0x66, 0xC6, 0x2E, 0x37, \
+     0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF }
+
+#define MBEDTLS_DHM_RFC7919_FFDHE3072_G_BIN { 0x02 }
+
+#define MBEDTLS_DHM_RFC7919_FFDHE4096_P_BIN {        \
+     0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, \
+     0xAD, 0xF8, 0x54, 0x58, 0xA2, 0xBB, 0x4A, 0x9A, \
+     0xAF, 0xDC, 0x56, 0x20, 0x27, 0x3D, 0x3C, 0xF1, \
+     0xD8, 0xB9, 0xC5, 0x83, 0xCE, 0x2D, 0x36, 0x95, \
+     0xA9, 0xE1, 0x36, 0x41, 0x14, 0x64, 0x33, 0xFB, \
+     0xCC, 0x93, 0x9D, 0xCE, 0x24, 0x9B, 0x3E, 0xF9, \
+     0x7D, 0x2F, 0xE3, 0x63, 0x63, 0x0C, 0x75, 0xD8, \
+     0xF6, 0x81, 0xB2, 0x02, 0xAE, 0xC4, 0x61, 0x7A, \
+     0xD3, 0xDF, 0x1E, 0xD5, 0xD5, 0xFD, 0x65, 0x61, \
+     0x24, 0x33, 0xF5, 0x1F, 0x5F, 0x06, 0x6E, 0xD0, \
+     0x85, 0x63, 0x65, 0x55, 0x3D, 0xED, 0x1A, 0xF3, \
+     0xB5, 0x57, 0x13, 0x5E, 0x7F, 0x57, 0xC9, 0x35, \
+     0x98, 0x4F, 0x0C, 0x70, 0xE0, 0xE6, 0x8B, 0x77, \
+     0xE2, 0xA6, 0x89, 0xDA, 0xF3, 0xEF, 0xE8, 0x72, \
+     0x1D, 0xF1, 0x58, 0xA1, 0x36, 0xAD, 0xE7, 0x35, \
+     0x30, 0xAC, 0xCA, 0x4F, 0x48, 0x3A, 0x79, 0x7A, \
+     0xBC, 0x0A, 0xB1, 0x82, 0xB3, 0x24, 0xFB, 0x61, \
+     0xD1, 0x08, 0xA9, 0x4B, 0xB2, 0xC8, 0xE3, 0xFB, \
+     0xB9, 0x6A, 0xDA, 0xB7, 0x60, 0xD7, 0xF4, 0x68, \
+     0x1D, 0x4F, 0x42, 0xA3, 0xDE, 0x39, 0x4D, 0xF4, \
+     0xAE, 0x56, 0xED, 0xE7, 0x63, 0x72, 0xBB, 0x19, \
+     0x0B, 0x07, 0xA7, 0xC8, 0xEE, 0x0A, 0x6D, 0x70, \
+     0x9E, 0x02, 0xFC, 0xE1, 0xCD, 0xF7, 0xE2, 0xEC, \
+     0xC0, 0x34, 0x04, 0xCD, 0x28, 0x34, 0x2F, 0x61, \
+     0x91, 0x72, 0xFE, 0x9C, 0xE9, 0x85, 0x83, 0xFF, \
+     0x8E, 0x4F, 0x12, 0x32, 0xEE, 0xF2, 0x81, 0x83, \
+     0xC3, 0xFE, 0x3B, 0x1B, 0x4C, 0x6F, 0xAD, 0x73, \
+     0x3B, 0xB5, 0xFC, 0xBC, 0x2E, 0xC2, 0x20, 0x05, \
+     0xC5, 0x8E, 0xF1, 0x83, 0x7D, 0x16, 0x83, 0xB2, \
+     0xC6, 0xF3, 0x4A, 0x26, 0xC1, 0xB2, 0xEF, 0xFA, \
+     0x88, 0x6B, 0x42, 0x38, 0x61, 0x1F, 0xCF, 0xDC, \
+     0xDE, 0x35, 0x5B, 0x3B, 0x65, 0x19, 0x03, 0x5B, \
+     0xBC, 0x34, 0xF4, 0xDE, 0xF9, 0x9C, 0x02, 0x38, \
+     0x61, 0xB4, 0x6F, 0xC9, 0xD6, 0xE6, 0xC9, 0x07, \
+     0x7A, 0xD9, 0x1D, 0x26, 0x91, 0xF7, 0xF7, 0xEE, \
+     0x59, 0x8C, 0xB0, 0xFA, 0xC1, 0x86, 0xD9, 0x1C, \
+     0xAE, 0xFE, 0x13, 0x09, 0x85, 0x13, 0x92, 0x70, \
+     0xB4, 0x13, 0x0C, 0x93, 0xBC, 0x43, 0x79, 0x44, \
+     0xF4, 0xFD, 0x44, 0x52, 0xE2, 0xD7, 0x4D, 0xD3, \
+     0x64, 0xF2, 0xE2, 0x1E, 0x71, 0xF5, 0x4B, 0xFF, \
+     0x5C, 0xAE, 0x82, 0xAB, 0x9C, 0x9D, 0xF6, 0x9E, \
+     0xE8, 0x6D, 0x2B, 0xC5, 0x22, 0x36, 0x3A, 0x0D, \
+     0xAB, 0xC5, 0x21, 0x97, 0x9B, 0x0D, 0xEA, 0xDA, \
+     0x1D, 0xBF, 0x9A, 0x42, 0xD5, 0xC4, 0x48, 0x4E, \
+     0x0A, 0xBC, 0xD0, 0x6B, 0xFA, 0x53, 0xDD, 0xEF, \
+     0x3C, 0x1B, 0x20, 0xEE, 0x3F, 0xD5, 0x9D, 0x7C, \
+     0x25, 0xE4, 0x1D, 0x2B, 0x66, 0x9E, 0x1E, 0xF1, \
+     0x6E, 0x6F, 0x52, 0xC3, 0x16, 0x4D, 0xF4, 0xFB, \
+     0x79, 0x30, 0xE9, 0xE4, 0xE5, 0x88, 0x57, 0xB6, \
+     0xAC, 0x7D, 0x5F, 0x42, 0xD6, 0x9F, 0x6D, 0x18, \
+     0x77, 0x63, 0xCF, 0x1D, 0x55, 0x03, 0x40, 0x04, \
+     0x87, 0xF5, 0x5B, 0xA5, 0x7E, 0x31, 0xCC, 0x7A, \
+     0x71, 0x35, 0xC8, 0x86, 0xEF, 0xB4, 0x31, 0x8A, \
+     0xED, 0x6A, 0x1E, 0x01, 0x2D, 0x9E, 0x68, 0x32, \
+     0xA9, 0x07, 0x60, 0x0A, 0x91, 0x81, 0x30, 0xC4, \
+     0x6D, 0xC7, 0x78, 0xF9, 0x71, 0xAD, 0x00, 0x38, \
+     0x09, 0x29, 0x99, 0xA3, 0x33, 0xCB, 0x8B, 0x7A, \
+     0x1A, 0x1D, 0xB9, 0x3D, 0x71, 0x40, 0x00, 0x3C, \
+     0x2A, 0x4E, 0xCE, 0xA9, 0xF9, 0x8D, 0x0A, 0xCC, \
+     0x0A, 0x82, 0x91, 0xCD, 0xCE, 0xC9, 0x7D, 0xCF, \
+     0x8E, 0xC9, 0xB5, 0x5A, 0x7F, 0x88, 0xA4, 0x6B, \
+     0x4D, 0xB5, 0xA8, 0x51, 0xF4, 0x41, 0x82, 0xE1, \
+     0xC6, 0x8A, 0x00, 0x7E, 0x5E, 0x65, 0x5F, 0x6A, \
+     0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF }
+
+#define MBEDTLS_DHM_RFC7919_FFDHE4096_G_BIN { 0x02 }
+
+#define MBEDTLS_DHM_RFC7919_FFDHE6144_P_BIN {        \
+     0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, \
+     0xAD, 0xF8, 0x54, 0x58, 0xA2, 0xBB, 0x4A, 0x9A, \
+     0xAF, 0xDC, 0x56, 0x20, 0x27, 0x3D, 0x3C, 0xF1, \
+     0xD8, 0xB9, 0xC5, 0x83, 0xCE, 0x2D, 0x36, 0x95, \
+     0xA9, 0xE1, 0x36, 0x41, 0x14, 0x64, 0x33, 0xFB, \
+     0xCC, 0x93, 0x9D, 0xCE, 0x24, 0x9B, 0x3E, 0xF9, \
+     0x7D, 0x2F, 0xE3, 0x63, 0x63, 0x0C, 0x75, 0xD8, \
+     0xF6, 0x81, 0xB2, 0x02, 0xAE, 0xC4, 0x61, 0x7A, \
+     0xD3, 0xDF, 0x1E, 0xD5, 0xD5, 0xFD, 0x65, 0x61, \
+     0x24, 0x33, 0xF5, 0x1F, 0x5F, 0x06, 0x6E, 0xD0, \
+     0x85, 0x63, 0x65, 0x55, 0x3D, 0xED, 0x1A, 0xF3, \
+     0xB5, 0x57, 0x13, 0x5E, 0x7F, 0x57, 0xC9, 0x35, \
+     0x98, 0x4F, 0x0C, 0x70, 0xE0, 0xE6, 0x8B, 0x77, \
+     0xE2, 0xA6, 0x89, 0xDA, 0xF3, 0xEF, 0xE8, 0x72, \
+     0x1D, 0xF1, 0x58, 0xA1, 0x36, 0xAD, 0xE7, 0x35, \
+     0x30, 0xAC, 0xCA, 0x4F, 0x48, 0x3A, 0x79, 0x7A, \
+     0xBC, 0x0A, 0xB1, 0x82, 0xB3, 0x24, 0xFB, 0x61, \
+     0xD1, 0x08, 0xA9, 0x4B, 0xB2, 0xC8, 0xE3, 0xFB, \
+     0xB9, 0x6A, 0xDA, 0xB7, 0x60, 0xD7, 0xF4, 0x68, \
+     0x1D, 0x4F, 0x42, 0xA3, 0xDE, 0x39, 0x4D, 0xF4, \
+     0xAE, 0x56, 0xED, 0xE7, 0x63, 0x72, 0xBB, 0x19, \
+     0x0B, 0x07, 0xA7, 0xC8, 0xEE, 0x0A, 0x6D, 0x70, \
+     0x9E, 0x02, 0xFC, 0xE1, 0xCD, 0xF7, 0xE2, 0xEC, \
+     0xC0, 0x34, 0x04, 0xCD, 0x28, 0x34, 0x2F, 0x61, \
+     0x91, 0x72, 0xFE, 0x9C, 0xE9, 0x85, 0x83, 0xFF, \
+     0x8E, 0x4F, 0x12, 0x32, 0xEE, 0xF2, 0x81, 0x83, \
+     0xC3, 0xFE, 0x3B, 0x1B, 0x4C, 0x6F, 0xAD, 0x73, \
+     0x3B, 0xB5, 0xFC, 0xBC, 0x2E, 0xC2, 0x20, 0x05, \
+     0xC5, 0x8E, 0xF1, 0x83, 0x7D, 0x16, 0x83, 0xB2, \
+     0xC6, 0xF3, 0x4A, 0x26, 0xC1, 0xB2, 0xEF, 0xFA, \
+     0x88, 0x6B, 0x42, 0x38, 0x61, 0x1F, 0xCF, 0xDC, \
+     0xDE, 0x35, 0x5B, 0x3B, 0x65, 0x19, 0x03, 0x5B, \
+     0xBC, 0x34, 0xF4, 0xDE, 0xF9, 0x9C, 0x02, 0x38, \
+     0x61, 0xB4, 0x6F, 0xC9, 0xD6, 0xE6, 0xC9, 0x07, \
+     0x7A, 0xD9, 0x1D, 0x26, 0x91, 0xF7, 0xF7, 0xEE, \
+     0x59, 0x8C, 0xB0, 0xFA, 0xC1, 0x86, 0xD9, 0x1C, \
+     0xAE, 0xFE, 0x13, 0x09, 0x85, 0x13, 0x92, 0x70, \
+     0xB4, 0x13, 0x0C, 0x93, 0xBC, 0x43, 0x79, 0x44, \
+     0xF4, 0xFD, 0x44, 0x52, 0xE2, 0xD7, 0x4D, 0xD3, \
+     0x64, 0xF2, 0xE2, 0x1E, 0x71, 0xF5, 0x4B, 0xFF, \
+     0x5C, 0xAE, 0x82, 0xAB, 0x9C, 0x9D, 0xF6, 0x9E, \
+     0xE8, 0x6D, 0x2B, 0xC5, 0x22, 0x36, 0x3A, 0x0D, \
+     0xAB, 0xC5, 0x21, 0x97, 0x9B, 0x0D, 0xEA, 0xDA, \
+     0x1D, 0xBF, 0x9A, 0x42, 0xD5, 0xC4, 0x48, 0x4E, \
+     0x0A, 0xBC, 0xD0, 0x6B, 0xFA, 0x53, 0xDD, 0xEF, \
+     0x3C, 0x1B, 0x20, 0xEE, 0x3F, 0xD5, 0x9D, 0x7C, \
+     0x25, 0xE4, 0x1D, 0x2B, 0x66, 0x9E, 0x1E, 0xF1, \
+     0x6E, 0x6F, 0x52, 0xC3, 0x16, 0x4D, 0xF4, 0xFB, \
+     0x79, 0x30, 0xE9, 0xE4, 0xE5, 0x88, 0x57, 0xB6, \
+     0xAC, 0x7D, 0x5F, 0x42, 0xD6, 0x9F, 0x6D, 0x18, \
+     0x77, 0x63, 0xCF, 0x1D, 0x55, 0x03, 0x40, 0x04, \
+     0x87, 0xF5, 0x5B, 0xA5, 0x7E, 0x31, 0xCC, 0x7A, \
+     0x71, 0x35, 0xC8, 0x86, 0xEF, 0xB4, 0x31, 0x8A, \
+     0xED, 0x6A, 0x1E, 0x01, 0x2D, 0x9E, 0x68, 0x32, \
+     0xA9, 0x07, 0x60, 0x0A, 0x91, 0x81, 0x30, 0xC4, \
+     0x6D, 0xC7, 0x78, 0xF9, 0x71, 0xAD, 0x00, 0x38, \
+     0x09, 0x29, 0x99, 0xA3, 0x33, 0xCB, 0x8B, 0x7A, \
+     0x1A, 0x1D, 0xB9, 0x3D, 0x71, 0x40, 0x00, 0x3C, \
+     0x2A, 0x4E, 0xCE, 0xA9, 0xF9, 0x8D, 0x0A, 0xCC, \
+     0x0A, 0x82, 0x91, 0xCD, 0xCE, 0xC9, 0x7D, 0xCF, \
+     0x8E, 0xC9, 0xB5, 0x5A, 0x7F, 0x88, 0xA4, 0x6B, \
+     0x4D, 0xB5, 0xA8, 0x51, 0xF4, 0x41, 0x82, 0xE1, \
+     0xC6, 0x8A, 0x00, 0x7E, 0x5E, 0x0D, 0xD9, 0x02, \
+     0x0B, 0xFD, 0x64, 0xB6, 0x45, 0x03, 0x6C, 0x7A, \
+     0x4E, 0x67, 0x7D, 0x2C, 0x38, 0x53, 0x2A, 0x3A, \
+     0x23, 0xBA, 0x44, 0x42, 0xCA, 0xF5, 0x3E, 0xA6, \
+     0x3B, 0xB4, 0x54, 0x32, 0x9B, 0x76, 0x24, 0xC8, \
+     0x91, 0x7B, 0xDD, 0x64, 0xB1, 0xC0, 0xFD, 0x4C, \
+     0xB3, 0x8E, 0x8C, 0x33, 0x4C, 0x70, 0x1C, 0x3A, \
+     0xCD, 0xAD, 0x06, 0x57, 0xFC, 0xCF, 0xEC, 0x71, \
+     0x9B, 0x1F, 0x5C, 0x3E, 0x4E, 0x46, 0x04, 0x1F, \
+     0x38, 0x81, 0x47, 0xFB, 0x4C, 0xFD, 0xB4, 0x77, \
+     0xA5, 0x24, 0x71, 0xF7, 0xA9, 0xA9, 0x69, 0x10, \
+     0xB8, 0x55, 0x32, 0x2E, 0xDB, 0x63, 0x40, 0xD8, \
+     0xA0, 0x0E, 0xF0, 0x92, 0x35, 0x05, 0x11, 0xE3, \
+     0x0A, 0xBE, 0xC1, 0xFF, 0xF9, 0xE3, 0xA2, 0x6E, \
+     0x7F, 0xB2, 0x9F, 0x8C, 0x18, 0x30, 0x23, 0xC3, \
+     0x58, 0x7E, 0x38, 0xDA, 0x00, 0x77, 0xD9, 0xB4, \
+     0x76, 0x3E, 0x4E, 0x4B, 0x94, 0xB2, 0xBB, 0xC1, \
+     0x94, 0xC6, 0x65, 0x1E, 0x77, 0xCA, 0xF9, 0x92, \
+     0xEE, 0xAA, 0xC0, 0x23, 0x2A, 0x28, 0x1B, 0xF6, \
+     0xB3, 0xA7, 0x39, 0xC1, 0x22, 0x61, 0x16, 0x82, \
+     0x0A, 0xE8, 0xDB, 0x58, 0x47, 0xA6, 0x7C, 0xBE, \
+     0xF9, 0xC9, 0x09, 0x1B, 0x46, 0x2D, 0x53, 0x8C, \
+     0xD7, 0x2B, 0x03, 0x74, 0x6A, 0xE7, 0x7F, 0x5E, \
+     0x62, 0x29, 0x2C, 0x31, 0x15, 0x62, 0xA8, 0x46, \
+     0x50, 0x5D, 0xC8, 0x2D, 0xB8, 0x54, 0x33, 0x8A, \
+     0xE4, 0x9F, 0x52, 0x35, 0xC9, 0x5B, 0x91, 0x17, \
+     0x8C, 0xCF, 0x2D, 0xD5, 0xCA, 0xCE, 0xF4, 0x03, \
+     0xEC, 0x9D, 0x18, 0x10, 0xC6, 0x27, 0x2B, 0x04, \
+     0x5B, 0x3B, 0x71, 0xF9, 0xDC, 0x6B, 0x80, 0xD6, \
+     0x3F, 0xDD, 0x4A, 0x8E, 0x9A, 0xDB, 0x1E, 0x69, \
+     0x62, 0xA6, 0x95, 0x26, 0xD4, 0x31, 0x61, 0xC1, \
+     0xA4, 0x1D, 0x57, 0x0D, 0x79, 0x38, 0xDA, 0xD4, \
+     0xA4, 0x0E, 0x32, 0x9C, 0xD0, 0xE4, 0x0E, 0x65, \
+     0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF }
+
+#define MBEDTLS_DHM_RFC7919_FFDHE6144_G_BIN { 0x02 }
+
+#define MBEDTLS_DHM_RFC7919_FFDHE8192_P_BIN {        \
+     0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, \
+     0xAD, 0xF8, 0x54, 0x58, 0xA2, 0xBB, 0x4A, 0x9A, \
+     0xAF, 0xDC, 0x56, 0x20, 0x27, 0x3D, 0x3C, 0xF1, \
+     0xD8, 0xB9, 0xC5, 0x83, 0xCE, 0x2D, 0x36, 0x95, \
+     0xA9, 0xE1, 0x36, 0x41, 0x14, 0x64, 0x33, 0xFB, \
+     0xCC, 0x93, 0x9D, 0xCE, 0x24, 0x9B, 0x3E, 0xF9, \
+     0x7D, 0x2F, 0xE3, 0x63, 0x63, 0x0C, 0x75, 0xD8, \
+     0xF6, 0x81, 0xB2, 0x02, 0xAE, 0xC4, 0x61, 0x7A, \
+     0xD3, 0xDF, 0x1E, 0xD5, 0xD5, 0xFD, 0x65, 0x61, \
+     0x24, 0x33, 0xF5, 0x1F, 0x5F, 0x06, 0x6E, 0xD0, \
+     0x85, 0x63, 0x65, 0x55, 0x3D, 0xED, 0x1A, 0xF3, \
+     0xB5, 0x57, 0x13, 0x5E, 0x7F, 0x57, 0xC9, 0x35, \
+     0x98, 0x4F, 0x0C, 0x70, 0xE0, 0xE6, 0x8B, 0x77, \
+     0xE2, 0xA6, 0x89, 0xDA, 0xF3, 0xEF, 0xE8, 0x72, \
+     0x1D, 0xF1, 0x58, 0xA1, 0x36, 0xAD, 0xE7, 0x35, \
+     0x30, 0xAC, 0xCA, 0x4F, 0x48, 0x3A, 0x79, 0x7A, \
+     0xBC, 0x0A, 0xB1, 0x82, 0xB3, 0x24, 0xFB, 0x61, \
+     0xD1, 0x08, 0xA9, 0x4B, 0xB2, 0xC8, 0xE3, 0xFB, \
+     0xB9, 0x6A, 0xDA, 0xB7, 0x60, 0xD7, 0xF4, 0x68, \
+     0x1D, 0x4F, 0x42, 0xA3, 0xDE, 0x39, 0x4D, 0xF4, \
+     0xAE, 0x56, 0xED, 0xE7, 0x63, 0x72, 0xBB, 0x19, \
+     0x0B, 0x07, 0xA7, 0xC8, 0xEE, 0x0A, 0x6D, 0x70, \
+     0x9E, 0x02, 0xFC, 0xE1, 0xCD, 0xF7, 0xE2, 0xEC, \
+     0xC0, 0x34, 0x04, 0xCD, 0x28, 0x34, 0x2F, 0x61, \
+     0x91, 0x72, 0xFE, 0x9C, 0xE9, 0x85, 0x83, 0xFF, \
+     0x8E, 0x4F, 0x12, 0x32, 0xEE, 0xF2, 0x81, 0x83, \
+     0xC3, 0xFE, 0x3B, 0x1B, 0x4C, 0x6F, 0xAD, 0x73, \
+     0x3B, 0xB5, 0xFC, 0xBC, 0x2E, 0xC2, 0x20, 0x05, \
+     0xC5, 0x8E, 0xF1, 0x83, 0x7D, 0x16, 0x83, 0xB2, \
+     0xC6, 0xF3, 0x4A, 0x26, 0xC1, 0xB2, 0xEF, 0xFA, \
+     0x88, 0x6B, 0x42, 0x38, 0x61, 0x1F, 0xCF, 0xDC, \
+     0xDE, 0x35, 0x5B, 0x3B, 0x65, 0x19, 0x03, 0x5B, \
+     0xBC, 0x34, 0xF4, 0xDE, 0xF9, 0x9C, 0x02, 0x38, \
+     0x61, 0xB4, 0x6F, 0xC9, 0xD6, 0xE6, 0xC9, 0x07, \
+     0x7A, 0xD9, 0x1D, 0x26, 0x91, 0xF7, 0xF7, 0xEE, \
+     0x59, 0x8C, 0xB0, 0xFA, 0xC1, 0x86, 0xD9, 0x1C, \
+     0xAE, 0xFE, 0x13, 0x09, 0x85, 0x13, 0x92, 0x70, \
+     0xB4, 0x13, 0x0C, 0x93, 0xBC, 0x43, 0x79, 0x44, \
+     0xF4, 0xFD, 0x44, 0x52, 0xE2, 0xD7, 0x4D, 0xD3, \
+     0x64, 0xF2, 0xE2, 0x1E, 0x71, 0xF5, 0x4B, 0xFF, \
+     0x5C, 0xAE, 0x82, 0xAB, 0x9C, 0x9D, 0xF6, 0x9E, \
+     0xE8, 0x6D, 0x2B, 0xC5, 0x22, 0x36, 0x3A, 0x0D, \
+     0xAB, 0xC5, 0x21, 0x97, 0x9B, 0x0D, 0xEA, 0xDA, \
+     0x1D, 0xBF, 0x9A, 0x42, 0xD5, 0xC4, 0x48, 0x4E, \
+     0x0A, 0xBC, 0xD0, 0x6B, 0xFA, 0x53, 0xDD, 0xEF, \
+     0x3C, 0x1B, 0x20, 0xEE, 0x3F, 0xD5, 0x9D, 0x7C, \
+     0x25, 0xE4, 0x1D, 0x2B, 0x66, 0x9E, 0x1E, 0xF1, \
+     0x6E, 0x6F, 0x52, 0xC3, 0x16, 0x4D, 0xF4, 0xFB, \
+     0x79, 0x30, 0xE9, 0xE4, 0xE5, 0x88, 0x57, 0xB6, \
+     0xAC, 0x7D, 0x5F, 0x42, 0xD6, 0x9F, 0x6D, 0x18, \
+     0x77, 0x63, 0xCF, 0x1D, 0x55, 0x03, 0x40, 0x04, \
+     0x87, 0xF5, 0x5B, 0xA5, 0x7E, 0x31, 0xCC, 0x7A, \
+     0x71, 0x35, 0xC8, 0x86, 0xEF, 0xB4, 0x31, 0x8A, \
+     0xED, 0x6A, 0x1E, 0x01, 0x2D, 0x9E, 0x68, 0x32, \
+     0xA9, 0x07, 0x60, 0x0A, 0x91, 0x81, 0x30, 0xC4, \
+     0x6D, 0xC7, 0x78, 0xF9, 0x71, 0xAD, 0x00, 0x38, \
+     0x09, 0x29, 0x99, 0xA3, 0x33, 0xCB, 0x8B, 0x7A, \
+     0x1A, 0x1D, 0xB9, 0x3D, 0x71, 0x40, 0x00, 0x3C, \
+     0x2A, 0x4E, 0xCE, 0xA9, 0xF9, 0x8D, 0x0A, 0xCC, \
+     0x0A, 0x82, 0x91, 0xCD, 0xCE, 0xC9, 0x7D, 0xCF, \
+     0x8E, 0xC9, 0xB5, 0x5A, 0x7F, 0x88, 0xA4, 0x6B, \
+     0x4D, 0xB5, 0xA8, 0x51, 0xF4, 0x41, 0x82, 0xE1, \
+     0xC6, 0x8A, 0x00, 0x7E, 0x5E, 0x0D, 0xD9, 0x02, \
+     0x0B, 0xFD, 0x64, 0xB6, 0x45, 0x03, 0x6C, 0x7A, \
+     0x4E, 0x67, 0x7D, 0x2C, 0x38, 0x53, 0x2A, 0x3A, \
+     0x23, 0xBA, 0x44, 0x42, 0xCA, 0xF5, 0x3E, 0xA6, \
+     0x3B, 0xB4, 0x54, 0x32, 0x9B, 0x76, 0x24, 0xC8, \
+     0x91, 0x7B, 0xDD, 0x64, 0xB1, 0xC0, 0xFD, 0x4C, \
+     0xB3, 0x8E, 0x8C, 0x33, 0x4C, 0x70, 0x1C, 0x3A, \
+     0xCD, 0xAD, 0x06, 0x57, 0xFC, 0xCF, 0xEC, 0x71, \
+     0x9B, 0x1F, 0x5C, 0x3E, 0x4E, 0x46, 0x04, 0x1F, \
+     0x38, 0x81, 0x47, 0xFB, 0x4C, 0xFD, 0xB4, 0x77, \
+     0xA5, 0x24, 0x71, 0xF7, 0xA9, 0xA9, 0x69, 0x10, \
+     0xB8, 0x55, 0x32, 0x2E, 0xDB, 0x63, 0x40, 0xD8, \
+     0xA0, 0x0E, 0xF0, 0x92, 0x35, 0x05, 0x11, 0xE3, \
+     0x0A, 0xBE, 0xC1, 0xFF, 0xF9, 0xE3, 0xA2, 0x6E, \
+     0x7F, 0xB2, 0x9F, 0x8C, 0x18, 0x30, 0x23, 0xC3, \
+     0x58, 0x7E, 0x38, 0xDA, 0x00, 0x77, 0xD9, 0xB4, \
+     0x76, 0x3E, 0x4E, 0x4B, 0x94, 0xB2, 0xBB, 0xC1, \
+     0x94, 0xC6, 0x65, 0x1E, 0x77, 0xCA, 0xF9, 0x92, \
+     0xEE, 0xAA, 0xC0, 0x23, 0x2A, 0x28, 0x1B, 0xF6, \
+     0xB3, 0xA7, 0x39, 0xC1, 0x22, 0x61, 0x16, 0x82, \
+     0x0A, 0xE8, 0xDB, 0x58, 0x47, 0xA6, 0x7C, 0xBE, \
+     0xF9, 0xC9, 0x09, 0x1B, 0x46, 0x2D, 0x53, 0x8C, \
+     0xD7, 0x2B, 0x03, 0x74, 0x6A, 0xE7, 0x7F, 0x5E, \
+     0x62, 0x29, 0x2C, 0x31, 0x15, 0x62, 0xA8, 0x46, \
+     0x50, 0x5D, 0xC8, 0x2D, 0xB8, 0x54, 0x33, 0x8A, \
+     0xE4, 0x9F, 0x52, 0x35, 0xC9, 0x5B, 0x91, 0x17, \
+     0x8C, 0xCF, 0x2D, 0xD5, 0xCA, 0xCE, 0xF4, 0x03, \
+     0xEC, 0x9D, 0x18, 0x10, 0xC6, 0x27, 0x2B, 0x04, \
+     0x5B, 0x3B, 0x71, 0xF9, 0xDC, 0x6B, 0x80, 0xD6, \
+     0x3F, 0xDD, 0x4A, 0x8E, 0x9A, 0xDB, 0x1E, 0x69, \
+     0x62, 0xA6, 0x95, 0x26, 0xD4, 0x31, 0x61, 0xC1, \
+     0xA4, 0x1D, 0x57, 0x0D, 0x79, 0x38, 0xDA, 0xD4, \
+     0xA4, 0x0E, 0x32, 0x9C, 0xCF, 0xF4, 0x6A, 0xAA, \
+     0x36, 0xAD, 0x00, 0x4C, 0xF6, 0x00, 0xC8, 0x38, \
+     0x1E, 0x42, 0x5A, 0x31, 0xD9, 0x51, 0xAE, 0x64, \
+     0xFD, 0xB2, 0x3F, 0xCE, 0xC9, 0x50, 0x9D, 0x43, \
+     0x68, 0x7F, 0xEB, 0x69, 0xED, 0xD1, 0xCC, 0x5E, \
+     0x0B, 0x8C, 0xC3, 0xBD, 0xF6, 0x4B, 0x10, 0xEF, \
+     0x86, 0xB6, 0x31, 0x42, 0xA3, 0xAB, 0x88, 0x29, \
+     0x55, 0x5B, 0x2F, 0x74, 0x7C, 0x93, 0x26, 0x65, \
+     0xCB, 0x2C, 0x0F, 0x1C, 0xC0, 0x1B, 0xD7, 0x02, \
+     0x29, 0x38, 0x88, 0x39, 0xD2, 0xAF, 0x05, 0xE4, \
+     0x54, 0x50, 0x4A, 0xC7, 0x8B, 0x75, 0x82, 0x82, \
+     0x28, 0x46, 0xC0, 0xBA, 0x35, 0xC3, 0x5F, 0x5C, \
+     0x59, 0x16, 0x0C, 0xC0, 0x46, 0xFD, 0x82, 0x51, \
+     0x54, 0x1F, 0xC6, 0x8C, 0x9C, 0x86, 0xB0, 0x22, \
+     0xBB, 0x70, 0x99, 0x87, 0x6A, 0x46, 0x0E, 0x74, \
+     0x51, 0xA8, 0xA9, 0x31, 0x09, 0x70, 0x3F, 0xEE, \
+     0x1C, 0x21, 0x7E, 0x6C, 0x38, 0x26, 0xE5, 0x2C, \
+     0x51, 0xAA, 0x69, 0x1E, 0x0E, 0x42, 0x3C, 0xFC, \
+     0x99, 0xE9, 0xE3, 0x16, 0x50, 0xC1, 0x21, 0x7B, \
+     0x62, 0x48, 0x16, 0xCD, 0xAD, 0x9A, 0x95, 0xF9, \
+     0xD5, 0xB8, 0x01, 0x94, 0x88, 0xD9, 0xC0, 0xA0, \
+     0xA1, 0xFE, 0x30, 0x75, 0xA5, 0x77, 0xE2, 0x31, \
+     0x83, 0xF8, 0x1D, 0x4A, 0x3F, 0x2F, 0xA4, 0x57, \
+     0x1E, 0xFC, 0x8C, 0xE0, 0xBA, 0x8A, 0x4F, 0xE8, \
+     0xB6, 0x85, 0x5D, 0xFE, 0x72, 0xB0, 0xA6, 0x6E, \
+     0xDE, 0xD2, 0xFB, 0xAB, 0xFB, 0xE5, 0x8A, 0x30, \
+     0xFA, 0xFA, 0xBE, 0x1C, 0x5D, 0x71, 0xA8, 0x7E, \
+     0x2F, 0x74, 0x1E, 0xF8, 0xC1, 0xFE, 0x86, 0xFE, \
+     0xA6, 0xBB, 0xFD, 0xE5, 0x30, 0x67, 0x7F, 0x0D, \
+     0x97, 0xD1, 0x1D, 0x49, 0xF7, 0xA8, 0x44, 0x3D, \
+     0x08, 0x22, 0xE5, 0x06, 0xA9, 0xF4, 0x61, 0x4E, \
+     0x01, 0x1E, 0x2A, 0x94, 0x83, 0x8F, 0xF8, 0x8C, \
+     0xD6, 0x8C, 0x8B, 0xB7, 0xC5, 0xC6, 0x42, 0x4C, \
+     0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF }
+
+#define MBEDTLS_DHM_RFC7919_FFDHE8192_G_BIN { 0x02 }
+
 #endif /* dhm.h */
diff --git a/include/mbedtls/ecdh.h b/include/mbedtls/ecdh.h
index 625a281..99cfde0 100644
--- a/include/mbedtls/ecdh.h
+++ b/include/mbedtls/ecdh.h
@@ -1,9 +1,18 @@
 /**
  * \file ecdh.h
  *
- * \brief Elliptic curve Diffie-Hellman
+ * \brief The Elliptic Curve Diffie-Hellman (ECDH) protocol APIs.
  *
- *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ * ECDH is an anonymous key agreement protocol allowing two parties to
+ * establish a shared secret over an insecure channel. Each party must have an
+ * elliptic-curve public–private key pair.
+ *
+ * For more information, see <em>NIST SP 800-56A Rev. 2: Recommendation for
+ * Pair-Wise Key Establishment Schemes Using Discrete Logarithm
+ * Cryptography</em>.
+ */
+/*
+ *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
@@ -18,8 +27,9 @@
  *  See the License for the specific language governing permissions and
  *  limitations under the License.
  *
- *  This file is part of mbed TLS (https://tls.mbed.org)
+ *  This file is part of Mbed TLS (https://tls.mbed.org)
  */
+
 #ifndef MBEDTLS_ECDH_H
 #define MBEDTLS_ECDH_H
 
@@ -30,7 +40,9 @@
 #endif
 
 /**
- * When importing from an EC key, select if it is our key or the peer's key
+ * Defines the source of the imported EC key:
+ * <ul><li>Our key.</li>
+ * <li>The key of the peer.</li></ul>
  */
 typedef enum
 {
@@ -39,56 +51,67 @@
 } mbedtls_ecdh_side;
 
 /**
- * \brief           ECDH context structure
+ * \brief           The ECDH context structure.
  */
 typedef struct
 {
-    mbedtls_ecp_group grp;      /*!<  elliptic curve used                           */
-    mbedtls_mpi d;              /*!<  our secret value (private key)                */
-    mbedtls_ecp_point Q;        /*!<  our public value (public key)                 */
-    mbedtls_ecp_point Qp;       /*!<  peer's public value (public key)              */
-    mbedtls_mpi z;              /*!<  shared secret                                 */
-    int point_format;   /*!<  format for point export in TLS messages       */
-    mbedtls_ecp_point Vi;       /*!<  blinding value (for later)                    */
-    mbedtls_ecp_point Vf;       /*!<  un-blinding value (for later)                 */
-    mbedtls_mpi _d;             /*!<  previous d (for later)                        */
+    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. */
+    int point_format;        /*!< The format of point export in TLS messages. */
+    mbedtls_ecp_point Vi;    /*!< The blinding value. */
+    mbedtls_ecp_point Vf;    /*!< The unblinding value. */
+    mbedtls_mpi _d;          /*!< The previous \p d. */
 }
 mbedtls_ecdh_context;
 
 /**
- * \brief           Generate a public key.
- *                  Raw function that only does the core computation.
+ * \brief           This function generates an ECDH keypair on an elliptic
+ *                  curve.
  *
- * \param grp       ECP group
- * \param d         Destination MPI (secret exponent, aka private key)
- * \param Q         Destination point (public key)
- * \param f_rng     RNG function
- * \param p_rng     RNG parameter
+ *                  This function performs the first of two core computations
+ *                  implemented during the ECDH key exchange. The second core
+ *                  computation is performed by mbedtls_ecdh_compute_shared().
  *
- * \return          0 if successful,
- *                  or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
+ * \param grp       The ECP group.
+ * \param d         The destination MPI (private key).
+ * \param Q         The destination point (public key).
+ * \param f_rng     The RNG function.
+ * \param p_rng     The RNG parameter.
+ *
+ * \return          \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX or
+ *                  \c MBEDTLS_MPI_XXX error code on failure.
+ *
+ * \see             ecp.h
  */
 int mbedtls_ecdh_gen_public( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q,
                      int (*f_rng)(void *, unsigned char *, size_t),
                      void *p_rng );
 
 /**
- * \brief           Compute shared secret
- *                  Raw function that only does the core computation.
+ * \brief           This function computes the shared secret.
  *
- * \param grp       ECP group
- * \param z         Destination MPI (shared secret)
- * \param Q         Public key from other party
- * \param d         Our secret exponent (private key)
- * \param f_rng     RNG function (see notes)
- * \param p_rng     RNG parameter
+ *                  This function performs the second of two core computations
+ *                  implemented during the ECDH key exchange. The first core
+ *                  computation is performed by mbedtls_ecdh_gen_public().
  *
- * \return          0 if successful,
- *                  or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
+ * \param grp       The ECP group.
+ * \param z         The destination MPI (shared secret).
+ * \param Q         The public key from another party.
+ * \param d         Our secret exponent (private key).
+ * \param f_rng     The RNG function.
+ * \param p_rng     The RNG parameter.
  *
- * \note            If f_rng is not NULL, it is used to implement
+ * \return          \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX or
+ *                  \c MBEDTLS_MPI_XXX error code on failure.
+ *
+ * \see             ecp.h
+ *
+ * \note            If \p f_rng is not NULL, it is used to implement
  *                  countermeasures against potential elaborate timing
- *                  attacks, see \c mbedtls_ecp_mul() for details.
+ *                  attacks. For more information, see mbedtls_ecp_mul().
  */
 int mbedtls_ecdh_compute_shared( mbedtls_ecp_group *grp, mbedtls_mpi *z,
                          const mbedtls_ecp_point *Q, const mbedtls_mpi *d,
@@ -96,34 +119,41 @@
                          void *p_rng );
 
 /**
- * \brief           Initialize context
+ * \brief           This function initializes an ECDH context.
  *
- * \param ctx       Context to initialize
+ * \param ctx       The ECDH context to initialize.
  */
 void mbedtls_ecdh_init( mbedtls_ecdh_context *ctx );
 
 /**
- * \brief           Free context
+ * \brief           This function frees a context.
  *
- * \param ctx       Context to free
+ * \param ctx       The context to free.
  */
 void mbedtls_ecdh_free( mbedtls_ecdh_context *ctx );
 
 /**
- * \brief           Generate a public key and a TLS ServerKeyExchange payload.
- *                  (First function used by a TLS server for ECDHE.)
+ * \brief           This function generates a public key and a TLS
+ *                  ServerKeyExchange payload.
  *
- * \param ctx       ECDH context
- * \param olen      number of chars written
- * \param buf       destination buffer
- * \param blen      length of buffer
- * \param f_rng     RNG function
- * \param p_rng     RNG parameter
+ *                  This is the first function used by a TLS server for ECDHE
+ *                  ciphersuites.
  *
- * \note            This function assumes that ctx->grp has already been
- *                  properly set (for example using mbedtls_ecp_group_load).
+ * \param ctx       The ECDH context.
+ * \param olen      The number of characters written.
+ * \param buf       The destination buffer.
+ * \param blen      The length of the destination buffer.
+ * \param f_rng     The RNG function.
+ * \param p_rng     The RNG parameter.
  *
- * \return          0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
+ * \note            This function assumes that the ECP group (grp) of the
+ *                  \p ctx context has already been properly set,
+ *                  for example, using mbedtls_ecp_group_load().
+ *
+ * \return          \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
+ *                  on failure.
+ *
+ * \see             ecp.h
  */
 int mbedtls_ecdh_make_params( mbedtls_ecdh_context *ctx, size_t *olen,
                       unsigned char *buf, size_t blen,
@@ -131,45 +161,63 @@
                       void *p_rng );
 
 /**
- * \brief           Parse and procress a TLS ServerKeyExhange payload.
- *                  (First function used by a TLS client for ECDHE.)
+ * \brief           This function parses and processes a TLS ServerKeyExhange
+ *                  payload.
  *
- * \param ctx       ECDH context
- * \param buf       pointer to start of input buffer
- * \param end       one past end of buffer
+ *                  This is the first function used by a TLS client for ECDHE
+ *                  ciphersuites.
  *
- * \return          0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
+ * \param ctx       The ECDH context.
+ * \param buf       The pointer to the start of the input buffer.
+ * \param end       The address for one Byte past the end of the buffer.
+ *
+ * \return          \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
+ *                  on failure.
+ *
+ * \see             ecp.h
  */
 int mbedtls_ecdh_read_params( mbedtls_ecdh_context *ctx,
                       const unsigned char **buf, const unsigned char *end );
 
 /**
- * \brief           Setup an ECDH context from an EC key.
- *                  (Used by clients and servers in place of the
- *                  ServerKeyEchange for static ECDH: import ECDH parameters
- *                  from a certificate's EC key information.)
+ * \brief           This function sets up an ECDH context from an EC key.
  *
- * \param ctx       ECDH constext to set
- * \param key       EC key to use
- * \param side      Is it our key (1) or the peer's key (0) ?
+ *                  It is used by clients and servers in place of the
+ *                  ServerKeyEchange for static ECDH, and imports ECDH
+ *                  parameters from the EC key information of a certificate.
  *
- * \return          0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
+ * \param ctx       The ECDH context to set up.
+ * \param key       The EC key to use.
+ * \param side      Defines the source of the key:
+ *                  <ul><li>1: Our key.</li>
+                    <li>0: The key of the peer.</li></ul>
+ *
+ * \return          \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
+ *                  on failure.
+ *
+ * \see             ecp.h
  */
 int mbedtls_ecdh_get_params( mbedtls_ecdh_context *ctx, const mbedtls_ecp_keypair *key,
                      mbedtls_ecdh_side side );
 
 /**
- * \brief           Generate a public key and a TLS ClientKeyExchange payload.
- *                  (Second function used by a TLS client for ECDH(E).)
+ * \brief           This function generates a public key and a TLS
+ *                  ClientKeyExchange payload.
  *
- * \param ctx       ECDH context
- * \param olen      number of bytes actually written
- * \param buf       destination buffer
- * \param blen      size of destination buffer
- * \param f_rng     RNG function
- * \param p_rng     RNG parameter
+ *                  This is the second function used by a TLS client for ECDH(E)
+ *                  ciphersuites.
  *
- * \return          0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
+ * \param ctx       The ECDH context.
+ * \param olen      The number of Bytes written.
+ * \param buf       The destination buffer.
+ * \param blen      The size of the destination buffer.
+ * \param f_rng     The RNG function.
+ * \param p_rng     The RNG parameter.
+ *
+ * \return          \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
+ *                  on failure.
+ *
+ * \see             ecp.h
  */
 int mbedtls_ecdh_make_public( mbedtls_ecdh_context *ctx, size_t *olen,
                       unsigned char *buf, size_t blen,
@@ -177,30 +225,45 @@
                       void *p_rng );
 
 /**
- * \brief           Parse and process a TLS ClientKeyExchange payload.
- *                  (Second function used by a TLS server for ECDH(E).)
+ * \brief       This function parses and processes a TLS ClientKeyExchange
+ *              payload.
  *
- * \param ctx       ECDH context
- * \param buf       start of input buffer
- * \param blen      length of input buffer
+ *              This is the second function used by a TLS server for ECDH(E)
+ *              ciphersuites.
  *
- * \return          0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
+ * \param ctx   The ECDH context.
+ * \param buf   The start of the input buffer.
+ * \param blen  The length of the input buffer.
+ *
+ * \return      \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
+ *              on failure.
+ *
+ * \see         ecp.h
  */
 int mbedtls_ecdh_read_public( mbedtls_ecdh_context *ctx,
                       const unsigned char *buf, size_t blen );
 
 /**
- * \brief           Derive and export the shared secret.
- *                  (Last function used by both TLS client en servers.)
+ * \brief           This function derives and exports the shared secret.
  *
- * \param ctx       ECDH context
- * \param olen      number of bytes written
- * \param buf       destination buffer
- * \param blen      buffer length
- * \param f_rng     RNG function, see notes for \c mbedtls_ecdh_compute_shared()
- * \param p_rng     RNG parameter
+ *                  This is the last function used by both TLS client
+ *                  and servers.
  *
- * \return          0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
+ * \param ctx       The ECDH context.
+ * \param olen      The number of Bytes written.
+ * \param buf       The destination buffer.
+ * \param blen      The length of the destination buffer.
+ * \param f_rng     The RNG function.
+ * \param p_rng     The RNG parameter.
+ *
+ * \return          \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
+ *                  on failure.
+ *
+ * \see             ecp.h
+ *
+ * \note            If \p f_rng is not NULL, it is used to implement
+ *                  countermeasures against potential elaborate timing
+ *                  attacks. For more information, see mbedtls_ecp_mul().
  */
 int mbedtls_ecdh_calc_secret( mbedtls_ecdh_context *ctx, size_t *olen,
                       unsigned char *buf, size_t blen,
diff --git a/include/mbedtls/ecdsa.h b/include/mbedtls/ecdsa.h
index a277715..aa23d67 100644
--- a/include/mbedtls/ecdsa.h
+++ b/include/mbedtls/ecdsa.h
@@ -1,9 +1,16 @@
 /**
  * \file ecdsa.h
  *
- * \brief Elliptic curve DSA
+ * \brief The Elliptic Curve Digital Signature Algorithm (ECDSA).
  *
- *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ * ECDSA is defined in <em>Standards for Efficient Cryptography Group (SECG):
+ * SEC1 Elliptic Curve Cryptography</em>.
+ * The use of ECDSA for TLS is defined in <em>RFC-4492: Elliptic Curve
+ * Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS)</em>.
+ *
+ */
+/*
+ *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
@@ -18,8 +25,9 @@
  *  See the License for the specific language governing permissions and
  *  limitations under the License.
  *
- *  This file is part of mbed TLS (https://tls.mbed.org)
+ *  This file is part of Mbed TLS (https://tls.mbed.org)
  */
+
 #ifndef MBEDTLS_ECDSA_H
 #define MBEDTLS_ECDSA_H
 
@@ -27,7 +35,7 @@
 #include "md.h"
 
 /*
- * RFC 4492 page 20:
+ * RFC-4492 page 20:
  *
  *     Ecdsa-Sig-Value ::= SEQUENCE {
  *         r       INTEGER,
@@ -43,11 +51,11 @@
 #if MBEDTLS_ECP_MAX_BYTES > 124
 #error "MBEDTLS_ECP_MAX_BYTES bigger than expected, please fix MBEDTLS_ECDSA_MAX_LEN"
 #endif
-/** Maximum size of an ECDSA signature in bytes */
+/** The maximal size of an ECDSA signature in Bytes. */
 #define MBEDTLS_ECDSA_MAX_LEN  ( 3 + 2 * ( 3 + MBEDTLS_ECP_MAX_BYTES ) )
 
 /**
- * \brief           ECDSA context structure
+ * \brief           The ECDSA context structure.
  */
 typedef mbedtls_ecp_keypair mbedtls_ecdsa_context;
 
@@ -56,25 +64,30 @@
 #endif
 
 /**
- * \brief           Compute ECDSA signature of a previously hashed message
+ * \brief           This function computes the ECDSA signature of a
+ *                  previously-hashed message.
  *
- * \note            The deterministic version is usually prefered.
+ * \note            The deterministic version is usually preferred.
  *
- * \param grp       ECP group
- * \param r         First output integer
- * \param s         Second output integer
- * \param d         Private signing key
- * \param buf       Message hash
- * \param blen      Length of buf
- * \param f_rng     RNG function
- * \param p_rng     RNG parameter
+ * \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 parameter.
  *
  * \note            If the bitlength of the message hash is larger than the
- *                  bitlength of the group order, then the hash is truncated as
- *                  prescribed by SEC1 4.1.3 step 5.
+ *                  bitlength of the group order, then the hash is truncated
+ *                  as defined in <em>Standards for Efficient Cryptography Group
+ *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
+ *                  4.1.3, step 5.
  *
- * \return          0 if successful,
- *                  or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
+ * \return          \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX
+ *                  or \c MBEDTLS_MPI_XXX error code on failure.
+ *
+ * \see             ecp.h
  */
 int mbedtls_ecdsa_sign( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
                 const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
@@ -82,23 +95,31 @@
 
 #if defined(MBEDTLS_ECDSA_DETERMINISTIC)
 /**
- * \brief           Compute ECDSA signature of a previously hashed message,
- *                  deterministic version (RFC 6979).
+ * \brief           This function computes the ECDSA signature of a
+ *                  previously-hashed message, deterministic version.
+ *                  For more information, see <em>RFC-6979: Deterministic
+ *                  Usage of the Digital Signature Algorithm (DSA) and Elliptic
+ *                  Curve Digital Signature Algorithm (ECDSA)</em>.
  *
- * \param grp       ECP group
- * \param r         First output integer
- * \param s         Second output integer
- * \param d         Private signing key
- * \param buf       Message hash
- * \param blen      Length of buf
- * \param md_alg    MD algorithm used to hash the message
+ * \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.
  *
  * \note            If the bitlength of the message hash is larger than the
  *                  bitlength of the group order, then the hash is truncated as
- *                  prescribed by SEC1 4.1.3 step 5.
+ *                  defined in <em>Standards for Efficient Cryptography Group
+ *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
+ *                  4.1.3, step 5.
  *
- * \return          0 if successful,
- *                  or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
+ * \return          \c 0 on success,
+ *                  or an \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
+ *                  error code on failure.
+ *
+ * \see             ecp.h
  */
 int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
                     const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
@@ -106,55 +127,73 @@
 #endif /* MBEDTLS_ECDSA_DETERMINISTIC */
 
 /**
- * \brief           Verify ECDSA signature of a previously hashed message
+ * \brief           This function verifies the ECDSA signature of a
+ *                  previously-hashed message.
  *
- * \param grp       ECP group
- * \param buf       Message hash
- * \param blen      Length of buf
- * \param Q         Public key to use for verification
- * \param r         First integer of the signature
- * \param s         Second integer of the signature
+ * \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 r         The first integer of the signature.
+ * \param s         The second integer of the signature.
  *
  * \note            If the bitlength of the message hash is larger than the
  *                  bitlength of the group order, then the hash is truncated as
- *                  prescribed by SEC1 4.1.4 step 3.
+ *                  defined in <em>Standards for Efficient Cryptography Group
+ *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
+ *                  4.1.4, step 3.
  *
- * \return          0 if successful,
- *                  MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid
- *                  or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
+ * \return          \c 0 on success,
+ *                  #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid,
+ *                  or an \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
+ *                  error code on failure for any other reason.
+ *
+ * \see             ecp.h
  */
 int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp,
                   const unsigned char *buf, size_t blen,
                   const mbedtls_ecp_point *Q, const mbedtls_mpi *r, const mbedtls_mpi *s);
 
 /**
- * \brief           Compute ECDSA signature and write it to buffer,
- *                  serialized as defined in RFC 4492 page 20.
- *                  (Not thread-safe to use same context in multiple threads)
+ * \brief           This function computes the ECDSA signature and writes it
+ *                  to a buffer, serialized as defined in <em>RFC-4492:
+ *                  Elliptic Curve Cryptography (ECC) Cipher Suites for
+ *                  Transport Layer Security (TLS)</em>.
  *
- * \note            The deterministic version (RFC 6979) is used if
- *                  MBEDTLS_ECDSA_DETERMINISTIC is defined.
+ * \warning         It is not thread-safe to use the same context in
+ *                  multiple threads.
  *
- * \param ctx       ECDSA context
- * \param md_alg    Algorithm that was used to hash the message
- * \param hash      Message hash
- * \param hlen      Length of hash
- * \param sig       Buffer that will hold the signature
- * \param slen      Length of the signature written
- * \param f_rng     RNG function
- * \param p_rng     RNG parameter
+ * \note            The deterministic version is used if
+ *                  #MBEDTLS_ECDSA_DETERMINISTIC is defined. For more
+ *                  information, see <em>RFC-6979: Deterministic Usage
+ *                  of the Digital Signature Algorithm (DSA) and Elliptic
+ *                  Curve Digital Signature Algorithm (ECDSA)</em>.
  *
- * \note            The "sig" buffer must be at least as large as twice the
- *                  size of the curve used, plus 9 (eg. 73 bytes if a 256-bit
- *                  curve is used). MBEDTLS_ECDSA_MAX_LEN is always safe.
+ * \param ctx       The ECDSA context.
+ * \param md_alg    The message digest that was used to hash the message.
+ * \param hash      The message hash.
+ * \param hlen      The length of the hash.
+ * \param sig       The buffer that holds the signature.
+ * \param slen      The length of the signature written.
+ * \param f_rng     The RNG function.
+ * \param p_rng     The RNG parameter.
+ *
+ * \note            The \p sig buffer must be at least twice as large as the
+ *                  size of the curve used, plus 9. For example, 73 Bytes if
+ *                  a 256-bit curve is used. A buffer length of
+ *                  #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
- *                  prescribed by SEC1 4.1.3 step 5.
+ *                  defined in <em>Standards for Efficient Cryptography Group
+ *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
+ *                  4.1.3, step 5.
  *
- * \return          0 if successful,
- *                  or a MBEDTLS_ERR_ECP_XXX, MBEDTLS_ERR_MPI_XXX or
- *                  MBEDTLS_ERR_ASN1_XXX error code
+ * \return          \c 0 on success,
+ *                  or an \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
+ *                  \c MBEDTLS_ERR_ASN1_XXX error code on failure.
+ *
+ * \see             ecp.h
  */
 int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t md_alg,
                            const unsigned char *hash, size_t hlen,
@@ -170,31 +209,43 @@
 #define MBEDTLS_DEPRECATED
 #endif
 /**
- * \brief           Compute ECDSA signature and write it to buffer,
- *                  serialized as defined in RFC 4492 page 20.
- *                  Deterministic version, RFC 6979.
- *                  (Not thread-safe to use same context in multiple threads)
+ * \brief   This function computes an ECDSA signature and writes it to a buffer,
+ *          serialized as defined in <em>RFC-4492: Elliptic Curve Cryptography
+ *          (ECC) Cipher Suites for Transport Layer Security (TLS)</em>.
+ *
+ *          The deterministic version is defined in <em>RFC-6979:
+ *          Deterministic Usage of the Digital Signature Algorithm (DSA) and
+ *          Elliptic Curve Digital Signature Algorithm (ECDSA)</em>.
+ *
+ * \warning         It is not thread-safe to use the same context in
+ *                  multiple threads.
+
  *
  * \deprecated      Superseded by mbedtls_ecdsa_write_signature() in 2.0.0
  *
- * \param ctx       ECDSA context
- * \param hash      Message hash
- * \param hlen      Length of hash
- * \param sig       Buffer that will hold the signature
- * \param slen      Length of the signature written
- * \param md_alg    MD algorithm used to hash the message
+ * \param ctx       The ECDSA context.
+ * \param hash      The Message hash.
+ * \param hlen      The length of the hash.
+ * \param sig       The buffer that holds the signature.
+ * \param slen      The length of the signature written.
+ * \param md_alg    The MD algorithm used to hash the message.
  *
- * \note            The "sig" buffer must be at least as large as twice the
- *                  size of the curve used, plus 9 (eg. 73 bytes if a 256-bit
- *                  curve is used). MBEDTLS_ECDSA_MAX_LEN is always safe.
+ * \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
- *                  prescribed by SEC1 4.1.3 step 5.
+ *                  defined in <em>Standards for Efficient Cryptography Group
+ *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
+ *                  4.1.3, step 5.
  *
- * \return          0 if successful,
- *                  or a MBEDTLS_ERR_ECP_XXX, MBEDTLS_ERR_MPI_XXX or
- *                  MBEDTLS_ERR_ASN1_XXX error code
+ * \return          \c 0 on success,
+ *                  or an \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
+ *                  \c MBEDTLS_ERR_ASN1_XXX error code on failure.
+ *
+ * \see             ecp.h
  */
 int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx,
                                const unsigned char *hash, size_t hlen,
@@ -205,63 +256,74 @@
 #endif /* MBEDTLS_ECDSA_DETERMINISTIC */
 
 /**
- * \brief           Read and verify an ECDSA signature
+ * \brief           This function reads and verifies an ECDSA signature.
  *
- * \param ctx       ECDSA context
- * \param hash      Message hash
- * \param hlen      Size of hash
- * \param sig       Signature to read and verify
- * \param slen      Size of sig
+ * \param ctx       The ECDSA context.
+ * \param hash      The message hash.
+ * \param hlen      The size of the hash.
+ * \param sig       The signature to read and verify.
+ * \param slen      The size of \p sig.
  *
  * \note            If the bitlength of the message hash is larger than the
  *                  bitlength of the group order, then the hash is truncated as
- *                  prescribed by SEC1 4.1.4 step 3.
+ *                  defined in <em>Standards for Efficient Cryptography Group
+ *                  (SECG): SEC1 Elliptic Curve Cryptography</em>, section
+ *                  4.1.4, step 3.
  *
- * \return          0 if successful,
- *                  MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid,
- *                  MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if the signature is
- *                  valid but its actual length is less than siglen,
- *                  or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_ERR_MPI_XXX error code
+ * \return          \c 0 on success,
+ *                  #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid,
+ *                  #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if the signature is
+ *                  valid but its actual length is less than \p siglen,
+ *                  or an \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX
+ *                  error code on failure for any other reason.
+ *
+ * \see             ecp.h
  */
 int mbedtls_ecdsa_read_signature( mbedtls_ecdsa_context *ctx,
                           const unsigned char *hash, size_t hlen,
                           const unsigned char *sig, size_t slen );
 
 /**
- * \brief           Generate an ECDSA keypair on the given curve
+ * \brief          This function generates an ECDSA keypair on the given curve.
  *
- * \param ctx       ECDSA context in which the keypair should be stored
- * \param gid       Group (elliptic curve) to use. One of the various
- *                  MBEDTLS_ECP_DP_XXX macros depending on configuration.
- * \param f_rng     RNG function
- * \param p_rng     RNG parameter
+ * \param ctx      The ECDSA context to store the keypair in.
+ * \param gid      The elliptic curve to use. One of the various
+ *                 \c MBEDTLS_ECP_DP_XXX macros depending on configuration.
+ * \param f_rng    The RNG function.
+ * \param p_rng    The RNG parameter.
  *
- * \return          0 on success, or a MBEDTLS_ERR_ECP_XXX code.
+ * \return         \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX code on
+ *                 failure.
+ *
+ * \see            ecp.h
  */
 int mbedtls_ecdsa_genkey( mbedtls_ecdsa_context *ctx, mbedtls_ecp_group_id gid,
                   int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
 
 /**
- * \brief           Set an ECDSA context from an EC key pair
+ * \brief           This function sets an ECDSA context from an EC key pair.
  *
- * \param ctx       ECDSA context to set
- * \param key       EC key to use
+ * \param ctx       The ECDSA context to set.
+ * \param key       The EC key to use.
  *
- * \return          0 on success, or a MBEDTLS_ERR_ECP_XXX code.
+ * \return          \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX code on
+ *                  failure.
+ *
+ * \see             ecp.h
  */
 int mbedtls_ecdsa_from_keypair( mbedtls_ecdsa_context *ctx, const mbedtls_ecp_keypair *key );
 
 /**
- * \brief           Initialize context
+ * \brief           This function initializes an ECDSA context.
  *
- * \param ctx       Context to initialize
+ * \param ctx       The ECDSA context to initialize.
  */
 void mbedtls_ecdsa_init( mbedtls_ecdsa_context *ctx );
 
 /**
- * \brief           Free context
+ * \brief           This function frees an ECDSA context.
  *
- * \param ctx       Context to free
+ * \param ctx       The ECDSA context to free.
  */
 void mbedtls_ecdsa_free( mbedtls_ecdsa_context *ctx );
 
diff --git a/include/mbedtls/ecjpake.h b/include/mbedtls/ecjpake.h
index 161a5b2..d86e820 100644
--- a/include/mbedtls/ecjpake.h
+++ b/include/mbedtls/ecjpake.h
@@ -2,7 +2,8 @@
  * \file ecjpake.h
  *
  * \brief Elliptic curve J-PAKE
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
@@ -43,6 +44,8 @@
 #include "ecp.h"
 #include "md.h"
 
+#if !defined(MBEDTLS_ECJPAKE_ALT)
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -222,17 +225,31 @@
  */
 void mbedtls_ecjpake_free( mbedtls_ecjpake_context *ctx );
 
+#ifdef __cplusplus
+}
+#endif
+
+#else  /* MBEDTLS_ECJPAKE_ALT */
+#include "ecjpake_alt.h"
+#endif /* MBEDTLS_ECJPAKE_ALT */
+
 #if defined(MBEDTLS_SELF_TEST)
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 /**
  * \brief          Checkup routine
  *
  * \return         0 if successful, or 1 if a test failed
  */
 int mbedtls_ecjpake_self_test( int verbose );
-#endif
 
 #ifdef __cplusplus
 }
 #endif
 
+#endif /* MBEDTLS_SELF_TEST */
+
 #endif /* ecjpake.h */
diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h
index dad9aef..b00ba4d 100644
--- a/include/mbedtls/ecp.h
+++ b/include/mbedtls/ecp.h
@@ -2,7 +2,8 @@
  * \file ecp.h
  *
  * \brief Elliptic curves over GF(p)
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
@@ -36,6 +37,7 @@
 #define MBEDTLS_ERR_ECP_RANDOM_FAILED                     -0x4D00  /**< Generation of random value, such as (ephemeral) key, failed. */
 #define MBEDTLS_ERR_ECP_INVALID_KEY                       -0x4C80  /**< Invalid private or public key. */
 #define MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH                  -0x4C00  /**< Signature is valid but shorter than the user-supplied length. */
+#define MBEDTLS_ERR_ECP_HW_ACCEL_FAILED                   -0x4B80  /**< ECP hardware accelerator failed. */
 
 #if !defined(MBEDTLS_ECP_ALT)
 /*
diff --git a/include/mbedtls/ecp_internal.h b/include/mbedtls/ecp_internal.h
index 2991e26..8a6d517 100644
--- a/include/mbedtls/ecp_internal.h
+++ b/include/mbedtls/ecp_internal.h
@@ -3,7 +3,8 @@
  *
  * \brief Function declarations for alternative implementation of elliptic curve
  * point arithmetic.
- *
+ */
+/*
  *  Copyright (C) 2016, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/entropy.h b/include/mbedtls/entropy.h
index 747aca4..fcb4d02 100644
--- a/include/mbedtls/entropy.h
+++ b/include/mbedtls/entropy.h
@@ -2,7 +2,8 @@
  * \file entropy.h
  *
  * \brief Entropy accumulator implementation
- *
+ */
+/*
  *  Copyright (C) 2006-2016, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
@@ -121,6 +122,7 @@
  */
 typedef struct
 {
+    int accumulator_started;
 #if defined(MBEDTLS_ENTROPY_SHA512_ACCUMULATOR)
     mbedtls_sha512_context  accumulator;
 #else
diff --git a/include/mbedtls/entropy_poll.h b/include/mbedtls/entropy_poll.h
index 81258d5..94dd657 100644
--- a/include/mbedtls/entropy_poll.h
+++ b/include/mbedtls/entropy_poll.h
@@ -2,7 +2,8 @@
  * \file entropy_poll.h
  *
  * \brief Platform-specific and custom entropy polling functions
- *
+ */
+/*
  *  Copyright (C) 2006-2016, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/error.h b/include/mbedtls/error.h
index 4eb7b78..8b4d3a8 100644
--- a/include/mbedtls/error.h
+++ b/include/mbedtls/error.h
@@ -2,7 +2,8 @@
  * \file error.h
  *
  * \brief Error to string translation
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
@@ -49,23 +50,32 @@
  *
  * Module   Nr  Codes assigned
  * MPI       7  0x0002-0x0010
- * GCM       2  0x0012-0x0014
- * BLOWFISH  2  0x0016-0x0018
+ * GCM       3  0x0012-0x0014   0x0013-0x0013
+ * BLOWFISH  3  0x0016-0x0018   0x0017-0x0017
  * THREADING 3  0x001A-0x001E
- * AES       2  0x0020-0x0022   0x0023-0x0023
- * CAMELLIA  2  0x0024-0x0026
- * XTEA      1  0x0028-0x0028
+ * AES       4  0x0020-0x0022   0x0023-0x0025
+ * CAMELLIA  3  0x0024-0x0026   0x0027-0x0027
+ * XTEA      2  0x0028-0x0028   0x0029-0x0029
  * BASE64    2  0x002A-0x002C
  * OID       1  0x002E-0x002E   0x000B-0x000B
  * PADLOCK   1  0x0030-0x0030
- * DES       1  0x0032-0x0032
+ * DES       2  0x0032-0x0032   0x0033-0x0033
  * CTR_DBRG  4  0x0034-0x003A
  * ENTROPY   3  0x003C-0x0040   0x003D-0x003F
  * NET      11  0x0042-0x0052   0x0043-0x0045
  * ASN1      7  0x0060-0x006C
+ * CMAC      1  0x007A-0x007A
  * PBKDF2    1  0x007C-0x007C
- * HMAC_DRBG 4  0x0003-0x0009
- * CCM       2                  0x000D-0x000F
+ * HMAC_DRBG 4                  0x0003-0x0009
+ * CCM       3                  0x000D-0x0011
+ * ARC4      1                  0x0019-0x0019
+ * MD2       1                  0x002B-0x002B
+ * MD4       1                  0x002D-0x002D
+ * MD5       1                  0x002F-0x002F
+ * RIPEMD160 1                  0x0031-0x0031
+ * SHA1      1                  0x0035-0x0035
+ * SHA256    1                  0x0037-0x0037
+ * SHA512    1                  0x0039-0x0039
  *
  * High-level module nr (3 bits - 0x0...-0x7...)
  * Name      ID  Nr of Errors
@@ -73,12 +83,12 @@
  * PKCS#12   1   4 (Started from top)
  * X509      2   20
  * PKCS5     2   4 (Started from top)
- * DHM       3   9
- * PK        3   14 (Started from top)
- * RSA       4   10
- * ECP       4   8 (Started from top)
- * MD        5   4
- * CIPHER    6   6
+ * DHM       3   11
+ * PK        3   15 (Started from top)
+ * RSA       4   11
+ * ECP       4   9 (Started from top)
+ * MD        5   5
+ * CIPHER    6   8
  * SSL       6   17 (Started from top)
  * SSL       7   31
  *
diff --git a/include/mbedtls/gcm.h b/include/mbedtls/gcm.h
index 8f3b565..1e5a507 100644
--- a/include/mbedtls/gcm.h
+++ b/include/mbedtls/gcm.h
@@ -1,9 +1,16 @@
 /**
  * \file gcm.h
  *
- * \brief Galois/Counter mode for 128-bit block ciphers
+ * \brief Galois/Counter Mode (GCM) for 128-bit block ciphers, as defined
+ *        in <em>D. McGrew, J. Viega, The Galois/Counter Mode of Operation
+ *        (GCM), Natl. Inst. Stand. Technol.</em>
  *
- *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ * For more information on GCM, see <em>NIST SP 800-38D: Recommendation for
+ * Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC</em>.
+ *
+ */
+/*
+ *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
@@ -18,8 +25,9 @@
  *  See the License for the specific language governing permissions and
  *  limitations under the License.
  *
- *  This file is part of mbed TLS (https://tls.mbed.org)
+ *  This file is part of Mbed TLS (https://tls.mbed.org)
  */
+
 #ifndef MBEDTLS_GCM_H
 #define MBEDTLS_GCM_H
 
@@ -31,6 +39,7 @@
 #define MBEDTLS_GCM_DECRYPT     0
 
 #define MBEDTLS_ERR_GCM_AUTH_FAILED                       -0x0012  /**< Authenticated decryption failed. */
+#define MBEDTLS_ERR_GCM_HW_ACCEL_FAILED                   -0x0013  /**< GCM hardware accelerator failed. */
 #define MBEDTLS_ERR_GCM_BAD_INPUT                         -0x0014  /**< Bad input parameters to function. */
 
 #if !defined(MBEDTLS_GCM_ALT)
@@ -40,39 +49,49 @@
 #endif
 
 /**
- * \brief          GCM context structure
+ * \brief          The GCM context structure.
  */
 typedef struct {
-    mbedtls_cipher_context_t cipher_ctx;/*!< cipher context used */
-    uint64_t HL[16];            /*!< Precalculated HTable */
-    uint64_t HH[16];            /*!< Precalculated HTable */
-    uint64_t len;               /*!< Total data length */
-    uint64_t add_len;           /*!< Total add length */
-    unsigned char base_ectr[16];/*!< First ECTR for tag */
-    unsigned char y[16];        /*!< Y working value */
-    unsigned char buf[16];      /*!< buf working value */
-    int mode;                   /*!< Encrypt or Decrypt */
+    mbedtls_cipher_context_t cipher_ctx;  /*!< The cipher context used. */
+    uint64_t HL[16];                      /*!< Precalculated HTable low. */
+    uint64_t HH[16];                      /*!< Precalculated HTable high. */
+    uint64_t len;                         /*!< The total length of the encrypted data. */
+    uint64_t add_len;                     /*!< The total length of the additional data. */
+    unsigned char base_ectr[16];          /*!< The first ECTR for tag. */
+    unsigned char y[16];                  /*!< The Y working value. */
+    unsigned char buf[16];                /*!< The buf working value. */
+    int mode;                             /*!< The operation to perform:
+                                               #MBEDTLS_GCM_ENCRYPT or
+                                               #MBEDTLS_GCM_DECRYPT. */
 }
 mbedtls_gcm_context;
 
 /**
- * \brief           Initialize GCM context (just makes references valid)
- *                  Makes the context ready for mbedtls_gcm_setkey() or
- *                  mbedtls_gcm_free().
+ * \brief           This function initializes the specified GCM context,
+ *                  to make references valid, and prepares the context
+ *                  for mbedtls_gcm_setkey() or mbedtls_gcm_free().
  *
- * \param ctx       GCM context to initialize
+ *                  The function does not bind the GCM context to a particular
+ *                  cipher, nor set the key. For this purpose, use
+ *                  mbedtls_gcm_setkey().
+ *
+ * \param ctx       The GCM context to initialize.
  */
 void mbedtls_gcm_init( mbedtls_gcm_context *ctx );
 
 /**
- * \brief           GCM initialization (encryption)
+ * \brief           This function associates a GCM context with a
+ *                  cipher algorithm and a key.
  *
- * \param ctx       GCM context to be initialized
- * \param cipher    cipher to use (a 128-bit block cipher)
- * \param key       encryption key
- * \param keybits   must be 128, 192 or 256
+ * \param ctx       The GCM context to initialize.
+ * \param cipher    The 128-bit block cipher to use.
+ * \param key       The encryption key.
+ * \param keybits   The key size in bits. Valid options are:
+ *                  <ul><li>128 bits</li>
+ *                  <li>192 bits</li>
+ *                  <li>256 bits</li></ul>
  *
- * \return          0 if successful, or a cipher specific error code
+ * \return          \c 0 on success, or a cipher specific error code.
  */
 int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx,
                         mbedtls_cipher_id_t cipher,
@@ -80,26 +99,27 @@
                         unsigned int keybits );
 
 /**
- * \brief           GCM buffer encryption/decryption using a block cipher
+ * \brief           This function performs GCM encryption or decryption of a buffer.
  *
- * \note On encryption, the output buffer can be the same as the input buffer.
- *       On decryption, the output buffer cannot be the same as input buffer.
- *       If buffers overlap, the output buffer must trail at least 8 bytes
+ * \note For encryption, the output buffer can be the same as the input buffer.
+ *       For decryption, the output buffer cannot be the same as input buffer.
+ *       If the buffers overlap, the output buffer must trail at least 8 Bytes
  *       behind the input buffer.
  *
- * \param ctx       GCM context
- * \param mode      MBEDTLS_GCM_ENCRYPT or MBEDTLS_GCM_DECRYPT
- * \param length    length of the input data
- * \param iv        initialization vector
- * \param iv_len    length of IV
- * \param add       additional data
- * \param add_len   length of additional data
- * \param input     buffer holding the input data
- * \param output    buffer for holding the output data
- * \param tag_len   length of the tag to generate
- * \param tag       buffer for holding the tag
+ * \param ctx       The GCM context to use for encryption or decryption.
+ * \param mode      The operation to perform: #MBEDTLS_GCM_ENCRYPT or
+ *                  #MBEDTLS_GCM_DECRYPT.
+ * \param length    The length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish().
+ * \param iv        The initialization vector.
+ * \param iv_len    The length of the IV.
+ * \param add       The buffer holding the additional data.
+ * \param add_len   The length of the additional data.
+ * \param input     The buffer holding the input data.
+ * \param output    The buffer for holding the output data.
+ * \param tag_len   The length of the tag to generate.
+ * \param tag       The buffer for holding the tag.
  *
- * \return         0 if successful
+ * \return         \c 0 on success.
  */
 int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx,
                        int mode,
@@ -114,25 +134,26 @@
                        unsigned char *tag );
 
 /**
- * \brief           GCM buffer authenticated decryption using a block cipher
+ * \brief           This function performs a GCM authenticated decryption of a
+ *                  buffer.
  *
- * \note On decryption, the output buffer cannot be the same as input buffer.
- *       If buffers overlap, the output buffer must trail at least 8 bytes
+ * \note For decryption, the output buffer cannot be the same as input buffer.
+ *       If the buffers overlap, the output buffer must trail at least 8 Bytes
  *       behind the input buffer.
  *
- * \param ctx       GCM context
- * \param length    length of the input data
- * \param iv        initialization vector
- * \param iv_len    length of IV
- * \param add       additional data
- * \param add_len   length of additional data
- * \param tag       buffer holding the tag
- * \param tag_len   length of the tag
- * \param input     buffer holding the input data
- * \param output    buffer for holding the output data
+ * \param ctx       The GCM context.
+ * \param length    The length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish().
+ * \param iv        The initialization vector.
+ * \param iv_len    The length of the IV.
+ * \param add       The buffer holding the additional data.
+ * \param add_len   The length of the additional data.
+ * \param tag       The buffer holding the tag.
+ * \param tag_len   The length of the tag.
+ * \param input     The buffer holding the input data.
+ * \param output    The buffer for holding the output data.
  *
- * \return         0 if successful and authenticated,
- *                 MBEDTLS_ERR_GCM_AUTH_FAILED if tag does not match
+ * \return         0 if successful and authenticated, or
+ *                 #MBEDTLS_ERR_GCM_AUTH_FAILED if tag does not match.
  */
 int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx,
                       size_t length,
@@ -146,16 +167,18 @@
                       unsigned char *output );
 
 /**
- * \brief           Generic GCM stream start function
+ * \brief           This function starts a GCM encryption or decryption
+ *                  operation.
  *
- * \param ctx       GCM context
- * \param mode      MBEDTLS_GCM_ENCRYPT or MBEDTLS_GCM_DECRYPT
- * \param iv        initialization vector
- * \param iv_len    length of IV
- * \param add       additional data (or NULL if length is 0)
- * \param add_len   length of additional data
+ * \param ctx       The GCM context.
+ * \param mode      The operation to perform: #MBEDTLS_GCM_ENCRYPT or
+ *                  #MBEDTLS_GCM_DECRYPT.
+ * \param iv        The initialization vector.
+ * \param iv_len    The length of the IV.
+ * \param add       The buffer holding the additional data, or NULL if \p add_len is 0.
+ * \param add_len   The length of the additional data. If 0, \p  add is NULL.
  *
- * \return         0 if successful
+ * \return         \c 0 on success.
  */
 int mbedtls_gcm_starts( mbedtls_gcm_context *ctx,
                 int mode,
@@ -165,21 +188,23 @@
                 size_t add_len );
 
 /**
- * \brief           Generic GCM update function. Encrypts/decrypts using the
- *                  given GCM context. Expects input to be a multiple of 16
- *                  bytes! Only the last call before mbedtls_gcm_finish() can be less
- *                  than 16 bytes!
+ * \brief           This function feeds an input buffer into an ongoing GCM
+ *                  encryption or decryption operation.
  *
- * \note On decryption, the output buffer cannot be the same as input buffer.
- *       If buffers overlap, the output buffer must trail at least 8 bytes
+ *    `             The function expects input to be a multiple of 16
+ *                  Bytes. Only the last call before calling
+ *                  mbedtls_gcm_finish() can be less than 16 Bytes.
+ *
+ * \note For decryption, the output buffer cannot be the same as input buffer.
+ *       If the buffers overlap, the output buffer must trail at least 8 Bytes
  *       behind the input buffer.
  *
- * \param ctx       GCM context
- * \param length    length of the input data
- * \param input     buffer holding the input data
- * \param output    buffer for holding the output data
+ * \param ctx       The GCM context.
+ * \param length    The length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish().
+ * \param input     The buffer holding the input data.
+ * \param output    The buffer for holding the output data.
  *
- * \return         0 if successful or MBEDTLS_ERR_GCM_BAD_INPUT
+ * \return         \c 0 on success, or #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
  */
 int mbedtls_gcm_update( mbedtls_gcm_context *ctx,
                 size_t length,
@@ -187,24 +212,27 @@
                 unsigned char *output );
 
 /**
- * \brief           Generic GCM finalisation function. Wraps up the GCM stream
- *                  and generates the tag. The tag can have a maximum length of
- *                  16 bytes.
+ * \brief           This function finishes the GCM operation and generates
+ *                  the authentication tag.
  *
- * \param ctx       GCM context
- * \param tag       buffer for holding the tag
- * \param tag_len   length of the tag to generate (must be at least 4)
+ *                  It wraps up the GCM stream, and generates the
+ *                  tag. The tag can have a maximum length of 16 Bytes.
  *
- * \return          0 if successful or MBEDTLS_ERR_GCM_BAD_INPUT
+ * \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.
+ *
+ * \return          \c 0 on success, or #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
  */
 int mbedtls_gcm_finish( mbedtls_gcm_context *ctx,
                 unsigned char *tag,
                 size_t tag_len );
 
 /**
- * \brief           Free a GCM context and underlying cipher sub-context
+ * \brief           This function clears a GCM context and the underlying
+ *                  cipher sub-context.
  *
- * \param ctx       GCM context to free
+ * \param ctx       The GCM context to clear.
  */
 void mbedtls_gcm_free( mbedtls_gcm_context *ctx );
 
@@ -221,9 +249,9 @@
 #endif
 
 /**
- * \brief          Checkup routine
+ * \brief          The GCM checkup routine.
  *
- * \return         0 if successful, or 1 if the test failed
+ * \return         \c 0 on success, or \c 1 on failure.
  */
 int mbedtls_gcm_self_test( int verbose );
 
diff --git a/include/mbedtls/havege.h b/include/mbedtls/havege.h
index dac5d31..d4cb3ed 100644
--- a/include/mbedtls/havege.h
+++ b/include/mbedtls/havege.h
@@ -2,7 +2,8 @@
  * \file havege.h
  *
  * \brief HAVEGE: HArdware Volatile Entropy Gathering and Expansion
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/hmac_drbg.h b/include/mbedtls/hmac_drbg.h
index e010558..e0821cf 100644
--- a/include/mbedtls/hmac_drbg.h
+++ b/include/mbedtls/hmac_drbg.h
@@ -2,7 +2,8 @@
  * \file hmac_drbg.h
  *
  * \brief HMAC_DRBG (NIST SP 800-90A)
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/md.h b/include/mbedtls/md.h
index 89be847..06538c3 100644
--- a/include/mbedtls/md.h
+++ b/include/mbedtls/md.h
@@ -1,11 +1,12 @@
-/**
+ /**
  * \file md.h
  *
- * \brief Generic message digest wrapper
+ * \brief The generic message-digest wrapper.
  *
  * \author Adriaan de Jong <dejong@fox-it.com>
- *
- *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ */
+/*
+ *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
@@ -20,8 +21,9 @@
  *  See the License for the specific language governing permissions and
  *  limitations under the License.
  *
- *  This file is part of mbed TLS (https://tls.mbed.org)
+ *  This file is part of Mbed TLS (https://tls.mbed.org)
  */
+
 #ifndef MBEDTLS_MD_H
 #define MBEDTLS_MD_H
 
@@ -37,11 +39,20 @@
 #define MBEDTLS_ERR_MD_BAD_INPUT_DATA                     -0x5100  /**< Bad input parameters to function. */
 #define MBEDTLS_ERR_MD_ALLOC_FAILED                       -0x5180  /**< Failed to allocate memory. */
 #define MBEDTLS_ERR_MD_FILE_IO_ERROR                      -0x5200  /**< Opening or reading of file failed. */
+#define MBEDTLS_ERR_MD_HW_ACCEL_FAILED                    -0x5280  /**< MD hardware accelerator failed. */
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/**
+ * \brief     Enumeration of supported message digests
+ *
+ * \warning   MD2, MD4, MD5 and SHA-1 are considered weak message digests and
+ *            their use constitutes a security risk. We recommend considering
+ *            stronger message digests instead.
+ *
+ */
 typedef enum {
     MBEDTLS_MD_NONE=0,
     MBEDTLS_MD_MD2,
@@ -62,65 +73,79 @@
 #endif
 
 /**
- * Opaque struct defined in md_internal.h
+ * Opaque struct defined in md_internal.h.
  */
 typedef struct mbedtls_md_info_t mbedtls_md_info_t;
 
 /**
- * Generic message digest context.
+ * The generic message-digest context.
  */
 typedef struct {
-    /** Information about the associated message digest */
+    /** Information about the associated message digest. */
     const mbedtls_md_info_t *md_info;
 
-    /** Digest-specific context */
+    /** The digest-specific context. */
     void *md_ctx;
 
-    /** HMAC part of the context */
+    /** The HMAC part of the context. */
     void *hmac_ctx;
 } mbedtls_md_context_t;
 
 /**
- * \brief Returns the list of digests supported by the generic digest module.
+ * \brief           This function returns the list of digests supported by the
+ *                  generic digest module.
  *
- * \return          a statically allocated array of digests, the last entry
- *                  is 0.
+ * \return          A statically allocated array of digests. Each element
+ *                  in the returned list is an integer belonging to the
+ *                  message-digest enumeration #mbedtls_md_type_t.
+ *                  The last entry is 0.
  */
 const int *mbedtls_md_list( void );
 
 /**
- * \brief           Returns the message digest information associated with the
- *                  given digest name.
+ * \brief           This function returns the message-digest information
+ *                  associated with the given digest name.
  *
- * \param md_name   Name of the digest to search for.
+ * \param md_name   The name of the digest to search for.
  *
- * \return          The message digest information associated with md_name or
- *                  NULL if not found.
+ * \return          The message-digest information associated with \p md_name,
+ *                  or NULL if not found.
  */
 const mbedtls_md_info_t *mbedtls_md_info_from_string( const char *md_name );
 
 /**
- * \brief           Returns the message digest information associated with the
- *                  given digest type.
+ * \brief           This function returns the message-digest information
+ *                  associated with the given digest type.
  *
- * \param md_type   type of digest to search for.
+ * \param md_type   The type of digest to search for.
  *
- * \return          The message digest information associated with md_type or
- *                  NULL if not found.
+ * \return          The message-digest information associated with \p md_type,
+ *                  or NULL if not found.
  */
 const mbedtls_md_info_t *mbedtls_md_info_from_type( mbedtls_md_type_t md_type );
 
 /**
- * \brief           Initialize a md_context (as NONE)
- *                  This should always be called first.
- *                  Prepares the context for mbedtls_md_setup() or mbedtls_md_free().
+ * \brief           This function initializes a message-digest context without
+ *                  binding it to a particular message-digest algorithm.
+ *
+ *                  This function should always be called first. It prepares the
+ *                  context for mbedtls_md_setup() for binding it to a
+ *                  message-digest algorithm.
  */
 void mbedtls_md_init( mbedtls_md_context_t *ctx );
 
 /**
- * \brief           Free and clear the internal structures of ctx.
- *                  Can be called at any time after mbedtls_md_init().
- *                  Mandatory once mbedtls_md_setup() has been called.
+ * \brief           This function clears the internal structure of \p ctx and
+ *                  frees any embedded internal structure, but does not free
+ *                  \p ctx itself.
+ *
+ *                  If you have called mbedtls_md_setup() on \p ctx, you must
+ *                  call mbedtls_md_free() when you are no longer using the
+ *                  context.
+ *                  Calling this function if you have previously
+ *                  called mbedtls_md_init() and nothing else is optional.
+ *                  You must not call this function if you have not called
+ *                  mbedtls_md_init().
  */
 void mbedtls_md_free( mbedtls_md_context_t *ctx );
 
@@ -131,220 +156,288 @@
 #define MBEDTLS_DEPRECATED
 #endif
 /**
- * \brief           Select MD to use and allocate internal structures.
- *                  Should be called after mbedtls_md_init() or mbedtls_md_free().
+ * \brief           This function selects the message digest algorithm to use,
+ *                  and allocates internal structures.
+ *
+ *                  It should be called after mbedtls_md_init() or mbedtls_md_free().
  *                  Makes it necessary to call mbedtls_md_free() later.
  *
  * \deprecated      Superseded by mbedtls_md_setup() in 2.0.0
  *
- * \param ctx       Context to set up.
- * \param md_info   Message digest to use.
+ * \param ctx       The context to set up.
+ * \param md_info   The information structure of the message-digest algorithm
+ *                  to use.
  *
  * \returns         \c 0 on success,
- *                  \c MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure,
- *                  \c MBEDTLS_ERR_MD_ALLOC_FAILED memory allocation failure.
+ *                  #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure,
+ *                  #MBEDTLS_ERR_MD_ALLOC_FAILED memory allocation failure.
  */
 int mbedtls_md_init_ctx( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info ) MBEDTLS_DEPRECATED;
 #undef MBEDTLS_DEPRECATED
 #endif /* MBEDTLS_DEPRECATED_REMOVED */
 
 /**
- * \brief           Select MD to use and allocate internal structures.
- *                  Should be called after mbedtls_md_init() or mbedtls_md_free().
- *                  Makes it necessary to call mbedtls_md_free() later.
+ * \brief           This function selects the message digest algorithm to use,
+ *                  and allocates internal structures.
  *
- * \param ctx       Context to set up.
- * \param md_info   Message digest to use.
- * \param hmac      0 to save some memory if HMAC will not be used,
- *                  non-zero is HMAC is going to be used with this context.
+ *                  It should be called after mbedtls_md_init() or
+ *                  mbedtls_md_free(). Makes it necessary to call
+ *                  mbedtls_md_free() later.
+ *
+ * \param ctx       The context to set up.
+ * \param md_info   The information structure of the message-digest algorithm
+ *                  to use.
+ * \param hmac      <ul><li>0: HMAC is not used. Saves some memory.</li>
+ *                  <li>non-zero: HMAC is used with this context.</li></ul>
  *
  * \returns         \c 0 on success,
- *                  \c MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure,
- *                  \c MBEDTLS_ERR_MD_ALLOC_FAILED memory allocation failure.
+ *                  #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure, or
+ *                  #MBEDTLS_ERR_MD_ALLOC_FAILED on memory allocation failure.
  */
 int mbedtls_md_setup( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info, int hmac );
 
 /**
- * \brief           Clone the state of an MD context
+ * \brief           This function clones the state of an message-digest
+ *                  context.
  *
- * \note            The two contexts must have been setup to the same type
- *                  (cloning from SHA-256 to SHA-512 make no sense).
+ * \note            You must call mbedtls_md_setup() on \c dst before calling
+ *                  this function.
  *
- * \warning         Only clones the MD state, not the HMAC state! (for now)
+ * \note            The two contexts must have the same type,
+ *                  for example, both are SHA-256.
  *
- * \param dst       The destination context
- * \param src       The context to be cloned
+ * \warning         This function clones the message-digest state, not the
+ *                  HMAC state.
+ *
+ * \param dst       The destination context.
+ * \param src       The context to be cloned.
  *
  * \return          \c 0 on success,
- *                  \c MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure.
+ *                  #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure.
  */
 int mbedtls_md_clone( mbedtls_md_context_t *dst,
                       const mbedtls_md_context_t *src );
 
 /**
- * \brief           Returns the size of the message digest output.
+ * \brief           This function extracts the message-digest size from the
+ *                  message-digest information structure.
  *
- * \param md_info   message digest info
+ * \param md_info   The information structure of the message-digest algorithm
+ *                  to use.
  *
- * \return          size of the message digest output in bytes.
+ * \return          The size of the message-digest output in Bytes.
  */
 unsigned char mbedtls_md_get_size( const mbedtls_md_info_t *md_info );
 
 /**
- * \brief           Returns the type of the message digest output.
+ * \brief           This function extracts the message-digest type from the
+ *                  message-digest information structure.
  *
- * \param md_info   message digest info
+ * \param md_info   The information structure of the message-digest algorithm
+ *                  to use.
  *
- * \return          type of the message digest output.
+ * \return          The type of the message digest.
  */
 mbedtls_md_type_t mbedtls_md_get_type( const mbedtls_md_info_t *md_info );
 
 /**
- * \brief           Returns the name of the message digest output.
+ * \brief           This function extracts the message-digest name from the
+ *                  message-digest information structure.
  *
- * \param md_info   message digest info
+ * \param md_info   The information structure of the message-digest algorithm
+ *                  to use.
  *
- * \return          name of the message digest output.
+ * \return          The name of the message digest.
  */
 const char *mbedtls_md_get_name( const mbedtls_md_info_t *md_info );
 
 /**
- * \brief           Prepare the context to digest a new message.
- *                  Generally called after mbedtls_md_setup() or mbedtls_md_finish().
- *                  Followed by mbedtls_md_update().
+ * \brief           This function starts a message-digest computation.
  *
- * \param ctx       generic message digest context.
+ *                  You must call this function after setting up the context
+ *                  with mbedtls_md_setup(), and before passing data with
+ *                  mbedtls_md_update().
  *
- * \returns         0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- *                  verification fails.
+ * \param ctx       The generic message-digest context.
+ *
+ * \returns         \c 0 on success, #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
+ *                  parameter verification fails.
  */
 int mbedtls_md_starts( mbedtls_md_context_t *ctx );
 
 /**
- * \brief           Generic message digest process buffer
- *                  Called between mbedtls_md_starts() and mbedtls_md_finish().
- *                  May be called repeatedly.
+ * \brief           This function feeds an input buffer into an ongoing
+ *                  message-digest computation.
  *
- * \param ctx       Generic message digest context
- * \param input     buffer holding the  datal
- * \param ilen      length of the input data
+ *                  You must call mbedtls_md_starts() before calling this
+ *                  function. You may call this function multiple times.
+ *                  Afterwards, call mbedtls_md_finish().
  *
- * \returns         0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- *                  verification fails.
+ * \param ctx       The generic message-digest context.
+ * \param input     The buffer holding the input data.
+ * \param ilen      The length of the input data.
+ *
+ * \returns         \c 0 on success, #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
+ *                  parameter verification fails.
  */
 int mbedtls_md_update( mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen );
 
 /**
- * \brief           Generic message digest final digest
- *                  Called after mbedtls_md_update().
- *                  Usually followed by mbedtls_md_free() or mbedtls_md_starts().
+ * \brief           This function finishes the digest operation,
+ *                  and writes the result to the output buffer.
  *
- * \param ctx       Generic message digest context
- * \param output    Generic message digest checksum result
+ *                  Call this function after a call to mbedtls_md_starts(),
+ *                  followed by any number of calls to mbedtls_md_update().
+ *                  Afterwards, you may either clear the context with
+ *                  mbedtls_md_free(), or call mbedtls_md_starts() to reuse
+ *                  the context for another digest operation with the same
+ *                  algorithm.
  *
- * \returns         0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- *                  verification fails.
+ * \param ctx       The generic message-digest context.
+ * \param output    The buffer for the generic message-digest checksum result.
+ *
+ * \returns         \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
+ *                  parameter verification fails.
  */
 int mbedtls_md_finish( mbedtls_md_context_t *ctx, unsigned char *output );
 
 /**
- * \brief          Output = message_digest( input buffer )
+ * \brief          This function calculates the message-digest of a buffer,
+ *                 with respect to a configurable message-digest algorithm
+ *                 in a single call.
  *
- * \param md_info  message digest info
- * \param input    buffer holding the  data
- * \param ilen     length of the input data
- * \param output   Generic message digest checksum result
+ *                 The result is calculated as
+ *                 Output = message_digest(input buffer).
  *
- * \returns        0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- *                 verification fails.
+ * \param md_info  The information structure of the message-digest algorithm
+ *                 to use.
+ * \param input    The buffer holding the data.
+ * \param ilen     The length of the input data.
+ * \param output   The generic message-digest checksum result.
+ *
+ * \returns        \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
+ *                 parameter verification fails.
  */
 int mbedtls_md( const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen,
         unsigned char *output );
 
 #if defined(MBEDTLS_FS_IO)
 /**
- * \brief          Output = message_digest( file contents )
+ * \brief          This function calculates the message-digest checksum
+ *                 result of the contents of the provided file.
  *
- * \param md_info  message digest info
- * \param path     input file name
- * \param output   generic message digest checksum result
+ *                 The result is calculated as
+ *                 Output = message_digest(file contents).
  *
- * \return         0 if successful,
- *                 MBEDTLS_ERR_MD_FILE_IO_ERROR if file input failed,
- *                 MBEDTLS_ERR_MD_BAD_INPUT_DATA if md_info was NULL.
+ * \param md_info  The information structure of the message-digest algorithm
+ *                 to use.
+ * \param path     The input file name.
+ * \param output   The generic message-digest checksum result.
+ *
+ * \return         \c 0 on success,
+ *                 #MBEDTLS_ERR_MD_FILE_IO_ERROR if file input failed, or
+ *                 #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info was NULL.
  */
 int mbedtls_md_file( const mbedtls_md_info_t *md_info, const char *path,
                      unsigned char *output );
 #endif /* MBEDTLS_FS_IO */
 
 /**
- * \brief           Set HMAC key and prepare to authenticate a new message.
- *                  Usually called after mbedtls_md_setup() or mbedtls_md_hmac_finish().
+ * \brief           This function sets the HMAC key and prepares to
+ *                  authenticate a new message.
  *
- * \param ctx       HMAC context
- * \param key       HMAC secret key
- * \param keylen    length of the HMAC key in bytes
+ *                  Call this function after mbedtls_md_setup(), to use
+ *                  the MD context for an HMAC calculation, then call
+ *                  mbedtls_md_hmac_update() to provide the input data, and
+ *                  mbedtls_md_hmac_finish() to get the HMAC value.
  *
- * \returns         0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- *                  verification fails.
+ * \param ctx       The message digest context containing an embedded HMAC
+ *                  context.
+ * \param key       The HMAC secret key.
+ * \param keylen    The length of the HMAC key in Bytes.
+ *
+ * \returns         \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
+ *                  parameter verification fails.
  */
 int mbedtls_md_hmac_starts( mbedtls_md_context_t *ctx, const unsigned char *key,
                     size_t keylen );
 
 /**
- * \brief           Generic HMAC process buffer.
- *                  Called between mbedtls_md_hmac_starts() or mbedtls_md_hmac_reset()
- *                  and mbedtls_md_hmac_finish().
- *                  May be called repeatedly.
+ * \brief           This function feeds an input buffer into an ongoing HMAC
+ *                  computation.
  *
- * \param ctx       HMAC context
- * \param input     buffer holding the  data
- * \param ilen      length of the input data
+ *                  Call mbedtls_md_hmac_starts() or mbedtls_md_hmac_reset()
+ *                  before calling this function.
+ *                  You may call this function multiple times to pass the
+ *                  input piecewise.
+ *                  Afterwards, call mbedtls_md_hmac_finish().
  *
- * \returns         0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- *                  verification fails.
+ * \param ctx       The message digest context containing an embedded HMAC
+ *                  context.
+ * \param input     The buffer holding the input data.
+ * \param ilen      The length of the input data.
+ *
+ * \returns         \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
+ *                  parameter verification fails.
  */
 int mbedtls_md_hmac_update( mbedtls_md_context_t *ctx, const unsigned char *input,
                     size_t ilen );
 
 /**
- * \brief           Output HMAC.
- *                  Called after mbedtls_md_hmac_update().
- *                  Usually followed by mbedtls_md_hmac_reset(),
- *                  mbedtls_md_hmac_starts(), or mbedtls_md_free().
+ * \brief           This function finishes the HMAC operation, and writes
+ *                  the result to the output buffer.
  *
- * \param ctx       HMAC context
- * \param output    Generic HMAC checksum result
+ *                  Call this function after mbedtls_md_hmac_starts() and
+ *                  mbedtls_md_hmac_update() to get the HMAC value. Afterwards
+ *                  you may either call mbedtls_md_free() to clear the context,
+ *                  or call mbedtls_md_hmac_reset() to reuse the context with
+ *                  the same HMAC key.
  *
- * \returns         0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- *                  verification fails.
+ * \param ctx       The message digest context containing an embedded HMAC
+ *                  context.
+ * \param output    The generic HMAC checksum result.
+ *
+ * \returns         \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
+ *                  parameter verification fails.
  */
 int mbedtls_md_hmac_finish( mbedtls_md_context_t *ctx, unsigned char *output);
 
 /**
- * \brief           Prepare to authenticate a new message with the same key.
- *                  Called after mbedtls_md_hmac_finish() and before
- *                  mbedtls_md_hmac_update().
+ * \brief           This function prepares to authenticate a new message with
+ *                  the same key as the previous HMAC operation.
  *
- * \param ctx       HMAC context to be reset
+ *                  You may call this function after mbedtls_md_hmac_finish().
+ *                  Afterwards call mbedtls_md_hmac_update() to pass the new
+ *                  input.
  *
- * \returns         0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- *                  verification fails.
+ * \param ctx       The message digest context containing an embedded HMAC
+ *                  context.
+ *
+ * \returns         \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
+ *                  parameter verification fails.
  */
 int mbedtls_md_hmac_reset( mbedtls_md_context_t *ctx );
 
 /**
- * \brief          Output = Generic_HMAC( hmac key, input buffer )
+ * \brief          This function calculates the full generic HMAC
+ *                 on the input buffer with the provided key.
  *
- * \param md_info  message digest info
- * \param key      HMAC secret key
- * \param keylen   length of the HMAC key in bytes
- * \param input    buffer holding the  data
- * \param ilen     length of the input data
- * \param output   Generic HMAC-result
+ *                 The function allocates the context, performs the
+ *                 calculation, and frees the context.
  *
- * \returns        0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter
- *                 verification fails.
+ *                 The HMAC result is calculated as
+ *                 output = generic HMAC(hmac key, input buffer).
+ *
+ * \param md_info  The information structure of the message-digest algorithm
+ *                 to use.
+ * \param key      The HMAC secret key.
+ * \param keylen   The length of the HMAC secret key in Bytes.
+ * \param input    The buffer holding the input data.
+ * \param ilen     The length of the input data.
+ * \param output   The generic HMAC result.
+ *
+ * \returns        \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
+ *                 parameter verification fails.
  */
 int mbedtls_md_hmac( const mbedtls_md_info_t *md_info, const unsigned char *key, size_t keylen,
                 const unsigned char *input, size_t ilen,
diff --git a/include/mbedtls/md2.h b/include/mbedtls/md2.h
index 0f93fbf..2ff3f17 100644
--- a/include/mbedtls/md2.h
+++ b/include/mbedtls/md2.h
@@ -3,6 +3,11 @@
  *
  * \brief MD2 message digest algorithm (hash function)
  *
+ * \warning MD2 is considered a weak message digest and its use constitutes a
+ *          security risk. We recommend considering stronger message digests
+ *          instead.
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
@@ -19,6 +24,7 @@
  *  limitations under the License.
  *
  *  This file is part of mbed TLS (https://tls.mbed.org)
+ *
  */
 #ifndef MBEDTLS_MD2_H
 #define MBEDTLS_MD2_H
@@ -31,6 +37,13 @@
 
 #include <stddef.h>
 
+#define MBEDTLS_ERR_MD2_HW_ACCEL_FAILED                   -0x002B  /**< MD2 hardware accelerator failed */
+
+#if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
+    !defined(inline) && !defined(__cplusplus)
+#define inline __inline
+#endif
+
 #if !defined(MBEDTLS_MD2_ALT)
 // Regular implementation
 //
@@ -41,6 +54,11 @@
 
 /**
  * \brief          MD2 context structure
+ *
+ * \warning        MD2 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
 typedef struct
 {
@@ -55,6 +73,11 @@
  * \brief          Initialize MD2 context
  *
  * \param ctx      MD2 context to be initialized
+ *
+ * \warning        MD2 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
 void mbedtls_md2_init( mbedtls_md2_context *ctx );
 
@@ -62,6 +85,11 @@
  * \brief          Clear MD2 context
  *
  * \param ctx      MD2 context to be cleared
+ *
+ * \warning        MD2 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
 void mbedtls_md2_free( mbedtls_md2_context *ctx );
 
@@ -70,6 +98,11 @@
  *
  * \param dst      The destination context
  * \param src      The context to be cloned
+ *
+ * \warning        MD2 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
 void mbedtls_md2_clone( mbedtls_md2_context *dst,
                         const mbedtls_md2_context *src );
@@ -78,25 +111,150 @@
  * \brief          MD2 context setup
  *
  * \param ctx      context to be initialized
+ *
+ * \return         0 if successful
+ *
+ * \warning        MD2 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
-void mbedtls_md2_starts( mbedtls_md2_context *ctx );
+int mbedtls_md2_starts_ret( mbedtls_md2_context *ctx );
 
 /**
  * \brief          MD2 process buffer
  *
  * \param ctx      MD2 context
- * \param input    buffer holding the  data
+ * \param input    buffer holding the data
  * \param ilen     length of the input data
+ *
+ * \return         0 if successful
+ *
+ * \warning        MD2 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
-void mbedtls_md2_update( mbedtls_md2_context *ctx, const unsigned char *input, size_t ilen );
+int mbedtls_md2_update_ret( mbedtls_md2_context *ctx,
+                            const unsigned char *input,
+                            size_t ilen );
 
 /**
  * \brief          MD2 final digest
  *
  * \param ctx      MD2 context
  * \param output   MD2 checksum result
+ *
+ * \return         0 if successful
+ *
+ * \warning        MD2 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
-void mbedtls_md2_finish( mbedtls_md2_context *ctx, unsigned char output[16] );
+int mbedtls_md2_finish_ret( mbedtls_md2_context *ctx,
+                            unsigned char output[16] );
+
+/**
+ * \brief          MD2 process data block (internal use only)
+ *
+ * \param ctx      MD2 context
+ *
+ * \return         0 if successful
+ *
+ * \warning        MD2 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
+ */
+int mbedtls_internal_md2_process( mbedtls_md2_context *ctx );
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED      __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+/**
+ * \brief          MD2 context setup
+ *
+ * \deprecated     Superseded by mbedtls_md2_starts_ret() in 2.7.0
+ *
+ * \param ctx      context to be initialized
+ *
+ * \warning        MD2 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_md2_starts(
+                                                    mbedtls_md2_context *ctx )
+{
+    mbedtls_md2_starts_ret( ctx );
+}
+
+/**
+ * \brief          MD2 process buffer
+ *
+ * \deprecated     Superseded by mbedtls_md2_update_ret() in 2.7.0
+ *
+ * \param ctx      MD2 context
+ * \param input    buffer holding the data
+ * \param ilen     length of the input data
+ *
+ * \warning        MD2 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_md2_update(
+                                                mbedtls_md2_context *ctx,
+                                                const unsigned char *input,
+                                                size_t ilen )
+{
+    mbedtls_md2_update_ret( ctx, input, ilen );
+}
+
+/**
+ * \brief          MD2 final digest
+ *
+ * \deprecated     Superseded by mbedtls_md2_finish_ret() in 2.7.0
+ *
+ * \param ctx      MD2 context
+ * \param output   MD2 checksum result
+ *
+ * \warning        MD2 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_md2_finish(
+                                                    mbedtls_md2_context *ctx,
+                                                    unsigned char output[16] )
+{
+    mbedtls_md2_finish_ret( ctx, output );
+}
+
+/**
+ * \brief          MD2 process data block (internal use only)
+ *
+ * \deprecated     Superseded by mbedtls_internal_md2_process() in 2.7.0
+ *
+ * \param ctx      MD2 context
+ *
+ * \warning        MD2 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_md2_process(
+                                                    mbedtls_md2_context *ctx )
+{
+    mbedtls_internal_md2_process( ctx );
+}
+
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
 
 #ifdef __cplusplus
 }
@@ -113,22 +271,61 @@
 /**
  * \brief          Output = MD2( input buffer )
  *
- * \param input    buffer holding the  data
+ * \param input    buffer holding the data
  * \param ilen     length of the input data
  * \param output   MD2 checksum result
+ *
+ * \warning        MD2 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
-void mbedtls_md2( const unsigned char *input, size_t ilen, unsigned char output[16] );
+int mbedtls_md2_ret( const unsigned char *input,
+                     size_t ilen,
+                     unsigned char output[16] );
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED      __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+/**
+ * \brief          Output = MD2( input buffer )
+ *
+ * \deprecated     Superseded by mbedtls_md2_ret() in 2.7.0
+ *
+ * \param input    buffer holding the data
+ * \param ilen     length of the input data
+ * \param output   MD2 checksum result
+ *
+ * \warning        MD2 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_md2( const unsigned char *input,
+                                                   size_t ilen,
+                                                   unsigned char output[16] )
+{
+    mbedtls_md2_ret( input, ilen, output );
+}
+
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
 
 /**
  * \brief          Checkup routine
  *
  * \return         0 if successful, or 1 if the test failed
+ *
+ * \warning        MD2 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
 int mbedtls_md2_self_test( int verbose );
 
-/* Internal use */
-void mbedtls_md2_process( mbedtls_md2_context *ctx );
-
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/mbedtls/md4.h b/include/mbedtls/md4.h
index 45214d4..a2ab57f 100644
--- a/include/mbedtls/md4.h
+++ b/include/mbedtls/md4.h
@@ -3,6 +3,11 @@
  *
  * \brief MD4 message digest algorithm (hash function)
  *
+ * \warning MD4 is considered a weak message digest and its use constitutes a
+ *          security risk. We recommend considering stronger message digests
+ *          instead.
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
@@ -19,6 +24,7 @@
  *  limitations under the License.
  *
  *  This file is part of mbed TLS (https://tls.mbed.org)
+ *
  */
 #ifndef MBEDTLS_MD4_H
 #define MBEDTLS_MD4_H
@@ -32,6 +38,13 @@
 #include <stddef.h>
 #include <stdint.h>
 
+#define MBEDTLS_ERR_MD4_HW_ACCEL_FAILED                   -0x002D  /**< MD4 hardware accelerator failed */
+
+#if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
+    !defined(inline) && !defined(__cplusplus)
+#define inline __inline
+#endif
+
 #if !defined(MBEDTLS_MD4_ALT)
 // Regular implementation
 //
@@ -42,6 +55,11 @@
 
 /**
  * \brief          MD4 context structure
+ *
+ * \warning        MD4 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
 typedef struct
 {
@@ -55,6 +73,11 @@
  * \brief          Initialize MD4 context
  *
  * \param ctx      MD4 context to be initialized
+ *
+ * \warning        MD4 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
 void mbedtls_md4_init( mbedtls_md4_context *ctx );
 
@@ -62,6 +85,11 @@
  * \brief          Clear MD4 context
  *
  * \param ctx      MD4 context to be cleared
+ *
+ * \warning        MD4 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
 void mbedtls_md4_free( mbedtls_md4_context *ctx );
 
@@ -70,6 +98,11 @@
  *
  * \param dst      The destination context
  * \param src      The context to be cloned
+ *
+ * \warning        MD4 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
 void mbedtls_md4_clone( mbedtls_md4_context *dst,
                         const mbedtls_md4_context *src );
@@ -78,25 +111,153 @@
  * \brief          MD4 context setup
  *
  * \param ctx      context to be initialized
+ *
+ * \return         0 if successful
+ *
+ * \warning        MD4 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
  */
-void mbedtls_md4_starts( mbedtls_md4_context *ctx );
+int mbedtls_md4_starts_ret( mbedtls_md4_context *ctx );
 
 /**
  * \brief          MD4 process buffer
  *
  * \param ctx      MD4 context
- * \param input    buffer holding the  data
+ * \param input    buffer holding the data
  * \param ilen     length of the input data
+ *
+ * \return         0 if successful
+ *
+ * \warning        MD4 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
-void mbedtls_md4_update( mbedtls_md4_context *ctx, const unsigned char *input, size_t ilen );
+int mbedtls_md4_update_ret( mbedtls_md4_context *ctx,
+                            const unsigned char *input,
+                            size_t ilen );
 
 /**
  * \brief          MD4 final digest
  *
  * \param ctx      MD4 context
  * \param output   MD4 checksum result
+ *
+ * \return         0 if successful
+ *
+ * \warning        MD4 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
-void mbedtls_md4_finish( mbedtls_md4_context *ctx, unsigned char output[16] );
+int mbedtls_md4_finish_ret( mbedtls_md4_context *ctx,
+                            unsigned char output[16] );
+
+/**
+ * \brief          MD4 process data block (internal use only)
+ *
+ * \param ctx      MD4 context
+ * \param data     buffer holding one block of data
+ *
+ * \return         0 if successful
+ *
+ * \warning        MD4 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
+ */
+int mbedtls_internal_md4_process( mbedtls_md4_context *ctx,
+                                  const unsigned char data[64] );
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED      __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+/**
+ * \brief          MD4 context setup
+ *
+ * \deprecated     Superseded by mbedtls_md4_starts_ret() in 2.7.0
+ *
+ * \param ctx      context to be initialized
+ *
+ * \warning        MD4 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_md4_starts(
+                                                    mbedtls_md4_context *ctx )
+{
+    mbedtls_md4_starts_ret( ctx );
+}
+
+/**
+ * \brief          MD4 process buffer
+ *
+ * \deprecated     Superseded by mbedtls_md4_update_ret() in 2.7.0
+ *
+ * \param ctx      MD4 context
+ * \param input    buffer holding the data
+ * \param ilen     length of the input data
+ *
+ * \warning        MD4 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_md4_update(
+                                                    mbedtls_md4_context *ctx,
+                                                    const unsigned char *input,
+                                                    size_t ilen )
+{
+    mbedtls_md4_update_ret( ctx, input, ilen );
+}
+
+/**
+ * \brief          MD4 final digest
+ *
+ * \deprecated     Superseded by mbedtls_md4_finish_ret() in 2.7.0
+ *
+ * \param ctx      MD4 context
+ * \param output   MD4 checksum result
+ *
+ * \warning        MD4 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_md4_finish(
+                                                    mbedtls_md4_context *ctx,
+                                                    unsigned char output[16] )
+{
+    mbedtls_md4_finish_ret( ctx, output );
+}
+
+/**
+ * \brief          MD4 process data block (internal use only)
+ *
+ * \deprecated     Superseded by mbedtls_internal_md4_process() in 2.7.0
+ *
+ * \param ctx      MD4 context
+ * \param data     buffer holding one block of data
+ *
+ * \warning        MD4 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_md4_process(
+                                                mbedtls_md4_context *ctx,
+                                                const unsigned char data[64] )
+{
+    mbedtls_internal_md4_process( ctx, data );
+}
+
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
 
 #ifdef __cplusplus
 }
@@ -113,22 +274,63 @@
 /**
  * \brief          Output = MD4( input buffer )
  *
- * \param input    buffer holding the  data
+ * \param input    buffer holding the data
  * \param ilen     length of the input data
  * \param output   MD4 checksum result
+ *
+ * \return         0 if successful
+ *
+ * \warning        MD4 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
-void mbedtls_md4( const unsigned char *input, size_t ilen, unsigned char output[16] );
+int mbedtls_md4_ret( const unsigned char *input,
+                     size_t ilen,
+                     unsigned char output[16] );
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED      __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+/**
+ * \brief          Output = MD4( input buffer )
+ *
+ * \deprecated     Superseded by mbedtls_md4_ret() in 2.7.0
+ *
+ * \param input    buffer holding the data
+ * \param ilen     length of the input data
+ * \param output   MD4 checksum result
+ *
+ * \warning        MD4 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_md4( const unsigned char *input,
+                                                   size_t ilen,
+                                                   unsigned char output[16] )
+{
+    mbedtls_md4_ret( input, ilen, output );
+}
+
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
 
 /**
  * \brief          Checkup routine
  *
  * \return         0 if successful, or 1 if the test failed
+ *
+ * \warning        MD4 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
 int mbedtls_md4_self_test( int verbose );
 
-/* Internal use */
-void mbedtls_md4_process( mbedtls_md4_context *ctx, const unsigned char data[64] );
-
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/mbedtls/md5.h b/include/mbedtls/md5.h
index 5a64061..d49391f 100644
--- a/include/mbedtls/md5.h
+++ b/include/mbedtls/md5.h
@@ -3,6 +3,11 @@
  *
  * \brief MD5 message digest algorithm (hash function)
  *
+ * \warning   MD5 is considered a weak message digest and its use constitutes a
+ *            security risk. We recommend considering stronger message
+ *            digests instead.
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
@@ -32,16 +37,28 @@
 #include <stddef.h>
 #include <stdint.h>
 
+#define MBEDTLS_ERR_MD5_HW_ACCEL_FAILED                   -0x002F  /**< MD5 hardware accelerator failed */
+
 #if !defined(MBEDTLS_MD5_ALT)
 // Regular implementation
 //
 
+#if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
+    !defined(inline) && !defined(__cplusplus)
+#define inline __inline
+#endif
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /**
  * \brief          MD5 context structure
+ *
+ * \warning        MD5 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
 typedef struct
 {
@@ -55,6 +72,11 @@
  * \brief          Initialize MD5 context
  *
  * \param ctx      MD5 context to be initialized
+ *
+ * \warning        MD5 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
 void mbedtls_md5_init( mbedtls_md5_context *ctx );
 
@@ -62,6 +84,11 @@
  * \brief          Clear MD5 context
  *
  * \param ctx      MD5 context to be cleared
+ *
+ * \warning        MD5 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
 void mbedtls_md5_free( mbedtls_md5_context *ctx );
 
@@ -70,6 +97,11 @@
  *
  * \param dst      The destination context
  * \param src      The context to be cloned
+ *
+ * \warning        MD5 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
 void mbedtls_md5_clone( mbedtls_md5_context *dst,
                         const mbedtls_md5_context *src );
@@ -78,28 +110,154 @@
  * \brief          MD5 context setup
  *
  * \param ctx      context to be initialized
+ *
+ * \return         0 if successful
+ *
+ * \warning        MD5 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
-void mbedtls_md5_starts( mbedtls_md5_context *ctx );
+int mbedtls_md5_starts_ret( mbedtls_md5_context *ctx );
 
 /**
  * \brief          MD5 process buffer
  *
  * \param ctx      MD5 context
- * \param input    buffer holding the  data
+ * \param input    buffer holding the data
  * \param ilen     length of the input data
+ *
+ * \return         0 if successful
+ *
+ * \warning        MD5 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
-void mbedtls_md5_update( mbedtls_md5_context *ctx, const unsigned char *input, size_t ilen );
+int mbedtls_md5_update_ret( mbedtls_md5_context *ctx,
+                            const unsigned char *input,
+                            size_t ilen );
 
 /**
  * \brief          MD5 final digest
  *
  * \param ctx      MD5 context
  * \param output   MD5 checksum result
+ *
+ * \return         0 if successful
+ *
+ * \warning        MD5 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
-void mbedtls_md5_finish( mbedtls_md5_context *ctx, unsigned char output[16] );
+int mbedtls_md5_finish_ret( mbedtls_md5_context *ctx,
+                            unsigned char output[16] );
 
-/* Internal use */
-void mbedtls_md5_process( mbedtls_md5_context *ctx, const unsigned char data[64] );
+/**
+ * \brief          MD5 process data block (internal use only)
+ *
+ * \param ctx      MD5 context
+ * \param data     buffer holding one block of data
+ *
+ * \return         0 if successful
+ *
+ * \warning        MD5 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
+ */
+int mbedtls_internal_md5_process( mbedtls_md5_context *ctx,
+                                  const unsigned char data[64] );
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED      __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+/**
+ * \brief          MD5 context setup
+ *
+ * \deprecated     Superseded by mbedtls_md5_starts_ret() in 2.7.0
+ *
+ * \param ctx      context to be initialized
+ *
+ * \warning        MD5 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_md5_starts(
+                                                    mbedtls_md5_context *ctx )
+{
+    mbedtls_md5_starts_ret( ctx );
+}
+
+/**
+ * \brief          MD5 process buffer
+ *
+ * \deprecated     Superseded by mbedtls_md5_update_ret() in 2.7.0
+ *
+ * \param ctx      MD5 context
+ * \param input    buffer holding the data
+ * \param ilen     length of the input data
+ *
+ * \warning        MD5 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_md5_update(
+                                                    mbedtls_md5_context *ctx,
+                                                    const unsigned char *input,
+                                                    size_t ilen )
+{
+    mbedtls_md5_update_ret( ctx, input, ilen );
+}
+
+/**
+ * \brief          MD5 final digest
+ *
+ * \deprecated     Superseded by mbedtls_md5_finish_ret() in 2.7.0
+ *
+ * \param ctx      MD5 context
+ * \param output   MD5 checksum result
+ *
+ * \warning        MD5 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_md5_finish(
+                                                    mbedtls_md5_context *ctx,
+                                                    unsigned char output[16] )
+{
+    mbedtls_md5_finish_ret( ctx, output );
+}
+
+/**
+ * \brief          MD5 process data block (internal use only)
+ *
+ * \deprecated     Superseded by mbedtls_internal_md5_process() in 2.7.0
+ *
+ * \param ctx      MD5 context
+ * \param data     buffer holding one block of data
+ *
+ * \warning        MD5 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_md5_process(
+                                                mbedtls_md5_context *ctx,
+                                                const unsigned char data[64] )
+{
+    mbedtls_internal_md5_process( ctx, data );
+}
+
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
 
 #ifdef __cplusplus
 }
@@ -116,16 +274,60 @@
 /**
  * \brief          Output = MD5( input buffer )
  *
- * \param input    buffer holding the  data
+ * \param input    buffer holding the data
  * \param ilen     length of the input data
  * \param output   MD5 checksum result
+ *
+ * \return         0 if successful
+ *
+ * \warning        MD5 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
-void mbedtls_md5( const unsigned char *input, size_t ilen, unsigned char output[16] );
+int mbedtls_md5_ret( const unsigned char *input,
+                     size_t ilen,
+                     unsigned char output[16] );
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED      __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+/**
+ * \brief          Output = MD5( input buffer )
+ *
+ * \deprecated     Superseded by mbedtls_md5_ret() in 2.7.0
+ *
+ * \param input    buffer holding the data
+ * \param ilen     length of the input data
+ * \param output   MD5 checksum result
+ *
+ * \warning        MD5 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_md5( const unsigned char *input,
+                                                   size_t ilen,
+                                                   unsigned char output[16] )
+{
+    mbedtls_md5_ret( input, ilen, output );
+}
+
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
 
 /**
  * \brief          Checkup routine
  *
  * \return         0 if successful, or 1 if the test failed
+ *
+ * \warning        MD5 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
 int mbedtls_md5_self_test( int verbose );
 
diff --git a/include/mbedtls/md_internal.h b/include/mbedtls/md_internal.h
index e2441bb..04de482 100644
--- a/include/mbedtls/md_internal.h
+++ b/include/mbedtls/md_internal.h
@@ -6,7 +6,8 @@
  * \warning This in an internal header. Do not include directly.
  *
  * \author Adriaan de Jong <dejong@fox-it.com>
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
@@ -58,17 +59,17 @@
     int block_size;
 
     /** Digest initialisation function */
-    void (*starts_func)( void *ctx );
+    int (*starts_func)( void *ctx );
 
     /** Digest update function */
-    void (*update_func)( void *ctx, const unsigned char *input, size_t ilen );
+    int (*update_func)( void *ctx, const unsigned char *input, size_t ilen );
 
     /** Digest finalisation function */
-    void (*finish_func)( void *ctx, unsigned char *output );
+    int (*finish_func)( void *ctx, unsigned char *output );
 
     /** Generic digest function */
-    void (*digest_func)( const unsigned char *input, size_t ilen,
-                         unsigned char *output );
+    int (*digest_func)( const unsigned char *input, size_t ilen,
+                        unsigned char *output );
 
     /** Allocate a new context */
     void * (*ctx_alloc_func)( void );
@@ -80,7 +81,7 @@
     void (*clone_func)( void *dst, const void *src );
 
     /** Internal use only */
-    void (*process_func)( void *ctx, const unsigned char *input );
+    int (*process_func)( void *ctx, const unsigned char *input );
 };
 
 #if defined(MBEDTLS_MD2_C)
diff --git a/include/mbedtls/memory_buffer_alloc.h b/include/mbedtls/memory_buffer_alloc.h
index d5df316..705f9a6 100644
--- a/include/mbedtls/memory_buffer_alloc.h
+++ b/include/mbedtls/memory_buffer_alloc.h
@@ -2,7 +2,8 @@
  * \file memory_buffer_alloc.h
  *
  * \brief Buffer-based memory allocator
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/net.h b/include/mbedtls/net.h
index 774559b..28ae821 100644
--- a/include/mbedtls/net.h
+++ b/include/mbedtls/net.h
@@ -3,6 +3,9 @@
  *
  * \brief Deprecated header file that includes mbedtls/net_sockets.h
  *
+ * \deprecated Superseded by mbedtls/net_sockets.h
+ */
+/*
  *  Copyright (C) 2006-2016, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
@@ -19,8 +22,6 @@
  *  limitations under the License.
  *
  *  This file is part of mbed TLS (https://tls.mbed.org)
- *
- * \deprecated Superseded by mbedtls/net_sockets.h
  */
 
 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
diff --git a/include/mbedtls/net_sockets.h b/include/mbedtls/net_sockets.h
index de33552..54e612c 100644
--- a/include/mbedtls/net_sockets.h
+++ b/include/mbedtls/net_sockets.h
@@ -2,7 +2,8 @@
  * \file net_sockets.h
  *
  * \brief Network communication functions
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/oid.h b/include/mbedtls/oid.h
index fcecdaf..bf2ef5e 100644
--- a/include/mbedtls/oid.h
+++ b/include/mbedtls/oid.h
@@ -2,7 +2,8 @@
  * \file oid.h
  *
  * \brief Object Identifier (OID) database
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/padlock.h b/include/mbedtls/padlock.h
index 2045a5a..677936e 100644
--- a/include/mbedtls/padlock.h
+++ b/include/mbedtls/padlock.h
@@ -3,7 +3,8 @@
  *
  * \brief VIA PadLock ACE for HW encryption/decryption supported by some
  *        processors
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/pem.h b/include/mbedtls/pem.h
index 54dc02d..2cf4c0a 100644
--- a/include/mbedtls/pem.h
+++ b/include/mbedtls/pem.h
@@ -2,7 +2,8 @@
  * \file pem.h
  *
  * \brief Privacy Enhanced Mail (PEM) decoding
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/pk.h b/include/mbedtls/pk.h
index f9f9b9b..1059bda 100644
--- a/include/mbedtls/pk.h
+++ b/include/mbedtls/pk.h
@@ -2,7 +2,8 @@
  * \file pk.h
  *
  * \brief Public Key abstraction layer
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
@@ -63,6 +64,7 @@
 #define MBEDTLS_ERR_PK_UNKNOWN_NAMED_CURVE -0x3A00  /**< Elliptic curve is unsupported (only NIST curves are supported). */
 #define MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE -0x3980  /**< Unavailable feature, e.g. RSA disabled for RSA key. */
 #define MBEDTLS_ERR_PK_SIG_LEN_MISMATCH    -0x3900  /**< The signature is valid but its length is less than expected. */
+#define MBEDTLS_ERR_PK_HW_ACCEL_FAILED     -0x3880  /**< PK hardware accelerator failed. */
 
 #ifdef __cplusplus
 extern "C" {
diff --git a/include/mbedtls/pk_internal.h b/include/mbedtls/pk_internal.h
index 01d0f21..3dae0fc 100644
--- a/include/mbedtls/pk_internal.h
+++ b/include/mbedtls/pk_internal.h
@@ -1,8 +1,9 @@
 /**
- * \file pk.h
+ * \file pk_internal.h
  *
  * \brief Public Key abstraction layer: wrapper functions
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/pkcs11.h b/include/mbedtls/pkcs11.h
index 2e88928..bf65c55 100644
--- a/include/mbedtls/pkcs11.h
+++ b/include/mbedtls/pkcs11.h
@@ -4,7 +4,8 @@
  * \brief Wrapper for PKCS#11 library libpkcs11-helper
  *
  * \author Adriaan de Jong <dejong@fox-it.com>
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/pkcs12.h b/include/mbedtls/pkcs12.h
index 9b2d904..a621ef5 100644
--- a/include/mbedtls/pkcs12.h
+++ b/include/mbedtls/pkcs12.h
@@ -2,7 +2,8 @@
  * \file pkcs12.h
  *
  * \brief PKCS#12 Personal Information Exchange Syntax
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/pkcs5.h b/include/mbedtls/pkcs5.h
index ec5cb9e..9a3c9fd 100644
--- a/include/mbedtls/pkcs5.h
+++ b/include/mbedtls/pkcs5.h
@@ -4,7 +4,8 @@
  * \brief PKCS#5 functions
  *
  * \author Mathias Olsson <mathias@kompetensum.com>
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/platform.h b/include/mbedtls/platform.h
index 35010f8..ed10775 100644
--- a/include/mbedtls/platform.h
+++ b/include/mbedtls/platform.h
@@ -1,9 +1,10 @@
 /**
  * \file platform.h
  *
- * \brief mbed TLS Platform abstraction layer
- *
- *  Copyright (C) 2006-2016, ARM Limited, All Rights Reserved
+ * \brief The Mbed TLS platform abstraction layer.
+ */
+/*
+ *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
@@ -18,7 +19,7 @@
  *  See the License for the specific language governing permissions and
  *  limitations under the License.
  *
- *  This file is part of mbed TLS (https://tls.mbed.org)
+ *  This file is part of Mbed TLS (https://tls.mbed.org)
  */
 #ifndef MBEDTLS_PLATFORM_H
 #define MBEDTLS_PLATFORM_H
@@ -51,34 +52,34 @@
 #include <time.h>
 #if !defined(MBEDTLS_PLATFORM_STD_SNPRINTF)
 #if defined(_WIN32)
-#define MBEDTLS_PLATFORM_STD_SNPRINTF   mbedtls_platform_win32_snprintf /**< Default snprintf to use  */
+#define MBEDTLS_PLATFORM_STD_SNPRINTF   mbedtls_platform_win32_snprintf /**< The default \c snprintf function to use.  */
 #else
-#define MBEDTLS_PLATFORM_STD_SNPRINTF   snprintf /**< Default snprintf to use  */
+#define MBEDTLS_PLATFORM_STD_SNPRINTF   snprintf /**< The default \c snprintf function to use.  */
 #endif
 #endif
 #if !defined(MBEDTLS_PLATFORM_STD_PRINTF)
-#define MBEDTLS_PLATFORM_STD_PRINTF   printf /**< Default printf to use  */
+#define MBEDTLS_PLATFORM_STD_PRINTF   printf /**< The default \c printf function to use. */
 #endif
 #if !defined(MBEDTLS_PLATFORM_STD_FPRINTF)
-#define MBEDTLS_PLATFORM_STD_FPRINTF fprintf /**< Default fprintf to use */
+#define MBEDTLS_PLATFORM_STD_FPRINTF fprintf /**< The default \c fprintf function to use. */
 #endif
 #if !defined(MBEDTLS_PLATFORM_STD_CALLOC)
-#define MBEDTLS_PLATFORM_STD_CALLOC   calloc /**< Default allocator to use */
+#define MBEDTLS_PLATFORM_STD_CALLOC   calloc /**< The default \c calloc function to use. */
 #endif
 #if !defined(MBEDTLS_PLATFORM_STD_FREE)
-#define MBEDTLS_PLATFORM_STD_FREE       free /**< Default free to use */
+#define MBEDTLS_PLATFORM_STD_FREE       free /**< The default \c free function to use. */
 #endif
 #if !defined(MBEDTLS_PLATFORM_STD_EXIT)
-#define MBEDTLS_PLATFORM_STD_EXIT      exit /**< Default exit to use */
+#define MBEDTLS_PLATFORM_STD_EXIT      exit /**< The default \c exit function to use. */
 #endif
 #if !defined(MBEDTLS_PLATFORM_STD_TIME)
-#define MBEDTLS_PLATFORM_STD_TIME       time    /**< Default time to use */
+#define MBEDTLS_PLATFORM_STD_TIME       time    /**< The default \c time function to use. */
 #endif
 #if !defined(MBEDTLS_PLATFORM_STD_EXIT_SUCCESS)
-#define MBEDTLS_PLATFORM_STD_EXIT_SUCCESS  EXIT_SUCCESS /**< Default exit value to use */
+#define MBEDTLS_PLATFORM_STD_EXIT_SUCCESS  EXIT_SUCCESS /**< The default exit value to use. */
 #endif
 #if !defined(MBEDTLS_PLATFORM_STD_EXIT_FAILURE)
-#define MBEDTLS_PLATFORM_STD_EXIT_FAILURE  EXIT_FAILURE /**< Default exit value to use */
+#define MBEDTLS_PLATFORM_STD_EXIT_FAILURE  EXIT_FAILURE /**< The default exit value to use. */
 #endif
 #if defined(MBEDTLS_FS_IO)
 #if !defined(MBEDTLS_PLATFORM_STD_NV_SEED_READ)
@@ -115,12 +116,12 @@
 extern void (*mbedtls_free)( void *ptr );
 
 /**
- * \brief   Set your own memory implementation function pointers
+ * \brief   This function allows configuring custom memory-management functions.
  *
- * \param calloc_func   the calloc function implementation
- * \param free_func     the free function implementation
+ * \param calloc_func   The \c calloc function implementation.
+ * \param free_func     The \c free function implementation.
  *
- * \return              0 if successful
+ * \return              \c 0.
  */
 int mbedtls_platform_set_calloc_free( void * (*calloc_func)( size_t, size_t ),
                               void (*free_func)( void * ) );
@@ -139,11 +140,11 @@
 extern int (*mbedtls_fprintf)( FILE *stream, const char *format, ... );
 
 /**
- * \brief   Set your own fprintf function pointer
+ * \brief   This function allows configuring a custom \p fprintf function pointer.
  *
- * \param fprintf_func   the fprintf function implementation
+ * \param fprintf_func   The \c fprintf function implementation.
  *
- * \return              0
+ * \return               \c 0.
  */
 int mbedtls_platform_set_fprintf( int (*fprintf_func)( FILE *stream, const char *,
                                                ... ) );
@@ -162,11 +163,12 @@
 extern int (*mbedtls_printf)( const char *format, ... );
 
 /**
- * \brief   Set your own printf function pointer
+ * \brief    This function allows configuring a custom \c printf function
+ *           pointer.
  *
- * \param printf_func   the printf function implementation
+ * \param printf_func   The \c printf function implementation.
  *
- * \return              0
+ * \return              \c 0 on success.
  */
 int mbedtls_platform_set_printf( int (*printf_func)( const char *, ... ) );
 #else /* !MBEDTLS_PLATFORM_PRINTF_ALT */
@@ -195,11 +197,12 @@
 extern int (*mbedtls_snprintf)( char * s, size_t n, const char * format, ... );
 
 /**
- * \brief   Set your own snprintf function pointer
+ * \brief   This function allows configuring a custom \c snprintf function
+ *          pointer.
  *
- * \param snprintf_func   the snprintf function implementation
+ * \param snprintf_func   The \c snprintf function implementation.
  *
- * \return              0
+ * \return    \c 0 on success.
  */
 int mbedtls_platform_set_snprintf( int (*snprintf_func)( char * s, size_t n,
                                                  const char * format, ... ) );
@@ -218,11 +221,12 @@
 extern void (*mbedtls_exit)( int status );
 
 /**
- * \brief   Set your own exit function pointer
+ * \brief   This function allows configuring a custom \c exit function
+ *          pointer.
  *
- * \param exit_func   the exit function implementation
+ * \param exit_func   The \c exit function implementation.
  *
- * \return              0
+ * \return  \c 0 on success.
  */
 int mbedtls_platform_set_exit( void (*exit_func)( int status ) );
 #else
@@ -265,12 +269,13 @@
 extern int (*mbedtls_nv_seed_write)( unsigned char *buf, size_t buf_len );
 
 /**
- * \brief   Set your own seed file writing/reading functions
+ * \brief   This function allows configuring custom seed file writing and
+ *          reading functions.
  *
- * \param   nv_seed_read_func   the seed reading function implementation
- * \param   nv_seed_write_func  the seed writing function implementation
+ * \param   nv_seed_read_func   The seed reading function implementation.
+ * \param   nv_seed_write_func  The seed writing function implementation.
  *
- * \return              0
+ * \return  \c 0 on success.
  */
 int mbedtls_platform_set_nv_seed(
             int (*nv_seed_read_func)( unsigned char *buf, size_t buf_len ),
@@ -291,13 +296,13 @@
 #if !defined(MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT)
 
 /**
- * \brief   Platform context structure
+ * \brief   The platform context structure.
  *
  * \note    This structure may be used to assist platform-specific
- *          setup/teardown operations.
+ *          setup or teardown operations.
  */
 typedef struct {
-    char dummy; /**< Placeholder member as empty structs are not portable */
+    char dummy; /**< Placeholder member, as empty structs are not portable. */
 }
 mbedtls_platform_context;
 
@@ -306,32 +311,32 @@
 #endif /* !MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT */
 
 /**
- * \brief   Perform any platform initialisation operations
+ * \brief   This function performs any platform initialization operations.
  *
- * \param   ctx     mbed TLS context
+ * \param   ctx     The Mbed TLS context.
  *
- * \return  0 if successful
+ * \return  \c 0 on success.
  *
- * \note    This function is intended to allow platform specific initialisation,
+ * \note    This function is intended to allow platform-specific initialization,
  *          and should be called before any other library functions. Its
- *          implementation is platform specific, and by default, unless platform
- *          specific code is provided, it does nothing.
+ *          implementation is platform-specific, and unless
+ *          platform-specific code is provided, it does nothing.
  *
- *          Its use and whether its necessary to be called is dependent on the
+ *          Its use and whether it is necessary to call it is dependent on the
  *          platform.
  */
 int mbedtls_platform_setup( mbedtls_platform_context *ctx );
 /**
- * \brief   Perform any platform teardown operations
+ * \brief   This function performs any platform teardown operations.
  *
- * \param   ctx     mbed TLS context
+ * \param   ctx     The Mbed TLS context.
  *
- * \note    This function should be called after every other mbed TLS module has
- *          been correctly freed using the appropriate free function.
- *          Its implementation is platform specific, and by default, unless
- *          platform specific code is provided, it does nothing.
+ * \note    This function should be called after every other Mbed TLS module
+ *          has been correctly freed using the appropriate free function.
+ *          Its implementation is platform-specific, and unless
+ *          platform-specific code is provided, it does nothing.
  *
- *          Its use and whether its necessary to be called is dependent on the
+ *          Its use and whether it is necessary to call it is dependent on the
  *          platform.
  */
 void mbedtls_platform_teardown( mbedtls_platform_context *ctx );
diff --git a/include/mbedtls/platform_time.h b/include/mbedtls/platform_time.h
index abb3431..2ed36f5 100644
--- a/include/mbedtls/platform_time.h
+++ b/include/mbedtls/platform_time.h
@@ -2,7 +2,8 @@
  * \file platform_time.h
  *
  * \brief mbed TLS Platform time abstraction
- *
+ */
+/*
  *  Copyright (C) 2006-2016, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/ripemd160.h b/include/mbedtls/ripemd160.h
index 7083fc8..c21868b 100644
--- a/include/mbedtls/ripemd160.h
+++ b/include/mbedtls/ripemd160.h
@@ -2,7 +2,8 @@
  * \file ripemd160.h
  *
  * \brief RIPE MD-160 message digest
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
@@ -32,6 +33,13 @@
 #include <stddef.h>
 #include <stdint.h>
 
+#define MBEDTLS_ERR_RIPEMD160_HW_ACCEL_FAILED             -0x0031  /**< RIPEMD160 hardware accelerator failed */
+
+#if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
+    !defined(inline) && !defined(__cplusplus)
+#define inline __inline
+#endif
+
 #if !defined(MBEDTLS_RIPEMD160_ALT)
 // Regular implementation
 //
@@ -78,36 +86,121 @@
  * \brief          RIPEMD-160 context setup
  *
  * \param ctx      context to be initialized
+ *
+ * \return         0 if successful
  */
-void mbedtls_ripemd160_starts( mbedtls_ripemd160_context *ctx );
+int mbedtls_ripemd160_starts_ret( mbedtls_ripemd160_context *ctx );
 
 /**
  * \brief          RIPEMD-160 process buffer
  *
  * \param ctx      RIPEMD-160 context
- * \param input    buffer holding the  data
+ * \param input    buffer holding the data
  * \param ilen     length of the input data
+ *
+ * \return         0 if successful
  */
-void mbedtls_ripemd160_update( mbedtls_ripemd160_context *ctx,
-                       const unsigned char *input, size_t ilen );
+int mbedtls_ripemd160_update_ret( mbedtls_ripemd160_context *ctx,
+                                  const unsigned char *input,
+                                  size_t ilen );
 
 /**
  * \brief          RIPEMD-160 final digest
  *
  * \param ctx      RIPEMD-160 context
  * \param output   RIPEMD-160 checksum result
+ *
+ * \return         0 if successful
  */
-void mbedtls_ripemd160_finish( mbedtls_ripemd160_context *ctx, unsigned char output[20] );
+int mbedtls_ripemd160_finish_ret( mbedtls_ripemd160_context *ctx,
+                                  unsigned char output[20] );
 
-/* Internal use */
-void mbedtls_ripemd160_process( mbedtls_ripemd160_context *ctx, const unsigned char data[64] );
+/**
+ * \brief          RIPEMD-160 process data block (internal use only)
+ *
+ * \param ctx      RIPEMD-160 context
+ * \param data     buffer holding one block of data
+ *
+ * \return         0 if successful
+ */
+int mbedtls_internal_ripemd160_process( mbedtls_ripemd160_context *ctx,
+                                        const unsigned char data[64] );
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED      __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+/**
+ * \brief          RIPEMD-160 context setup
+ *
+ * \deprecated     Superseded by mbedtls_ripemd160_starts_ret() in 2.7.0
+ *
+ * \param ctx      context to be initialized
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_ripemd160_starts(
+                                            mbedtls_ripemd160_context *ctx )
+{
+    mbedtls_ripemd160_starts_ret( ctx );
+}
+
+/**
+ * \brief          RIPEMD-160 process buffer
+ *
+ * \deprecated     Superseded by mbedtls_ripemd160_update_ret() in 2.7.0
+ *
+ * \param ctx      RIPEMD-160 context
+ * \param input    buffer holding the data
+ * \param ilen     length of the input data
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_ripemd160_update(
+                                                mbedtls_ripemd160_context *ctx,
+                                                const unsigned char *input,
+                                                size_t ilen )
+{
+    mbedtls_ripemd160_update_ret( ctx, input, ilen );
+}
+
+/**
+ * \brief          RIPEMD-160 final digest
+ *
+ * \deprecated     Superseded by mbedtls_ripemd160_finish_ret() in 2.7.0
+ *
+ * \param ctx      RIPEMD-160 context
+ * \param output   RIPEMD-160 checksum result
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_ripemd160_finish(
+                                                mbedtls_ripemd160_context *ctx,
+                                                unsigned char output[20] )
+{
+    mbedtls_ripemd160_finish_ret( ctx, output );
+}
+
+/**
+ * \brief          RIPEMD-160 process data block (internal use only)
+ *
+ * \deprecated     Superseded by mbedtls_internal_ripemd160_process() in 2.7.0
+ *
+ * \param ctx      RIPEMD-160 context
+ * \param data     buffer holding one block of data
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_ripemd160_process(
+                                            mbedtls_ripemd160_context *ctx,
+                                            const unsigned char data[64] )
+{
+    mbedtls_internal_ripemd160_process( ctx, data );
+}
+
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
 
 #ifdef __cplusplus
 }
 #endif
 
 #else  /* MBEDTLS_RIPEMD160_ALT */
-#include "ripemd160.h"
+#include "ripemd160_alt.h"
 #endif /* MBEDTLS_RIPEMD160_ALT */
 
 #ifdef __cplusplus
@@ -117,12 +210,41 @@
 /**
  * \brief          Output = RIPEMD-160( input buffer )
  *
- * \param input    buffer holding the  data
+ * \param input    buffer holding the data
+ * \param ilen     length of the input data
+ * \param output   RIPEMD-160 checksum result
+ *
+ * \return         0 if successful
+ */
+int mbedtls_ripemd160_ret( const unsigned char *input,
+                           size_t ilen,
+                           unsigned char output[20] );
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED      __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+/**
+ * \brief          Output = RIPEMD-160( input buffer )
+ *
+ * \deprecated     Superseded by mbedtls_ripemd160_ret() in 2.7.0
+ *
+ * \param input    buffer holding the data
  * \param ilen     length of the input data
  * \param output   RIPEMD-160 checksum result
  */
-void mbedtls_ripemd160( const unsigned char *input, size_t ilen,
-                unsigned char output[20] );
+MBEDTLS_DEPRECATED static inline void mbedtls_ripemd160(
+                                                    const unsigned char *input,
+                                                    size_t ilen,
+                                                    unsigned char output[20] )
+{
+    mbedtls_ripemd160_ret( input, ilen, output );
+}
+
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
 
 /**
  * \brief          Checkup routine
diff --git a/include/mbedtls/rsa.h b/include/mbedtls/rsa.h
index d7503ac..fb2f77f 100644
--- a/include/mbedtls/rsa.h
+++ b/include/mbedtls/rsa.h
@@ -1,9 +1,15 @@
 /**
  * \file rsa.h
  *
- * \brief The RSA public-key cryptosystem
+ * \brief The RSA public-key cryptosystem.
  *
- *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ * For more information, see <em>Public-Key Cryptography Standards (PKCS)
+ * #1 v1.5: RSA Encryption</em> and <em>Public-Key Cryptography Standards
+ * (PKCS) #1 v2.1: RSA Cryptography Specifications</em>.
+ *
+ */
+/*
+ *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
@@ -18,7 +24,7 @@
  *  See the License for the specific language governing permissions and
  *  limitations under the License.
  *
- *  This file is part of mbed TLS (https://tls.mbed.org)
+ *  This file is part of Mbed TLS (https://tls.mbed.org)
  */
 #ifndef MBEDTLS_RSA_H
 #define MBEDTLS_RSA_H
@@ -42,25 +48,26 @@
 #define MBEDTLS_ERR_RSA_BAD_INPUT_DATA                    -0x4080  /**< Bad input parameters to function. */
 #define MBEDTLS_ERR_RSA_INVALID_PADDING                   -0x4100  /**< Input data contains invalid padding and is rejected. */
 #define MBEDTLS_ERR_RSA_KEY_GEN_FAILED                    -0x4180  /**< Something failed during generation of a key. */
-#define MBEDTLS_ERR_RSA_KEY_CHECK_FAILED                  -0x4200  /**< Key failed to pass the library's validity check. */
+#define MBEDTLS_ERR_RSA_KEY_CHECK_FAILED                  -0x4200  /**< Key failed to pass the validity check of the library. */
 #define MBEDTLS_ERR_RSA_PUBLIC_FAILED                     -0x4280  /**< The public key operation failed. */
 #define MBEDTLS_ERR_RSA_PRIVATE_FAILED                    -0x4300  /**< The private key operation failed. */
 #define MBEDTLS_ERR_RSA_VERIFY_FAILED                     -0x4380  /**< The PKCS#1 verification failed. */
 #define MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE                  -0x4400  /**< The output buffer for decryption is not large enough. */
 #define MBEDTLS_ERR_RSA_RNG_FAILED                        -0x4480  /**< The random generator failed to generate non-zeros. */
-#define MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION             -0x4500  /**< The implementation doesn't offer the requested operation, e.g. because of security violations or lack of functionality */
+#define MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION             -0x4500  /**< The implementation does not offer the requested operation, for example, because of security violations or lack of functionality. */
+#define MBEDTLS_ERR_RSA_HW_ACCEL_FAILED                   -0x4580  /**< RSA hardware accelerator failed. */
 
 /*
  * RSA constants
  */
-#define MBEDTLS_RSA_PUBLIC      0
-#define MBEDTLS_RSA_PRIVATE     1
+#define MBEDTLS_RSA_PUBLIC      0 /**< Request private key operation. */
+#define MBEDTLS_RSA_PRIVATE     1 /**< Request public key operation. */
 
-#define MBEDTLS_RSA_PKCS_V15    0
-#define MBEDTLS_RSA_PKCS_V21    1
+#define MBEDTLS_RSA_PKCS_V15    0 /**< Use PKCS-1 v1.5 encoding. */
+#define MBEDTLS_RSA_PKCS_V21    1 /**< Use PKCS-1 v2.1 encoding. */
 
-#define MBEDTLS_RSA_SIGN        1
-#define MBEDTLS_RSA_CRYPT       2
+#define MBEDTLS_RSA_SIGN        1 /**< Identifier for RSA signature operations. */
+#define MBEDTLS_RSA_CRYPT       2 /**< Identifier for RSA encryption and decryption operations. */
 
 #define MBEDTLS_RSA_SALT_LEN_ANY    -1
 
@@ -78,103 +85,106 @@
 #endif
 
 /**
- * \brief   RSA context structure
+ * \brief   The RSA context structure.
  *
  * \note    Direct manipulation of the members of this structure
- *          is deprecated and will no longer be supported starting
- *          from the next major release. All manipulation should instead
- *          be done through the public interface functions.
- *
+ *          is deprecated. All manipulation should instead be done through
+ *          the public interface functions.
  */
 typedef struct
 {
-    int ver;                    /*!<  always 0          */
-    size_t len;                 /*!<  size(N) in chars  */
+    int ver;                    /*!<  Always 0.*/
+    size_t len;                 /*!<  The size of \p N in Bytes. */
 
-    mbedtls_mpi N;                      /*!<  public modulus    */
-    mbedtls_mpi E;                      /*!<  public exponent   */
+    mbedtls_mpi N;                      /*!<  The public modulus. */
+    mbedtls_mpi E;                      /*!<  The public exponent. */
 
-    mbedtls_mpi D;                      /*!<  private exponent  */
-    mbedtls_mpi P;                      /*!<  1st prime factor  */
-    mbedtls_mpi Q;                      /*!<  2nd prime factor  */
+    mbedtls_mpi D;                      /*!<  The private exponent. */
+    mbedtls_mpi P;                      /*!<  The first prime factor. */
+    mbedtls_mpi Q;                      /*!<  The second prime factor. */
 
-    mbedtls_mpi DP;                     /*!<  D % (P - 1)       */
-    mbedtls_mpi DQ;                     /*!<  D % (Q - 1)       */
+    mbedtls_mpi DP;                     /*!<  \p D % (P - 1)       */
+    mbedtls_mpi DQ;                     /*!<  \p D % (Q - 1)       */
     mbedtls_mpi QP;                     /*!<  1 / (Q % P)       */
 
-    mbedtls_mpi RN;                     /*!<  cached R^2 mod N  */
+    mbedtls_mpi RN;                     /*!<  cached R^2 mod \p N  */
 
-    mbedtls_mpi RP;                     /*!<  cached R^2 mod P  */
-    mbedtls_mpi RQ;                     /*!<  cached R^2 mod Q  */
+    mbedtls_mpi RP;                     /*!<  cached R^2 mod \p P  */
+    mbedtls_mpi RQ;                     /*!<  cached R^2 mod \p Q  */
 
-    mbedtls_mpi Vi;                     /*!<  cached blinding value     */
-    mbedtls_mpi Vf;                     /*!<  cached un-blinding value  */
+    mbedtls_mpi Vi;                     /*!<  The cached blinding value. */
+    mbedtls_mpi Vf;                     /*!<  The cached un-blinding value. */
 
-    int padding;                /*!<  \c MBEDTLS_RSA_PKCS_V15 for 1.5 padding and
-                                      \c MBEDTLS_RSA_PKCS_v21 for OAEP/PSS */
-    int hash_id;                /*!<  Hash identifier of mbedtls_md_type_t as
-                                      specified in the mbedtls_md.h header file
-                                      for the EME-OAEP and EMSA-PSS
-                                      encoding                          */
+    int padding;                /*!< Selects padding mode:
+                                     #MBEDTLS_RSA_PKCS_V15 for 1.5 padding and
+                                     #MBEDTLS_RSA_PKCS_V21 for OAEP or PSS. */
+    int hash_id;                /*!< Hash identifier of mbedtls_md_type_t type,
+                                     as specified in md.h for use in the MGF
+                                     mask generating function used in the
+                                     EME-OAEP and EMSA-PSS encodings. */
 #if defined(MBEDTLS_THREADING_C)
-    mbedtls_threading_mutex_t mutex;    /*!<  Thread-safety mutex       */
+    mbedtls_threading_mutex_t mutex;    /*!<  Thread-safety mutex. */
 #endif
 }
 mbedtls_rsa_context;
 
 /**
- * \brief          Initialize an RSA context
+ * \brief          This function initializes an RSA context.
  *
- *                 Note: Set padding to \c MBEDTLS_RSA_PKCS_V21 for the RSAES-OAEP
+ * \note           Set padding to #MBEDTLS_RSA_PKCS_V21 for the RSAES-OAEP
  *                 encryption scheme and the RSASSA-PSS signature scheme.
  *
- * \param ctx      RSA context to be initialized
- * \param padding  \c MBEDTLS_RSA_PKCS_V15 or \c MBEDTLS_RSA_PKCS_V21
- * \param hash_id  \c MBEDTLS_RSA_PKCS_V21 hash identifier
+ * \param ctx      The RSA context to initialize.
+ * \param padding  Selects padding mode: #MBEDTLS_RSA_PKCS_V15 or
+ *                 #MBEDTLS_RSA_PKCS_V21.
+ * \param hash_id  The hash identifier of #mbedtls_md_type_t type, if
+ *                 \p padding is #MBEDTLS_RSA_PKCS_V21.
  *
- * \note           The hash_id parameter is actually ignored
- *                 when using \c MBEDTLS_RSA_PKCS_V15 padding.
+ * \note           The \p hash_id parameter is ignored when using
+ *                 #MBEDTLS_RSA_PKCS_V15 padding.
  *
- * \note           Choice of padding mode is strictly enforced for private key
+ * \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's merely
+ *                 mixing padding modes. For public key operations it is
  *                 a default value, which can be overriden by calling specific
- *                 rsa_rsaes_xxx or rsa_rsassa_xxx functions.
+ *                 \c rsa_rsaes_xxx or \c rsa_rsassa_xxx functions.
  *
- * \note           The chosen hash is always used for OEAP encryption.
- *                 For PSS signatures, it's always used for making signatures,
- *                 but can be overriden (and always is, if set to
- *                 \c MBEDTLS_MD_NONE) for verifying them.
+ * \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.
  */
 void mbedtls_rsa_init( mbedtls_rsa_context *ctx,
                        int padding,
                        int hash_id);
 
 /**
- * \brief          Import a set of core parameters into an RSA context
+ * \brief          This function imports a set of core parameters into an
+ *                 RSA context.
  *
- * \param ctx      Initialized RSA context to store parameters
- * \param N        RSA modulus, or NULL
- * \param P        First prime factor of N, or NULL
- * \param Q        Second prime factor of N, or NULL
- * \param D        Private exponent, or NULL
- * \param E        Public exponent, or NULL
+ * \param ctx      The initialized RSA context to store the parameters in.
+ * \param N        The RSA modulus, or NULL.
+ * \param P        The first prime factor of \p N, or NULL.
+ * \param Q        The second prime factor of \p N, or NULL.
+ * \param D        The private exponent, or NULL.
+ * \param E        The public exponent, or NULL.
  *
  * \note           This function can be called multiple times for successive
- *                 imports if the parameters are not simultaneously present.
+ *                 imports, if the parameters are not simultaneously present.
+ *
  *                 Any sequence of calls to this function should be followed
- *                 by a call to \c mbedtls_rsa_complete which will check
- *                 and complete the provided information to a ready-for-use
+ *                 by a call to mbedtls_rsa_complete(), which checks and
+ *                 completes the provided information to a ready-for-use
  *                 public or private RSA key.
  *
- * \note           See the documentation of \c mbedtls_rsa_complete for more
- *                 information on which parameters are necessary to setup
- *                 a private or public RSA key.
+ * \note           See mbedtls_rsa_complete() for more information on which
+ *                 parameters are necessary to set up a private or public
+ *                 RSA key.
  *
  * \note           The imported parameters are copied and need not be preserved
  *                 for the lifetime of the RSA context being set up.
  *
- * \return         0 if successful, non-zero error code on failure.
+ * \return         \c 0 on success, or a non-zero error code on failure.
  */
 int mbedtls_rsa_import( mbedtls_rsa_context *ctx,
                         const mbedtls_mpi *N,
@@ -182,36 +192,37 @@
                         const mbedtls_mpi *D, const mbedtls_mpi *E );
 
 /**
- * \brief          Import core RSA parameters in raw big-endian
- *                 binary format into an RSA context
+ * \brief          This function imports core RSA parameters, in raw big-endian
+ *                 binary format, into an RSA context.
  *
- * \param ctx      Initialized RSA context to store parameters
- * \param N        RSA modulus, or NULL
- * \param N_len    Byte length of N, ignored if N == NULL
- * \param P        First prime factor of N, or NULL
- * \param P_len    Byte length of P, ignored if P == NULL
- * \param Q        Second prime factor of N, or NULL
- * \param Q_len    Byte length of Q, ignored if Q == NULL
- * \param D        Private exponent, or NULL
- * \param D_len    Byte length of D, ignored if D == NULL
- * \param E        Public exponent, or NULL
- * \param E_len    Byte length of E, ignored if E == NULL
+ * \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.
  *
  * \note           This function can be called multiple times for successive
- *                 imports if the parameters are not simultaneously present.
+ *                 imports, if the parameters are not simultaneously present.
+ *
  *                 Any sequence of calls to this function should be followed
- *                 by a call to \c mbedtls_rsa_complete which will check
- *                 and complete the provided information to a ready-for-use
+ *                 by a call to mbedtls_rsa_complete(), which checks and
+ *                 completes the provided information to a ready-for-use
  *                 public or private RSA key.
  *
- * \note           See the documentation of \c mbedtls_rsa_complete for more
- *                 information on which parameters are necessary to setup
- *                 a private or public RSA key.
+ * \note           See mbedtls_rsa_complete() for more information on which
+ *                 parameters are necessary to set up a private or public
+ *                 RSA key.
  *
  * \note           The imported parameters are copied and need not be preserved
  *                 for the lifetime of the RSA context being set up.
  *
- * \return         0 if successful, non-zero error code on failure.
+ * \return         \c 0 on success, or a non-zero error code on failure.
  */
 int mbedtls_rsa_import_raw( mbedtls_rsa_context *ctx,
                             unsigned char const *N, size_t N_len,
@@ -221,71 +232,71 @@
                             unsigned char const *E, size_t E_len );
 
 /**
- * \brief          Attempt to complete an RSA context from
+ * \brief          This function completes an RSA context from
  *                 a set of imported core parameters.
  *
- * \param ctx      Initialized RSA context to store parameters
+ *                 To setup an RSA public key, precisely \p N and \p E
+ *                 must have been imported.
  *
- * \note
- *                 - To setup an RSA public key, precisely N and E
- *                   must have been imported.
+ *                 To setup an RSA private key, sufficient information must
+ *                 be present for the other parameters to be derivable.
  *
- *                 - To setup an RSA private key, enough information must be
- *                   present for the other parameters to be derivable.
+ *                 The default implementation supports the following:
+ *                 <ul><li>Derive \p P, \p Q from \p N, \p D, \p E.</li>
+ *                 <li>Derive \p N, \p D from \p P, \p Q, \p E.</li></ul>
+ *                 Alternative implementations need not support these.
  *
- *                   The default implementation supports the following:
- *                     - Derive P, Q from N, D, E
- *                     - Derive N, D from P, Q, E.
+ *                 If this function runs successfully, it guarantees that
+ *                 the RSA context can be used for RSA operations without
+ *                 the risk of failure or crash.
  *
- *                 - Alternative implementations need not support these
- *                   and may return \c MBEDTLS_ERR_RSA_BAD_INPUT_DATA instead.
+ * \param ctx      The initialized RSA context holding imported parameters.
  *
- * \return
- *                 - 0 if successful. In this case, it is guaranteed
- *                   that the RSA context can be used for RSA operations
- *                   without the risk of failure or crash.
- *                 - \c MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the attempted
- *                   derivations failed.
+ * \return         \c 0 on success, or #MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the
+ *                 attempted derivations failed.
  *
  * \warning        This function need not perform consistency checks
- *                 for the imported parameters! In particular, parameters that
- *                 are not needed by the implementation may be silently discarded
- *                 and left unchecked. For the purpose of checking the consistency
- *                 of the key material, see \c mbedtls_rsa_check_privkey.
+ *                 for the imported parameters. In particular, parameters that
+ *                 are not needed by the implementation might be silently
+ *                 discarded and left unchecked. To check the consistency
+ *                 of the key material, see mbedtls_rsa_check_privkey().
  *
  */
 int mbedtls_rsa_complete( mbedtls_rsa_context *ctx );
 
 /**
- * \brief          Export core parameters of an RSA key
+ * \brief          This function exports the core parameters of an RSA key.
  *
- * \param ctx      Initialized RSA context
- * \param N        MPI to hold the RSA modulus, or NULL
- * \param P        MPI to hold the first prime factor of N, or NULL
- * \param Q        MPI to hold the second prime factor of N, or NULL
- * \param D        MPI to hold the private exponent, or NULL
- * \param E        MPI to hold the public exponent, or NULL
+ *                 If this function runs successfully, the non-NULL buffers
+ *                 pointed to by \p N, \p P, \p Q, \p D, and \p E are fully
+ *                 written, with additional unused space filled leading by
+ *                 zero Bytes.
  *
- * \return
- *                 - 0 if successful. In this case, the non-NULL buffers
- *                   pointed to by N, P, Q, D, E are fully written, with
- *                   additional unused space filled leading by 0-bytes.
- *                 - Non-zero return code otherwise. In particular, if
- *                   exporting the requested parameters
- *                   cannot be done because of a lack of functionality
- *                   or because of security policies, the error code
- *                   \c MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION is returned.
- *                   In this case, the RSA context stays intact and can
- *                   be continued to be used.
+ *                 Possible reasons for returning
+ *                 #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION:<ul>
+ *                 <li>An alternative RSA implementation is in use, which
+ *                 stores the key externally, and either cannot or should
+ *                 not export it into RAM.</li>
+ *                 <li>A SW or HW implementation might not support a certain
+ *                 deduction. For example, \p P, \p Q from \p N, \p D,
+ *                 and \p E if the former are not part of the
+ *                 implementation.</li></ul>
  *
- * \note           Reasons for returning \c MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION
- *                 would be the following: Firstly, it might be that an
- *                 alternative RSA implementation is in use which stores
- *                 the key externally, and which either cannot or should not
- *                 export it into RAM. Alternatively, an implementation
- *                 (regardless of SW or HW) might not support deducing e.g.
- *                 P, Q from N, D, E if the former are not part of the
- *                 implementation.
+ *                 If the function fails due to an unsupported operation,
+ *                 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.
+ *
+ * \return         \c 0 on success,
+ *                 #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the
+ *                 requested parameters cannot be done due to missing
+ *                 functionality or because of security policies,
+ *                 or a non-zero return code on any other failure.
  *
  */
 int mbedtls_rsa_export( const mbedtls_rsa_context *ctx,
@@ -293,46 +304,48 @@
                         mbedtls_mpi *D, mbedtls_mpi *E );
 
 /**
- * \brief          Export core parameters of an RSA key
- *                 in raw big-endian binary format
+ * \brief          This function exports core parameters of an RSA key
+ *                 in raw big-endian binary format.
  *
- * \param ctx      Initialized RSA context
- * \param N        Byte array to store the RSA modulus, or NULL
- * \param N_len    Size of buffer for modulus
- * \param P        Byte array to hold the first prime factor of N, or NULL
- * \param P_len    Size of buffer for first prime factor
- * \param Q        Byte array to hold the second prime factor of N, or NULL
- * \param Q_len    Size of buffer for second prime factor
- * \param D        Byte array to hold the private exponent, or NULL
- * \param D_len    Size of buffer for private exponent
- * \param E        Byte array to hold the public exponent, or NULL
- * \param E_len    Size of buffer for public exponent
+ *                 If this function runs successfully, the non-NULL buffers
+ *                 pointed to by \p N, \p P, \p Q, \p D, and \p E are fully
+ *                 written, with additional unused space filled leading by
+ *                 zero Bytes.
+ *
+ *                 Possible reasons for returning
+ *                 #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION:<ul>
+ *                 <li>An alternative RSA implementation is in use, which
+ *                 stores the key externally, and either cannot or should
+ *                 not export it into RAM.</li>
+ *                 <li>A SW or HW implementation might not support a certain
+ *                 deduction. For example, \p P, \p Q from \p N, \p D,
+ *                 and \p E if the former are not part of the
+ *                 implementation.</li></ul>
+ *                 If the function fails due to an unsupported operation,
+ *                 the RSA context stays intact and remains usable.
+ *
+ * \param ctx      The initialized RSA context.
+ * \param N        The Byte array to store the RSA modulus, or NULL.
+ * \param N_len    The size of the buffer for the modulus.
+ * \param P        The Byte array to hold the first prime factor of \p N, or
+ *                 NULL.
+ * \param P_len    The size of the buffer for the first prime factor.
+ * \param Q        The Byte array to hold the second prime factor of \p N, or
+                   NULL.
+ * \param Q_len    The size of the buffer for the second prime factor.
+ * \param D        The Byte array to hold the private exponent, or NULL.
+ * \param D_len    The size of the buffer for the private exponent.
+ * \param E        The Byte array to hold the public exponent, or NULL.
+ * \param E_len    The size of the buffer for the public exponent.
  *
  * \note           The length fields are ignored if the corresponding
  *                 buffer pointers are NULL.
  *
- * \return
- *                 - 0 if successful. In this case, the non-NULL buffers
- *                   pointed to by N, P, Q, D, E are fully written, with
- *                   additional unused space filled leading by 0-bytes.
- *                 - Non-zero return code otherwise. In particular, if
- *                   exporting the requested parameters
- *                   cannot be done because of a lack of functionality
- *                   or because of security policies, the error code
- *                   \c MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION is returned.
- *                   In this case, the RSA context stays intact and can
- *                   be continued to be used.
- *
- * \note           Reasons for returning \c MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION
- *                 would be the following: Firstly, it might be that an
- *                 alternative RSA implementation is in use which stores
- *                 the key externally, and which either cannot or should not
- *                 export it into RAM. Alternatively, an implementation
- *                 (regardless of SW or HW) might not support deducing e.g.
- *                 P, Q from N, D, E if the former are not part of the
- *                 implementation.
- *
- *
+ * \return         \c 0 on success,
+ *                 #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the
+ *                 requested parameters cannot be done due to missing
+ *                 functionality or because of security policies,
+ *                 or a non-zero return code on any other failure.
  */
 int mbedtls_rsa_export_raw( const mbedtls_rsa_context *ctx,
                             unsigned char *N, size_t N_len,
@@ -342,57 +355,59 @@
                             unsigned char *E, size_t E_len );
 
 /**
- * \brief          Export CRT parameters of a private RSA key
+ * \brief          This function exports CRT parameters of a private RSA key.
  *
- * \param ctx      Initialized RSA context
- * \param DP       MPI to hold D modulo P-1, or NULL
- * \param DQ       MPI to hold D modulo Q-1, or NULL
- * \param QP       MPI to hold modular inverse of Q modulo P, or NULL
+ * \param ctx      The initialized RSA context.
+ * \param DP       The MPI to hold D modulo P-1, or NULL.
+ * \param DQ       The MPI to hold D modulo Q-1, or NULL.
+ * \param QP       The MPI to hold modular inverse of Q modulo P, or NULL.
  *
- * \return         0 if successful, non-zero error code otherwise.
+ * \return         \c 0 on success, non-zero error code otherwise.
  *
  * \note           Alternative RSA implementations not using CRT-parameters
- *                 internally can implement this function using based on
- *                 \c mbedtls_rsa_deduce_opt.
+ *                 internally can implement this function based on
+ *                 mbedtls_rsa_deduce_opt().
  *
  */
 int mbedtls_rsa_export_crt( const mbedtls_rsa_context *ctx,
                             mbedtls_mpi *DP, mbedtls_mpi *DQ, mbedtls_mpi *QP );
 
 /**
- * \brief          Set padding for an already initialized RSA context
- *                 See \c mbedtls_rsa_init() for details.
+ * \brief          This function sets padding for an already initialized RSA
+ *                 context. See mbedtls_rsa_init() for details.
  *
- * \param ctx      RSA context to be set
- * \param padding  \c MBEDTLS_RSA_PKCS_V15 or \c MBEDTLS_RSA_PKCS_V21
- * \param hash_id  \c MBEDTLS_RSA_PKCS_V21 hash identifier
+ * \param ctx      The RSA context to be set.
+ * \param padding  Selects padding mode: #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);
 
 /**
- * \brief          Get length of RSA modulus in bytes
+ * \brief          This function retrieves the length of RSA modulus in Bytes.
  *
- * \param ctx      Initialized RSA context
+ * \param ctx      The initialized RSA context.
  *
- * \return         Length of RSA modulus, in bytes.
+ * \return         The length of the RSA modulus in Bytes.
  *
  */
 size_t mbedtls_rsa_get_len( const mbedtls_rsa_context *ctx );
 
 /**
- * \brief          Generate an RSA keypair
+ * \brief          This function generates an RSA keypair.
  *
- * \param ctx      RSA context that will hold the key
- * \param f_rng    RNG function
- * \param p_rng    RNG parameter
- * \param nbits    size of the public key in bits
- * \param exponent public exponent (e.g., 65537)
+ * \param ctx      The RSA context used to hold the key.
+ * \param f_rng    The RNG function.
+ * \param p_rng    The RNG parameter.
+ * \param nbits    The size of the public key in bits.
+ * \param exponent The public exponent. For example, 65537.
  *
- * \note           mbedtls_rsa_init() must be called beforehand to setup
- *                 the RSA context.
+ * \note           mbedtls_rsa_init() must be called before this function,
+ *                 to set up the RSA context.
  *
- * \return         0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+                   on failure.
  */
 int mbedtls_rsa_gen_key( mbedtls_rsa_context *ctx,
                          int (*f_rng)(void *, unsigned char *, size_t),
@@ -400,101 +415,109 @@
                          unsigned int nbits, int exponent );
 
 /**
- * \brief          Check if a context contains (at least) an RSA public key
+ * \brief          This function checks if a context contains at least an RSA
+ *                 public key.
  *
- * \param ctx      RSA context to be checked
+ *                 If the function runs successfully, it is guaranteed that
+ *                 enough information is present to perform an RSA public key
+ *                 operation using mbedtls_rsa_public().
  *
- * \return         0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code.
- *                 On success, it is guaranteed that enough information is
- *                 present to perform an RSA public key operation
- *                 \c mbedtls_rsa_public.
+ * \param ctx      The RSA context to check.
+ *
+ * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
  */
 int mbedtls_rsa_check_pubkey( const mbedtls_rsa_context *ctx );
 
 /**
- * \brief      Check if a context contains an RSA private key
+ * \brief      This function checks if a context contains an RSA private key
  *             and perform basic consistency checks.
  *
- * \param ctx  RSA context to be checked
+ * \param ctx  The RSA context to check.
  *
- * \return     0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code.
+ * \return     \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code on
+ *             failure.
  *
  * \note       The consistency checks performed by this function not only
- *             ensure that \c mbedtls_rsa_private can be called successfully
+ *             ensure that mbedtls_rsa_private() can be called successfully
  *             on the given context, but that the various parameters are
  *             mutually consistent with high probability, in the sense that
- *             \c mbedtls_rsa_public and \c mbedtls_rsa_private are inverses.
+ *             mbedtls_rsa_public() and mbedtls_rsa_private() are inverses.
  *
  * \warning    This function should catch accidental misconfigurations
  *             like swapping of parameters, but it cannot establish full
  *             trust in neither the quality nor the consistency of the key
  *             material that was used to setup the given RSA context:
- *             - Regarding consistency, note (see \c mbedtls_rsa_complete)
- *               that imported parameters irrelevant for the implementation
- *               might be silently dropped, in which case the present
- *               function doesn't have access to and hence cannot check them.
- *               If you want to check the consistency of the entire
- *               content of, say, an PKCS1-encoded RSA private key, you
- *               should use \c mbedtls_rsa_validate_params before setting
- *               up the RSA context.
- *               Further, if the implementation performs empirical checks,
- *               these checks will substantiate but not guarantee consistency.
- *             - Regarding quality, this function is not expected to perform
- *               extended quality assessments like checking that the prime
- *               factors are safe. Further, it is the user's responsibility to
- *               ensure trustworthiness of the source of his RSA parameters,
- *               a question going beyond what's effectively checkable
- *               by the library.
- *
+ *             <ul><li>Consistency: Imported parameters that are irrelevant
+ *             for the implementation might be silently dropped. If dropped,
+ *             the current function does not have access to them,
+ *             and therefore cannot check them. See mbedtls_rsa_complete().
+ *             If you want to check the consistency of the entire
+ *             content of an PKCS1-encoded RSA private key, for example, you
+ *             should use mbedtls_rsa_validate_params() before setting
+ *             up the RSA context.
+ *             Additionally, if the implementation performs empirical checks,
+ *             these checks substantiate but do not guarantee consistency.</li>
+ *             <li>Quality: This function is not expected to perform
+ *             extended quality assessments like checking that the prime
+ *             factors are safe. Additionally, it is the responsibility of the
+ *             user to ensure the trustworthiness of the source of his RSA
+ *             parameters, which goes beyond what is effectively checkable
+ *             by the library.</li></ul>
  */
 int mbedtls_rsa_check_privkey( const mbedtls_rsa_context *ctx );
 
 /**
- * \brief          Check a public-private RSA key pair.
- *                 Check each of the contexts, and make sure they match.
+ * \brief          This function checks a public-private RSA key pair.
  *
- * \param pub      RSA context holding the public key
- * \param prv      RSA context holding the private key
+ *                 It checks each of the contexts, and makes sure they match.
  *
- * \return         0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \param pub      The RSA context holding the public key.
+ * \param prv      The RSA context holding the private key.
+ *
+ * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  */
 int mbedtls_rsa_check_pub_priv( const mbedtls_rsa_context *pub,
                                 const mbedtls_rsa_context *prv );
 
 /**
- * \brief          Do an RSA public key operation
+ * \brief          This function performs an RSA public key operation.
  *
- * \param ctx      RSA context
- * \param input    input buffer
- * \param output   output buffer
+ * \param ctx      The RSA context.
+ * \param input    The input buffer.
+ * \param output   The output buffer.
  *
- * \return         0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
- * \note           This function does NOT take care of message
- *                 padding. Also, be sure to set input[0] = 0 or ensure that
- *                 input is smaller than N.
+ * \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 (eg. 128 bytes if RSA-1024 is used).
+ *                 enough. For example, 128 Bytes if RSA-1024 is used.
  */
 int mbedtls_rsa_public( mbedtls_rsa_context *ctx,
                 const unsigned char *input,
                 unsigned char *output );
 
 /**
- * \brief          Do an RSA private key operation
+ * \brief          This function performs an RSA private key operation.
  *
- * \param ctx      RSA context
- * \param f_rng    RNG function (Needed for blinding)
- * \param p_rng    RNG parameter
- * \param input    input buffer
- * \param output   output buffer
+ * \param ctx      The RSA context.
+ * \param f_rng    The RNG function. Needed for blinding.
+ * \param p_rng    The RNG parameter.
+ * \param input    The input buffer.
+ * \param output   The output buffer.
  *
- * \return         0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
  * \note           The input and output buffers must be large
- *                 enough (eg. 128 bytes if RSA-1024 is used).
+ *                 enough. For example, 128 Bytes if RSA-1024 is used.
  */
 int mbedtls_rsa_private( mbedtls_rsa_context *ctx,
                  int (*f_rng)(void *, unsigned char *, size_t),
@@ -503,32 +526,36 @@
                  unsigned char *output );
 
 /**
- * \brief          Generic wrapper to perform a PKCS#1 encryption using the
- *                 mode from the context. Add the message padding, then do an
- *                 RSA operation.
+ * \brief          This function adds the message padding, then performs an RSA
+ *                 operation.
  *
- * \param ctx      RSA context
- * \param f_rng    RNG function (Needed for padding and PKCS#1 v2.1 encoding
- *                               and \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng    RNG parameter
- * \param mode     \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param ilen     contains the plaintext length
- * \param input    buffer holding the data to be encrypted
- * \param output   buffer that will hold the ciphertext
+ *                 It is the generic wrapper for performing a PKCS#1 encryption
+ *                 operation using the \p mode from the context.
+ *
+ *
+ * \param ctx      The RSA context.
+ * \param f_rng    The RNG function. Needed for padding, PKCS#1 v2.1
+ *                 encoding, and #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng    The RNG parameter.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param ilen     The length of the plaintext.
+ * \param input    The buffer holding the data to encrypt.
+ * \param output   The buffer used to hold the ciphertext.
  *
  * \deprecated     It is deprecated and discouraged to call this function
- *                 in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary
- *                 are likely to remove the mode argument and have it implicitly
- *                 set to MBEDTLS_RSA_PUBLIC.
+ *                 in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
+ *                 are likely to remove the \p mode argument and have it
+ *                 implicitly set to #MBEDTLS_RSA_PUBLIC.
  *
  * \note           Alternative implementations of RSA need not support
- *                 mode being set to MBEDTLS_RSA_PRIVATE and may instead
- *                 return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *                 mode being set to #MBEDTLS_RSA_PRIVATE and might instead
+ *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
- * \note           The output buffer must be as large as the size
- *                 of ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \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.
  */
 int mbedtls_rsa_pkcs1_encrypt( mbedtls_rsa_context *ctx,
                        int (*f_rng)(void *, unsigned char *, size_t),
@@ -538,29 +565,32 @@
                        unsigned char *output );
 
 /**
- * \brief          Perform a PKCS#1 v1.5 encryption (RSAES-PKCS1-v1_5-ENCRYPT)
+ * \brief          This function performs a PKCS#1 v1.5 encryption operation
+ *                 (RSAES-PKCS1-v1_5-ENCRYPT).
  *
- * \param ctx      RSA context
- * \param f_rng    RNG function (Needed for padding and \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng    RNG parameter
- * \param mode     \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param ilen     contains the plaintext length
- * \param input    buffer holding the data to be encrypted
- * \param output   buffer that will hold the ciphertext
+ * \param ctx      The RSA context.
+ * \param f_rng    The RNG function. Needed for padding and
+ *                 #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng    The RNG parameter.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param ilen     The length of the plaintext.
+ * \param input    The buffer holding the data to encrypt.
+ * \param output   The buffer used to hold the ciphertext.
  *
  * \deprecated     It is deprecated and discouraged to call this function
- *                 in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary
- *                 are likely to remove the mode argument and have it implicitly
- *                 set to MBEDTLS_RSA_PUBLIC.
+ *                 in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
+ *                 are likely to remove the \p mode argument and have it
+ *                 implicitly set to #MBEDTLS_RSA_PUBLIC.
  *
  * \note           Alternative implementations of RSA need not support
- *                 mode being set to MBEDTLS_RSA_PRIVATE and may instead
- *                 return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *                 mode being set to #MBEDTLS_RSA_PRIVATE and might instead
+ *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
  * \note           The output buffer must be as large as the size
- *                 of ctx->N (eg. 128 bytes if RSA-1024 is used).
+ *                 of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
  */
 int mbedtls_rsa_rsaes_pkcs1_v15_encrypt( mbedtls_rsa_context *ctx,
                                  int (*f_rng)(void *, unsigned char *, size_t),
@@ -570,32 +600,34 @@
                                  unsigned char *output );
 
 /**
- * \brief          Perform a PKCS#1 v2.1 OAEP encryption (RSAES-OAEP-ENCRYPT)
+ * \brief            This function performs a PKCS#1 v2.1 OAEP encryption
+ *                   operation (RSAES-OAEP-ENCRYPT).
  *
- * \param ctx      RSA context
- * \param f_rng    RNG function (Needed for padding and PKCS#1 v2.1 encoding
- *                               and \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng    RNG parameter
- * \param mode     \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param label    buffer holding the custom label to use
- * \param label_len contains the label length
- * \param ilen     contains the plaintext length
- * \param input    buffer holding the data to be encrypted
- * \param output   buffer that will hold the ciphertext
+ * \param ctx        The RSA context.
+ * \param f_rng      The RNG function. Needed for padding and PKCS#1 v2.1
+ *                   encoding and #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng      The RNG parameter.
+ * \param mode       #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param label      The buffer holding the custom label to use.
+ * \param label_len  The length of the label.
+ * \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.
  *
  * \deprecated     It is deprecated and discouraged to call this function
- *                 in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary
- *                 are likely to remove the mode argument and have it implicitly
- *                 set to MBEDTLS_RSA_PUBLIC.
+ *                 in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
+ *                 are likely to remove the \p mode argument and have it
+ *                 implicitly set to #MBEDTLS_RSA_PUBLIC.
  *
  * \note           Alternative implementations of RSA need not support
- *                 mode being set to MBEDTLS_RSA_PRIVATE and may instead
- *                 return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *                 mode being set to #MBEDTLS_RSA_PRIVATE and might instead
+ *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
  * \note           The output buffer must be as large as the size
- *                 of ctx->N (eg. 128 bytes if RSA-1024 is used).
+ *                 of ctx->N. For example, 128 Bytes if RSA-1024 is used.
  */
 int mbedtls_rsa_rsaes_oaep_encrypt( mbedtls_rsa_context *ctx,
                             int (*f_rng)(void *, unsigned char *, size_t),
@@ -607,39 +639,42 @@
                             unsigned char *output );
 
 /**
- * \brief          Generic wrapper to perform a PKCS#1 decryption using the
- *                 mode from the context. Do an RSA operation, then remove
- *                 the message padding
+ * \brief          This function performs an RSA operation, then removes the
+ *                 message padding.
  *
- * \param ctx      RSA context
- * \param f_rng    RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng    RNG parameter
- * \param mode     \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param olen     will contain the plaintext length
- * \param input    buffer holding the encrypted data
- * \param output   buffer that will hold the plaintext
- * \param output_max_len    maximum length of the output buffer
+ *                 It is the generic wrapper for performing a PKCS#1 decryption
+ *                 operation using the \p mode from the context.
+ *
+ * \param ctx      The RSA context.
+ * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng    The RNG parameter.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param olen     The length of the plaintext.
+ * \param input    The buffer holding the encrypted data.
+ * \param output   The buffer used to hold the plaintext.
+ * \param output_max_len    The maximum length of the output buffer.
  *
  * \deprecated     It is deprecated and discouraged to call this function
- *                 in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary
- *                 are likely to remove the mode argument and have it implicitly
- *                 set to MBEDTLS_RSA_PRIVATE.
+ *                 in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
+ *                 are likely to remove the \p mode argument and have it
+ *                 implicitly set to #MBEDTLS_RSA_PRIVATE.
  *
  * \note           Alternative implementations of RSA need not support
- *                 mode being set to MBEDTLS_RSA_PUBLIC and may instead
- *                 return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *                 mode being set to #MBEDTLS_RSA_PUBLIC and might instead
+ *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
  * \note           The output buffer length \c output_max_len should be
- *                 as large as the size \c ctx->len of \c ctx->N (eg. 128 bytes
- *                 if RSA-1024 is used) to be able to hold an arbitrary
- *                 decrypted message. If it is not large enough to hold
- *                 the decryption of the particular ciphertext provided,
- *                 the function will return \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
+ *                 as large as the size \p ctx->len of \p ctx->N (for example,
+ *                 128 Bytes if RSA-1024 is used) to be able to hold an
+ *                 arbitrary decrypted message. If it is not large enough to
+ *                 hold the decryption of the particular ciphertext provided,
+ *                 the function returns \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
  *
  * \note           The input buffer must be as large as the size
- *                 of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
+ *                 of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
  */
 int mbedtls_rsa_pkcs1_decrypt( mbedtls_rsa_context *ctx,
                        int (*f_rng)(void *, unsigned char *, size_t),
@@ -650,37 +685,39 @@
                        size_t output_max_len );
 
 /**
- * \brief          Perform a PKCS#1 v1.5 decryption (RSAES-PKCS1-v1_5-DECRYPT)
+ * \brief          This function performs a PKCS#1 v1.5 decryption
+ *                 operation (RSAES-PKCS1-v1_5-DECRYPT).
  *
- * \param ctx      RSA context
- * \param f_rng    RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng    RNG parameter
- * \param mode     \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param olen     will contain the plaintext length
- * \param input    buffer holding the encrypted data
- * \param output   buffer that will hold the plaintext
- * \param output_max_len    maximum length of the output buffer
+ * \param ctx      The RSA context.
+ * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng    The RNG parameter.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param olen     The length of the plaintext.
+ * \param input    The buffer holding the encrypted data.
+ * \param output   The buffer to hold the plaintext.
+ * \param output_max_len    The maximum length of the output buffer.
  *
  * \deprecated     It is deprecated and discouraged to call this function
- *                 in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary
- *                 are likely to remove the mode argument and have it implicitly
- *                 set to MBEDTLS_RSA_PRIVATE.
+ *                 in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
+ *                 are likely to remove the \p mode argument and have it
+ *                 implicitly set to #MBEDTLS_RSA_PRIVATE.
  *
  * \note           Alternative implementations of RSA need not support
- *                 mode being set to MBEDTLS_RSA_PUBLIC and may instead
- *                 return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *                 mode being set to #MBEDTLS_RSA_PUBLIC and might instead
+ *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
  * \note           The output buffer length \c output_max_len should be
- *                 as large as the size \c ctx->len of \c ctx->N (eg. 128 bytes
- *                 if RSA-1024 is used) to be able to hold an arbitrary
- *                 decrypted message. If it is not large enough to hold
- *                 the decryption of the particular ciphertext provided,
- *                 the function will return \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
+ *                 as large as the size \p ctx->len of \p ctx->N, for example,
+ *                 128 Bytes if RSA-1024 is used, to be able to hold an
+ *                 arbitrary decrypted message. If it is not large enough to
+ *                 hold the decryption of the particular ciphertext provided,
+ *                 the function returns #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
  *
  * \note           The input buffer must be as large as the size
- *                 of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
+ *                 of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
  */
 int mbedtls_rsa_rsaes_pkcs1_v15_decrypt( mbedtls_rsa_context *ctx,
                                  int (*f_rng)(void *, unsigned char *, size_t),
@@ -691,40 +728,42 @@
                                  size_t output_max_len );
 
 /**
- * \brief          Perform a PKCS#1 v2.1 OAEP decryption (RSAES-OAEP-DECRYPT)
+ * \brief          This function performs a PKCS#1 v2.1 OAEP decryption
+ *                 operation (RSAES-OAEP-DECRYPT).
  *
- * \param ctx      RSA context
- * \param f_rng    RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng    RNG parameter
- * \param mode     \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param label    buffer holding the custom label to use
- * \param label_len contains the label length
- * \param olen     will contain the plaintext length
- * \param input    buffer holding the encrypted data
- * \param output   buffer that will hold the plaintext
- * \param output_max_len    maximum length of the output buffer
+ * \param ctx        The RSA context.
+ * \param f_rng      The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng      The RNG parameter.
+ * \param mode       #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param 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.
  *
  * \deprecated     It is deprecated and discouraged to call this function
- *                 in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary
- *                 are likely to remove the mode argument and have it implicitly
- *                 set to MBEDTLS_RSA_PRIVATE.
+ *                 in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
+ *                 are likely to remove the \p mode argument and have it
+ *                 implicitly set to #MBEDTLS_RSA_PRIVATE.
  *
  * \note           Alternative implementations of RSA need not support
- *                 mode being set to MBEDTLS_RSA_PUBLIC and may instead
- *                 return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *                 mode being set to #MBEDTLS_RSA_PUBLIC and might instead
+ *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
  * \note           The output buffer length \c output_max_len should be
- *                 as large as the size \c ctx->len of \c ctx->N (eg. 128 bytes
- *                 if RSA-1024 is used) to be able to hold an arbitrary
- *                 decrypted message. If it is not large enough to hold
- *                 the decryption of the particular ciphertext provided,
- *                 the function will return \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
+ *                 as large as the size \p ctx->len of \p ctx->N, for
+ *                 example, 128 Bytes if RSA-1024 is used, to be able to
+ *                 hold an arbitrary decrypted message. If it is not
+ *                 large enough to hold the decryption of the particular
+ *                 ciphertext provided, the function returns
+ *                 #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
  *
  * \note           The input buffer must be as large as the size
- *                 of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
- *
+ *                 of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
  */
 int mbedtls_rsa_rsaes_oaep_decrypt( mbedtls_rsa_context *ctx,
                             int (*f_rng)(void *, unsigned char *, size_t),
@@ -737,39 +776,41 @@
                             size_t output_max_len );
 
 /**
- * \brief          Generic wrapper to perform a PKCS#1 signature using the
- *                 mode from the context. Do a private RSA operation to sign
- *                 a message digest
+ * \brief          This function performs a private RSA operation to sign
+ *                 a message digest using PKCS#1.
  *
- * \param ctx      RSA context
- * \param f_rng    RNG function (Needed for PKCS#1 v2.1 encoding and for
- *                               \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng    RNG parameter
- * \param mode     \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param md_alg   a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE for
- *                 signing raw data)
- * \param hashlen  message digest length (for \c MBEDTLS_MD_NONE only)
- * \param hash     buffer holding the message digest
- * \param sig      buffer that will hold the ciphertext
+ *                 It is the generic wrapper for performing a PKCS#1
+ *                 signature using the \p mode from the context.
+ *
+ * \param ctx      The RSA context.
+ * \param f_rng    The RNG function. Needed for PKCS#1 v2.1 encoding and for
+ *                 #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng    The RNG parameter.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param md_alg   The message-digest algorithm used to hash the original data.
+ *                 Use #MBEDTLS_MD_NONE for signing raw data.
+ * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash     The buffer holding the message digest.
+ * \param sig      The buffer to hold the ciphertext.
  *
  * \deprecated     It is deprecated and discouraged to call this function
- *                 in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary
- *                 are likely to remove the mode argument and have it implicitly
- *                 set to MBEDTLS_RSA_PRIVATE.
+ *                 in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
+ *                 are likely to remove the \p mode argument and have it
+ *                 implicitly set to #MBEDTLS_RSA_PRIVATE.
  *
  * \note           Alternative implementations of RSA need not support
- *                 mode being set to MBEDTLS_RSA_PUBLIC and may instead
- *                 return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *                 mode being set to #MBEDTLS_RSA_PUBLIC and might instead
+ *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         0 if the signing operation was successful,
- *                 or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return         \c 0 if the signing operation was successful,
+ *                 or an \c MBEDTLS_ERR_RSA_XXX error code on failure.
  *
- * \note           The \c sig buffer must be as large as the size
- *                 of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \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           In case of PKCS#1 v2.1 encoding, see comments on
- *                 \c mbedtls_rsa_rsassa_pss_sign() for details on
- *                 \c md_alg and \c hash_id.
+ * \note           For PKCS#1 v2.1 encoding, see comments on
+ *                 mbedtls_rsa_rsassa_pss_sign() for details on
+ *                 \p md_alg and \p hash_id.
  */
 int mbedtls_rsa_pkcs1_sign( mbedtls_rsa_context *ctx,
                     int (*f_rng)(void *, unsigned char *, size_t),
@@ -781,32 +822,34 @@
                     unsigned char *sig );
 
 /**
- * \brief          Perform a PKCS#1 v1.5 signature (RSASSA-PKCS1-v1_5-SIGN)
+ * \brief          This function performs a PKCS#1 v1.5 signature
+ *                 operation (RSASSA-PKCS1-v1_5-SIGN).
  *
- * \param ctx      RSA context
- * \param f_rng    RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng    RNG parameter
- * \param mode     \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param md_alg   a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE
- *                 for signing raw data)
- * \param hashlen  message digest length (for \c MBEDTLS_MD_NONE only)
- * \param hash     buffer holding the message digest
- * \param sig      buffer that will hold the ciphertext
+ * \param ctx      The RSA context.
+ * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng    The RNG parameter.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param md_alg   The message-digest algorithm used to hash the original data.
+ *                 Use #MBEDTLS_MD_NONE for signing raw data.
+ * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash     The buffer holding the message digest.
+ * \param sig      The buffer to hold the ciphertext.
  *
  * \deprecated     It is deprecated and discouraged to call this function
- *                 in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary
- *                 are likely to remove the mode argument and have it implicitly
- *                 set to MBEDTLS_RSA_PRIVATE.
+ *                 in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
+ *                 are likely to remove the \p mode argument and have it
+ *                 implicitly set to #MBEDTLS_RSA_PRIVATE.
  *
  * \note           Alternative implementations of RSA need not support
- *                 mode being set to MBEDTLS_RSA_PUBLIC and may instead
- *                 return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *                 mode being set to #MBEDTLS_RSA_PUBLIC and might instead
+ *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         0 if the signing operation was successful,
+ * \return         \c 0 if the signing operation was successful,
  *                 or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
- * \note           The \c sig buffer must be as large as the size
- *                 of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \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.
  */
 int mbedtls_rsa_rsassa_pkcs1_v15_sign( mbedtls_rsa_context *ctx,
                                int (*f_rng)(void *, unsigned char *, size_t),
@@ -818,38 +861,42 @@
                                unsigned char *sig );
 
 /**
- * \brief          Perform a PKCS#1 v2.1 PSS signature (RSASSA-PSS-SIGN)
+ * \brief          This function performs a PKCS#1 v2.1 PSS signature
+ *                 operation (RSASSA-PSS-SIGN).
  *
- * \param ctx      RSA context
- * \param f_rng    RNG function (Needed for PKCS#1 v2.1 encoding and for
- *                               \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng    RNG parameter
- * \param mode     \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param md_alg   a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE
- *                 for signing raw data)
- * \param hashlen  message digest length (for \c MBEDTLS_MD_NONE only)
- * \param hash     buffer holding the message digest
- * \param sig      buffer that will hold the ciphertext
+ * \param ctx      The RSA context.
+ * \param f_rng    The RNG function. Needed for PKCS#1 v2.1 encoding and for
+ *                 #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng    The RNG parameter.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param md_alg   The message-digest algorithm used to hash the original data.
+ *                 Use #MBEDTLS_MD_NONE for signing raw data.
+ * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash     The buffer holding the message digest.
+ * \param sig      The buffer to hold the ciphertext.
  *
  * \deprecated     It is deprecated and discouraged to call this function
- *                 in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary
- *                 are likely to remove the mode argument and have it implicitly
- *                 set to MBEDTLS_RSA_PRIVATE.
+ *                 in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
+ *                 are likely to remove the \p mode argument and have it
+ *                 implicitly set to #MBEDTLS_RSA_PRIVATE.
  *
  * \note           Alternative implementations of RSA need not support
- *                 mode being set to MBEDTLS_RSA_PUBLIC and may instead
- *                 return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *                 mode being set to #MBEDTLS_RSA_PUBLIC and might instead
+ *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         0 if the signing operation was successful,
+ * \return         \c 0 if the signing operation was successful,
  *                 or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
- * \note           The \c sig buffer must be as large as the size
- *                 of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \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 \c hash_id in the RSA context is the one used for the
- *                 encoding. \c md_alg in the function call is the type of hash
- *                 that is encoded. According to RFC 3447 it is advised to
- *                 keep both hashes the same.
+ * \note           The \p hash_id in the RSA context is the one used for the
+ *                 encoding. \p md_alg in the function call is the type of hash
+ *                 that is encoded. According to <em>RFC-3447: Public-Key
+ *                 Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography
+ *                 Specifications</em> it is advised to keep both hashes the
+ *                 same.
  */
 int mbedtls_rsa_rsassa_pss_sign( mbedtls_rsa_context *ctx,
                          int (*f_rng)(void *, unsigned char *, size_t),
@@ -861,36 +908,41 @@
                          unsigned char *sig );
 
 /**
- * \brief          Generic wrapper to perform a PKCS#1 verification using the
- *                 mode from the context. Do a public RSA operation and check
- *                 the message digest
+ * \brief          This function performs a public RSA operation and checks
+ *                 the message digest.
  *
- * \param ctx      points to an RSA public key
- * \param f_rng    RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng    RNG parameter
- * \param mode     \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param md_alg   a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE for signing raw data)
- * \param hashlen  message digest length (for \c MBEDTLS_MD_NONE only)
- * \param hash     buffer holding the message digest
- * \param sig      buffer holding the ciphertext
+ *                 This is the generic wrapper for performing a PKCS#1
+ *                 verification using the mode from the context.
+ *
+ * \param ctx      The RSA public key context.
+ * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng    The RNG parameter.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param md_alg   The message-digest algorithm used to hash the original data.
+ *                 Use #MBEDTLS_MD_NONE for signing raw data.
+ * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash     The buffer holding the message digest.
+ * \param sig      The buffer holding the ciphertext.
  *
  * \deprecated     It is deprecated and discouraged to call this function
- *                 in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary
- *                 are likely to remove the mode argument and have it implicitly
- *                 set to MBEDTLS_RSA_PUBLIC.
+ *                 in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
+ *                 are likely to remove the \p mode argument and have it
+ *                 set to #MBEDTLS_RSA_PUBLIC.
  *
  * \note           Alternative implementations of RSA need not support
- *                 mode being set to MBEDTLS_RSA_PRIVATE and may instead
- *                 return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *                 mode being set to #MBEDTLS_RSA_PRIVATE and might instead
+ *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         0 if the verify operation was successful,
+ * \return         \c 0 if the verify operation was successful,
  *                 or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
- * \note           The \c sig buffer must be as large as the size
- *                 of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \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           In case of PKCS#1 v2.1 encoding, see comments on
- *                 \c mbedtls_rsa_rsassa_pss_verify() about md_alg and hash_id.
+ * \note           For PKCS#1 v2.1 encoding, see comments on
+ *                 mbedtls_rsa_rsassa_pss_verify() about \p md_alg and
+ *                 \p hash_id.
  */
 int mbedtls_rsa_pkcs1_verify( mbedtls_rsa_context *ctx,
                       int (*f_rng)(void *, unsigned char *, size_t),
@@ -902,32 +954,34 @@
                       const unsigned char *sig );
 
 /**
- * \brief          Perform a PKCS#1 v1.5 verification (RSASSA-PKCS1-v1_5-VERIFY)
+ * \brief          This function performs a PKCS#1 v1.5 verification
+ *                 operation (RSASSA-PKCS1-v1_5-VERIFY).
  *
- * \param ctx      points to an RSA public key
- * \param f_rng    RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng    RNG parameter
- * \param mode     \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param md_alg   a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE
- *                 for signing raw data)
- * \param hashlen  message digest length (for \c MBEDTLS_MD_NONE only)
- * \param hash     buffer holding the message digest
- * \param sig      buffer holding the ciphertext
+ * \param ctx      The RSA public key context.
+ * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng    The RNG parameter.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param md_alg   The message-digest algorithm used to hash the original data.
+ *                 Use #MBEDTLS_MD_NONE for signing raw data.
+ * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash     The buffer holding the message digest.
+ * \param sig      The buffer holding the ciphertext.
  *
  * \deprecated     It is deprecated and discouraged to call this function
- *                 in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary
- *                 are likely to remove the mode argument and have it implicitly
- *                 set to MBEDTLS_RSA_PUBLIC.
+ *                 in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
+ *                 are likely to remove the \p mode argument and have it
+ *                 set to #MBEDTLS_RSA_PUBLIC.
  *
  * \note           Alternative implementations of RSA need not support
- *                 mode being set to MBEDTLS_RSA_PRIVATE and may instead
- *                 return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *                 mode being set to #MBEDTLS_RSA_PRIVATE and might instead
+ *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         0 if the verify operation was successful,
+ * \return         \c 0 if the verify operation was successful,
  *                 or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
- * \note           The \c sig buffer must be as large as the size
- *                 of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \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.
  */
 int mbedtls_rsa_rsassa_pkcs1_v15_verify( mbedtls_rsa_context *ctx,
                                  int (*f_rng)(void *, unsigned char *, size_t),
@@ -939,38 +993,45 @@
                                  const unsigned char *sig );
 
 /**
- * \brief          Perform a PKCS#1 v2.1 PSS verification (RSASSA-PSS-VERIFY)
- *                 (This is the "simple" version.)
+ * \brief          This function performs a PKCS#1 v2.1 PSS verification
+ *                 operation (RSASSA-PSS-VERIFY).
  *
- * \param ctx      points to an RSA public key
- * \param f_rng    RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng    RNG parameter
- * \param mode     \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param md_alg   a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE for signing raw data)
- * \param hashlen  message digest length (for \c MBEDTLS_MD_NONE only)
- * \param hash     buffer holding the message digest
- * \param sig      buffer holding the ciphertext
+ *                 The hash function for the MGF mask generating function
+ *                 is that specified in the RSA context.
+ *
+ * \param ctx      The RSA public key context.
+ * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng    The RNG parameter.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param md_alg   The message-digest algorithm used to hash the original data.
+ *                 Use #MBEDTLS_MD_NONE for signing raw data.
+ * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash     The buffer holding the message digest.
+ * \param sig      The buffer holding the ciphertext.
  *
  * \deprecated     It is deprecated and discouraged to call this function
- *                 in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary
- *                 are likely to remove the mode argument and have it implicitly
- *                 set to MBEDTLS_RSA_PUBLIC.
+ *                 in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
+ *                 are likely to remove the \p mode argument and have it
+ *                 implicitly set to #MBEDTLS_RSA_PUBLIC.
  *
  * \note           Alternative implementations of RSA need not support
- *                 mode being set to MBEDTLS_RSA_PRIVATE and may instead
- *                 return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *                 mode being set to #MBEDTLS_RSA_PRIVATE and might instead
+ *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         0 if the verify operation was successful,
+ * \return         \c 0 if the verify operation was successful,
  *                 or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
- * \note           The \c sig buffer must be as large as the size
- *                 of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \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 \c hash_id in the RSA context is the one used for the
- *                 verification. \c md_alg in the function call is the type of
- *                 hash that is verified. According to RFC 3447 it is advised to
- *                 keep both hashes the same. If \c hash_id in the RSA context is
- *                 unset, the \c md_alg from the function call 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
+ *                 Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography
+ *                 Specifications</em> it is advised to keep both hashes the
+ *                 same. If \p hash_id in the RSA context is unset,
+ *                 the \p md_alg from the function call is used.
  */
 int mbedtls_rsa_rsassa_pss_verify( mbedtls_rsa_context *ctx,
                            int (*f_rng)(void *, unsigned char *, size_t),
@@ -982,28 +1043,33 @@
                            const unsigned char *sig );
 
 /**
- * \brief          Perform a PKCS#1 v2.1 PSS verification (RSASSA-PSS-VERIFY)
- *                 (This is the version with "full" options.)
+ * \brief          This function performs a PKCS#1 v2.1 PSS verification
+ *                 operation (RSASSA-PSS-VERIFY).
  *
- * \param ctx      points to an RSA public key
- * \param f_rng    RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng    RNG parameter
- * \param mode     \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param md_alg   a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE for signing raw data)
- * \param hashlen  message digest length (for \c MBEDTLS_MD_NONE only)
- * \param hash     buffer holding the message digest
- * \param mgf1_hash_id message digest used for mask generation
- * \param expected_salt_len Length of the salt used in padding, use
- *                 \c MBEDTLS_RSA_SALT_LEN_ANY to accept any salt length
- * \param sig      buffer holding the ciphertext
+ *                 The hash function for the MGF mask generating function
+ *                 is that specified in \p mgf1_hash_id.
  *
- * \return         0 if the verify operation was successful,
+ * \param ctx      The RSA public key context.
+ * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng    The RNG parameter.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param md_alg   The message-digest algorithm used to hash the original data.
+ *                 Use #MBEDTLS_MD_NONE for signing raw data.
+ * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash     The buffer holding the message digest.
+ * \param mgf1_hash_id The message digest used for mask generation.
+ * \param expected_salt_len The length of the salt used in padding. Use
+ *                 #MBEDTLS_RSA_SALT_LEN_ANY to accept any salt length.
+ * \param sig      The buffer holding the ciphertext.
+ *
+ * \return         \c 0 if the verify operation was successful,
  *                 or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
- * \note           The \c sig buffer must be as large as the size
- *                 of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \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 \c hash_id in the RSA context is ignored.
+ * \note           The \p hash_id in the RSA context is ignored.
  */
 int mbedtls_rsa_rsassa_pss_verify_ext( mbedtls_rsa_context *ctx,
                                int (*f_rng)(void *, unsigned char *, size_t),
@@ -1017,20 +1083,20 @@
                                const unsigned char *sig );
 
 /**
- * \brief          Copy the components of an RSA context
+ * \brief          This function copies the components of an RSA context.
  *
- * \param dst      Destination context
- * \param src      Source context
+ * \param dst      The destination context.
+ * \param src      The source context.
  *
- * \return         0 on success,
- *                 \c MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure
+ * \return         \c 0 on success,
+ *                 #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure.
  */
 int mbedtls_rsa_copy( mbedtls_rsa_context *dst, const mbedtls_rsa_context *src );
 
 /**
- * \brief          Free the components of an RSA key
+ * \brief          This function frees the components of an RSA key.
  *
- * \param ctx      RSA Context to free
+ * \param ctx      The RSA Context to free.
  */
 void mbedtls_rsa_free( mbedtls_rsa_context *ctx );
 
@@ -1047,9 +1113,9 @@
 #endif
 
 /**
- * \brief          Checkup routine
+ * \brief          The RSA checkup routine.
  *
- * \return         0 if successful, or 1 if the test failed
+ * \return         \c 0 on success, or \c 1 on failure.
  */
 int mbedtls_rsa_self_test( int verbose );
 
diff --git a/include/mbedtls/rsa_internal.h b/include/mbedtls/rsa_internal.h
index 7e6a2ec..bcb3c94 100644
--- a/include/mbedtls/rsa_internal.h
+++ b/include/mbedtls/rsa_internal.h
@@ -2,7 +2,8 @@
  * \file rsa_internal.h
  *
  * \brief Context-independent RSA helper functions
- *
+ */
+/*
  *  Copyright (C) 2006-2017, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/sha1.h b/include/mbedtls/sha1.h
index 7a67c6c..e4f8650 100644
--- a/include/mbedtls/sha1.h
+++ b/include/mbedtls/sha1.h
@@ -1,9 +1,14 @@
 /**
  * \file sha1.h
  *
- * \brief SHA-1 cryptographic hash function
+ * \brief The SHA-1 cryptographic hash function.
  *
- *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ * \warning   SHA-1 is considered a weak message digest and its use constitutes
+ *            a security risk. We recommend considering stronger message
+ *            digests instead.
+ */
+/*
+ *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
@@ -18,7 +23,7 @@
  *  See the License for the specific language governing permissions and
  *  limitations under the License.
  *
- *  This file is part of mbed TLS (https://tls.mbed.org)
+ *  This file is part of Mbed TLS (https://tls.mbed.org)
  */
 #ifndef MBEDTLS_SHA1_H
 #define MBEDTLS_SHA1_H
@@ -32,6 +37,13 @@
 #include <stddef.h>
 #include <stdint.h>
 
+#define MBEDTLS_ERR_SHA1_HW_ACCEL_FAILED                  -0x0035  /**< SHA-1 hardware accelerator failed */
+
+#if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
+    !defined(inline) && !defined(__cplusplus)
+#define inline __inline
+#endif
+
 #if !defined(MBEDTLS_SHA1_ALT)
 // Regular implementation
 //
@@ -41,65 +53,213 @@
 #endif
 
 /**
- * \brief          SHA-1 context structure
+ * \brief          The SHA-1 context structure.
+ *
+ * \warning        SHA-1 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
 typedef struct
 {
-    uint32_t total[2];          /*!< number of bytes processed  */
-    uint32_t state[5];          /*!< intermediate digest state  */
-    unsigned char buffer[64];   /*!< data block being processed */
+    uint32_t total[2];          /*!< The number of Bytes processed.  */
+    uint32_t state[5];          /*!< The intermediate digest state.  */
+    unsigned char buffer[64];   /*!< The data block being processed. */
 }
 mbedtls_sha1_context;
 
 /**
- * \brief          Initialize SHA-1 context
+ * \brief          This function initializes a SHA-1 context.
  *
- * \param ctx      SHA-1 context to be initialized
+ * \param ctx      The SHA-1 context to initialize.
+ *
+ * \warning        SHA-1 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
 void mbedtls_sha1_init( mbedtls_sha1_context *ctx );
 
 /**
- * \brief          Clear SHA-1 context
+ * \brief          This function clears a SHA-1 context.
  *
- * \param ctx      SHA-1 context to be cleared
+ * \param ctx      The SHA-1 context to clear.
+ *
+ * \warning        SHA-1 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
 void mbedtls_sha1_free( mbedtls_sha1_context *ctx );
 
 /**
- * \brief          Clone (the state of) a SHA-1 context
+ * \brief          This function clones the state of a SHA-1 context.
  *
- * \param dst      The destination context
- * \param src      The context to be cloned
+ * \param dst      The destination context.
+ * \param src      The context to clone.
+ *
+ * \warning        SHA-1 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
 void mbedtls_sha1_clone( mbedtls_sha1_context *dst,
                          const mbedtls_sha1_context *src );
 
 /**
+ * \brief          This function starts a SHA-1 checksum calculation.
+ *
+ * \param ctx      The context to initialize.
+ *
+ * \return         \c 0 if successful
+ *
+ * \warning        SHA-1 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
+ */
+int mbedtls_sha1_starts_ret( mbedtls_sha1_context *ctx );
+
+/**
+ * \brief          This function feeds an input buffer into an ongoing SHA-1
+ *                 checksum calculation.
+ *
+ * \param ctx      The SHA-1 context.
+ * \param input    The buffer holding the input data.
+ * \param ilen     The length of the input data.
+ *
+ * \return         \c 0 if successful
+ *
+ * \warning        SHA-1 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
+ */
+int mbedtls_sha1_update_ret( mbedtls_sha1_context *ctx,
+                             const unsigned char *input,
+                             size_t ilen );
+
+/**
+ * \brief          This function finishes the SHA-1 operation, and writes
+ *                 the result to the output buffer.
+ *
+ * \param ctx      The SHA-1 context.
+ * \param output   The SHA-1 checksum result.
+ *
+ * \return         \c 0 if successful
+ *
+ * \warning        SHA-1 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
+ */
+int mbedtls_sha1_finish_ret( mbedtls_sha1_context *ctx,
+                             unsigned char output[20] );
+
+/**
+ * \brief          SHA-1 process data block (internal use only)
+ *
+ * \param ctx      SHA-1 context
+ * \param data     The data block being processed.
+ *
+ * \return         \c 0 if successful
+ *
+ * \warning        SHA-1 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
+ */
+int mbedtls_internal_sha1_process( mbedtls_sha1_context *ctx,
+                                   const unsigned char data[64] );
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED      __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+/**
  * \brief          SHA-1 context setup
  *
- * \param ctx      context to be initialized
+ * \deprecated     Superseded by mbedtls_sha1_starts_ret() in 2.7.0
+ *
+ * \param ctx      The SHA-1 context to be initialized.
+ *
+ * \warning        SHA-1 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
-void mbedtls_sha1_starts( mbedtls_sha1_context *ctx );
+MBEDTLS_DEPRECATED static inline void mbedtls_sha1_starts(
+                                                mbedtls_sha1_context *ctx )
+{
+    mbedtls_sha1_starts_ret( ctx );
+}
 
 /**
  * \brief          SHA-1 process buffer
  *
- * \param ctx      SHA-1 context
- * \param input    buffer holding the  data
- * \param ilen     length of the input data
+ * \deprecated     Superseded by mbedtls_sha1_update_ret() in 2.7.0
+ *
+ * \param ctx      The SHA-1 context.
+ * \param input    The buffer holding the input data.
+ * \param ilen     The length of the input data.
+ *
+ * \warning        SHA-1 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
-void mbedtls_sha1_update( mbedtls_sha1_context *ctx, const unsigned char *input, size_t ilen );
+MBEDTLS_DEPRECATED static inline void mbedtls_sha1_update(
+                                                mbedtls_sha1_context *ctx,
+                                                const unsigned char *input,
+                                                size_t ilen )
+{
+    mbedtls_sha1_update_ret( ctx, input, ilen );
+}
 
 /**
  * \brief          SHA-1 final digest
  *
- * \param ctx      SHA-1 context
- * \param output   SHA-1 checksum result
+ * \deprecated     Superseded by mbedtls_sha1_finish_ret() in 2.7.0
+ *
+ * \param ctx      The SHA-1 context.
+ * \param output   The SHA-1 checksum result.
+ *
+ * \warning        SHA-1 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
-void mbedtls_sha1_finish( mbedtls_sha1_context *ctx, unsigned char output[20] );
+MBEDTLS_DEPRECATED static inline void mbedtls_sha1_finish(
+                                                mbedtls_sha1_context *ctx,
+                                                unsigned char output[20] )
+{
+    mbedtls_sha1_finish_ret( ctx, output );
+}
 
-/* Internal use */
-void mbedtls_sha1_process( mbedtls_sha1_context *ctx, const unsigned char data[64] );
+/**
+ * \brief          SHA-1 process data block (internal use only)
+ *
+ * \deprecated     Superseded by mbedtls_internal_sha1_process() in 2.7.0
+ *
+ * \param ctx      The SHA-1 context.
+ * \param data     The data block being processed.
+ *
+ * \warning        SHA-1 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_sha1_process(
+                                                mbedtls_sha1_context *ctx,
+                                                const unsigned char data[64] )
+{
+    mbedtls_internal_sha1_process( ctx, data );
+}
+
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
 
 #ifdef __cplusplus
 }
@@ -114,18 +274,68 @@
 #endif
 
 /**
+ * \brief          This function calculates the SHA-1 checksum of a buffer.
+ *
+ *                 The function allocates the context, performs the
+ *                 calculation, and frees the context.
+ *
+ *                 The SHA-1 result is calculated as
+ *                 output = SHA-1(input buffer).
+ *
+ * \param input    The buffer holding the input data.
+ * \param ilen     The length of the input data.
+ * \param output   The SHA-1 checksum result.
+ *
+ * \return         \c 0 if successful
+ *
+ * \warning        SHA-1 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
+ */
+int mbedtls_sha1_ret( const unsigned char *input,
+                      size_t ilen,
+                      unsigned char output[20] );
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED      __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+/**
  * \brief          Output = SHA-1( input buffer )
  *
- * \param input    buffer holding the  data
- * \param ilen     length of the input data
- * \param output   SHA-1 checksum result
+ * \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.
+ *
+ * \warning        SHA-1 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
-void mbedtls_sha1( const unsigned char *input, size_t ilen, unsigned char output[20] );
+MBEDTLS_DEPRECATED static inline void mbedtls_sha1( const unsigned char *input,
+                                                    size_t ilen,
+                                                    unsigned char output[20] )
+{
+    mbedtls_sha1_ret( input, ilen, output );
+}
+
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
 
 /**
- * \brief          Checkup routine
+ * \brief          The SHA-1 checkup routine.
  *
- * \return         0 if successful, or 1 if the test failed
+ * \return         \c 0 on success, or \c 1 on failure.
+ *
+ * \warning        SHA-1 is considered a weak message digest and its use
+ *                 constitutes a security risk. We recommend considering
+ *                 stronger message digests instead.
+ *
  */
 int mbedtls_sha1_self_test( int verbose );
 
diff --git a/include/mbedtls/sha256.h b/include/mbedtls/sha256.h
index f8041ad..a2b6e11 100644
--- a/include/mbedtls/sha256.h
+++ b/include/mbedtls/sha256.h
@@ -1,9 +1,10 @@
 /**
  * \file sha256.h
  *
- * \brief SHA-224 and SHA-256 cryptographic hash function
- *
- *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ * \brief The SHA-224 and SHA-256 cryptographic hash function.
+ */
+/*
+ *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
@@ -18,7 +19,7 @@
  *  See the License for the specific language governing permissions and
  *  limitations under the License.
  *
- *  This file is part of mbed TLS (https://tls.mbed.org)
+ *  This file is part of Mbed TLS (https://tls.mbed.org)
  */
 #ifndef MBEDTLS_SHA256_H
 #define MBEDTLS_SHA256_H
@@ -32,6 +33,12 @@
 #include <stddef.h>
 #include <stdint.h>
 
+#define MBEDTLS_ERR_SHA256_HW_ACCEL_FAILED                -0x0037  /**< SHA-256 hardware accelerator failed */
+
+#if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
+    !defined(inline) && !defined(__cplusplus)
+#define inline __inline
+#endif
 #if !defined(MBEDTLS_SHA256_ALT)
 // Regular implementation
 //
@@ -41,69 +48,174 @@
 #endif
 
 /**
- * \brief          SHA-256 context structure
+ * \brief          The SHA-256 context structure.
+ *
+ *                 The structure is used both for SHA-256 and for SHA-224
+ *                 checksum calculations. The choice between these two is
+ *                 made in the call to mbedtls_sha256_starts_ret().
  */
 typedef struct
 {
-    uint32_t total[2];          /*!< number of bytes processed  */
-    uint32_t state[8];          /*!< intermediate digest state  */
-    unsigned char buffer[64];   /*!< data block being processed */
-    int is224;                  /*!< 0 => SHA-256, else SHA-224 */
+    uint32_t total[2];          /*!< The number of Bytes processed.  */
+    uint32_t state[8];          /*!< The intermediate digest state.  */
+    unsigned char buffer[64];   /*!< The data block being processed. */
+    int is224;                  /*!< Determines which function to use.
+                                     <ul><li>0: Use SHA-256.</li>
+                                     <li>1: Use SHA-224.</li></ul> */
 }
 mbedtls_sha256_context;
 
 /**
- * \brief          Initialize SHA-256 context
+ * \brief          This function initializes a SHA-256 context.
  *
- * \param ctx      SHA-256 context to be initialized
+ * \param ctx      The SHA-256 context to initialize.
  */
 void mbedtls_sha256_init( mbedtls_sha256_context *ctx );
 
 /**
- * \brief          Clear SHA-256 context
+ * \brief          This function clears a SHA-256 context.
  *
- * \param ctx      SHA-256 context to be cleared
+ * \param ctx      The SHA-256 context to clear.
  */
 void mbedtls_sha256_free( mbedtls_sha256_context *ctx );
 
 /**
- * \brief          Clone (the state of) a SHA-256 context
+ * \brief          This function clones the state of a SHA-256 context.
  *
- * \param dst      The destination context
- * \param src      The context to be cloned
+ * \param dst      The destination context.
+ * \param src      The context to clone.
  */
 void mbedtls_sha256_clone( mbedtls_sha256_context *dst,
                            const mbedtls_sha256_context *src );
 
 /**
- * \brief          SHA-256 context setup
+ * \brief          This function starts a SHA-224 or SHA-256 checksum
+ *                 calculation.
  *
- * \param ctx      context to be initialized
- * \param is224    0 = use SHA256, 1 = use SHA224
+ * \param ctx      The context to initialize.
+ * \param is224    Determines which function to use.
+ *                 <ul><li>0: Use SHA-256.</li>
+ *                 <li>1: Use SHA-224.</li></ul>
+ *
+ * \return         \c 0 on success.
  */
-void mbedtls_sha256_starts( mbedtls_sha256_context *ctx, int is224 );
+int mbedtls_sha256_starts_ret( mbedtls_sha256_context *ctx, int is224 );
 
 /**
- * \brief          SHA-256 process buffer
+ * \brief          This function feeds an input buffer into an ongoing
+ *                 SHA-256 checksum calculation.
  *
  * \param ctx      SHA-256 context
- * \param input    buffer holding the  data
+ * \param input    buffer holding the data
  * \param ilen     length of the input data
+ *
+ * \return         \c 0 on success.
  */
-void mbedtls_sha256_update( mbedtls_sha256_context *ctx, const unsigned char *input,
-                    size_t ilen );
+int mbedtls_sha256_update_ret( mbedtls_sha256_context *ctx,
+                               const unsigned char *input,
+                               size_t ilen );
 
 /**
- * \brief          SHA-256 final digest
+ * \brief          This function finishes the SHA-256 operation, and writes
+ *                 the result to the output buffer.
  *
- * \param ctx      SHA-256 context
- * \param output   SHA-224/256 checksum result
+ * \param ctx      The SHA-256 context.
+ * \param output   The SHA-224 or SHA-256 checksum result.
+ *
+ * \return         \c 0 on success.
  */
-void mbedtls_sha256_finish( mbedtls_sha256_context *ctx, unsigned char output[32] );
+int mbedtls_sha256_finish_ret( mbedtls_sha256_context *ctx,
+                               unsigned char output[32] );
 
-/* Internal use */
-void mbedtls_sha256_process( mbedtls_sha256_context *ctx, const unsigned char data[64] );
+/**
+ * \brief          This function processes a single data block within
+ *                 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.
+ *
+ * \return         \c 0 on success.
+ */
+int mbedtls_internal_sha256_process( mbedtls_sha256_context *ctx,
+                                     const unsigned char data[64] );
 
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED      __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+/**
+ * \brief          This function starts a SHA-256 checksum calculation.
+ *
+ * \deprecated     Superseded by mbedtls_sha256_starts_ret() in 2.7.0.
+ *
+ * \param ctx      The SHA-256 context to initialize.
+ * \param is224    Determines which function to use.
+ *                 <ul><li>0: Use SHA-256.</li>
+ *                 <li>1: Use SHA-224.</li></ul>
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_sha256_starts(
+                                                mbedtls_sha256_context *ctx,
+                                                int is224 )
+{
+    mbedtls_sha256_starts_ret( ctx, is224 );
+}
+
+/**
+ * \brief          This function feeds an input buffer into an ongoing
+ *                 SHA-256 checksum calculation.
+ *
+ * \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.
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_sha256_update(
+                                                mbedtls_sha256_context *ctx,
+                                                const unsigned char *input,
+                                                size_t ilen )
+{
+    mbedtls_sha256_update_ret( ctx, input, ilen );
+}
+
+/**
+ * \brief          This function finishes the SHA-256 operation, and writes
+ *                 the result to the output buffer.
+ *
+ * \deprecated     Superseded by mbedtls_sha256_finish_ret() in 2.7.0.
+ *
+ * \param ctx      The SHA-256 context.
+ * \param output   The SHA-224or SHA-256 checksum result.
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_sha256_finish(
+                                                mbedtls_sha256_context *ctx,
+                                                unsigned char output[32] )
+{
+    mbedtls_sha256_finish_ret( ctx, output );
+}
+
+/**
+ * \brief          This function processes a single data block within
+ *                 the ongoing SHA-256 computation. This function is for
+ *                 internal use only.
+ *
+ * \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.
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_sha256_process(
+                                                mbedtls_sha256_context *ctx,
+                                                const unsigned char data[64] )
+{
+    mbedtls_internal_sha256_process( ctx, data );
+}
+
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
 #ifdef __cplusplus
 }
 #endif
@@ -117,20 +229,69 @@
 #endif
 
 /**
- * \brief          Output = SHA-256( input buffer )
+ * \brief          This function calculates the SHA-224 or SHA-256
+ *                 checksum of a buffer.
  *
- * \param input    buffer holding the  data
- * \param ilen     length of the input data
- * \param output   SHA-224/256 checksum result
- * \param is224    0 = use SHA256, 1 = use SHA224
+ *                 The function allocates the context, performs the
+ *                 calculation, and frees the context.
+ *
+ *                 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.
+ *                 <ul><li>0: Use SHA-256.</li>
+ *                 <li>1: Use SHA-224.</li></ul>
  */
-void mbedtls_sha256( const unsigned char *input, size_t ilen,
-           unsigned char output[32], int is224 );
+int mbedtls_sha256_ret( const unsigned char *input,
+                        size_t ilen,
+                        unsigned char output[32],
+                        int is224 );
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED      __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
 
 /**
- * \brief          Checkup routine
+ * \brief          This function calculates the SHA-224 or SHA-256 checksum
+ *                 of a buffer.
  *
- * \return         0 if successful, or 1 if the test failed
+ *                 The function allocates the context, performs the
+ *                 calculation, and frees the context.
+ *
+ *                 The SHA-256 result is calculated as
+ *                 output = SHA-256(input buffer).
+ *
+ * \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.
+ *                 <ul><li>0: Use SHA-256.</li>
+ *                 <li>1: Use SHA-224.</li></ul>
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_sha256(
+                                                    const unsigned char *input,
+                                                    size_t ilen,
+                                                    unsigned char output[32],
+                                                    int is224 )
+{
+    mbedtls_sha256_ret( input, ilen, output, is224 );
+}
+
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
+
+/**
+ * \brief          The SHA-224 and SHA-256 checkup routine.
+ *
+ * \return         \c 0 on success, or \c 1 on failure.
  */
 int mbedtls_sha256_self_test( int verbose );
 
diff --git a/include/mbedtls/sha512.h b/include/mbedtls/sha512.h
index 627694f..52ae204 100644
--- a/include/mbedtls/sha512.h
+++ b/include/mbedtls/sha512.h
@@ -1,9 +1,10 @@
 /**
  * \file sha512.h
  *
- * \brief SHA-384 and SHA-512 cryptographic hash function
- *
- *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ * \brief The SHA-384 and SHA-512 cryptographic hash function.
+ */
+/*
+ *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
@@ -18,7 +19,7 @@
  *  See the License for the specific language governing permissions and
  *  limitations under the License.
  *
- *  This file is part of mbed TLS (https://tls.mbed.org)
+ *  This file is part of Mbed TLS (https://tls.mbed.org)
  */
 #ifndef MBEDTLS_SHA512_H
 #define MBEDTLS_SHA512_H
@@ -32,6 +33,12 @@
 #include <stddef.h>
 #include <stdint.h>
 
+#define MBEDTLS_ERR_SHA512_HW_ACCEL_FAILED                -0x0039  /**< SHA-512 hardware accelerator failed */
+
+#if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
+    !defined(inline) && !defined(__cplusplus)
+#define inline __inline
+#endif
 #if !defined(MBEDTLS_SHA512_ALT)
 // Regular implementation
 //
@@ -41,65 +48,174 @@
 #endif
 
 /**
- * \brief          SHA-512 context structure
+ * \brief          The SHA-512 context structure.
+ *
+ *                 The structure is used both for SHA-384 and for SHA-512
+ *                 checksum calculations. The choice between these two is
+ *                 made in the call to mbedtls_sha512_starts_ret().
  */
 typedef struct
 {
-    uint64_t total[2];          /*!< number of bytes processed  */
-    uint64_t state[8];          /*!< intermediate digest state  */
-    unsigned char buffer[128];  /*!< data block being processed */
-    int is384;                  /*!< 0 => SHA-512, else SHA-384 */
+    uint64_t total[2];          /*!< The number of Bytes processed. */
+    uint64_t state[8];          /*!< The intermediate digest state. */
+    unsigned char buffer[128];  /*!< The data block being processed. */
+    int is384;                  /*!< Determines which function to use.
+                                 *   <ul><li>0: Use SHA-512.</li>
+                                 *   <li>1: Use SHA-384.</li></ul> */
 }
 mbedtls_sha512_context;
 
 /**
- * \brief          Initialize SHA-512 context
+ * \brief          This function initializes a SHA-512 context.
  *
- * \param ctx      SHA-512 context to be initialized
+ * \param ctx      The SHA-512 context to initialize.
  */
 void mbedtls_sha512_init( mbedtls_sha512_context *ctx );
 
 /**
- * \brief          Clear SHA-512 context
+ * \brief          This function clears a SHA-512 context.
  *
- * \param ctx      SHA-512 context to be cleared
+ * \param ctx      The SHA-512 context to clear.
  */
 void mbedtls_sha512_free( mbedtls_sha512_context *ctx );
 
 /**
- * \brief          Clone (the state of) a SHA-512 context
+ * \brief          This function clones the state of a SHA-512 context.
  *
- * \param dst      The destination context
- * \param src      The context to be cloned
+ * \param dst      The destination context.
+ * \param src      The context to clone.
  */
 void mbedtls_sha512_clone( mbedtls_sha512_context *dst,
                            const mbedtls_sha512_context *src );
 
 /**
- * \brief          SHA-512 context setup
+ * \brief          This function starts a SHA-384 or SHA-512 checksum
+ *                 calculation.
  *
- * \param ctx      context to be initialized
- * \param is384    0 = use SHA512, 1 = use SHA384
+ * \param ctx      The SHA-512 context to initialize.
+ * \param is384    Determines which function to use.
+ *                 <ul><li>0: Use SHA-512.</li>
+ *                 <li>1: Use SHA-384.</li></ul>
+ *
+ * \return         \c 0 on success.
  */
-void mbedtls_sha512_starts( mbedtls_sha512_context *ctx, int is384 );
+int mbedtls_sha512_starts_ret( mbedtls_sha512_context *ctx, int is384 );
 
 /**
- * \brief          SHA-512 process buffer
+ * \brief          This function feeds an input buffer into an ongoing
+ *                 SHA-512 checksum calculation.
  *
- * \param ctx      SHA-512 context
- * \param input    buffer holding the  data
- * \param ilen     length of the input data
+ * \param ctx      The SHA-512 context.
+ * \param input    The buffer holding the input data.
+ * \param ilen     The length of the input data.
+ *
+ * \return         \c 0 on success.
  */
-void mbedtls_sha512_update( mbedtls_sha512_context *ctx, const unsigned char *input,
+int mbedtls_sha512_update_ret( mbedtls_sha512_context *ctx,
+                    const unsigned char *input,
                     size_t ilen );
 
 /**
- * \brief          SHA-512 final digest
+ * \brief          This function finishes the SHA-512 operation, and writes
+ *                 the result to the output buffer. This function is for
+ *                 internal use only.
  *
- * \param ctx      SHA-512 context
- * \param output   SHA-384/512 checksum result
+ * \param ctx      The SHA-512 context.
+ * \param output   The SHA-384 or SHA-512 checksum result.
+ *
+ * \return         \c 0 on success.
  */
-void mbedtls_sha512_finish( mbedtls_sha512_context *ctx, unsigned char output[64] );
+int mbedtls_sha512_finish_ret( mbedtls_sha512_context *ctx,
+                               unsigned char output[64] );
+
+/**
+ * \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.
+ *
+ * \return         \c 0 on success.
+ */
+int mbedtls_internal_sha512_process( mbedtls_sha512_context *ctx,
+                                     const unsigned char data[128] );
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED      __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+/**
+ * \brief          This function starts a SHA-384 or SHA-512 checksum
+ *                 calculation.
+ *
+ * \deprecated     Superseded by mbedtls_sha512_starts_ret() in 2.7.0
+ *
+ * \param ctx      The SHA-512 context to initialize.
+ * \param is384    Determines which function to use.
+ *                 <ul><li>0: Use SHA-512.</li>
+ *                 <li>1: Use SHA-384.</li></ul>
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_sha512_starts(
+                                                mbedtls_sha512_context *ctx,
+                                                int is384 )
+{
+    mbedtls_sha512_starts_ret( ctx, is384 );
+}
+
+/**
+ * \brief          This function feeds an input buffer into an ongoing
+ *                 SHA-512 checksum calculation.
+ *
+ * \deprecated     Superseded by mbedtls_sha512_update_ret() in 2.7.0
+ *
+ * \param ctx      The SHA-512 context.
+ * \param input    The buffer holding the data.
+ * \param ilen     The length of the input data.
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_sha512_update(
+                                                mbedtls_sha512_context *ctx,
+                                                const unsigned char *input,
+                                                size_t ilen )
+{
+    mbedtls_sha512_update_ret( ctx, input, ilen );
+}
+
+/**
+ * \brief          This function finishes the SHA-512 operation, and writes
+ *                 the result to the output buffer.
+ *
+ * \deprecated     Superseded by mbedtls_sha512_finish_ret() in 2.7.0
+ *
+ * \param ctx      The SHA-512 context.
+ * \param output   The SHA-384 or SHA-512 checksum result.
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_sha512_finish(
+                                                mbedtls_sha512_context *ctx,
+                                                unsigned char output[64] )
+{
+    mbedtls_sha512_finish_ret( ctx, output );
+}
+
+/**
+ * \brief          This function processes a single data block within
+ *                 the ongoing SHA-512 computation. This function is for
+ *                 internal use only.
+ *
+ * \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.
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_sha512_process(
+                                            mbedtls_sha512_context *ctx,
+                                            const unsigned char data[128] )
+{
+    mbedtls_internal_sha512_process( ctx, data );
+}
+
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
 
 #ifdef __cplusplus
 }
@@ -114,26 +230,72 @@
 #endif
 
 /**
- * \brief          Output = SHA-512( input buffer )
+ * \brief          This function calculates the SHA-512 or SHA-384
+ *                 checksum of a buffer.
  *
- * \param input    buffer holding the  data
- * \param ilen     length of the input data
- * \param output   SHA-384/512 checksum result
- * \param is384    0 = use SHA512, 1 = use SHA384
+ *                 The function allocates the context, performs the
+ *                 calculation, and frees the context.
+ *
+ *                 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 output   The SHA-384 or SHA-512 checksum result.
+ * \param is384    Determines which function to use.
+ *                 <ul><li>0: Use SHA-512.</li>
+ *                 <li>1: Use SHA-384.</li></ul>
+ *
+ * \return         \c 0 on success.
  */
-void mbedtls_sha512( const unsigned char *input, size_t ilen,
-             unsigned char output[64], int is384 );
+int mbedtls_sha512_ret( const unsigned char *input,
+                        size_t ilen,
+                        unsigned char output[64],
+                        int is384 );
 
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED      __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
 /**
- * \brief          Checkup routine
+ * \brief          This function calculates the SHA-512 or SHA-384
+ *                 checksum of a buffer.
  *
- * \return         0 if successful, or 1 if the test failed
+ *                 The function allocates the context, performs the
+ *                 calculation, and frees the context.
+ *
+ *                 The SHA-512 result is calculated as
+ *                 output = SHA-512(input buffer).
+ *
+ * \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.
+ *                 <ul><li>0: Use SHA-512.</li>
+ *                 <li>1: Use SHA-384.</li></ul>
+ */
+MBEDTLS_DEPRECATED static inline void mbedtls_sha512(
+                                                    const unsigned char *input,
+                                                    size_t ilen,
+                                                    unsigned char output[64],
+                                                    int is384 )
+{
+    mbedtls_sha512_ret( input, ilen, output, is384 );
+}
+
+#undef MBEDTLS_DEPRECATED
+#endif /* !MBEDTLS_DEPRECATED_REMOVED */
+ /**
+ * \brief          The SHA-384 or SHA-512 checkup routine.
+ *
+ * \return         \c 0 on success, or \c 1 on failure.
  */
 int mbedtls_sha512_self_test( int verbose );
 
-/* Internal use */
-void mbedtls_sha512_process( mbedtls_sha512_context *ctx, const unsigned char data[128] );
-
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index e98101e..51e843a 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -2,7 +2,8 @@
  * \file ssl.h
  *
  * \brief SSL/TLS functions.
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
@@ -1699,18 +1700,50 @@
 #endif /* MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED */
 
 #if defined(MBEDTLS_DHM_C) && defined(MBEDTLS_SSL_SRV_C)
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
+
+#if defined(MBEDTLS_DEPRECATED_WARNING)
+#define MBEDTLS_DEPRECATED    __attribute__((deprecated))
+#else
+#define MBEDTLS_DEPRECATED
+#endif
+
 /**
  * \brief          Set the Diffie-Hellman public P and G values,
  *                 read as hexadecimal strings (server-side only)
- *                 (Default: MBEDTLS_DHM_RFC5114_MODP_2048_[PG])
+ *                 (Default values: MBEDTLS_DHM_RFC3526_MODP_2048_[PG])
  *
  * \param conf     SSL configuration
  * \param dhm_P    Diffie-Hellman-Merkle modulus
  * \param dhm_G    Diffie-Hellman-Merkle generator
  *
+ * \deprecated     Superseded by \c mbedtls_ssl_conf_dh_param_bin.
+ *
  * \return         0 if successful
  */
-int mbedtls_ssl_conf_dh_param( mbedtls_ssl_config *conf, const char *dhm_P, const char *dhm_G );
+MBEDTLS_DEPRECATED int mbedtls_ssl_conf_dh_param( mbedtls_ssl_config *conf,
+                                                  const char *dhm_P,
+                                                  const char *dhm_G );
+
+#endif /* MBEDTLS_DEPRECATED_REMOVED */
+
+/**
+ * \brief          Set the Diffie-Hellman public P and G values
+ *                 from big-endian binary presentations.
+ *                 (Default values: MBEDTLS_DHM_RFC3526_MODP_2048_[PG]_BIN)
+ *
+ * \param conf     SSL configuration
+ * \param dhm_P    Diffie-Hellman-Merkle modulus in big-endian binary form
+ * \param P_len    Length of DHM modulus
+ * \param dhm_G    Diffie-Hellman-Merkle generator in big-endian binary form
+ * \param G_len    Length of DHM generator
+ *
+ * \return         0 if successful
+ */
+int mbedtls_ssl_conf_dh_param_bin( mbedtls_ssl_config *conf,
+                                   const unsigned char *dhm_P, size_t P_len,
+                                   const unsigned char *dhm_G,  size_t G_len );
 
 /**
  * \brief          Set the Diffie-Hellman public P and G values,
diff --git a/include/mbedtls/ssl_cache.h b/include/mbedtls/ssl_cache.h
index 3734bb7..ec081e6 100644
--- a/include/mbedtls/ssl_cache.h
+++ b/include/mbedtls/ssl_cache.h
@@ -2,7 +2,8 @@
  * \file ssl_cache.h
  *
  * \brief SSL session cache implementation
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/ssl_ciphersuites.h b/include/mbedtls/ssl_ciphersuites.h
index 9101d9c..545468a 100644
--- a/include/mbedtls/ssl_ciphersuites.h
+++ b/include/mbedtls/ssl_ciphersuites.h
@@ -2,7 +2,8 @@
  * \file ssl_ciphersuites.h
  *
  * \brief SSL Ciphersuites for mbed TLS
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/ssl_cookie.h b/include/mbedtls/ssl_cookie.h
index 037e1c3..80b65bb 100644
--- a/include/mbedtls/ssl_cookie.h
+++ b/include/mbedtls/ssl_cookie.h
@@ -2,7 +2,8 @@
  * \file ssl_cookie.h
  *
  * \brief DTLS cookie callbacks implementation
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/ssl_internal.h b/include/mbedtls/ssl_internal.h
index 756360b..9f583a8 100644
--- a/include/mbedtls/ssl_internal.h
+++ b/include/mbedtls/ssl_internal.h
@@ -1,8 +1,9 @@
 /**
- * \file ssl_ticket.h
+ * \file ssl_internal.h
  *
  * \brief Internal functions shared by the SSL modules
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
@@ -24,6 +25,7 @@
 #define MBEDTLS_SSL_INTERNAL_H
 
 #include "ssl.h"
+#include "cipher.h"
 
 #if defined(MBEDTLS_MD5_C)
 #include "md5.h"
@@ -138,14 +140,34 @@
 #define MBEDTLS_SSL_PADDING_ADD              0
 #endif
 
-#define MBEDTLS_SSL_BUFFER_LEN  ( MBEDTLS_SSL_MAX_CONTENT_LEN               \
-                        + MBEDTLS_SSL_COMPRESSION_ADD               \
-                        + 29 /* counter + header + IV */    \
-                        + MBEDTLS_SSL_MAC_ADD                       \
-                        + MBEDTLS_SSL_PADDING_ADD                   \
+#define MBEDTLS_SSL_PAYLOAD_LEN ( MBEDTLS_SSL_MAX_CONTENT_LEN    \
+                        + MBEDTLS_SSL_COMPRESSION_ADD            \
+                        + MBEDTLS_MAX_IV_LENGTH                  \
+                        + MBEDTLS_SSL_MAC_ADD                    \
+                        + MBEDTLS_SSL_PADDING_ADD                \
                         )
 
 /*
+ * Check that we obey the standard's message size bounds
+ */
+
+#if MBEDTLS_SSL_MAX_CONTENT_LEN > 16384
+#error Bad configuration - record content too large.
+#endif
+
+#if MBEDTLS_SSL_PAYLOAD_LEN > 16384 + 2048
+#error Bad configuration - protected record payload too large.
+#endif
+
+/* Note: Even though the TLS record header is only 5 bytes
+   long, we're internally using 8 bytes to store the
+   implicit sequence number. */
+#define MBEDTLS_SSL_HEADER_LEN 13
+
+#define MBEDTLS_SSL_BUFFER_LEN  \
+    ( ( MBEDTLS_SSL_HEADER_LEN ) + ( MBEDTLS_SSL_PAYLOAD_LEN ) )
+
+/*
  * TLS extension flags (for extensions with outgoing ServerHello content
  * that need it (e.g. for RENEGOTIATION_INFO the server already knows because
  * of state of the renegotiation flag, so no indicator is required)
@@ -600,9 +622,9 @@
 static inline int mbedtls_ssl_safer_memcmp( const void *a, const void *b, size_t n )
 {
     size_t i;
-    const unsigned char *A = (const unsigned char *) a;
-    const unsigned char *B = (const unsigned char *) b;
-    unsigned char diff = 0;
+    volatile const unsigned char *A = (volatile const unsigned char *) a;
+    volatile const unsigned char *B = (volatile const unsigned char *) b;
+    volatile unsigned char diff = 0;
 
     for( i = 0; i < n; i++ )
         diff |= A[i] ^ B[i];
@@ -610,6 +632,23 @@
     return( diff );
 }
 
+#if defined(MBEDTLS_SSL_PROTO_SSL3) || defined(MBEDTLS_SSL_PROTO_TLS1) || \
+    defined(MBEDTLS_SSL_PROTO_TLS1_1)
+int mbedtls_ssl_get_key_exchange_md_ssl_tls( mbedtls_ssl_context *ssl,
+                                        unsigned char *output,
+                                        unsigned char *data, size_t data_len );
+#endif /* MBEDTLS_SSL_PROTO_SSL3 || MBEDTLS_SSL_PROTO_TLS1 || \
+          MBEDTLS_SSL_PROTO_TLS1_1 */
+
+#if defined(MBEDTLS_SSL_PROTO_TLS1) || defined(MBEDTLS_SSL_PROTO_TLS1_1) || \
+    defined(MBEDTLS_SSL_PROTO_TLS1_2)
+int mbedtls_ssl_get_key_exchange_md_tls1_2( mbedtls_ssl_context *ssl,
+                                        unsigned char *output,
+                                        unsigned char *data, size_t data_len,
+                                        mbedtls_md_type_t md_alg );
+#endif /* MBEDTLS_SSL_PROTO_TLS1 || MBEDTLS_SSL_PROTO_TLS1_1 || \
+          MBEDTLS_SSL_PROTO_TLS1_2 */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/mbedtls/ssl_ticket.h b/include/mbedtls/ssl_ticket.h
index 7c6bc61..93ad46a 100644
--- a/include/mbedtls/ssl_ticket.h
+++ b/include/mbedtls/ssl_ticket.h
@@ -2,7 +2,8 @@
  * \file ssl_ticket.h
  *
  * \brief TLS server ticket callbacks implementation
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/threading.h b/include/mbedtls/threading.h
index b0c34ec..58e6db2 100644
--- a/include/mbedtls/threading.h
+++ b/include/mbedtls/threading.h
@@ -2,7 +2,8 @@
  * \file threading.h
  *
  * \brief Threading abstraction layer
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/timing.h b/include/mbedtls/timing.h
index bfb8579..2c497bf 100644
--- a/include/mbedtls/timing.h
+++ b/include/mbedtls/timing.h
@@ -2,7 +2,8 @@
  * \file timing.h
  *
  * \brief Portable interface to timeouts and to the CPU cycle counter
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/version.h b/include/mbedtls/version.h
index 3b209a6..961be59 100644
--- a/include/mbedtls/version.h
+++ b/include/mbedtls/version.h
@@ -2,7 +2,8 @@
  * \file version.h
  *
  * \brief Run-time version information
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
@@ -38,7 +39,7 @@
  * Major, Minor, Patchlevel
  */
 #define MBEDTLS_VERSION_MAJOR  2
-#define MBEDTLS_VERSION_MINOR  6
+#define MBEDTLS_VERSION_MINOR  7
 #define MBEDTLS_VERSION_PATCH  0
 
 /**
@@ -46,9 +47,9 @@
  *    MMNNPP00
  *    Major version | Minor version | Patch version
  */
-#define MBEDTLS_VERSION_NUMBER         0x02060000
-#define MBEDTLS_VERSION_STRING         "2.6.0"
-#define MBEDTLS_VERSION_STRING_FULL    "mbed TLS 2.6.0"
+#define MBEDTLS_VERSION_NUMBER         0x02070000
+#define MBEDTLS_VERSION_STRING         "2.7.0"
+#define MBEDTLS_VERSION_STRING_FULL    "mbed TLS 2.7.0"
 
 #if defined(MBEDTLS_VERSION_C)
 
diff --git a/include/mbedtls/x509.h b/include/mbedtls/x509.h
index d7e318d..d6db9c6 100644
--- a/include/mbedtls/x509.h
+++ b/include/mbedtls/x509.h
@@ -2,7 +2,8 @@
  * \file x509.h
  *
  * \brief X.509 generic defines and structures
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/x509_crl.h b/include/mbedtls/x509_crl.h
index 7988439..08a4283 100644
--- a/include/mbedtls/x509_crl.h
+++ b/include/mbedtls/x509_crl.h
@@ -2,7 +2,8 @@
  * \file x509_crl.h
  *
  * \brief X.509 certificate revocation list parsing
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/x509_crt.h b/include/mbedtls/x509_crt.h
index 06166d8..2dbb7ec 100644
--- a/include/mbedtls/x509_crt.h
+++ b/include/mbedtls/x509_crt.h
@@ -2,7 +2,8 @@
  * \file x509_crt.h
  *
  * \brief X.509 certificate parsing and writing
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
@@ -373,21 +374,22 @@
 
 #if defined(MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE)
 /**
- * \brief          Check usage of certificate against extentedJeyUsage.
+ * \brief           Check usage of certificate against extendedKeyUsage.
  *
- * \param crt      Leaf certificate used.
- * \param usage_oid Intended usage (eg MBEDTLS_OID_SERVER_AUTH or MBEDTLS_OID_CLIENT_AUTH).
+ * \param crt       Leaf certificate used.
+ * \param usage_oid Intended usage (eg MBEDTLS_OID_SERVER_AUTH or
+ *                  MBEDTLS_OID_CLIENT_AUTH).
  * \param usage_len Length of usage_oid (eg given by MBEDTLS_OID_SIZE()).
  *
- * \return         0 if this use of the certificate is allowed,
- *                 MBEDTLS_ERR_X509_BAD_INPUT_DATA if not.
+ * \return          0 if this use of the certificate is allowed,
+ *                  MBEDTLS_ERR_X509_BAD_INPUT_DATA if not.
  *
- * \note           Usually only makes sense on leaf certificates.
+ * \note            Usually only makes sense on leaf certificates.
  */
 int mbedtls_x509_crt_check_extended_key_usage( const mbedtls_x509_crt *crt,
-                                       const char *usage_oid,
-                                       size_t usage_len );
-#endif /* MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE) */
+                                               const char *usage_oid,
+                                               size_t usage_len );
+#endif /* MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE */
 
 #if defined(MBEDTLS_X509_CRL_PARSE_C)
 /**
diff --git a/include/mbedtls/x509_csr.h b/include/mbedtls/x509_csr.h
index fe9843c..0c6ccad 100644
--- a/include/mbedtls/x509_csr.h
+++ b/include/mbedtls/x509_csr.h
@@ -2,7 +2,8 @@
  * \file x509_csr.h
  *
  * \brief X.509 certificate signing request parsing and writing
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/xtea.h b/include/mbedtls/xtea.h
index b073f84..34ccee3 100644
--- a/include/mbedtls/xtea.h
+++ b/include/mbedtls/xtea.h
@@ -2,7 +2,8 @@
  * \file xtea.h
  *
  * \brief XTEA block cipher (32-bit)
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
@@ -36,6 +37,7 @@
 #define MBEDTLS_XTEA_DECRYPT     0
 
 #define MBEDTLS_ERR_XTEA_INVALID_INPUT_LENGTH             -0x0028  /**< The data input has an invalid length. */
+#define MBEDTLS_ERR_XTEA_HW_ACCEL_FAILED                  -0x0029  /**< XTEA hardware accelerator failed. */
 
 #if !defined(MBEDTLS_XTEA_ALT)
 // Regular implementation
diff --git a/library/CMakeLists.txt b/library/CMakeLists.txt
index e02229d..02ccea8 100644
--- a/library/CMakeLists.txt
+++ b/library/CMakeLists.txt
@@ -141,15 +141,15 @@
 
 if(USE_SHARED_MBEDTLS_LIBRARY)
     add_library(mbedcrypto SHARED ${src_crypto})
-    set_target_properties(mbedcrypto PROPERTIES VERSION 2.6.0 SOVERSION 0)
+    set_target_properties(mbedcrypto PROPERTIES VERSION 2.7.0 SOVERSION 1)
     target_link_libraries(mbedcrypto ${libs})
 
     add_library(mbedx509 SHARED ${src_x509})
-    set_target_properties(mbedx509 PROPERTIES VERSION 2.6.0 SOVERSION 0)
+    set_target_properties(mbedx509 PROPERTIES VERSION 2.7.0 SOVERSION 0)
     target_link_libraries(mbedx509 ${libs} mbedcrypto)
 
     add_library(mbedtls SHARED ${src_tls})
-    set_target_properties(mbedtls PROPERTIES VERSION 2.6.0 SOVERSION 10)
+    set_target_properties(mbedtls PROPERTIES VERSION 2.7.0 SOVERSION 10)
     target_link_libraries(mbedtls ${libs} mbedx509)
 
     install(TARGETS mbedtls mbedx509 mbedcrypto
diff --git a/library/Makefile b/library/Makefile
index 541d47f..65a102f 100644
--- a/library/Makefile
+++ b/library/Makefile
@@ -33,7 +33,7 @@
 
 SOEXT_TLS=so.10
 SOEXT_X509=so.0
-SOEXT_CRYPTO=so.0
+SOEXT_CRYPTO=so.1
 
 DLEXT=so
 # OSX shared library extension:
diff --git a/library/bignum.c b/library/bignum.c
index d3a150c..d27c130 100644
--- a/library/bignum.c
+++ b/library/bignum.c
@@ -63,6 +63,11 @@
     volatile mbedtls_mpi_uint *p = v; while( n-- ) *p++ = 0;
 }
 
+/* Implementation that should never be optimized out by the compiler */
+static void mbedtls_zeroize( void *v, size_t n ) {
+    volatile unsigned char *p = v; while( n-- ) *p++ = 0;
+}
+
 #define ciL    (sizeof(mbedtls_mpi_uint))         /* chars in limb  */
 #define biL    (ciL << 3)               /* bits  in limb  */
 #define biH    (ciL << 2)               /* half limb size */
@@ -672,16 +677,20 @@
 int mbedtls_mpi_read_binary( mbedtls_mpi *X, const unsigned char *buf, size_t buflen )
 {
     int ret;
-    size_t i, j, n;
+    size_t i, j;
+    size_t const limbs = CHARS_TO_LIMBS( buflen );
 
-    for( n = 0; n < buflen; n++ )
-        if( buf[n] != 0 )
-            break;
+    /* Ensure that target MPI has exactly the necessary number of limbs */
+    if( X->n != limbs )
+    {
+        mbedtls_mpi_free( X );
+        mbedtls_mpi_init( X );
+        MBEDTLS_MPI_CHK( mbedtls_mpi_grow( X, limbs ) );
+    }
 
-    MBEDTLS_MPI_CHK( mbedtls_mpi_grow( X, CHARS_TO_LIMBS( buflen - n ) ) );
     MBEDTLS_MPI_CHK( mbedtls_mpi_lset( X, 0 ) );
 
-    for( i = buflen, j = 0; i > n; i--, j++ )
+    for( i = buflen, j = 0; i > 0; i--, j++ )
         X->p[j / ciL] |= ((mbedtls_mpi_uint) buf[i - 1]) << ((j % ciL) << 3);
 
 cleanup:
@@ -1882,6 +1891,7 @@
     MBEDTLS_MPI_CHK( mbedtls_mpi_read_binary( X, buf, size ) );
 
 cleanup:
+    mbedtls_zeroize( buf, sizeof( buf ) );
     return( ret );
 }
 
diff --git a/library/cipher.c b/library/cipher.c
index e9e0b22..ff03273 100644
--- a/library/cipher.c
+++ b/library/cipher.c
@@ -516,14 +516,14 @@
     if( NULL == input || NULL == data_len )
         return( MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA );
 
-    bad = 0xFF;
+    bad = 0x80;
     *data_len = 0;
     for( i = input_len; i > 0; i-- )
     {
         prev_done = done;
-        done |= ( input[i-1] != 0 );
+        done |= ( input[i - 1] != 0 );
         *data_len |= ( i - 1 ) * ( done != prev_done );
-        bad &= ( input[i-1] ^ 0x80 ) | ( done == prev_done );
+        bad ^= input[i - 1] * ( done != prev_done );
     }
 
     return( MBEDTLS_ERR_CIPHER_INVALID_PADDING * ( bad != 0 ) );
diff --git a/library/ctr_drbg.c b/library/ctr_drbg.c
index 55612c7..ff532a0 100644
--- a/library/ctr_drbg.c
+++ b/library/ctr_drbg.c
@@ -19,7 +19,7 @@
  *  This file is part of mbed TLS (https://tls.mbed.org)
  */
 /*
- *  The NIST SP 800-90 DRBGs are described in the following publucation.
+ *  The NIST SP 800-90 DRBGs are described in the following publication.
  *
  *  http://csrc.nist.gov/publications/nistpubs/800-90/SP800-90revised_March2007.pdf
  */
@@ -94,11 +94,15 @@
     /*
      * Initialize with an empty key
      */
-    mbedtls_aes_setkey_enc( &ctx->aes_ctx, key, MBEDTLS_CTR_DRBG_KEYBITS );
+    if( ( ret = mbedtls_aes_setkey_enc( &ctx->aes_ctx, key, MBEDTLS_CTR_DRBG_KEYBITS ) ) != 0 )
+    {
+        return( ret );
+    }
 
     if( ( ret = mbedtls_ctr_drbg_reseed( ctx, custom, len ) ) != 0 )
+    {
         return( ret );
-
+    }
     return( 0 );
 }
 
@@ -148,6 +152,7 @@
     unsigned char chain[MBEDTLS_CTR_DRBG_BLOCKSIZE];
     unsigned char *p, *iv;
     mbedtls_aes_context aes_ctx;
+    int ret = 0;
 
     int i, j;
     size_t buf_len, use_len;
@@ -180,7 +185,10 @@
     for( i = 0; i < MBEDTLS_CTR_DRBG_KEYSIZE; i++ )
         key[i] = i;
 
-    mbedtls_aes_setkey_enc( &aes_ctx, key, MBEDTLS_CTR_DRBG_KEYBITS );
+    if( ( ret = mbedtls_aes_setkey_enc( &aes_ctx, key, MBEDTLS_CTR_DRBG_KEYBITS ) ) != 0 )
+    {
+        goto exit;
+    }
 
     /*
      * Reduce data to MBEDTLS_CTR_DRBG_SEEDLEN bytes of data
@@ -199,7 +207,10 @@
             use_len -= ( use_len >= MBEDTLS_CTR_DRBG_BLOCKSIZE ) ?
                        MBEDTLS_CTR_DRBG_BLOCKSIZE : use_len;
 
-            mbedtls_aes_crypt_ecb( &aes_ctx, MBEDTLS_AES_ENCRYPT, chain, chain );
+            if( ( ret = mbedtls_aes_crypt_ecb( &aes_ctx, MBEDTLS_AES_ENCRYPT, chain, chain ) ) != 0 )
+            {
+                goto exit;
+            }
         }
 
         memcpy( tmp + j, chain, MBEDTLS_CTR_DRBG_BLOCKSIZE );
@@ -213,20 +224,40 @@
     /*
      * Do final encryption with reduced data
      */
-    mbedtls_aes_setkey_enc( &aes_ctx, tmp, MBEDTLS_CTR_DRBG_KEYBITS );
+    if( ( ret = mbedtls_aes_setkey_enc( &aes_ctx, tmp, MBEDTLS_CTR_DRBG_KEYBITS ) ) != 0 )
+    {
+        goto exit;
+    }
     iv = tmp + MBEDTLS_CTR_DRBG_KEYSIZE;
     p = output;
 
     for( j = 0; j < MBEDTLS_CTR_DRBG_SEEDLEN; j += MBEDTLS_CTR_DRBG_BLOCKSIZE )
     {
-        mbedtls_aes_crypt_ecb( &aes_ctx, MBEDTLS_AES_ENCRYPT, iv, iv );
+        if( ( ret = mbedtls_aes_crypt_ecb( &aes_ctx, MBEDTLS_AES_ENCRYPT, iv, iv ) ) != 0 )
+        {
+            goto exit;
+        }
         memcpy( p, iv, MBEDTLS_CTR_DRBG_BLOCKSIZE );
         p += MBEDTLS_CTR_DRBG_BLOCKSIZE;
     }
-
+exit:
     mbedtls_aes_free( &aes_ctx );
+    /*
+    * tidy up the stack
+    */
+    mbedtls_zeroize( buf, sizeof( buf ) );
+    mbedtls_zeroize( tmp, sizeof( tmp ) );
+    mbedtls_zeroize( key, sizeof( key ) );
+    mbedtls_zeroize( chain, sizeof( chain ) );
+    if( 0 != ret )
+    {
+        /*
+        * wipe partial seed from memory
+        */
+        mbedtls_zeroize( output, MBEDTLS_CTR_DRBG_SEEDLEN );
+    }
 
-    return( 0 );
+    return( ret );
 }
 
 static int ctr_drbg_update_internal( mbedtls_ctr_drbg_context *ctx,
@@ -235,6 +266,7 @@
     unsigned char tmp[MBEDTLS_CTR_DRBG_SEEDLEN];
     unsigned char *p = tmp;
     int i, j;
+    int ret = 0;
 
     memset( tmp, 0, MBEDTLS_CTR_DRBG_SEEDLEN );
 
@@ -250,7 +282,10 @@
         /*
          * Crypt counter block
          */
-        mbedtls_aes_crypt_ecb( &ctx->aes_ctx, MBEDTLS_AES_ENCRYPT, ctx->counter, p );
+        if( ( ret = mbedtls_aes_crypt_ecb( &ctx->aes_ctx, MBEDTLS_AES_ENCRYPT, ctx->counter, p ) ) != 0 )
+        {
+            return( ret );
+        }
 
         p += MBEDTLS_CTR_DRBG_BLOCKSIZE;
     }
@@ -261,7 +296,10 @@
     /*
      * Update key and counter
      */
-    mbedtls_aes_setkey_enc( &ctx->aes_ctx, tmp, MBEDTLS_CTR_DRBG_KEYBITS );
+    if( ( ret = mbedtls_aes_setkey_enc( &ctx->aes_ctx, tmp, MBEDTLS_CTR_DRBG_KEYBITS ) ) != 0 )
+    {
+        return( ret );
+    }
     memcpy( ctx->counter, tmp + MBEDTLS_CTR_DRBG_KEYSIZE, MBEDTLS_CTR_DRBG_BLOCKSIZE );
 
     return( 0 );
@@ -289,6 +327,7 @@
 {
     unsigned char seed[MBEDTLS_CTR_DRBG_MAX_SEED_INPUT];
     size_t seedlen = 0;
+    int ret;
 
     if( ctx->entropy_len > MBEDTLS_CTR_DRBG_MAX_SEED_INPUT ||
         len > MBEDTLS_CTR_DRBG_MAX_SEED_INPUT - ctx->entropy_len )
@@ -319,12 +358,18 @@
     /*
      * Reduce to 384 bits
      */
-    block_cipher_df( seed, seed, seedlen );
+    if( ( ret = block_cipher_df( seed, seed, seedlen ) ) != 0 )
+    {
+        return( ret );
+    }
 
     /*
      * Update state
      */
-    ctr_drbg_update_internal( ctx, seed );
+    if( ( ret = ctr_drbg_update_internal( ctx, seed ) ) != 0 )
+    {
+        return( ret );
+    }
     ctx->reseed_counter = 1;
 
     return( 0 );
@@ -354,15 +399,22 @@
         ctx->prediction_resistance )
     {
         if( ( ret = mbedtls_ctr_drbg_reseed( ctx, additional, add_len ) ) != 0 )
+        {
             return( ret );
-
+        }
         add_len = 0;
     }
 
     if( add_len > 0 )
     {
-        block_cipher_df( add_input, additional, add_len );
-        ctr_drbg_update_internal( ctx, add_input );
+        if( ( ret = block_cipher_df( add_input, additional, add_len ) ) != 0 )
+        {
+            return( ret );
+        }
+        if( ( ret = ctr_drbg_update_internal( ctx, add_input ) ) != 0 )
+        {
+            return( ret );
+        }
     }
 
     while( output_len > 0 )
@@ -377,7 +429,10 @@
         /*
          * Crypt counter block
          */
-        mbedtls_aes_crypt_ecb( &ctx->aes_ctx, MBEDTLS_AES_ENCRYPT, ctx->counter, tmp );
+        if( ( ret = mbedtls_aes_crypt_ecb( &ctx->aes_ctx, MBEDTLS_AES_ENCRYPT, ctx->counter, tmp ) ) != 0 )
+        {
+            return( ret );
+        }
 
         use_len = ( output_len > MBEDTLS_CTR_DRBG_BLOCKSIZE ) ? MBEDTLS_CTR_DRBG_BLOCKSIZE :
                                                        output_len;
@@ -389,7 +444,10 @@
         output_len -= use_len;
     }
 
-    ctr_drbg_update_internal( ctx, add_input );
+    if( ( ret = ctr_drbg_update_internal( ctx, add_input ) ) != 0 )
+    {
+        return( ret );
+    }
 
     ctx->reseed_counter++;
 
@@ -430,20 +488,20 @@
         goto exit;
 
     if( fwrite( buf, 1, MBEDTLS_CTR_DRBG_MAX_INPUT, f ) != MBEDTLS_CTR_DRBG_MAX_INPUT )
-    {
         ret = MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR;
-        goto exit;
-    }
-
-    ret = 0;
+    else
+        ret = 0;
 
 exit:
+    mbedtls_zeroize( buf, sizeof( buf ) );
+
     fclose( f );
     return( ret );
 }
 
 int mbedtls_ctr_drbg_update_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path )
 {
+    int ret = 0;
     FILE *f;
     size_t n;
     unsigned char buf[ MBEDTLS_CTR_DRBG_MAX_INPUT ];
@@ -462,14 +520,16 @@
     }
 
     if( fread( buf, 1, n, f ) != n )
-    {
-        fclose( f );
-        return( MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR );
-    }
+        ret = MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR;
+    else
+        mbedtls_ctr_drbg_update( ctx, buf, n );
 
     fclose( f );
 
-    mbedtls_ctr_drbg_update( ctx, buf, n );
+    mbedtls_zeroize( buf, sizeof( buf ) );
+
+    if( ret != 0 )
+        return( ret );
 
     return( mbedtls_ctr_drbg_write_seed_file( ctx, path ) );
 }
diff --git a/library/dhm.c b/library/dhm.c
index bec52a1..28ac310 100644
--- a/library/dhm.c
+++ b/library/dhm.c
@@ -57,6 +57,7 @@
 #define mbedtls_free       free
 #endif
 
+#if !defined(MBEDTLS_DHM_ALT)
 /* Implementation that should never be optimized out by the compiler */
 static void mbedtls_zeroize( void *v, size_t n ) {
     volatile unsigned char *p = v; while( n-- ) *p++ = 0;
@@ -93,6 +94,9 @@
  *
  * Parameter should be: 2 <= public_param <= P - 2
  *
+ * This means that we need to return an error if
+ *              public_param < 2 or public_param > P-2
+ *
  * For more information on the attack, see:
  *  http://www.cl.cam.ac.uk/~rja14/Papers/psandqs.pdf
  *  http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2005-2643
@@ -100,17 +104,17 @@
 static int dhm_check_range( const mbedtls_mpi *param, const mbedtls_mpi *P )
 {
     mbedtls_mpi L, U;
-    int ret = MBEDTLS_ERR_DHM_BAD_INPUT_DATA;
+    int ret = 0;
 
     mbedtls_mpi_init( &L ); mbedtls_mpi_init( &U );
 
     MBEDTLS_MPI_CHK( mbedtls_mpi_lset( &L, 2 ) );
     MBEDTLS_MPI_CHK( mbedtls_mpi_sub_int( &U, P, 2 ) );
 
-    if( mbedtls_mpi_cmp_mpi( param, &L ) >= 0 &&
-        mbedtls_mpi_cmp_mpi( param, &U ) <= 0 )
+    if( mbedtls_mpi_cmp_mpi( param, &L ) < 0 ||
+        mbedtls_mpi_cmp_mpi( param, &U ) > 0 )
     {
-        ret = 0;
+        ret = MBEDTLS_ERR_DHM_BAD_INPUT_DATA;
     }
 
 cleanup:
@@ -187,10 +191,15 @@
     /*
      * export P, G, GX
      */
-#define DHM_MPI_EXPORT(X,n)                     \
-    MBEDTLS_MPI_CHK( mbedtls_mpi_write_binary( X, p + 2, n ) ); \
-    *p++ = (unsigned char)( n >> 8 );           \
-    *p++ = (unsigned char)( n      ); p += n;
+#define DHM_MPI_EXPORT( X, n )                                          \
+    do {                                                                \
+        MBEDTLS_MPI_CHK( mbedtls_mpi_write_binary( ( X ),               \
+                                                   p + 2,               \
+                                                   ( n ) ) );           \
+        *p++ = (unsigned char)( ( n ) >> 8 );                           \
+        *p++ = (unsigned char)( ( n )      );                           \
+        p += ( n );                                                     \
+    } while( 0 )
 
     n1 = mbedtls_mpi_size( &ctx->P  );
     n2 = mbedtls_mpi_size( &ctx->G  );
@@ -201,7 +210,7 @@
     DHM_MPI_EXPORT( &ctx->G , n2 );
     DHM_MPI_EXPORT( &ctx->GX, n3 );
 
-    *olen  = p - output;
+    *olen = p - output;
 
     ctx->len = n1;
 
@@ -214,6 +223,28 @@
 }
 
 /*
+ * Set prime modulus and generator
+ */
+int mbedtls_dhm_set_group( mbedtls_dhm_context *ctx,
+                           const mbedtls_mpi *P,
+                           const mbedtls_mpi *G )
+{
+    int ret;
+
+    if( ctx == NULL || P == NULL || G == NULL )
+        return( MBEDTLS_ERR_DHM_BAD_INPUT_DATA );
+
+    if( ( ret = mbedtls_mpi_copy( &ctx->P, P ) ) != 0 ||
+        ( ret = mbedtls_mpi_copy( &ctx->G, G ) ) != 0 )
+    {
+        return( MBEDTLS_ERR_DHM_SET_GROUP_FAILED + ret );
+    }
+
+    ctx->len = mbedtls_mpi_size( &ctx->P );
+    return( 0 );
+}
+
+/*
  * Import the peer's public value G^Y
  */
 int mbedtls_dhm_read_public( mbedtls_dhm_context *ctx,
@@ -400,10 +431,11 @@
  */
 void mbedtls_dhm_free( mbedtls_dhm_context *ctx )
 {
-    mbedtls_mpi_free( &ctx->pX); mbedtls_mpi_free( &ctx->Vf ); mbedtls_mpi_free( &ctx->Vi );
-    mbedtls_mpi_free( &ctx->RP ); mbedtls_mpi_free( &ctx->K ); mbedtls_mpi_free( &ctx->GY );
-    mbedtls_mpi_free( &ctx->GX ); mbedtls_mpi_free( &ctx->X ); mbedtls_mpi_free( &ctx->G );
-    mbedtls_mpi_free( &ctx->P );
+    mbedtls_mpi_free( &ctx->pX ); mbedtls_mpi_free( &ctx->Vf );
+    mbedtls_mpi_free( &ctx->Vi ); mbedtls_mpi_free( &ctx->RP );
+    mbedtls_mpi_free( &ctx->K  ); mbedtls_mpi_free( &ctx->GY );
+    mbedtls_mpi_free( &ctx->GX ); mbedtls_mpi_free( &ctx->X  );
+    mbedtls_mpi_free( &ctx->G  ); mbedtls_mpi_free( &ctx->P  );
 
     mbedtls_zeroize( ctx, sizeof( mbedtls_dhm_context ) );
 }
@@ -542,7 +574,10 @@
     if( fread( *buf, 1, *n, f ) != *n )
     {
         fclose( f );
+
+        mbedtls_zeroize( *buf, *n + 1 );
         mbedtls_free( *buf );
+
         return( MBEDTLS_ERR_DHM_FILE_IO_ERROR );
     }
 
@@ -577,6 +612,7 @@
 }
 #endif /* MBEDTLS_FS_IO */
 #endif /* MBEDTLS_ASN1_PARSE_C */
+#endif /* MBEDTLS_DHM_ALT */
 
 #if defined(MBEDTLS_SELF_TEST)
 
diff --git a/library/ecjpake.c b/library/ecjpake.c
index 1fa1c2d..e8f4086 100644
--- a/library/ecjpake.c
+++ b/library/ecjpake.c
@@ -36,6 +36,8 @@
 
 #include <string.h>
 
+#if !defined(MBEDTLS_ECJPAKE_ALT)
+
 /*
  * Convert a mbedtls_ecjpake_role to identifier string
  */
@@ -764,6 +766,7 @@
 #undef ID_MINE
 #undef ID_PEER
 
+#endif /* ! MBEDTLS_ECJPAKE_ALT */
 
 #if defined(MBEDTLS_SELF_TEST)
 
diff --git a/library/ecp.c b/library/ecp.c
index 5ad6863..b41baef 100644
--- a/library/ecp.c
+++ b/library/ecp.c
@@ -1953,7 +1953,6 @@
     {
         /* SEC1 3.2.1: Generate d such that 1 <= n < N */
         int count = 0;
-        unsigned char rnd[MBEDTLS_ECP_MAX_BYTES];
 
         /*
          * Match the procedure given in RFC 6979 (deterministic ECDSA):
@@ -1964,8 +1963,7 @@
          */
         do
         {
-            MBEDTLS_MPI_CHK( f_rng( p_rng, rnd, n_size ) );
-            MBEDTLS_MPI_CHK( mbedtls_mpi_read_binary( d, rnd, n_size ) );
+            MBEDTLS_MPI_CHK( mbedtls_mpi_fill_random( d, n_size, f_rng, p_rng ) );
             MBEDTLS_MPI_CHK( mbedtls_mpi_shift_r( d, 8 * n_size - grp->nbits ) );
 
             /*
diff --git a/library/entropy.c b/library/entropy.c
index bf943aa..e17512e 100644
--- a/library/entropy.c
+++ b/library/entropy.c
@@ -68,16 +68,18 @@
 
 void mbedtls_entropy_init( mbedtls_entropy_context *ctx )
 {
-    memset( ctx, 0, sizeof(mbedtls_entropy_context) );
+    ctx->source_count = 0;
+    memset( ctx->source, 0, sizeof( ctx->source ) );
 
 #if defined(MBEDTLS_THREADING_C)
     mbedtls_mutex_init( &ctx->mutex );
 #endif
 
+    ctx->accumulator_started = 0;
 #if defined(MBEDTLS_ENTROPY_SHA512_ACCUMULATOR)
-    mbedtls_sha512_starts( &ctx->accumulator, 0 );
+    mbedtls_sha512_init( &ctx->accumulator );
 #else
-    mbedtls_sha256_starts( &ctx->accumulator, 0 );
+    mbedtls_sha256_init( &ctx->accumulator );
 #endif
 #if defined(MBEDTLS_HAVEGE_C)
     mbedtls_havege_init( &ctx->havege_data );
@@ -116,6 +118,7 @@
     mbedtls_entropy_add_source( ctx, mbedtls_nv_seed_poll, NULL,
                                 MBEDTLS_ENTROPY_BLOCK_SIZE,
                                 MBEDTLS_ENTROPY_SOURCE_STRONG );
+    ctx->initial_entropy_run = 0;
 #endif
 #endif /* MBEDTLS_NO_DEFAULT_ENTROPY_SOURCES */
 }
@@ -128,7 +131,17 @@
 #if defined(MBEDTLS_THREADING_C)
     mbedtls_mutex_free( &ctx->mutex );
 #endif
-    mbedtls_zeroize( ctx, sizeof( mbedtls_entropy_context ) );
+#if defined(MBEDTLS_ENTROPY_SHA512_ACCUMULATOR)
+    mbedtls_sha512_free( &ctx->accumulator );
+#else
+    mbedtls_sha256_free( &ctx->accumulator );
+#endif
+#if defined(MBEDTLS_ENTROPY_NV_SEED)
+    ctx->initial_entropy_run = 0;
+#endif
+    ctx->source_count = 0;
+    mbedtls_zeroize( ctx->source, sizeof( ctx->source ) );
+    ctx->accumulator_started = 0;
 }
 
 int mbedtls_entropy_add_source( mbedtls_entropy_context *ctx,
@@ -175,13 +188,16 @@
     unsigned char tmp[MBEDTLS_ENTROPY_BLOCK_SIZE];
     size_t use_len = len;
     const unsigned char *p = data;
+    int ret = 0;
 
     if( use_len > MBEDTLS_ENTROPY_BLOCK_SIZE )
     {
 #if defined(MBEDTLS_ENTROPY_SHA512_ACCUMULATOR)
-        mbedtls_sha512( data, len, tmp, 0 );
+        if( ( ret = mbedtls_sha512_ret( data, len, tmp, 0 ) ) != 0 )
+            goto cleanup;
 #else
-        mbedtls_sha256( data, len, tmp, 0 );
+        if( ( ret = mbedtls_sha256_ret( data, len, tmp, 0 ) ) != 0 )
+            goto cleanup;
 #endif
         p = tmp;
         use_len = MBEDTLS_ENTROPY_BLOCK_SIZE;
@@ -190,15 +206,35 @@
     header[0] = source_id;
     header[1] = use_len & 0xFF;
 
+    /*
+     * Start the accumulator if this has not already happened. Note that
+     * it is sufficient to start the accumulator here only because all calls to
+     * gather entropy eventually execute this code.
+     */
 #if defined(MBEDTLS_ENTROPY_SHA512_ACCUMULATOR)
-    mbedtls_sha512_update( &ctx->accumulator, header, 2 );
-    mbedtls_sha512_update( &ctx->accumulator, p, use_len );
+    if( ctx->accumulator_started == 0 &&
+        ( ret = mbedtls_sha512_starts_ret( &ctx->accumulator, 0 ) ) != 0 )
+        goto cleanup;
+    else
+        ctx->accumulator_started = 1;
+    if( ( ret = mbedtls_sha512_update_ret( &ctx->accumulator, header, 2 ) ) != 0 )
+        goto cleanup;
+    ret = mbedtls_sha512_update_ret( &ctx->accumulator, p, use_len );
 #else
-    mbedtls_sha256_update( &ctx->accumulator, header, 2 );
-    mbedtls_sha256_update( &ctx->accumulator, p, use_len );
+    if( ctx->accumulator_started == 0 &&
+        ( ret = mbedtls_sha256_starts_ret( &ctx->accumulator, 0 ) ) != 0 )
+        goto cleanup;
+    else
+        ctx->accumulator_started = 1;
+    if( ( ret = mbedtls_sha256_update_ret( &ctx->accumulator, header, 2 ) ) != 0 )
+        goto cleanup;
+    ret = mbedtls_sha256_update_ret( &ctx->accumulator, p, use_len );
 #endif
 
-    return( 0 );
+cleanup:
+    mbedtls_zeroize( tmp, sizeof( tmp ) );
+
+    return( ret );
 }
 
 int mbedtls_entropy_update_manual( mbedtls_entropy_context *ctx,
@@ -245,7 +281,7 @@
         if( ( ret = ctx->source[i].f_source( ctx->source[i].p_source,
                         buf, MBEDTLS_ENTROPY_MAX_GATHER, &olen ) ) != 0 )
         {
-            return( ret );
+            goto cleanup;
         }
 
         /*
@@ -253,15 +289,20 @@
          */
         if( olen > 0 )
         {
-            entropy_update( ctx, (unsigned char) i, buf, olen );
+            if( ( ret = entropy_update( ctx, (unsigned char) i,
+                                        buf, olen ) ) != 0 )
+                return( ret );
             ctx->source[i].size += olen;
         }
     }
 
     if( have_one_strong == 0 )
-        return( MBEDTLS_ERR_ENTROPY_NO_STRONG_SOURCE );
+        ret = MBEDTLS_ERR_ENTROPY_NO_STRONG_SOURCE;
 
-    return( 0 );
+cleanup:
+    mbedtls_zeroize( buf, sizeof( buf ) );
+
+    return( ret );
 }
 
 /*
@@ -336,33 +377,52 @@
     memset( buf, 0, MBEDTLS_ENTROPY_BLOCK_SIZE );
 
 #if defined(MBEDTLS_ENTROPY_SHA512_ACCUMULATOR)
-    mbedtls_sha512_finish( &ctx->accumulator, buf );
+    /*
+     * Note that at this stage it is assumed that the accumulator was started
+     * in a previous call to entropy_update(). If this is not guaranteed, the
+     * code below will fail.
+     */
+    if( ( ret = mbedtls_sha512_finish_ret( &ctx->accumulator, buf ) ) != 0 )
+        goto exit;
 
     /*
      * Reset accumulator and counters and recycle existing entropy
      */
-    memset( &ctx->accumulator, 0, sizeof( mbedtls_sha512_context ) );
-    mbedtls_sha512_starts( &ctx->accumulator, 0 );
-    mbedtls_sha512_update( &ctx->accumulator, buf, MBEDTLS_ENTROPY_BLOCK_SIZE );
+    mbedtls_sha512_free( &ctx->accumulator );
+    mbedtls_sha512_init( &ctx->accumulator );
+    if( ( ret = mbedtls_sha512_starts_ret( &ctx->accumulator, 0 ) ) != 0 )
+        goto exit;
+    if( ( ret = mbedtls_sha512_update_ret( &ctx->accumulator, buf,
+                                           MBEDTLS_ENTROPY_BLOCK_SIZE ) ) != 0 )
+        goto exit;
 
     /*
      * Perform second SHA-512 on entropy
      */
-    mbedtls_sha512( buf, MBEDTLS_ENTROPY_BLOCK_SIZE, buf, 0 );
+    if( ( ret = mbedtls_sha512_ret( buf, MBEDTLS_ENTROPY_BLOCK_SIZE,
+                                    buf, 0 ) ) != 0 )
+        goto exit;
 #else /* MBEDTLS_ENTROPY_SHA512_ACCUMULATOR */
-    mbedtls_sha256_finish( &ctx->accumulator, buf );
+    if( ( ret = mbedtls_sha256_finish_ret( &ctx->accumulator, buf ) ) != 0 )
+        goto exit;
 
     /*
      * Reset accumulator and counters and recycle existing entropy
      */
-    memset( &ctx->accumulator, 0, sizeof( mbedtls_sha256_context ) );
-    mbedtls_sha256_starts( &ctx->accumulator, 0 );
-    mbedtls_sha256_update( &ctx->accumulator, buf, MBEDTLS_ENTROPY_BLOCK_SIZE );
+    mbedtls_sha256_free( &ctx->accumulator );
+    mbedtls_sha256_init( &ctx->accumulator );
+    if( ( ret = mbedtls_sha256_starts_ret( &ctx->accumulator, 0 ) ) != 0 )
+        goto exit;
+    if( ( ret = mbedtls_sha256_update_ret( &ctx->accumulator, buf,
+                                           MBEDTLS_ENTROPY_BLOCK_SIZE ) ) != 0 )
+        goto exit;
 
     /*
      * Perform second SHA-256 on entropy
      */
-    mbedtls_sha256( buf, MBEDTLS_ENTROPY_BLOCK_SIZE, buf, 0 );
+    if( ( ret = mbedtls_sha256_ret( buf, MBEDTLS_ENTROPY_BLOCK_SIZE,
+                                    buf, 0 ) ) != 0 )
+        goto exit;
 #endif /* MBEDTLS_ENTROPY_SHA512_ACCUMULATOR */
 
     for( i = 0; i < ctx->source_count; i++ )
@@ -373,6 +433,8 @@
     ret = 0;
 
 exit:
+    mbedtls_zeroize( buf, sizeof( buf ) );
+
 #if defined(MBEDTLS_THREADING_C)
     if( mbedtls_mutex_unlock( &ctx->mutex ) != 0 )
         return( MBEDTLS_ERR_THREADING_MUTEX_ERROR );
@@ -385,7 +447,7 @@
 int mbedtls_entropy_update_nv_seed( mbedtls_entropy_context *ctx )
 {
     int ret = MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR;
-    unsigned char buf[ MBEDTLS_ENTROPY_MAX_SEED_SIZE ];
+    unsigned char buf[MBEDTLS_ENTROPY_BLOCK_SIZE];
 
     /* Read new seed  and write it to NV */
     if( ( ret = mbedtls_entropy_func( ctx, buf, MBEDTLS_ENTROPY_BLOCK_SIZE ) ) != 0 )
@@ -396,9 +458,9 @@
 
     /* Manually update the remaining stream with a separator value to diverge */
     memset( buf, 0, MBEDTLS_ENTROPY_BLOCK_SIZE );
-    mbedtls_entropy_update_manual( ctx, buf, MBEDTLS_ENTROPY_BLOCK_SIZE );
+    ret = mbedtls_entropy_update_manual( ctx, buf, MBEDTLS_ENTROPY_BLOCK_SIZE );
 
-    return( 0 );
+    return( ret );
 }
 #endif /* MBEDTLS_ENTROPY_NV_SEED */
 
@@ -424,12 +486,15 @@
     ret = 0;
 
 exit:
+    mbedtls_zeroize( buf, sizeof( buf ) );
+
     fclose( f );
     return( ret );
 }
 
 int mbedtls_entropy_update_seed_file( mbedtls_entropy_context *ctx, const char *path )
 {
+    int ret = 0;
     FILE *f;
     size_t n;
     unsigned char buf[ MBEDTLS_ENTROPY_MAX_SEED_SIZE ];
@@ -445,14 +510,16 @@
         n = MBEDTLS_ENTROPY_MAX_SEED_SIZE;
 
     if( fread( buf, 1, n, f ) != n )
-    {
-        fclose( f );
-        return( MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR );
-    }
+        ret = MBEDTLS_ERR_ENTROPY_FILE_IO_ERROR;
+    else
+        ret = mbedtls_entropy_update_manual( ctx, buf, n );
 
     fclose( f );
 
-    mbedtls_entropy_update_manual( ctx, buf, n );
+    mbedtls_zeroize( buf, sizeof( buf ) );
+
+    if( ret != 0 )
+        return( ret );
 
     return( mbedtls_entropy_write_seed_file( ctx, path ) );
 }
diff --git a/library/error.c b/library/error.c
index 151ca4e..0292480 100644
--- a/library/error.c
+++ b/library/error.c
@@ -45,6 +45,10 @@
 #include "mbedtls/aes.h"
 #endif
 
+#if defined(MBEDTLS_ARC4_C)
+#include "mbedtls/arc4.h"
+#endif
+
 #if defined(MBEDTLS_BASE64_C)
 #include "mbedtls/base64.h"
 #endif
@@ -69,6 +73,10 @@
 #include "mbedtls/cipher.h"
 #endif
 
+#if defined(MBEDTLS_CMAC_C)
+#include "mbedtls/cmac.h"
+#endif
+
 #if defined(MBEDTLS_CTR_DRBG_C)
 #include "mbedtls/ctr_drbg.h"
 #endif
@@ -101,6 +109,18 @@
 #include "mbedtls/md.h"
 #endif
 
+#if defined(MBEDTLS_MD2_C)
+#include "mbedtls/md2.h"
+#endif
+
+#if defined(MBEDTLS_MD4_C)
+#include "mbedtls/md4.h"
+#endif
+
+#if defined(MBEDTLS_MD5_C)
+#include "mbedtls/md5.h"
+#endif
+
 #if defined(MBEDTLS_NET_C)
 #include "mbedtls/net_sockets.h"
 #endif
@@ -129,10 +149,26 @@
 #include "mbedtls/pkcs5.h"
 #endif
 
+#if defined(MBEDTLS_RIPEMD160_C)
+#include "mbedtls/ripemd160.h"
+#endif
+
 #if defined(MBEDTLS_RSA_C)
 #include "mbedtls/rsa.h"
 #endif
 
+#if defined(MBEDTLS_SHA1_C)
+#include "mbedtls/sha1.h"
+#endif
+
+#if defined(MBEDTLS_SHA256_C)
+#include "mbedtls/sha256.h"
+#endif
+
+#if defined(MBEDTLS_SHA512_C)
+#include "mbedtls/sha512.h"
+#endif
+
 #if defined(MBEDTLS_SSL_TLS_C)
 #include "mbedtls/ssl.h"
 #endif
@@ -174,7 +210,7 @@
         if( use_ret == -(MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE) )
             mbedtls_snprintf( buf, buflen, "CIPHER - The selected feature is not available" );
         if( use_ret == -(MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA) )
-            mbedtls_snprintf( buf, buflen, "CIPHER - Bad input parameters to function" );
+            mbedtls_snprintf( buf, buflen, "CIPHER - Bad input parameters" );
         if( use_ret == -(MBEDTLS_ERR_CIPHER_ALLOC_FAILED) )
             mbedtls_snprintf( buf, buflen, "CIPHER - Failed to allocate memory" );
         if( use_ret == -(MBEDTLS_ERR_CIPHER_INVALID_PADDING) )
@@ -184,12 +220,14 @@
         if( use_ret == -(MBEDTLS_ERR_CIPHER_AUTH_FAILED) )
             mbedtls_snprintf( buf, buflen, "CIPHER - Authentication failed (for AEAD modes)" );
         if( use_ret == -(MBEDTLS_ERR_CIPHER_INVALID_CONTEXT) )
-            mbedtls_snprintf( buf, buflen, "CIPHER - The context is invalid, eg because it was free()ed" );
+            mbedtls_snprintf( buf, buflen, "CIPHER - The context is invalid. For example, because it was freed" );
+        if( use_ret == -(MBEDTLS_ERR_CIPHER_HW_ACCEL_FAILED) )
+            mbedtls_snprintf( buf, buflen, "CIPHER - Cipher hardware accelerator failed" );
 #endif /* MBEDTLS_CIPHER_C */
 
 #if defined(MBEDTLS_DHM_C)
         if( use_ret == -(MBEDTLS_ERR_DHM_BAD_INPUT_DATA) )
-            mbedtls_snprintf( buf, buflen, "DHM - Bad input parameters to function" );
+            mbedtls_snprintf( buf, buflen, "DHM - Bad input parameters" );
         if( use_ret == -(MBEDTLS_ERR_DHM_READ_PARAMS_FAILED) )
             mbedtls_snprintf( buf, buflen, "DHM - Reading of the DHM parameters failed" );
         if( use_ret == -(MBEDTLS_ERR_DHM_MAKE_PARAMS_FAILED) )
@@ -205,7 +243,11 @@
         if( use_ret == -(MBEDTLS_ERR_DHM_ALLOC_FAILED) )
             mbedtls_snprintf( buf, buflen, "DHM - Allocation of memory failed" );
         if( use_ret == -(MBEDTLS_ERR_DHM_FILE_IO_ERROR) )
-            mbedtls_snprintf( buf, buflen, "DHM - Read/write of file failed" );
+            mbedtls_snprintf( buf, buflen, "DHM - Read or write of file failed" );
+        if( use_ret == -(MBEDTLS_ERR_DHM_HW_ACCEL_FAILED) )
+            mbedtls_snprintf( buf, buflen, "DHM - DHM hardware accelerator failed" );
+        if( use_ret == -(MBEDTLS_ERR_DHM_SET_GROUP_FAILED) )
+            mbedtls_snprintf( buf, buflen, "DHM - Setting the modulus and generator failed" );
 #endif /* MBEDTLS_DHM_C */
 
 #if defined(MBEDTLS_ECP_C)
@@ -225,6 +267,8 @@
             mbedtls_snprintf( buf, buflen, "ECP - Invalid private or public key" );
         if( use_ret == -(MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH) )
             mbedtls_snprintf( buf, buflen, "ECP - Signature is valid but shorter than the user-supplied length" );
+        if( use_ret == -(MBEDTLS_ERR_ECP_HW_ACCEL_FAILED) )
+            mbedtls_snprintf( buf, buflen, "ECP - ECP hardware accelerator failed" );
 #endif /* MBEDTLS_ECP_C */
 
 #if defined(MBEDTLS_MD_C)
@@ -236,6 +280,8 @@
             mbedtls_snprintf( buf, buflen, "MD - Failed to allocate memory" );
         if( use_ret == -(MBEDTLS_ERR_MD_FILE_IO_ERROR) )
             mbedtls_snprintf( buf, buflen, "MD - Opening or reading of file failed" );
+        if( use_ret == -(MBEDTLS_ERR_MD_HW_ACCEL_FAILED) )
+            mbedtls_snprintf( buf, buflen, "MD - MD hardware accelerator failed" );
 #endif /* MBEDTLS_MD_C */
 
 #if defined(MBEDTLS_PEM_PARSE_C) || defined(MBEDTLS_PEM_WRITE_C)
@@ -288,6 +334,8 @@
             mbedtls_snprintf( buf, buflen, "PK - Unavailable feature, e.g. RSA disabled for RSA key" );
         if( use_ret == -(MBEDTLS_ERR_PK_SIG_LEN_MISMATCH) )
             mbedtls_snprintf( buf, buflen, "PK - The signature is valid but its length is less than expected" );
+        if( use_ret == -(MBEDTLS_ERR_PK_HW_ACCEL_FAILED) )
+            mbedtls_snprintf( buf, buflen, "PK - PK hardware accelerator failed" );
 #endif /* MBEDTLS_PK_C */
 
 #if defined(MBEDTLS_PKCS12_C)
@@ -320,7 +368,7 @@
         if( use_ret == -(MBEDTLS_ERR_RSA_KEY_GEN_FAILED) )
             mbedtls_snprintf( buf, buflen, "RSA - Something failed during generation of a key" );
         if( use_ret == -(MBEDTLS_ERR_RSA_KEY_CHECK_FAILED) )
-            mbedtls_snprintf( buf, buflen, "RSA - Key failed to pass the library's validity check" );
+            mbedtls_snprintf( buf, buflen, "RSA - Key failed to pass the validity check of the library" );
         if( use_ret == -(MBEDTLS_ERR_RSA_PUBLIC_FAILED) )
             mbedtls_snprintf( buf, buflen, "RSA - The public key operation failed" );
         if( use_ret == -(MBEDTLS_ERR_RSA_PRIVATE_FAILED) )
@@ -332,7 +380,9 @@
         if( use_ret == -(MBEDTLS_ERR_RSA_RNG_FAILED) )
             mbedtls_snprintf( buf, buflen, "RSA - The random generator failed to generate non-zeros" );
         if( use_ret == -(MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION) )
-            mbedtls_snprintf( buf, buflen, "RSA - The implementation doesn't offer the requested operation, e.g. because of security violations or lack of functionality" );
+            mbedtls_snprintf( buf, buflen, "RSA - The implementation does not offer the requested operation, for example, because of security violations or lack of functionality" );
+        if( use_ret == -(MBEDTLS_ERR_RSA_HW_ACCEL_FAILED) )
+            mbedtls_snprintf( buf, buflen, "RSA - RSA hardware accelerator failed" );
 #endif /* MBEDTLS_RSA_C */
 
 #if defined(MBEDTLS_SSL_TLS_C)
@@ -521,9 +571,16 @@
     if( use_ret == -(MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH) )
         mbedtls_snprintf( buf, buflen, "AES - Invalid data input length" );
     if( use_ret == -(MBEDTLS_ERR_AES_FEATURE_UNAVAILABLE) )
-        mbedtls_snprintf( buf, buflen, "AES - Feature not available, e.g. unsupported AES key size" );
+        mbedtls_snprintf( buf, buflen, "AES - Feature not available. For example, an unsupported AES key size" );
+    if( use_ret == -(MBEDTLS_ERR_AES_HW_ACCEL_FAILED) )
+        mbedtls_snprintf( buf, buflen, "AES - AES hardware accelerator failed" );
 #endif /* MBEDTLS_AES_C */
 
+#if defined(MBEDTLS_ARC4_C)
+    if( use_ret == -(MBEDTLS_ERR_ARC4_HW_ACCEL_FAILED) )
+        mbedtls_snprintf( buf, buflen, "ARC4 - ARC4 hardware accelerator failed" );
+#endif /* MBEDTLS_ARC4_C */
+
 #if defined(MBEDTLS_ASN1_PARSE_C)
     if( use_ret == -(MBEDTLS_ERR_ASN1_OUT_OF_DATA) )
         mbedtls_snprintf( buf, buflen, "ASN1 - Out of data when parsing an ASN1 data structure" );
@@ -570,6 +627,8 @@
 #if defined(MBEDTLS_BLOWFISH_C)
     if( use_ret == -(MBEDTLS_ERR_BLOWFISH_INVALID_KEY_LENGTH) )
         mbedtls_snprintf( buf, buflen, "BLOWFISH - Invalid key length" );
+    if( use_ret == -(MBEDTLS_ERR_BLOWFISH_HW_ACCEL_FAILED) )
+        mbedtls_snprintf( buf, buflen, "BLOWFISH - Blowfish hardware accelerator failed" );
     if( use_ret == -(MBEDTLS_ERR_BLOWFISH_INVALID_INPUT_LENGTH) )
         mbedtls_snprintf( buf, buflen, "BLOWFISH - Invalid data input length" );
 #endif /* MBEDTLS_BLOWFISH_C */
@@ -579,29 +638,40 @@
         mbedtls_snprintf( buf, buflen, "CAMELLIA - Invalid key length" );
     if( use_ret == -(MBEDTLS_ERR_CAMELLIA_INVALID_INPUT_LENGTH) )
         mbedtls_snprintf( buf, buflen, "CAMELLIA - Invalid data input length" );
+    if( use_ret == -(MBEDTLS_ERR_CAMELLIA_HW_ACCEL_FAILED) )
+        mbedtls_snprintf( buf, buflen, "CAMELLIA - Camellia hardware accelerator failed" );
 #endif /* MBEDTLS_CAMELLIA_C */
 
 #if defined(MBEDTLS_CCM_C)
     if( use_ret == -(MBEDTLS_ERR_CCM_BAD_INPUT) )
-        mbedtls_snprintf( buf, buflen, "CCM - Bad input parameters to function" );
+        mbedtls_snprintf( buf, buflen, "CCM - Bad input parameters to the function" );
     if( use_ret == -(MBEDTLS_ERR_CCM_AUTH_FAILED) )
         mbedtls_snprintf( buf, buflen, "CCM - Authenticated decryption failed" );
+    if( use_ret == -(MBEDTLS_ERR_CCM_HW_ACCEL_FAILED) )
+        mbedtls_snprintf( buf, buflen, "CCM - CCM hardware accelerator failed" );
 #endif /* MBEDTLS_CCM_C */
 
+#if defined(MBEDTLS_CMAC_C)
+    if( use_ret == -(MBEDTLS_ERR_CMAC_HW_ACCEL_FAILED) )
+        mbedtls_snprintf( buf, buflen, "CMAC - CMAC hardware accelerator failed" );
+#endif /* MBEDTLS_CMAC_C */
+
 #if defined(MBEDTLS_CTR_DRBG_C)
     if( use_ret == -(MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED) )
         mbedtls_snprintf( buf, buflen, "CTR_DRBG - The entropy source failed" );
     if( use_ret == -(MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG) )
-        mbedtls_snprintf( buf, buflen, "CTR_DRBG - Too many random requested in single call" );
+        mbedtls_snprintf( buf, buflen, "CTR_DRBG - The requested random buffer length is too big" );
     if( use_ret == -(MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG) )
-        mbedtls_snprintf( buf, buflen, "CTR_DRBG - Input too large (Entropy + additional)" );
+        mbedtls_snprintf( buf, buflen, "CTR_DRBG - The input (entropy + additional data) is too large" );
     if( use_ret == -(MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR) )
-        mbedtls_snprintf( buf, buflen, "CTR_DRBG - Read/write error in file" );
+        mbedtls_snprintf( buf, buflen, "CTR_DRBG - Read or write error in file" );
 #endif /* MBEDTLS_CTR_DRBG_C */
 
 #if defined(MBEDTLS_DES_C)
     if( use_ret == -(MBEDTLS_ERR_DES_INVALID_INPUT_LENGTH) )
         mbedtls_snprintf( buf, buflen, "DES - The data input has an invalid length" );
+    if( use_ret == -(MBEDTLS_ERR_DES_HW_ACCEL_FAILED) )
+        mbedtls_snprintf( buf, buflen, "DES - DES hardware accelerator failed" );
 #endif /* MBEDTLS_DES_C */
 
 #if defined(MBEDTLS_ENTROPY_C)
@@ -620,6 +690,8 @@
 #if defined(MBEDTLS_GCM_C)
     if( use_ret == -(MBEDTLS_ERR_GCM_AUTH_FAILED) )
         mbedtls_snprintf( buf, buflen, "GCM - Authenticated decryption failed" );
+    if( use_ret == -(MBEDTLS_ERR_GCM_HW_ACCEL_FAILED) )
+        mbedtls_snprintf( buf, buflen, "GCM - GCM hardware accelerator failed" );
     if( use_ret == -(MBEDTLS_ERR_GCM_BAD_INPUT) )
         mbedtls_snprintf( buf, buflen, "GCM - Bad input parameters to function" );
 #endif /* MBEDTLS_GCM_C */
@@ -635,6 +707,21 @@
         mbedtls_snprintf( buf, buflen, "HMAC_DRBG - The entropy source failed" );
 #endif /* MBEDTLS_HMAC_DRBG_C */
 
+#if defined(MBEDTLS_MD2_C)
+    if( use_ret == -(MBEDTLS_ERR_MD2_HW_ACCEL_FAILED) )
+        mbedtls_snprintf( buf, buflen, "MD2 - MD2 hardware accelerator failed" );
+#endif /* MBEDTLS_MD2_C */
+
+#if defined(MBEDTLS_MD4_C)
+    if( use_ret == -(MBEDTLS_ERR_MD4_HW_ACCEL_FAILED) )
+        mbedtls_snprintf( buf, buflen, "MD4 - MD4 hardware accelerator failed" );
+#endif /* MBEDTLS_MD4_C */
+
+#if defined(MBEDTLS_MD5_C)
+    if( use_ret == -(MBEDTLS_ERR_MD5_HW_ACCEL_FAILED) )
+        mbedtls_snprintf( buf, buflen, "MD5 - MD5 hardware accelerator failed" );
+#endif /* MBEDTLS_MD5_C */
+
 #if defined(MBEDTLS_NET_C)
     if( use_ret == -(MBEDTLS_ERR_NET_SOCKET_FAILED) )
         mbedtls_snprintf( buf, buflen, "NET - Failed to open a socket" );
@@ -672,6 +759,26 @@
         mbedtls_snprintf( buf, buflen, "PADLOCK - Input data should be aligned" );
 #endif /* MBEDTLS_PADLOCK_C */
 
+#if defined(MBEDTLS_RIPEMD160_C)
+    if( use_ret == -(MBEDTLS_ERR_RIPEMD160_HW_ACCEL_FAILED) )
+        mbedtls_snprintf( buf, buflen, "RIPEMD160 - RIPEMD160 hardware accelerator failed" );
+#endif /* MBEDTLS_RIPEMD160_C */
+
+#if defined(MBEDTLS_SHA1_C)
+    if( use_ret == -(MBEDTLS_ERR_SHA1_HW_ACCEL_FAILED) )
+        mbedtls_snprintf( buf, buflen, "SHA1 - SHA-1 hardware accelerator failed" );
+#endif /* MBEDTLS_SHA1_C */
+
+#if defined(MBEDTLS_SHA256_C)
+    if( use_ret == -(MBEDTLS_ERR_SHA256_HW_ACCEL_FAILED) )
+        mbedtls_snprintf( buf, buflen, "SHA256 - SHA-256 hardware accelerator failed" );
+#endif /* MBEDTLS_SHA256_C */
+
+#if defined(MBEDTLS_SHA512_C)
+    if( use_ret == -(MBEDTLS_ERR_SHA512_HW_ACCEL_FAILED) )
+        mbedtls_snprintf( buf, buflen, "SHA512 - SHA-512 hardware accelerator failed" );
+#endif /* MBEDTLS_SHA512_C */
+
 #if defined(MBEDTLS_THREADING_C)
     if( use_ret == -(MBEDTLS_ERR_THREADING_FEATURE_UNAVAILABLE) )
         mbedtls_snprintf( buf, buflen, "THREADING - The selected feature is not available" );
@@ -684,6 +791,8 @@
 #if defined(MBEDTLS_XTEA_C)
     if( use_ret == -(MBEDTLS_ERR_XTEA_INVALID_INPUT_LENGTH) )
         mbedtls_snprintf( buf, buflen, "XTEA - The data input has an invalid length" );
+    if( use_ret == -(MBEDTLS_ERR_XTEA_HW_ACCEL_FAILED) )
+        mbedtls_snprintf( buf, buflen, "XTEA - XTEA hardware accelerator failed" );
 #endif /* MBEDTLS_XTEA_C */
     // END generated code
 
diff --git a/library/hmac_drbg.c b/library/hmac_drbg.c
index bf5f9b5..24c609e 100644
--- a/library/hmac_drbg.c
+++ b/library/hmac_drbg.c
@@ -364,11 +364,14 @@
 
 exit:
     fclose( f );
+    mbedtls_zeroize( buf, sizeof( buf ) );
+
     return( ret );
 }
 
 int mbedtls_hmac_drbg_update_seed_file( mbedtls_hmac_drbg_context *ctx, const char *path )
 {
+    int ret = 0;
     FILE *f;
     size_t n;
     unsigned char buf[ MBEDTLS_HMAC_DRBG_MAX_INPUT ];
@@ -387,14 +390,16 @@
     }
 
     if( fread( buf, 1, n, f ) != n )
-    {
-        fclose( f );
-        return( MBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR );
-    }
+        ret = MBEDTLS_ERR_HMAC_DRBG_FILE_IO_ERROR;
+    else
+        mbedtls_hmac_drbg_update( ctx, buf, n );
 
     fclose( f );
 
-    mbedtls_hmac_drbg_update( ctx, buf, n );
+    mbedtls_zeroize( buf, sizeof( buf ) );
+
+    if( ret != 0 )
+        return( ret );
 
     return( mbedtls_hmac_drbg_write_seed_file( ctx, path ) );
 }
diff --git a/library/md.c b/library/md.c
index eda98f6..00249af 100644
--- a/library/md.c
+++ b/library/md.c
@@ -250,9 +250,7 @@
     if( ctx == NULL || ctx->md_info == NULL )
         return( MBEDTLS_ERR_MD_BAD_INPUT_DATA );
 
-    ctx->md_info->starts_func( ctx->md_ctx );
-
-    return( 0 );
+    return( ctx->md_info->starts_func( ctx->md_ctx ) );
 }
 
 int mbedtls_md_update( mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen )
@@ -260,9 +258,7 @@
     if( ctx == NULL || ctx->md_info == NULL )
         return( MBEDTLS_ERR_MD_BAD_INPUT_DATA );
 
-    ctx->md_info->update_func( ctx->md_ctx, input, ilen );
-
-    return( 0 );
+    return( ctx->md_info->update_func( ctx->md_ctx, input, ilen ) );
 }
 
 int mbedtls_md_finish( mbedtls_md_context_t *ctx, unsigned char *output )
@@ -270,9 +266,7 @@
     if( ctx == NULL || ctx->md_info == NULL )
         return( MBEDTLS_ERR_MD_BAD_INPUT_DATA );
 
-    ctx->md_info->finish_func( ctx->md_ctx, output );
-
-    return( 0 );
+    return( ctx->md_info->finish_func( ctx->md_ctx, output ) );
 }
 
 int mbedtls_md( const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen,
@@ -281,9 +275,7 @@
     if( md_info == NULL )
         return( MBEDTLS_ERR_MD_BAD_INPUT_DATA );
 
-    md_info->digest_func( input, ilen, output );
-
-    return( 0 );
+    return( md_info->digest_func( input, ilen, output ) );
 }
 
 #if defined(MBEDTLS_FS_IO)
@@ -306,20 +298,20 @@
     if( ( ret = mbedtls_md_setup( &ctx, md_info, 0 ) ) != 0 )
         goto cleanup;
 
-    md_info->starts_func( ctx.md_ctx );
+    if( ( ret = md_info->starts_func( ctx.md_ctx ) ) != 0 )
+        goto cleanup;
 
     while( ( n = fread( buf, 1, sizeof( buf ), f ) ) > 0 )
-        md_info->update_func( ctx.md_ctx, buf, n );
+        if( ( ret = md_info->update_func( ctx.md_ctx, buf, n ) ) != 0 )
+            goto cleanup;
 
     if( ferror( f ) != 0 )
-    {
         ret = MBEDTLS_ERR_MD_FILE_IO_ERROR;
-        goto cleanup;
-    }
-
-    md_info->finish_func( ctx.md_ctx, output );
+    else
+        ret = md_info->finish_func( ctx.md_ctx, output );
 
 cleanup:
+    mbedtls_zeroize( buf, sizeof( buf ) );
     fclose( f );
     mbedtls_md_free( &ctx );
 
@@ -329,6 +321,7 @@
 
 int mbedtls_md_hmac_starts( mbedtls_md_context_t *ctx, const unsigned char *key, size_t keylen )
 {
+    int ret;
     unsigned char sum[MBEDTLS_MD_MAX_SIZE];
     unsigned char *ipad, *opad;
     size_t i;
@@ -338,9 +331,12 @@
 
     if( keylen > (size_t) ctx->md_info->block_size )
     {
-        ctx->md_info->starts_func( ctx->md_ctx );
-        ctx->md_info->update_func( ctx->md_ctx, key, keylen );
-        ctx->md_info->finish_func( ctx->md_ctx, sum );
+        if( ( ret = ctx->md_info->starts_func( ctx->md_ctx ) ) != 0 )
+            goto cleanup;
+        if( ( ret = ctx->md_info->update_func( ctx->md_ctx, key, keylen ) ) != 0 )
+            goto cleanup;
+        if( ( ret = ctx->md_info->finish_func( ctx->md_ctx, sum ) ) != 0 )
+            goto cleanup;
 
         keylen = ctx->md_info->size;
         key = sum;
@@ -358,12 +354,16 @@
         opad[i] = (unsigned char)( opad[i] ^ key[i] );
     }
 
+    if( ( ret = ctx->md_info->starts_func( ctx->md_ctx ) ) != 0 )
+        goto cleanup;
+    if( ( ret = ctx->md_info->update_func( ctx->md_ctx, ipad,
+                                           ctx->md_info->block_size ) ) != 0 )
+        goto cleanup;
+
+cleanup:
     mbedtls_zeroize( sum, sizeof( sum ) );
 
-    ctx->md_info->starts_func( ctx->md_ctx );
-    ctx->md_info->update_func( ctx->md_ctx, ipad, ctx->md_info->block_size );
-
-    return( 0 );
+    return( ret );
 }
 
 int mbedtls_md_hmac_update( mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen )
@@ -371,13 +371,12 @@
     if( ctx == NULL || ctx->md_info == NULL || ctx->hmac_ctx == NULL )
         return( MBEDTLS_ERR_MD_BAD_INPUT_DATA );
 
-    ctx->md_info->update_func( ctx->md_ctx, input, ilen );
-
-    return( 0 );
+    return( ctx->md_info->update_func( ctx->md_ctx, input, ilen ) );
 }
 
 int mbedtls_md_hmac_finish( mbedtls_md_context_t *ctx, unsigned char *output )
 {
+    int ret;
     unsigned char tmp[MBEDTLS_MD_MAX_SIZE];
     unsigned char *opad;
 
@@ -386,17 +385,22 @@
 
     opad = (unsigned char *) ctx->hmac_ctx + ctx->md_info->block_size;
 
-    ctx->md_info->finish_func( ctx->md_ctx, tmp );
-    ctx->md_info->starts_func( ctx->md_ctx );
-    ctx->md_info->update_func( ctx->md_ctx, opad, ctx->md_info->block_size );
-    ctx->md_info->update_func( ctx->md_ctx, tmp, ctx->md_info->size );
-    ctx->md_info->finish_func( ctx->md_ctx, output );
-
-    return( 0 );
+    if( ( ret = ctx->md_info->finish_func( ctx->md_ctx, tmp ) ) != 0 )
+        return( ret );
+    if( ( ret = ctx->md_info->starts_func( ctx->md_ctx ) ) != 0 )
+        return( ret );
+    if( ( ret = ctx->md_info->update_func( ctx->md_ctx, opad,
+                                           ctx->md_info->block_size ) ) != 0 )
+        return( ret );
+    if( ( ret = ctx->md_info->update_func( ctx->md_ctx, tmp,
+                                           ctx->md_info->size ) ) != 0 )
+        return( ret );
+    return( ctx->md_info->finish_func( ctx->md_ctx, output ) );
 }
 
 int mbedtls_md_hmac_reset( mbedtls_md_context_t *ctx )
 {
+    int ret;
     unsigned char *ipad;
 
     if( ctx == NULL || ctx->md_info == NULL || ctx->hmac_ctx == NULL )
@@ -404,15 +408,16 @@
 
     ipad = (unsigned char *) ctx->hmac_ctx;
 
-    ctx->md_info->starts_func( ctx->md_ctx );
-    ctx->md_info->update_func( ctx->md_ctx, ipad, ctx->md_info->block_size );
-
-    return( 0 );
+    if( ( ret = ctx->md_info->starts_func( ctx->md_ctx ) ) != 0 )
+        return( ret );
+    return( ctx->md_info->update_func( ctx->md_ctx, ipad,
+                                       ctx->md_info->block_size ) );
 }
 
-int mbedtls_md_hmac( const mbedtls_md_info_t *md_info, const unsigned char *key, size_t keylen,
-                const unsigned char *input, size_t ilen,
-                unsigned char *output )
+int mbedtls_md_hmac( const mbedtls_md_info_t *md_info,
+                     const unsigned char *key, size_t keylen,
+                     const unsigned char *input, size_t ilen,
+                     unsigned char *output )
 {
     mbedtls_md_context_t ctx;
     int ret;
@@ -423,15 +428,19 @@
     mbedtls_md_init( &ctx );
 
     if( ( ret = mbedtls_md_setup( &ctx, md_info, 1 ) ) != 0 )
-        return( ret );
+        goto cleanup;
 
-    mbedtls_md_hmac_starts( &ctx, key, keylen );
-    mbedtls_md_hmac_update( &ctx, input, ilen );
-    mbedtls_md_hmac_finish( &ctx, output );
+    if( ( ret = mbedtls_md_hmac_starts( &ctx, key, keylen ) ) != 0 )
+        goto cleanup;
+    if( ( ret = mbedtls_md_hmac_update( &ctx, input, ilen ) ) != 0 )
+        goto cleanup;
+    if( ( ret = mbedtls_md_hmac_finish( &ctx, output ) ) != 0 )
+        goto cleanup;
 
+cleanup:
     mbedtls_md_free( &ctx );
 
-    return( 0 );
+    return( ret );
 }
 
 int mbedtls_md_process( mbedtls_md_context_t *ctx, const unsigned char *data )
@@ -439,9 +448,7 @@
     if( ctx == NULL || ctx->md_info == NULL )
         return( MBEDTLS_ERR_MD_BAD_INPUT_DATA );
 
-    ctx->md_info->process_func( ctx->md_ctx, data );
-
-    return( 0 );
+    return( ctx->md_info->process_func( ctx->md_ctx, data ) );
 }
 
 unsigned char mbedtls_md_get_size( const mbedtls_md_info_t *md_info )
diff --git a/library/md2.c b/library/md2.c
index 95cbcce..5028e8c 100644
--- a/library/md2.c
+++ b/library/md2.c
@@ -105,16 +105,18 @@
 /*
  * MD2 context setup
  */
-void mbedtls_md2_starts( mbedtls_md2_context *ctx )
+int mbedtls_md2_starts_ret( mbedtls_md2_context *ctx )
 {
     memset( ctx->cksum, 0, 16 );
     memset( ctx->state, 0, 46 );
     memset( ctx->buffer, 0, 16 );
     ctx->left = 0;
+
+    return( 0 );
 }
 
 #if !defined(MBEDTLS_MD2_PROCESS_ALT)
-void mbedtls_md2_process( mbedtls_md2_context *ctx )
+int mbedtls_internal_md2_process( mbedtls_md2_context *ctx )
 {
     int i, j;
     unsigned char t = 0;
@@ -146,14 +148,19 @@
            ( ctx->cksum[i] ^ PI_SUBST[ctx->buffer[i] ^ t] );
         t  = ctx->cksum[i];
     }
+
+    return( 0 );
 }
 #endif /* !MBEDTLS_MD2_PROCESS_ALT */
 
 /*
  * MD2 process buffer
  */
-void mbedtls_md2_update( mbedtls_md2_context *ctx, const unsigned char *input, size_t ilen )
+int mbedtls_md2_update_ret( mbedtls_md2_context *ctx,
+                            const unsigned char *input,
+                            size_t ilen )
 {
+    int ret;
     size_t fill;
 
     while( ilen > 0 )
@@ -172,16 +179,21 @@
         if( ctx->left == 16 )
         {
             ctx->left = 0;
-            mbedtls_md2_process( ctx );
+            if( ( ret = mbedtls_internal_md2_process( ctx ) ) != 0 )
+                return( ret );
         }
     }
+
+    return( 0 );
 }
 
 /*
  * MD2 final digest
  */
-void mbedtls_md2_finish( mbedtls_md2_context *ctx, unsigned char output[16] )
+int mbedtls_md2_finish_ret( mbedtls_md2_context *ctx,
+                            unsigned char output[16] )
 {
+    int ret;
     size_t i;
     unsigned char x;
 
@@ -190,12 +202,16 @@
     for( i = ctx->left; i < 16; i++ )
         ctx->buffer[i] = x;
 
-    mbedtls_md2_process( ctx );
+    if( ( ret = mbedtls_internal_md2_process( ctx ) ) != 0 )
+        return( ret );
 
     memcpy( ctx->buffer, ctx->cksum, 16 );
-    mbedtls_md2_process( ctx );
+    if( ( ret = mbedtls_internal_md2_process( ctx ) ) != 0 )
+        return( ret );
 
     memcpy( output, ctx->state, 16 );
+
+    return( 0 );
 }
 
 #endif /* !MBEDTLS_MD2_ALT */
@@ -203,15 +219,28 @@
 /*
  * output = MD2( input buffer )
  */
-void mbedtls_md2( const unsigned char *input, size_t ilen, unsigned char output[16] )
+int mbedtls_md2_ret( const unsigned char *input,
+                     size_t ilen,
+                     unsigned char output[16] )
 {
+    int ret;
     mbedtls_md2_context ctx;
 
     mbedtls_md2_init( &ctx );
-    mbedtls_md2_starts( &ctx );
-    mbedtls_md2_update( &ctx, input, ilen );
-    mbedtls_md2_finish( &ctx, output );
+
+    if( ( ret = mbedtls_md2_starts_ret( &ctx ) ) != 0 )
+        goto exit;
+
+    if( ( ret = mbedtls_md2_update_ret( &ctx, input, ilen ) ) != 0 )
+        goto exit;
+
+    if( ( ret = mbedtls_md2_finish_ret( &ctx, output ) ) != 0 )
+        goto exit;
+
+exit:
     mbedtls_md2_free( &ctx );
+
+    return( ret );
 }
 
 #if defined(MBEDTLS_SELF_TEST)
@@ -219,7 +248,7 @@
 /*
  * RFC 1319 test vectors
  */
-static const char md2_test_str[7][81] =
+static const unsigned char md2_test_str[7][81] =
 {
     { "" },
     { "a" },
@@ -227,10 +256,15 @@
     { "message digest" },
     { "abcdefghijklmnopqrstuvwxyz" },
     { "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789" },
-    { "12345678901234567890123456789012345678901234567890123456789012" \
+    { "12345678901234567890123456789012345678901234567890123456789012"
       "345678901234567890" }
 };
 
+static const size_t md2_test_strlen[7] =
+{
+    0, 1, 3, 14, 26, 62, 80
+};
+
 static const unsigned char md2_test_sum[7][16] =
 {
     { 0x83, 0x50, 0xE5, 0xA3, 0xE2, 0x4C, 0x15, 0x3D,
@@ -254,7 +288,7 @@
  */
 int mbedtls_md2_self_test( int verbose )
 {
-    int i;
+    int i, ret = 0;
     unsigned char md2sum[16];
 
     for( i = 0; i < 7; i++ )
@@ -262,15 +296,14 @@
         if( verbose != 0 )
             mbedtls_printf( "  MD2 test #%d: ", i + 1 );
 
-        mbedtls_md2( (unsigned char *) md2_test_str[i],
-             strlen( md2_test_str[i] ), md2sum );
+        ret = mbedtls_md2_ret( md2_test_str[i], md2_test_strlen[i], md2sum );
+        if( ret != 0 )
+            goto fail;
 
         if( memcmp( md2sum, md2_test_sum[i], 16 ) != 0 )
         {
-            if( verbose != 0 )
-                mbedtls_printf( "failed\n" );
-
-            return( 1 );
+            ret = 1;
+            goto fail;
         }
 
         if( verbose != 0 )
@@ -281,6 +314,12 @@
         mbedtls_printf( "\n" );
 
     return( 0 );
+
+fail:
+    if( verbose != 0 )
+        mbedtls_printf( "failed\n" );
+
+    return( ret );
 }
 
 #endif /* MBEDTLS_SELF_TEST */
diff --git a/library/md4.c b/library/md4.c
index 11a77e3..34a4b0e 100644
--- a/library/md4.c
+++ b/library/md4.c
@@ -98,7 +98,7 @@
 /*
  * MD4 context setup
  */
-void mbedtls_md4_starts( mbedtls_md4_context *ctx )
+int mbedtls_md4_starts_ret( mbedtls_md4_context *ctx )
 {
     ctx->total[0] = 0;
     ctx->total[1] = 0;
@@ -107,10 +107,13 @@
     ctx->state[1] = 0xEFCDAB89;
     ctx->state[2] = 0x98BADCFE;
     ctx->state[3] = 0x10325476;
+
+    return( 0 );
 }
 
 #if !defined(MBEDTLS_MD4_PROCESS_ALT)
-void mbedtls_md4_process( mbedtls_md4_context *ctx, const unsigned char data[64] )
+int mbedtls_internal_md4_process( mbedtls_md4_context *ctx,
+                                  const unsigned char data[64] )
 {
     uint32_t X[16], A, B, C, D;
 
@@ -211,19 +214,24 @@
     ctx->state[1] += B;
     ctx->state[2] += C;
     ctx->state[3] += D;
+
+    return( 0 );
 }
 #endif /* !MBEDTLS_MD4_PROCESS_ALT */
 
 /*
  * MD4 process buffer
  */
-void mbedtls_md4_update( mbedtls_md4_context *ctx, const unsigned char *input, size_t ilen )
+int mbedtls_md4_update_ret( mbedtls_md4_context *ctx,
+                            const unsigned char *input,
+                            size_t ilen )
 {
+    int ret;
     size_t fill;
     uint32_t left;
 
     if( ilen == 0 )
-        return;
+        return( 0 );
 
     left = ctx->total[0] & 0x3F;
     fill = 64 - left;
@@ -238,7 +246,10 @@
     {
         memcpy( (void *) (ctx->buffer + left),
                 (void *) input, fill );
-        mbedtls_md4_process( ctx, ctx->buffer );
+
+        if( ( ret = mbedtls_internal_md4_process( ctx, ctx->buffer ) ) != 0 )
+            return( ret );
+
         input += fill;
         ilen  -= fill;
         left = 0;
@@ -246,7 +257,9 @@
 
     while( ilen >= 64 )
     {
-        mbedtls_md4_process( ctx, input );
+        if( ( ret = mbedtls_internal_md4_process( ctx, input ) ) != 0 )
+            return( ret );
+
         input += 64;
         ilen  -= 64;
     }
@@ -256,6 +269,8 @@
         memcpy( (void *) (ctx->buffer + left),
                 (void *) input, ilen );
     }
+
+    return( 0 );
 }
 
 static const unsigned char md4_padding[64] =
@@ -269,8 +284,10 @@
 /*
  * MD4 final digest
  */
-void mbedtls_md4_finish( mbedtls_md4_context *ctx, unsigned char output[16] )
+int mbedtls_md4_finish_ret( mbedtls_md4_context *ctx,
+                            unsigned char output[16] )
 {
+    int ret;
     uint32_t last, padn;
     uint32_t high, low;
     unsigned char msglen[8];
@@ -285,13 +302,20 @@
     last = ctx->total[0] & 0x3F;
     padn = ( last < 56 ) ? ( 56 - last ) : ( 120 - last );
 
-    mbedtls_md4_update( ctx, (unsigned char *) md4_padding, padn );
-    mbedtls_md4_update( ctx, msglen, 8 );
+    ret = mbedtls_md4_update_ret( ctx, (unsigned char *)md4_padding, padn );
+    if( ret != 0 )
+        return( ret );
+
+    if( ( ret = mbedtls_md4_update_ret( ctx, msglen, 8 ) ) != 0 )
+        return( ret );
+
 
     PUT_UINT32_LE( ctx->state[0], output,  0 );
     PUT_UINT32_LE( ctx->state[1], output,  4 );
     PUT_UINT32_LE( ctx->state[2], output,  8 );
     PUT_UINT32_LE( ctx->state[3], output, 12 );
+
+    return( 0 );
 }
 
 #endif /* !MBEDTLS_MD4_ALT */
@@ -299,15 +323,28 @@
 /*
  * output = MD4( input buffer )
  */
-void mbedtls_md4( const unsigned char *input, size_t ilen, unsigned char output[16] )
+int mbedtls_md4_ret( const unsigned char *input,
+                     size_t ilen,
+                     unsigned char output[16] )
 {
+    int ret;
     mbedtls_md4_context ctx;
 
     mbedtls_md4_init( &ctx );
-    mbedtls_md4_starts( &ctx );
-    mbedtls_md4_update( &ctx, input, ilen );
-    mbedtls_md4_finish( &ctx, output );
+
+    if( ( ret = mbedtls_md4_starts_ret( &ctx ) ) != 0 )
+        goto exit;
+
+    if( ( ret = mbedtls_md4_update_ret( &ctx, input, ilen ) ) != 0 )
+        goto exit;
+
+    if( ( ret = mbedtls_md4_finish_ret( &ctx, output ) ) != 0 )
+        goto exit;
+
+exit:
     mbedtls_md4_free( &ctx );
+
+    return( ret );
 }
 
 #if defined(MBEDTLS_SELF_TEST)
@@ -315,7 +352,7 @@
 /*
  * RFC 1320 test vectors
  */
-static const char md4_test_str[7][81] =
+static const unsigned char md4_test_str[7][81] =
 {
     { "" },
     { "a" },
@@ -323,10 +360,15 @@
     { "message digest" },
     { "abcdefghijklmnopqrstuvwxyz" },
     { "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789" },
-    { "12345678901234567890123456789012345678901234567890123456789012" \
+    { "12345678901234567890123456789012345678901234567890123456789012"
       "345678901234567890" }
 };
 
+static const size_t md4_test_strlen[7] =
+{
+    0, 1, 3, 14, 26, 62, 80
+};
+
 static const unsigned char md4_test_sum[7][16] =
 {
     { 0x31, 0xD6, 0xCF, 0xE0, 0xD1, 0x6A, 0xE9, 0x31,
@@ -350,7 +392,7 @@
  */
 int mbedtls_md4_self_test( int verbose )
 {
-    int i;
+    int i, ret = 0;
     unsigned char md4sum[16];
 
     for( i = 0; i < 7; i++ )
@@ -358,15 +400,14 @@
         if( verbose != 0 )
             mbedtls_printf( "  MD4 test #%d: ", i + 1 );
 
-        mbedtls_md4( (unsigned char *) md4_test_str[i],
-             strlen( md4_test_str[i] ), md4sum );
+        ret = mbedtls_md4_ret( md4_test_str[i], md4_test_strlen[i], md4sum );
+        if( ret != 0 )
+            goto fail;
 
         if( memcmp( md4sum, md4_test_sum[i], 16 ) != 0 )
         {
-            if( verbose != 0 )
-                mbedtls_printf( "failed\n" );
-
-            return( 1 );
+            ret = 1;
+            goto fail;
         }
 
         if( verbose != 0 )
@@ -377,6 +418,12 @@
         mbedtls_printf( "\n" );
 
     return( 0 );
+
+fail:
+    if( verbose != 0 )
+        mbedtls_printf( "failed\n" );
+
+    return( ret );
 }
 
 #endif /* MBEDTLS_SELF_TEST */
diff --git a/library/md5.c b/library/md5.c
index 5d972dc..8872dc4 100644
--- a/library/md5.c
+++ b/library/md5.c
@@ -97,7 +97,7 @@
 /*
  * MD5 context setup
  */
-void mbedtls_md5_starts( mbedtls_md5_context *ctx )
+int mbedtls_md5_starts_ret( mbedtls_md5_context *ctx )
 {
     ctx->total[0] = 0;
     ctx->total[1] = 0;
@@ -106,10 +106,13 @@
     ctx->state[1] = 0xEFCDAB89;
     ctx->state[2] = 0x98BADCFE;
     ctx->state[3] = 0x10325476;
+
+    return( 0 );
 }
 
 #if !defined(MBEDTLS_MD5_PROCESS_ALT)
-void mbedtls_md5_process( mbedtls_md5_context *ctx, const unsigned char data[64] )
+int mbedtls_internal_md5_process( mbedtls_md5_context *ctx,
+                                  const unsigned char data[64] )
 {
     uint32_t X[16], A, B, C, D;
 
@@ -230,19 +233,24 @@
     ctx->state[1] += B;
     ctx->state[2] += C;
     ctx->state[3] += D;
+
+    return( 0 );
 }
 #endif /* !MBEDTLS_MD5_PROCESS_ALT */
 
 /*
  * MD5 process buffer
  */
-void mbedtls_md5_update( mbedtls_md5_context *ctx, const unsigned char *input, size_t ilen )
+int mbedtls_md5_update_ret( mbedtls_md5_context *ctx,
+                            const unsigned char *input,
+                            size_t ilen )
 {
+    int ret;
     size_t fill;
     uint32_t left;
 
     if( ilen == 0 )
-        return;
+        return( 0 );
 
     left = ctx->total[0] & 0x3F;
     fill = 64 - left;
@@ -256,7 +264,9 @@
     if( left && ilen >= fill )
     {
         memcpy( (void *) (ctx->buffer + left), input, fill );
-        mbedtls_md5_process( ctx, ctx->buffer );
+        if( ( ret = mbedtls_internal_md5_process( ctx, ctx->buffer ) ) != 0 )
+            return( ret );
+
         input += fill;
         ilen  -= fill;
         left = 0;
@@ -264,7 +274,9 @@
 
     while( ilen >= 64 )
     {
-        mbedtls_md5_process( ctx, input );
+        if( ( ret = mbedtls_internal_md5_process( ctx, input ) ) != 0 )
+            return( ret );
+
         input += 64;
         ilen  -= 64;
     }
@@ -273,6 +285,8 @@
     {
         memcpy( (void *) (ctx->buffer + left), input, ilen );
     }
+
+    return( 0 );
 }
 
 static const unsigned char md5_padding[64] =
@@ -286,8 +300,10 @@
 /*
  * MD5 final digest
  */
-void mbedtls_md5_finish( mbedtls_md5_context *ctx, unsigned char output[16] )
+int mbedtls_md5_finish_ret( mbedtls_md5_context *ctx,
+                            unsigned char output[16] )
 {
+    int ret;
     uint32_t last, padn;
     uint32_t high, low;
     unsigned char msglen[8];
@@ -302,13 +318,18 @@
     last = ctx->total[0] & 0x3F;
     padn = ( last < 56 ) ? ( 56 - last ) : ( 120 - last );
 
-    mbedtls_md5_update( ctx, md5_padding, padn );
-    mbedtls_md5_update( ctx, msglen, 8 );
+    if( ( ret = mbedtls_md5_update_ret( ctx, md5_padding, padn ) ) != 0 )
+            return( ret );
+
+    if( ( ret = mbedtls_md5_update_ret( ctx, msglen, 8 ) ) != 0 )
+            return( ret );
 
     PUT_UINT32_LE( ctx->state[0], output,  0 );
     PUT_UINT32_LE( ctx->state[1], output,  4 );
     PUT_UINT32_LE( ctx->state[2], output,  8 );
     PUT_UINT32_LE( ctx->state[3], output, 12 );
+
+    return( 0 );
 }
 
 #endif /* !MBEDTLS_MD5_ALT */
@@ -316,15 +337,28 @@
 /*
  * output = MD5( input buffer )
  */
-void mbedtls_md5( const unsigned char *input, size_t ilen, unsigned char output[16] )
+int mbedtls_md5_ret( const unsigned char *input,
+                     size_t ilen,
+                     unsigned char output[16] )
 {
+    int ret;
     mbedtls_md5_context ctx;
 
     mbedtls_md5_init( &ctx );
-    mbedtls_md5_starts( &ctx );
-    mbedtls_md5_update( &ctx, input, ilen );
-    mbedtls_md5_finish( &ctx, output );
+
+    if( ( ret = mbedtls_md5_starts_ret( &ctx ) ) != 0 )
+        goto exit;
+
+    if( ( ret = mbedtls_md5_update_ret( &ctx, input, ilen ) ) != 0 )
+        goto exit;
+
+    if( ( ret = mbedtls_md5_finish_ret( &ctx, output ) ) != 0 )
+        goto exit;
+
+exit:
     mbedtls_md5_free( &ctx );
+
+    return( ret );
 }
 
 #if defined(MBEDTLS_SELF_TEST)
@@ -339,11 +373,11 @@
     { "message digest" },
     { "abcdefghijklmnopqrstuvwxyz" },
     { "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789" },
-    { "12345678901234567890123456789012345678901234567890123456789012" \
+    { "12345678901234567890123456789012345678901234567890123456789012"
       "345678901234567890" }
 };
 
-static const int md5_test_buflen[7] =
+static const size_t md5_test_buflen[7] =
 {
     0, 1, 3, 14, 26, 62, 80
 };
@@ -371,7 +405,7 @@
  */
 int mbedtls_md5_self_test( int verbose )
 {
-    int i;
+    int i, ret = 0;
     unsigned char md5sum[16];
 
     for( i = 0; i < 7; i++ )
@@ -379,14 +413,14 @@
         if( verbose != 0 )
             mbedtls_printf( "  MD5 test #%d: ", i + 1 );
 
-        mbedtls_md5( md5_test_buf[i], md5_test_buflen[i], md5sum );
+        ret = mbedtls_md5_ret( md5_test_buf[i], md5_test_buflen[i], md5sum );
+        if( ret != 0 )
+            goto fail;
 
         if( memcmp( md5sum, md5_test_sum[i], 16 ) != 0 )
         {
-            if( verbose != 0 )
-                mbedtls_printf( "failed\n" );
-
-            return( 1 );
+            ret = 1;
+            goto fail;
         }
 
         if( verbose != 0 )
@@ -397,6 +431,12 @@
         mbedtls_printf( "\n" );
 
     return( 0 );
+
+fail:
+    if( verbose != 0 )
+        mbedtls_printf( "failed\n" );
+
+    return( ret );
 }
 
 #endif /* MBEDTLS_SELF_TEST */
diff --git a/library/md_wrap.c b/library/md_wrap.c
index 2cfcae2..32f0871 100644
--- a/library/md_wrap.c
+++ b/library/md_wrap.c
@@ -71,20 +71,20 @@
 
 #if defined(MBEDTLS_MD2_C)
 
-static void md2_starts_wrap( void *ctx )
+static int md2_starts_wrap( void *ctx )
 {
-    mbedtls_md2_starts( (mbedtls_md2_context *) ctx );
+    return( mbedtls_md2_starts_ret( (mbedtls_md2_context *) ctx ) );
 }
 
-static void md2_update_wrap( void *ctx, const unsigned char *input,
+static int md2_update_wrap( void *ctx, const unsigned char *input,
                              size_t ilen )
 {
-    mbedtls_md2_update( (mbedtls_md2_context *) ctx, input, ilen );
+    return( mbedtls_md2_update_ret( (mbedtls_md2_context *) ctx, input, ilen ) );
 }
 
-static void md2_finish_wrap( void *ctx, unsigned char *output )
+static int md2_finish_wrap( void *ctx, unsigned char *output )
 {
-    mbedtls_md2_finish( (mbedtls_md2_context *) ctx, output );
+    return( mbedtls_md2_finish_ret( (mbedtls_md2_context *) ctx, output ) );
 }
 
 static void *md2_ctx_alloc( void )
@@ -109,11 +109,11 @@
                  (const mbedtls_md2_context *) src );
 }
 
-static void md2_process_wrap( void *ctx, const unsigned char *data )
+static int md2_process_wrap( void *ctx, const unsigned char *data )
 {
     ((void) data);
 
-    mbedtls_md2_process( (mbedtls_md2_context *) ctx );
+    return( mbedtls_internal_md2_process( (mbedtls_md2_context *) ctx ) );
 }
 
 const mbedtls_md_info_t mbedtls_md2_info = {
@@ -124,7 +124,7 @@
     md2_starts_wrap,
     md2_update_wrap,
     md2_finish_wrap,
-    mbedtls_md2,
+    mbedtls_md2_ret,
     md2_ctx_alloc,
     md2_ctx_free,
     md2_clone_wrap,
@@ -135,20 +135,20 @@
 
 #if defined(MBEDTLS_MD4_C)
 
-static void md4_starts_wrap( void *ctx )
+static int md4_starts_wrap( void *ctx )
 {
-    mbedtls_md4_starts( (mbedtls_md4_context *) ctx );
+    return( mbedtls_md4_starts_ret( (mbedtls_md4_context *) ctx ) );
 }
 
-static void md4_update_wrap( void *ctx, const unsigned char *input,
+static int md4_update_wrap( void *ctx, const unsigned char *input,
                              size_t ilen )
 {
-    mbedtls_md4_update( (mbedtls_md4_context *) ctx, input, ilen );
+    return( mbedtls_md4_update_ret( (mbedtls_md4_context *) ctx, input, ilen ) );
 }
 
-static void md4_finish_wrap( void *ctx, unsigned char *output )
+static int md4_finish_wrap( void *ctx, unsigned char *output )
 {
-    mbedtls_md4_finish( (mbedtls_md4_context *) ctx, output );
+    return( mbedtls_md4_finish_ret( (mbedtls_md4_context *) ctx, output ) );
 }
 
 static void *md4_ctx_alloc( void )
@@ -170,12 +170,12 @@
 static void md4_clone_wrap( void *dst, const void *src )
 {
     mbedtls_md4_clone( (mbedtls_md4_context *) dst,
-                 (const mbedtls_md4_context *) src );
+                       (const mbedtls_md4_context *) src );
 }
 
-static void md4_process_wrap( void *ctx, const unsigned char *data )
+static int md4_process_wrap( void *ctx, const unsigned char *data )
 {
-    mbedtls_md4_process( (mbedtls_md4_context *) ctx, data );
+    return( mbedtls_internal_md4_process( (mbedtls_md4_context *) ctx, data ) );
 }
 
 const mbedtls_md_info_t mbedtls_md4_info = {
@@ -186,7 +186,7 @@
     md4_starts_wrap,
     md4_update_wrap,
     md4_finish_wrap,
-    mbedtls_md4,
+    mbedtls_md4_ret,
     md4_ctx_alloc,
     md4_ctx_free,
     md4_clone_wrap,
@@ -197,20 +197,20 @@
 
 #if defined(MBEDTLS_MD5_C)
 
-static void md5_starts_wrap( void *ctx )
+static int md5_starts_wrap( void *ctx )
 {
-    mbedtls_md5_starts( (mbedtls_md5_context *) ctx );
+    return( mbedtls_md5_starts_ret( (mbedtls_md5_context *) ctx ) );
 }
 
-static void md5_update_wrap( void *ctx, const unsigned char *input,
+static int md5_update_wrap( void *ctx, const unsigned char *input,
                              size_t ilen )
 {
-    mbedtls_md5_update( (mbedtls_md5_context *) ctx, input, ilen );
+    return( mbedtls_md5_update_ret( (mbedtls_md5_context *) ctx, input, ilen ) );
 }
 
-static void md5_finish_wrap( void *ctx, unsigned char *output )
+static int md5_finish_wrap( void *ctx, unsigned char *output )
 {
-    mbedtls_md5_finish( (mbedtls_md5_context *) ctx, output );
+    return( mbedtls_md5_finish_ret( (mbedtls_md5_context *) ctx, output ) );
 }
 
 static void *md5_ctx_alloc( void )
@@ -232,12 +232,12 @@
 static void md5_clone_wrap( void *dst, const void *src )
 {
     mbedtls_md5_clone( (mbedtls_md5_context *) dst,
-                 (const mbedtls_md5_context *) src );
+                       (const mbedtls_md5_context *) src );
 }
 
-static void md5_process_wrap( void *ctx, const unsigned char *data )
+static int md5_process_wrap( void *ctx, const unsigned char *data )
 {
-    mbedtls_md5_process( (mbedtls_md5_context *) ctx, data );
+    return( mbedtls_internal_md5_process( (mbedtls_md5_context *) ctx, data ) );
 }
 
 const mbedtls_md_info_t mbedtls_md5_info = {
@@ -248,7 +248,7 @@
     md5_starts_wrap,
     md5_update_wrap,
     md5_finish_wrap,
-    mbedtls_md5,
+    mbedtls_md5_ret,
     md5_ctx_alloc,
     md5_ctx_free,
     md5_clone_wrap,
@@ -259,20 +259,22 @@
 
 #if defined(MBEDTLS_RIPEMD160_C)
 
-static void ripemd160_starts_wrap( void *ctx )
+static int ripemd160_starts_wrap( void *ctx )
 {
-    mbedtls_ripemd160_starts( (mbedtls_ripemd160_context *) ctx );
+    return( mbedtls_ripemd160_starts_ret( (mbedtls_ripemd160_context *) ctx ) );
 }
 
-static void ripemd160_update_wrap( void *ctx, const unsigned char *input,
+static int ripemd160_update_wrap( void *ctx, const unsigned char *input,
                                    size_t ilen )
 {
-    mbedtls_ripemd160_update( (mbedtls_ripemd160_context *) ctx, input, ilen );
+    return( mbedtls_ripemd160_update_ret( (mbedtls_ripemd160_context *) ctx,
+                                          input, ilen ) );
 }
 
-static void ripemd160_finish_wrap( void *ctx, unsigned char *output )
+static int ripemd160_finish_wrap( void *ctx, unsigned char *output )
 {
-    mbedtls_ripemd160_finish( (mbedtls_ripemd160_context *) ctx, output );
+    return( mbedtls_ripemd160_finish_ret( (mbedtls_ripemd160_context *) ctx,
+                                          output ) );
 }
 
 static void *ripemd160_ctx_alloc( void )
@@ -297,9 +299,10 @@
                        (const mbedtls_ripemd160_context *) src );
 }
 
-static void ripemd160_process_wrap( void *ctx, const unsigned char *data )
+static int ripemd160_process_wrap( void *ctx, const unsigned char *data )
 {
-    mbedtls_ripemd160_process( (mbedtls_ripemd160_context *) ctx, data );
+    return( mbedtls_internal_ripemd160_process(
+                                (mbedtls_ripemd160_context *) ctx, data ) );
 }
 
 const mbedtls_md_info_t mbedtls_ripemd160_info = {
@@ -310,7 +313,7 @@
     ripemd160_starts_wrap,
     ripemd160_update_wrap,
     ripemd160_finish_wrap,
-    mbedtls_ripemd160,
+    mbedtls_ripemd160_ret,
     ripemd160_ctx_alloc,
     ripemd160_ctx_free,
     ripemd160_clone_wrap,
@@ -321,20 +324,21 @@
 
 #if defined(MBEDTLS_SHA1_C)
 
-static void sha1_starts_wrap( void *ctx )
+static int sha1_starts_wrap( void *ctx )
 {
-    mbedtls_sha1_starts( (mbedtls_sha1_context *) ctx );
+    return( mbedtls_sha1_starts_ret( (mbedtls_sha1_context *) ctx ) );
 }
 
-static void sha1_update_wrap( void *ctx, const unsigned char *input,
+static int sha1_update_wrap( void *ctx, const unsigned char *input,
                               size_t ilen )
 {
-    mbedtls_sha1_update( (mbedtls_sha1_context *) ctx, input, ilen );
+    return( mbedtls_sha1_update_ret( (mbedtls_sha1_context *) ctx,
+                                     input, ilen ) );
 }
 
-static void sha1_finish_wrap( void *ctx, unsigned char *output )
+static int sha1_finish_wrap( void *ctx, unsigned char *output )
 {
-    mbedtls_sha1_finish( (mbedtls_sha1_context *) ctx, output );
+    return( mbedtls_sha1_finish_ret( (mbedtls_sha1_context *) ctx, output ) );
 }
 
 static void *sha1_ctx_alloc( void )
@@ -359,9 +363,10 @@
     mbedtls_free( ctx );
 }
 
-static void sha1_process_wrap( void *ctx, const unsigned char *data )
+static int sha1_process_wrap( void *ctx, const unsigned char *data )
 {
-    mbedtls_sha1_process( (mbedtls_sha1_context *) ctx, data );
+    return( mbedtls_internal_sha1_process( (mbedtls_sha1_context *) ctx,
+                                           data ) );
 }
 
 const mbedtls_md_info_t mbedtls_sha1_info = {
@@ -372,7 +377,7 @@
     sha1_starts_wrap,
     sha1_update_wrap,
     sha1_finish_wrap,
-    mbedtls_sha1,
+    mbedtls_sha1_ret,
     sha1_ctx_alloc,
     sha1_ctx_free,
     sha1_clone_wrap,
@@ -386,26 +391,28 @@
  */
 #if defined(MBEDTLS_SHA256_C)
 
-static void sha224_starts_wrap( void *ctx )
+static int sha224_starts_wrap( void *ctx )
 {
-    mbedtls_sha256_starts( (mbedtls_sha256_context *) ctx, 1 );
+    return( mbedtls_sha256_starts_ret( (mbedtls_sha256_context *) ctx, 1 ) );
 }
 
-static void sha224_update_wrap( void *ctx, const unsigned char *input,
+static int sha224_update_wrap( void *ctx, const unsigned char *input,
                                 size_t ilen )
 {
-    mbedtls_sha256_update( (mbedtls_sha256_context *) ctx, input, ilen );
+    return( mbedtls_sha256_update_ret( (mbedtls_sha256_context *) ctx,
+                                       input, ilen ) );
 }
 
-static void sha224_finish_wrap( void *ctx, unsigned char *output )
+static int sha224_finish_wrap( void *ctx, unsigned char *output )
 {
-    mbedtls_sha256_finish( (mbedtls_sha256_context *) ctx, output );
+    return( mbedtls_sha256_finish_ret( (mbedtls_sha256_context *) ctx,
+                                       output ) );
 }
 
-static void sha224_wrap( const unsigned char *input, size_t ilen,
-                    unsigned char *output )
+static int sha224_wrap( const unsigned char *input, size_t ilen,
+                        unsigned char *output )
 {
-    mbedtls_sha256( input, ilen, output, 1 );
+    return( mbedtls_sha256_ret( input, ilen, output, 1 ) );
 }
 
 static void *sha224_ctx_alloc( void )
@@ -430,9 +437,10 @@
                     (const mbedtls_sha256_context *) src );
 }
 
-static void sha224_process_wrap( void *ctx, const unsigned char *data )
+static int sha224_process_wrap( void *ctx, const unsigned char *data )
 {
-    mbedtls_sha256_process( (mbedtls_sha256_context *) ctx, data );
+    return( mbedtls_internal_sha256_process( (mbedtls_sha256_context *) ctx,
+                                             data ) );
 }
 
 const mbedtls_md_info_t mbedtls_sha224_info = {
@@ -450,15 +458,15 @@
     sha224_process_wrap,
 };
 
-static void sha256_starts_wrap( void *ctx )
+static int sha256_starts_wrap( void *ctx )
 {
-    mbedtls_sha256_starts( (mbedtls_sha256_context *) ctx, 0 );
+    return( mbedtls_sha256_starts_ret( (mbedtls_sha256_context *) ctx, 0 ) );
 }
 
-static void sha256_wrap( const unsigned char *input, size_t ilen,
-                    unsigned char *output )
+static int sha256_wrap( const unsigned char *input, size_t ilen,
+                        unsigned char *output )
 {
-    mbedtls_sha256( input, ilen, output, 0 );
+    return( mbedtls_sha256_ret( input, ilen, output, 0 ) );
 }
 
 const mbedtls_md_info_t mbedtls_sha256_info = {
@@ -480,26 +488,28 @@
 
 #if defined(MBEDTLS_SHA512_C)
 
-static void sha384_starts_wrap( void *ctx )
+static int sha384_starts_wrap( void *ctx )
 {
-    mbedtls_sha512_starts( (mbedtls_sha512_context *) ctx, 1 );
+    return( mbedtls_sha512_starts_ret( (mbedtls_sha512_context *) ctx, 1 ) );
 }
 
-static void sha384_update_wrap( void *ctx, const unsigned char *input,
-                                size_t ilen )
+static int sha384_update_wrap( void *ctx, const unsigned char *input,
+                               size_t ilen )
 {
-    mbedtls_sha512_update( (mbedtls_sha512_context *) ctx, input, ilen );
+    return( mbedtls_sha512_update_ret( (mbedtls_sha512_context *) ctx,
+                                       input, ilen ) );
 }
 
-static void sha384_finish_wrap( void *ctx, unsigned char *output )
+static int sha384_finish_wrap( void *ctx, unsigned char *output )
 {
-    mbedtls_sha512_finish( (mbedtls_sha512_context *) ctx, output );
+    return( mbedtls_sha512_finish_ret( (mbedtls_sha512_context *) ctx,
+                                       output ) );
 }
 
-static void sha384_wrap( const unsigned char *input, size_t ilen,
-                    unsigned char *output )
+static int sha384_wrap( const unsigned char *input, size_t ilen,
+                        unsigned char *output )
 {
-    mbedtls_sha512( input, ilen, output, 1 );
+    return( mbedtls_sha512_ret( input, ilen, output, 1 ) );
 }
 
 static void *sha384_ctx_alloc( void )
@@ -524,9 +534,10 @@
                     (const mbedtls_sha512_context *) src );
 }
 
-static void sha384_process_wrap( void *ctx, const unsigned char *data )
+static int sha384_process_wrap( void *ctx, const unsigned char *data )
 {
-    mbedtls_sha512_process( (mbedtls_sha512_context *) ctx, data );
+    return( mbedtls_internal_sha512_process( (mbedtls_sha512_context *) ctx,
+                                             data ) );
 }
 
 const mbedtls_md_info_t mbedtls_sha384_info = {
@@ -544,15 +555,15 @@
     sha384_process_wrap,
 };
 
-static void sha512_starts_wrap( void *ctx )
+static int sha512_starts_wrap( void *ctx )
 {
-    mbedtls_sha512_starts( (mbedtls_sha512_context *) ctx, 0 );
+    return( mbedtls_sha512_starts_ret( (mbedtls_sha512_context *) ctx, 0 ) );
 }
 
-static void sha512_wrap( const unsigned char *input, size_t ilen,
-                    unsigned char *output )
+static int sha512_wrap( const unsigned char *input, size_t ilen,
+                        unsigned char *output )
 {
-    mbedtls_sha512( input, ilen, output, 0 );
+    return( mbedtls_sha512_ret( input, ilen, output, 0 ) );
 }
 
 const mbedtls_md_info_t mbedtls_sha512_info = {
diff --git a/library/pem.c b/library/pem.c
index 87401ba..c09651f 100644
--- a/library/pem.c
+++ b/library/pem.c
@@ -82,31 +82,33 @@
     return( 0 );
 }
 
-static void pem_pbkdf1( unsigned char *key, size_t keylen,
-                        unsigned char *iv,
-                        const unsigned char *pwd, size_t pwdlen )
+static int pem_pbkdf1( unsigned char *key, size_t keylen,
+                       unsigned char *iv,
+                       const unsigned char *pwd, size_t pwdlen )
 {
     mbedtls_md5_context md5_ctx;
     unsigned char md5sum[16];
     size_t use_len;
+    int ret;
 
     mbedtls_md5_init( &md5_ctx );
 
     /*
      * key[ 0..15] = MD5(pwd || IV)
      */
-    mbedtls_md5_starts( &md5_ctx );
-    mbedtls_md5_update( &md5_ctx, pwd, pwdlen );
-    mbedtls_md5_update( &md5_ctx, iv,  8 );
-    mbedtls_md5_finish( &md5_ctx, md5sum );
+    if( ( ret = mbedtls_md5_starts_ret( &md5_ctx ) ) != 0 )
+        goto exit;
+    if( ( ret = mbedtls_md5_update_ret( &md5_ctx, pwd, pwdlen ) ) != 0 )
+        goto exit;
+    if( ( ret = mbedtls_md5_update_ret( &md5_ctx, iv,  8 ) ) != 0 )
+        goto exit;
+    if( ( ret = mbedtls_md5_finish_ret( &md5_ctx, md5sum ) ) != 0 )
+        goto exit;
 
     if( keylen <= 16 )
     {
         memcpy( key, md5sum, keylen );
-
-        mbedtls_md5_free( &md5_ctx );
-        mbedtls_zeroize( md5sum, 16 );
-        return;
+        goto exit;
     }
 
     memcpy( key, md5sum, 16 );
@@ -114,11 +116,16 @@
     /*
      * key[16..23] = MD5(key[ 0..15] || pwd || IV])
      */
-    mbedtls_md5_starts( &md5_ctx );
-    mbedtls_md5_update( &md5_ctx, md5sum,  16 );
-    mbedtls_md5_update( &md5_ctx, pwd, pwdlen );
-    mbedtls_md5_update( &md5_ctx, iv,  8 );
-    mbedtls_md5_finish( &md5_ctx, md5sum );
+    if( ( ret = mbedtls_md5_starts_ret( &md5_ctx ) ) != 0 )
+        goto exit;
+    if( ( ret = mbedtls_md5_update_ret( &md5_ctx, md5sum, 16 ) ) != 0 )
+        goto exit;
+    if( ( ret = mbedtls_md5_update_ret( &md5_ctx, pwd, pwdlen ) ) != 0 )
+        goto exit;
+    if( ( ret = mbedtls_md5_update_ret( &md5_ctx, iv, 8 ) ) != 0 )
+        goto exit;
+    if( ( ret = mbedtls_md5_finish_ret( &md5_ctx, md5sum ) ) != 0 )
+        goto exit;
 
     use_len = 16;
     if( keylen < 32 )
@@ -126,8 +133,11 @@
 
     memcpy( key + 16, md5sum, use_len );
 
+exit:
     mbedtls_md5_free( &md5_ctx );
     mbedtls_zeroize( md5sum, 16 );
+
+    return( ret );
 }
 
 #if defined(MBEDTLS_DES_C)
@@ -144,7 +154,8 @@
 
     mbedtls_des_init( &des_ctx );
 
-    pem_pbkdf1( des_key, 8, des_iv, pwd, pwdlen );
+    if( ( ret = pem_pbkdf1( des_key, 8, des_iv, pwd, pwdlen ) ) != 0 )
+        goto exit;
 
     if( ( ret = mbedtls_des_setkey_dec( &des_ctx, des_key ) ) != 0 )
         goto exit;
@@ -171,7 +182,8 @@
 
     mbedtls_des3_init( &des3_ctx );
 
-    pem_pbkdf1( des3_key, 24, des3_iv, pwd, pwdlen );
+    if( ( ret = pem_pbkdf1( des3_key, 24, des3_iv, pwd, pwdlen ) ) != 0 )
+        goto exit;
 
     if( ( ret = mbedtls_des3_set3key_dec( &des3_ctx, des3_key ) ) != 0 )
         goto exit;
@@ -200,7 +212,8 @@
 
     mbedtls_aes_init( &aes_ctx );
 
-    pem_pbkdf1( aes_key, keylen, aes_iv, pwd, pwdlen );
+    if( ( ret = pem_pbkdf1( aes_key, keylen, aes_iv, pwd, pwdlen ) ) != 0 )
+        goto exit;
 
     if( ( ret = mbedtls_aes_setkey_dec( &aes_ctx, aes_key, keylen * 8 ) ) != 0 )
         goto exit;
@@ -346,6 +359,7 @@
 
     if( ( ret = mbedtls_base64_decode( buf, len, &len, s1, s2 - s1 ) ) != 0 )
     {
+        mbedtls_zeroize( buf, len );
         mbedtls_free( buf );
         return( MBEDTLS_ERR_PEM_INVALID_DATA + ret );
     }
@@ -356,6 +370,7 @@
     ( defined(MBEDTLS_DES_C) || defined(MBEDTLS_AES_C) )
         if( pwd == NULL )
         {
+            mbedtls_zeroize( buf, len );
             mbedtls_free( buf );
             return( MBEDTLS_ERR_PEM_PASSWORD_REQUIRED );
         }
@@ -392,10 +407,12 @@
          */
         if( len <= 2 || buf[0] != 0x30 || buf[1] > 0x83 )
         {
+            mbedtls_zeroize( buf, len );
             mbedtls_free( buf );
             return( MBEDTLS_ERR_PEM_PASSWORD_MISMATCH );
         }
 #else
+        mbedtls_zeroize( buf, len );
         mbedtls_free( buf );
         return( MBEDTLS_ERR_PEM_FEATURE_UNAVAILABLE );
 #endif /* MBEDTLS_MD5_C && MBEDTLS_CIPHER_MODE_CBC &&
@@ -410,6 +427,8 @@
 
 void mbedtls_pem_free( mbedtls_pem_context *ctx )
 {
+    if( ctx->buf != NULL )
+        mbedtls_zeroize( ctx->buf, ctx->buflen );
     mbedtls_free( ctx->buf );
     mbedtls_free( ctx->info );
 
diff --git a/library/pkparse.c b/library/pkparse.c
index f97d89e..b4def4f 100644
--- a/library/pkparse.c
+++ b/library/pkparse.c
@@ -104,7 +104,10 @@
     if( fread( *buf, 1, *n, f ) != *n )
     {
         fclose( f );
+
+        mbedtls_zeroize( *buf, *n );
         mbedtls_free( *buf );
+
         return( MBEDTLS_ERR_PK_FILE_IO_ERROR );
     }
 
diff --git a/library/platform.c b/library/platform.c
index af3b2f1..76df7fa 100644
--- a/library/platform.c
+++ b/library/platform.c
@@ -29,6 +29,14 @@
 
 #include "mbedtls/platform.h"
 
+#if defined(MBEDTLS_ENTROPY_NV_SEED) && \
+    !defined(MBEDTLS_PLATFORM_NO_STD_FUNCTIONS) && defined(MBEDTLS_FS_IO)
+/* Implementation that should never be optimized out by the compiler */
+static void mbedtls_zeroize( void *v, size_t n ) {
+    volatile unsigned char *p = (unsigned char*)v; while( n-- ) *p++ = 0;
+}
+#endif
+
 #if defined(MBEDTLS_PLATFORM_MEMORY)
 #if !defined(MBEDTLS_PLATFORM_STD_CALLOC)
 static void *platform_calloc_uninit( size_t n, size_t size )
@@ -228,12 +236,13 @@
     size_t n;
 
     if( ( file = fopen( MBEDTLS_PLATFORM_STD_NV_SEED_FILE, "rb" ) ) == NULL )
-        return -1;
+        return( -1 );
 
     if( ( n = fread( buf, 1, buf_len, file ) ) != buf_len )
     {
         fclose( file );
-        return -1;
+        mbedtls_zeroize( buf, buf_len );
+        return( -1 );
     }
 
     fclose( file );
diff --git a/library/ripemd160.c b/library/ripemd160.c
index cdb0a63..b85b117 100644
--- a/library/ripemd160.c
+++ b/library/ripemd160.c
@@ -46,6 +46,8 @@
 #endif /* MBEDTLS_PLATFORM_C */
 #endif /* MBEDTLS_SELF_TEST */
 
+#if !defined(MBEDTLS_RIPEMD160_ALT)
+
 /*
  * 32-bit integer manipulation macros (little endian)
  */
@@ -96,7 +98,7 @@
 /*
  * RIPEMD-160 context setup
  */
-void mbedtls_ripemd160_starts( mbedtls_ripemd160_context *ctx )
+int mbedtls_ripemd160_starts_ret( mbedtls_ripemd160_context *ctx )
 {
     ctx->total[0] = 0;
     ctx->total[1] = 0;
@@ -106,13 +108,16 @@
     ctx->state[2] = 0x98BADCFE;
     ctx->state[3] = 0x10325476;
     ctx->state[4] = 0xC3D2E1F0;
+
+    return( 0 );
 }
 
 #if !defined(MBEDTLS_RIPEMD160_PROCESS_ALT)
 /*
  * Process one block
  */
-void mbedtls_ripemd160_process( mbedtls_ripemd160_context *ctx, const unsigned char data[64] )
+int mbedtls_internal_ripemd160_process( mbedtls_ripemd160_context *ctx,
+                                        const unsigned char data[64] )
 {
     uint32_t A, B, C, D, E, Ap, Bp, Cp, Dp, Ep, X[16];
 
@@ -287,20 +292,24 @@
     ctx->state[3] = ctx->state[4] + A + Bp;
     ctx->state[4] = ctx->state[0] + B + Cp;
     ctx->state[0] = C;
+
+    return( 0 );
 }
 #endif /* !MBEDTLS_RIPEMD160_PROCESS_ALT */
 
 /*
  * RIPEMD-160 process buffer
  */
-void mbedtls_ripemd160_update( mbedtls_ripemd160_context *ctx,
-                       const unsigned char *input, size_t ilen )
+int mbedtls_ripemd160_update_ret( mbedtls_ripemd160_context *ctx,
+                                  const unsigned char *input,
+                                  size_t ilen )
 {
+    int ret;
     size_t fill;
     uint32_t left;
 
     if( ilen == 0 )
-        return;
+        return( 0 );
 
     left = ctx->total[0] & 0x3F;
     fill = 64 - left;
@@ -314,7 +323,10 @@
     if( left && ilen >= fill )
     {
         memcpy( (void *) (ctx->buffer + left), input, fill );
-        mbedtls_ripemd160_process( ctx, ctx->buffer );
+
+        if( ( ret = mbedtls_internal_ripemd160_process( ctx, ctx->buffer ) ) != 0 )
+            return( ret );
+
         input += fill;
         ilen  -= fill;
         left = 0;
@@ -322,7 +334,9 @@
 
     while( ilen >= 64 )
     {
-        mbedtls_ripemd160_process( ctx, input );
+        if( ( ret = mbedtls_internal_ripemd160_process( ctx, input ) ) != 0 )
+            return( ret );
+
         input += 64;
         ilen  -= 64;
     }
@@ -331,6 +345,8 @@
     {
         memcpy( (void *) (ctx->buffer + left), input, ilen );
     }
+
+    return( 0 );
 }
 
 static const unsigned char ripemd160_padding[64] =
@@ -344,8 +360,10 @@
 /*
  * RIPEMD-160 final digest
  */
-void mbedtls_ripemd160_finish( mbedtls_ripemd160_context *ctx, unsigned char output[20] )
+int mbedtls_ripemd160_finish_ret( mbedtls_ripemd160_context *ctx,
+                                  unsigned char output[20] )
 {
+    int ret;
     uint32_t last, padn;
     uint32_t high, low;
     unsigned char msglen[8];
@@ -360,29 +378,50 @@
     last = ctx->total[0] & 0x3F;
     padn = ( last < 56 ) ? ( 56 - last ) : ( 120 - last );
 
-    mbedtls_ripemd160_update( ctx, ripemd160_padding, padn );
-    mbedtls_ripemd160_update( ctx, msglen, 8 );
+    ret = mbedtls_ripemd160_update_ret( ctx, ripemd160_padding, padn );
+    if( ret != 0 )
+        return( ret );
+
+    ret = mbedtls_ripemd160_update_ret( ctx, msglen, 8 );
+    if( ret != 0 )
+        return( ret );
 
     PUT_UINT32_LE( ctx->state[0], output,  0 );
     PUT_UINT32_LE( ctx->state[1], output,  4 );
     PUT_UINT32_LE( ctx->state[2], output,  8 );
     PUT_UINT32_LE( ctx->state[3], output, 12 );
     PUT_UINT32_LE( ctx->state[4], output, 16 );
+
+    return( 0 );
 }
 
+#endif /* ! MBEDTLS_RIPEMD160_ALT */
+
 /*
  * output = RIPEMD-160( input buffer )
  */
-void mbedtls_ripemd160( const unsigned char *input, size_t ilen,
-                unsigned char output[20] )
+int mbedtls_ripemd160_ret( const unsigned char *input,
+                           size_t ilen,
+                           unsigned char output[20] )
 {
+    int ret;
     mbedtls_ripemd160_context ctx;
 
     mbedtls_ripemd160_init( &ctx );
-    mbedtls_ripemd160_starts( &ctx );
-    mbedtls_ripemd160_update( &ctx, input, ilen );
-    mbedtls_ripemd160_finish( &ctx, output );
+
+    if( ( ret = mbedtls_ripemd160_starts_ret( &ctx ) ) != 0 )
+        goto exit;
+
+    if( ( ret = mbedtls_ripemd160_update_ret( &ctx, input, ilen ) ) != 0 )
+        goto exit;
+
+    if( ( ret = mbedtls_ripemd160_finish_ret( &ctx, output ) ) != 0 )
+        goto exit;
+
+exit:
     mbedtls_ripemd160_free( &ctx );
+
+    return( ret );
 }
 
 #if defined(MBEDTLS_SELF_TEST)
@@ -391,18 +430,22 @@
  * http://homes.esat.kuleuven.be/~bosselae/mbedtls_ripemd160.html#HMAC
  */
 #define TESTS   8
-#define KEYS    2
-static const char *ripemd160_test_input[TESTS] =
+static const unsigned char ripemd160_test_str[TESTS][81] =
 {
-    "",
-    "a",
-    "abc",
-    "message digest",
-    "abcdefghijklmnopqrstuvwxyz",
-    "abcdbcdecdefdefgefghfghighijhijkijkljklmklmnlmnomnopnopq",
-    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789",
-    "1234567890123456789012345678901234567890"
-        "1234567890123456789012345678901234567890",
+    { "" },
+    { "a" },
+    { "abc" },
+    { "message digest" },
+    { "abcdefghijklmnopqrstuvwxyz" },
+    { "abcdbcdecdefdefgefghfghighijhijkijkljklmklmnlmnomnopnopq" },
+    { "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789" },
+    { "12345678901234567890123456789012345678901234567890123456789012"
+      "345678901234567890" },
+};
+
+static const size_t ripemd160_test_strlen[TESTS] =
+{
+    0, 1, 3, 14, 26, 56, 62, 80
 };
 
 static const unsigned char ripemd160_test_md[TESTS][20] =
@@ -430,7 +473,7 @@
  */
 int mbedtls_ripemd160_self_test( int verbose )
 {
-    int i;
+    int i, ret = 0;
     unsigned char output[20];
 
     memset( output, 0, sizeof output );
@@ -440,16 +483,15 @@
         if( verbose != 0 )
             mbedtls_printf( "  RIPEMD-160 test #%d: ", i + 1 );
 
-        mbedtls_ripemd160( (const unsigned char *) ripemd160_test_input[i],
-                   strlen( ripemd160_test_input[i] ),
-                   output );
+        ret = mbedtls_ripemd160_ret( ripemd160_test_str[i],
+                                     ripemd160_test_strlen[i], output );
+        if( ret != 0 )
+            goto fail;
 
         if( memcmp( output, ripemd160_test_md[i], 20 ) != 0 )
         {
-            if( verbose != 0 )
-                mbedtls_printf( "failed\n" );
-
-            return( 1 );
+            ret = 1;
+            goto fail;
         }
 
         if( verbose != 0 )
@@ -460,6 +502,12 @@
         mbedtls_printf( "\n" );
 
     return( 0 );
+
+fail:
+    if( verbose != 0 )
+        mbedtls_printf( "failed\n" );
+
+    return( ret );
 }
 
 #endif /* MBEDTLS_SELF_TEST */
diff --git a/library/rsa.c b/library/rsa.c
index 8c0d8c3..6526978 100644
--- a/library/rsa.c
+++ b/library/rsa.c
@@ -942,7 +942,7 @@
  * \param slen      length of the source buffer
  * \param md_ctx    message digest context to use
  */
-static void mgf_mask( unsigned char *dst, size_t dlen, unsigned char *src,
+static int mgf_mask( unsigned char *dst, size_t dlen, unsigned char *src,
                       size_t slen, mbedtls_md_context_t *md_ctx )
 {
     unsigned char mask[MBEDTLS_MD_MAX_SIZE];
@@ -950,6 +950,7 @@
     unsigned char *p;
     unsigned int hlen;
     size_t i, use_len;
+    int ret = 0;
 
     memset( mask, 0, MBEDTLS_MD_MAX_SIZE );
     memset( counter, 0, 4 );
@@ -965,10 +966,14 @@
         if( dlen < hlen )
             use_len = dlen;
 
-        mbedtls_md_starts( md_ctx );
-        mbedtls_md_update( md_ctx, src, slen );
-        mbedtls_md_update( md_ctx, counter, 4 );
-        mbedtls_md_finish( md_ctx, mask );
+        if( ( ret = mbedtls_md_starts( md_ctx ) ) != 0 )
+            goto exit;
+        if( ( ret = mbedtls_md_update( md_ctx, src, slen ) ) != 0 )
+            goto exit;
+        if( ( ret = mbedtls_md_update( md_ctx, counter, 4 ) ) != 0 )
+            goto exit;
+        if( ( ret = mbedtls_md_finish( md_ctx, mask ) ) != 0 )
+            goto exit;
 
         for( i = 0; i < use_len; ++i )
             *p++ ^= mask[i];
@@ -978,7 +983,10 @@
         dlen -= use_len;
     }
 
+exit:
     mbedtls_zeroize( mask, sizeof( mask ) );
+
+    return( ret );
 }
 #endif /* MBEDTLS_PKCS1_V21 */
 
@@ -1030,7 +1038,8 @@
     p += hlen;
 
     /* Construct DB */
-    mbedtls_md( md_info, label, label_len, p );
+    if( ( ret = mbedtls_md( md_info, label, label_len, p ) ) != 0 )
+        return( ret );
     p += hlen;
     p += olen - 2 * hlen - 2 - ilen;
     *p++ = 1;
@@ -1038,21 +1047,24 @@
 
     mbedtls_md_init( &md_ctx );
     if( ( ret = mbedtls_md_setup( &md_ctx, md_info, 0 ) ) != 0 )
-    {
-        mbedtls_md_free( &md_ctx );
-        return( ret );
-    }
+        goto exit;
 
     /* maskedDB: Apply dbMask to DB */
-    mgf_mask( output + hlen + 1, olen - hlen - 1, output + 1, hlen,
-               &md_ctx );
+    if( ( ret = mgf_mask( output + hlen + 1, olen - hlen - 1, output + 1, hlen,
+                          &md_ctx ) ) != 0 )
+        goto exit;
 
     /* maskedSeed: Apply seedMask to seed */
-    mgf_mask( output + 1, hlen, output + hlen + 1, olen - hlen - 1,
-               &md_ctx );
+    if( ( ret = mgf_mask( output + 1, hlen, output + hlen + 1, olen - hlen - 1,
+                          &md_ctx ) ) != 0 )
+        goto exit;
 
+exit:
     mbedtls_md_free( &md_ctx );
 
+    if( ret != 0 )
+        return( ret );
+
     return( ( mode == MBEDTLS_RSA_PUBLIC )
             ? mbedtls_rsa_public(  ctx, output, output )
             : mbedtls_rsa_private( ctx, f_rng, p_rng, output, output ) );
@@ -1219,20 +1231,23 @@
         goto cleanup;
     }
 
-
-    /* Generate lHash */
-    mbedtls_md( md_info, label, label_len, lhash );
-
     /* seed: Apply seedMask to maskedSeed */
-    mgf_mask( buf + 1, hlen, buf + hlen + 1, ilen - hlen - 1,
-               &md_ctx );
-
+    if( ( ret = mgf_mask( buf + 1, hlen, buf + hlen + 1, ilen - hlen - 1,
+                          &md_ctx ) ) != 0 ||
     /* DB: Apply dbMask to maskedDB */
-    mgf_mask( buf + hlen + 1, ilen - hlen - 1, buf + 1, hlen,
-               &md_ctx );
+        ( ret = mgf_mask( buf + hlen + 1, ilen - hlen - 1, buf + 1, hlen,
+                          &md_ctx ) ) != 0 )
+    {
+        mbedtls_md_free( &md_ctx );
+        goto cleanup;
+    }
 
     mbedtls_md_free( &md_ctx );
 
+    /* Generate lHash */
+    if( ( ret = mbedtls_md( md_info, label, label_len, lhash ) ) != 0 )
+        goto cleanup;
+
     /*
      * Check contents, in "constant-time"
      */
@@ -1483,28 +1498,28 @@
 
     mbedtls_md_init( &md_ctx );
     if( ( ret = mbedtls_md_setup( &md_ctx, md_info, 0 ) ) != 0 )
-    {
-        mbedtls_md_free( &md_ctx );
-        /* No need to zeroize salt: we didn't use it. */
-        return( ret );
-    }
+        goto exit;
 
     /* Generate H = Hash( M' ) */
-    mbedtls_md_starts( &md_ctx );
-    mbedtls_md_update( &md_ctx, p, 8 );
-    mbedtls_md_update( &md_ctx, hash, hashlen );
-    mbedtls_md_update( &md_ctx, salt, slen );
-    mbedtls_md_finish( &md_ctx, p );
-    mbedtls_zeroize( salt, sizeof( salt ) );
+    if( ( ret = mbedtls_md_starts( &md_ctx ) ) != 0 )
+        goto exit;
+    if( ( ret = mbedtls_md_update( &md_ctx, p, 8 ) ) != 0 )
+        goto exit;
+    if( ( ret = mbedtls_md_update( &md_ctx, hash, hashlen ) ) != 0 )
+        goto exit;
+    if( ( ret = mbedtls_md_update( &md_ctx, salt, slen ) ) != 0 )
+        goto exit;
+    if( ( ret = mbedtls_md_finish( &md_ctx, p ) ) != 0 )
+        goto exit;
 
     /* Compensate for boundary condition when applying mask */
     if( msb % 8 == 0 )
         offset = 1;
 
     /* maskedDB: Apply dbMask to DB */
-    mgf_mask( sig + offset, olen - hlen - 1 - offset, p, hlen, &md_ctx );
-
-    mbedtls_md_free( &md_ctx );
+    if( ( ret = mgf_mask( sig + offset, olen - hlen - 1 - offset, p, hlen,
+                          &md_ctx ) ) != 0 )
+        goto exit;
 
     msb = mbedtls_mpi_bitlen( &ctx->N ) - 1;
     sig[0] &= 0xFF >> ( olen * 8 - msb );
@@ -1512,6 +1527,14 @@
     p += hlen;
     *p++ = 0xBC;
 
+    mbedtls_zeroize( salt, sizeof( salt ) );
+
+exit:
+    mbedtls_md_free( &md_ctx );
+
+    if( ret != 0 )
+        return( ret );
+
     return( ( mode == MBEDTLS_RSA_PUBLIC )
             ? mbedtls_rsa_public(  ctx, sig, sig )
             : mbedtls_rsa_private( ctx, f_rng, p_rng, sig, sig ) );
@@ -1774,10 +1797,11 @@
     int ret;
     size_t siglen;
     unsigned char *p;
+    unsigned char *hash_start;
     unsigned char result[MBEDTLS_MD_MAX_SIZE];
     unsigned char zeros[8];
     unsigned int hlen;
-    size_t slen, msb;
+    size_t observed_salt_len, msb;
     const mbedtls_md_info_t *md_info;
     mbedtls_md_context_t md_ctx;
     unsigned char buf[MBEDTLS_MPI_MAX_SIZE];
@@ -1817,7 +1841,6 @@
         return( MBEDTLS_ERR_RSA_BAD_INPUT_DATA );
 
     hlen = mbedtls_md_get_size( md_info );
-    slen = siglen - hlen - 1; /* Currently length of salt + padding */
 
     memset( zeros, 0, 8 );
 
@@ -1826,61 +1849,77 @@
      */
     msb = mbedtls_mpi_bitlen( &ctx->N ) - 1;
 
+    if( buf[0] >> ( 8 - siglen * 8 + msb ) )
+        return( MBEDTLS_ERR_RSA_BAD_INPUT_DATA );
+
     /* Compensate for boundary condition when applying mask */
     if( msb % 8 == 0 )
     {
         p++;
         siglen -= 1;
     }
-    if( buf[0] >> ( 8 - siglen * 8 + msb ) )
+
+    if( siglen < hlen + 2 )
         return( MBEDTLS_ERR_RSA_BAD_INPUT_DATA );
+    hash_start = p + siglen - hlen - 1;
 
     mbedtls_md_init( &md_ctx );
     if( ( ret = mbedtls_md_setup( &md_ctx, md_info, 0 ) ) != 0 )
-    {
-        mbedtls_md_free( &md_ctx );
-        return( ret );
-    }
+        goto exit;
 
-    mgf_mask( p, siglen - hlen - 1, p + siglen - hlen - 1, hlen, &md_ctx );
+    ret = mgf_mask( p, siglen - hlen - 1, hash_start, hlen, &md_ctx );
+    if( ret != 0 )
+        goto exit;
 
     buf[0] &= 0xFF >> ( siglen * 8 - msb );
 
-    while( p < buf + siglen && *p == 0 )
+    while( p < hash_start - 1 && *p == 0 )
         p++;
 
-    if( p == buf + siglen ||
-        *p++ != 0x01 )
+    if( *p++ != 0x01 )
     {
-        mbedtls_md_free( &md_ctx );
-        return( MBEDTLS_ERR_RSA_INVALID_PADDING );
+        ret = MBEDTLS_ERR_RSA_INVALID_PADDING;
+        goto exit;
     }
 
-    /* Actual salt len */
-    slen -= p - buf;
+    observed_salt_len = hash_start - p;
 
     if( expected_salt_len != MBEDTLS_RSA_SALT_LEN_ANY &&
-        slen != (size_t) expected_salt_len )
+        observed_salt_len != (size_t) expected_salt_len )
     {
-        mbedtls_md_free( &md_ctx );
-        return( MBEDTLS_ERR_RSA_INVALID_PADDING );
+        ret = MBEDTLS_ERR_RSA_INVALID_PADDING;
+        goto exit;
     }
 
     /*
      * Generate H = Hash( M' )
      */
-    mbedtls_md_starts( &md_ctx );
-    mbedtls_md_update( &md_ctx, zeros, 8 );
-    mbedtls_md_update( &md_ctx, hash, hashlen );
-    mbedtls_md_update( &md_ctx, p, slen );
-    mbedtls_md_finish( &md_ctx, result );
+    ret = mbedtls_md_starts( &md_ctx );
+    if ( ret != 0 )
+        goto exit;
+    ret = mbedtls_md_update( &md_ctx, zeros, 8 );
+    if ( ret != 0 )
+        goto exit;
+    ret = mbedtls_md_update( &md_ctx, hash, hashlen );
+    if ( ret != 0 )
+        goto exit;
+    ret = mbedtls_md_update( &md_ctx, p, observed_salt_len );
+    if ( ret != 0 )
+        goto exit;
+    ret = mbedtls_md_finish( &md_ctx, result );
+    if ( ret != 0 )
+        goto exit;
 
+    if( memcmp( hash_start, result, hlen ) != 0 )
+    {
+        ret = MBEDTLS_ERR_RSA_VERIFY_FAILED;
+        goto exit;
+    }
+
+exit:
     mbedtls_md_free( &md_ctx );
 
-    if( memcmp( p + slen, result, hlen ) == 0 )
-        return( 0 );
-    else
-        return( MBEDTLS_ERR_RSA_VERIFY_FAILED );
+    return( ret );
 }
 
 /*
@@ -2229,7 +2268,13 @@
     if( verbose != 0 )
         mbedtls_printf( "  PKCS#1 data sign  : " );
 
-    mbedtls_sha1( rsa_plaintext, PT_LEN, sha1sum );
+    if( mbedtls_sha1_ret( rsa_plaintext, PT_LEN, sha1sum ) != 0 )
+    {
+        if( verbose != 0 )
+            mbedtls_printf( "failed\n" );
+
+        return( 1 );
+    }
 
     if( mbedtls_rsa_pkcs1_sign( &rsa, myrand, NULL,
                                 MBEDTLS_RSA_PRIVATE, MBEDTLS_MD_SHA1, 0,
diff --git a/library/sha1.c b/library/sha1.c
index 2ccf2a2..8432eba 100644
--- a/library/sha1.c
+++ b/library/sha1.c
@@ -97,7 +97,7 @@
 /*
  * SHA-1 context setup
  */
-void mbedtls_sha1_starts( mbedtls_sha1_context *ctx )
+int mbedtls_sha1_starts_ret( mbedtls_sha1_context *ctx )
 {
     ctx->total[0] = 0;
     ctx->total[1] = 0;
@@ -107,10 +107,13 @@
     ctx->state[2] = 0x98BADCFE;
     ctx->state[3] = 0x10325476;
     ctx->state[4] = 0xC3D2E1F0;
+
+    return( 0 );
 }
 
 #if !defined(MBEDTLS_SHA1_PROCESS_ALT)
-void mbedtls_sha1_process( mbedtls_sha1_context *ctx, const unsigned char data[64] )
+int mbedtls_internal_sha1_process( mbedtls_sha1_context *ctx,
+                                   const unsigned char data[64] )
 {
     uint32_t temp, W[16], A, B, C, D, E;
 
@@ -264,19 +267,24 @@
     ctx->state[2] += C;
     ctx->state[3] += D;
     ctx->state[4] += E;
+
+    return( 0 );
 }
 #endif /* !MBEDTLS_SHA1_PROCESS_ALT */
 
 /*
  * SHA-1 process buffer
  */
-void mbedtls_sha1_update( mbedtls_sha1_context *ctx, const unsigned char *input, size_t ilen )
+int mbedtls_sha1_update_ret( mbedtls_sha1_context *ctx,
+                             const unsigned char *input,
+                             size_t ilen )
 {
+    int ret;
     size_t fill;
     uint32_t left;
 
     if( ilen == 0 )
-        return;
+        return( 0 );
 
     left = ctx->total[0] & 0x3F;
     fill = 64 - left;
@@ -290,7 +298,10 @@
     if( left && ilen >= fill )
     {
         memcpy( (void *) (ctx->buffer + left), input, fill );
-        mbedtls_sha1_process( ctx, ctx->buffer );
+
+        if( ( ret = mbedtls_internal_sha1_process( ctx, ctx->buffer ) ) != 0 )
+            return( ret );
+
         input += fill;
         ilen  -= fill;
         left = 0;
@@ -298,13 +309,17 @@
 
     while( ilen >= 64 )
     {
-        mbedtls_sha1_process( ctx, input );
+        if( ( ret = mbedtls_internal_sha1_process( ctx, input ) ) != 0 )
+            return( ret );
+
         input += 64;
         ilen  -= 64;
     }
 
     if( ilen > 0 )
         memcpy( (void *) (ctx->buffer + left), input, ilen );
+
+    return( 0 );
 }
 
 static const unsigned char sha1_padding[64] =
@@ -318,8 +333,10 @@
 /*
  * SHA-1 final digest
  */
-void mbedtls_sha1_finish( mbedtls_sha1_context *ctx, unsigned char output[20] )
+int mbedtls_sha1_finish_ret( mbedtls_sha1_context *ctx,
+                             unsigned char output[20] )
 {
+    int ret;
     uint32_t last, padn;
     uint32_t high, low;
     unsigned char msglen[8];
@@ -334,14 +351,18 @@
     last = ctx->total[0] & 0x3F;
     padn = ( last < 56 ) ? ( 56 - last ) : ( 120 - last );
 
-    mbedtls_sha1_update( ctx, sha1_padding, padn );
-    mbedtls_sha1_update( ctx, msglen, 8 );
+    if( ( ret = mbedtls_sha1_update_ret( ctx, sha1_padding, padn ) ) != 0 )
+        return( ret );
+    if( ( ret = mbedtls_sha1_update_ret( ctx, msglen, 8 ) ) != 0 )
+        return( ret );
 
     PUT_UINT32_BE( ctx->state[0], output,  0 );
     PUT_UINT32_BE( ctx->state[1], output,  4 );
     PUT_UINT32_BE( ctx->state[2], output,  8 );
     PUT_UINT32_BE( ctx->state[3], output, 12 );
     PUT_UINT32_BE( ctx->state[4], output, 16 );
+
+    return( 0 );
 }
 
 #endif /* !MBEDTLS_SHA1_ALT */
@@ -349,15 +370,28 @@
 /*
  * output = SHA-1( input buffer )
  */
-void mbedtls_sha1( const unsigned char *input, size_t ilen, unsigned char output[20] )
+int mbedtls_sha1_ret( const unsigned char *input,
+                      size_t ilen,
+                      unsigned char output[20] )
 {
+    int ret;
     mbedtls_sha1_context ctx;
 
     mbedtls_sha1_init( &ctx );
-    mbedtls_sha1_starts( &ctx );
-    mbedtls_sha1_update( &ctx, input, ilen );
-    mbedtls_sha1_finish( &ctx, output );
+
+    if( ( ret = mbedtls_sha1_starts_ret( &ctx ) ) != 0 )
+        goto exit;
+
+    if( ( ret = mbedtls_sha1_update_ret( &ctx, input, ilen ) ) != 0 )
+        goto exit;
+
+    if( ( ret = mbedtls_sha1_finish_ret( &ctx, output ) ) != 0 )
+        goto exit;
+
+exit:
     mbedtls_sha1_free( &ctx );
+
+    return( ret );
 }
 
 #if defined(MBEDTLS_SELF_TEST)
@@ -371,7 +405,7 @@
     { "" }
 };
 
-static const int sha1_test_buflen[3] =
+static const size_t sha1_test_buflen[3] =
 {
     3, 56, 1000
 };
@@ -406,28 +440,35 @@
         if( verbose != 0 )
             mbedtls_printf( "  SHA-1 test #%d: ", i + 1 );
 
-        mbedtls_sha1_starts( &ctx );
+        if( ( ret = mbedtls_sha1_starts_ret( &ctx ) ) != 0 )
+            goto fail;
 
         if( i == 2 )
         {
             memset( buf, 'a', buflen = 1000 );
 
             for( j = 0; j < 1000; j++ )
-                mbedtls_sha1_update( &ctx, buf, buflen );
+            {
+                ret = mbedtls_sha1_update_ret( &ctx, buf, buflen );
+                if( ret != 0 )
+                    goto fail;
+            }
         }
         else
-            mbedtls_sha1_update( &ctx, sha1_test_buf[i],
-                               sha1_test_buflen[i] );
+        {
+            ret = mbedtls_sha1_update_ret( &ctx, sha1_test_buf[i],
+                                           sha1_test_buflen[i] );
+            if( ret != 0 )
+                goto fail;
+        }
 
-        mbedtls_sha1_finish( &ctx, sha1sum );
+        if( ( ret = mbedtls_sha1_finish_ret( &ctx, sha1sum ) ) != 0 )
+            goto fail;
 
         if( memcmp( sha1sum, sha1_test_sum[i], 20 ) != 0 )
         {
-            if( verbose != 0 )
-                mbedtls_printf( "failed\n" );
-
             ret = 1;
-            goto exit;
+            goto fail;
         }
 
         if( verbose != 0 )
@@ -437,6 +478,12 @@
     if( verbose != 0 )
         mbedtls_printf( "\n" );
 
+    goto exit;
+
+fail:
+    if( verbose != 0 )
+        mbedtls_printf( "failed\n" );
+
 exit:
     mbedtls_sha1_free( &ctx );
 
diff --git a/library/sha256.c b/library/sha256.c
index ad25d38..abcd64d 100644
--- a/library/sha256.c
+++ b/library/sha256.c
@@ -100,7 +100,7 @@
 /*
  * SHA-256 context setup
  */
-void mbedtls_sha256_starts( mbedtls_sha256_context *ctx, int is224 )
+int mbedtls_sha256_starts_ret( mbedtls_sha256_context *ctx, int is224 )
 {
     ctx->total[0] = 0;
     ctx->total[1] = 0;
@@ -131,6 +131,8 @@
     }
 
     ctx->is224 = is224;
+
+    return( 0 );
 }
 
 #if !defined(MBEDTLS_SHA256_PROCESS_ALT)
@@ -179,7 +181,8 @@
     d += temp1; h = temp1 + temp2;              \
 }
 
-void mbedtls_sha256_process( mbedtls_sha256_context *ctx, const unsigned char data[64] )
+int mbedtls_internal_sha256_process( mbedtls_sha256_context *ctx,
+                                const unsigned char data[64] )
 {
     uint32_t temp1, temp2, W[64];
     uint32_t A[8];
@@ -232,20 +235,24 @@
 
     for( i = 0; i < 8; i++ )
         ctx->state[i] += A[i];
+
+    return( 0 );
 }
 #endif /* !MBEDTLS_SHA256_PROCESS_ALT */
 
 /*
  * SHA-256 process buffer
  */
-void mbedtls_sha256_update( mbedtls_sha256_context *ctx, const unsigned char *input,
-                    size_t ilen )
+int mbedtls_sha256_update_ret( mbedtls_sha256_context *ctx,
+                               const unsigned char *input,
+                               size_t ilen )
 {
+    int ret;
     size_t fill;
     uint32_t left;
 
     if( ilen == 0 )
-        return;
+        return( 0 );
 
     left = ctx->total[0] & 0x3F;
     fill = 64 - left;
@@ -259,7 +266,10 @@
     if( left && ilen >= fill )
     {
         memcpy( (void *) (ctx->buffer + left), input, fill );
-        mbedtls_sha256_process( ctx, ctx->buffer );
+
+        if( ( ret = mbedtls_internal_sha256_process( ctx, ctx->buffer ) ) != 0 )
+            return( ret );
+
         input += fill;
         ilen  -= fill;
         left = 0;
@@ -267,13 +277,17 @@
 
     while( ilen >= 64 )
     {
-        mbedtls_sha256_process( ctx, input );
+        if( ( ret = mbedtls_internal_sha256_process( ctx, input ) ) != 0 )
+            return( ret );
+
         input += 64;
         ilen  -= 64;
     }
 
     if( ilen > 0 )
         memcpy( (void *) (ctx->buffer + left), input, ilen );
+
+    return( 0 );
 }
 
 static const unsigned char sha256_padding[64] =
@@ -287,8 +301,10 @@
 /*
  * SHA-256 final digest
  */
-void mbedtls_sha256_finish( mbedtls_sha256_context *ctx, unsigned char output[32] )
+int mbedtls_sha256_finish_ret( mbedtls_sha256_context *ctx,
+                               unsigned char output[32] )
 {
+    int ret;
     uint32_t last, padn;
     uint32_t high, low;
     unsigned char msglen[8];
@@ -303,8 +319,11 @@
     last = ctx->total[0] & 0x3F;
     padn = ( last < 56 ) ? ( 56 - last ) : ( 120 - last );
 
-    mbedtls_sha256_update( ctx, sha256_padding, padn );
-    mbedtls_sha256_update( ctx, msglen, 8 );
+    if( ( ret = mbedtls_sha256_update_ret( ctx, sha256_padding, padn ) ) != 0 )
+        return( ret );
+
+    if( ( ret = mbedtls_sha256_update_ret( ctx, msglen, 8 ) ) != 0 )
+        return( ret );
 
     PUT_UINT32_BE( ctx->state[0], output,  0 );
     PUT_UINT32_BE( ctx->state[1], output,  4 );
@@ -316,6 +335,8 @@
 
     if( ctx->is224 == 0 )
         PUT_UINT32_BE( ctx->state[7], output, 28 );
+
+    return( 0 );
 }
 
 #endif /* !MBEDTLS_SHA256_ALT */
@@ -323,16 +344,29 @@
 /*
  * output = SHA-256( input buffer )
  */
-void mbedtls_sha256( const unsigned char *input, size_t ilen,
-             unsigned char output[32], int is224 )
+int mbedtls_sha256_ret( const unsigned char *input,
+                        size_t ilen,
+                        unsigned char output[32],
+                        int is224 )
 {
+    int ret;
     mbedtls_sha256_context ctx;
 
     mbedtls_sha256_init( &ctx );
-    mbedtls_sha256_starts( &ctx, is224 );
-    mbedtls_sha256_update( &ctx, input, ilen );
-    mbedtls_sha256_finish( &ctx, output );
+
+    if( ( ret = mbedtls_sha256_starts_ret( &ctx, is224 ) ) != 0 )
+        goto exit;
+
+    if( ( ret = mbedtls_sha256_update_ret( &ctx, input, ilen ) ) != 0 )
+        goto exit;
+
+    if( ( ret = mbedtls_sha256_finish_ret( &ctx, output ) ) != 0 )
+        goto exit;
+
+exit:
     mbedtls_sha256_free( &ctx );
+
+    return( ret );
 }
 
 #if defined(MBEDTLS_SELF_TEST)
@@ -346,7 +380,7 @@
     { "" }
 };
 
-static const int sha256_test_buflen[3] =
+static const size_t sha256_test_buflen[3] =
 {
     3, 56, 1000
 };
@@ -415,28 +449,37 @@
         if( verbose != 0 )
             mbedtls_printf( "  SHA-%d test #%d: ", 256 - k * 32, j + 1 );
 
-        mbedtls_sha256_starts( &ctx, k );
+        if( ( ret = mbedtls_sha256_starts_ret( &ctx, k ) ) != 0 )
+            goto fail;
 
         if( j == 2 )
         {
             memset( buf, 'a', buflen = 1000 );
 
             for( j = 0; j < 1000; j++ )
-                mbedtls_sha256_update( &ctx, buf, buflen );
+            {
+                ret = mbedtls_sha256_update_ret( &ctx, buf, buflen );
+                if( ret != 0 )
+                    goto fail;
+            }
+
         }
         else
-            mbedtls_sha256_update( &ctx, sha256_test_buf[j],
-                                 sha256_test_buflen[j] );
+        {
+            ret = mbedtls_sha256_update_ret( &ctx, sha256_test_buf[j],
+                                             sha256_test_buflen[j] );
+            if( ret != 0 )
+                 goto fail;
+        }
 
-        mbedtls_sha256_finish( &ctx, sha256sum );
+        if( ( ret = mbedtls_sha256_finish_ret( &ctx, sha256sum ) ) != 0 )
+            goto fail;
+
 
         if( memcmp( sha256sum, sha256_test_sum[i], 32 - k * 4 ) != 0 )
         {
-            if( verbose != 0 )
-                mbedtls_printf( "failed\n" );
-
             ret = 1;
-            goto exit;
+            goto fail;
         }
 
         if( verbose != 0 )
@@ -446,6 +489,12 @@
     if( verbose != 0 )
         mbedtls_printf( "\n" );
 
+    goto exit;
+
+fail:
+    if( verbose != 0 )
+        mbedtls_printf( "failed\n" );
+
 exit:
     mbedtls_sha256_free( &ctx );
     mbedtls_free( buf );
diff --git a/library/sha512.c b/library/sha512.c
index 724522a..c99b6da 100644
--- a/library/sha512.c
+++ b/library/sha512.c
@@ -114,7 +114,7 @@
 /*
  * SHA-512 context setup
  */
-void mbedtls_sha512_starts( mbedtls_sha512_context *ctx, int is384 )
+int mbedtls_sha512_starts_ret( mbedtls_sha512_context *ctx, int is384 )
 {
     ctx->total[0] = 0;
     ctx->total[1] = 0;
@@ -145,6 +145,8 @@
     }
 
     ctx->is384 = is384;
+
+    return( 0 );
 }
 
 #if !defined(MBEDTLS_SHA512_PROCESS_ALT)
@@ -196,7 +198,8 @@
     UL64(0x5FCB6FAB3AD6FAEC),  UL64(0x6C44198C4A475817)
 };
 
-void mbedtls_sha512_process( mbedtls_sha512_context *ctx, const unsigned char data[128] )
+int mbedtls_internal_sha512_process( mbedtls_sha512_context *ctx,
+                                     const unsigned char data[128] )
 {
     int i;
     uint64_t temp1, temp2, W[80];
@@ -263,20 +266,24 @@
     ctx->state[5] += F;
     ctx->state[6] += G;
     ctx->state[7] += H;
+
+    return( 0 );
 }
 #endif /* !MBEDTLS_SHA512_PROCESS_ALT */
 
 /*
  * SHA-512 process buffer
  */
-void mbedtls_sha512_update( mbedtls_sha512_context *ctx, const unsigned char *input,
-                    size_t ilen )
+int mbedtls_sha512_update_ret( mbedtls_sha512_context *ctx,
+                               const unsigned char *input,
+                               size_t ilen )
 {
+    int ret;
     size_t fill;
     unsigned int left;
 
     if( ilen == 0 )
-        return;
+        return( 0 );
 
     left = (unsigned int) (ctx->total[0] & 0x7F);
     fill = 128 - left;
@@ -289,7 +296,10 @@
     if( left && ilen >= fill )
     {
         memcpy( (void *) (ctx->buffer + left), input, fill );
-        mbedtls_sha512_process( ctx, ctx->buffer );
+
+        if( ( ret = mbedtls_internal_sha512_process( ctx, ctx->buffer ) ) != 0 )
+            return( ret );
+
         input += fill;
         ilen  -= fill;
         left = 0;
@@ -297,13 +307,17 @@
 
     while( ilen >= 128 )
     {
-        mbedtls_sha512_process( ctx, input );
+        if( ( ret = mbedtls_internal_sha512_process( ctx, input ) ) != 0 )
+            return( ret );
+
         input += 128;
         ilen  -= 128;
     }
 
     if( ilen > 0 )
         memcpy( (void *) (ctx->buffer + left), input, ilen );
+
+    return( 0 );
 }
 
 static const unsigned char sha512_padding[128] =
@@ -321,8 +335,10 @@
 /*
  * SHA-512 final digest
  */
-void mbedtls_sha512_finish( mbedtls_sha512_context *ctx, unsigned char output[64] )
+int mbedtls_sha512_finish_ret( mbedtls_sha512_context *ctx,
+                               unsigned char output[64] )
 {
+    int ret;
     size_t last, padn;
     uint64_t high, low;
     unsigned char msglen[16];
@@ -337,8 +353,11 @@
     last = (size_t)( ctx->total[0] & 0x7F );
     padn = ( last < 112 ) ? ( 112 - last ) : ( 240 - last );
 
-    mbedtls_sha512_update( ctx, sha512_padding, padn );
-    mbedtls_sha512_update( ctx, msglen, 16 );
+    if( ( ret = mbedtls_sha512_update_ret( ctx, sha512_padding, padn ) ) != 0 )
+            return( ret );
+
+    if( ( ret = mbedtls_sha512_update_ret( ctx, msglen, 16 ) ) != 0 )
+            return( ret );
 
     PUT_UINT64_BE( ctx->state[0], output,  0 );
     PUT_UINT64_BE( ctx->state[1], output,  8 );
@@ -352,6 +371,8 @@
         PUT_UINT64_BE( ctx->state[6], output, 48 );
         PUT_UINT64_BE( ctx->state[7], output, 56 );
     }
+
+    return( 0 );
 }
 
 #endif /* !MBEDTLS_SHA512_ALT */
@@ -359,16 +380,29 @@
 /*
  * output = SHA-512( input buffer )
  */
-void mbedtls_sha512( const unsigned char *input, size_t ilen,
-             unsigned char output[64], int is384 )
+int mbedtls_sha512_ret( const unsigned char *input,
+                    size_t ilen,
+                    unsigned char output[64],
+                    int is384 )
 {
+    int ret;
     mbedtls_sha512_context ctx;
 
     mbedtls_sha512_init( &ctx );
-    mbedtls_sha512_starts( &ctx, is384 );
-    mbedtls_sha512_update( &ctx, input, ilen );
-    mbedtls_sha512_finish( &ctx, output );
+
+    if( ( ret = mbedtls_sha512_starts_ret( &ctx, is384 ) ) != 0 )
+        goto exit;
+
+    if( ( ret = mbedtls_sha512_update_ret( &ctx, input, ilen ) ) != 0 )
+        goto exit;
+
+    if( ( ret = mbedtls_sha512_finish_ret( &ctx, output ) ) != 0 )
+        goto exit;
+
+exit:
     mbedtls_sha512_free( &ctx );
+
+    return( ret );
 }
 
 #if defined(MBEDTLS_SELF_TEST)
@@ -384,7 +418,7 @@
     { "" }
 };
 
-static const int sha512_test_buflen[3] =
+static const size_t sha512_test_buflen[3] =
 {
     3, 112, 1000
 };
@@ -471,28 +505,35 @@
         if( verbose != 0 )
             mbedtls_printf( "  SHA-%d test #%d: ", 512 - k * 128, j + 1 );
 
-        mbedtls_sha512_starts( &ctx, k );
+        if( ( ret = mbedtls_sha512_starts_ret( &ctx, k ) ) != 0 )
+            goto fail;
 
         if( j == 2 )
         {
             memset( buf, 'a', buflen = 1000 );
 
             for( j = 0; j < 1000; j++ )
-                mbedtls_sha512_update( &ctx, buf, buflen );
+            {
+                ret = mbedtls_sha512_update_ret( &ctx, buf, buflen );
+                if( ret != 0 )
+                    goto fail;
+            }
         }
         else
-            mbedtls_sha512_update( &ctx, sha512_test_buf[j],
-                                 sha512_test_buflen[j] );
+        {
+            ret = mbedtls_sha512_update_ret( &ctx, sha512_test_buf[j],
+                                             sha512_test_buflen[j] );
+            if( ret != 0 )
+                goto fail;
+        }
 
-        mbedtls_sha512_finish( &ctx, sha512sum );
+        if( ( ret = mbedtls_sha512_finish_ret( &ctx, sha512sum ) ) != 0 )
+            goto fail;
 
         if( memcmp( sha512sum, sha512_test_sum[i], 64 - k * 16 ) != 0 )
         {
-            if( verbose != 0 )
-                mbedtls_printf( "failed\n" );
-
             ret = 1;
-            goto exit;
+            goto fail;
         }
 
         if( verbose != 0 )
@@ -502,6 +543,12 @@
     if( verbose != 0 )
         mbedtls_printf( "\n" );
 
+    goto exit;
+
+fail:
+    if( verbose != 0 )
+        mbedtls_printf( "failed\n" );
+
 exit:
     mbedtls_sha512_free( &ctx );
     mbedtls_free( buf );
diff --git a/library/ssl_cli.c b/library/ssl_cli.c
index 554348f..2534346 100644
--- a/library/ssl_cli.c
+++ b/library/ssl_cli.c
@@ -2498,39 +2498,11 @@
     defined(MBEDTLS_SSL_PROTO_TLS1_1)
         if( md_alg == MBEDTLS_MD_NONE )
         {
-            mbedtls_md5_context mbedtls_md5;
-            mbedtls_sha1_context mbedtls_sha1;
-
-            mbedtls_md5_init(  &mbedtls_md5  );
-            mbedtls_sha1_init( &mbedtls_sha1 );
-
             hashlen = 36;
-
-            /*
-             * digitally-signed struct {
-             *     opaque md5_hash[16];
-             *     opaque sha_hash[20];
-             * };
-             *
-             * md5_hash
-             *     MD5(ClientHello.random + ServerHello.random
-             *                            + ServerParams);
-             * sha_hash
-             *     SHA(ClientHello.random + ServerHello.random
-             *                            + ServerParams);
-             */
-            mbedtls_md5_starts( &mbedtls_md5 );
-            mbedtls_md5_update( &mbedtls_md5, ssl->handshake->randbytes, 64 );
-            mbedtls_md5_update( &mbedtls_md5, params, params_len );
-            mbedtls_md5_finish( &mbedtls_md5, hash );
-
-            mbedtls_sha1_starts( &mbedtls_sha1 );
-            mbedtls_sha1_update( &mbedtls_sha1, ssl->handshake->randbytes, 64 );
-            mbedtls_sha1_update( &mbedtls_sha1, params, params_len );
-            mbedtls_sha1_finish( &mbedtls_sha1, hash + 16 );
-
-            mbedtls_md5_free(  &mbedtls_md5  );
-            mbedtls_sha1_free( &mbedtls_sha1 );
+            ret = mbedtls_ssl_get_key_exchange_md_ssl_tls( ssl, hash, params,
+                                                           params_len );
+            if( ret != 0 )
+                return( ret );
         }
         else
 #endif /* MBEDTLS_SSL_PROTO_SSL3 || MBEDTLS_SSL_PROTO_TLS1 || \
@@ -2539,34 +2511,12 @@
     defined(MBEDTLS_SSL_PROTO_TLS1_2)
         if( md_alg != MBEDTLS_MD_NONE )
         {
-            mbedtls_md_context_t ctx;
-
-            mbedtls_md_init( &ctx );
-
             /* Info from md_alg will be used instead */
             hashlen = 0;
-
-            /*
-             * digitally-signed struct {
-             *     opaque client_random[32];
-             *     opaque server_random[32];
-             *     ServerDHParams params;
-             * };
-             */
-            if( ( ret = mbedtls_md_setup( &ctx,
-                                     mbedtls_md_info_from_type( md_alg ), 0 ) ) != 0 )
-            {
-                MBEDTLS_SSL_DEBUG_RET( 1, "mbedtls_md_setup", ret );
-                mbedtls_ssl_send_alert_message( ssl, MBEDTLS_SSL_ALERT_LEVEL_FATAL,
-                                                MBEDTLS_SSL_ALERT_MSG_INTERNAL_ERROR );
+            ret = mbedtls_ssl_get_key_exchange_md_tls1_2( ssl, hash, params,
+                                                          params_len, md_alg );
+            if( ret != 0 )
                 return( ret );
-            }
-
-            mbedtls_md_starts( &ctx );
-            mbedtls_md_update( &ctx, ssl->handshake->randbytes, 64 );
-            mbedtls_md_update( &ctx, params, params_len );
-            mbedtls_md_finish( &ctx, hash );
-            mbedtls_md_free( &ctx );
         }
         else
 #endif /* MBEDTLS_SSL_PROTO_TLS1 || MBEDTLS_SSL_PROTO_TLS1_1 || \
diff --git a/library/ssl_srv.c b/library/ssl_srv.c
index 37f415d..aca4235 100644
--- a/library/ssl_srv.c
+++ b/library/ssl_srv.c
@@ -603,33 +603,41 @@
     }
 
     /*
-     * Use our order of preference
+     * Validate peer's list (lengths)
      */
     start = buf + 2;
     end = buf + len;
+    for( theirs = start; theirs != end; theirs += cur_len )
+    {
+        cur_len = *theirs++;
+
+        /* Current identifier must fit in list */
+        if( cur_len > (size_t)( end - theirs ) )
+        {
+            mbedtls_ssl_send_alert_message( ssl, MBEDTLS_SSL_ALERT_LEVEL_FATAL,
+                                            MBEDTLS_SSL_ALERT_MSG_DECODE_ERROR );
+            return( MBEDTLS_ERR_SSL_BAD_HS_CLIENT_HELLO );
+        }
+
+        /* Empty strings MUST NOT be included */
+        if( cur_len == 0 )
+        {
+            mbedtls_ssl_send_alert_message( ssl, MBEDTLS_SSL_ALERT_LEVEL_FATAL,
+                                            MBEDTLS_SSL_ALERT_MSG_ILLEGAL_PARAMETER );
+            return( MBEDTLS_ERR_SSL_BAD_HS_CLIENT_HELLO );
+        }
+    }
+
+    /*
+     * Use our order of preference
+     */
     for( ours = ssl->conf->alpn_list; *ours != NULL; ours++ )
     {
         ours_len = strlen( *ours );
         for( theirs = start; theirs != end; theirs += cur_len )
         {
-            /* If the list is well formed, we should get equality first */
-            if( theirs > end )
-            {
-                mbedtls_ssl_send_alert_message( ssl, MBEDTLS_SSL_ALERT_LEVEL_FATAL,
-                                                MBEDTLS_SSL_ALERT_MSG_ILLEGAL_PARAMETER );
-                return( MBEDTLS_ERR_SSL_BAD_HS_CLIENT_HELLO );
-            }
-
             cur_len = *theirs++;
 
-            /* Empty strings MUST NOT be included */
-            if( cur_len == 0 )
-            {
-                mbedtls_ssl_send_alert_message( ssl, MBEDTLS_SSL_ALERT_LEVEL_FATAL,
-                                                MBEDTLS_SSL_ALERT_MSG_ILLEGAL_PARAMETER );
-                return( MBEDTLS_ERR_SSL_BAD_HS_CLIENT_HELLO );
-            }
-
             if( cur_len == ours_len &&
                 memcmp( theirs, *ours, cur_len ) == 0 )
             {
@@ -2042,7 +2050,7 @@
     const mbedtls_ssl_ciphersuite_t *suite = NULL;
     const mbedtls_cipher_info_t *cipher = NULL;
 
-    if( ssl->session_negotiate->encrypt_then_mac == MBEDTLS_SSL_EXTENDED_MS_DISABLED ||
+    if( ssl->session_negotiate->encrypt_then_mac == MBEDTLS_SSL_ETM_DISABLED ||
         ssl->minor_ver == MBEDTLS_SSL_MINOR_VERSION_0 )
     {
         *olen = 0;
@@ -2937,10 +2945,11 @@
          *     opaque dh_Ys<1..2^16-1>;
          * } ServerDHParams;
          */
-        if( ( ret = mbedtls_mpi_copy( &ssl->handshake->dhm_ctx.P, &ssl->conf->dhm_P ) ) != 0 ||
-            ( ret = mbedtls_mpi_copy( &ssl->handshake->dhm_ctx.G, &ssl->conf->dhm_G ) ) != 0 )
+        if( ( ret = mbedtls_dhm_set_group( &ssl->handshake->dhm_ctx,
+                                           &ssl->conf->dhm_P,
+                                           &ssl->conf->dhm_G ) ) != 0 )
         {
-            MBEDTLS_SSL_DEBUG_RET( 1, "mbedtls_mpi_copy", ret );
+            MBEDTLS_SSL_DEBUG_RET( 1, "mbedtls_dhm_set_group", ret );
             return( ret );
         }
 
@@ -3093,40 +3102,12 @@
     defined(MBEDTLS_SSL_PROTO_TLS1_1)
         if( md_alg == MBEDTLS_MD_NONE )
         {
-            mbedtls_md5_context mbedtls_md5;
-            mbedtls_sha1_context mbedtls_sha1;
-
-            mbedtls_md5_init(  &mbedtls_md5  );
-            mbedtls_sha1_init( &mbedtls_sha1 );
-
-            /*
-             * digitally-signed struct {
-             *     opaque md5_hash[16];
-             *     opaque sha_hash[20];
-             * };
-             *
-             * md5_hash
-             *     MD5(ClientHello.random + ServerHello.random
-             *                            + ServerParams);
-             * sha_hash
-             *     SHA(ClientHello.random + ServerHello.random
-             *                            + ServerParams);
-             */
-
-            mbedtls_md5_starts( &mbedtls_md5 );
-            mbedtls_md5_update( &mbedtls_md5, ssl->handshake->randbytes,  64 );
-            mbedtls_md5_update( &mbedtls_md5, dig_signed, dig_signed_len );
-            mbedtls_md5_finish( &mbedtls_md5, hash );
-
-            mbedtls_sha1_starts( &mbedtls_sha1 );
-            mbedtls_sha1_update( &mbedtls_sha1, ssl->handshake->randbytes,  64 );
-            mbedtls_sha1_update( &mbedtls_sha1, dig_signed, dig_signed_len );
-            mbedtls_sha1_finish( &mbedtls_sha1, hash + 16 );
-
             hashlen = 36;
-
-            mbedtls_md5_free(  &mbedtls_md5  );
-            mbedtls_sha1_free( &mbedtls_sha1 );
+            ret = mbedtls_ssl_get_key_exchange_md_ssl_tls( ssl, hash,
+                                                           dig_signed,
+                                                           dig_signed_len );
+            if( ret != 0 )
+                return( ret );
         }
         else
 #endif /* MBEDTLS_SSL_PROTO_SSL3 || MBEDTLS_SSL_PROTO_TLS1 || \
@@ -3135,32 +3116,14 @@
     defined(MBEDTLS_SSL_PROTO_TLS1_2)
         if( md_alg != MBEDTLS_MD_NONE )
         {
-            mbedtls_md_context_t ctx;
-            const mbedtls_md_info_t *md_info = mbedtls_md_info_from_type( md_alg );
-
-            mbedtls_md_init( &ctx );
-
             /* Info from md_alg will be used instead */
             hashlen = 0;
-
-            /*
-             * digitally-signed struct {
-             *     opaque client_random[32];
-             *     opaque server_random[32];
-             *     ServerDHParams params;
-             * };
-             */
-            if( ( ret = mbedtls_md_setup( &ctx, md_info, 0 ) ) != 0 )
-            {
-                MBEDTLS_SSL_DEBUG_RET( 1, "mbedtls_md_setup", ret );
+            ret = mbedtls_ssl_get_key_exchange_md_tls1_2( ssl, hash,
+                                                          dig_signed,
+                                                          dig_signed_len,
+                                                          md_alg );
+            if( ret != 0 )
                 return( ret );
-            }
-
-            mbedtls_md_starts( &ctx );
-            mbedtls_md_update( &ctx, ssl->handshake->randbytes, 64 );
-            mbedtls_md_update( &ctx, dig_signed, dig_signed_len );
-            mbedtls_md_finish( &ctx, hash );
-            mbedtls_md_free( &ctx );
         }
         else
 #endif /* MBEDTLS_SSL_PROTO_TLS1 || MBEDTLS_SSL_PROTO_TLS1_1 || \
@@ -3433,7 +3396,7 @@
     /*
      * Receive client pre-shared key identity name
      */
-    if( *p + 2 > end )
+    if( end - *p < 2 )
     {
         MBEDTLS_SSL_DEBUG_MSG( 1, ( "bad client key exchange message" ) );
         return( MBEDTLS_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE );
@@ -3442,7 +3405,7 @@
     n = ( (*p)[0] << 8 ) | (*p)[1];
     *p += 2;
 
-    if( n < 1 || n > 65535 || *p + n > end )
+    if( n < 1 || n > 65535 || n > (size_t) ( end - *p ) )
     {
         MBEDTLS_SSL_DEBUG_MSG( 1, ( "bad client key exchange message" ) );
         return( MBEDTLS_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE );
diff --git a/library/ssl_tls.c b/library/ssl_tls.c
index 2690e46..617dedb 100644
--- a/library/ssl_tls.c
+++ b/library/ssl_tls.c
@@ -221,6 +221,7 @@
                      const unsigned char *random, size_t rlen,
                      unsigned char *dstbuf, size_t dlen )
 {
+    int ret = 0;
     size_t i;
     mbedtls_md5_context md5;
     mbedtls_sha1_context sha1;
@@ -243,25 +244,35 @@
     {
         memset( padding, (unsigned char) ('A' + i), 1 + i );
 
-        mbedtls_sha1_starts( &sha1 );
-        mbedtls_sha1_update( &sha1, padding, 1 + i );
-        mbedtls_sha1_update( &sha1, secret, slen );
-        mbedtls_sha1_update( &sha1, random, rlen );
-        mbedtls_sha1_finish( &sha1, sha1sum );
+        if( ( ret = mbedtls_sha1_starts_ret( &sha1 ) ) != 0 )
+            goto exit;
+        if( ( ret = mbedtls_sha1_update_ret( &sha1, padding, 1 + i ) ) != 0 )
+            goto exit;
+        if( ( ret = mbedtls_sha1_update_ret( &sha1, secret, slen ) ) != 0 )
+            goto exit;
+        if( ( ret = mbedtls_sha1_update_ret( &sha1, random, rlen ) ) != 0 )
+            goto exit;
+        if( ( ret = mbedtls_sha1_finish_ret( &sha1, sha1sum ) ) != 0 )
+            goto exit;
 
-        mbedtls_md5_starts( &md5 );
-        mbedtls_md5_update( &md5, secret, slen );
-        mbedtls_md5_update( &md5, sha1sum, 20 );
-        mbedtls_md5_finish( &md5, dstbuf + i * 16 );
+        if( ( ret = mbedtls_md5_starts_ret( &md5 ) ) != 0 )
+            goto exit;
+        if( ( ret = mbedtls_md5_update_ret( &md5, secret, slen ) ) != 0 )
+            goto exit;
+        if( ( ret = mbedtls_md5_update_ret( &md5, sha1sum, 20 ) ) != 0 )
+            goto exit;
+        if( ( ret = mbedtls_md5_finish_ret( &md5, dstbuf + i * 16 ) ) != 0 )
+            goto exit;
     }
 
+exit:
     mbedtls_md5_free(  &md5  );
     mbedtls_sha1_free( &sha1 );
 
     mbedtls_zeroize( padding, sizeof( padding ) );
     mbedtls_zeroize( sha1sum, sizeof( sha1sum ) );
 
-    return( 0 );
+    return( ret );
 }
 #endif /* MBEDTLS_SSL_PROTO_SSL3 */
 
@@ -978,25 +989,25 @@
     memset( pad_1, 0x36, 48 );
     memset( pad_2, 0x5C, 48 );
 
-    mbedtls_md5_update( &md5, ssl->session_negotiate->master, 48 );
-    mbedtls_md5_update( &md5, pad_1, 48 );
-    mbedtls_md5_finish( &md5, hash );
+    mbedtls_md5_update_ret( &md5, ssl->session_negotiate->master, 48 );
+    mbedtls_md5_update_ret( &md5, pad_1, 48 );
+    mbedtls_md5_finish_ret( &md5, hash );
 
-    mbedtls_md5_starts( &md5 );
-    mbedtls_md5_update( &md5, ssl->session_negotiate->master, 48 );
-    mbedtls_md5_update( &md5, pad_2, 48 );
-    mbedtls_md5_update( &md5, hash,  16 );
-    mbedtls_md5_finish( &md5, hash );
+    mbedtls_md5_starts_ret( &md5 );
+    mbedtls_md5_update_ret( &md5, ssl->session_negotiate->master, 48 );
+    mbedtls_md5_update_ret( &md5, pad_2, 48 );
+    mbedtls_md5_update_ret( &md5, hash,  16 );
+    mbedtls_md5_finish_ret( &md5, hash );
 
-    mbedtls_sha1_update( &sha1, ssl->session_negotiate->master, 48 );
-    mbedtls_sha1_update( &sha1, pad_1, 40 );
-    mbedtls_sha1_finish( &sha1, hash + 16 );
+    mbedtls_sha1_update_ret( &sha1, ssl->session_negotiate->master, 48 );
+    mbedtls_sha1_update_ret( &sha1, pad_1, 40 );
+    mbedtls_sha1_finish_ret( &sha1, hash + 16 );
 
-    mbedtls_sha1_starts( &sha1 );
-    mbedtls_sha1_update( &sha1, ssl->session_negotiate->master, 48 );
-    mbedtls_sha1_update( &sha1, pad_2, 40 );
-    mbedtls_sha1_update( &sha1, hash + 16, 20 );
-    mbedtls_sha1_finish( &sha1, hash + 16 );
+    mbedtls_sha1_starts_ret( &sha1 );
+    mbedtls_sha1_update_ret( &sha1, ssl->session_negotiate->master, 48 );
+    mbedtls_sha1_update_ret( &sha1, pad_2, 40 );
+    mbedtls_sha1_update_ret( &sha1, hash + 16, 20 );
+    mbedtls_sha1_finish_ret( &sha1, hash + 16 );
 
     MBEDTLS_SSL_DEBUG_BUF( 3, "calculated verify result", hash, 36 );
     MBEDTLS_SSL_DEBUG_MSG( 2, ( "<= calc verify" ) );
@@ -1022,8 +1033,8 @@
     mbedtls_md5_clone( &md5, &ssl->handshake->fin_md5 );
     mbedtls_sha1_clone( &sha1, &ssl->handshake->fin_sha1 );
 
-     mbedtls_md5_finish( &md5,  hash );
-    mbedtls_sha1_finish( &sha1, hash + 16 );
+     mbedtls_md5_finish_ret( &md5,  hash );
+    mbedtls_sha1_finish_ret( &sha1, hash + 16 );
 
     MBEDTLS_SSL_DEBUG_BUF( 3, "calculated verify result", hash, 36 );
     MBEDTLS_SSL_DEBUG_MSG( 2, ( "<= calc verify" ) );
@@ -1046,7 +1057,7 @@
     MBEDTLS_SSL_DEBUG_MSG( 2, ( "=> calc verify sha256" ) );
 
     mbedtls_sha256_clone( &sha256, &ssl->handshake->fin_sha256 );
-    mbedtls_sha256_finish( &sha256, hash );
+    mbedtls_sha256_finish_ret( &sha256, hash );
 
     MBEDTLS_SSL_DEBUG_BUF( 3, "calculated verify result", hash, 32 );
     MBEDTLS_SSL_DEBUG_MSG( 2, ( "<= calc verify" ) );
@@ -1067,7 +1078,7 @@
     MBEDTLS_SSL_DEBUG_MSG( 2, ( "=> calc verify sha384" ) );
 
     mbedtls_sha512_clone( &sha512, &ssl->handshake->fin_sha512 );
-    mbedtls_sha512_finish( &sha512, hash );
+    mbedtls_sha512_finish_ret( &sha512, hash );
 
     MBEDTLS_SSL_DEBUG_BUF( 3, "calculated verify result", hash, 48 );
     MBEDTLS_SSL_DEBUG_MSG( 2, ( "<= calc verify" ) );
@@ -1203,9 +1214,12 @@
 /*
  * SSLv3.0 MAC functions
  */
-static void ssl_mac( mbedtls_md_context_t *md_ctx, unsigned char *secret,
-                     unsigned char *buf, size_t len,
-                     unsigned char *ctr, int type )
+#define SSL_MAC_MAX_BYTES   20  /* MD-5 or SHA-1 */
+static void ssl_mac( mbedtls_md_context_t *md_ctx,
+                     const unsigned char *secret,
+                     const unsigned char *buf, size_t len,
+                     const unsigned char *ctr, int type,
+                     unsigned char out[SSL_MAC_MAX_BYTES] )
 {
     unsigned char header[11];
     unsigned char padding[48];
@@ -1230,14 +1244,14 @@
     mbedtls_md_update( md_ctx, padding, padlen  );
     mbedtls_md_update( md_ctx, header,  11      );
     mbedtls_md_update( md_ctx, buf,     len     );
-    mbedtls_md_finish( md_ctx, buf +    len     );
+    mbedtls_md_finish( md_ctx, out              );
 
     memset( padding, 0x5C, padlen );
     mbedtls_md_starts( md_ctx );
     mbedtls_md_update( md_ctx, secret,    md_size );
     mbedtls_md_update( md_ctx, padding,   padlen  );
-    mbedtls_md_update( md_ctx, buf + len, md_size );
-    mbedtls_md_finish( md_ctx, buf + len          );
+    mbedtls_md_update( md_ctx, out,       md_size );
+    mbedtls_md_finish( md_ctx, out                );
 }
 #endif /* MBEDTLS_SSL_PROTO_SSL3 */
 
@@ -1268,6 +1282,14 @@
     MBEDTLS_SSL_DEBUG_BUF( 4, "before encrypt: output payload",
                       ssl->out_msg, ssl->out_msglen );
 
+    if( ssl->out_msglen > MBEDTLS_SSL_MAX_CONTENT_LEN )
+    {
+        MBEDTLS_SSL_DEBUG_MSG( 1, ( "Record content %u too large, maximum %d",
+                                    (unsigned) ssl->out_msglen,
+                                    MBEDTLS_SSL_MAX_CONTENT_LEN ) );
+        return( MBEDTLS_ERR_SSL_BAD_INPUT_DATA );
+    }
+
     /*
      * Add MAC before if needed
      */
@@ -1282,10 +1304,15 @@
 #if defined(MBEDTLS_SSL_PROTO_SSL3)
         if( ssl->minor_ver == MBEDTLS_SSL_MINOR_VERSION_0 )
         {
+            unsigned char mac[SSL_MAC_MAX_BYTES];
+
             ssl_mac( &ssl->transform_out->md_ctx_enc,
                       ssl->transform_out->mac_enc,
                       ssl->out_msg, ssl->out_msglen,
-                      ssl->out_ctr, ssl->out_msgtype );
+                      ssl->out_ctr, ssl->out_msgtype,
+                      mac );
+
+            memcpy( ssl->out_msg + ssl->out_msglen, mac, ssl->transform_out->maclen );
         }
         else
 #endif
@@ -1293,14 +1320,17 @@
         defined(MBEDTLS_SSL_PROTO_TLS1_2)
         if( ssl->minor_ver >= MBEDTLS_SSL_MINOR_VERSION_1 )
         {
+            unsigned char mac[MBEDTLS_SSL_MAC_ADD];
+
             mbedtls_md_hmac_update( &ssl->transform_out->md_ctx_enc, ssl->out_ctr, 8 );
             mbedtls_md_hmac_update( &ssl->transform_out->md_ctx_enc, ssl->out_hdr, 3 );
             mbedtls_md_hmac_update( &ssl->transform_out->md_ctx_enc, ssl->out_len, 2 );
             mbedtls_md_hmac_update( &ssl->transform_out->md_ctx_enc,
                              ssl->out_msg, ssl->out_msglen );
-            mbedtls_md_hmac_finish( &ssl->transform_out->md_ctx_enc,
-                             ssl->out_msg + ssl->out_msglen );
+            mbedtls_md_hmac_finish( &ssl->transform_out->md_ctx_enc, mac );
             mbedtls_md_hmac_reset( &ssl->transform_out->md_ctx_enc );
+
+            memcpy( ssl->out_msg + ssl->out_msglen, mac, ssl->transform_out->maclen );
         }
         else
 #endif
@@ -1562,8 +1592,6 @@
     return( 0 );
 }
 
-#define SSL_MAX_MAC_SIZE   48
-
 static int ssl_decrypt_buf( mbedtls_ssl_context *ssl )
 {
     size_t i;
@@ -1731,7 +1759,7 @@
 #if defined(MBEDTLS_SSL_ENCRYPT_THEN_MAC)
         if( ssl->session_in->encrypt_then_mac == MBEDTLS_SSL_ETM_ENABLED )
         {
-            unsigned char computed_mac[SSL_MAX_MAC_SIZE];
+            unsigned char mac_expect[MBEDTLS_SSL_MAC_ADD];
             unsigned char pseudo_hdr[13];
 
             MBEDTLS_SSL_DEBUG_MSG( 3, ( "using encrypt then mac" ) );
@@ -1749,16 +1777,16 @@
             mbedtls_md_hmac_update( &ssl->transform_in->md_ctx_dec, pseudo_hdr, 13 );
             mbedtls_md_hmac_update( &ssl->transform_in->md_ctx_dec,
                              ssl->in_iv, ssl->in_msglen );
-            mbedtls_md_hmac_finish( &ssl->transform_in->md_ctx_dec, computed_mac );
+            mbedtls_md_hmac_finish( &ssl->transform_in->md_ctx_dec, mac_expect );
             mbedtls_md_hmac_reset( &ssl->transform_in->md_ctx_dec );
 
             MBEDTLS_SSL_DEBUG_BUF( 4, "message  mac", ssl->in_iv + ssl->in_msglen,
                                               ssl->transform_in->maclen );
-            MBEDTLS_SSL_DEBUG_BUF( 4, "computed mac", computed_mac,
+            MBEDTLS_SSL_DEBUG_BUF( 4, "expected mac", mac_expect,
                                               ssl->transform_in->maclen );
 
-            if( mbedtls_ssl_safer_memcmp( ssl->in_iv + ssl->in_msglen, computed_mac,
-                              ssl->transform_in->maclen ) != 0 )
+            if( mbedtls_ssl_safer_memcmp( ssl->in_iv + ssl->in_msglen, mac_expect,
+                                          ssl->transform_in->maclen ) != 0 )
             {
                 MBEDTLS_SSL_DEBUG_MSG( 1, ( "message mac does not match" ) );
 
@@ -1918,22 +1946,21 @@
 #if defined(SSL_SOME_MODES_USE_MAC)
     if( auth_done == 0 )
     {
-        unsigned char tmp[SSL_MAX_MAC_SIZE];
+        unsigned char mac_expect[MBEDTLS_SSL_MAC_ADD];
 
         ssl->in_msglen -= ssl->transform_in->maclen;
 
         ssl->in_len[0] = (unsigned char)( ssl->in_msglen >> 8 );
         ssl->in_len[1] = (unsigned char)( ssl->in_msglen      );
 
-        memcpy( tmp, ssl->in_msg + ssl->in_msglen, ssl->transform_in->maclen );
-
 #if defined(MBEDTLS_SSL_PROTO_SSL3)
         if( ssl->minor_ver == MBEDTLS_SSL_MINOR_VERSION_0 )
         {
             ssl_mac( &ssl->transform_in->md_ctx_dec,
                       ssl->transform_in->mac_dec,
                       ssl->in_msg, ssl->in_msglen,
-                      ssl->in_ctr, ssl->in_msgtype );
+                      ssl->in_ctr, ssl->in_msgtype,
+                      mac_expect );
         }
         else
 #endif /* MBEDTLS_SSL_PROTO_SSL3 */
@@ -1965,8 +1992,7 @@
             mbedtls_md_hmac_update( &ssl->transform_in->md_ctx_dec, ssl->in_len, 2 );
             mbedtls_md_hmac_update( &ssl->transform_in->md_ctx_dec, ssl->in_msg,
                              ssl->in_msglen );
-            mbedtls_md_hmac_finish( &ssl->transform_in->md_ctx_dec,
-                             ssl->in_msg + ssl->in_msglen );
+            mbedtls_md_hmac_finish( &ssl->transform_in->md_ctx_dec, mac_expect );
             /* Call mbedtls_md_process at least once due to cache attacks */
             for( j = 0; j < extra_run + 1; j++ )
                 mbedtls_md_process( &ssl->transform_in->md_ctx_dec, ssl->in_msg );
@@ -1981,12 +2007,12 @@
             return( MBEDTLS_ERR_SSL_INTERNAL_ERROR );
         }
 
-        MBEDTLS_SSL_DEBUG_BUF( 4, "message  mac", tmp, ssl->transform_in->maclen );
-        MBEDTLS_SSL_DEBUG_BUF( 4, "computed mac", ssl->in_msg + ssl->in_msglen,
-                       ssl->transform_in->maclen );
+        MBEDTLS_SSL_DEBUG_BUF( 4, "expected mac", mac_expect, ssl->transform_in->maclen );
+        MBEDTLS_SSL_DEBUG_BUF( 4, "message  mac", ssl->in_msg + ssl->in_msglen,
+                               ssl->transform_in->maclen );
 
-        if( mbedtls_ssl_safer_memcmp( tmp, ssl->in_msg + ssl->in_msglen,
-                         ssl->transform_in->maclen ) != 0 )
+        if( mbedtls_ssl_safer_memcmp( ssl->in_msg + ssl->in_msglen, mac_expect,
+                                      ssl->transform_in->maclen ) != 0 )
         {
 #if defined(MBEDTLS_SSL_DEBUG_ALL)
             MBEDTLS_SSL_DEBUG_MSG( 1, ( "message mac does not match" ) );
@@ -2735,6 +2761,15 @@
         if( ssl->conf->transport == MBEDTLS_SSL_TRANSPORT_DATAGRAM )
         {
             /* Make room for the additional DTLS fields */
+            if( MBEDTLS_SSL_MAX_CONTENT_LEN - ssl->out_msglen < 8 )
+            {
+                MBEDTLS_SSL_DEBUG_MSG( 1, ( "DTLS handshake message too large: "
+                              "size %u, maximum %u",
+                               (unsigned) ( ssl->in_hslen - 4 ),
+                               (unsigned) ( MBEDTLS_SSL_MAX_CONTENT_LEN - 12 ) ) );
+                return( MBEDTLS_ERR_SSL_BAD_INPUT_DATA );
+            }
+
             memmove( ssl->out_msg + 12, ssl->out_msg + 4, len - 4 );
             ssl->out_msglen += 8;
             len += 8;
@@ -4843,15 +4878,15 @@
 {
 #if defined(MBEDTLS_SSL_PROTO_SSL3) || defined(MBEDTLS_SSL_PROTO_TLS1) || \
     defined(MBEDTLS_SSL_PROTO_TLS1_1)
-     mbedtls_md5_starts( &ssl->handshake->fin_md5  );
-    mbedtls_sha1_starts( &ssl->handshake->fin_sha1 );
+     mbedtls_md5_starts_ret( &ssl->handshake->fin_md5  );
+    mbedtls_sha1_starts_ret( &ssl->handshake->fin_sha1 );
 #endif
 #if defined(MBEDTLS_SSL_PROTO_TLS1_2)
 #if defined(MBEDTLS_SHA256_C)
-    mbedtls_sha256_starts( &ssl->handshake->fin_sha256, 0 );
+    mbedtls_sha256_starts_ret( &ssl->handshake->fin_sha256, 0 );
 #endif
 #if defined(MBEDTLS_SHA512_C)
-    mbedtls_sha512_starts( &ssl->handshake->fin_sha512, 1 );
+    mbedtls_sha512_starts_ret( &ssl->handshake->fin_sha512, 1 );
 #endif
 #endif /* MBEDTLS_SSL_PROTO_TLS1_2 */
 }
@@ -4861,15 +4896,15 @@
 {
 #if defined(MBEDTLS_SSL_PROTO_SSL3) || defined(MBEDTLS_SSL_PROTO_TLS1) || \
     defined(MBEDTLS_SSL_PROTO_TLS1_1)
-     mbedtls_md5_update( &ssl->handshake->fin_md5 , buf, len );
-    mbedtls_sha1_update( &ssl->handshake->fin_sha1, buf, len );
+     mbedtls_md5_update_ret( &ssl->handshake->fin_md5 , buf, len );
+    mbedtls_sha1_update_ret( &ssl->handshake->fin_sha1, buf, len );
 #endif
 #if defined(MBEDTLS_SSL_PROTO_TLS1_2)
 #if defined(MBEDTLS_SHA256_C)
-    mbedtls_sha256_update( &ssl->handshake->fin_sha256, buf, len );
+    mbedtls_sha256_update_ret( &ssl->handshake->fin_sha256, buf, len );
 #endif
 #if defined(MBEDTLS_SHA512_C)
-    mbedtls_sha512_update( &ssl->handshake->fin_sha512, buf, len );
+    mbedtls_sha512_update_ret( &ssl->handshake->fin_sha512, buf, len );
 #endif
 #endif /* MBEDTLS_SSL_PROTO_TLS1_2 */
 }
@@ -4879,8 +4914,8 @@
 static void ssl_update_checksum_md5sha1( mbedtls_ssl_context *ssl,
                                          const unsigned char *buf, size_t len )
 {
-     mbedtls_md5_update( &ssl->handshake->fin_md5 , buf, len );
-    mbedtls_sha1_update( &ssl->handshake->fin_sha1, buf, len );
+     mbedtls_md5_update_ret( &ssl->handshake->fin_md5 , buf, len );
+    mbedtls_sha1_update_ret( &ssl->handshake->fin_sha1, buf, len );
 }
 #endif
 
@@ -4889,7 +4924,7 @@
 static void ssl_update_checksum_sha256( mbedtls_ssl_context *ssl,
                                         const unsigned char *buf, size_t len )
 {
-    mbedtls_sha256_update( &ssl->handshake->fin_sha256, buf, len );
+    mbedtls_sha256_update_ret( &ssl->handshake->fin_sha256, buf, len );
 }
 #endif
 
@@ -4897,7 +4932,7 @@
 static void ssl_update_checksum_sha384( mbedtls_ssl_context *ssl,
                                         const unsigned char *buf, size_t len )
 {
-    mbedtls_sha512_update( &ssl->handshake->fin_sha512, buf, len );
+    mbedtls_sha512_update_ret( &ssl->handshake->fin_sha512, buf, len );
 }
 #endif
 #endif /* MBEDTLS_SSL_PROTO_TLS1_2 */
@@ -4950,29 +4985,29 @@
 
     memset( padbuf, 0x36, 48 );
 
-    mbedtls_md5_update( &md5, (const unsigned char *) sender, 4 );
-    mbedtls_md5_update( &md5, session->master, 48 );
-    mbedtls_md5_update( &md5, padbuf, 48 );
-    mbedtls_md5_finish( &md5, md5sum );
+    mbedtls_md5_update_ret( &md5, (const unsigned char *) sender, 4 );
+    mbedtls_md5_update_ret( &md5, session->master, 48 );
+    mbedtls_md5_update_ret( &md5, padbuf, 48 );
+    mbedtls_md5_finish_ret( &md5, md5sum );
 
-    mbedtls_sha1_update( &sha1, (const unsigned char *) sender, 4 );
-    mbedtls_sha1_update( &sha1, session->master, 48 );
-    mbedtls_sha1_update( &sha1, padbuf, 40 );
-    mbedtls_sha1_finish( &sha1, sha1sum );
+    mbedtls_sha1_update_ret( &sha1, (const unsigned char *) sender, 4 );
+    mbedtls_sha1_update_ret( &sha1, session->master, 48 );
+    mbedtls_sha1_update_ret( &sha1, padbuf, 40 );
+    mbedtls_sha1_finish_ret( &sha1, sha1sum );
 
     memset( padbuf, 0x5C, 48 );
 
-    mbedtls_md5_starts( &md5 );
-    mbedtls_md5_update( &md5, session->master, 48 );
-    mbedtls_md5_update( &md5, padbuf, 48 );
-    mbedtls_md5_update( &md5, md5sum, 16 );
-    mbedtls_md5_finish( &md5, buf );
+    mbedtls_md5_starts_ret( &md5 );
+    mbedtls_md5_update_ret( &md5, session->master, 48 );
+    mbedtls_md5_update_ret( &md5, padbuf, 48 );
+    mbedtls_md5_update_ret( &md5, md5sum, 16 );
+    mbedtls_md5_finish_ret( &md5, buf );
 
-    mbedtls_sha1_starts( &sha1 );
-    mbedtls_sha1_update( &sha1, session->master, 48 );
-    mbedtls_sha1_update( &sha1, padbuf , 40 );
-    mbedtls_sha1_update( &sha1, sha1sum, 20 );
-    mbedtls_sha1_finish( &sha1, buf + 16 );
+    mbedtls_sha1_starts_ret( &sha1 );
+    mbedtls_sha1_update_ret( &sha1, session->master, 48 );
+    mbedtls_sha1_update_ret( &sha1, padbuf , 40 );
+    mbedtls_sha1_update_ret( &sha1, sha1sum, 20 );
+    mbedtls_sha1_finish_ret( &sha1, buf + 16 );
 
     MBEDTLS_SSL_DEBUG_BUF( 3, "calc finished result", buf, 36 );
 
@@ -5029,8 +5064,8 @@
              ? "client finished"
              : "server finished";
 
-    mbedtls_md5_finish(  &md5, padbuf );
-    mbedtls_sha1_finish( &sha1, padbuf + 16 );
+    mbedtls_md5_finish_ret(  &md5, padbuf );
+    mbedtls_sha1_finish_ret( &sha1, padbuf + 16 );
 
     ssl->handshake->tls_prf( session->master, 48, sender,
                              padbuf, 36, buf, len );
@@ -5081,7 +5116,7 @@
              ? "client finished"
              : "server finished";
 
-    mbedtls_sha256_finish( &sha256, padbuf );
+    mbedtls_sha256_finish_ret( &sha256, padbuf );
 
     ssl->handshake->tls_prf( session->master, 48, sender,
                              padbuf, 32, buf, len );
@@ -5130,7 +5165,7 @@
              ? "client finished"
              : "server finished";
 
-    mbedtls_sha512_finish( &sha512, padbuf );
+    mbedtls_sha512_finish_ret( &sha512, padbuf );
 
     ssl->handshake->tls_prf( session->master, 48, sender,
                              padbuf, 48, buf, len );
@@ -5444,17 +5479,17 @@
     defined(MBEDTLS_SSL_PROTO_TLS1_1)
      mbedtls_md5_init(   &handshake->fin_md5  );
     mbedtls_sha1_init(   &handshake->fin_sha1 );
-     mbedtls_md5_starts( &handshake->fin_md5  );
-    mbedtls_sha1_starts( &handshake->fin_sha1 );
+     mbedtls_md5_starts_ret( &handshake->fin_md5  );
+    mbedtls_sha1_starts_ret( &handshake->fin_sha1 );
 #endif
 #if defined(MBEDTLS_SSL_PROTO_TLS1_2)
 #if defined(MBEDTLS_SHA256_C)
     mbedtls_sha256_init(   &handshake->fin_sha256    );
-    mbedtls_sha256_starts( &handshake->fin_sha256, 0 );
+    mbedtls_sha256_starts_ret( &handshake->fin_sha256, 0 );
 #endif
 #if defined(MBEDTLS_SHA512_C)
     mbedtls_sha512_init(   &handshake->fin_sha512    );
-    mbedtls_sha512_starts( &handshake->fin_sha512, 1 );
+    mbedtls_sha512_starts_ret( &handshake->fin_sha512, 1 );
 #endif
 #endif /* MBEDTLS_SSL_PROTO_TLS1_2 */
 
@@ -6056,12 +6091,19 @@
         return( MBEDTLS_ERR_SSL_BAD_INPUT_DATA );
     }
 
-    if( conf->psk != NULL || conf->psk_identity != NULL )
+    if( conf->psk != NULL )
     {
+        mbedtls_zeroize( conf->psk, conf->psk_len );
+
         mbedtls_free( conf->psk );
-        mbedtls_free( conf->psk_identity );
         conf->psk = NULL;
+        conf->psk_len = 0;
+    }
+    if( conf->psk_identity != NULL )
+    {
+        mbedtls_free( conf->psk_identity );
         conf->psk_identity = NULL;
+        conf->psk_identity_len = 0;
     }
 
     if( ( conf->psk = mbedtls_calloc( 1, psk_len ) ) == NULL ||
@@ -6093,7 +6135,11 @@
         return( MBEDTLS_ERR_SSL_BAD_INPUT_DATA );
 
     if( ssl->handshake->psk != NULL )
+    {
+        mbedtls_zeroize( ssl->handshake->psk, ssl->handshake->psk_len );
         mbedtls_free( ssl->handshake->psk );
+        ssl->handshake->psk_len = 0;
+    }
 
     if( ( ssl->handshake->psk = mbedtls_calloc( 1, psk_len ) ) == NULL )
         return( MBEDTLS_ERR_SSL_ALLOC_FAILED );
@@ -6115,6 +6161,8 @@
 #endif /* MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED */
 
 #if defined(MBEDTLS_DHM_C) && defined(MBEDTLS_SSL_SRV_C)
+
+#if !defined(MBEDTLS_DEPRECATED_REMOVED)
 int mbedtls_ssl_conf_dh_param( mbedtls_ssl_config *conf, const char *dhm_P, const char *dhm_G )
 {
     int ret;
@@ -6129,6 +6177,24 @@
 
     return( 0 );
 }
+#endif /* MBEDTLS_DEPRECATED_REMOVED */
+
+int mbedtls_ssl_conf_dh_param_bin( mbedtls_ssl_config *conf,
+                                   const unsigned char *dhm_P, size_t P_len,
+                                   const unsigned char *dhm_G, size_t G_len )
+{
+    int ret;
+
+    if( ( ret = mbedtls_mpi_read_binary( &conf->dhm_P, dhm_P, P_len ) ) != 0 ||
+        ( ret = mbedtls_mpi_read_binary( &conf->dhm_G, dhm_G, G_len ) ) != 0 )
+    {
+        mbedtls_mpi_free( &conf->dhm_P );
+        mbedtls_mpi_free( &conf->dhm_G );
+        return( ret );
+    }
+
+    return( 0 );
+}
 
 int mbedtls_ssl_conf_dh_param_ctx( mbedtls_ssl_config *conf, mbedtls_dhm_context *dhm_ctx )
 {
@@ -7556,9 +7622,14 @@
 #if defined(MBEDTLS_DHM_C) && defined(MBEDTLS_SSL_SRV_C)
             if( endpoint == MBEDTLS_SSL_IS_SERVER )
             {
-                if( ( ret = mbedtls_ssl_conf_dh_param( conf,
-                                MBEDTLS_DHM_RFC5114_MODP_2048_P,
-                                MBEDTLS_DHM_RFC5114_MODP_2048_G ) ) != 0 )
+                const unsigned char dhm_p[] =
+                    MBEDTLS_DHM_RFC3526_MODP_2048_P_BIN;
+                const unsigned char dhm_g[] =
+                    MBEDTLS_DHM_RFC3526_MODP_2048_G_BIN;
+
+                if ( ( ret = mbedtls_ssl_conf_dh_param_bin( conf,
+                                               dhm_p, sizeof( dhm_p ),
+                                               dhm_g, sizeof( dhm_g ) ) ) != 0 )
                 {
                     return( ret );
                 }
@@ -8058,4 +8129,148 @@
 #endif /* MBEDTLS_SSL_PROTO_TLS1_2 */
 }
 
+#if defined(MBEDTLS_SSL_PROTO_SSL3) || defined(MBEDTLS_SSL_PROTO_TLS1) || \
+    defined(MBEDTLS_SSL_PROTO_TLS1_1)
+int mbedtls_ssl_get_key_exchange_md_ssl_tls( mbedtls_ssl_context *ssl,
+                                        unsigned char *output,
+                                        unsigned char *data, size_t data_len )
+{
+    int ret = 0;
+    mbedtls_md5_context mbedtls_md5;
+    mbedtls_sha1_context mbedtls_sha1;
+
+    mbedtls_md5_init( &mbedtls_md5 );
+    mbedtls_sha1_init( &mbedtls_sha1 );
+
+    /*
+     * digitally-signed struct {
+     *     opaque md5_hash[16];
+     *     opaque sha_hash[20];
+     * };
+     *
+     * md5_hash
+     *     MD5(ClientHello.random + ServerHello.random
+     *                            + ServerParams);
+     * sha_hash
+     *     SHA(ClientHello.random + ServerHello.random
+     *                            + ServerParams);
+     */
+    if( ( ret = mbedtls_md5_starts_ret( &mbedtls_md5 ) ) != 0 )
+    {
+        MBEDTLS_SSL_DEBUG_RET( 1, "mbedtls_md5_starts_ret", ret );
+        goto exit;
+    }
+    if( ( ret = mbedtls_md5_update_ret( &mbedtls_md5,
+                                        ssl->handshake->randbytes, 64 ) ) != 0 )
+    {
+        MBEDTLS_SSL_DEBUG_RET( 1, "mbedtls_md5_update_ret", ret );
+        goto exit;
+    }
+    if( ( ret = mbedtls_md5_update_ret( &mbedtls_md5, data, data_len ) ) != 0 )
+    {
+        MBEDTLS_SSL_DEBUG_RET( 1, "mbedtls_md5_update_ret", ret );
+        goto exit;
+    }
+    if( ( ret = mbedtls_md5_finish_ret( &mbedtls_md5, output ) ) != 0 )
+    {
+        MBEDTLS_SSL_DEBUG_RET( 1, "mbedtls_md5_finish_ret", ret );
+        goto exit;
+    }
+
+    if( ( ret = mbedtls_sha1_starts_ret( &mbedtls_sha1 ) ) != 0 )
+    {
+        MBEDTLS_SSL_DEBUG_RET( 1, "mbedtls_sha1_starts_ret", ret );
+        goto exit;
+    }
+    if( ( ret = mbedtls_sha1_update_ret( &mbedtls_sha1,
+                                         ssl->handshake->randbytes, 64 ) ) != 0 )
+    {
+        MBEDTLS_SSL_DEBUG_RET( 1, "mbedtls_sha1_update_ret", ret );
+        goto exit;
+    }
+    if( ( ret = mbedtls_sha1_update_ret( &mbedtls_sha1, data,
+                                         data_len ) ) != 0 )
+    {
+        MBEDTLS_SSL_DEBUG_RET( 1, "mbedtls_sha1_update_ret", ret );
+        goto exit;
+    }
+    if( ( ret = mbedtls_sha1_finish_ret( &mbedtls_sha1,
+                                         output + 16 ) ) != 0 )
+    {
+        MBEDTLS_SSL_DEBUG_RET( 1, "mbedtls_sha1_finish_ret", ret );
+        goto exit;
+    }
+
+exit:
+    mbedtls_md5_free( &mbedtls_md5 );
+    mbedtls_sha1_free( &mbedtls_sha1 );
+
+    if( ret != 0 )
+        mbedtls_ssl_send_alert_message( ssl, MBEDTLS_SSL_ALERT_LEVEL_FATAL,
+                                        MBEDTLS_SSL_ALERT_MSG_INTERNAL_ERROR );
+
+    return( ret );
+
+}
+#endif /* MBEDTLS_SSL_PROTO_SSL3 || MBEDTLS_SSL_PROTO_TLS1 || \
+          MBEDTLS_SSL_PROTO_TLS1_1 */
+
+#if defined(MBEDTLS_SSL_PROTO_TLS1) || defined(MBEDTLS_SSL_PROTO_TLS1_1) || \
+    defined(MBEDTLS_SSL_PROTO_TLS1_2)
+int mbedtls_ssl_get_key_exchange_md_tls1_2( mbedtls_ssl_context *ssl,
+                                       unsigned char *output,
+                                       unsigned char *data, size_t data_len,
+                                       mbedtls_md_type_t md_alg )
+{
+    int ret = 0;
+    mbedtls_md_context_t ctx;
+    const mbedtls_md_info_t *md_info = mbedtls_md_info_from_type( md_alg );
+
+    mbedtls_md_init( &ctx );
+
+    /*
+     * digitally-signed struct {
+     *     opaque client_random[32];
+     *     opaque server_random[32];
+     *     ServerDHParams params;
+     * };
+     */
+    if( ( ret = mbedtls_md_setup( &ctx, md_info, 0 ) ) != 0 )
+    {
+        MBEDTLS_SSL_DEBUG_RET( 1, "mbedtls_md_setup", ret );
+        goto exit;
+    }
+    if( ( ret = mbedtls_md_starts( &ctx ) ) != 0 )
+    {
+        MBEDTLS_SSL_DEBUG_RET( 1, "mbedtls_md_starts", ret );
+        goto exit;
+    }
+    if( ( ret = mbedtls_md_update( &ctx, ssl->handshake->randbytes, 64 ) ) != 0 )
+    {
+        MBEDTLS_SSL_DEBUG_RET( 1, "mbedtls_md_update", ret );
+        goto exit;
+    }
+    if( ( ret = mbedtls_md_update( &ctx, data, data_len ) ) != 0 )
+    {
+        MBEDTLS_SSL_DEBUG_RET( 1, "mbedtls_md_update", ret );
+        goto exit;
+    }
+    if( ( ret = mbedtls_md_finish( &ctx, output ) ) != 0 )
+    {
+        MBEDTLS_SSL_DEBUG_RET( 1, "mbedtls_md_finish", ret );
+        goto exit;
+    }
+
+exit:
+    mbedtls_md_free( &ctx );
+
+    if( ret != 0 )
+        mbedtls_ssl_send_alert_message( ssl, MBEDTLS_SSL_ALERT_LEVEL_FATAL,
+                                        MBEDTLS_SSL_ALERT_MSG_INTERNAL_ERROR );
+
+    return( ret );
+}
+#endif /* MBEDTLS_SSL_PROTO_TLS1 || MBEDTLS_SSL_PROTO_TLS1_1 || \
+          MBEDTLS_SSL_PROTO_TLS1_2 */
+
 #endif /* MBEDTLS_SSL_TLS_C */
diff --git a/library/timing.c b/library/timing.c
index 6df137d..35d6d89 100644
--- a/library/timing.c
+++ b/library/timing.c
@@ -278,6 +278,14 @@
 {
     DWORD ThreadId;
 
+    if( seconds == 0 )
+    {
+        /* No need to create a thread for this simple case.
+         * Also, this shorcut is more reliable at least on MinGW32 */
+        mbedtls_timing_alarmed = 1;
+        return;
+    }
+
     mbedtls_timing_alarmed = 0;
     alarmMs = seconds * 1000;
     CloseHandle( CreateThread( NULL, 0, TimerProc, NULL, 0, &ThreadId ) );
diff --git a/library/version_features.c b/library/version_features.c
index 172cf12..72afec2 100644
--- a/library/version_features.c
+++ b/library/version_features.c
@@ -105,6 +105,12 @@
 #if defined(MBEDTLS_DES_ALT)
     "MBEDTLS_DES_ALT",
 #endif /* MBEDTLS_DES_ALT */
+#if defined(MBEDTLS_DHM_ALT)
+    "MBEDTLS_DHM_ALT",
+#endif /* MBEDTLS_DHM_ALT */
+#if defined(MBEDTLS_ECJPAKE_ALT)
+    "MBEDTLS_ECJPAKE_ALT",
+#endif /* MBEDTLS_ECJPAKE_ALT */
 #if defined(MBEDTLS_GCM_ALT)
     "MBEDTLS_GCM_ALT",
 #endif /* MBEDTLS_GCM_ALT */
diff --git a/library/x509write_crt.c b/library/x509write_crt.c
index 0af23d7..41dfe87 100644
--- a/library/x509write_crt.c
+++ b/library/x509write_crt.c
@@ -177,8 +177,11 @@
     memset( buf, 0, sizeof(buf) );
     MBEDTLS_ASN1_CHK_ADD( len, mbedtls_pk_write_pubkey( &c, buf, ctx->subject_key ) );
 
-    mbedtls_sha1( buf + sizeof(buf) - len, len, buf + sizeof(buf) - 20 );
-    c = buf + sizeof(buf) - 20;
+    ret = mbedtls_sha1_ret( buf + sizeof( buf ) - len, len,
+                            buf + sizeof( buf ) - 20 );
+    if( ret != 0 )
+        return( ret );
+    c = buf + sizeof( buf ) - 20;
     len = 20;
 
     MBEDTLS_ASN1_CHK_ADD( len, mbedtls_asn1_write_len( &c, buf, len ) );
@@ -199,7 +202,10 @@
     memset( buf, 0, sizeof(buf) );
     MBEDTLS_ASN1_CHK_ADD( len, mbedtls_pk_write_pubkey( &c, buf, ctx->issuer_key ) );
 
-    mbedtls_sha1( buf + sizeof( buf ) - len, len, buf + sizeof( buf ) - 20 );
+    ret = mbedtls_sha1_ret( buf + sizeof( buf ) - len, len,
+                            buf + sizeof( buf ) - 20 );
+    if( ret != 0 )
+        return( ret );
     c = buf + sizeof( buf ) - 20;
     len = 20;
 
@@ -414,7 +420,11 @@
     /*
      * Make signature
      */
-    mbedtls_md( mbedtls_md_info_from_type( ctx->md_alg ), c, len, hash );
+    if( ( ret = mbedtls_md( mbedtls_md_info_from_type( ctx->md_alg ), c,
+                            len, hash ) ) != 0 )
+    {
+        return( ret );
+    }
 
     if( ( ret = mbedtls_pk_sign( ctx->issuer_key, ctx->md_alg, hash, 0, sig, &sig_len,
                          f_rng, p_rng ) ) != 0 )
diff --git a/programs/hash/hello.c b/programs/hash/hello.c
index df420f2..2e8c224 100644
--- a/programs/hash/hello.c
+++ b/programs/hash/hello.c
@@ -28,8 +28,11 @@
 #if defined(MBEDTLS_PLATFORM_C)
 #include "mbedtls/platform.h"
 #else
+#include <stdlib.h>
 #include <stdio.h>
-#define mbedtls_printf     printf
+#define mbedtls_printf       printf
+#define MBEDTLS_EXIT_SUCCESS EXIT_SUCCESS
+#define MBEDTLS_EXIT_FAILURE EXIT_FAILURE
 #endif
 
 #if defined(MBEDTLS_MD5_C)
@@ -45,13 +48,14 @@
 #else
 int main( void )
 {
-    int i;
+    int i, ret;
     unsigned char digest[16];
     char str[] = "Hello, world!";
 
     mbedtls_printf( "\n  MD5('%s') = ", str );
 
-    mbedtls_md5( (unsigned char *) str, 13, digest );
+    if( ( ret = mbedtls_md5_ret( (unsigned char *) str, 13, digest ) ) != 0 )
+        return( MBEDTLS_EXIT_FAILURE );
 
     for( i = 0; i < 16; i++ )
         mbedtls_printf( "%02x", digest[i] );
@@ -63,6 +67,6 @@
     fflush( stdout ); getchar();
 #endif
 
-    return( 0 );
+    return( MBEDTLS_EXIT_SUCCESS );
 }
 #endif /* MBEDTLS_MD5_C */
diff --git a/programs/pkey/dh_client.c b/programs/pkey/dh_client.c
index 875d0b0..0978408 100644
--- a/programs/pkey/dh_client.c
+++ b/programs/pkey/dh_client.c
@@ -212,7 +212,11 @@
         goto exit;
     }
 
-    mbedtls_sha1( buf, (int)( p - 2 - buf ), hash );
+    if( ( ret = mbedtls_sha1_ret( buf, (int)( p - 2 - buf ), hash ) ) != 0 )
+    {
+        mbedtls_printf( " failed\n  ! mbedtls_sha1_ret returned %d\n\n", ret );
+        goto exit;
+    }
 
     if( ( ret = mbedtls_rsa_pkcs1_verify( &rsa, NULL, NULL, MBEDTLS_RSA_PUBLIC,
                                   MBEDTLS_MD_SHA256, 0, hash, p ) ) != 0 )
diff --git a/programs/pkey/dh_server.c b/programs/pkey/dh_server.c
index a8ee8fd..4304231 100644
--- a/programs/pkey/dh_server.c
+++ b/programs/pkey/dh_server.c
@@ -217,7 +217,11 @@
     /*
      * 5. Sign the parameters and send them
      */
-    mbedtls_sha1( buf, n, hash );
+    if( ( ret = mbedtls_sha1_ret( buf, n, hash ) ) != 0 )
+    {
+        mbedtls_printf( " failed\n  ! mbedtls_sha1_ret returned %d\n\n", ret );
+        goto exit;
+    }
 
     buf[n    ] = (unsigned char)( rsa.len >> 8 );
     buf[n + 1] = (unsigned char)( rsa.len      );
@@ -248,6 +252,7 @@
 
     memset( buf, 0, sizeof( buf ) );
 
+    n = dhm.len;
     if( ( ret = mbedtls_net_recv( &client_fd, buf, n ) ) != (int) n )
     {
         mbedtls_printf( " failed\n  ! mbedtls_net_recv returned %d\n\n", ret );
diff --git a/programs/pkey/ecdsa.c b/programs/pkey/ecdsa.c
index c3ce56a..b474060 100644
--- a/programs/pkey/ecdsa.c
+++ b/programs/pkey/ecdsa.c
@@ -102,7 +102,6 @@
     mbedtls_ecdsa_context ctx_sign, ctx_verify;
     mbedtls_entropy_context entropy;
     mbedtls_ctr_drbg_context ctr_drbg;
-    mbedtls_sha256_context sha256_ctx;
     unsigned char message[100];
     unsigned char hash[32];
     unsigned char sig[MBEDTLS_ECDSA_MAX_LEN];
@@ -113,7 +112,6 @@
     mbedtls_ecdsa_init( &ctx_sign );
     mbedtls_ecdsa_init( &ctx_verify );
     mbedtls_ctr_drbg_init( &ctr_drbg );
-    mbedtls_sha256_init( &sha256_ctx );
 
     memset( sig, 0, sizeof( sig ) );
     memset( message, 0x25, sizeof( message ) );
@@ -165,9 +163,11 @@
     mbedtls_printf( "  . Computing message hash..." );
     fflush( stdout );
 
-    mbedtls_sha256_starts( &sha256_ctx, 0 );
-    mbedtls_sha256_update( &sha256_ctx, message, sizeof( message ) );
-    mbedtls_sha256_finish( &sha256_ctx, hash );
+    if( ( ret = mbedtls_sha256_ret( message, sizeof( message ), hash, 0 ) ) != 0 )
+    {
+        mbedtls_printf( " failed\n  ! mbedtls_sha256_ret returned %d\n", ret );
+        goto exit;
+    }
 
     mbedtls_printf( " ok\n" );
 
@@ -242,7 +242,6 @@
     mbedtls_ecdsa_free( &ctx_sign );
     mbedtls_ctr_drbg_free( &ctr_drbg );
     mbedtls_entropy_free( &entropy );
-    mbedtls_sha256_free( &sha256_ctx );
 
     return( ret );
 }
diff --git a/programs/pkey/gen_key.c b/programs/pkey/gen_key.c
index ed6ed30..a7f5c90 100644
--- a/programs/pkey/gen_key.c
+++ b/programs/pkey/gen_key.c
@@ -345,7 +345,7 @@
                                    mbedtls_ctr_drbg_random, &ctr_drbg );
         if( ret != 0 )
         {
-            mbedtls_printf( " failed\n  !  mbedtls_rsa_gen_key returned -0x%04x", -ret );
+            mbedtls_printf( " failed\n  !  mbedtls_ecp_gen_key returned -0x%04x", -ret );
             goto exit;
         }
     }
diff --git a/programs/ssl/ssl_server2.c b/programs/ssl/ssl_server2.c
index 1285abc..cc29b49 100644
--- a/programs/ssl/ssl_server2.c
+++ b/programs/ssl/ssl_server2.c
@@ -2019,8 +2019,10 @@
 #if !defined(_WIN32)
     if( received_sigterm )
     {
-        mbedtls_printf( " interrupted by SIGTERM\n" );
-        ret = 0;
+        mbedtls_printf( " interrupted by SIGTERM (not in net_accept())\n" );
+        if( ret == MBEDTLS_ERR_NET_INVALID_CONTEXT )
+            ret = 0;
+
         goto exit;
     }
 #endif
@@ -2056,8 +2058,10 @@
 #if !defined(_WIN32)
         if( received_sigterm )
         {
-            mbedtls_printf( " interrupted by signal\n" );
-            ret = 0;
+            mbedtls_printf( " interrupted by SIGTERM (in net_accept())\n" );
+            if( ret == MBEDTLS_ERR_NET_ACCEPT_FAILED )
+                ret = 0;
+
             goto exit;
         }
 #endif
diff --git a/programs/test/benchmark.c b/programs/test/benchmark.c
index a2677af..2864caf 100644
--- a/programs/test/benchmark.c
+++ b/programs/test/benchmark.c
@@ -131,15 +131,6 @@
                      ( mbedtls_timing_hardclock() - tsc ) / ( jj * BUFSIZE ) );         \
 } while( 0 )
 
-#if defined(MBEDTLS_ERROR_C)
-#define PRINT_ERROR                                                     \
-        mbedtls_strerror( ret, ( char * )tmp, sizeof( tmp ) );          \
-        mbedtls_printf( "FAILED: %s\n", tmp );
-#else
-#define PRINT_ERROR                                                     \
-        mbedtls_printf( "FAILED: -0x%04x\n", -ret );
-#endif
-
 #if defined(MBEDTLS_MEMORY_BUFFER_ALLOC_C) && defined(MBEDTLS_MEMORY_DEBUG)
 
 #define MEMORY_MEASURE_INIT                                             \
@@ -327,32 +318,32 @@
 
 #if defined(MBEDTLS_MD4_C)
     if( todo.md4 )
-        TIME_AND_TSC( "MD4", mbedtls_md4( buf, BUFSIZE, tmp ) );
+        TIME_AND_TSC( "MD4", mbedtls_md4_ret( buf, BUFSIZE, tmp ) );
 #endif
 
 #if defined(MBEDTLS_MD5_C)
     if( todo.md5 )
-        TIME_AND_TSC( "MD5", mbedtls_md5( buf, BUFSIZE, tmp ) );
+        TIME_AND_TSC( "MD5", mbedtls_md5_ret( buf, BUFSIZE, tmp ) );
 #endif
 
 #if defined(MBEDTLS_RIPEMD160_C)
     if( todo.ripemd160 )
-        TIME_AND_TSC( "RIPEMD160", mbedtls_ripemd160( buf, BUFSIZE, tmp ) );
+        TIME_AND_TSC( "RIPEMD160", mbedtls_ripemd160_ret( buf, BUFSIZE, tmp ) );
 #endif
 
 #if defined(MBEDTLS_SHA1_C)
     if( todo.sha1 )
-        TIME_AND_TSC( "SHA-1", mbedtls_sha1( buf, BUFSIZE, tmp ) );
+        TIME_AND_TSC( "SHA-1", mbedtls_sha1_ret( buf, BUFSIZE, tmp ) );
 #endif
 
 #if defined(MBEDTLS_SHA256_C)
     if( todo.sha256 )
-        TIME_AND_TSC( "SHA-256", mbedtls_sha256( buf, BUFSIZE, tmp, 0 ) );
+        TIME_AND_TSC( "SHA-256", mbedtls_sha256_ret( buf, BUFSIZE, tmp, 0 ) );
 #endif
 
 #if defined(MBEDTLS_SHA512_C)
     if( todo.sha512 )
-        TIME_AND_TSC( "SHA-512", mbedtls_sha512( buf, BUFSIZE, tmp, 0 ) );
+        TIME_AND_TSC( "SHA-512", mbedtls_sha512_ret( buf, BUFSIZE, tmp, 0 ) );
 #endif
 
 #if defined(MBEDTLS_ARC4_C)
@@ -667,14 +658,22 @@
     if( todo.dhm )
     {
         int dhm_sizes[] = { 2048, 3072 };
-        const char *dhm_P[] = {
-            MBEDTLS_DHM_RFC3526_MODP_2048_P,
-            MBEDTLS_DHM_RFC3526_MODP_3072_P,
-        };
-        const char *dhm_G[] = {
-            MBEDTLS_DHM_RFC3526_MODP_2048_G,
-            MBEDTLS_DHM_RFC3526_MODP_3072_G,
-        };
+        const unsigned char dhm_P_2048[] =
+            MBEDTLS_DHM_RFC3526_MODP_2048_P_BIN;
+        const unsigned char dhm_P_3072[] =
+            MBEDTLS_DHM_RFC3526_MODP_3072_P_BIN;
+        const unsigned char dhm_G_2048[] =
+            MBEDTLS_DHM_RFC3526_MODP_2048_G_BIN;
+        const unsigned char dhm_G_3072[] =
+            MBEDTLS_DHM_RFC3526_MODP_3072_G_BIN;
+
+        const unsigned char *dhm_P[] = { dhm_P_2048, dhm_P_3072 };
+        const size_t dhm_P_size[] = { sizeof( dhm_P_2048 ),
+                                      sizeof( dhm_P_3072 ) };
+
+        const unsigned char *dhm_G[] = { dhm_G_2048, dhm_G_3072 };
+        const size_t dhm_G_size[] = { sizeof( dhm_G_2048 ),
+                                      sizeof( dhm_G_3072 ) };
 
         mbedtls_dhm_context dhm;
         size_t olen;
@@ -682,8 +681,10 @@
         {
             mbedtls_dhm_init( &dhm );
 
-            if( mbedtls_mpi_read_string( &dhm.P, 16, dhm_P[i] ) != 0 ||
-                mbedtls_mpi_read_string( &dhm.G, 16, dhm_G[i] ) != 0 )
+            if( mbedtls_mpi_read_binary( &dhm.P, dhm_P[i],
+                                         dhm_P_size[i] ) != 0 ||
+                mbedtls_mpi_read_binary( &dhm.G, dhm_G[i],
+                                         dhm_G_size[i] ) != 0 )
             {
                 mbedtls_exit( 1 );
             }
diff --git a/scripts/generate_errors.pl b/scripts/generate_errors.pl
index cfcf07c..59618d4 100755
--- a/scripts/generate_errors.pl
+++ b/scripts/generate_errors.pl
@@ -29,13 +29,14 @@
 
 my $error_format_file = $data_dir.'/error.fmt';
 
-my @low_level_modules = ( "AES", "ASN1", "BLOWFISH", "CAMELLIA", "BIGNUM",
-                          "BASE64", "XTEA", "PBKDF2", "OID",
-                          "PADLOCK", "DES", "NET", "CTR_DRBG", "ENTROPY",
-                          "HMAC_DRBG", "MD2", "MD4", "MD5", "RIPEMD160",
-                          "SHA1", "SHA256", "SHA512", "GCM", "THREADING", "CCM" );
-my @high_level_modules = ( "PEM", "X509", "DHM", "RSA", "ECP", "MD", "CIPHER", "SSL",
-                           "PK", "PKCS12", "PKCS5" );
+my @low_level_modules = qw( AES ARC4 ASN1 BASE64 BIGNUM BLOWFISH
+                            CAMELLIA CCM CMAC CTR_DRBG DES
+                            ENTROPY GCM HMAC_DRBG MD2 MD4 MD5
+                            NET OID PADLOCK PBKDF2 RIPEMD160
+                            SHA1 SHA256 SHA512 THREADING XTEA );
+my @high_level_modules = qw( CIPHER DHM ECP MD
+                             PEM PK PKCS12 PKCS5
+                             RSA SSL X509 );
 
 my $line_separator = $/;
 undef $/;
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index dc27979..16e19a9 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -31,7 +31,7 @@
     include_directories(${CMAKE_CURRENT_SOURCE_DIR})
     add_executable(test_suite_${data_name} test_suite_${data_name}.c)
     target_link_libraries(test_suite_${data_name} ${libs})
-    add_test(${data_name}-suite test_suite_${data_name})
+    add_test(${data_name}-suite test_suite_${data_name} --verbose)
 endfunction(add_test_suite)
 
 if(CMAKE_COMPILER_IS_GNUCC OR CMAKE_COMPILER_IS_CLANG)
diff --git a/tests/compat.sh b/tests/compat.sh
index 958d618..672bdab 100755
--- a/tests/compat.sh
+++ b/tests/compat.sh
@@ -887,8 +887,9 @@
         done
     }
 else
+    echo "Warning: lsof not available, wait_server_start = sleep"
     wait_server_start() {
-        sleep 1
+        sleep 2
     }
 fi
 
diff --git a/tests/data_files/rsa512.key b/tests/data_files/rsa512.key
new file mode 100644
index 0000000..1fd7987
--- /dev/null
+++ b/tests/data_files/rsa512.key
@@ -0,0 +1,9 @@
+-----BEGIN RSA PRIVATE KEY-----
+MIIBOwIBAAJBALB20jJQgW+aqwIwfkUrl/DK51mDabQWJOivx5caWaE4kvZLB+qm
+7JKMFgstbsj50N1bY8izrAdntPZciS9WwQ8CAwEAAQJAKYfNcIoB7II6PQmsrhrU
+Z5dZW3fSKNANX7X/A1DwR0DlF8uZnpWsWbYcRoXX7QjvepZqc54wryhW55Wlm6yI
+AQIhAOJIaLjSpbHjzzcJQ7mylxn2WGIlbJPPzJ9OaFZCZQvxAiEAx6OEAvl6JKa6
+6a+N2Wvhtcgb4qqR6UHQGJQYGJz5nP8CIAvgoR6ScAAWZRoOcm+c4DGMrLb6H+ji
+T2tNQkzEz2kBAiEAmw34GStU36STpa6RGJ4+tyZN6jWakDVqf7x+HpfFE1cCIQDc
+KzXIxec2taye4OeIa1v4W/MigMmYE9w93Uw/Qi3azA==
+-----END RSA PRIVATE KEY-----
diff --git a/tests/data_files/rsa521.key b/tests/data_files/rsa521.key
new file mode 100644
index 0000000..0b940aa
--- /dev/null
+++ b/tests/data_files/rsa521.key
@@ -0,0 +1,9 @@
+-----BEGIN RSA PRIVATE KEY-----
+MIIBPQIBAAJCATG2mGDzy5v4XqNY/fK9KZDxt3qA1qT9+BekPdiWvffdJq+KwCN/
+Um4NM7EFyXH9vU/6ns6Z/EafMez0Kej1YsHDAgMBAAECQCdoYjwdMSHp4kksL5Aa
+0kDc58ni0chy9IgXo+FHjTVmR9DkaZANrwfVvYMJxqYCZo0im1Dw7ZJBUDJQNXnl
+ZokCIRiSk66I24AWa7XGUFvatVwXWi2ACE4QEKqzWQe1mQ24/wIhDHD1TCKpqucA
+XDI+1N7EHs+fN4CfTSWe8FPGiK6q3VM9AiESrKKLi/q011U4KeS8SfR2blDcL2cg
+XFkuQWqxzzLoGOUCIQmgl5E0+Ypwe0zc7NYZFDarf4+ZjqxKQnXCvk0irMHcGQIh
+EVPli6RQb3Gcx7vXJHltzSTno7NElzBDRMBVUlBmVxAJ
+-----END RSA PRIVATE KEY-----
diff --git a/tests/data_files/rsa522.key b/tests/data_files/rsa522.key
new file mode 100644
index 0000000..18fbe70
--- /dev/null
+++ b/tests/data_files/rsa522.key
@@ -0,0 +1,9 @@
+-----BEGIN RSA PRIVATE KEY-----
+MIIBPgIBAAJCAtMCdT492ij0L02fkshkdCDqb7yXwQ+EmLlmqVPzV2mNZYEGDf4y
+yKuY20vFzirN8MHm5ASnWhMoJVDBqjfTzci/AgMBAAECQU05ffxf7uVg74yC9tKg
+qCa746NpMh3OM+HZrUxiOXv0sJMRXNEPD5HNLtgcNY6MI5NYbUvkOXktnFZpxWYP
+TH7BAiEeFJGs5Z6gRd2v/IbYLMFDHgjqho04INGTOvnyI7lGVKUCIRgJM7moFuoM
+UrKTmJK1uOzauWEykCKgc6BGH6TGZoEWkwIhBzQn2v82qO1ydOYGKRk2w2sa+Yd1
+pH5/kkHqf+m8QjKdAiEQ9eVW+4J30wxD0JyX4b1E/S5UpN5KYNhWX0US+6D3NBsC
+IRxePzdQlutZWg0Cnku3QE1tOLBCFlP7QVVl5FbKcY5H5w==
+-----END RSA PRIVATE KEY-----
diff --git a/tests/data_files/rsa528.key b/tests/data_files/rsa528.key
new file mode 100644
index 0000000..fd463b5
--- /dev/null
+++ b/tests/data_files/rsa528.key
@@ -0,0 +1,9 @@
+-----BEGIN RSA PRIVATE KEY-----
+MIIBRQIBAAJDAOMcJG1GSFmEJh/RdMqz1DVzRGAuzXk8R9vlQlLTe7NQvGNDWbGV
+FVQggORySktnIpG+V8dkj1Finq7yNOhH2ZzGXwIDAQABAkMAsWYyLglQSlwnS4NZ
+L1z4zieTqW3lomWr2+BgxkHbxl2w0Rx4L+Ezp+YK6mhtIQWNkoytPvWJJMS7Jrkg
+agMAHQJBAiIA+F1y5GO0Bv+igsNLXwwtbCqs8hAkavU9W8egt/oDbhzbAiIA6hds
+PZp/s1X7n7dwfmebSs+3vLZFuQfifN8XZLw0CXHNAiEuEzgDQrPdMIN3er96zImI
+rYoUBgabiQ9u/WPFfa4xOU0CIgDDYC089Tfjy72pPgcr2PkpZVhqro5esg/8PI5f
+yxx7TXkCIgCYoE8Y5IxomtL1ub1AQzPe9UyyUGzQB1yWeiloJh6LjxA=
+-----END RSA PRIVATE KEY-----
diff --git a/tests/scripts/all.sh b/tests/scripts/all.sh
index b559af8..d5fc12d 100755
--- a/tests/scripts/all.sh
+++ b/tests/scripts/all.sh
@@ -653,34 +653,39 @@
     cleanup
     make CC=gcc CFLAGS='-Werror -Wall -Wextra -m32'
 
-    msg "build: gcc, force 32-bit compilation"
-    cleanup
-    cp "$CONFIG_H" "$CONFIG_BAK"
-    scripts/config.pl unset MBEDTLS_HAVE_ASM
-    scripts/config.pl unset MBEDTLS_AESNI_C
-    scripts/config.pl unset MBEDTLS_PADLOCK_C
-    make CC=gcc CFLAGS='-Werror -Wall -Wextra -DMBEDTLS_HAVE_INT32'
-
-    msg "build: gcc, force 64-bit compilation"
-    cleanup
-    cp "$CONFIG_H" "$CONFIG_BAK"
-    scripts/config.pl unset MBEDTLS_HAVE_ASM
-    scripts/config.pl unset MBEDTLS_AESNI_C
-    scripts/config.pl unset MBEDTLS_PADLOCK_C
-    make CC=gcc CFLAGS='-Werror -Wall -Wextra -DMBEDTLS_HAVE_INT64'
-
-    msg "test: gcc, force 64-bit compilation"
+    msg "test: i386, make, gcc"
     make test
 
-    msg "build: gcc, force 64-bit compilation"
+    msg "build: 64-bit ILP32, make, gcc" # ~ 30s
     cleanup
-    cp "$CONFIG_H" "$CONFIG_BAK"
-    scripts/config.pl unset MBEDTLS_HAVE_ASM
-    scripts/config.pl unset MBEDTLS_AESNI_C
-    scripts/config.pl unset MBEDTLS_PADLOCK_C
-    make CC=gcc CFLAGS='-Werror -Wall -Wextra -DMBEDTLS_HAVE_INT64'
+    make CC=gcc CFLAGS='-Werror -Wall -Wextra -mx32'
+
+    msg "test: 64-bit ILP32, make, gcc"
+    make test
 fi # x86_64
 
+msg "build: gcc, force 32-bit bignum limbs"
+cleanup
+cp "$CONFIG_H" "$CONFIG_BAK"
+scripts/config.pl unset MBEDTLS_HAVE_ASM
+scripts/config.pl unset MBEDTLS_AESNI_C
+scripts/config.pl unset MBEDTLS_PADLOCK_C
+make CC=gcc CFLAGS='-Werror -Wall -Wextra -DMBEDTLS_HAVE_INT32'
+
+msg "test: gcc, force 32-bit bignum limbs"
+make test
+
+msg "build: gcc, force 64-bit bignum limbs"
+cleanup
+cp "$CONFIG_H" "$CONFIG_BAK"
+scripts/config.pl unset MBEDTLS_HAVE_ASM
+scripts/config.pl unset MBEDTLS_AESNI_C
+scripts/config.pl unset MBEDTLS_PADLOCK_C
+make CC=gcc CFLAGS='-Werror -Wall -Wextra -DMBEDTLS_HAVE_INT64'
+
+msg "test: gcc, force 64-bit bignum limbs"
+make test
+
 msg "build: arm-none-eabi-gcc, make" # ~ 10s
 cleanup
 cp "$CONFIG_H" "$CONFIG_BAK"
diff --git a/tests/ssl-opt.sh b/tests/ssl-opt.sh
index fa785a4..fbdd694 100755
--- a/tests/ssl-opt.sh
+++ b/tests/ssl-opt.sh
@@ -308,6 +308,7 @@
         done
     }
 else
+    echo "Warning: lsof not available, wait_server_start = sleep $START_DELAY"
     wait_server_start() {
         sleep "$START_DELAY"
     }
@@ -656,14 +657,28 @@
 # used by watchdog
 MAIN_PID="$$"
 
-# be more patient with valgrind
+# We use somewhat arbitrary delays for tests:
+# - how long do we wait for the server to start (when lsof not available)?
+# - how long do we allow for the client to finish?
+#   (not to check performance, just to avoid waiting indefinitely)
+# Things are slower with valgrind, so give extra time here.
+#
+# Note: without lsof, there is a trade-off between the running time of this
+# script and the risk of spurious errors because we didn't wait long enough.
+# The watchdog delay on the other hand doesn't affect normal running time of
+# the script, only the case where a client or server gets stuck.
 if [ "$MEMCHECK" -gt 0 ]; then
-    START_DELAY=3
-    DOG_DELAY=30
+    START_DELAY=6
+    DOG_DELAY=60
 else
-    START_DELAY=1
-    DOG_DELAY=10
+    START_DELAY=2
+    DOG_DELAY=20
 fi
+
+# some particular tests need more time:
+# - for the client, we multiply the usual watchdog limit by a factor
+# - for the server, we sleep for a number of seconds after the client exits
+# see client_need_more_time() and server_needs_more_time()
 CLI_DELAY_FACTOR=1
 SRV_DELAY_SECONDS=0
 
@@ -821,40 +836,40 @@
             "$P_SRV debug_level=4" \
             "$P_CLI force_ciphersuite=TLS-RSA-WITH-AES-128-CBC-SHA" \
             0 \
-            -s "dumping 'computed mac' (20 bytes)" \
-            -S "dumping 'computed mac' (10 bytes)"
+            -s "dumping 'expected mac' (20 bytes)" \
+            -S "dumping 'expected mac' (10 bytes)"
 
 run_test    "Truncated HMAC: client disabled, server default" \
             "$P_SRV debug_level=4" \
             "$P_CLI force_ciphersuite=TLS-RSA-WITH-AES-128-CBC-SHA \
              trunc_hmac=0" \
             0 \
-            -s "dumping 'computed mac' (20 bytes)" \
-            -S "dumping 'computed mac' (10 bytes)"
+            -s "dumping 'expected mac' (20 bytes)" \
+            -S "dumping 'expected mac' (10 bytes)"
 
 run_test    "Truncated HMAC: client enabled, server default" \
             "$P_SRV debug_level=4" \
             "$P_CLI force_ciphersuite=TLS-RSA-WITH-AES-128-CBC-SHA \
              trunc_hmac=1" \
             0 \
-            -s "dumping 'computed mac' (20 bytes)" \
-            -S "dumping 'computed mac' (10 bytes)"
+            -s "dumping 'expected mac' (20 bytes)" \
+            -S "dumping 'expected mac' (10 bytes)"
 
 run_test    "Truncated HMAC: client enabled, server disabled" \
             "$P_SRV debug_level=4 trunc_hmac=0" \
             "$P_CLI force_ciphersuite=TLS-RSA-WITH-AES-128-CBC-SHA \
              trunc_hmac=1" \
             0 \
-            -s "dumping 'computed mac' (20 bytes)" \
-            -S "dumping 'computed mac' (10 bytes)"
+            -s "dumping 'expected mac' (20 bytes)" \
+            -S "dumping 'expected mac' (10 bytes)"
 
 run_test    "Truncated HMAC: client enabled, server enabled" \
             "$P_SRV debug_level=4 trunc_hmac=1" \
             "$P_CLI force_ciphersuite=TLS-RSA-WITH-AES-128-CBC-SHA \
              trunc_hmac=1" \
             0 \
-            -S "dumping 'computed mac' (20 bytes)" \
-            -s "dumping 'computed mac' (10 bytes)"
+            -S "dumping 'expected mac' (20 bytes)" \
+            -s "dumping 'expected mac' (10 bytes)"
 
 # Tests for Encrypt-then-MAC extension
 
@@ -3082,7 +3097,7 @@
                     debug_level=3" \
             0 \
             -c "value of 'DHM: P ' (2048 bits)" \
-            -c "value of 'DHM: G ' (2048 bits)"
+            -c "value of 'DHM: G ' (2 bits)"
 
 run_test    "DHM parameters: other parameters" \
             "$P_SRV dhm_file=data_files/dhparams.pem" \
diff --git a/tests/suites/test_suite_cipher.padding.data b/tests/suites/test_suite_cipher.padding.data
index d6fc266..1c0ba09 100644
--- a/tests/suites/test_suite_cipher.padding.data
+++ b/tests/suites/test_suite_cipher.padding.data
@@ -184,6 +184,10 @@
 depends_on:MBEDTLS_CIPHER_PADDING_ONE_AND_ZEROS
 check_padding:MBEDTLS_PADDING_ONE_AND_ZEROS:"0000000000":MBEDTLS_ERR_CIPHER_INVALID_PADDING:4
 
+Check one and zeros padding #8 (last byte 0x80 | x)
+depends_on:MBEDTLS_CIPHER_PADDING_ONE_AND_ZEROS
+check_padding:MBEDTLS_PADDING_ONE_AND_ZEROS:"0000000082":MBEDTLS_ERR_CIPHER_INVALID_PADDING:4
+
 Check zeros and len padding #1 (correct)
 depends_on:MBEDTLS_CIPHER_PADDING_ZEROS_AND_LEN
 check_padding:MBEDTLS_PADDING_ZEROS_AND_LEN:"DABBAD0001":0:4
diff --git a/tests/suites/test_suite_ctr_drbg.function b/tests/suites/test_suite_ctr_drbg.function
index 883cfe0..d8ffebe 100644
--- a/tests/suites/test_suite_ctr_drbg.function
+++ b/tests/suites/test_suite_ctr_drbg.function
@@ -1,8 +1,8 @@
 /* BEGIN_HEADER */
 #include "mbedtls/ctr_drbg.h"
 
-int test_offset_idx;
-int mbedtls_entropy_func( void *data, unsigned char *buf, size_t len )
+static int test_offset_idx;
+static int mbedtls_test_entropy_func( void *data, unsigned char *buf, size_t len )
 {
     const unsigned char *p = (unsigned char *) data;
     memcpy( buf, p + test_offset_idx, len );
@@ -72,7 +72,7 @@
     add2_len = unhexify( add2, add2_string );
 
     test_offset_idx = 0;
-    TEST_ASSERT( mbedtls_ctr_drbg_seed_entropy_len( &ctx, mbedtls_entropy_func, entropy, add_init, add_init_len, 32 ) == 0 );
+    TEST_ASSERT( mbedtls_ctr_drbg_seed_entropy_len( &ctx, mbedtls_test_entropy_func, entropy, add_init, add_init_len, 32 ) == 0 );
     mbedtls_ctr_drbg_set_prediction_resistance( &ctx, MBEDTLS_CTR_DRBG_PR_ON );
 
     TEST_ASSERT( mbedtls_ctr_drbg_random_with_add( &ctx, buf, 16, add1, add1_len ) == 0 );
@@ -110,7 +110,7 @@
     add2_len = unhexify( add2, add2_string );
 
     test_offset_idx = 0;
-    TEST_ASSERT( mbedtls_ctr_drbg_seed_entropy_len( &ctx, mbedtls_entropy_func, entropy, add_init, add_init_len, 32 ) == 0 );
+    TEST_ASSERT( mbedtls_ctr_drbg_seed_entropy_len( &ctx, mbedtls_test_entropy_func, entropy, add_init, add_init_len, 32 ) == 0 );
 
     TEST_ASSERT( mbedtls_ctr_drbg_random_with_add( &ctx, buf, 16, add1, add1_len ) == 0 );
     TEST_ASSERT( mbedtls_ctr_drbg_reseed( &ctx, add_reseed, add_reseed_len ) == 0 );
@@ -141,7 +141,7 @@
 
     /* Init must use entropy */
     last_idx = test_offset_idx;
-    TEST_ASSERT( mbedtls_ctr_drbg_seed( &ctx, mbedtls_entropy_func, entropy, NULL, 0 ) == 0 );
+    TEST_ASSERT( mbedtls_ctr_drbg_seed( &ctx, mbedtls_test_entropy_func, entropy, NULL, 0 ) == 0 );
     TEST_ASSERT( last_idx < test_offset_idx );
 
     /* By default, PR is off and reseed_interval is large,
diff --git a/tests/suites/test_suite_dhm.data b/tests/suites/test_suite_dhm.data
index f2cdeff..e351ebd 100644
--- a/tests/suites/test_suite_dhm.data
+++ b/tests/suites/test_suite_dhm.data
@@ -1,11 +1,23 @@
 Diffie-Hellman full exchange #1
-dhm_do_dhm:10:"23":10:"5"
+dhm_do_dhm:10:"23":10:"5":0
 
 Diffie-Hellman full exchange #2
-dhm_do_dhm:10:"93450983094850938450983409623":10:"9345098304850938450983409622"
+dhm_do_dhm:10:"93450983094850938450983409623":10:"9345098304850938450983409622":0
 
 Diffie-Hellman full exchange #3
-dhm_do_dhm:10:"93450983094850938450983409623982317398171298719873918739182739712938719287391879381271":10:"9345098309485093845098340962223981329819812792137312973297123912791271"
+dhm_do_dhm:10:"93450983094850938450983409623982317398171298719873918739182739712938719287391879381271":10:"9345098309485093845098340962223981329819812792137312973297123912791271":0
+
+Diffie-Hellman trivial subgroup #1
+dhm_do_dhm:10:"23":10:"1":MBEDTLS_ERR_DHM_BAD_INPUT_DATA
+
+Diffie-Hellman trivial subgroup #2
+dhm_do_dhm:10:"23":10:"-1":MBEDTLS_ERR_DHM_BAD_INPUT_DATA
+
+Diffie-Hellman small modulus
+dhm_do_dhm:10:"3":10:"5":MBEDTLS_ERR_DHM_MAKE_PARAMS_FAILED
+
+Diffie-Hellman zero modulus
+dhm_do_dhm:10:"0":10:"5":MBEDTLS_ERR_DHM_BAD_INPUT_DATA
 
 Diffie-Hallman load parameters from file
 dhm_file:"data_files/dhparams.pem":"9e35f430443a09904f3a39a979797d070df53378e79c2438bef4e761f3c714553328589b041c809be1d6c6b5f1fc9f47d3a25443188253a992a56818b37ba9de5a40d362e56eff0be5417474c125c199272c8fe41dea733df6f662c92ae76556e755d10c64e6a50968f67fc6ea73d0dca8569be2ba204e23580d8bca2f4975b3":"02":128
diff --git a/tests/suites/test_suite_dhm.function b/tests/suites/test_suite_dhm.function
index b9b8e19..4fd8fff 100644
--- a/tests/suites/test_suite_dhm.function
+++ b/tests/suites/test_suite_dhm.function
@@ -9,7 +9,7 @@
 
 /* BEGIN_CASE */
 void dhm_do_dhm( int radix_P, char *input_P,
-                 int radix_G, char *input_G )
+                 int radix_G, char *input_G, int result )
 {
     mbedtls_dhm_context ctx_srv;
     mbedtls_dhm_context ctx_cli;
@@ -44,7 +44,10 @@
     /*
      * First key exchange
      */
-    TEST_ASSERT( mbedtls_dhm_make_params( &ctx_srv, x_size, ske, &ske_len, &rnd_pseudo_rand, &rnd_info ) == 0 );
+    TEST_ASSERT( mbedtls_dhm_make_params( &ctx_srv, x_size, ske, &ske_len, &rnd_pseudo_rand, &rnd_info ) == result );
+    if ( result != 0 )
+        goto exit;
+
     ske[ske_len++] = 0;
     ske[ske_len++] = 0;
     TEST_ASSERT( mbedtls_dhm_read_params( &ctx_cli, &p, ske + ske_len ) == 0 );
diff --git a/tests/suites/test_suite_hmac_drbg.function b/tests/suites/test_suite_hmac_drbg.function
index 5209470..a413f5e 100644
--- a/tests/suites/test_suite_hmac_drbg.function
+++ b/tests/suites/test_suite_hmac_drbg.function
@@ -7,7 +7,7 @@
     size_t len;
 } entropy_ctx;
 
-int mbedtls_entropy_func( void *data, unsigned char *buf, size_t len )
+static int mbedtls_test_entropy_func( void *data, unsigned char *buf, size_t len )
 {
     entropy_ctx *ctx = (entropy_ctx *) data;
 
@@ -50,7 +50,7 @@
 
     /* Init must use entropy */
     last_len = entropy.len;
-    TEST_ASSERT( mbedtls_hmac_drbg_seed( &ctx, md_info, mbedtls_entropy_func, &entropy,
+    TEST_ASSERT( mbedtls_hmac_drbg_seed( &ctx, md_info, mbedtls_test_entropy_func, &entropy,
                                  NULL, 0 ) == 0 );
     TEST_ASSERT( entropy.len < last_len );
 
@@ -206,7 +206,7 @@
     TEST_ASSERT( memcmp( my_output, output, out_len ) == 0 );
 
     /* And now the normal entropy-based variant */
-    TEST_ASSERT( mbedtls_hmac_drbg_seed( &ctx, md_info, mbedtls_entropy_func, &p_entropy,
+    TEST_ASSERT( mbedtls_hmac_drbg_seed( &ctx, md_info, mbedtls_test_entropy_func, &p_entropy,
                                  custom, custom_len ) == 0 );
     TEST_ASSERT( mbedtls_hmac_drbg_random_with_add( &ctx, my_output, out_len,
                                             add1, add1_len ) == 0 );
@@ -251,7 +251,7 @@
     md_info = mbedtls_md_info_from_type( md_alg );
     TEST_ASSERT( md_info != NULL );
 
-    TEST_ASSERT( mbedtls_hmac_drbg_seed( &ctx, md_info, mbedtls_entropy_func, &p_entropy,
+    TEST_ASSERT( mbedtls_hmac_drbg_seed( &ctx, md_info, mbedtls_test_entropy_func, &p_entropy,
                                  custom, custom_len ) == 0 );
     TEST_ASSERT( mbedtls_hmac_drbg_reseed( &ctx, add1, add1_len ) == 0 );
     TEST_ASSERT( mbedtls_hmac_drbg_random_with_add( &ctx, my_output, out_len,
@@ -296,7 +296,7 @@
     md_info = mbedtls_md_info_from_type( md_alg );
     TEST_ASSERT( md_info != NULL );
 
-    TEST_ASSERT( mbedtls_hmac_drbg_seed( &ctx, md_info, mbedtls_entropy_func, &p_entropy,
+    TEST_ASSERT( mbedtls_hmac_drbg_seed( &ctx, md_info, mbedtls_test_entropy_func, &p_entropy,
                                  custom, custom_len ) == 0 );
     mbedtls_hmac_drbg_set_prediction_resistance( &ctx, MBEDTLS_HMAC_DRBG_PR_ON );
     TEST_ASSERT( mbedtls_hmac_drbg_random_with_add( &ctx, my_output, out_len,
diff --git a/tests/suites/test_suite_mdx.function b/tests/suites/test_suite_mdx.function
index 9d0ee47..648a9cc 100644
--- a/tests/suites/test_suite_mdx.function
+++ b/tests/suites/test_suite_mdx.function
@@ -8,6 +8,7 @@
 /* BEGIN_CASE depends_on:MBEDTLS_MD2_C */
 void md2_text( char *text_src_string, char *hex_hash_string )
 {
+    int ret;
     unsigned char src_str[100];
     unsigned char hash_str[33];
     unsigned char output[16];
@@ -18,7 +19,8 @@
 
     strncpy( (char *) src_str, text_src_string, sizeof(src_str) - 1 );
 
-    mbedtls_md2( src_str, strlen( (char *) src_str ), output );
+    ret = mbedtls_md2_ret( src_str, strlen( (char *) src_str ), output );
+    TEST_ASSERT( ret == 0 ) ;
     hexify( hash_str, output, sizeof  output );
 
     TEST_ASSERT( strcmp( (char *) hash_str, hex_hash_string ) == 0 );
@@ -28,6 +30,7 @@
 /* BEGIN_CASE depends_on:MBEDTLS_MD4_C */
 void md4_text( char *text_src_string, char *hex_hash_string )
 {
+    int ret;
     unsigned char src_str[100];
     unsigned char hash_str[33];
     unsigned char output[16];
@@ -38,7 +41,8 @@
 
     strncpy( (char *) src_str, text_src_string, sizeof(src_str) - 1 );
 
-    mbedtls_md4( src_str, strlen( (char *) src_str ), output );
+    ret = mbedtls_md4_ret( src_str, strlen( (char *) src_str ), output );
+    TEST_ASSERT( ret == 0 );
     hexify( hash_str, output, sizeof  output );
 
     TEST_ASSERT( strcmp( (char *) hash_str, hex_hash_string ) == 0 );
@@ -48,6 +52,7 @@
 /* BEGIN_CASE depends_on:MBEDTLS_MD5_C */
 void md5_text( char *text_src_string, char *hex_hash_string )
 {
+    int ret;
     unsigned char src_str[100];
     unsigned char hash_str[33];
     unsigned char output[16];
@@ -58,7 +63,8 @@
 
     strncpy( (char *) src_str, text_src_string, sizeof(src_str) - 1 );
 
-    mbedtls_md5( src_str, strlen( (char *) src_str ), output );
+    ret = mbedtls_md5_ret( src_str, strlen( (char *) src_str ), output );
+    TEST_ASSERT( ret == 0 );
     hexify( hash_str, output, sizeof  output );
 
     TEST_ASSERT( strcmp( (char *) hash_str, hex_hash_string ) == 0 );
@@ -68,6 +74,7 @@
 /* BEGIN_CASE depends_on:MBEDTLS_RIPEMD160_C */
 void ripemd160_text( char *text_src_string, char *hex_hash_string )
 {
+    int ret;
     unsigned char src_str[100];
     unsigned char hash_str[41];
     unsigned char output[20];
@@ -78,7 +85,8 @@
 
     strncpy( (char *) src_str, text_src_string, sizeof(src_str) - 1 );
 
-    mbedtls_ripemd160( src_str, strlen( (char *) src_str ), output );
+    ret = mbedtls_ripemd160_ret( src_str, strlen( (char *) src_str ), output );
+    TEST_ASSERT( ret == 0 );
     hexify( hash_str, output, sizeof output );
 
     TEST_ASSERT( strcmp( (char *) hash_str, hex_hash_string ) == 0 );
diff --git a/tests/suites/test_suite_pk.function b/tests/suites/test_suite_pk.function
index e847836..2180f5c 100644
--- a/tests/suites/test_suite_pk.function
+++ b/tests/suites/test_suite_pk.function
@@ -5,8 +5,8 @@
 #include "mbedtls/ecp.h"
 #include "mbedtls/rsa.h"
 
-/* For detecting 64-bit compilation */
-#include "mbedtls/bignum.h"
+#include <limits.h>
+#include <stdint.h>
 
 static int rnd_std_rand( void *rng_state, unsigned char *output, size_t len );
 
@@ -413,11 +413,14 @@
 }
 /* END_CASE */
 
-/* BEGIN_CASE depends_on:MBEDTLS_RSA_C:MBEDTLS_HAVE_INT64 */
+/* BEGIN_CASE depends_on:MBEDTLS_RSA_C */
 void pk_rsa_overflow( )
 {
     mbedtls_pk_context pk;
-    size_t hash_len = (size_t)-1;
+    size_t hash_len = SIZE_MAX;
+
+    if( SIZE_MAX <= UINT_MAX )
+        return;
 
     mbedtls_pk_init( &pk );
 
@@ -486,13 +489,13 @@
     TEST_ASSERT( strcmp( mbedtls_pk_get_name( &alt ), "RSA-alt" ) == 0 );
 
     /* Test signature */
-    TEST_ASSERT( mbedtls_pk_sign( &alt, MBEDTLS_MD_NONE, hash, sizeof hash,
-                          sig, &sig_len, rnd_std_rand, NULL ) == 0 );
-#if defined(MBEDTLS_HAVE_INT64)
-    TEST_ASSERT( mbedtls_pk_sign( &alt, MBEDTLS_MD_NONE, hash, (size_t)-1,
-                          NULL, NULL, rnd_std_rand, NULL ) ==
+#if SIZE_MAX > UINT_MAX
+    TEST_ASSERT( mbedtls_pk_sign( &alt, MBEDTLS_MD_NONE, hash, SIZE_MAX,
+                                  sig, &sig_len, rnd_std_rand, NULL ) ==
                  MBEDTLS_ERR_PK_BAD_INPUT_DATA );
-#endif /* MBEDTLS_HAVE_INT64 */
+#endif /* SIZE_MAX > UINT_MAX */
+    TEST_ASSERT( mbedtls_pk_sign( &alt, MBEDTLS_MD_NONE, hash, sizeof hash,
+                                  sig, &sig_len, rnd_std_rand, NULL ) == 0 );
     TEST_ASSERT( sig_len == RSA_KEY_LEN );
     TEST_ASSERT( mbedtls_pk_verify( &rsa, MBEDTLS_MD_NONE,
                             hash, sizeof hash, sig, sig_len ) == 0 );
diff --git a/tests/suites/test_suite_pkcs1_v21.data b/tests/suites/test_suite_pkcs1_v21.data
index ac16beb..6258c62 100644
--- a/tests/suites/test_suite_pkcs1_v21.data
+++ b/tests/suites/test_suite_pkcs1_v21.data
@@ -787,3 +787,47 @@
 depends_on:MBEDTLS_SHA256_C
 pkcs1_rsassa_pss_verify_ext:1024:16:"00dd118a9f99bab068ca2aea3b6a6d5997ed4ec954e40deecea07da01eaae80ec2bb1340db8a128e891324a5c5f5fad8f590d7c8cacbc5fe931dafda1223735279461abaa0572b761631b3a8afe7389b088b63993a0a25ee45d21858bab9931aedd4589a631b37fcf714089f856549f359326dd1e0e86dde52ed66b4a90bda4095":16:"010001":MBEDTLS_MD_NONE:MBEDTLS_MD_SHA256:MBEDTLS_MD_SHA1:MBEDTLS_RSA_SALT_LEN_ANY:"c0719e9a8d5d838d861dc6f675c899d2b309a3a65bb9fe6b11e5afcbf9a2c0b1":"7fc506d26ca3b22922a1ce39faaedd273161b82d9443c56f1a034f131ae4a18cae1474271cb4b66a17d9707ca58b0bdbd3c406b7e65bbcc9bbbce94dc45de807b4989b23b3e4db74ca29298137837eb90cc83d3219249bc7d480fceaf075203a86e54c4ecfa4e312e39f8f69d76534089a36ed9049ca9cfd5ab1db1fa75fe5c8":0:MBEDTLS_ERR_RSA_INVALID_PADDING
 
+RSASSA-PSS verify ext, 512-bit key, empty salt, good signature
+depends_on:MBEDTLS_SHA256_C
+pkcs1_rsassa_pss_verify_ext:512:16:"00b076d23250816f9aab02307e452b97f0cae7598369b41624e8afc7971a59a13892f64b07eaa6ec928c160b2d6ec8f9d0dd5b63c8b3ac0767b4f65c892f56c10f":16:"010001":MBEDTLS_MD_SHA256:MBEDTLS_MD_SHA256:MBEDTLS_MD_SHA256:0:"":"ace8b03347da1b9a7a5e94a0d76359bb39c819bb170bef38ea84995ed653446c0ae87ede434cdf9d0cb2d7bf164cf427892363e6855a1d24d0ce5dd72acaf246":0:0
+
+RSASSA-PSS verify ext, 512-bit key, empty salt, bad signature
+depends_on:MBEDTLS_SHA256_C
+pkcs1_rsassa_pss_verify_ext:512:16:"00b076d23250816f9aab02307e452b97f0cae7598369b41624e8afc7971a59a13892f64b07eaa6ec928c160b2d6ec8f9d0dd5b63c8b3ac0767b4f65c892f56c10f":16:"010001":MBEDTLS_MD_SHA256:MBEDTLS_MD_SHA256:MBEDTLS_MD_SHA256:0:"":"ace8b03347da1b9a7a5e94a0d76359bb39c819bb170bef38ea84995ed653446c0ae87ede434cdf9d0cb2d7bf164cf427892363e6855a1d24d0ce5dd72acaf247":MBEDTLS_ERR_RSA_INVALID_PADDING:MBEDTLS_ERR_RSA_INVALID_PADDING
+
+RSASSA-PSS verify ext, 522-bit key, SHA-512, empty salt, good signature
+depends_on:MBEDTLS_SHA512_C
+pkcs1_rsassa_pss_verify_ext:522:16:"02d302753e3dda28f42f4d9f92c8647420ea6fbc97c10f8498b966a953f357698d6581060dfe32c8ab98db4bc5ce2acdf0c1e6e404a75a13282550c1aa37d3cdc8bf":16:"010001":MBEDTLS_MD_SHA512:MBEDTLS_MD_SHA512:MBEDTLS_MD_SHA512:0:"":"016752ae0b5dfbade6bbd3dd37868d48c8d741f92dca41c360aeda553204c2212a117b1a3d77e0d3f48723503c46e16c8a64de00f1dee3e37e478417452630859486":0:0
+
+RSASSA-PSS verify ext, 528-bit key, SHA-512, saltlen=64, good signature with saltlen=0
+depends_on:MBEDTLS_SHA512_C
+pkcs1_rsassa_pss_verify_ext:528:16:"00e31c246d46485984261fd174cab3d4357344602ecd793c47dbe54252d37bb350bc634359b19515542080e4724a4b672291be57c7648f51629eaef234e847d99cc65f":16:"010001":MBEDTLS_MD_SHA512:MBEDTLS_MD_SHA512:MBEDTLS_MD_SHA512:64:"":"a9ad7994ba3a1071124153486924448cc67a5af3a5d34e9261d53770782cc85f58e2edde5f7004652a645e3e9606530eb57de41df7298ae2be9dec69cc0d613ab629":0:MBEDTLS_ERR_RSA_INVALID_PADDING
+
+RSASSA-PSS verify ext, 528-bit key, SHA-512, empty salt, good signature
+depends_on:MBEDTLS_SHA512_C
+pkcs1_rsassa_pss_verify_ext:528:16:"00e31c246d46485984261fd174cab3d4357344602ecd793c47dbe54252d37bb350bc634359b19515542080e4724a4b672291be57c7648f51629eaef234e847d99cc65f":16:"010001":MBEDTLS_MD_SHA512:MBEDTLS_MD_SHA512:MBEDTLS_MD_SHA512:0:"":"a9ad7994ba3a1071124153486924448cc67a5af3a5d34e9261d53770782cc85f58e2edde5f7004652a645e3e9606530eb57de41df7298ae2be9dec69cc0d613ab629":0:0
+
+RSASSA-PSS verify ext, 528-bit key, SHA-512, saltlen=64, good signature with saltlen=0
+depends_on:MBEDTLS_SHA512_C
+pkcs1_rsassa_pss_verify_ext:528:16:"00e31c246d46485984261fd174cab3d4357344602ecd793c47dbe54252d37bb350bc634359b19515542080e4724a4b672291be57c7648f51629eaef234e847d99cc65f":16:"010001":MBEDTLS_MD_SHA512:MBEDTLS_MD_SHA512:MBEDTLS_MD_SHA512:64:"":"a9ad7994ba3a1071124153486924448cc67a5af3a5d34e9261d53770782cc85f58e2edde5f7004652a645e3e9606530eb57de41df7298ae2be9dec69cc0d613ab629":0:MBEDTLS_ERR_RSA_INVALID_PADDING
+
+RSASSA-PSS verify ext, 512-bit key, SHA-512 (hash too large)
+depends_on:MBEDTLS_SHA512_C
+pkcs1_rsassa_pss_verify_ext:512:16:"00b076d23250816f9aab02307e452b97f0cae7598369b41624e8afc7971a59a13892f64b07eaa6ec928c160b2d6ec8f9d0dd5b63c8b3ac0767b4f65c892f56c10f":16:"010001":MBEDTLS_MD_SHA512:MBEDTLS_MD_SHA512:MBEDTLS_MD_SHA512:0:"":"ace8b03347da1b9a7a5e94a0d76359bb39c819bb170bef38ea84995ed653446c0ae87ede434cdf9d0cb2d7bf164cf427892363e6855a1d24d0ce5dd72acaf246":MBEDTLS_ERR_RSA_BAD_INPUT_DATA:MBEDTLS_ERR_RSA_BAD_INPUT_DATA
+
+RSASSA-PSS verify ext, 521-bit key, SHA-512, empty salt, bad signature
+depends_on:MBEDTLS_SHA512_C
+pkcs1_rsassa_pss_verify_ext:521:16:"0131b69860f3cb9bf85ea358fdf2bd2990f1b77a80d6a4fdf817a43dd896bdf7dd26af8ac0237f526e0d33b105c971fdbd4ffa9ece99fc469f31ecf429e8f562c1c3":16:"010001":MBEDTLS_MD_SHA512:MBEDTLS_MD_SHA512:MBEDTLS_MD_SHA512:0:"":"00471794655837da498cbf27242807b40593a353c707eb22fd2cc5a3259e728ac4f1df676043eeec8e16c1175b3d9ac8cae72ec1d5772dd69de71c5677f19031568e":MBEDTLS_ERR_RSA_BAD_INPUT_DATA:MBEDTLS_ERR_RSA_BAD_INPUT_DATA
+
+RSASSA-PSS verify ext, 521-bit key, SHA-256, empty salt, good signature
+depends_on:MBEDTLS_SHA256_C
+pkcs1_rsassa_pss_verify_ext:521:16:"0131b69860f3cb9bf85ea358fdf2bd2990f1b77a80d6a4fdf817a43dd896bdf7dd26af8ac0237f526e0d33b105c971fdbd4ffa9ece99fc469f31ecf429e8f562c1c3":16:"010001":MBEDTLS_MD_SHA256:MBEDTLS_MD_SHA256:MBEDTLS_MD_SHA256:0:"41":"009c4941157fa36288e467310b198ab0c615c40963d611ffeef03000549ded809235955ecc57adba44782e9497c004f480ba2b3d58db8335fe0b391075c02c843a6d":0:0
+
+RSASSA-PSS verify ext, 521-bit key, SHA-256, empty salt, flipped-highest-bit signature
+depends_on:MBEDTLS_SHA256_C
+pkcs1_rsassa_pss_verify_ext:521:16:"0131b69860f3cb9bf85ea358fdf2bd2990f1b77a80d6a4fdf817a43dd896bdf7dd26af8ac0237f526e0d33b105c971fdbd4ffa9ece99fc469f31ecf429e8f562c1c3":16:"010001":MBEDTLS_MD_SHA256:MBEDTLS_MD_SHA256:MBEDTLS_MD_SHA256:0:"41":"00e11a2403df681c44a1f73f014b6c9ad17847d0b673f7c2a801cee208d10ab5792c10cd0cd495a4b331aaa521409fca7cb1b0d978b3a84cd67e28078b98753e9466":MBEDTLS_ERR_RSA_BAD_INPUT_DATA:MBEDTLS_ERR_RSA_BAD_INPUT_DATA
+
+RSASSA-PSS verify ext, all-zero padding, automatic salt length
+depends_on:MBEDTLS_SHA256_C
+pkcs1_rsassa_pss_verify_ext:512:16:"00b076d23250816f9aab02307e452b97f0cae7598369b41624e8afc7971a59a13892f64b07eaa6ec928c160b2d6ec8f9d0dd5b63c8b3ac0767b4f65c892f56c10f":16:"010001":MBEDTLS_MD_NONE:MBEDTLS_MD_SHA256:MBEDTLS_MD_SHA256:MBEDTLS_RSA_SALT_LEN_ANY:"":"63a35294577c7e593170378175b7df27c293dae583ec2a971426eb2d66f2af483e897bfae5dc20300a9d61a3644e08c3aee61a463690a3498901563c46041056":MBEDTLS_ERR_RSA_INVALID_PADDING:MBEDTLS_ERR_RSA_INVALID_PADDING
+
diff --git a/tests/suites/test_suite_shax.function b/tests/suites/test_suite_shax.function
index 6b3ee9c..d704b38 100644
--- a/tests/suites/test_suite_shax.function
+++ b/tests/suites/test_suite_shax.function
@@ -18,7 +18,7 @@
 
     src_len = unhexify( src_str, hex_src_string );
 
-    mbedtls_sha1( src_str, src_len, output );
+    TEST_ASSERT( mbedtls_sha1_ret( src_str, src_len, output ) == 0 );
     hexify( hash_str, output, 20 );
 
     TEST_ASSERT( strcmp( (char *) hash_str, hex_hash_string ) == 0 );
@@ -39,7 +39,7 @@
 
     src_len = unhexify( src_str, hex_src_string );
 
-    mbedtls_sha256( src_str, src_len, output, 1 );
+    TEST_ASSERT( mbedtls_sha256_ret( src_str, src_len, output, 1 ) == 0 );
     hexify( hash_str, output, 28 );
 
     TEST_ASSERT( strcmp( (char *) hash_str, hex_hash_string ) == 0 );
@@ -60,7 +60,7 @@
 
     src_len = unhexify( src_str, hex_src_string );
 
-    mbedtls_sha256( src_str, src_len, output, 0 );
+    TEST_ASSERT( mbedtls_sha256_ret( src_str, src_len, output, 0 ) == 0 );
     hexify( hash_str, output, 32 );
 
     TEST_ASSERT( strcmp( (char *) hash_str, hex_hash_string ) == 0 );
@@ -81,7 +81,7 @@
 
     src_len = unhexify( src_str, hex_src_string );
 
-    mbedtls_sha512( src_str, src_len, output, 1 );
+    TEST_ASSERT( mbedtls_sha512_ret( src_str, src_len, output, 1 ) == 0 );
     hexify( hash_str, output, 48 );
 
     TEST_ASSERT( strcmp( (char *) hash_str, hex_hash_string ) == 0 );
@@ -102,7 +102,7 @@
 
     src_len = unhexify( src_str, hex_src_string );
 
-    mbedtls_sha512( src_str, src_len, output, 0);
+    TEST_ASSERT( mbedtls_sha512_ret( src_str, src_len, output, 0 ) == 0 );
     hexify( hash_str, output, 64 );
 
     TEST_ASSERT( strcmp( (char *) hash_str, hex_hash_string ) == 0 );
diff --git a/tests/suites/test_suite_version.data b/tests/suites/test_suite_version.data
index 1442a38..1aa4ffa 100644
--- a/tests/suites/test_suite_version.data
+++ b/tests/suites/test_suite_version.data
@@ -1,8 +1,8 @@
 Check compiletime library version
-check_compiletime_version:"2.6.0"
+check_compiletime_version:"2.7.0"
 
 Check runtime library version
-check_runtime_version:"2.6.0"
+check_runtime_version:"2.7.0"
 
 Check for MBEDTLS_VERSION_C
 check_feature:"MBEDTLS_VERSION_C":0