# zephyrproject-rtos/mbedtls architecture

> Architecture diagram of the GitHub repository zephyrproject-rtos/mbedtls, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zephyrproject-rtos/mbedtls
- Repository: https://github.com/zephyrproject-rtos/mbedtls

## Overview

The Mbed TLS project is a security-focused, embedded cryptographic library written in C. Its primary purpose is to offer reliable implementations of cryptographic primitives, X.509 certificate handling, and secure communication protocols (SSL/TLS and DTLS), with specific considerations for embedded systems. In addition, it provides a reference implementation of the PSA Cryptography API and supports drivers for hardware accelerators and secure elements.

##### Main Components
- Library Core Modules – These include the cryptographic primitives, X.509 certificate handling, and the SSL/TLS/DTLS protocols. Note that the code is split into several libraries:
– libmbedcrypto (handling low-level cryptographic algorithms)
– libmbedx509 (handling X.509 certificates, CRLs, etc.)
– libmbedtls (the main TLS/DTLS implementation, which depends on the other two)
- PSA Cryptography API & Drivers – Represent the abstraction layer for cryptography that distinguishes between software implementations and hardware/drivers (under "psa" related files inside include, library, and 3rdparty folders).
- Third-Party Components – Highlight the modules under “3rdparty” such as Everest and p256-m, which are integrated to provide extra cryptographic support.
- Configuration and Build Mechanisms – This is shown by the directories and files such as “configs”, “cmake”, “Makefile”, and Visual Studio solution files. It shows support for different build systems (GNU Make, CMake, Visual Studio) and diverse configuration settings (through “mbedtls_config.h” and scripts like “scripts/config.py”).
- Example Programs – Use the “programs” directory to indicate sample usage and demonstration of Mbed TLS capabilities.
- Auxiliary Tools and Scripts – Include the numerous scripts (in “scripts”, “framework”, and subfolders) used for generating source files, checking configuration, and maintaining code style.

##### Relationships and Interactions
o libmbedtls → depends on libmbedx509 and libmbedcrypto.
o libmbedx509 → depends on libmbedcrypto.
- How the PSA Cryptography API serves as an adaptor layer that can route cryptographic operations either to in-software implementations or to external drivers.
- Integration of third-party components as “modules” that supplement core cryptographic functionalities.
- Build systems (Make, CMake, Visual Studio) as separate configuration nodes that produce the final library binaries.
- Test suites feeding back into the development cycle, ensuring compatibility across configurations.

##### Architectural Patterns and Design Principles
- Modular Design – Emphasize the project’s clear separation into independent yet interdependent libraries.
- Abstraction Layers – Illustrate how the PSA layer hides implementation details and supports algorithm agility and driver integration.
- Configurability – The central role of “mbedtls_config.h” and various build scripts (Python, Perl, shell) indicate that the library is highly configurable and supports multiple target platforms.
- Cross-platform and Embedded Focus – Note the attention to minimizing resource footprint (small code footprint for embedded systems) and portability (multiple build systems and configuration options).

##### Relevant Technologies and Tools
- C99 standard for the core code.
- Build systems: GNU Make, CMake, Microsoft Visual Studio.
- Documentation tools: Doxygen and ReadTheDocs.
- Scripting languages: Python and Perl for generating source files, tests, and configuration.
- External dependencies: Dependencies on cryptographic standards and integration of PSA specifications.

##### Elements
- Clear labels for each component/module (e.g., “libmbedtls – TLS/DTLS”, “libmbedcrypto – Cryptographic Primitives”, “PSA Cryptography API”, “Configuration & Build System”, “Test Suite”, “Third-party Modules”).
o Library inter-dependencies (showing how one module depends on another).
o Data flow where cryptographic operations use the PSA interface to reach either internal implementations or external drivers.
o Flow from configuration files to generated files to compiled binaries.
- Connections indicating build system support, showing that multiple build targets (Make, CMake, Visual Studio) all build the three primary libraries.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Development & Build Layer
    subgraph "Development & Build"
        Config("Configuration & Build"):::config
        Aux("Auxiliary Tools & Scripts"):::tools
        Test("Test Suite & Documentation"):::test
        Example("Example Programs"):::example
    end

    %% Core Libraries Layer
    subgraph "Core Libraries"
        Crypto("libmbedcrypto\n(Cryptographic Primitives)"):::core
        X509("libmbedx509\n(X.509 Certificate Handling)"):::core
        TLS("libmbedtls\n(TLS/DTLS Implementation)"):::core
    end

    %% PSA Component
    PSA("PSA Cryptography API & Drivers"):::psa

    %% Third-Party Components Layer
    subgraph "Third-Party Components"
        Everest("Everest"):::thirdparty
        P256("p256-m"):::thirdparty
    end

    %% Relationships within Core Libraries
    TLS -->|"depends_on"| X509
    TLS -->|"depends_on"| Crypto
    X509 -->|"depends_on"| Crypto

    %% Integration with PSA Layer
    PSA -->|"abstracts"| Crypto
    PSA -->|"abstracts"| X509

    %% Third-Party Integration with Core Libraries
    Crypto -->|"integrates_with"| Everest
    Crypto -->|"integrates_with"| P256

    %% Development & Build to Core & PSA layers
    Config -->|"builds"| Crypto
    Config -->|"builds"| X509
    Config -->|"builds"| TLS
    Config -->|"configures"| PSA
    Aux -->|"supports"| Config
    Test -->|"validates"| Crypto
    Test -->|"validates"| X509
    Test -->|"validates"| TLS
    Example -->|"demonstrates"| TLS

    %% Click Events
    click Crypto "https://github.com/zephyrproject-rtos/mbedtls/tree/zephyr/library/"
    click X509 "https://github.com/zephyrproject-rtos/mbedtls/blob/zephyr/library/x509.c"
    click TLS "https://github.com/zephyrproject-rtos/mbedtls/blob/zephyr/library/ssl_tls.c"
    click PSA "https://github.com/zephyrproject-rtos/mbedtls/blob/zephyr/include/psa/crypto.h"
    click Everest "https://github.com/zephyrproject-rtos/mbedtls/tree/zephyr/3rdparty/everest/"
    click P256 "https://github.com/zephyrproject-rtos/mbedtls/tree/zephyr/3rdparty/p256-m/"
    click Config "https://github.com/zephyrproject-rtos/mbedtls/blob/zephyr/configs/mbedtls_config.h"
    click Test "https://github.com/zephyrproject-rtos/mbedtls/tree/zephyr/tests/"
    click Example "https://github.com/zephyrproject-rtos/mbedtls/tree/zephyr/programs/psa/"
    click Aux "https://github.com/zephyrproject-rtos/mbedtls/blob/zephyr/scripts/config.py"

    %% Styles
    classDef core fill:#F9C74F,stroke:#333,stroke-width:2px;
    classDef psa fill:#90BE6D,stroke:#333,stroke-width:2px;
    classDef config fill:#577590,stroke:#fff,stroke-width:2px,color:#fff;
    classDef test fill:#F94144,stroke:#333,stroke-width:2px;
    classDef example fill:#F3722C,stroke:#333,stroke-width:2px;
    classDef tools fill:#277DA1,stroke:#333,stroke-width:2px,color:#fff;
    classDef thirdparty fill:#4D908E,stroke:#333,stroke-width:2px;
```
