doc: security: Update cryptographic documentation

doc/security/security-overview.rst

@@ -122,14 +122,12 @@ Security Functionality
 The security functionality in Zephyr hinges mainly on the inclusion of
 cryptographic algorithms, and on its monolithic system design.
 
-The cryptographic features are provided through a set of cryptographic
-libraries. Applications can choose TinyCrypt2 or Mbed TLS based on their
-needs. TinyCrypt2 supports key cryptographic algorithms required by the
-connectivity stacks. TinyCrypt2, however, only provides a limited set of
-algorithms. Mbed TLS supports a wider range of algorithms, but at the
-cost of additional requirements such as malloc support. Applications can
-choose the solution that matches their individual requirements. Future
-work may include APIs to abstract the underlying crypto library choice.
+The cryptographic features are provided through PSA Crypto, with
+mbedTLS as the underlying implementation. Applications leverage PSA
+Crypto APIs, ensuring a standardized and secure approach to
+cryptographic operations. mbedTLS, as the implementation of PSA
+Crypto, supports a wide range of cryptographic algorithms, making it
+suitable for various application requirements.
 
 APIs for vendor specific cryptographic IPs in both hardware and software
 are planned, including secure key storage in the form of secure access

doc/services/crypto/index.rst

@@ -13,6 +13,6 @@ The following crypto libraries have been included:
 .. toctree::
    :maxdepth: 1
 
-   tinycrypt.rst
+   psa_crypto.rst
    random/index.rst
    api/index.rst

doc/services/crypto/psa_crypto.rst

@@ -0,0 +1,181 @@
+.. _psa_crypto:
+
+PSA Crypto
+##########
+
+Overview
+********
+
+The PSA (Platform Security Architecture) Crypto API offers a portable
+programming interface for cryptographic operations and key storage
+across a wide range of hardware. It is designed to be user-friendly
+while still providing access to the low-level primitives essential for
+modern cryptography.
+
+It is created and maintained by Arm. Arm developed the PSA as a
+comprehensive security framework to address the increasing security
+needs of connected devices.
+
+In Zephyr, the PSA Crypto API is implemented using Mbed TLS, an
+open-source cryptographic library that provides the underlying
+cryptographic functions.
+
+Design Goals
+************
+
+The interface is suitable for a vast range of devices: from
+special-purpose cryptographic processors that process data with a
+built-in key, to constrained devices running custom application code,
+such as microcontrollers, and multi-application devices, such as
+servers. It follows the principle of cryptographic agility.
+
+Algorithm Flexibility
+  The PSA Crypto API supports a wide range of cryptographic algorithms,
+  allowing developers to switch between different cryptographic
+  methods as needed. This flexibility is crucial for maintaining
+  security as new algorithms emerge and existing ones become obsolete.
+
+Key Management
+  The PSA Crypto API includes robust key management features that
+  support the creation, storage, and use of cryptographic keys in a
+  secure and flexible manner. It uses opaque key identifiers, which
+  allows for easy key replacement and updates without exposing key
+  material.
+
+Implementation Independence
+  The PSA Crypto API abstracts the underlying cryptographic library,
+  meaning that the specific implementation can be changed without
+  affecting the application code. This abstraction supports
+  cryptographic agility by enabling the use of different cryptographic
+  libraries or hardware accelerators as needed.
+
+Future-Proofing
+  By adhering to cryptographic agility, PSA Crypto ensures that
+  applications can quickly adapt to new cryptographic standards and
+  practices, enhancing long-term security and compliance.
+
+Examples of Applications
+************************
+
+Network Security (TLS)
+  The API provides all of the cryptographic primitives needed to establish TLS connections.
+
+Secure Storage
+  The API provides all primitives related to storage encryption, block
+  or file-based, with master encryption keys stored inside a key store.
+
+Network Credentials
+  The API provides network credential management inside a key store,
+  for example, for X.509-based authentication or pre-shared keys on
+  enterprise networks.
+
+Device Pairing
+  The API provides support for key agreement protocols that are often
+  used for secure pairing of devices over wireless channels. For
+  example, the pairing of an NFC token or a Bluetooth device might use
+  key agreement protocols upon first use.
+
+Secure Boot
+  The API provides primitives for use during firmware integrity and
+  authenticity validation, during a secure or trusted boot process.
+
+Attestation
+  The API provides primitives used in attestation
+  activities. Attestation is the ability for a device to sign an array
+  of bytes with a device private key and return the result to the
+  caller. There are several use cases; ranging from attestation of the
+  device state, to the ability to generate a key pair and prove that it
+  has been generated inside a secure key store. The API provides access
+  to the algorithms commonly used for attestation.
+
+Factory Provisioning
+  Most IoT devices receive a unique identity during the factory
+  provisioning process, or once they have been deployed to the
+  field. This API provides the APIs necessary for populating a device
+  with keys that represent that identity.
+
+Usage considerations
+********************
+
+Always check for errors
+  Most functions in the PSA Crypto API can return errors. All functions
+  that can fail have the return type ``psa_status_t``. A few functions
+  cannot fail, and thus, return void or some other type.
+
+  If an error occurs, unless otherwise specified, the content of the
+  output parameters is undefined and must not be used.
+
+  Some common causes of errors include:
+
+  * In implementations where the keys are stored and processed in a
+    separate environment from the application, all functions that need
+    to access the cryptography processing environment might fail due
+    to an error in the communication between the two environments.
+
+  * If an algorithm is implemented with a hardware accelerator, which
+    is logically separate from the application processor, the
+    accelerator might fail, even when the application processor keeps
+    running normally.
+
+  * Most functions might fail due to a lack of resources. However,
+    some implementations guarantee that certain functions always have
+    sufficient memory.
+
+  * All functions that access persistent keys might fail due to a
+    storage failure.
+
+  * All functions that require randomness might fail due to a lack of
+    entropy. Implementations are encouraged to seed the random
+    generator with sufficient entropy during the execution of
+    ``psa_crypto_init()``. However, some security standards require
+    periodic reseeding from a hardware random generator, which can
+    fail.
+
+Shared memory and concurrency
+  Some environments allow applications to be multithreaded, while
+  others do not. In some environments, applications can share memory
+  with a different security context. In environments with
+  multithreaded applications or shared memory, applications must be
+  written carefully to avoid data corruption or leakage. This
+  specification requires the application to obey certain constraints.
+
+  In general, the PSA Crypto API allows either one writer or any number of
+  simultaneous readers, on any given object. In other words, if two or
+  more calls access the same object concurrently, then the behavior is
+  only well-defined if all the calls are only reading from the object
+  and do not modify it. Read accesses include reading memory by input
+  parameters and reading keystore content by using a key. For more
+  details, refer to `Concurrent calls
+  <https://arm-software.github.io/psa-api/crypto/1.2/overview/conventions.html#concurrent-calls>`_
+
+  If an application shares memory with another security context, it
+  can pass shared memory blocks as input buffers or output buffers,
+  but not as non-buffer parameters. For more details, refer to
+  `Stability of parameters <https://arm-software.github.io/psa-api/crypto/1.2/overview/conventions.html#stability-of-parameters>`_.
+
+Cleaning up after use
+  To minimize impact if the system is compromised, it is recommended
+  that applications wipe all sensitive data from memory when it is no
+  longer used. That way, only data that is currently in use can be
+  leaked, and past data is not compromised.
+
+  Wiping sensitive data includes:
+
+  * Clearing temporary buffers in the stack or on the heap.
+
+  * Aborting operations if they will not be finished.
+
+  * Destroying keys that are no longer used.
+
+References
+**********
+
+* `PSA Crypto`_
+
+.. _PSA Crypto:
+   https://arm-software.github.io/psa-api/crypto/
+
+* `Mbed TLS`_
+
+.. _Mbed TLS:
+   https://www.trustedfirmware.org/projects/mbed-tls/