Merge branch 'development' into development-restricted

Author: yanesca

README.md

@@ -6,9 +6,9 @@ Mbed Crypto is distributed under the Apache License, version 2.0. See the [LICEN
 
 ## PSA cryptography API
 
-Arm's Platform Security Architecture (PSA) is a holistic set of threat models, security analyses, hardware and firmware architecture specifications, and an open source firmware reference implementation. PSA provides a recipe, based on industry best practice, that allows security to be consistently designed in, at both a hardware and firmware level.
+Arm's [Platform Security Architecture (PSA)](https://developer.arm.com/architectures/security-architectures/platform-security-architecture) is a holistic set of threat models, security analyses, hardware and firmware architecture specifications, and an open source firmware reference implementation. PSA provides a recipe, based on industry best practice, that allows security to be consistently designed in, at both a hardware and firmware level.
 
-The PSA cryptography API provides access to a set of cryptographic primitives. It has a dual purpose. First, it can be used in a PSA-compliant platform to build services, such as secure boot, secure storage and secure communication. Second, it can also be used independently of other PSA components on any platform.
+The [PSA cryptography API](https://armmbed.github.io/mbed-crypto/psa/#application-programming-interface) provides access to a set of cryptographic primitives. It has a dual purpose. First, it can be used in a PSA-compliant platform to build services, such as secure boot, secure storage and secure communication. Second, it can also be used independently of other PSA components on any platform.
 
 The design goals of the PSA cryptography API include:
 
@@ -24,17 +24,17 @@ Mbed Crypto is a reference implementation of the PSA cryptography API. It is wri
 
 ## Documentation
 
-The Mbed Crypto library is a reference implementation of the PSA cryptography API. Please refer to the PSA Cryptography API documents for an overview of the library's interfaces and a detailed description of the types, macros and functions that it provides.
+The Mbed Crypto library implements both the legacy Mbed TLS interfaces to cryptographic primitives (`mbedtls_xxx`) and the new PSA Cryptography interfaces (`psa_xxx`).
 
-There are currently a few deviations where the library does not yet implement the latest version of the specification. Please refer to the [compliance issues on Github](https://github.com/ARMmbed/mbed-crypto/labels/compliance) for an up-to-date list.
+Documentation for the Mbed TLS interfaces in the default library configuration is available as part of the [Mbed TLS documentation](https://tls.mbed.org/api/).
 
-### PSA Cryptography API
+For the PSA interfaces, please refer to the PSA Cryptography API documents linked from the [PSA cryptography interfaces documentation portal](https://armmbed.github.io/mbed-crypto/psa/#application-programming-interface) for an overview of the library's interfaces and a detailed description of the types, macros and functions that it provides. The API reference is available in [PDF](https://armmbed.github.io/mbed-crypto/PSA_Cryptography_API_Specification.pdf) and [HTML](https://armmbed.github.io/mbed-crypto/html/index.html) formats.
 
-You can read the [complete PSA cryptography API specification as a PDF document](https://github.com/ARMmbed/mbed-crypto/raw/psa-crypto-api/docs/PSA_Cryptography_API_Specification.pdf). The API reference is also available in [HTML format](https://armmbed.github.io/mbed-crypto/html/index.html).
+There are currently a few deviations where the library does not yet implement the latest version of the specification. Please refer to the [compliance issues on Github](https://github.com/ARMmbed/mbed-crypto/labels/compliance) for an up-to-date list.
 
 ### Browsable library documentation
 
-To generate a local copy of the library documentation in HTML format:
+To generate a local copy of the library documentation in HTML format, tailored to your compile-time configuration:
 
 1. Make sure that [Doxygen](http://www.doxygen.nl/) is installed. We use version 1.8.11 but slightly older or more recent versions should work.
 1. Run `make apidoc`.

docs/getting_started.md

@@ -119,8 +119,8 @@ Mbed Crypto supports encrypting, decrypting, signing and verifying messages usin
 **Prerequisites to performing asymmetric signature operations:**
 * Initialize the library with a successful call to `psa_crypto_init()`.
 * Have a valid key with appropriate attributes set:
-    * Usage flag `PSA_KEY_USAGE_SIGN` to allow signing.
-    * Usage flag `PSA_KEY_USAGE_VERIFY` to allow signature verification.
+    * Usage flag `PSA_KEY_USAGE_SIGN_HASH` to allow signing.
+    * Usage flag `PSA_KEY_USAGE_VERIFY_HASH` to allow signature verification.
     * Algorithm set to the desired signature algorithm.
 
 This example shows how to sign a hash that has already been calculated:
@@ -133,7 +133,7 @@ void sign_a_message_using_rsa(const uint8_t *key, size_t key_len)
                         0x60, 0x41, 0x8a, 0xaf, 0x0c, 0xc5, 0xab, 0x58,
                         0x7f, 0x42, 0xc2, 0x57, 0x0a, 0x88, 0x40, 0x95,
                         0xa9, 0xe8, 0xcc, 0xac, 0xd0, 0xf6, 0x54, 0x5c};
-    uint8_t signature[PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE] = {0};
+    uint8_t signature[PSA_SIGNATURE_MAX_SIZE] = {0};
     size_t signature_length;
     psa_key_handle_t handle;
 
@@ -148,7 +148,7 @@ void sign_a_message_using_rsa(const uint8_t *key, size_t key_len)
     }
 
     /* Set key attributes */
-    psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_SIGN);
+    psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_SIGN_HASH);
     psa_set_key_algorithm(&attributes, PSA_ALG_RSA_PKCS1V15_SIGN_RAW);
     psa_set_key_type(&attributes, PSA_KEY_TYPE_RSA_KEY_PAIR);
     psa_set_key_bits(&attributes, 1024);
@@ -161,10 +161,10 @@ void sign_a_message_using_rsa(const uint8_t *key, size_t key_len)
     }
 
     /* Sign message using the key */
-    status = psa_asymmetric_sign(handle, PSA_ALG_RSA_PKCS1V15_SIGN_RAW,
-                                 hash, sizeof(hash),
-                                 signature, sizeof(signature),
-                                 &signature_length);
+    status = psa_sign_hash(handle, PSA_ALG_RSA_PKCS1V15_SIGN_RAW,
+                           hash, sizeof(hash),
+                           signature, sizeof(signature),
+                           &signature_length);
     if (status != PSA_SUCCESS) {
         printf("Failed to sign\n");
         return;
@@ -861,7 +861,7 @@ Mbed Crypto provides a simple way to generate a key or key pair.
     }
 
     /* Generate a key */
-    psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_SIGN);
+    psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_SIGN_HASH);
     psa_set_key_algorithm(&attributes,
                           PSA_ALG_DETERMINISTIC_ECDSA(PSA_ALG_SHA_256));
     psa_set_key_type(&attributes,

include/mbedtls/asn1.h

@@ -75,6 +75,7 @@
 #define MBEDTLS_ASN1_OCTET_STRING            0x04
 #define MBEDTLS_ASN1_NULL                    0x05
 #define MBEDTLS_ASN1_OID                     0x06
+#define MBEDTLS_ASN1_ENUMERATED              0x0A
 #define MBEDTLS_ASN1_UTF8_STRING             0x0C
 #define MBEDTLS_ASN1_SEQUENCE                0x10
 #define MBEDTLS_ASN1_SET                     0x11
@@ -254,13 +255,32 @@ int mbedtls_asn1_get_bool( unsigned char **p,
  *              a valid ASN.1 INTEGER.
  * \return      #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the parsed value does
  *              not fit in an \c int.
- * \return      An ASN.1 error code if the input does not start with
- *              a valid ASN.1 INTEGER.
  */
 int mbedtls_asn1_get_int( unsigned char **p,
                           const unsigned char *end,
                           int *val );
 
+/**
+ * \brief       Retrieve an enumerated ASN.1 tag and its value.
+ *              Updates the pointer to immediately behind the full tag.
+ *
+ * \param p     On entry, \c *p points to the start of the ASN.1 element.
+ *              On successful completion, \c *p points to the first byte
+ *              beyond the ASN.1 element.
+ *              On error, the value of \c *p is undefined.
+ * \param end   End of data.
+ * \param val   On success, the parsed value.
+ *
+ * \return      0 if successful.
+ * \return      An ASN.1 error code if the input does not start with
+ *              a valid ASN.1 ENUMERATED.
+ * \return      #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the parsed value does
+ *              not fit in an \c int.
+ */
+int mbedtls_asn1_get_enum( unsigned char **p,
+                           const unsigned char *end,
+                           int *val );
+
 /**
  * \brief       Retrieve a bitstring ASN.1 tag and its value.
  *              Updates the pointer to immediately behind the full tag.
@@ -367,8 +387,6 @@ int mbedtls_asn1_get_sequence_of( unsigned char **p,
  * \return      #MBEDTLS_ERR_ASN1_INVALID_LENGTH if the parsed value does
  *              not fit in an \c int.
  * \return      An MPI error code if the parsed value is too large.
- * \return      An ASN.1 error code if the input does not start with
- *              a valid ASN.1 INTEGER.
  */
 int mbedtls_asn1_get_mpi( unsigned char **p,
                           const unsigned char *end,

include/mbedtls/asn1write.h

@@ -192,6 +192,21 @@ int mbedtls_asn1_write_bool( unsigned char **p, unsigned char *start,
  */
 int mbedtls_asn1_write_int( unsigned char **p, unsigned char *start, int val );
 
+/**
+ * \brief           Write an enum tag (#MBEDTLS_ASN1_ENUMERATED) and value
+ *                  in ASN.1 format.
+ *
+ * \note            This function works backwards in data buffer.
+ *
+ * \param p         The reference to the current position pointer.
+ * \param start     The start of the buffer, for bounds-checking.
+ * \param val       The integer value to write.
+ *
+ * \return          The number of bytes written to \p p on success.
+ * \return          A negative \c MBEDTLS_ERR_ASN1_XXX error code on failure.
+ */
+int mbedtls_asn1_write_enum( unsigned char **p, unsigned char *start, int val );
+
 /**
  * \brief           Write a string in ASN.1 format using a specific
  *                  string encoding tag.

include/mbedtls/ctr_drbg.h

@@ -177,7 +177,9 @@ typedef struct mbedtls_ctr_drbg_context
                                  * minus one.
                                  * Before the initial seeding, this field
                                  * contains the amount of entropy in bytes
-                                 * to use as a nonce for the initial seeding.
+                                 * to use as a nonce for the initial seeding,
+                                 * or -1 if no nonce length has been explicitly
+                                 * set (see mbedtls_ctr_drbg_set_nonce_len()).
                                  */
     int prediction_resistance;  /*!< This determines whether prediction
                                      resistance is enabled, that is

include/mbedtls/error.h

@@ -52,9 +52,10 @@
  * For historical reasons, low-level error codes are divided in even and odd,
  * even codes were assigned first, and -1 is reserved for other errors.
  *
- * Low-level module errors (0x0002-0x007E, 0x0003-0x007F)
+ * Low-level module errors (0x0002-0x007E, 0x0001-0x007F)
  *
  * Module   Nr  Codes assigned
+ * ERROR     2         0x006E   0x0001
  * MPI       7  0x0002-0x0010
  * GCM       3  0x0012-0x0014   0x0013-0x0013
  * BLOWFISH  3  0x0016-0x0018   0x0017-0x0017
@@ -86,7 +87,7 @@
  * CHACHA20  3                  0x0051-0x0055
  * POLY1305  3                  0x0057-0x005B
  * CHACHAPOLY 2 0x0054-0x0056
- * PLATFORM  1  0x0070-0x0072
+ * PLATFORM  2  0x0070-0x0072
  *
  * High-level module nr (3 bits - 0x0...-0x7...)
  * Name      ID  Nr of Errors
@@ -112,6 +113,9 @@
 extern "C" {
 #endif
 
+#define MBEDTLS_ERR_ERROR_GENERIC_ERROR       -0x0001  /**< Generic error */
+#define MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED -0x006E  /**< This is a bug in the library */
+
 /**
  * \brief Translate a mbed TLS error code into a string representation,
  *        Result is truncated if necessary and always includes a terminating

include/mbedtls/pk.h

@@ -134,11 +134,11 @@ typedef struct mbedtls_pk_rsassa_pss_options
 #endif
 
 #if defined(MBEDTLS_USE_PSA_CRYPTO)
-#if PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE > MBEDTLS_PK_SIGNATURE_MAX_SIZE
-/* PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE is the maximum size of a signature made
+#if PSA_SIGNATURE_MAX_SIZE > MBEDTLS_PK_SIGNATURE_MAX_SIZE
+/* PSA_SIGNATURE_MAX_SIZE is the maximum size of a signature made
  * through the PSA API in the PSA representation. */
 #undef MBEDTLS_PK_SIGNATURE_MAX_SIZE
-#define MBEDTLS_PK_SIGNATURE_MAX_SIZE PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE
+#define MBEDTLS_PK_SIGNATURE_MAX_SIZE PSA_SIGNATURE_MAX_SIZE
 #endif
 
 #if PSA_VENDOR_ECDSA_SIGNATURE_MAX_SIZE + 11 > MBEDTLS_PK_SIGNATURE_MAX_SIZE

include/mbedtls/psa_util.h

@@ -378,24 +378,6 @@ static inline psa_ecc_curve_t mbedtls_psa_translate_ecc_group( mbedtls_ecp_group
     }
 }
 
-
-#define MBEDTLS_PSA_ECC_KEY_BITS_OF_CURVE( curve )                \
-    ( curve == PSA_ECC_CURVE_SECP192R1        ? 192 :             \
-      curve == PSA_ECC_CURVE_SECP224R1        ? 224 :             \
-      curve == PSA_ECC_CURVE_SECP256R1        ? 256 :             \
-      curve == PSA_ECC_CURVE_SECP384R1        ? 384 :             \
-      curve == PSA_ECC_CURVE_SECP521R1        ? 521 :             \
-      curve == PSA_ECC_CURVE_SECP192K1        ? 192 :             \
-      curve == PSA_ECC_CURVE_SECP224K1        ? 224 :             \
-      curve == PSA_ECC_CURVE_SECP256K1        ? 256 :             \
-      curve == PSA_ECC_CURVE_BRAINPOOL_P256R1 ? 256 :             \
-      curve == PSA_ECC_CURVE_BRAINPOOL_P384R1 ? 384 :             \
-      curve == PSA_ECC_CURVE_BRAINPOOL_P512R1 ? 512 :             \
-      0 )
-
-#define MBEDTLS_PSA_ECC_KEY_BYTES_OF_CURVE( curve )                \
-    ( ( MBEDTLS_PSA_ECC_KEY_BITS_OF_CURVE( curve ) + 7 ) / 8 )
-
 /* Translations for PK layer */
 
 static inline int mbedtls_psa_err_translate_pk( psa_status_t status )

include/psa/crypto.h

@@ -2879,7 +2879,7 @@ psa_status_t psa_aead_abort(psa_aead_operation_t *operation);
  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
  *         The size of the \p signature buffer is too small. You can
  *         determine a sufficient buffer size by calling
- *         #PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
+ *         #PSA_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
  *         where \c key_type and \c key_bits are the type and bit-size
  *         respectively of \p handle.
  * \retval #PSA_ERROR_NOT_SUPPORTED
@@ -2895,13 +2895,13 @@ psa_status_t psa_aead_abort(psa_aead_operation_t *operation);
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.
  */
-psa_status_t psa_asymmetric_sign(psa_key_handle_t handle,
-                                 psa_algorithm_t alg,
-                                 const uint8_t *hash,
-                                 size_t hash_length,
-                                 uint8_t *signature,
-                                 size_t signature_size,
-                                 size_t *signature_length);
+psa_status_t psa_sign_hash(psa_key_handle_t handle,
+                           psa_algorithm_t alg,
+                           const uint8_t *hash,
+                           size_t hash_length,
+                           uint8_t *signature,
+                           size_t signature_size,
+                           size_t *signature_length);
 
 /**
  * \brief Verify the signature a hash or short message using a public key.
@@ -2941,12 +2941,12 @@ psa_status_t psa_asymmetric_sign(psa_key_handle_t handle,
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.
  */
-psa_status_t psa_asymmetric_verify(psa_key_handle_t handle,
-                                   psa_algorithm_t alg,
-                                   const uint8_t *hash,
-                                   size_t hash_length,
-                                   const uint8_t *signature,
-                                   size_t signature_length);
+psa_status_t psa_verify_hash(psa_key_handle_t handle,
+                             psa_algorithm_t alg,
+                             const uint8_t *hash,
+                             size_t hash_length,
+                             const uint8_t *signature,
+                             size_t signature_length);
 
 /**
  * \brief Encrypt a short message with a public key.