Skip to content

Platform_Integration.md

Latest commit

 

History

History
113 lines (79 loc) · 4.28 KB

Platform_Integration.md

File metadata and controls

113 lines (79 loc) · 4.28 KB

Platform Integration

Platform integration consist of several tasks, which are discussed in this chapter.

Provide Template with "USE" directives for System Crypto Configuration

To make the job of a system crypto configurator as easy as possible, a template file with the appropriate "use" directives should be provided for the target platform. See Crypto Configuration for more information.

Provide Key Storage Implementation

An implementation of the PSA key storage mechanism must be provided for the target platform. For this purpose, the following file must be adapted:

  • library/psa_its_file.c

For demonstration purposes, this file assumes that the file-based implementation of library/psa_crypto_storage.c will be used. For production systems, the latter needs to be replaced by some other suitable implementation.

See the specification of the PSA Secure Storage API for more information.

Provide Mutex Implementation

If an application uses a multithreading runtime, the platform must provide an adapter to the runtime's version of a mutex. The following items must be provided, through implementation or forwarding to a compatible implementation:

  • oberon_mutex_type
  • oberon_mutex_init
  • oberon_mutex_lock
  • oberon_mutex_unlock
  • oberon_mutex_free

They are located in oberon/drivers/oberon_helpers.h.

In order to use the provided mutex implementation, the C directive OBERON_USE_MUTEX must be defined in the above file.

Note: In the standard version of oberon_helpers.h, when using Mbed TLS and MBEDTLS_THREADING_C, forwarding to the corresponding Mbed TLS abstractions is already provided.

Provide Hardware Drivers

If the target platform – or some of its family members if it supports an entire family of chips – provide hardware crypto acceleration, corresponding hardware drivers should be provided. See Crypto Driver Development for more information. If a hardware driver does not come with a hardware driver crypto configuration header file, the platform integrator needs to create one for it.

Provide Platform Crypto Configuration

Once the set of available hardware drivers for a target platform is known, the platform crypto configuration must be adapted accordingly. A demo configuration is provided at:

  • oberon/platforms/demo/

It includes mock drivers located in subdirectory drivers/, example configurations located in subdirectory example_config/ (see Appendix C: System Crypto Configuration Examples), default driver configuration and context type definition headers located in include/psa/, and a default driver wrappers implementation located in library/.

Provide Crypto Driver Configuration

The crypto driver configuration file provided in oberon/platforms/demo/ must be adapted and placed in:

  • include/psa/crypto_driver_config.h

In this file, there should be one # include statement to the hardware driver crypto configuration file for every hardware driver. The rest of the file must not be modified.

Adapt the Driver Wrappers

To make the set of available hardware drivers known to Oberon PSA Crypto and its configuration mechanism, the driver wrappers C file provided in oberon/platforms/demo/ must be adapted and placed in:

  • library/psa_crypto_driver_wrappers.c

See the PSA documentation regarding the naming rules that must be obeyed in this file.

The following header files provided in oberon/platforms/demo/ may need to be extended to include the context data types (operation types):

  • psa/crypto_driver_contexts_primitives.h
  • psa/crypto_driver_contexts_composites.h
  • psa/crypto_driver_contexts_key_derivation.h

When Using Other Driver Wrappers

When using another driver wrappers implementation than the one provided with Oberon PSA Crypto, make sure that the situation is correctly handled where operation->id is not recognized in a configuration. In such a situation:

  • The psa_driver_wrapper_*_abort functions must return PSA_SUCCESS.
  • All other functions (except psa_driver_wrapper_*_setup) must return PSA_ERROR_BAD_STATE.

To learn about driver development, continue with chapter Crypto Driver Development.