From 802b19f6613b0f991209ee9347739cdfc3652268 Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Tue, 3 Sep 2019 16:40:44 +0300 Subject: [PATCH] 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).