| Gilles Peskine | 6c723a2 | 2020-04-17 16:57:52 +0200 | [diff] [blame] | 1 | .. _usage-considerations: |
| 2 | |
| 3 | Usage considerations |
| 4 | -------------------- |
| 5 | |
| 6 | Security recommendations |
| 7 | ~~~~~~~~~~~~~~~~~~~~~~~~ |
| 8 | |
| 9 | Always check for errors |
| 10 | ^^^^^^^^^^^^^^^^^^^^^^^ |
| 11 | |
| 12 | Most functions in this API can return errors. All functions that can fail have |
| 13 | the return type `psa_status_t`. A few functions cannot fail, and thus, return |
| 14 | ``void`` or some other type. |
| 15 | |
| 16 | If an error occurs, unless otherwise specified, the content of the output |
| 17 | parameters is undefined and must not be used. |
| 18 | |
| 19 | Some common causes of errors include: |
| 20 | |
| 21 | - In implementations where the keys are stored and processed in a separate |
| 22 | environment from the application, all functions that need to access the |
| 23 | cryptography processing environment might fail due to an error in the |
| 24 | communication between the two environments. |
| 25 | - If an algorithm is implemented with a hardware accelerator, which is |
| 26 | logically separate from the application processor, the accelerator might fail, |
| 27 | even when the application processor keeps running normally. |
| 28 | - Most functions might fail due to a lack of resources. However, some |
| 29 | implementations guarantee that certain functions always have sufficient |
| 30 | memory. |
| 31 | - All functions that access persistent keys might fail due to a storage failure. |
| 32 | - All functions that require randomness might fail due to a lack of entropy. |
| 33 | Implementations are encouraged to seed the random generator with sufficient |
| 34 | entropy during the execution of `psa_crypto_init()`. However, some security |
| 35 | standards require periodic reseeding from a hardware random generator, which |
| 36 | can fail. |
| 37 | |
| 38 | Shared memory and concurrency |
| 39 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 40 | |
| 41 | Some environments allow applications to be multithreaded, while others do not. |
| 42 | In some environments, applications can share memory with a different security |
| 43 | context. In environments with multithreaded applications or shared memory, |
| 44 | applications must be written carefully to avoid data corruption or leakage. This |
| 45 | specification requires the application to obey certain constraints. |
| 46 | |
| 47 | In general, this API allows either one writer or any number of simultaneous |
| 48 | readers, on any given object. In other words, if two or more calls access the |
| 49 | same object concurrently, then the behavior is only well-defined if all the |
| 50 | calls are only reading from the object and do not modify it. Read accesses |
| 51 | include reading memory by input parameters and reading keystore content by using |
| 52 | a key. For more details, refer to the `concurrency` |
| 53 | section. |
| 54 | |
| 55 | If an application shares memory with another security context, it can pass |
| 56 | shared memory blocks as input buffers or output buffers, but not as non-buffer |
| 57 | parameters. For more details, refer to the :title:`stability-of-parameters` section. |
| 58 | |
| 59 | Cleaning up after use |
| 60 | ^^^^^^^^^^^^^^^^^^^^^ |
| 61 | |
| 62 | To minimize impact if the system is compromised, it is recommended that |
| 63 | applications wipe all sensitive data from memory when it is no longer used. That |
| 64 | way, only data that is currently in use can be leaked, and past data is not |
| 65 | compromised. |
| 66 | |
| 67 | Wiping sensitive data includes: |
| 68 | |
| 69 | - Clearing temporary buffers in the stack or on the heap. |
| 70 | - Aborting operations if they will not be finished. |
| 71 | - Destroying keys that are no longer used. |