Skip to content

Latest commit

 

History

History
executable file
·
180 lines (121 loc) · 6.01 KB

README.md

File metadata and controls

executable file
·
180 lines (121 loc) · 6.01 KB
Raw

README

Oberon PSA Crypto Repo

Oberon PSA Crypto is a software library 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 optimized for resource-constrained microcontrollers: it is focused in particular on small memory footprint and high speed in software for hardware that contains only limited – or no – hardware crypto accelerators.

The library is compatible with the PSA Certified Crypto API version as specified in PSA Certified Crypto API 1.2.1 and PAKE extension 1.2 Final 1, and to Arm's Mbed TLS 3.6.0.

The supported crypto feature set is documented in Appendix A: Supported Crypto Features.

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

The Oberon PSA Crypto repo is a clone of Arm's MBed TLS repo, with most files that are not needed for PSA Crypto compatibility stripped away. Mbed TLS files that have been modified by Oberon contain a NOTICE line.

The files originating from Mbed TLS are contained in the following subdirectories:

  • include
  • library
  • tests

The following directory contains the source code of the Oberon drivers. They depend on the ocrypto library (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 Certified Functional APIs Architecture Test Suite:

  • api-tests

The following directory contains incoming licenses of third-party software or third-party specifications:

  • licenses-incoming

You can find more information on licensing and copyrights in documents LICENSING and LICENSE.

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 the cryptographic functions from Mbed TLS:

  • programs

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

  • CHANGELOG.md

The following file contains the current software version:

  • VERSION

Migrate from Mbed TLS crypto code

If you want to migrate from Mbed TLS 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 Certified APIs Architecture 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.

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 build for a set of configurations, with PSA-related Mbed TLS tests, a PSA Certified APIs Architecture Test Suite, and in variants with and without multi-threading support based on the POSIX mutex reference implemenentation.

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

  • PSA-related Mbed TLS tests: -DCONFIG_MBEDTLS_PSA_TESTS=ON/OFF
  • PSA Certified APIs Architecture Test Suite: DCONFIG_PSA_API_TESTS=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.