README

Oberon PSA Crypto

Oberon PSA Crypto is a software product developed by Oberon microsystems. It implements the PSA Certified Crypto API specification, which aims at standardizing a cryptography API for embedded systems. Oberon PSA Crypto is a lightweight implementation of this API and is optimized for resource-constrained microcontrollers: it is focused in particular on small memory footprint and high speed - in software, hardware, and in mixed hardware/software configurations.

The software is compatible with the PSA Certified Crypto API version as specified in PSA Certified Crypto API, and is aligned with the current version of Arm's TF-PSA-Crypto. For the currently supported API versions, see the Compatibility section in the CHANGELOG document.

The software consists of a portable PSA Crypto Core that exposes the PSA Certified Crypto API. It delegates crypto processing to a number of software crypto drivers (Oberon drivers) that can be mixed and matched with vendor-specific hardware drivers, where available.

The crypto feature set supported by the core and the software drivers is documented in Appendix A: Supported Crypto Features.

The software passes the PSA API Test Suite for cryptographic functions and thereby demonstrates compliance with the standard. See the official PSA Certified Crypto API compliance certificate.

The Oberon PSA Crypto repo is derived from Arm's TF-PSA-Crypto repo, with most files that are not needed for PSA Crypto compatibility stripped away. TF-PSA-Crypto files that have been modified by Oberon contain a NOTICE line.

Some files originating from TF-PSA-Crypto or Mbed TLS are contained in the following subdirectories.

Main PSA components of the product (apart from the Oberon drivers, see below):

• include
• core
• dispatch

Extra functionality that is not part of the PSA standard and is provided for Mbed TLS- or TF-PSA-Crypto-compatibility:

• platform
• utilities
• extras
• legacy_sub

Test code, can also be used as example code showing the API usage:

• api-tests
• programs
• framework
• tests
• val_common

The following directory contains the source code of the Oberon drivers. Some of them depend on the ocrypto software product (which is not included in this repo):

• oberon/drivers

The following directory contains the documentation of Oberon PSA Crypto:

• oberon/docs

For reading the documentation, it is recommended to start with Documentation Overview.

The following directory contains sketches of platform-specific system crypto configurations and mock crypto driver implementations. This code is intended as starting point useful for system crypto configurators, platform integrators and crypto driver developers. They are not intended to be used as production code and no guarantees are given that they can be built and run as is:

• oberon/platforms

The following directory contains a copy of the PSA API Test Suite:

• api-tests

The following directory contains a README-SSL and a CMake file for building the ssl_server2 and ssl_client2 examples and SSL tests from Mbed TLS, using Oberon PSA Crypto instead of TF-PSA-Crypto:

• programs

The following file contains the change history of Oberon PSA Crypto:

• CHANGELOG.md

For every release, API compatibility information is given regarding the PSA Certified Crypto API version that is supported.

The following file contains licensing information:

• LICENSING.md

The following file contains the current software version:

• VERSION

Migrate from TF-PSA-Crypto

If you want to migrate from TF-PSA-Crypto to Oberon PSA Crypto, please see Appendix D: Mbed TLS.

Build with CMake

Oberon PSA Crypto can be built and tested on a host with CMake (MacOS/clang or Windows/MSVC). Mbed TLS Tests have been generated from Mbed TLS and copied to tests/generated. Some tests contain bug fixes. The PSA API Test Suite was copied from the main branch of https://github.com/ARM-software/psa-arch-tests.

Prerequisites

CMake version 3.13 or newer.

Compatible ocrypto release version, see CHANGELOG.md.

Note: Oberon PSA Crypto uses ocrypto as implementation of its crypto primitives. The provided CMake files can be used for a quick test on a host platform (Linux, Windows) and uses ocrypto's platform-independent implementation (no assembly language). When Oberon PSA Crypto is used on a microcontroller, please make sure that you use the platform-optimized code instead! It is located in ocrypto inside src/platforms/, e.g. folder src/platforms/M4F for Cortex-M4F, instead of the default folder Generic for the platform-independent code, which is far less optimized.

Functional certification tests for the PSA Certified Crypto API require Python3 and have been tested on macOS.

Build

Provide the path to ocrypto with CMake via -DOCRYPTO_ROOT=path/to/ocrypto or copy ocrypto sources with their src and include directories to path oberon/ocrypto in the repository.

Build the source in a separate directory build from the command line:

cd /path/to/this/repo
cmake -B build -DOCRYPTO_ROOT=path/to/ocrypto 
cmake --build build

Supported platforms with demonstration drivers, configurations, and includes are located in path oberon/platforms and can be provided to CMake via -DPLATFORM=folder_name.

Multi-threading support can be enabled with define MBEDTLS_THREADING_C in mbedtls_config.h.

Build with Tests

By default, Oberon PSA Crypto is built for a set of configurations, with PSA-related Mbed TLS tests, a PSA API Test Suite, and in variants with and without multi-threading support based on the POSIX mutex reference implementation.

To select for which tests Oberon PSA Crypto is built, the following CMAKE options are provided:

• PSA API Test Suite: -DCONFIG_PSA_API_TESTS=ON/OFF
• PSA-related Mbed TLS tests: -DCONFIG_MBEDTLS_PSA_TESTS=ON/OFF -DCONFIG_MBEDTLS_PSA_TESTS_LONG=ON/OFF
• Tests example configurations: -DCONFIG_TEST_EXAMPLE_CONFIGS=ON/OFF
• Multi-threading support: -DCONFIG_MBEDTLS_THREADING=ON/OFF

Run Tests

Run all tests from the same build directory:

cd build
ctest -C Debug

Run Mbed TLS PSA tests only:

cd build
ctest -L CONFIG_MBEDTLS_PSA_TESTS --verbose -C Debug

Run PSA certification tests only:

cd build
ctest -L CONFIG_PSA_API_TESTS --verbose -C Debug

Clean

Delete the build directory:

rm -rf build

Copyright and Licenses

See LICENSING.md file for copyright and licensing information.

Documentation

The documentation of Oberon PSA Crypto is organized as a sequence of markdown pages. It starts with the Documentation Overview and can be read sequentially. A number of appendices give additional information on special topics.

Bug Tracking and Security Vulnerabilities

Oberon PSA Crypto bugs and security vulnerabilities are tracked in document Bug Tracking.

This file by Oberon microsystems is licensed under the Creative Commons Attribution-ShareAlike 4.0 License.