Documentation fixes

Move MBEDTLS_ECP_MAX_BYTES to a proper place,
adjust comments and descriptions, move includes
to the top of the file

include/mbedtls/ecdsa.h

@@ -40,6 +40,9 @@
  * (assuming ECP_MAX_BYTES is less than 126 for r and s,
  * and less than 124 (total len <= 255) for the sequence)
  */
+#if MBEDTLS_ECP_MAX_BYTES > 124
+#error "MBEDTLS_ECP_MAX_BYTES bigger than expected, please fix MBEDTLS_ECDSA_MAX_LEN"
+#endif
 
 /**
  * \brief           Maximum ECDSA signature size for a given curve bit size
@@ -52,10 +55,6 @@
  *                  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 ) +     \
@@ -237,8 +236,7 @@ int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx,
 #endif /* MBEDTLS_ECDSA_DETERMINISTIC */
 
 /**
- * \brief           Convert a signature from numbers to ASN.1 INTEGER's,
+ * \brief           Convert a signature from numbers to ASN.1
- *                  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
@@ -250,6 +248,11 @@ int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx,
  *                  `MBEDTLS_ECDSA_MAX_SIG_LEN(grp->pbits)` bytes long if
  *                  the signature was produced from curve \c grp,
  *                  otherwise this function will return an error.
+ *                  The output ASN.1 SEQUENCE format is as follows:
+ *                  Ecdsa-Sig-Value ::= SEQUENCE {
+ *                              r       INTEGER,
+ *                              s       INTEGER
+ *                          }
  *
  * \return          0 if successful,
  *                  or a MBEDTLS_ERR_MPI_XXX or MBEDTLS_ERR_ASN1_XXX error code

include/mbedtls/pk.h

@@ -80,8 +80,11 @@ extern "C" {
 /**@{*/
 
 /**
- * \brief          Asymmetric operation context types
+ * \brief           Asymmetric operation context types
- */
+ *
+ * \note            An opaque key may be an RSA or ECC key or a key of an
+ *                  unrecognized type. Call \c mbedtls_pk_can_do() to check
+ *                  whether a key is of a recognized type. */
 typedef enum {
     MBEDTLS_PK_NONE=0,          /**< Unused context object */
     MBEDTLS_PK_RSA,             /**< RSA key pair (normal software implementation) with PKCS#1 v1.5 or PSS context */
@@ -90,10 +93,7 @@ typedef enum {
     MBEDTLS_PK_ECDSA,           /**< ECC key pair with ECDSA context */
     MBEDTLS_PK_RSA_ALT,         /**< RSA (alternative implementation) */
     MBEDTLS_PK_RSASSA_PSS,      /**< RSA key pair; same context as MBEDTLS_PK_RSA, but used to represent keys with the algorithm identifier id-RSASSA-PSS */
-    /** Opaque key pair (cryptographic material held in an external module).
+    MBEDTLS_PK_OPAQUE,          /**< Opaque key pair (cryptographic material held in an external module).*/
-     * This may be an RSA or ECC key or a key of an unrecognized type. Call
-     * \c mbedtls_pk_can_do() to check whether a key is of a recognized type. */
-    MBEDTLS_PK_OPAQUE,
 } mbedtls_pk_type_t;
 
 /**

library/ecp.c

@@ -51,6 +51,11 @@
 #include "mbedtls/ecp.h"
 #include "mbedtls/threading.h"
 
+#if defined(MBEDTLS_ASN1_WRITE_C) && defined(MBEDTLS_OID_C)
+#include "mbedtls/asn1write.h"
+#include "mbedtls/oid.h"
+#endif
+
 #include <string.h>
 
 #if !defined(MBEDTLS_ECP_ALT)
@@ -2062,8 +2067,6 @@ cleanup:
 }
 
 #if defined(MBEDTLS_ASN1_WRITE_C) && defined(MBEDTLS_OID_C)
-#include "mbedtls/asn1write.h"
-#include "mbedtls/oid.h"
 int mbedtls_ecp_ansi_write_group( const mbedtls_ecp_group *grp,
                                   unsigned char *p,
                                   size_t size, size_t *olen )