yuzu-emu/mbedtls
1
0
Fork 0
mirror of https://github.com/yuzu-emu/mbedtls.git synced 2024-11-23 04:55:51 +01:00
Code Issues Packages Projects Releases Wiki Activity

Update getting_started.md

Browse Source
This commit is contained in:
Guy Wild 2019-09-03 16:40:44 +03:00
parent c03c0fcd93
commit 802b19f661
1 changed files with 13 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
docs/getting_started.md
View File

@ -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 import it. After you import the key, you'll be given a handle that refers to the key for use
with other function calls. with other function calls.
**Prerequisites for importing keys:** **Prerequisites to importing keys:**
* Initialize the library with a successful call to `psa_crypto_init()`. * Initialize the library with a successful call to `psa_crypto_init()`.
This example shows how to import a key: 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. 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 `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 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. 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 ```c
enum { enum {
block_size = PSA_BLOCK_CIPHER_BLOCK_SIZE(PSA_KEY_TYPE_AES), 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. 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_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_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. 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 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:** **To calculate a hash:**
1. Allocate an operation structure (`psa_hash_operation_t`) to pass to the hash functions. 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_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. 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:
@ -490,10 +490,12 @@ Making multiple sequential calls to `psa_hash_abort()` on an operation that has
Mbed Crypto can generate random data. 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()`. * 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 ```C
psa_status_t status; psa_status_t status;
uint8_t random[10] = { 0 }; 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 */ /* Clean up */
mbedtls_psa_crypto_free(); 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 ### 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()` 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)`. 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 an optional salt with `psa_key_derivation_input_bytes()`.
1. Provide information 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 1. Provide `secret` with `psa_key_derivation_input_key()`, referencing a key that
can be used for key derivation. can be used for key derivation.
1. Set the key attributes desired for the new derived key. We'll set 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` 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 1. Set the desired key attributes for key generation by calling
`psa_set_key_algorithm()` with the chosen ECDSA algorithm (such as `psa_set_key_algorithm()` with the chosen ECDSA algorithm (such as
`PSA_ALG_DETERMINISTIC_ECDSA(PSA_ALG_SHA_256)`). Do not set `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). pair (or private key).
1. Generate a key by calling `psa_generate_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()`:
@ -877,6 +878,6 @@ Mbed Crypto provides a simple way to generate a key or key pair.
mbedtls_psa_crypto_free(); 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). 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).