From c03c0fcd9392a0119798b7fa344d32408bc55894 Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Tue, 3 Sep 2019 13:18:04 +0300 Subject: [PATCH 01/12] Update getting_started.md --- docs/getting_started.md | 186 ++++++++++++++++++++-------------------- 1 file changed, 92 insertions(+), 94 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). 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`. +The call to `psa_cipher_abort()` frees any resources associated with the operation, except for the operation structure itself. -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. +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. -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. +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. -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. +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()`). + +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. +other data. -Prerequisites to working with the key derivation APIs: -* Initialize the library with a successful call to `psa_crypto_init`. +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 about the Mbed Crypto -More information on [Mbed Crypto](https://github.com/ARMmbed/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 Date: Tue, 3 Sep 2019 16:40:44 +0300 Subject: [PATCH 02/12] 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()`: +**Note:** To generate a random key, use `psa_generate_key()` instead of `psa_generate_random()`. + +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 Date: Wed, 4 Sep 2019 09:14:55 +0300 Subject: [PATCH 03/12] 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 Date: Wed, 4 Sep 2019 09:16:14 +0300 Subject: [PATCH 04/12] Update docs/getting_started.md Co-Authored-By: Gilles Peskine --- 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 Date: Wed, 4 Sep 2019 09:16:53 +0300 Subject: [PATCH 05/12] Update docs/getting_started.md Co-Authored-By: Gilles Peskine --- 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 Date: Wed, 4 Sep 2019 09:17:23 +0300 Subject: [PATCH 06/12] Update docs/getting_started.md Co-Authored-By: Gilles Peskine --- 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 Date: Wed, 4 Sep 2019 09:17:54 +0300 Subject: [PATCH 07/12] Update docs/getting_started.md Co-Authored-By: Gilles Peskine --- 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 Date: Wed, 4 Sep 2019 09:56:51 +0300 Subject: [PATCH 08/12] 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 2a9e9f7d52f2aebaa079ec68b77137fb91489bfa Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Wed, 4 Sep 2019 13:45:54 +0300 Subject: [PATCH 09/12] 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 5b1347a59e977c738240535b19734059f1cbf64f Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Thu, 5 Sep 2019 09:46:31 +0300 Subject: [PATCH 10/12] 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 Date: Thu, 5 Sep 2019 11:35:16 +0300 Subject: [PATCH 11/12] 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 Date: Thu, 5 Sep 2019 11:38:14 +0300 Subject: [PATCH 12/12] 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