diff --git a/include/mbedtls/ecdsa.h b/include/mbedtls/ecdsa.h
index c0088db..7490c65 100644
--- a/include/mbedtls/ecdsa.h
+++ b/include/mbedtls/ecdsa.h
@@ -52,6 +52,10 @@
  *                  this is a problem, call the function
  *                  mbedtls_ecdsa_max_sig_len instead.
  */
+#if MBEDTLS_ECP_MAX_BYTES > 124
+#error "MBEDTLS_ECP_MAX_BYTES bigger than expected, please fix MBEDTLS_ECDSA_MAX_LEN"
+#endif
+
 #define MBEDTLS_ECDSA_MAX_SIG_LEN( bits )                               \
     ( /*T,L of SEQUENCE*/ ( ( bits ) >= 61 * 8 ? 3 : 2 ) +              \
       /*T,L of r,s*/        2 * ( ( ( bits ) >= 127 * 8 ? 3 : 2 ) +     \
@@ -71,12 +75,9 @@
     return( MBEDTLS_ECDSA_MAX_SIG_LEN( bits ) );
 }
 
-#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 */
-#define MBEDTLS_ECDSA_MAX_LEN  ( 3 + 2 * ( 3 + MBEDTLS_ECP_MAX_BYTES ) )
-
+#define MBEDTLS_ECDSA_MAX_LEN (MBEDTLS_ECDSA_MAX_SIG_LEN( \
+        8 * MBEDTLS_ECP_MAX_BYTES ) )
 /**
  * \brief           ECDSA context structure
  */
@@ -236,7 +237,8 @@
 #endif /* MBEDTLS_ECDSA_DETERMINISTIC */
 
 /**
- * \brief           Convert a signature from numbers to ASN.1
+ * \brief           Convert a signature from numbers to ASN.1 INTEGER's,
+ *                  then both packed together as parts of an ASN.1 SEQUENCE
  *
  * \param r         First number of the signature
  * \param s         Second number of the signature
diff --git a/include/mbedtls/pk.h b/include/mbedtls/pk.h
index c6bb7c4..f7fa4d3 100644
--- a/include/mbedtls/pk.h
+++ b/include/mbedtls/pk.h
@@ -3,7 +3,7 @@
  *
  * \brief Public Key cryptography abstraction layer
  *
- *  Copyright (C) 2006-2017, ARM Limited, All Rights Reserved
+ *  Copyright (C) 2006-2018, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
@@ -169,7 +169,7 @@
 mbedtls_pk_type_t mbedtls_pk_get_type( const mbedtls_pk_context *ctx );
 
 /**
- * \brief           Merge key types with the same representation
+ * \brief           Get the representation type associated with a given type
  *
  * \param type      Any key type
  * \return          A canonical representative among the types with the
@@ -200,10 +200,10 @@
 /**
  * Quick access to an RSA context inside a PK context.
  *
- * \warning You must make sure the PK context actually holds a transparent
- * RSA context before using this function! This function is only valid if
- * `mbedtls_pk_get_type(&pk)` is one of \c MBEDTLS_PK_RSA or
- * \c MBEDTLS_PK_RSASSA_PSS.
+ * \warning You must either make sure the PK context actually holds a
+ * transparent RSA context by checking
+ * \c mbedtls_pk_representation_type( mbedtls_pk_get_type( &pk ) ) before using
+ * this function, or check that the return value is not NULL before using it.
  */
 static inline mbedtls_rsa_context *mbedtls_pk_rsa( const mbedtls_pk_context pk )
 {
@@ -220,10 +220,10 @@
 /**
  * Quick access to an EC context inside a PK context.
  *
- * \warning You must make sure the PK context actually holds a transparent
- * EC context before using this function! This function is only valid if
- * `mbedtls_pk_get_type(&pk)` is one of \c MBEDTLS_PK_ECKEY,
- * \c MBEDTLS_PK_ECKEY_DH or \c MBEDTLS_PK_ECDSA.
+ * \warning You must either make sure the PK context actually holds a
+ * transparent RSA context by checking
+ * \c mbedtls_pk_representation_type( mbedtls_pk_get_type( &pk ) ) before using
+ * this function, or check that the return value is not NULL before using it.
  */
 static inline mbedtls_ecp_keypair *mbedtls_pk_ec( const mbedtls_pk_context pk )
 {
@@ -287,11 +287,15 @@
  *                  MBEDTLS_ERR_PK_BAD_INPUT_DATA on invalid input,
  *                  MBEDTLS_ERR_PK_ALLOC_FAILED on allocation failure.
  *
- * \note            Engines that implement of opaque keys may offer an
+ * \note            Engines that implement opaque keys may offer an
  *                  alternative setup function that take engine-dependent
  *                  parameters. If such a function exists, call it
- *                  instead of mbedtls_pk_setup. The implementation-specific
- *                  setup function should call mbedtls_pk_setup internally.
+ *                  instead of mbedtls_pk_setup. A standard way of providing
+ *                  such function is by first calling the generic
+ *                  mbedtls_pk_setup function (in particular taking care of
+ *                  context allocation through ctx_alloc) and afterwards
+ *                  proceeding to initialize the implementation-specific
+ *                  context structure.
  *
  * \note            For contexts holding an RSA-alt key pair, use
  *                  \c mbedtls_pk_setup_rsa_alt() instead.
@@ -436,17 +440,18 @@
  * \param hash      Hash of the message to sign
  * \param hash_len  Hash length or 0 (see notes)
  * \param sig       Place to write the signature
- * \param sig_len   Number of bytes written to sig
+ * \param sig_len   Actual length in bytes of the created signature
  * \param f_rng     RNG function
  * \param p_rng     RNG parameter
  *
  * \return          0 on success, or a type-specific error code.
  *
  * \note            The signature buffer \c sig must be of appropriate size
- *                  which can be calculated with \c mbedtls_pk_signature_size.
+ *                  which can be calculated with
+ *                  \c mbedtls_pk_get_signature_size.
  *                  Depending on the algorithm, the value returned in
  *                  \c sig_len may be less or equal to the value returned by
- *                  \c mbedtls_pk_signature_size.
+ *                  \c mbedtls_pk_get_signature_size.
  *
  * \note            For RSA keys, the default padding type is PKCS#1 v1.5.
  *                  There is no interface in the PK module to make RSASSA-PSS
@@ -526,11 +531,12 @@
  *                  * MBEDTLS_ERR_PK_TYPE_MISMATCH if the contexts cannot
  *                    represent keys of the same type.
  *                  * MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE if it is impossible
- *                    to determine whether the keys match. This is guaranteed
- *                    not to happen if \c prv is a transparent key pair.
+ *                    to determine whether the keys match. This can only happen
+ *                    if \c prv is an opaque key.
  *                  * Or a type-specific error code.
  *
- * \note            Opaque key types may not implement this function.
+ * \note            Opaque key types may omit implementing this function
+ *                  by providing a NULL pointer in the mbedtls_pk_info_t structure.
  *                  An opaque \c pub never matches a transparent \c prv.
  */
 int mbedtls_pk_check_pair( const mbedtls_pk_context *pub, const mbedtls_pk_context *prv );
diff --git a/include/mbedtls/pk_info.h b/include/mbedtls/pk_info.h
index a808c2c..d1d95ef 100644
--- a/include/mbedtls/pk_info.h
+++ b/include/mbedtls/pk_info.h
@@ -3,7 +3,10 @@
  *
  * \brief Public Key cryptography abstraction layer: object interface
  *
- *  Copyright (C) 2006-2017, ARM Limited, All Rights Reserved
+ *  This file contains the info structure interface used by developers to
+ *  provide engine-specific implementations of opaque key handling functions.
+ *
+ *  Copyright (C) 2006-2018, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
@@ -40,10 +43,16 @@
  * Methods that opaque key pair objects must implement.
  *
  * Engines that interface with external cryptographic processors must
- * implement this interface. Platform-specific hardware accelerators
- * that can be used for all keys of a given type should use alternative
- * ("xxx_alt") interfaces instead. This interface allows using different
- * engines for each key.
+ * implement this interface. It allows using different engines for each key.
+ * Platform-specific hardware accelerators that can be used for all keys of
+ * a given type should not use this interface, but rather provide an
+ * alternative implementation of the respective cryptographic module - for
+ * example to use an RSA accelerator you can define MBEDTLS_RSA_ALT, and
+ * provide your own implementation of the RSA module.
+ *
+ * \warning: If you are using the PK interface to perform operations on
+ * keys, call the functions in pk.h. The interface in this file should only
+ * be used by implementers of opaque key engines.
  *
  * An engine for asymmetric cryptography must implement the interface
  * described in this structure. The interface for the engine may be
@@ -68,14 +77,11 @@
  * in the corresponding field. The corresponding function in pk.h will
  * return MBEDTLS_ERR_PK_TYPE_MISMATCH in this case.
  *
- * \note If you are using the PK interface to perform operations on
- * keys, call the functions in pk.h. The interface in this file should only
- * be used by implementers of opaque key engines.
  *
  * \warning: Do not declare this structure directly! It may be extended in
  * future* versions of Mbed TLS. Call the macro
- * MBEDTLS_PK_OPAQUE_INFO_1() or MBEDTLS_PK_OPAQUE_INFO_ASYNC_1() instead.
- * These macros are guaranteed to take parameters with the same type
+ * MBEDTLS_PK_OPAQUE_INFO_1() instead.
+ * This macro is guaranteed to take parameters with the same type
  * and semantics as previous versions and fill any new field of the
  * structure with sensible values.
  */
@@ -105,7 +111,8 @@
      * This function cannot fail. */
     size_t (*get_bitlen)( const void *ctx );
 
-    /** Tell if the context implements this type (e.g.\ ECKEY can do ECDSA).
+    /** Tell if the context implements the algorithm specified by
+     * the provided type (e.g.\ ECKEY can do ECDSA).
      *
      * mbedtls_pk_can_do() calls this function.
      *
diff --git a/include/mbedtls/pk_internal.h b/include/mbedtls/pk_internal.h
index 06475e9..0a33087 100644
--- a/include/mbedtls/pk_internal.h
+++ b/include/mbedtls/pk_internal.h
@@ -3,7 +3,10 @@
  *
  * \brief Public Key cryptography abstraction layer: built-in key types
  *
- *  Copyright (C) 2006-2017, ARM Limited, All Rights Reserved
+ *  This file contains built-in types for handling various key types using
+ *  the interface defined in pk_info.h.
+ *
+ *  Copyright (C) 2006-2018, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
  *  Licensed under the Apache License, Version 2.0 (the "License"); you may