From 031d6335b7e762cb8ae8dd7fb44e04a22235f978 Mon Sep 17 00:00:00 2001
From: Hanno Becker <hanno.becker@arm.com>
Date: Wed, 1 May 2019 17:09:11 +0100
Subject: [PATCH 01/77] Fix mpi_bigendian_to_host() on bigendian systems

The previous implementation of mpi_bigendian_to_host() did
a byte-swapping regardless of the endianness of the system.

Fixes #2622.
---
 library/bignum.c | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/library/bignum.c b/library/bignum.c
index 98ee12a71..b5e022ac7 100644
--- a/library/bignum.c
+++ b/library/bignum.c
@@ -742,10 +742,15 @@ int mbedtls_mpi_write_file( const char *p, const mbedtls_mpi *X, int radix, FILE
 static mbedtls_mpi_uint mpi_uint_bigendian_to_host_c( mbedtls_mpi_uint x )
 {
     uint8_t i;
+    unsigned char *x_ptr;
     mbedtls_mpi_uint tmp = 0;
-    /* This works regardless of the endianness. */
-    for( i = 0; i < ciL; i++, x >>= 8 )
-        tmp |= ( x & 0xFF ) << ( ( ciL - 1 - i ) << 3 );
+
+    for( i = 0, x_ptr = (unsigned char*) &x; i < ciL; i++, x_ptr++ )
+    {
+        tmp <<= CHAR_BIT;
+        tmp |= (mbedtls_mpi_uint) *x_ptr;
+    }
+
     return( tmp );
 }
 

From 5f9aa2be7d20cc8248b3d8e115213ffe2e6ea638 Mon Sep 17 00:00:00 2001
From: Hanno Becker <hanno.becker@arm.com>
Date: Thu, 2 May 2019 09:33:56 +0100
Subject: [PATCH 02/77] Adapt ChangeLog

---
 ChangeLog | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/ChangeLog b/ChangeLog
index 58ff14734..e429caf8e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -33,6 +33,9 @@ Bugfix
      for the parameter.
    * Add a check for MBEDTLS_X509_CRL_PARSE_C in ssl_server2, guarding the crl
      sni entry parameter. Reported by inestlerode in #560.
+   * Fix bug in endianness conversion in bignum module. This lead to
+     functionally incorrect code on bigendian systems which don't have
+     __BYTE_ORDER__ defined. Reported by Brendan Shanks. Fixes #2622.
 
 Changes
    * Server's RSA certificate in certs.c was SHA-1 signed. In the default

From c03c0fcd9392a0119798b7fa344d32408bc55894 Mon Sep 17 00:00:00 2001
From: Guy Wild <guy.wild@arm.com>
Date: Tue, 3 Sep 2019 13:18:04 +0300
Subject: [PATCH 03/77] Update getting_started.md

---
 docs/getting_started.md | 188 ++++++++++++++++++++--------------------
 1 file changed, 93 insertions(+), 95 deletions(-)

diff --git a/docs/getting_started.md b/docs/getting_started.md
index 4d380e088..3097a1ae9 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -18,7 +18,7 @@ The Mbed Crypto library is distributed under the Apache License, version 2.0.
 #### Platform Security Architecture (PSA)
 
 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. Part of the API provided by PSA is the cryptography interface, which provides access to a set of primitives.
+security analyses, hardware and firmware architecture specifications, and an open source firmware reference implementation. PSA provides a recipe, based on industry best practice, that enables you to design security into both hardware and firmware consistently. Part of the API provided by PSA is the cryptography interface, which provides access to a set of primitives.
 
 ### Using Mbed Crypto
 
@@ -37,19 +37,19 @@ security analyses, hardware and firmware architecture specifications, and an ope
 
 ### Getting the Mbed Crypto library
 
-Mbed Crypto releases are available in the [public Github repository]( https://github.com/ARMmbed/mbed-crypto).
+Mbed Crypto releases are available in the [public GitHub repository](https://github.com/ARMmbed/mbed-crypto).
 
 ### Building the Mbed Crypto library
 
-You need the following tools to build the library with the provided makefiles:
+**Prerequisites to building the library with the provided makefiles:**
 * GNU Make.
 * A C toolchain (compiler, linker, archiver).
 * Python 2 or Python 3 (either works) to generate the test code.
 * Perl to run the tests.
 
-If you have a C compiler such as GCC or Clang, just run `make` in the top-level directory to build the library, a set of unit tests and some sample programs.
+If you have a C compiler, such as GCC or Clang, just run `make` in the top-level directory to build the library, a set of unit tests and some sample programs.
 
-To select a different compiler, set the `CC` variable to name or path of the compiler and linker (default: `cc`) and set `AR` to a compatible archiver (default: `ar`), such as:
+To select a different compiler, set the `CC` variable to the name or path of the compiler and linker (default: `cc`) and set `AR` to a compatible archiver (default: `ar`); for example:
 ```
 make CC=arm-linux-gnueabi-gcc AR=arm-linux-gnueabi-ar
 ```
@@ -64,13 +64,13 @@ To use the Mbed Crypto APIs, call `psa_crypto_init()` before calling any other A
 ### Importing a key
 
 To use a key for cryptography operations in Mbed Crypto, you need to first
-import it. Upon importing, you'll be given a handle to refer to the key for use
+import it. After you import the key, you'll be given a handle that refers to the key for use
 with other function calls.
 
-Prerequisites for importing keys:
-* Initialize the library with a successful call to `psa_crypto_init`.
+**Prerequisites for importing keys:**
+* Initialize the library with a successful call to `psa_crypto_init()`.
 
-Importing a key:
+This example shows how to import a key:
 ```C
     psa_status_t status;
     psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
@@ -112,18 +112,16 @@ Importing a key:
 
 ### Signing a message using RSA
 
-Mbed Crypto provides support for encrypting, decrypting, signing and verifying messages using public key signature algorithms (such as RSA or ECDSA).
+Mbed Crypto supports encrypting, decrypting, signing and verifying messages using public key signature algorithms, such as RSA or ECDSA.
 
-Prerequisites for performing asymmetric signature operations:
-* Initialize the library with a successful call to `psa_crypto_init`.
+**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.
-    * Algorithm set to desired signature algorithm.
+    * Algorithm set to the desired signature algorithm.
 
-To sign a given `hash` using RSA:
-1. Call `psa_asymmetric_sign()` and get the output buffer that contains the
-   signature:
+This example shows how to sign a given hash using RSA, call `psa_asymmetric_sign()` and get the output buffer that contains the signature:
 ```C
     psa_status_t status;
     psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
@@ -179,21 +177,21 @@ To sign a given `hash` using RSA:
 
 ### Using symmetric ciphers
 
-Mbed Crypto provides support for encrypting and decrypting messages using various symmetric cipher algorithms (both block and stream ciphers).
+Mbed Crypto supports encrypting and decrypting messages using various symmetric cipher algorithms (both block and stream ciphers).
 
-Prerequisites to working with the symmetric cipher API:
-* Initialize the library with a successful call to `psa_crypto_init`.
-* Configure the key policy accordingly (`PSA_KEY_USAGE_ENCRYPT` to allow encryption or `PSA_KEY_USAGE_DECRYPT` to allow decryption).
+**Prerequisites to working with the symmetric cipher API:**
+* Initialize the library with a successful call to `psa_crypto_init()`.
+* Configure the key policy accordingly (set `PSA_KEY_USAGE_ENCRYPT` to allow encryption or `PSA_KEY_USAGE_DECRYPT` to allow decryption).
 * Have a valid key in the key slot.
 
-Encrypting a message with a symmetric cipher:
+**To encrypt a message with a symmetric cipher:**
 1. Allocate an operation (`psa_cipher_operation_t`) structure to pass to the cipher functions.
-1. Call `psa_cipher_encrypt_setup` to initialize the operation structure and  specify the algorithm and the key to be used.
-1. Call either `psa_cipher_generate_iv` or `psa_cipher_set_iv` to generate or set the initialization vector (IV). We recommended `psa_cipher_generate_iv`, unless you require a specific IV value.
-1. Call `psa_cipher_update` one or more times, passing either the whole or only a fragment of the message each time.
-1. Call `psa_cipher_finish` to end the operation and output the encrypted message.
+1. Call `psa_cipher_encrypt_setup()` to initialize the operation structure and specify the algorithm and the key to be used.
+1. Call either `psa_cipher_generate_iv()` or `psa_cipher_set_iv()` to generate or set the initialization vector (IV). We recommended calling `psa_cipher_generate_iv()`, unless you require a specific IV value.
+1. Call `psa_cipher_update()` one or more times, passing the whole message or only a fragment of the message each time.
+1. Call `psa_cipher_finish()` to end the operation and output the encrypted message.
 
-Encrypting data using an AES key in cipher block chain (CBC) mode with no padding (assuming all prerequisites have been fulfilled):
+This example shows how to encrypt data using an Advanced Encryption Standard (AES) key in cipher block chain (CBC) mode with no padding (assuming all prerequisites have been fulfilled):
 ```c
     enum {
         block_size = PSA_BLOCK_CIPHER_BLOCK_SIZE(PSA_KEY_TYPE_AES),
@@ -267,14 +265,14 @@ Encrypting data using an AES key in cipher block chain (CBC) mode with no paddin
     mbedtls_psa_crypto_free();
 ```
 
-Decrypting a message with a symmetric cipher:
+**To decrypt a message with a symmetric cipher:**
 1. Allocate an operation (`psa_cipher_operation_t`) structure to pass to the cipher functions.
-1. Call `psa_cipher_decrypt_setup` to initialize the operation structure and to specify the algorithm and the key to be used.
-1. Call `psa_cipher_set_iv` with the IV for the decryption.
-1. Call `psa_cipher_update` one or more times passing either the whole or only a fragment of the message each time.
-1. Call `psa_cipher_finish` to end the operation and output the decrypted message.
+1. Call `psa_cipher_decrypt_setup()` to initialize the operation structure and to specify the algorithm and the key to be used.
+1. Call `psa_cipher_set_iv()` with the IV for the decryption.
+1. Call `psa_cipher_update()` one or more times, passing the whole message or only a fragment of the message each time.
+1. Call `psa_cipher_finish()` to end the operation and output the decrypted message.
 
-Decrypting encrypted data using an AES key in CBC mode with no padding
+This example shows how to decrypt encrypted data using an AES key in CBC mode with no padding
 (assuming all prerequisites have been fulfilled):
 ```c
     enum {
@@ -350,33 +348,35 @@ Decrypting encrypted data using an AES key in CBC mode with no padding
 
 #### Handling cipher operation contexts
 
-Once you've initialized the operation structure with a successful call to `psa_cipher_encrypt_setup` or `psa_cipher_decrypt_setup`, you can terminate the operation at any time by calling `psa_cipher_abort`.
+After you've initialized the operation structure with a successful call to `psa_cipher_encrypt_setup()` or `psa_cipher_decrypt_setup()`, you can terminate the operation at any time by calling `psa_cipher_abort()`.
+
+The call to `psa_cipher_abort()` frees any resources associated with the operation, except for the operation structure itself.
 
-The call to `psa_cipher_abort` frees any resources associated with the operation (except for the operation structure itself). An implicit call to `psa_cipher_abort` occurs when any of these conditions occur:
-* A call to `psa_cipher_generate_iv`, `psa_cipher_set_iv` or `psa_cipher_update` has failed (returning any status other than `PSA_SUCCESS`).
-* Either a successful or failed call to `psa_cipher_finish`.
+Mbed Crypto implicitly calls `psa_cipher_abort()` when:
+* A call to `psa_cipher_generate_iv()`, `psa_cipher_set_iv()` or `psa_cipher_update()` fails (returning any status other than `PSA_SUCCESS`).
+* A call to `psa_cipher_finish()` succeeds or fails.
 
-Once `psa_cipher_abort` has been called (either implicitly by the implementation or explicitly by the user), the operation structure is invalidated and may not be reused for the same operation. However, the operation structure may be reused for a different operation by calling either `psa_cipher_encrypt_setup` or `psa_cipher_decrypt_setup` again.
+After an implicit or explicit call to `psa_cipher_abort()`, the operation structure is invalidated; in other words, you cannot reuse the operation structure for the same operation. You can, however, reuse the operation structure for a different operation by calling either `psa_cipher_encrypt_setup()` or `psa_cipher_decrypt_setup()` again.
 
-For an operation that has been initialized successfully (by a successful call to `psa_cipher_encrypt_setup` or `psa_cipher_decrypt_setup`) it is imperative that at some time `psa_cipher_abort` is called.
+You must call `psa_cipher_abort()` at some point for any operation that is initialized successfully (by a successful call to `psa_cipher_encrypt_setup()` or `psa_cipher_decrypt_setup()`).
 
-Multiple sequential calls to `psa_cipher_abort` on an operation that has already been terminated (either implicitly or explicitly) are safe and have no effect.
+Making multiple sequential calls to `psa_cipher_abort()` on an operation that is terminated (either implicitly or explicitly) is safe and has no effect.
 
 ### Hashing a message
 
 Mbed Crypto lets you compute and verify hashes using various hashing
 algorithms.
 
-Prerequisites to working with the hash APIs:
-* Initialize the library with a successful call to `psa_crypto_init`.
+**Prerequisites to working with the hash APIs:**
+* Initialize the library with a successful call to `psa_crypto_init()`.
 
-To calculate a hash:
+**To calculate a hash:**
 1. Allocate an operation structure (`psa_hash_operation_t`) to pass to the hash functions.
-1. Call `psa_hash_setup` to initialize the operation structure and specify the hash algorithm.
-1. Call `psa_hash_update` one or more times, passing either the whole or only a fragment of the message each time.
-1. Call `psa_hash_finish` to calculate the hash, or `psa_hash_verify` to compare the computed hash with an expected hash value.
+1. Call `psa_hash_setup()` to initialize the operation structure and specify the hash algorithm.
+1. Call `psa_hash_update()` one or more times, passing the whole message or only a fragment of the message each time.
+1. Call `psa_hash_finish()` to calculate the hash, or `psa_hash_verify()` to compare the computed hash with an expected hash value.
 
-Calculate the `SHA-256` hash of a message:
+This example shows how to calculate the `SHA-256` hash of a message:
 ```c
     psa_status_t status;
     psa_algorithm_t alg = PSA_ALG_SHA_256;
@@ -421,7 +421,7 @@ Calculate the `SHA-256` hash of a message:
     mbedtls_psa_crypto_free();
 ```
 
-Verify the `SHA-256` hash of a message:
+This example shows how to verify the `SHA-256` hash of a message:
 ```c
     psa_status_t status;
     psa_algorithm_t alg = PSA_ALG_SHA_256;
@@ -473,29 +473,27 @@ The API provides the macro `PSA_HASH_SIZE`, which returns the expected hash leng
 
 #### Handling hash operation contexts
 
-Once the operation structure has been successfully initialized by a successful call to `psa_hash_setup`, it's possible to terminate the operation at any time by calling `psa_hash_abort`. The call to `psa_hash_abort` frees any resources associated with the operation (except for the operation structure itself).
+After a successful call to `psa_hash_setup()` initializes the operation structure, you can terminate the operation at any time by calling `psa_hash_abort()`. The call to `psa_hash_abort()` frees any resources associated with the operation, except for the operation structure itself.
 
-An implicit call to `psa_hash_abort` occurs when any of these conditions occur:
-1. A call to `psa_hash_update` has failed (returning any status other than `PSA_SUCCESS`).
-1. Either a successful or failed call to `psa_hash_finish`.
-1. Either a successful or failed call to `psa_hash_verify`.
+Mbed Crypto implicitly calls `psa_hash_abort()` when:
+1. A call to `psa_hash_update()` fails (returning any status other than `PSA_SUCCESS`).
+1. A call to `psa_hash_finish()` succeeds or fails.
+1. A call to `psa_hash_verify()` succeeds or fails.
 
-Once `psa_hash_abort` has been called (either implicitly by the implementation or explicitly by the user), the operation structure is invalidated and may not be reused for the same operation. However, the operation structure may be reused for a different operation by calling `psa_hash_setup` again.
+After an implicit or explicit call to `psa_hash_abort()`, the operation structure is invalidated; in other words, you cannot reuse the operation structure for the same operation. You can, however, reuse the operation structure for a different operation by calling `psa_hash_setup()` again.
 
-For an operation that has been initialized successfully (by a successful call to `psa_hash_setup`) it is imperative that at some time `psa_hash_abort` is called.
+You must call `psa_hash_abort()` at some point for any operation that is initialized successfully (by a successful call to `psa_hash_setup()`) .
 
-Multiple sequential calls to `psa_hash_abort` on an operation that has already been terminated (either implicitly or explicitly) is safe and has no effect.
+Making multiple sequential calls to `psa_hash_abort()` on an operation that has already been terminated (either implicitly or explicitly) is safe and has no effect.
 
 ### Generating a random value
 
-Mbed Crypto can generate random data. To generate a random key, use
-`psa_generate_key()` instead of `psa_generate_random()`
+Mbed Crypto can generate random data.
 
-Prerequisites to random generation:
+**Prerequisites to random generation:**
 * Initialize the library with a successful call to `psa_crypto_init()`.
 
-Generate a random, ten-byte piece of data:
-1. Generate random bytes by calling `psa_generate_random()`:
+This example shows how to generate a random, ten-byte piece of data by calling `psa_generate_random()`:
 ```C
     psa_status_t status;
     uint8_t random[10] = { 0 };
@@ -521,42 +519,46 @@ Generate a random, ten-byte piece of data:
     /* Clean up */
     mbedtls_psa_crypto_free();
 ```
+To generate a random key, use `psa_generate_key()` instead of `psa_generate_random()`.
 
 ### Deriving a new key from an existing key
 
 Mbed Crypto provides a key derivation API that lets you derive new keys from
 existing ones. The key derivation API has functions to take inputs, including
 other keys and data, and functions to generate outputs, such as new keys or
-other data. A key derivation context must first be initialized and set up,
-provided with a key and optionally other data, and then derived data can be
-read from it either to a buffer or directly sent to a key slot. Refer to the
-documentation for the particular algorithm (such as HKDF or the TLS1.2 PRF) for
-information on which inputs to pass when and when you can obtain which outputs.
-
-Prerequisites to working with the key derivation APIs:
-* Initialize the library with a successful call to `psa_crypto_init`.
+other data.
+
+You must first initialize and set up a key derivation context,
+provided with a key and, optionally, other data. Then, use the key derivation context to either read derived data to a buffer or send derived data directly to a key slot.
+
+See the documentation for the particular algorithm (such as HKDF or the TLS1.2 PRF) for
+information about which inputs to pass when, and when you can obtain which outputs.
+
+**Prerequisites to working with the key derivation APIs:**
+* Initialize the library with a successful call to `psa_crypto_init()`.
 * Use a key with the appropriate attributes set:
     * Usage flags set for key derivation (`PSA_KEY_USAGE_DERIVE`)
     * Key type set to `PSA_KEY_TYPE_DERIVE`.
     * Algorithm set to a key derivation algorithm
       (`PSA_ALG_HKDF(PSA_ALG_SHA_256)`).
 
-Deriving a new AES-CTR 128-bit encryption key into a given key slot using HKDF
-with a given key, salt and info:
-1. Set up the key derivation context using the `psa_key_derivation_setup`
+**To derive a new AES-CTR 128-bit encryption key into a given key slot using HKDF
+with a given key, salt and information:**
+
+1. Set up the key derivation context using the `psa_key_derivation_setup()`
 function, specifying the derivation algorithm `PSA_ALG_HKDF(PSA_ALG_SHA_256)`.
-1. Provide an optional salt with `psa_key_derivation_input_bytes`.
-1. Provide info with `psa_key_derivation_input_bytes`.
-1. Provide secret with `psa_key_derivation_input_key`, referencing a key that
+1. Provide an optional salt with `psa_key_derivation_input_bytes()`.
+1. Provide information with `psa_key_derivation_input_bytes()`.
+1. Provide a secret with `psa_key_derivation_input_key()`, referencing a key that
    can be used for key derivation.
 1. Set the key attributes desired for the new derived key. We'll set
-   `PSA_KEY_USAGE_ENCRYPT` parameter and the algorithm `PSA_ALG_CTR` for this
+   the `PSA_KEY_USAGE_ENCRYPT` parameter and the `PSA_ALG_CTR` algorithm for this
    example.
 1. Derive the key by calling `psa_key_derivation_output_key()`.
 1. Clean up the key derivation context.
 
-At this point the derived key slot holds a new 128-bit AES-CTR encryption key
-derived from the key, salt and info provided:
+At this point, the derived key slot holds a new 128-bit AES-CTR encryption key
+derived from the key, salt and information provided:
 ```C
     psa_status_t status;
     psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
@@ -659,14 +661,13 @@ derived from the key, salt and info provided:
 
 ### Authenticating and encrypting or decrypting a message
 
-Mbed Crypto provides a simple way for authenticate and encrypt with associated data (AEAD) supporting `PSA_ALG_CCM` algorithm.
+Mbed Crypto provides a simple way to authenticate and encrypt with associated data (AEAD), supporting the `PSA_ALG_CCM` algorithm.
 
-Prerequisites to working with the AEAD ciphers APIs:
-* Initialize the library with a successful call to `psa_crypto_init`.
-* The key attributes for the key used for derivation must have usage flags
-  `PSA_KEY_USAGE_ENCRYPT` or `PSA_KEY_USAGE_DECRYPT`.
+**Prerequisites to working with the AEAD cipher APIs:**
+* Initialize the library with a successful call to `psa_crypto_init()`.
+* The key attributes for the key used for derivation must have the `PSA_KEY_USAGE_ENCRYPT` or `PSA_KEY_USAGE_DECRYPT` usage flags.
 
-To authenticate and encrypt a message:
+This example shows how to authenticate and encrypt a message:
 ```C
     psa_status_t status;
     static const uint8_t key[] = {
@@ -737,7 +738,7 @@ To authenticate and encrypt a message:
     mbedtls_psa_crypto_free();
 ```
 
-To authenticate and decrypt a message:
+This example shows how to authenticate and decrypt a message:
 
 ```C
     psa_status_t status;
@@ -816,18 +817,17 @@ To authenticate and decrypt a message:
 
 Mbed Crypto provides a simple way to generate a key or key pair.
 
-Prerequisites to using key generation and export APIs:
-* Initialize the library with a successful call to `psa_crypto_init`.
+**Prerequisites to using key generation and export APIs:**
+* Initialize the library with a successful call to `psa_crypto_init()`.
 
-Generate an ECDSA key:
+**To generate an ECDSA key:**
 1. Set the desired key attributes for key generation by calling
    `psa_set_key_algorithm()` with the chosen ECDSA algorithm (such as
-   `PSA_ALG_DETERMINISTIC_ECDSA(PSA_ALG_SHA_256)`). We don't set
-   `PSA_KEY_USAGE_EXPORT` as we only want to export the public key, not the key
+   `PSA_ALG_DETERMINISTIC_ECDSA(PSA_ALG_SHA_256)`). Do not set
+   `PSA_KEY_USAGE_EXPORT` because we only want to export the public key, not the key
    pair (or private key).
 1. Generate a key by calling `psa_generate_key()`.
-1. Export the generated public key by calling `psa_export_public_key()`
-:
+1. Export the generated public key by calling `psa_export_public_key()`:
 ```C
     enum {
         key_bits = 256,
@@ -877,8 +877,6 @@ Generate an ECDSA key:
     mbedtls_psa_crypto_free();
 ```
 
-### More about the Mbed Crypto library
-
-More information on [Mbed Crypto](https://github.com/ARMmbed/mbed-crypto/).
+### More about the Mbed Crypto
 
-More information on [PSA Crypto](https://github.com/ARMmbed/mbed-crypto/blob/development/docs/PSA_Crypto_API_Overview.pdf).
+For more information about PSA Crypto, download the *PSA Cryptography API* PDF under [PSA APIs](https://developer.arm.com/architectures/security-architectures/platform-security-architecture#implement).

From 802b19f6613b0f991209ee9347739cdfc3652268 Mon Sep 17 00:00:00 2001
From: Guy Wild <guy.wild@arm.com>
Date: Tue, 3 Sep 2019 16:40:44 +0300
Subject: [PATCH 04/77] Update getting_started.md

---
 docs/getting_started.md | 25 +++++++++++++------------
 1 file changed, 13 insertions(+), 12 deletions(-)

diff --git a/docs/getting_started.md b/docs/getting_started.md
index 3097a1ae9..de257a912 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -67,7 +67,7 @@ To use a key for cryptography operations in Mbed Crypto, you need to first
 import it. After you import the key, you'll be given a handle that refers to the key for use
 with other function calls.
 
-**Prerequisites for importing keys:**
+**Prerequisites to importing keys:**
 * Initialize the library with a successful call to `psa_crypto_init()`.
 
 This example shows how to import a key:
@@ -188,10 +188,10 @@ Mbed Crypto supports encrypting and decrypting messages using various symmetric
 1. Allocate an operation (`psa_cipher_operation_t`) structure to pass to the cipher functions.
 1. Call `psa_cipher_encrypt_setup()` to initialize the operation structure and specify the algorithm and the key to be used.
 1. Call either `psa_cipher_generate_iv()` or `psa_cipher_set_iv()` to generate or set the initialization vector (IV). We recommended calling `psa_cipher_generate_iv()`, unless you require a specific IV value.
-1. Call `psa_cipher_update()` one or more times, passing the whole message or only a fragment of the message each time.
+1. Call `psa_cipher_update()` one or more times, passing the whole message or a fragment of the message on each call.
 1. Call `psa_cipher_finish()` to end the operation and output the encrypted message.
 
-This example shows how to encrypt data using an Advanced Encryption Standard (AES) key in cipher block chain (CBC) mode with no padding (assuming all prerequisites have been fulfilled):
+This example shows how to encrypt data using an Advanced Encryption Standard (AES) key in Cipher Block Chaining (CBC) mode with no padding (assuming all prerequisites have been fulfilled):
 ```c
     enum {
         block_size = PSA_BLOCK_CIPHER_BLOCK_SIZE(PSA_KEY_TYPE_AES),
@@ -269,7 +269,7 @@ This example shows how to encrypt data using an Advanced Encryption Standard (AE
 1. Allocate an operation (`psa_cipher_operation_t`) structure to pass to the cipher functions.
 1. Call `psa_cipher_decrypt_setup()` to initialize the operation structure and to specify the algorithm and the key to be used.
 1. Call `psa_cipher_set_iv()` with the IV for the decryption.
-1. Call `psa_cipher_update()` one or more times, passing the whole message or only a fragment of the message each time.
+1. Call `psa_cipher_update()` one or more times, passing the whole message or a fragment of the message on each call.
 1. Call `psa_cipher_finish()` to end the operation and output the decrypted message.
 
 This example shows how to decrypt encrypted data using an AES key in CBC mode with no padding
@@ -373,7 +373,7 @@ algorithms.
 **To calculate a hash:**
 1. Allocate an operation structure (`psa_hash_operation_t`) to pass to the hash functions.
 1. Call `psa_hash_setup()` to initialize the operation structure and specify the hash algorithm.
-1. Call `psa_hash_update()` one or more times, passing the whole message or only a fragment of the message each time.
+1. Call `psa_hash_update()` one or more times, passing the whole message or a fragment of the message on each call.
 1. Call `psa_hash_finish()` to calculate the hash, or `psa_hash_verify()` to compare the computed hash with an expected hash value.
 
 This example shows how to calculate the `SHA-256` hash of a message:
@@ -490,10 +490,12 @@ Making multiple sequential calls to `psa_hash_abort()` on an operation that has
 
 Mbed Crypto can generate random data.
 
-**Prerequisites to random generation:**
+**Prerequisites to generating random data:**
 * Initialize the library with a successful call to `psa_crypto_init()`.
 
-This example shows how to generate a random, ten-byte piece of data by calling `psa_generate_random()`:
+<span class="notes">**Note:** To generate a random key, use `psa_generate_key()` instead of `psa_generate_random()`.</span>
+
+This example shows how to generate ten bytes of random data by calling `psa_generate_random()`:
 ```C
     psa_status_t status;
     uint8_t random[10] = { 0 };
@@ -519,7 +521,6 @@ This example shows how to generate a random, ten-byte piece of data by calling `
     /* Clean up */
     mbedtls_psa_crypto_free();
 ```
-To generate a random key, use `psa_generate_key()` instead of `psa_generate_random()`.
 
 ### Deriving a new key from an existing key
 
@@ -548,8 +549,8 @@ with a given key, salt and information:**
 1. Set up the key derivation context using the `psa_key_derivation_setup()`
 function, specifying the derivation algorithm `PSA_ALG_HKDF(PSA_ALG_SHA_256)`.
 1. Provide an optional salt with `psa_key_derivation_input_bytes()`.
-1. Provide information with `psa_key_derivation_input_bytes()`.
-1. Provide a secret with `psa_key_derivation_input_key()`, referencing a key that
+1. Provide `info` with `psa_key_derivation_input_bytes()`.
+1. Provide `secret` with `psa_key_derivation_input_key()`, referencing a key that
    can be used for key derivation.
 1. Set the key attributes desired for the new derived key. We'll set
    the `PSA_KEY_USAGE_ENCRYPT` parameter and the `PSA_ALG_CTR` algorithm for this
@@ -824,7 +825,7 @@ Mbed Crypto provides a simple way to generate a key or key pair.
 1. Set the desired key attributes for key generation by calling
    `psa_set_key_algorithm()` with the chosen ECDSA algorithm (such as
    `PSA_ALG_DETERMINISTIC_ECDSA(PSA_ALG_SHA_256)`). Do not set
-   `PSA_KEY_USAGE_EXPORT` because we only want to export the public key, not the key
+   `PSA_KEY_USAGE_EXPORT`; we only want to export the public key, not the key
    pair (or private key).
 1. Generate a key by calling `psa_generate_key()`.
 1. Export the generated public key by calling `psa_export_public_key()`:
@@ -877,6 +878,6 @@ Mbed Crypto provides a simple way to generate a key or key pair.
     mbedtls_psa_crypto_free();
 ```
 
-### More about the Mbed Crypto
+### More about the Mbed Crypto API
 
 For more information about PSA Crypto, download the *PSA Cryptography API* PDF under [PSA APIs](https://developer.arm.com/architectures/security-architectures/platform-security-architecture#implement).

From 5033fdd0e4bf619c545b1df34b849e208b1c11a9 Mon Sep 17 00:00:00 2001
From: Guy Wild <guy.wild@arm.com>
Date: Wed, 4 Sep 2019 09:14:55 +0300
Subject: [PATCH 05/77] Update getting_started.md

---
 docs/getting_started.md | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/docs/getting_started.md b/docs/getting_started.md
index de257a912..41a0c2567 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -47,7 +47,7 @@ Mbed Crypto releases are available in the [public GitHub repository](https://git
 * Python 2 or Python 3 (either works) to generate the test code.
 * Perl to run the tests.
 
-If you have a C compiler, such as GCC or Clang, just run `make` in the top-level directory to build the library, a set of unit tests and some sample programs.
+If you have a C compiler such as GCC or Clang, just run `make` in the top-level directory to build the library, a set of unit tests and some sample programs.
 
 To select a different compiler, set the `CC` variable to the name or path of the compiler and linker (default: `cc`) and set `AR` to a compatible archiver (default: `ar`); for example:
 ```
@@ -64,7 +64,7 @@ To use the Mbed Crypto APIs, call `psa_crypto_init()` before calling any other A
 ### Importing a key
 
 To use a key for cryptography operations in Mbed Crypto, you need to first
-import it. After you import the key, you'll be given a handle that refers to the key for use
+import it. Importing the key creates a handle that refers to the key for use
 with other function calls.
 
 **Prerequisites to importing keys:**
@@ -121,12 +121,15 @@ Mbed Crypto supports encrypting, decrypting, signing and verifying messages usin
     * Usage flag `PSA_KEY_USAGE_VERIFY` to allow signature verification.
     * Algorithm set to the desired signature algorithm.
 
-This example shows how to sign a given hash using RSA, call `psa_asymmetric_sign()` and get the output buffer that contains the signature:
+This example shows how to sign a hash that has already been calculated:
 ```C
     psa_status_t status;
     psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
     uint8_t key[] = RSA_KEY;
-    uint8_t hash[] = "INPUT_FOR_SIGN";
+    uint8_t hash[32] = {0x50, 0xd8, 0x58, 0xe0, 0x98, 0x5e, 0xcc, 0x7f,
+                    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};
     size_t signature_length;
     psa_key_handle_t handle;
@@ -181,8 +184,7 @@ Mbed Crypto supports encrypting and decrypting messages using various symmetric
 
 **Prerequisites to working with the symmetric cipher API:**
 * Initialize the library with a successful call to `psa_crypto_init()`.
-* Configure the key policy accordingly (set `PSA_KEY_USAGE_ENCRYPT` to allow encryption or `PSA_KEY_USAGE_DECRYPT` to allow decryption).
-* Have a valid key in the key slot.
+* Have a handle to a symmetric key. This key's usage flags must include `PSA_KEY_USAGE_ENCRYPT` to allow encryption or `PSA_KEY_USAGE_DECRYPT` to allow decryption.
 
 **To encrypt a message with a symmetric cipher:**
 1. Allocate an operation (`psa_cipher_operation_t`) structure to pass to the cipher functions.

From 33d421dd6abbbc7b48488d99bf5d25c411e6c5cd Mon Sep 17 00:00:00 2001
From: Guy Wild <guy.wild@arm.com>
Date: Wed, 4 Sep 2019 09:16:14 +0300
Subject: [PATCH 06/77] Update docs/getting_started.md

Co-Authored-By: Gilles Peskine <gilles.peskine@arm.com>
---
 docs/getting_started.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/getting_started.md b/docs/getting_started.md
index 41a0c2567..15410c118 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -188,7 +188,8 @@ Mbed Crypto supports encrypting and decrypting messages using various symmetric
 
 **To encrypt a message with a symmetric cipher:**
 1. Allocate an operation (`psa_cipher_operation_t`) structure to pass to the cipher functions.
-1. Call `psa_cipher_encrypt_setup()` to initialize the operation structure and specify the algorithm and the key to be used.
+1. Initialize the operation structure to zero or to `PSA_CIPHER_OPERATION_INIT`.
+1. Call `psa_cipher_encrypt_setup()` to specify the algorithm and the key to be used.
 1. Call either `psa_cipher_generate_iv()` or `psa_cipher_set_iv()` to generate or set the initialization vector (IV). We recommended calling `psa_cipher_generate_iv()`, unless you require a specific IV value.
 1. Call `psa_cipher_update()` one or more times, passing the whole message or a fragment of the message on each call.
 1. Call `psa_cipher_finish()` to end the operation and output the encrypted message.

From eefc517b1f7f34d2802fa6f5fc80d2580b9400ae Mon Sep 17 00:00:00 2001
From: Guy Wild <guy.wild@arm.com>
Date: Wed, 4 Sep 2019 09:16:53 +0300
Subject: [PATCH 07/77] Update docs/getting_started.md

Co-Authored-By: Gilles Peskine <gilles.peskine@arm.com>
---
 docs/getting_started.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/getting_started.md b/docs/getting_started.md
index 15410c118..5d123a602 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -375,7 +375,8 @@ algorithms.
 
 **To calculate a hash:**
 1. Allocate an operation structure (`psa_hash_operation_t`) to pass to the hash functions.
-1. Call `psa_hash_setup()` to initialize the operation structure and specify the hash algorithm.
+1. Initialize the operation structure to zero or to `PSA_HASH_OPERATION_INIT`.
+1. Call `psa_hash_setup()` to specify the hash algorithm.
 1. Call `psa_hash_update()` one or more times, passing the whole message or a fragment of the message on each call.
 1. Call `psa_hash_finish()` to calculate the hash, or `psa_hash_verify()` to compare the computed hash with an expected hash value.
 

From ad067c64f371747827ad774d500ec2b452967ea9 Mon Sep 17 00:00:00 2001
From: Guy Wild <guy.wild@arm.com>
Date: Wed, 4 Sep 2019 09:17:23 +0300
Subject: [PATCH 08/77] Update docs/getting_started.md

Co-Authored-By: Gilles Peskine <gilles.peskine@arm.com>
---
 docs/getting_started.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/getting_started.md b/docs/getting_started.md
index 5d123a602..6b87fa8d8 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -545,7 +545,7 @@ information about which inputs to pass when, and when you can obtain which outpu
     * Usage flags set for key derivation (`PSA_KEY_USAGE_DERIVE`)
     * Key type set to `PSA_KEY_TYPE_DERIVE`.
     * Algorithm set to a key derivation algorithm
-      (`PSA_ALG_HKDF(PSA_ALG_SHA_256)`).
+      (for example `PSA_ALG_HKDF(PSA_ALG_SHA_256)`).
 
 **To derive a new AES-CTR 128-bit encryption key into a given key slot using HKDF
 with a given key, salt and information:**

From 0058ab61e7260adedff07109f9e3faff36d705d9 Mon Sep 17 00:00:00 2001
From: Guy Wild <guy.wild@arm.com>
Date: Wed, 4 Sep 2019 09:17:54 +0300
Subject: [PATCH 09/77] Update docs/getting_started.md

Co-Authored-By: Gilles Peskine <gilles.peskine@arm.com>
---
 docs/getting_started.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/getting_started.md b/docs/getting_started.md
index 6b87fa8d8..b4a2554e5 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -557,7 +557,7 @@ function, specifying the derivation algorithm `PSA_ALG_HKDF(PSA_ALG_SHA_256)`.
 1. Provide `secret` with `psa_key_derivation_input_key()`, referencing a key that
    can be used for key derivation.
 1. Set the key attributes desired for the new derived key. We'll set
-   the `PSA_KEY_USAGE_ENCRYPT` parameter and the `PSA_ALG_CTR` algorithm for this
+   the `PSA_KEY_USAGE_ENCRYPT` usage flag and the `PSA_ALG_CTR` algorithm for this
    example.
 1. Derive the key by calling `psa_key_derivation_output_key()`.
 1. Clean up the key derivation context.

From 94113dbff342a2d27de60a7062b67432c0913b19 Mon Sep 17 00:00:00 2001
From: Guy Wild <guy.wild@arm.com>
Date: Wed, 4 Sep 2019 09:56:51 +0300
Subject: [PATCH 10/77] Update getting_started.md

---
 docs/getting_started.md | 14 ++++++--------
 1 file changed, 6 insertions(+), 8 deletions(-)

diff --git a/docs/getting_started.md b/docs/getting_started.md
index b4a2554e5..d8ddd4b13 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -190,11 +190,11 @@ Mbed Crypto supports encrypting and decrypting messages using various symmetric
 1. Allocate an operation (`psa_cipher_operation_t`) structure to pass to the cipher functions.
 1. Initialize the operation structure to zero or to `PSA_CIPHER_OPERATION_INIT`.
 1. Call `psa_cipher_encrypt_setup()` to specify the algorithm and the key to be used.
-1. Call either `psa_cipher_generate_iv()` or `psa_cipher_set_iv()` to generate or set the initialization vector (IV). We recommended calling `psa_cipher_generate_iv()`, unless you require a specific IV value.
+1. Call either `psa_cipher_generate_iv()` or `psa_cipher_set_iv()` to generate or set the initialization vector (IV). We recommend calling `psa_cipher_generate_iv()`, unless you require a specific IV value.
 1. Call `psa_cipher_update()` one or more times, passing the whole message or a fragment of the message on each call.
 1. Call `psa_cipher_finish()` to end the operation and output the encrypted message.
 
-This example shows how to encrypt data using an Advanced Encryption Standard (AES) key in Cipher Block Chaining (CBC) mode with no padding (assuming all prerequisites have been fulfilled):
+This example shows how to encrypt data using an AES (Advanced Encryption Standard) key in CBC (Cipher Block Chaining)) mode with no padding (assuming all prerequisites have been fulfilled):
 ```c
     enum {
         block_size = PSA_BLOCK_CIPHER_BLOCK_SIZE(PSA_KEY_TYPE_AES),
@@ -548,7 +548,7 @@ information about which inputs to pass when, and when you can obtain which outpu
       (for example `PSA_ALG_HKDF(PSA_ALG_SHA_256)`).
 
 **To derive a new AES-CTR 128-bit encryption key into a given key slot using HKDF
-with a given key, salt and information:**
+with a given key, salt and `info`:**
 
 1. Set up the key derivation context using the `psa_key_derivation_setup()`
 function, specifying the derivation algorithm `PSA_ALG_HKDF(PSA_ALG_SHA_256)`.
@@ -563,7 +563,7 @@ function, specifying the derivation algorithm `PSA_ALG_HKDF(PSA_ALG_SHA_256)`.
 1. Clean up the key derivation context.
 
 At this point, the derived key slot holds a new 128-bit AES-CTR encryption key
-derived from the key, salt and information provided:
+derived from the key, salt and `info` provided:
 ```C
     psa_status_t status;
     psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
@@ -828,9 +828,7 @@ Mbed Crypto provides a simple way to generate a key or key pair.
 **To generate an ECDSA key:**
 1. Set the desired key attributes for key generation by calling
    `psa_set_key_algorithm()` with the chosen ECDSA algorithm (such as
-   `PSA_ALG_DETERMINISTIC_ECDSA(PSA_ALG_SHA_256)`). Do not set
-   `PSA_KEY_USAGE_EXPORT`; we only want to export the public key, not the key
-   pair (or private key).
+   `PSA_ALG_DETERMINISTIC_ECDSA(PSA_ALG_SHA_256)`). You only want to export the public key, not the key pair (or private key); therefore, do not set `PSA_KEY_USAGE_EXPORT`.
 1. Generate a key by calling `psa_generate_key()`.
 1. Export the generated public key by calling `psa_export_public_key()`:
 ```C
@@ -884,4 +882,4 @@ Mbed Crypto provides a simple way to generate a key or key pair.
 
 ### More about the Mbed Crypto API
 
-For more information about PSA Crypto, download the *PSA Cryptography API* PDF under [PSA APIs](https://developer.arm.com/architectures/security-architectures/platform-security-architecture#implement).
+For more information about the PSA Crypto API, please see the [PSA Cryptography API Specification](https://armmbed.github.io/mbed-crypto/html/index.html).

From 29b64073af945f3ac7bcd0f17d75683dee38802e Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Tue, 6 Aug 2019 16:02:12 +0100
Subject: [PATCH 11/77] Added missing return codes to get_key_attributes

Note that PSA_ERROR_NOT_PERMITTED is not included
because I can't think of a scenario where you have
a valid key handle but aren't allowed to read the
attributes
---
 include/psa/crypto.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 0d8cbfa1f..2a63098a8 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -328,6 +328,8 @@ static size_t psa_get_key_bits(const psa_key_attributes_t *attributes);
  * \retval #PSA_ERROR_INVALID_HANDLE
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  */
 psa_status_t psa_get_key_attributes(psa_key_handle_t handle,
                                     psa_key_attributes_t *attributes);

From 89b7152ed037624044557c453267369f0784f71d Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Tue, 6 Aug 2019 16:21:00 +0100
Subject: [PATCH 12/77] Added PSA_ERROR_STORAGE_FAILURE to psa_export_key

It may be possible that an implementation does not
fetch key material until a command like
this is called and such an error may occur if an
off-chip secure storage dependency may have been wiped.
---
 include/psa/crypto.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 2a63098a8..96ffa0bbb 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -617,6 +617,7 @@ psa_status_t psa_destroy_key(psa_key_handle_t handle);
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize

From 0542d595ce7b9f3f9af0873fcf9c93c831641427 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Tue, 6 Aug 2019 16:34:44 +0100
Subject: [PATCH 13/77] Add PSA_ERROR_INSUFFICIENT_MEMORY to psa_export_key

It may be possible that the implementation runs out of
memory when exporting a key from storage or a secure
element. For example, it may not be possible to directly
move the data from storage to the caller, so the implementation
will have to buffer the material temporarily (an issue if dynamic
memory allocation scheme is used). For a large key
this is more likely to return.
---
 include/psa/crypto.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 96ffa0bbb..d62c2a9dd 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -618,6 +618,7 @@ psa_status_t psa_destroy_key(psa_key_handle_t handle);
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize

From 742084ea25e11c10f0a7843728ebca05376d262e Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Tue, 6 Aug 2019 16:54:52 +0100
Subject: [PATCH 14/77] Removed PSA_ERROR_DOES_NOT_EXIST from psa_export_key

If the key doesn't exist by the time this call is made
then the handle is invalid,
which means that PSA_ERROR_INVALID_HANDLE should be
returned rather than "does not exist"
---
 include/psa/crypto.h | 1 -
 1 file changed, 1 deletion(-)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index d62c2a9dd..f787b1369 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -604,7 +604,6 @@ psa_status_t psa_destroy_key(psa_key_handle_t handle);
  *
  * \retval #PSA_SUCCESS
  * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_DOES_NOT_EXIST
  * \retval #PSA_ERROR_NOT_PERMITTED
  *         The key does not have the #PSA_KEY_USAGE_EXPORT flag.
  * \retval #PSA_ERROR_NOT_SUPPORTED

From 88c51adfc08720dd7dcf2ba75a5c8a415d53713c Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Tue, 6 Aug 2019 17:09:33 +0100
Subject: [PATCH 15/77] Added PSA_ERROR_INSUFFICIENT_MEMORY to
 psa_export_public_key

For the same reasons that psa_export_key can fail with this error
---
 include/psa/crypto.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index f787b1369..8a987e9b1 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -687,6 +687,7 @@ psa_status_t psa_export_key(psa_key_handle_t handle,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize

From e926e7370fb59a0d4ce9266c266334deb8c88505 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Tue, 6 Aug 2019 17:12:44 +0100
Subject: [PATCH 16/77] Removed PSA_DOES_NOT_EXIST from psa_export_public_key

The implementation should return PSA_ERROR_INVALID_HANDLE instead.
---
 include/psa/crypto.h | 1 -
 1 file changed, 1 deletion(-)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 8a987e9b1..49f98b101 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -674,7 +674,6 @@ psa_status_t psa_export_key(psa_key_handle_t handle,
  *
  * \retval #PSA_SUCCESS
  * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_DOES_NOT_EXIST
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  *         The key is neither a public key nor a key pair.
  * \retval #PSA_ERROR_NOT_SUPPORTED

From 398b3c27e0eff516c4ac7b6ad710600a50bea4f4 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Tue, 6 Aug 2019 17:22:41 +0100
Subject: [PATCH 17/77] Add PSA_ERROR_STORAGE_FAILURE to psa_export_public_key

The same reason that it is included in psa_export_key
---
 include/psa/crypto.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 49f98b101..ed3aec7f1 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -686,6 +686,7 @@ psa_status_t psa_export_key(psa_key_handle_t handle,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().

From 60b0320af0579a21a2f3123f1d8bb5a81a050b1e Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Tue, 6 Aug 2019 17:26:16 +0100
Subject: [PATCH 18/77] Add PSA_ERROR_STORAGE_FAILURE to psa_copy_key

---
 include/psa/crypto.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index ed3aec7f1..2f5ec018c 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -775,6 +775,7 @@ psa_status_t psa_export_public_key(psa_key_handle_t handle,
  * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
  */
 psa_status_t psa_copy_key(psa_key_handle_t source_handle,

From f7d852a9d5d41d351610dc3d6ee36bef8e50b746 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Tue, 6 Aug 2019 17:50:26 +0100
Subject: [PATCH 19/77] Added PSA_ERROR_BUFFER_TOO_SMALL to psa_hash_compute

---
 include/psa/crypto.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 2f5ec018c..a797cd54f 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -807,6 +807,8 @@ psa_status_t psa_copy_key(psa_key_handle_t source_handle,
  *         Success.
  * \retval #PSA_ERROR_NOT_SUPPORTED
  *         \p alg is not supported or is not a hash algorithm.
+ * \retval #PSA_ERROR_BUFFER_TOO_SMALL
+ *         \p hash_size is too small
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE

From fa591c44afa8771a0c472252ecfa5b65bb9393ca Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Wed, 7 Aug 2019 10:47:47 +0100
Subject: [PATCH 20/77] Added PSA_ERROR_STORAGE_FAILURE to psa_mac_compute

In case the key could not be retrieved from
storage.
---
 include/psa/crypto.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index a797cd54f..de79c9b21 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -1134,6 +1134,8 @@ psa_status_t psa_hash_clone(const psa_hash_operation_t *source_operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
+ *         The key could not be retrieved from storage.
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize

From dec47b6f9dbab4f8679c69203465807bc8e06629 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Wed, 7 Aug 2019 14:25:38 +0100
Subject: [PATCH 21/77] Added the possibility of PSA_ERROR_BAD_STATE to all
 functions

---
 include/psa/crypto.h | 165 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 163 insertions(+), 2 deletions(-)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index de79c9b21..e6fa93af6 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -330,6 +330,10 @@ static size_t psa_get_key_bits(const psa_key_attributes_t *attributes);
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_get_key_attributes(psa_key_handle_t handle,
                                     psa_key_attributes_t *attributes);
@@ -395,6 +399,10 @@ void psa_reset_key_attributes(psa_key_attributes_t *attributes);
  *         through implementation-specific means.
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_open_key(psa_key_id_t id,
                           psa_key_handle_t *handle);
@@ -421,6 +429,10 @@ psa_status_t psa_open_key(psa_key_id_t id,
  * \retval #PSA_SUCCESS
  * \retval #PSA_ERROR_INVALID_HANDLE
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_close_key(psa_key_handle_t handle);
 
@@ -777,6 +789,10 @@ psa_status_t psa_export_public_key(psa_key_handle_t handle,
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_copy_key(psa_key_handle_t source_handle,
                           const psa_key_attributes_t *attributes,
@@ -813,6 +829,10 @@ psa_status_t psa_copy_key(psa_key_handle_t source_handle,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_hash_compute(psa_algorithm_t alg,
                               const uint8_t *input,
@@ -842,6 +862,10 @@ psa_status_t psa_hash_compute(psa_algorithm_t alg,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_hash_compare(psa_algorithm_t alg,
                               const uint8_t *input,
@@ -936,6 +960,10 @@ static psa_hash_operation_t psa_hash_operation_init(void);
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_hash_setup(psa_hash_operation_t *operation,
                             psa_algorithm_t alg);
@@ -958,6 +986,10 @@ psa_status_t psa_hash_setup(psa_hash_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_hash_update(psa_hash_operation_t *operation,
                              const uint8_t *input,
@@ -999,6 +1031,10 @@ psa_status_t psa_hash_update(psa_hash_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_hash_finish(psa_hash_operation_t *operation,
                              uint8_t *hash,
@@ -1035,6 +1071,10 @@ psa_status_t psa_hash_finish(psa_hash_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_hash_verify(psa_hash_operation_t *operation,
                              const uint8_t *hash,
@@ -1066,6 +1106,10 @@ psa_status_t psa_hash_verify(psa_hash_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_hash_abort(psa_hash_operation_t *operation);
 
@@ -1092,6 +1136,10 @@ psa_status_t psa_hash_abort(psa_hash_operation_t *operation);
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_hash_clone(const psa_hash_operation_t *source_operation,
                             psa_hash_operation_t *target_operation);
@@ -1174,6 +1222,12 @@ psa_status_t psa_mac_compute(psa_key_handle_t handle,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
+ *         The key could not be retrieved from storage.
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_mac_verify(psa_key_handle_t handle,
                             psa_algorithm_t alg,
@@ -1369,6 +1423,10 @@ psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_mac_update(psa_mac_operation_t *operation,
                             const uint8_t *input,
@@ -1411,6 +1469,10 @@ psa_status_t psa_mac_update(psa_mac_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_mac_sign_finish(psa_mac_operation_t *operation,
                                  uint8_t *mac,
@@ -1447,6 +1509,10 @@ psa_status_t psa_mac_sign_finish(psa_mac_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation,
                                    const uint8_t *mac,
@@ -1479,6 +1545,10 @@ psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_mac_abort(psa_mac_operation_t *operation);
 
@@ -1521,6 +1591,10 @@ psa_status_t psa_mac_abort(psa_mac_operation_t *operation);
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_cipher_encrypt(psa_key_handle_t handle,
                                 psa_algorithm_t alg,
@@ -1561,7 +1635,11 @@ psa_status_t psa_cipher_encrypt(psa_key_handle_t handle,
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
- * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code. * \retval #PSA_ERROR_CORRUPTION_DETECTED
+
  */
 psa_status_t psa_cipher_decrypt(psa_key_handle_t handle,
                                 psa_algorithm_t alg,
@@ -1768,6 +1846,10 @@ psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation,
                                     uint8_t *iv,
@@ -1803,6 +1885,10 @@ psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation,
                                const uint8_t *iv,
@@ -1839,6 +1925,10 @@ psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_cipher_update(psa_cipher_operation_t *operation,
                                const uint8_t *input,
@@ -1877,6 +1967,10 @@ psa_status_t psa_cipher_update(psa_cipher_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation,
                                uint8_t *output,
@@ -1910,6 +2004,10 @@ psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation);
 
@@ -2234,6 +2332,10 @@ psa_status_t psa_aead_decrypt_setup(psa_aead_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_aead_generate_nonce(psa_aead_operation_t *operation,
                                      uint8_t *nonce,
@@ -2268,6 +2370,10 @@ psa_status_t psa_aead_generate_nonce(psa_aead_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_aead_set_nonce(psa_aead_operation_t *operation,
                                 const uint8_t *nonce,
@@ -2306,6 +2412,10 @@ psa_status_t psa_aead_set_nonce(psa_aead_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_aead_set_lengths(psa_aead_operation_t *operation,
                                   size_t ad_length,
@@ -2348,6 +2458,10 @@ psa_status_t psa_aead_set_lengths(psa_aead_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation,
                                 const uint8_t *input,
@@ -2420,6 +2534,10 @@ psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_aead_update(psa_aead_operation_t *operation,
                              const uint8_t *input,
@@ -2489,6 +2607,10 @@ psa_status_t psa_aead_update(psa_aead_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_aead_finish(psa_aead_operation_t *operation,
                              uint8_t *ciphertext,
@@ -2547,6 +2669,10 @@ psa_status_t psa_aead_finish(psa_aead_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_aead_verify(psa_aead_operation_t *operation,
                              uint8_t *plaintext,
@@ -2582,6 +2708,10 @@ psa_status_t psa_aead_verify(psa_aead_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_aead_abort(psa_aead_operation_t *operation);
 
@@ -2891,6 +3021,11 @@ static psa_key_derivation_operation_t psa_key_derivation_operation_init(void);
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_BAD_STATE
+ *         The operation state is either not initialized or has been setup.
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_key_derivation_setup(
     psa_key_derivation_operation_t *operation,
@@ -2906,8 +3041,13 @@ psa_status_t psa_key_derivation_setup(
  * \param[out] capacity     On success, the capacity of the operation.
  *
  * \retval #PSA_SUCCESS
- * \retval #PSA_ERROR_BAD_STATE
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The operation state is not valid.
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_key_derivation_get_capacity(
     const psa_key_derivation_operation_t *operation,
@@ -2929,7 +3069,12 @@ psa_status_t psa_key_derivation_get_capacity(
  *         In this case, the operation object remains valid and its capacity
  *         remains unchanged.
  * \retval #PSA_ERROR_BAD_STATE
+ *         The operation state is not valid.
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_key_derivation_set_capacity(
     psa_key_derivation_operation_t *operation,
@@ -3082,6 +3227,10 @@ psa_status_t psa_key_derivation_input_key(
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_key_derivation_key_agreement(
     psa_key_derivation_operation_t *operation,
@@ -3116,6 +3265,10 @@ psa_status_t psa_key_derivation_key_agreement(
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_key_derivation_output_bytes(
     psa_key_derivation_operation_t *operation,
@@ -3264,6 +3417,10 @@ psa_status_t psa_key_derivation_output_key(
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_key_derivation_abort(
     psa_key_derivation_operation_t *operation);
@@ -3310,6 +3467,10 @@ psa_status_t psa_key_derivation_abort(
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_BAD_STATE
+ *         The library has not been previously initialized by psa_crypto_init().
+ *         It is implementation-dependent whether a failure to initialize
+ *         results in this error code.
  */
 psa_status_t psa_raw_key_agreement(psa_algorithm_t alg,
                                    psa_key_handle_t private_key,

From d5ae06b1e34d00033f496abf427a117dd6ba5705 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Wed, 7 Aug 2019 15:59:33 +0100
Subject: [PATCH 22/77] Add PSA_ERROR_BUFFER_TOO_SMALL to psa_mac_compute

---
 include/psa/crypto.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index e6fa93af6..2ee7cf60c 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -1178,6 +1178,8 @@ psa_status_t psa_hash_clone(const psa_hash_operation_t *source_operation,
  *         \p handle is not compatible with \p alg.
  * \retval #PSA_ERROR_NOT_SUPPORTED
  *         \p alg is not supported or is not a MAC algorithm.
+ * \retval #PSA_ERROR_BUFFER_TOO_SMALL
+ *         \p mac_size is too small
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE

From 7563ed17ab9026248f5eb2e7c4944884e6f87a6c Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Wed, 7 Aug 2019 16:02:45 +0100
Subject: [PATCH 23/77] Remove PSA_ERROR_DOES_NOT_EXIST from psa_mac_sign_setup

---
 include/psa/crypto.h | 1 -
 1 file changed, 1 deletion(-)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 2ee7cf60c..1fb1515cf 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -1323,7 +1323,6 @@ static psa_mac_operation_t psa_mac_operation_init(void);
  * \retval #PSA_SUCCESS
  *         Success.
  * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_DOES_NOT_EXIST
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  *         \p handle is not compatible with \p alg.

From 2409ba04292fae6d437f8621f07c68481b7e7732 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Wed, 7 Aug 2019 16:05:06 +0100
Subject: [PATCH 24/77] Added PSA_ERROR_STORAGE_FAILURE to psa_mac_sign_setup

---
 include/psa/crypto.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 1fb1515cf..a48e7e75c 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -1332,6 +1332,8 @@ static psa_mac_operation_t psa_mac_operation_init(void);
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
+ *         The key could not be retrieved from storage. 
  * \retval #PSA_ERROR_BAD_STATE
  *         The operation state is not valid (already set up and not
  *         subsequently completed).

From 9770d0e0f89986bdada221706e62c331677d1a08 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Wed, 7 Aug 2019 16:18:18 +0100
Subject: [PATCH 25/77] Add PSA_ERROR_STORAGE_FAILURE to psa_mac_verify_setup

---
 include/psa/crypto.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index a48e7e75c..58412196c 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -1394,6 +1394,8 @@ psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
+ *         The key could not be retrieved from storage
  * \retval #PSA_ERROR_BAD_STATE
  *         The operation state is not valid (already set up and not
  *         subsequently completed).

From 53d90c51994cdaf30470d0ac4d45e5fdba46cde3 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Wed, 7 Aug 2019 16:47:23 +0100
Subject: [PATCH 26/77] Only return PSA_ERROR_DOES_NOT_EXIST from psa_open_key

---
 include/psa/crypto.h | 7 -------
 1 file changed, 7 deletions(-)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 58412196c..b865177d1 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -1384,7 +1384,6 @@ psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation,
  * \retval #PSA_SUCCESS
  *         Success.
  * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_DOES_NOT_EXIST
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  *         \c key is not compatible with \c alg.
@@ -1740,7 +1739,6 @@ static psa_cipher_operation_t psa_cipher_operation_init(void);
  * \retval #PSA_SUCCESS
  *         Success.
  * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_DOES_NOT_EXIST
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  *         \p handle is not compatible with \p alg.
@@ -1802,7 +1800,6 @@ psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation,
  * \retval #PSA_SUCCESS
  *         Success.
  * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_DOES_NOT_EXIST
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  *         \p handle is not compatible with \p alg.
@@ -2053,7 +2050,6 @@ psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation);
  * \retval #PSA_SUCCESS
  *         Success.
  * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_DOES_NOT_EXIST
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  *         \p handle is not compatible with \p alg.
@@ -2109,7 +2105,6 @@ psa_status_t psa_aead_encrypt(psa_key_handle_t handle,
  * \retval #PSA_SUCCESS
  *         Success.
  * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_DOES_NOT_EXIST
  * \retval #PSA_ERROR_INVALID_SIGNATURE
  *         The ciphertext is not authentic.
  * \retval #PSA_ERROR_NOT_PERMITTED
@@ -3158,7 +3153,6 @@ psa_status_t psa_key_derivation_input_bytes(
  * \retval #PSA_SUCCESS
  *         Success.
  * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_DOES_NOT_EXIST
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  *         \c step is not compatible with the operation's algorithm.
@@ -3220,7 +3214,6 @@ psa_status_t psa_key_derivation_input_key(
  * \retval #PSA_SUCCESS
  *         Success.
  * \retval #PSA_ERROR_INVALID_HANDLE
- * \retval #PSA_ERROR_DOES_NOT_EXIST
  * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_ARGUMENT
  *         \c private_key is not compatible with \c alg,

From f961d5c9e60ca30638546548ac94bfa9479bbb0a Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Thu, 8 Aug 2019 10:27:50 +0100
Subject: [PATCH 27/77] Add missing return codes to psa_asymmetric_encrypt

---
 include/psa/crypto.h | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index b865177d1..273ddcb09 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -2839,6 +2839,8 @@ psa_status_t psa_asymmetric_verify(psa_key_handle_t handle,
  *                              that make up the returned output.
  *
  * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_INVALID_HANDLE
+ * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
  *         The size of the \p output buffer is too small. You can
  *         determine a sufficient buffer size by calling
@@ -2851,6 +2853,7 @@ psa_status_t psa_asymmetric_verify(psa_key_handle_t handle,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().

From 96f31ada184799a28358edafc498007f4d22b126 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Thu, 8 Aug 2019 10:30:58 +0100
Subject: [PATCH 28/77] Add missing return codes to psa_asymmetric_decrypt

---
 include/psa/crypto.h | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 273ddcb09..9c6ad82e7 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -2898,6 +2898,8 @@ psa_status_t psa_asymmetric_encrypt(psa_key_handle_t handle,
  *                              that make up the returned output.
  *
  * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_INVALID_HANDLE
+ * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
  *         The size of the \p output buffer is too small. You can
  *         determine a sufficient buffer size by calling
@@ -2910,6 +2912,7 @@ psa_status_t psa_asymmetric_encrypt(psa_key_handle_t handle,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
  * \retval #PSA_ERROR_INVALID_PADDING
  * \retval #PSA_ERROR_BAD_STATE

From c207ba376e7f61e505844791e4d4706527381eae Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Thu, 8 Aug 2019 10:55:38 +0100
Subject: [PATCH 29/77] Added missing return codes to psa_aead_decrypt

---
 include/psa/crypto.h | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 9c6ad82e7..fbe294753 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -2113,9 +2113,12 @@ psa_status_t psa_aead_encrypt(psa_key_handle_t handle,
  * \retval #PSA_ERROR_NOT_SUPPORTED
  *         \p alg is not supported or is not an AEAD algorithm.
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_BUFFER_TOO_SMALL
+ *         \p plaintext_size or \p nonce_length is too small
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize

From d21c6e6566abd4da05953c6d36b4b5cfe8b18fb7 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Thu, 8 Aug 2019 10:58:08 +0100
Subject: [PATCH 30/77] Add missing return codes to psa_generate_key

---
 include/psa/crypto.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index fbe294753..d25c1dc6a 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -3550,6 +3550,8 @@ psa_status_t psa_generate_random(uint8_t *output,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize

From 27c121574b6bf6a0ee1bb3960dcc5064538207b6 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Thu, 8 Aug 2019 11:10:32 +0100
Subject: [PATCH 31/77] Add missing parameters to psa_asymmetric_sign

---
 include/psa/crypto.h | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index d25c1dc6a..e5af9c605 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -2745,6 +2745,8 @@ psa_status_t psa_aead_abort(psa_aead_operation_t *operation);
  *                              that make up the returned signature value.
  *
  * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_INVALID_HANDLE
+ * \retval #PSA_ERROR_NOT_PERMITTED
  * \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
@@ -2757,6 +2759,7 @@ psa_status_t psa_aead_abort(psa_aead_operation_t *operation);
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().

From 6e758c9bb8ccd047e05f4c5fcef65cd4f207e03d Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Thu, 8 Aug 2019 11:11:43 +0100
Subject: [PATCH 32/77] Add missing return codes to psa_asymmetric_verify

---
 include/psa/crypto.h | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index e5af9c605..65d992d8d 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -2795,6 +2795,8 @@ psa_status_t psa_asymmetric_sign(psa_key_handle_t handle,
  *
  * \retval #PSA_SUCCESS
  *         The signature is valid.
+ * \retval #PSA_ERROR_INVALID_HANDLE
+ * \retval #PSA_ERROR_NOT_PERMITTED
  * \retval #PSA_ERROR_INVALID_SIGNATURE
  *         The calculation was perfomed successfully, but the passed
  *         signature is not a valid signature.
@@ -2804,6 +2806,7 @@ psa_status_t psa_asymmetric_sign(psa_key_handle_t handle,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize

From e970d6527313f0585421dcba5d14b4faaad14556 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Thu, 8 Aug 2019 14:40:04 +0100
Subject: [PATCH 33/77] Added extra bad state case to psa_hash_setup

---
 include/psa/crypto.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 65d992d8d..3d517d292 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -961,6 +961,8 @@ static psa_hash_operation_t psa_hash_operation_init(void);
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_BAD_STATE
+ *         \p operation is either not initialized or is in use
+ * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.

From 320659b54cb5f01256f548a89ed0fa56826a0063 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Thu, 8 Aug 2019 14:49:01 +0100
Subject: [PATCH 34/77] Added PSA_ERROR_BAD_STATE to functions with operations

In the case that the operation object has not been initialized
appropriately.
---
 include/psa/crypto.h | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 3d517d292..140d8922b 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -989,6 +989,8 @@ psa_status_t psa_hash_setup(psa_hash_operation_t *operation,
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_BAD_STATE
+ *         The operation state is not valid.
+ * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.
@@ -1034,6 +1036,8 @@ psa_status_t psa_hash_update(psa_hash_operation_t *operation,
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_BAD_STATE
+ *         The operation state is not valid.
+ * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.
@@ -1074,6 +1078,8 @@ psa_status_t psa_hash_finish(psa_hash_operation_t *operation,
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_BAD_STATE
+ *         The operation state is not valid.
+ * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.
@@ -1109,6 +1115,8 @@ psa_status_t psa_hash_verify(psa_hash_operation_t *operation,
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_BAD_STATE
+ *         The operation state is not valid.
+ * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.
@@ -1139,6 +1147,8 @@ psa_status_t psa_hash_abort(psa_hash_operation_t *operation);
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_BAD_STATE
+ *         The operation state is either not initialized or has already been setup.
+ * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.
@@ -3038,7 +3048,7 @@ static psa_key_derivation_operation_t psa_key_derivation_operation_init(void);
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_BAD_STATE
- *         The operation state is either not initialized or has been setup.
+ *         The operation state is either not initialized or has already been setup.
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize

From a3f6ba5843dc8cff69cc97cd82b1bb3c8d6fd60b Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Thu, 8 Aug 2019 14:51:49 +0100
Subject: [PATCH 35/77] Added PSA_ERROR_STORAGE_FAILURE to
 psa_cipher_(encrypt/decrypt)

---
 include/psa/crypto.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 140d8922b..7014be823 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -1607,6 +1607,7 @@ psa_status_t psa_mac_abort(psa_mac_operation_t *operation);
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
@@ -1651,6 +1652,7 @@ psa_status_t psa_cipher_encrypt(psa_key_handle_t handle,
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize

From 0d280b9873a68eed143c2ff978d18ff37e4f4941 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Thu, 8 Aug 2019 15:07:07 +0100
Subject: [PATCH 36/77] Add missing error codes for psa_raw_key_agreement

---
 include/psa/crypto.h | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 7014be823..b999fd115 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -3488,12 +3488,15 @@ psa_status_t psa_key_derivation_abort(
  *         \p private_key is not compatible with \p alg,
  *         or \p peer_key is not valid for \p alg or not compatible with
  *         \p private_key.
+ * \retval #PSA_ERROR_BUFFER_TOO_SMALL
+ *         \p output_size is too small
  * \retval #PSA_ERROR_NOT_SUPPORTED
  *         \p alg is not a supported key agreement algorithm.
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize

From 71b33ffcf8b01ea42a96c0584fbd0dd37bb0508d Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Thu, 8 Aug 2019 15:07:57 +0100
Subject: [PATCH 37/77] Add missing error codes to psa_generate_random

---
 include/psa/crypto.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index b999fd115..89dbd3fac 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -3531,6 +3531,7 @@ psa_status_t psa_raw_key_agreement(psa_algorithm_t alg,
  * \retval #PSA_SUCCESS
  * \retval #PSA_ERROR_NOT_SUPPORTED
  * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED

From 3e412494174eed9e310eaec42c3d18f78a3a294f Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Thu, 8 Aug 2019 15:10:33 +0100
Subject: [PATCH 38/77] Add PSA_ERROR_STORAGE_FAILURE to psa_aead_*_setup
 functions

---
 include/psa/crypto.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 89dbd3fac..c080f30ac 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -2251,6 +2251,7 @@ static psa_aead_operation_t psa_aead_operation_init(void);
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
@@ -2312,6 +2313,7 @@ psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize

From d789dc13da7d1457ccd87bae1d890788d56e5705 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Mon, 12 Aug 2019 15:06:48 +0100
Subject: [PATCH 39/77] Added a few more return codes

---
 include/psa/crypto.h | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index c080f30ac..a3a821d45 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -398,6 +398,7 @@ void psa_reset_key_attributes(psa_key_attributes_t *attributes);
  *         define any way to create such a key, but it may be possible
  *         through implementation-specific means.
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
@@ -1146,6 +1147,7 @@ psa_status_t psa_hash_abort(psa_hash_operation_t *operation);
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_BAD_STATE
  *         The operation state is either not initialized or has already been setup.
  * \retval #PSA_ERROR_BAD_STATE
@@ -1439,6 +1441,7 @@ psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize

From df3c7ac6450319768f6b741bb093ed928c882321 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Mon, 12 Aug 2019 16:43:30 +0100
Subject: [PATCH 40/77] Remove trailing whitespace

---
 include/psa/crypto.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index a3a821d45..3ffe07b01 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -1347,7 +1347,7 @@ static psa_mac_operation_t psa_mac_operation_init(void);
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_STORAGE_FAILURE
- *         The key could not be retrieved from storage. 
+ *         The key could not be retrieved from storage.
  * \retval #PSA_ERROR_BAD_STATE
  *         The operation state is not valid (already set up and not
  *         subsequently completed).

From 8d0bcf27ecf7a3864be9a19b8ce16fc3cfe469ff Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Tue, 13 Aug 2019 11:36:29 +0100
Subject: [PATCH 41/77] Add PSA_ERROR_INVALID_ARGUMENT to psa_hash_compare

---
 include/psa/crypto.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 3ffe07b01..0ecc41ff2 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -859,6 +859,8 @@ psa_status_t psa_hash_compute(psa_algorithm_t alg,
  *         differs from the expected hash.
  * \retval #PSA_ERROR_NOT_SUPPORTED
  *         \p alg is not supported or is not a hash algorithm.
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ *         \p input_length or \p hash_length do not match the hash size for \p alg
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE

From 263223689fc241e738be4ba4beb978570a8cb8fd Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Tue, 13 Aug 2019 11:43:40 +0100
Subject: [PATCH 42/77] Add storage failure to psa_mac_sign_finish

---
 include/psa/crypto.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 0ecc41ff2..fb48d34c7 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -1490,6 +1490,7 @@ psa_status_t psa_mac_update(psa_mac_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize

From d9e902488565db35a441a932705d372a1c3e3cd1 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Tue, 13 Aug 2019 11:44:30 +0100
Subject: [PATCH 43/77] Add storage failure to psa_mac_verify_finish

---
 include/psa/crypto.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index fb48d34c7..dace09bf5 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -1531,6 +1531,7 @@ psa_status_t psa_mac_sign_finish(psa_mac_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize

From dc5bf5c8e771b2df0e7311aff7774c20022cbcef Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Tue, 13 Aug 2019 11:46:09 +0100
Subject: [PATCH 44/77] Add storage failure to (encrypt/decrypt)_setup

---
 include/psa/crypto.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index dace09bf5..ece8edadd 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -1769,6 +1769,7 @@ static psa_cipher_operation_t psa_cipher_operation_init(void);
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The operation state is not valid (already set up and not
  *         subsequently completed).
@@ -1830,6 +1831,7 @@ psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The operation state is not valid (already set up and not
  *         subsequently completed).

From 484ba88a0f6c891df8a756bc2777455fc8ea2b10 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Tue, 13 Aug 2019 14:41:52 +0100
Subject: [PATCH 45/77] Add STORAGE_FAILURE everywhere + add missing codes

---
 include/psa/crypto.h | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index ece8edadd..18eee530a 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -1950,6 +1950,7 @@ psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
@@ -2079,6 +2080,8 @@ psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation);
  * \retval #PSA_ERROR_NOT_SUPPORTED
  *         \p alg is not supported or is not an AEAD algorithm.
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_BUFFER_TOO_SMALL
+ *         \p ciphertext_size is too small
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
@@ -2227,7 +2230,7 @@ static psa_aead_operation_t psa_aead_operation_init(void);
  *    of the non-encrypted additional authenticated data each time.
  * -# Call psa_aead_update() zero, one or more times, passing a fragment
  *    of the message to encrypt each time.
- * -# Call psa_aead_finish().
+ * -# Call psa_aead_finish(psa_aead_encrypt).
  *
  * The application may call psa_aead_abort() at any time after the operation
  * has been initialized.
@@ -2360,6 +2363,7 @@ psa_status_t psa_aead_decrypt_setup(psa_aead_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
@@ -2398,6 +2402,7 @@ psa_status_t psa_aead_generate_nonce(psa_aead_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
@@ -2440,6 +2445,7 @@ psa_status_t psa_aead_set_nonce(psa_aead_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
@@ -2486,6 +2492,7 @@ psa_status_t psa_aead_set_lengths(psa_aead_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
@@ -2562,6 +2569,7 @@ psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
@@ -2635,6 +2643,7 @@ psa_status_t psa_aead_update(psa_aead_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
@@ -2697,6 +2706,7 @@ psa_status_t psa_aead_finish(psa_aead_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
@@ -3084,6 +3094,8 @@ psa_status_t psa_key_derivation_setup(
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The operation state is not valid.
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
@@ -3111,6 +3123,8 @@ psa_status_t psa_key_derivation_get_capacity(
  * \retval #PSA_ERROR_BAD_STATE
  *         The operation state is not valid.
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
@@ -3157,6 +3171,7 @@ psa_status_t psa_key_derivation_set_capacity(
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The value of \p step is not valid given the state of \p operation.
  * \retval #PSA_ERROR_BAD_STATE
@@ -3202,6 +3217,7 @@ psa_status_t psa_key_derivation_input_bytes(
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The value of \p step is not valid given the state of \p operation.
  * \retval #PSA_ERROR_BAD_STATE
@@ -3265,6 +3281,7 @@ psa_status_t psa_key_derivation_input_key(
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
@@ -3303,6 +3320,7 @@ psa_status_t psa_key_derivation_key_agreement(
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
@@ -3424,6 +3442,7 @@ psa_status_t psa_key_derivation_output_bytes(
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize

From 6725757cecdf1b8743b3af7be75a32843c8e9339 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Thu, 15 Aug 2019 10:53:47 +0100
Subject: [PATCH 46/77] Remove errorneous insert

---
 include/psa/crypto.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 18eee530a..3bdc3aaa9 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -2230,7 +2230,7 @@ static psa_aead_operation_t psa_aead_operation_init(void);
  *    of the non-encrypted additional authenticated data each time.
  * -# Call psa_aead_update() zero, one or more times, passing a fragment
  *    of the message to encrypt each time.
- * -# Call psa_aead_finish(psa_aead_encrypt).
+ * -# Call psa_aead_finish().
  *
  * The application may call psa_aead_abort() at any time after the operation
  * has been initialized.

From f97c8523ee60933efd7bc22047b087cb0bff23cf Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Thu, 15 Aug 2019 13:27:12 +0100
Subject: [PATCH 47/77] Add CORRUPTION_DETECTED to psa_close_key

---
 include/psa/crypto.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 3bdc3aaa9..5b8be02b0 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -430,6 +430,7 @@ psa_status_t psa_open_key(psa_key_id_t id,
  * \retval #PSA_SUCCESS
  * \retval #PSA_ERROR_INVALID_HANDLE
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize

From 66200c4e98700f614e1f89928f748392508ee3af Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Thu, 15 Aug 2019 13:30:57 +0100
Subject: [PATCH 48/77] Add PSA_ERROR_STORAGE_FAILURE to psa_cipher_generate_iv

---
 include/psa/crypto.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 5b8be02b0..c5f2971e3 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -1872,6 +1872,7 @@ psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize

From fbf7f121f95be250d90690813f85924aa4dfe780 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Thu, 15 Aug 2019 13:34:51 +0100
Subject: [PATCH 49/77] Separate return codes for unsupported and invalid
 algorithms

---
 include/psa/crypto.h | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index c5f2971e3..35fe5e33b 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -956,7 +956,9 @@ static psa_hash_operation_t psa_hash_operation_init(void);
  * \retval #PSA_SUCCESS
  *         Success.
  * \retval #PSA_ERROR_NOT_SUPPORTED
- *         \p alg is not supported or is not a hash algorithm.
+ *         \p alg is not a supported hash algorithm.
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ *         \p alg is not a hash algorithm.
  * \retval #PSA_ERROR_BAD_STATE
  *         The operation state is not valid (already set up and not
  *         subsequently completed).

From 39797aa34c81620871c4e329e36ea2246d511f6e Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Fri, 23 Aug 2019 16:17:43 +0100
Subject: [PATCH 50/77] Fix erroneous cut and paste

---
 include/psa/crypto.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 35fe5e33b..4742120db 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -1663,11 +1663,11 @@ psa_status_t psa_cipher_encrypt(psa_key_handle_t handle,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
- *         results in this error code. * \retval #PSA_ERROR_CORRUPTION_DETECTED
-
+ *         results in this error code. 
  */
 psa_status_t psa_cipher_decrypt(psa_key_handle_t handle,
                                 psa_algorithm_t alg,

From 23c006f45e76c412333c220e1042fb33c39a0087 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Tue, 6 Aug 2019 16:02:12 +0100
Subject: [PATCH 51/77] Added missing return codes to get_key_attributes

Note that PSA_ERROR_NOT_PERMITTED is not included
because I can't think of a scenario where you have
a valid key handle but aren't allowed to read the
attributes
---
 include/psa/crypto.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 4742120db..aa63396f7 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -1667,7 +1667,7 @@ psa_status_t psa_cipher_encrypt(psa_key_handle_t handle,
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
- *         results in this error code. 
+ *         results in this error code.
  */
 psa_status_t psa_cipher_decrypt(psa_key_handle_t handle,
                                 psa_algorithm_t alg,

From 15731c14221e58cbeb8c892ce048a0fe11e5699d Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Tue, 6 Aug 2019 16:21:00 +0100
Subject: [PATCH 52/77] Added PSA_ERROR_STORAGE_FAILURE to psa_export_key

It may be possible that an implementation does not
fetch key material until a command like
this is called and such an error may occur if an
off-chip secure storage dependency may have been wiped.
---
 include/psa/crypto.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index aa63396f7..05d76e1c1 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -831,6 +831,7 @@ psa_status_t psa_copy_key(psa_key_handle_t source_handle,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize

From 7f1863c905c7b565a64d284303c79b9fecf52999 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Tue, 6 Aug 2019 16:34:44 +0100
Subject: [PATCH 53/77] Add PSA_ERROR_INSUFFICIENT_MEMORY to psa_export_key

It may be possible that the implementation runs out of
memory when exporting a key from storage or a secure
element. For example, it may not be possible to directly
move the data from storage to the caller, so the implementation
will have to buffer the material temporarily (an issue if dynamic
memory allocation scheme is used). For a large key
this is more likely to return.
---
 include/psa/crypto.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 05d76e1c1..57d3766ab 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -832,6 +832,7 @@ psa_status_t psa_copy_key(psa_key_handle_t source_handle,
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize

From 11638b99a0169288d239e0311d9656f15e33557c Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Tue, 6 Aug 2019 17:09:33 +0100
Subject: [PATCH 54/77] Added PSA_ERROR_INSUFFICIENT_MEMORY to
 psa_export_public_key

For the same reasons that psa_export_key can fail with this error
---
 include/psa/crypto.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 57d3766ab..d57011530 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -868,6 +868,7 @@ psa_status_t psa_hash_compute(psa_algorithm_t alg,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize

From 2a889781c55f6c289fa2103768104f629d2b4d84 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Tue, 6 Aug 2019 17:22:41 +0100
Subject: [PATCH 55/77] Add PSA_ERROR_STORAGE_FAILURE to psa_export_public_key

The same reason that it is included in psa_export_key
---
 include/psa/crypto.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index d57011530..84f1646a5 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -868,6 +868,7 @@ psa_status_t psa_hash_compute(psa_algorithm_t alg,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().

From 650229ba386a9f68563023149a4b3693197c572e Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Wed, 7 Aug 2019 10:47:47 +0100
Subject: [PATCH 56/77] Added PSA_ERROR_STORAGE_FAILURE to psa_mac_compute

In case the key could not be retrieved from
storage.
---
 include/psa/crypto.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 84f1646a5..6259a976f 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -1575,6 +1575,8 @@ psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
+ *         The key could not be retrieved from storage.
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize

From 52fa174a5a055e7b8e6ec7e2aa4df19986979064 Mon Sep 17 00:00:00 2001
From: Vikas Katariya <Vikas.Katariya@arm.com>
Date: Thu, 15 Aug 2019 11:59:08 +0100
Subject: [PATCH 57/77] Check for zero length and NULL buffer pointer.

In reference to issue https://github.com/ARMmbed/mbed-crypto/issues/49
---
 library/platform_util.c | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/library/platform_util.c b/library/platform_util.c
index 756e22679..b1f745097 100644
--- a/library/platform_util.c
+++ b/library/platform_util.c
@@ -72,7 +72,10 @@ static void * (* const volatile memset_func)( void *, int, size_t ) = memset;
 
 void mbedtls_platform_zeroize( void *buf, size_t len )
 {
-    memset_func( buf, 0, len );
+    MBEDTLS_INTERNAL_VALIDATE( len == 0 || buf != NULL );
+
+    if( len > 0 )
+        memset_func( buf, 0, len );
 }
 #endif /* MBEDTLS_PLATFORM_ZEROIZE_ALT */
 

From 1f42a84a13e137d05c85228e6b71e335690222b9 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Wed, 7 Aug 2019 15:59:33 +0100
Subject: [PATCH 58/77] Add PSA_ERROR_BUFFER_TOO_SMALL to psa_mac_compute

---
 include/psa/crypto.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 6259a976f..8a1e26240 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -1243,6 +1243,8 @@ psa_status_t psa_mac_compute(psa_key_handle_t handle,
  *         \p handle is not compatible with \p alg.
  * \retval #PSA_ERROR_NOT_SUPPORTED
  *         \p alg is not supported or is not a MAC algorithm.
+ * \retval #PSA_ERROR_BUFFER_TOO_SMALL
+ *         \p mac_size is too small
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE

From 23649246199d6028d8adb53b67c41bd289eeaa18 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Thu, 8 Aug 2019 10:58:08 +0100
Subject: [PATCH 59/77] Add missing return codes to psa_generate_key

---
 include/psa/crypto.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 8a1e26240..f721b7dbd 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -3577,6 +3577,8 @@ psa_status_t psa_raw_key_agreement(psa_algorithm_t alg,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize

From 97d3bc3674906ce373ad3b70fbc4bb83ce725a20 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Thu, 8 Aug 2019 14:40:04 +0100
Subject: [PATCH 60/77] Added extra bad state case to psa_hash_setup

---
 include/psa/crypto.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index f721b7dbd..71b1de231 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -503,6 +503,8 @@ psa_status_t psa_close_key(psa_key_handle_t handle);
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_BAD_STATE
+ *         \p operation is either not initialized or is in use
+ * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.

From 8f7cd1ee55cd5da92218b73e79f1715f00a9f8cc Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Thu, 8 Aug 2019 14:49:01 +0100
Subject: [PATCH 61/77] Added PSA_ERROR_BAD_STATE to functions with operations

In the case that the operation object has not been initialized
appropriately.
---
 include/psa/crypto.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 71b1de231..2a3c171db 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -1162,6 +1162,8 @@ psa_status_t psa_hash_abort(psa_hash_operation_t *operation);
  * \retval #PSA_ERROR_BAD_STATE
  *         The operation state is either not initialized or has already been setup.
  * \retval #PSA_ERROR_BAD_STATE
+ *         The operation state is either not initialized or has already been setup.
+ * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
  *         results in this error code.

From 22bc8fff0ceb55b1695540a961bd01d7acf255eb Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Thu, 8 Aug 2019 15:10:33 +0100
Subject: [PATCH 62/77] Add PSA_ERROR_STORAGE_FAILURE to psa_aead_*_setup
 functions

---
 include/psa/crypto.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 2a3c171db..09115f9c5 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -2046,6 +2046,7 @@ psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
@@ -2101,6 +2102,7 @@ psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation);
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize

From 56b32b126cc71ec851b8af14c610199841914a11 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Tue, 13 Aug 2019 11:43:40 +0100
Subject: [PATCH 63/77] Add storage failure to psa_mac_sign_finish

---
 include/psa/crypto.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 09115f9c5..35a196796 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -1926,6 +1926,7 @@ psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize

From 1f1e1a52537554e96d81306c1fec8a97ac02b2a3 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Tue, 13 Aug 2019 11:44:30 +0100
Subject: [PATCH 64/77] Add storage failure to psa_mac_verify_finish

---
 include/psa/crypto.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 35a196796..d714de04e 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -2010,6 +2010,7 @@ psa_status_t psa_cipher_update(psa_cipher_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize

From 1505b2108aa547a8cc2725cbc41f0c9aad3b9513 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Tue, 13 Aug 2019 14:41:52 +0100
Subject: [PATCH 65/77] Add STORAGE_FAILURE everywhere + add missing codes

---
 include/psa/crypto.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index d714de04e..5b556bc4f 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -2250,7 +2250,7 @@ static psa_aead_operation_t psa_aead_operation_init(void);
  *    of the non-encrypted additional authenticated data each time.
  * -# Call psa_aead_update() zero, one or more times, passing a fragment
  *    of the message to encrypt each time.
- * -# Call psa_aead_finish().
+ * -# Call psa_aead_finish(psa_aead_encrypt).
  *
  * The application may call psa_aead_abort() at any time after the operation
  * has been initialized.

From 599c7126680eaa57adcf9f1a2ce04ffb0a7468ff Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Thu, 15 Aug 2019 10:53:47 +0100
Subject: [PATCH 66/77] Remove errorneous insert

---
 include/psa/crypto.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 5b556bc4f..d714de04e 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -2250,7 +2250,7 @@ static psa_aead_operation_t psa_aead_operation_init(void);
  *    of the non-encrypted additional authenticated data each time.
  * -# Call psa_aead_update() zero, one or more times, passing a fragment
  *    of the message to encrypt each time.
- * -# Call psa_aead_finish(psa_aead_encrypt).
+ * -# Call psa_aead_finish().
  *
  * The application may call psa_aead_abort() at any time after the operation
  * has been initialized.

From f483973c37fe0f1e70015351332b93d6dd8e7efd Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Thu, 15 Aug 2019 13:30:57 +0100
Subject: [PATCH 67/77] Add PSA_ERROR_STORAGE_FAILURE to psa_cipher_generate_iv

---
 include/psa/crypto.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index d714de04e..2a418a47c 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -2766,6 +2766,7 @@ psa_status_t psa_aead_verify(psa_aead_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize

From fa2cefa001c9afcbf274d7105185be77e9394a58 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Tue, 3 Sep 2019 16:51:19 +0100
Subject: [PATCH 68/77] Fix warnings

---
 include/psa/crypto.h | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 2a418a47c..5fa75aea4 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -827,6 +827,7 @@ psa_status_t psa_copy_key(psa_key_handle_t source_handle,
  *         Success.
  * \retval #PSA_ERROR_NOT_SUPPORTED
  *         \p alg is not supported or is not a hash algorithm.
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
  * \retval #PSA_ERROR_BUFFER_TOO_SMALL
  *         \p hash_size is too small
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
@@ -2465,7 +2466,6 @@ psa_status_t psa_aead_set_nonce(psa_aead_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
- * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
@@ -3091,6 +3091,7 @@ static psa_key_derivation_operation_t psa_key_derivation_operation_init(void);
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The operation state is either not initialized or has already been setup.
  * \retval #PSA_ERROR_BAD_STATE

From 2a9e9f7d52f2aebaa079ec68b77137fb91489bfa Mon Sep 17 00:00:00 2001
From: Guy Wild <guy.wild@arm.com>
Date: Wed, 4 Sep 2019 13:45:54 +0300
Subject: [PATCH 69/77] Update getting_started.md

---
 docs/getting_started.md | 23 ++++++++++++-----------
 1 file changed, 12 insertions(+), 11 deletions(-)

diff --git a/docs/getting_started.md b/docs/getting_started.md
index d8ddd4b13..1afc19b67 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -191,10 +191,10 @@ Mbed Crypto supports encrypting and decrypting messages using various symmetric
 1. Initialize the operation structure to zero or to `PSA_CIPHER_OPERATION_INIT`.
 1. Call `psa_cipher_encrypt_setup()` to specify the algorithm and the key to be used.
 1. Call either `psa_cipher_generate_iv()` or `psa_cipher_set_iv()` to generate or set the initialization vector (IV). We recommend calling `psa_cipher_generate_iv()`, unless you require a specific IV value.
-1. Call `psa_cipher_update()` one or more times, passing the whole message or a fragment of the message on each call.
+1. Call `psa_cipher_update()` with the message to encrypt. You may call this function multiple times, passing successive fragments of the message on successive calls.
 1. Call `psa_cipher_finish()` to end the operation and output the encrypted message.
 
-This example shows how to encrypt data using an AES (Advanced Encryption Standard) key in CBC (Cipher Block Chaining)) mode with no padding (assuming all prerequisites have been fulfilled):
+This example shows how to encrypt data using an AES (Advanced Encryption Standard) key in CBC (Cipher Block Chaining) mode with no padding (assuming all prerequisites have been fulfilled):
 ```c
     enum {
         block_size = PSA_BLOCK_CIPHER_BLOCK_SIZE(PSA_KEY_TYPE_AES),
@@ -270,9 +270,10 @@ This example shows how to encrypt data using an AES (Advanced Encryption Standar
 
 **To decrypt a message with a symmetric cipher:**
 1. Allocate an operation (`psa_cipher_operation_t`) structure to pass to the cipher functions.
-1. Call `psa_cipher_decrypt_setup()` to initialize the operation structure and to specify the algorithm and the key to be used.
+1. Initialize the operation structure to zero or to `PSA_CIPHER_OPERATION_INIT`.
+1. Call `psa_cipher_decrypt_setup()` to specify the algorithm and the key to be used.
 1. Call `psa_cipher_set_iv()` with the IV for the decryption.
-1. Call `psa_cipher_update()` one or more times, passing the whole message or a fragment of the message on each call.
+1. Call `psa_cipher_update()` with the message to encrypt. You may call this function multiple times, passing successive fragments of the message on successive calls.
 1. Call `psa_cipher_finish()` to end the operation and output the decrypted message.
 
 This example shows how to decrypt encrypted data using an AES key in CBC mode with no padding
@@ -377,10 +378,10 @@ algorithms.
 1. Allocate an operation structure (`psa_hash_operation_t`) to pass to the hash functions.
 1. Initialize the operation structure to zero or to `PSA_HASH_OPERATION_INIT`.
 1. Call `psa_hash_setup()` to specify the hash algorithm.
-1. Call `psa_hash_update()` one or more times, passing the whole message or a fragment of the message on each call.
+1. Call `psa_hash_update()` with the message to encrypt. You may call this function multiple times, passing successive fragments of the message on successive calls.
 1. Call `psa_hash_finish()` to calculate the hash, or `psa_hash_verify()` to compare the computed hash with an expected hash value.
 
-This example shows how to calculate the `SHA-256` hash of a message:
+This example shows how to calculate the SHA-256 hash of a message:
 ```c
     psa_status_t status;
     psa_algorithm_t alg = PSA_ALG_SHA_256;
@@ -425,7 +426,7 @@ This example shows how to calculate the `SHA-256` hash of a message:
     mbedtls_psa_crypto_free();
 ```
 
-This example shows how to verify the `SHA-256` hash of a message:
+This example shows how to verify the SHA-256 hash of a message:
 ```c
     psa_status_t status;
     psa_algorithm_t alg = PSA_ALG_SHA_256;
@@ -477,7 +478,7 @@ The API provides the macro `PSA_HASH_SIZE`, which returns the expected hash leng
 
 #### Handling hash operation contexts
 
-After a successful call to `psa_hash_setup()` initializes the operation structure, you can terminate the operation at any time by calling `psa_hash_abort()`. The call to `psa_hash_abort()` frees any resources associated with the operation, except for the operation structure itself.
+After a successful call to `psa_hash_setup()`, you can terminate the operation at any time by calling `psa_hash_abort()`. The call to `psa_hash_abort()` frees any resources associated with the operation, except for the operation structure itself.
 
 Mbed Crypto implicitly calls `psa_hash_abort()` when:
 1. A call to `psa_hash_update()` fails (returning any status other than `PSA_SUCCESS`).
@@ -545,10 +546,10 @@ information about which inputs to pass when, and when you can obtain which outpu
     * Usage flags set for key derivation (`PSA_KEY_USAGE_DERIVE`)
     * Key type set to `PSA_KEY_TYPE_DERIVE`.
     * Algorithm set to a key derivation algorithm
-      (for example `PSA_ALG_HKDF(PSA_ALG_SHA_256)`).
+      (for example, `PSA_ALG_HKDF(PSA_ALG_SHA_256)`).
 
 **To derive a new AES-CTR 128-bit encryption key into a given key slot using HKDF
-with a given key, salt and `info`:**
+with a given key, salt and info:**
 
 1. Set up the key derivation context using the `psa_key_derivation_setup()`
 function, specifying the derivation algorithm `PSA_ALG_HKDF(PSA_ALG_SHA_256)`.
@@ -880,6 +881,6 @@ Mbed Crypto provides a simple way to generate a key or key pair.
     mbedtls_psa_crypto_free();
 ```
 
-### More about the Mbed Crypto API
+### More about the PSA Crypto API
 
 For more information about the PSA Crypto API, please see the [PSA Cryptography API Specification](https://armmbed.github.io/mbed-crypto/html/index.html).

From 3b5975641e614d7954b8da248d43c82e309794b1 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Wed, 4 Sep 2019 19:20:32 +0100
Subject: [PATCH 70/77] Fix return code warnings

- Remove STORAGE_FAILURE from hash and abort functions
- Remove BUFFER_TOO_SMALL from psa_mac_verify
---
 include/psa/crypto.h | 8 --------
 1 file changed, 8 deletions(-)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 5fa75aea4..9f6fcac32 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -834,7 +834,6 @@ psa_status_t psa_copy_key(psa_key_handle_t source_handle,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
- * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
@@ -871,7 +870,6 @@ psa_status_t psa_hash_compute(psa_algorithm_t alg,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
- * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
@@ -1248,8 +1246,6 @@ psa_status_t psa_mac_compute(psa_key_handle_t handle,
  *         \p handle is not compatible with \p alg.
  * \retval #PSA_ERROR_NOT_SUPPORTED
  *         \p alg is not supported or is not a MAC algorithm.
- * \retval #PSA_ERROR_BUFFER_TOO_SMALL
- *         \p mac_size is too small
  * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
@@ -1582,8 +1578,6 @@ psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
- * \retval #PSA_ERROR_STORAGE_FAILURE
- *         The key could not be retrieved from storage.
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
@@ -2049,7 +2043,6 @@ psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
- * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
@@ -2766,7 +2759,6 @@ psa_status_t psa_aead_verify(psa_aead_operation_t *operation,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
- * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize

From 5b1347a59e977c738240535b19734059f1cbf64f Mon Sep 17 00:00:00 2001
From: Guy Wild <guy.wild@arm.com>
Date: Thu, 5 Sep 2019 09:46:31 +0300
Subject: [PATCH 71/77] Update getting_started.md

---
 docs/getting_started.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/getting_started.md b/docs/getting_started.md
index 1afc19b67..a1c40eed9 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -127,9 +127,9 @@ This example shows how to sign a hash that has already been calculated:
     psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
     uint8_t key[] = RSA_KEY;
     uint8_t hash[32] = {0x50, 0xd8, 0x58, 0xe0, 0x98, 0x5e, 0xcc, 0x7f,
-                    0x60, 0x41, 0x8a, 0xaf, 0x0c, 0xc5, 0xab, 0x58,
-                    0x7f, 0x42, 0xc2, 0x57, 0x0a, 0x88, 0x40, 0x95,
-                    0xa9, 0xe8, 0xcc, 0xac, 0xd0, 0xf6, 0x54, 0x5c};
+                        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};
     size_t signature_length;
     psa_key_handle_t handle;

From ce56077f97553caa447fe4227bf832ad6153c383 Mon Sep 17 00:00:00 2001
From: Guy Wild <guy.wild@arm.com>
Date: Thu, 5 Sep 2019 11:35:16 +0300
Subject: [PATCH 72/77] Update based on Jaeden's comments.

---
 docs/getting_started.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/getting_started.md b/docs/getting_started.md
index a1c40eed9..8c995f3c8 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -553,7 +553,7 @@ with a given key, salt and info:**
 
 1. Set up the key derivation context using the `psa_key_derivation_setup()`
 function, specifying the derivation algorithm `PSA_ALG_HKDF(PSA_ALG_SHA_256)`.
-1. Provide an optional salt with `psa_key_derivation_input_bytes()`.
+1. Provide `salt` (optional) with `psa_key_derivation_input_bytes()`.
 1. Provide `info` with `psa_key_derivation_input_bytes()`.
 1. Provide `secret` with `psa_key_derivation_input_key()`, referencing a key that
    can be used for key derivation.
@@ -564,7 +564,7 @@ function, specifying the derivation algorithm `PSA_ALG_HKDF(PSA_ALG_SHA_256)`.
 1. Clean up the key derivation context.
 
 At this point, the derived key slot holds a new 128-bit AES-CTR encryption key
-derived from the key, salt and `info` provided:
+derived from the key, salt and info provided:
 ```C
     psa_status_t status;
     psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;

From 2900811b01e1d2451e32d435aca58fc2afb5a14b Mon Sep 17 00:00:00 2001
From: Guy Wild <guy.wild@arm.com>
Date: Thu, 5 Sep 2019 11:38:14 +0300
Subject: [PATCH 73/77] Update getting_started.md

---
 docs/getting_started.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/getting_started.md b/docs/getting_started.md
index 8c995f3c8..236c1a26c 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -553,9 +553,9 @@ with a given key, salt and info:**
 
 1. Set up the key derivation context using the `psa_key_derivation_setup()`
 function, specifying the derivation algorithm `PSA_ALG_HKDF(PSA_ALG_SHA_256)`.
-1. Provide `salt` (optional) with `psa_key_derivation_input_bytes()`.
-1. Provide `info` with `psa_key_derivation_input_bytes()`.
-1. Provide `secret` with `psa_key_derivation_input_key()`, referencing a key that
+1. Provide an optional salt with `psa_key_derivation_input_bytes()`.
+1. Provide info with `psa_key_derivation_input_bytes()`.
+1. Provide a secret with `psa_key_derivation_input_key()`, referencing a key that
    can be used for key derivation.
 1. Set the key attributes desired for the new derived key. We'll set
    the `PSA_KEY_USAGE_ENCRYPT` usage flag and the `PSA_ALG_CTR` algorithm for this

From 8619f8cd07ef5f9c2766973c1df87c62d3c9dbb3 Mon Sep 17 00:00:00 2001
From: "Adrian L. Shaw" <adrianlshaw@gmail.com>
Date: Thu, 5 Sep 2019 10:37:22 +0100
Subject: [PATCH 74/77] Remove storage errors from psa_generate_random

---
 include/psa/crypto.h | 2 --
 1 file changed, 2 deletions(-)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 9f6fcac32..d5e713e06 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -3579,8 +3579,6 @@ psa_status_t psa_raw_key_agreement(psa_algorithm_t alg,
  * \retval #PSA_ERROR_COMMUNICATION_FAILURE
  * \retval #PSA_ERROR_HARDWARE_FAILURE
  * \retval #PSA_ERROR_CORRUPTION_DETECTED
- * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
- * \retval #PSA_ERROR_STORAGE_FAILURE
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize

From dc22d8d022496483722ed0b9b0365435c0616068 Mon Sep 17 00:00:00 2001
From: Andrzej Kurek <andrzej.kurek@arm.com>
Date: Thu, 5 Sep 2019 09:34:34 -0400
Subject: [PATCH 75/77] Add an input check in psa_its_set

---
 library/psa_its_file.c | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/library/psa_its_file.c b/library/psa_its_file.c
index 05ca8afc7..0935b2780 100644
--- a/library/psa_its_file.c
+++ b/library/psa_its_file.c
@@ -214,9 +214,12 @@ psa_status_t psa_its_set( psa_storage_uid_t uid,
     n = fwrite( &header, 1, sizeof( header ), stream );
     if( n != sizeof( header ) )
         goto exit;
-    n = fwrite( p_data, 1, data_length, stream );
-    if( n != data_length )
-        goto exit;
+    if( data_length != 0 )
+    {
+        n = fwrite( p_data, 1, data_length, stream );
+        if( n != data_length )
+            goto exit;
+    }
     status = PSA_SUCCESS;
 
 exit:

From 10d42b686ad3e84af6019fae12d9ba010e2d122e Mon Sep 17 00:00:00 2001
From: Unknown <andrzej.kurek@mobica.com>
Date: Wed, 28 Aug 2019 02:29:20 -0400
Subject: [PATCH 76/77] Unify gcc and clang cmake flags to test with UBsan

Previously, not all flags were supported by the gcc version that was used
(pre-4.9). Now, since the minimum version gcc version tested is 5.4,
the flags can be unified.
---
 CMakeLists.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 16d71979a..81fa6cb89 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -137,8 +137,8 @@ if(CMAKE_COMPILER_IS_GNU)
     set(CMAKE_C_FLAGS_RELEASE     "-O2")
     set(CMAKE_C_FLAGS_DEBUG       "-O0 -g3")
     set(CMAKE_C_FLAGS_COVERAGE    "-O0 -g3 --coverage")
-    set(CMAKE_C_FLAGS_ASAN        "-Werror -fsanitize=address -fno-common -O3")
-    set(CMAKE_C_FLAGS_ASANDBG     "-Werror -fsanitize=address -fno-common -O1 -g3 -fno-omit-frame-pointer -fno-optimize-sibling-calls ")
+    set(CMAKE_C_FLAGS_ASAN        "-Werror -fsanitize=address -fno-common -fsanitize=undefined -fno-sanitize-recover=all -O3")
+    set(CMAKE_C_FLAGS_ASANDBG     "-Werror -fsanitize=address -fno-common -fsanitize=undefined -fno-sanitize-recover=all -O1 -g3 -fno-omit-frame-pointer -fno-optimize-sibling-calls")
     set(CMAKE_C_FLAGS_CHECK       "-Werror -Os")
     set(CMAKE_C_FLAGS_CHECKFULL   "${CMAKE_C_FLAGS_CHECK} -Wcast-qual")
 endif(CMAKE_COMPILER_IS_GNU)
@@ -149,7 +149,7 @@ if(CMAKE_COMPILER_IS_CLANG)
     set(CMAKE_C_FLAGS_DEBUG       "-O0 -g3")
     set(CMAKE_C_FLAGS_COVERAGE    "-O0 -g3 --coverage")
     set(CMAKE_C_FLAGS_ASAN        "-Werror -fsanitize=address -fno-common -fsanitize=undefined -fno-sanitize-recover=all -O3")
-    set(CMAKE_C_FLAGS_ASANDBG     "-Werror -fsanitize=address -fno-common -fsanitize=undefined -fno-sanitize-recover=all -O1 -g3 -fno-omit-frame-pointer -fno-optimize-sibling-calls ")
+    set(CMAKE_C_FLAGS_ASANDBG     "-Werror -fsanitize=address -fno-common -fsanitize=undefined -fno-sanitize-recover=all -O1 -g3 -fno-omit-frame-pointer -fno-optimize-sibling-calls")
     set(CMAKE_C_FLAGS_MEMSAN      "-Werror -fsanitize=memory -O3")
     set(CMAKE_C_FLAGS_MEMSANDBG   "-Werror -fsanitize=memory -O1 -g3 -fno-omit-frame-pointer -fno-optimize-sibling-calls -fsanitize-memory-track-origins=2")
     set(CMAKE_C_FLAGS_CHECK       "-Werror -Os")

From f094b53e8e6dff79cb62aaff532215b3b2f8e092 Mon Sep 17 00:00:00 2001
From: Unknown <andrzej.kurek@mobica.com>
Date: Tue, 3 Sep 2019 07:52:21 -0400
Subject: [PATCH 77/77] all.sh: disable MEMORY_BUFFER_ALLOC in cmake asan build

Enabling MBEDTLS_MEMORY_BUFFER_ALLOC_C bypasses ASan leak checks
because system calloc() and free() aren't used.
---
 tests/scripts/all.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/scripts/all.sh b/tests/scripts/all.sh
index 244fdc327..20458af2c 100755
--- a/tests/scripts/all.sh
+++ b/tests/scripts/all.sh
@@ -701,7 +701,7 @@ component_test_no_use_psa_crypto_full_cmake_asan() {
     # full minus MBEDTLS_USE_PSA_CRYPTO: run the same set of tests as basic-build-test.sh
     msg "build: cmake, full config + MBEDTLS_USE_PSA_CRYPTO, ASan"
     scripts/config.pl full
-    scripts/config.pl unset MBEDTLS_MEMORY_BACKTRACE # too slow for tests
+    scripts/config.pl unset MBEDTLS_MEMORY_BUFFER_ALLOC_C
     scripts/config.pl set MBEDTLS_ECP_RESTARTABLE  # not using PSA, so enable restartable ECC
     scripts/config.pl set MBEDTLS_PSA_CRYPTO_C
     scripts/config.pl unset MBEDTLS_USE_PSA_CRYPTO