# mbed-tls/mbedtls architecture

> Architecture diagram of the GitHub repository mbed-tls/mbedtls, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mbed-tls/mbedtls
- Repository: https://github.com/mbed-tls/mbedtls

## Overview

Mbed TLS is a C library for X.509 certificate processing and TLS/DTLS secure channels, backed by PSA cryptography. The principal workflow is an application configuring a client or server, opening transport, performing a TLS/DTLS handshake, validating certificates and deriving keys, then exchanging protected records. X.509 utilities provide a separate certificate/CSR/CRL workflow. The graph reflects sampled client, TLS 1.2/1.3, DTLS, socket, certificate, cache and ticket code; unsampled server details are represented only where the tree supports them.

Main entry points: [`library/ssl_tls.c`](https://github.com/mbed-tls/mbedtls/blob/development/library/ssl_tls.c) (TLS Orchestrator), [`programs/ssl/ssl_client2.c`](https://github.com/mbed-tls/mbedtls/blob/development/programs/ssl/ssl_client2.c) (TLS Applications), [`library/ssl_tls12_client.c`](https://github.com/mbed-tls/mbedtls/blob/development/library/ssl_tls12_client.c) (TLS 1.2 Protocol), [`library/ssl_tls13_client.c`](https://github.com/mbed-tls/mbedtls/blob/development/library/ssl_tls13_client.c) (TLS 1.3 Protocol)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Applications"]
  node_tls_apps["TLS Applications<br/>[ssl_client2.c]"]
  node_tls_server_app["TLS Server Apps<br/>[ssl_server.c]"]
  node_x509_tools["X.509 Utilities<br/>[cert_app.c]"]
end

subgraph group_protocol["TLS Protocol"]
  node_tls_core["TLS Orchestrator<br/>[ssl_tls.c]"]
  node_client_builder["Client Handshake<br/>[ssl_client.c]"]
  node_tls12["TLS 1.2 Protocol<br/>[ssl_tls12_client.c]"]
  node_tls13["TLS 1.3 Protocol<br/>[ssl_tls13_client.c]"]
  node_tls12_server["TLS 1.2 Server<br/>[ssl_tls12_server.c]"]
  node_record_layer["Record Layer<br/>[ssl_msg.c]"]
end

subgraph group_trust["Trust Crypto"]
  node_x509_engine["X.509 Engine<br/>[x509.c]"]
  node_cert_parser["Certificate Parser<br/>[x509_crt.c]"]
  node_cert_writers["Certificate Writers<br/>[x509write.c]"]
  node_psa_crypto["PSA Crypto"]
  node_key_schedule["TLS Key Schedule<br/>[ssl_tls13_keys.c]"]
end

subgraph group_transport["Transport State"]
  node_net["Socket Transport<br/>[net_sockets.c]"]
  node_dtls_timing["DTLS Timing<br/>[timing.c]"]
  node_session_cache["Session Cache<br/>[ssl_cache.c]"]
  node_session_tickets["Session Tickets<br/>[ssl_ticket.c]"]
end

node_developer(("Application User"))
node_peer(("TLS Peer"))

node_developer -->|"configures"| node_tls_apps
node_developer -->|"configures"| node_tls_server_app
node_developer -->|"requests"| node_x509_tools
node_tls_apps -->|"opens socket"| node_net
node_tls_apps -->|"calls TLS API"| node_tls_core
node_tls_server_app -->|"opens socket"| node_net
node_tls_server_app -->|"calls TLS API"| node_tls_core
node_tls_core -->|"builds hello"| node_client_builder
node_tls_core -->|"dispatches TLS 1.2"| node_tls12
node_tls_core -->|"dispatches TLS 1.3"| node_tls13
node_tls_core -->|"dispatches server"| node_tls12_server
node_tls_core -->|"processes records"| node_record_layer
node_client_builder -->|"offers extensions"| node_tls12
node_client_builder -->|"offers TLS 1.3"| node_tls13
node_tls12 -->|"validates certificates"| node_cert_parser
node_tls13 -->|"derives keys"| node_key_schedule
node_tls12 -->|"handles tickets"| node_session_tickets
node_tls13 -->|"handles tickets"| node_session_tickets
node_tls_core -->|"uses cache"| node_session_cache
node_key_schedule -->|"uses cryptography"| node_psa_crypto
node_cert_parser -->|"parses certificates"| node_x509_engine
node_x509_engine -->|"verifies signatures"| node_psa_crypto
node_x509_tools -->|"reads certificates"| node_cert_parser
node_x509_tools -->|"writes artifacts"| node_cert_writers
node_record_layer -->|"sends records"| node_net
node_tls_apps -.->|"configures DTLS"| node_dtls_timing
node_tls_core -.->|"drives timers"| node_dtls_timing
node_net -->|"carries traffic"| node_peer

click node_tls_apps "https://github.com/mbed-tls/mbedtls/blob/development/programs/ssl/ssl_client2.c"
click node_tls_server_app "https://github.com/mbed-tls/mbedtls/blob/development/programs/ssl/ssl_server.c"
click node_x509_tools "https://github.com/mbed-tls/mbedtls/blob/development/programs/x509/cert_app.c"
click node_tls_core "https://github.com/mbed-tls/mbedtls/blob/development/library/ssl_tls.c"
click node_client_builder "https://github.com/mbed-tls/mbedtls/blob/development/library/ssl_client.c"
click node_tls12 "https://github.com/mbed-tls/mbedtls/blob/development/library/ssl_tls12_client.c"
click node_tls13 "https://github.com/mbed-tls/mbedtls/blob/development/library/ssl_tls13_client.c"
click node_tls12_server "https://github.com/mbed-tls/mbedtls/blob/development/library/ssl_tls12_server.c"
click node_record_layer "https://github.com/mbed-tls/mbedtls/blob/development/library/ssl_msg.c"
click node_x509_engine "https://github.com/mbed-tls/mbedtls/blob/development/library/x509.c"
click node_cert_parser "https://github.com/mbed-tls/mbedtls/blob/development/library/x509_crt.c"
click node_cert_writers "https://github.com/mbed-tls/mbedtls/blob/development/library/x509write.c"
click node_key_schedule "https://github.com/mbed-tls/mbedtls/blob/development/library/ssl_tls13_keys.c"
click node_net "https://github.com/mbed-tls/mbedtls/blob/development/library/net_sockets.c"
click node_dtls_timing "https://github.com/mbed-tls/mbedtls/blob/development/library/timing.c"
click node_session_cache "https://github.com/mbed-tls/mbedtls/blob/development/library/ssl_cache.c"
click node_session_tickets "https://github.com/mbed-tls/mbedtls/blob/development/library/ssl_ticket.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_tls_apps,node_tls_server_app,node_x509_tools,node_developer toneBlue
class node_tls_core,node_client_builder,node_tls12,node_tls13,node_tls12_server,node_record_layer toneAmber
class node_x509_engine,node_cert_parser,node_cert_writers,node_psa_crypto,node_key_schedule toneMint
class node_net,node_dtls_timing,node_session_cache,node_session_tickets toneRose
class node_peer toneIndigo
```

## Components

### Applications

- [TLS Applications](https://github.com/mbed-tls/mbedtls/blob/development/programs/ssl/ssl_client2.c): `programs/ssl/ssl_client2.c`
- [TLS Server Apps](https://github.com/mbed-tls/mbedtls/blob/development/programs/ssl/ssl_server.c): `programs/ssl/ssl_server.c`
- [X.509 Utilities](https://github.com/mbed-tls/mbedtls/blob/development/programs/x509/cert_app.c): `programs/x509/cert_app.c`

### TLS Protocol

- [TLS Orchestrator](https://github.com/mbed-tls/mbedtls/blob/development/library/ssl_tls.c): `library/ssl_tls.c`
- [Client Handshake](https://github.com/mbed-tls/mbedtls/blob/development/library/ssl_client.c): `library/ssl_client.c`
- [TLS 1.2 Protocol](https://github.com/mbed-tls/mbedtls/blob/development/library/ssl_tls12_client.c): `library/ssl_tls12_client.c`
- [TLS 1.3 Protocol](https://github.com/mbed-tls/mbedtls/blob/development/library/ssl_tls13_client.c): `library/ssl_tls13_client.c`
- [TLS 1.2 Server](https://github.com/mbed-tls/mbedtls/blob/development/library/ssl_tls12_server.c): `library/ssl_tls12_server.c`
- [Record Layer](https://github.com/mbed-tls/mbedtls/blob/development/library/ssl_msg.c): `library/ssl_msg.c`

### Trust Crypto

- [X.509 Engine](https://github.com/mbed-tls/mbedtls/blob/development/library/x509.c): `library/x509.c`
- [Certificate Parser](https://github.com/mbed-tls/mbedtls/blob/development/library/x509_crt.c): `library/x509_crt.c`
- [Certificate Writers](https://github.com/mbed-tls/mbedtls/blob/development/library/x509write.c): `library/x509write.c`
- **PSA Crypto**
- [TLS Key Schedule](https://github.com/mbed-tls/mbedtls/blob/development/library/ssl_tls13_keys.c): `library/ssl_tls13_keys.c`

### Transport State

- [Socket Transport](https://github.com/mbed-tls/mbedtls/blob/development/library/net_sockets.c): `library/net_sockets.c`
- [DTLS Timing](https://github.com/mbed-tls/mbedtls/blob/development/library/timing.c): `library/timing.c`
- [Session Cache](https://github.com/mbed-tls/mbedtls/blob/development/library/ssl_cache.c): `library/ssl_cache.c`
- [Session Tickets](https://github.com/mbed-tls/mbedtls/blob/development/library/ssl_ticket.c): `library/ssl_ticket.c`

### Other components

- **Application User**
- **TLS Peer**

## Connections

- Application User → TLS Applications: configures
- Application User → TLS Server Apps: configures
- Application User → X.509 Utilities: requests
- TLS Applications → Socket Transport: opens socket
- TLS Applications → TLS Orchestrator: calls TLS API
- TLS Server Apps → Socket Transport: opens socket
- TLS Server Apps → TLS Orchestrator: calls TLS API
- TLS Orchestrator → Client Handshake: builds hello
- TLS Orchestrator → TLS 1.2 Protocol: dispatches TLS 1.2
- TLS Orchestrator → TLS 1.3 Protocol: dispatches TLS 1.3
- TLS Orchestrator → TLS 1.2 Server: dispatches server
- TLS Orchestrator → Record Layer: processes records
- Client Handshake → TLS 1.2 Protocol: offers extensions
- Client Handshake → TLS 1.3 Protocol: offers TLS 1.3
- TLS 1.2 Protocol → Certificate Parser: validates certificates
- TLS 1.3 Protocol → TLS Key Schedule: derives keys
- TLS 1.2 Protocol → Session Tickets: handles tickets
- TLS 1.3 Protocol → Session Tickets: handles tickets
- TLS Orchestrator → Session Cache: uses cache
- TLS Key Schedule → PSA Crypto: uses cryptography
- Certificate Parser → X.509 Engine: parses certificates
- X.509 Engine → PSA Crypto: verifies signatures
- X.509 Utilities → Certificate Parser: reads certificates
- X.509 Utilities → Certificate Writers: writes artifacts
- Record Layer → Socket Transport: sends records
- TLS Applications → DTLS Timing: configures DTLS
- TLS Orchestrator → DTLS Timing: drives timers
- Socket Transport → TLS Peer: carries traffic
