Application developers normally need not be concerned with crypto drivers; they simply use the high-level PSA Certified Crypto API and have their system crypto configurators configure the crypto features that they want to use in their applications. Platform integrators are only concerned with these drivers insofar as they need to configure – for the particular target platform that they support – which hardware driver should be used for which crypto feature.
Driver developers create the drivers. Here, mainly hardware drivers are discussed. Driver developers need to have detailed know-how regarding the hardware crypto accelerators for which they write hardware drivers. Their drivers have to conform to the PSA Crypto Driver API. A driver implementation consists of a C header file and an implementation file that must adhere to the naming conventions specified by PSA Crypto.
Ideally, a template for how to integrate this driver into the driver wrappers file is provided to platform integrators.
How to write actual driver code is beyond the scope of this documentation. Please see the PSA Crypto Driver API documentation on GitHub.
In addition to the driver code, a crypto driver developer should also provide a
hardware driver crypto configuration file <driver-name>_psa_config.h. This
file contains C define directives of the form PSA_NEED_XXX that combine "want"
and "use" of crypto features in the sense of "if crypto feature XXX is both
wanted by the application and available in a driver for the platform, then this
driver's code and support code in the driver wrappers are needed". In other
words: the "needs" are the intersection of "wants" and "uses" and are necessary
to control dead code elimination during the build process.
The hardware driver crypto configuration must also indicate whether an
algorithm / key type / key size combination is hardware-accelerated or not, by
defining PSA_ACCEL_XXX directives accordingly. This information is needed to
prefer hardware drivers for a crypto feature over Oberon drivers for the
same feature.
See the provided mock example in oberon/platforms/demo/drivers/demo_driver_config.h for more information.
The PSA_NEED_XXX and PSA_ACCEL_XXX directives supported by Oberon PSA Crypto
are listed in
Appendix B: Crypto Configuration Directives.
Note: The JSON configuration files as defined in the PSA Crypto specification are not used by Oberon PSA Crypto. If a hardware driver comes without a hardware driver crypto configuration header file as described above, it must be provided by the platform integrator.
Oberon drivers come preconfigured as part of Oberon PSA Crypto. Their Oberon driver crypto configuration file is located at:
oberon/drivers/oberon_config.h
It must not be modified.
Most networked embedded applications use cryptographic random numbers in some way
or another. The random number generator in PSA Crypto requires an entropy
driver for its inputs. Please refer to the PSA Certified Crypto API
specification. A mock driver is provided in
oberon/platforms/demo/drivers/demo_entropy.c. It is not intended for
production purposes.
This section is mainly relevant for Oberon microsystems and its Oberon drivers. Oberon PSA Crypto supports a uniform way for crypto drivers to delegate functionality to other crypto drivers. For example, an HMAC Oberon driver – which is software-only – may delegate hashing operations to a SHA hardware driver. This process is called driver chaining and requires upcalls to the otherwise private driver wrappers API.
Some Oberon drivers are simple facades for ocrypto functions, while other Oberon drivers support driver chaining – wherever this is appropriate. In particular, the following driver chains are supported in Oberon PSA Crypto:
- Signature → Hash
- Deterministic signature → HMAC
- HKDF → HMAC
- HMAC → Hash
- CMAC → AES
- HMAC-DRBG → HMAC
- CTR-DRBG → AES-ECB, AES-CMAC
- DRBG → Entropy
- RSA → SHA
Driver chaining allows to highly optimize the mix of software and hardware implementations of cryptographic code.
Note: Hardware drivers do not need to implement driver chaining. Hardware crypto accelerators implement a set of cryptographic operations completely, i.e., without upcalls into software.