# header-only/bearssl architecture

> Architecture diagram of the GitHub repository header-only/bearssl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/header-only/bearssl
- Repository: https://github.com/header-only/bearssl

## Overview

BearSSL is a header-only cryptography and SSL/TLS library. An application includes its umbrella header, configures an SSL client or server, and exchanges records through the SSL engine; certificate validation and cryptographic algorithms provide supporting capabilities. The graph also preserves the library’s standalone crypto, PEM, and X.509 functionality. Some implementation files are unsampled, so uncertain internal links are omitted rather than inferred.

Main entry points: [`include/bearssl.h`](https://github.com/header-only/bearssl/blob/headeronly/include/bearssl.h) (Public APIs), [`include/bearssl/impl/x509/x509_minimal.hpp`](https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/x509/x509_minimal.hpp) (X.509 validation), [`include/bearssl/impl/ssl/ssl_engine.hpp`](https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/ssl/ssl_engine.hpp) (TLS record engine), [`include/bearssl/impl/ssl/ssl_engine_default_aesgcm.hpp`](https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/ssl/ssl_engine_default_aesgcm.hpp) (Record defaults)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api_tls["API and TLS"]
  node_umbrella["Umbrella API<br/>[bearssl.hpp]"]
  node_api_headers["Public APIs<br/>[bearssl.h]"]
  node_ssl_engine["TLS record engine<br/>[ssl_engine.hpp]"]
  node_handshake["TLS handshake<br/>[ssl_hs_client.hpp]"]
  node_client["TLS client"]
  node_server["TLS server"]
  node_record_defaults["Record defaults"]
end

subgraph group_crypto["Cryptography"]
  node_hashes["Hash functions<br/>[sha2small.hpp]"]
  node_hmac["HMAC<br/>[hmac.hpp]"]
  node_drbg["HMAC DRBG<br/>[hmac_drbg.hpp]"]
  node_symmetric["Symmetric ciphers<br/>[bearssl_block.h]"]
  node_rsa["RSA<br/>[rsa_i15_priv.hpp]"]
  node_ec["Elliptic curves<br/>[ec_p256_m15.hpp]"]
end

subgraph group_identity["Certificates and keys"]
  node_pem["PEM decoding<br/>[pemdec.hpp]"]
  node_x509_decode["Certificate decoding<br/>[x509_decoder.hpp]"]
  node_x509_validate["X.509 validation<br/>[x509_minimal.hpp]"]
  node_keys["Private-key decoding<br/>[skey_decoder.hpp]"]
end

node_application(("Application"))

node_application -->|"includes"| node_umbrella
node_umbrella -->|"exposes"| node_api_headers
node_api_headers -->|"declares TLS API"| node_ssl_engine
node_api_headers -->|"declares hashes"| node_hashes
node_api_headers -->|"declares HMAC"| node_hmac
node_api_headers -->|"declares PRNG"| node_drbg
node_api_headers -->|"declares ciphers"| node_symmetric
node_api_headers -->|"declares RSA"| node_rsa
node_api_headers -->|"declares curves"| node_ec
node_api_headers -->|"declares PEM"| node_pem
node_api_headers -->|"declares X.509"| node_x509_validate
node_client -.->|"uses handshake"| node_handshake
node_server -.->|"uses handshake"| node_handshake
node_ssl_engine -->|"delegates handshake"| node_handshake
node_ssl_engine -->|"configures records"| node_record_defaults
node_record_defaults -->|"selects AES"| node_symmetric
node_record_defaults -->|"selects GHASH"| node_hashes
node_x509_validate -->|"uses ECDSA support"| node_ec
node_x509_validate -.->|"validates signatures"| node_rsa
node_ssl_engine -->|"matches certificate name"| node_x509_validate
node_pem -.->|"decodes PEM input"| node_x509_decode
node_x509_decode -.->|"provides certificates"| node_x509_validate
node_keys -.->|"decodes keys"| node_rsa

click node_umbrella "https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/bearssl.hpp"
click node_api_headers "https://github.com/header-only/bearssl/blob/headeronly/include/bearssl.h"
click node_ssl_engine "https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/ssl/ssl_engine.hpp"
click node_handshake "https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/ssl/ssl_hs_client.hpp"
click node_client "https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/ssl/ssl_client_full.hpp"
click node_server "https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/ssl/ssl_server_full_rsa.hpp"
click node_record_defaults "https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/ssl/ssl_engine_default_aesgcm.hpp"
click node_hashes "https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/hash/sha2small.hpp"
click node_hmac "https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/mac/hmac.hpp"
click node_drbg "https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/rand/hmac_drbg.hpp"
click node_symmetric "https://github.com/header-only/bearssl/blob/headeronly/include/bearssl_block.h"
click node_rsa "https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/rsa/rsa_i15_priv.hpp"
click node_ec "https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/ec/ec_p256_m15.hpp"
click node_pem "https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/codec/pemdec.hpp"
click node_x509_decode "https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/x509/x509_decoder.hpp"
click node_x509_validate "https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/x509/x509_minimal.hpp"
click node_keys "https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/x509/skey_decoder.hpp"

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_umbrella,node_api_headers,node_ssl_engine,node_handshake,node_client,node_server,node_record_defaults toneBlue
class node_hashes,node_hmac,node_drbg,node_symmetric,node_rsa,node_ec toneAmber
class node_pem,node_x509_decode,node_x509_validate,node_keys toneMint
class node_application toneIndigo
```

## Components

### API and TLS

- [Umbrella API](https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/bearssl.hpp): `include/bearssl/bearssl.hpp`
- [Public APIs](https://github.com/header-only/bearssl/blob/headeronly/include/bearssl.h): `include/bearssl.h`
- [TLS record engine](https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/ssl/ssl_engine.hpp): `include/bearssl/impl/ssl/ssl_engine.hpp`
- [TLS handshake](https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/ssl/ssl_hs_client.hpp): `include/bearssl/impl/ssl/ssl_hs_client.hpp`
- [TLS client](https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/ssl/ssl_client_full.hpp): `include/bearssl/impl/ssl/ssl_client_full.hpp`
- [TLS server](https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/ssl/ssl_server_full_rsa.hpp): `include/bearssl/impl/ssl/ssl_server_full_rsa.hpp`
- [Record defaults](https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/ssl/ssl_engine_default_aesgcm.hpp): `include/bearssl/impl/ssl/ssl_engine_default_aesgcm.hpp`

### Cryptography

- [Hash functions](https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/hash/sha2small.hpp): `include/bearssl/impl/hash/sha2small.hpp`
- [HMAC](https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/mac/hmac.hpp): `include/bearssl/impl/mac/hmac.hpp`
- [HMAC DRBG](https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/rand/hmac_drbg.hpp): `include/bearssl/impl/rand/hmac_drbg.hpp`
- [Symmetric ciphers](https://github.com/header-only/bearssl/blob/headeronly/include/bearssl_block.h): `include/bearssl_block.h`
- [RSA](https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/rsa/rsa_i15_priv.hpp): `include/bearssl/impl/rsa/rsa_i15_priv.hpp`
- [Elliptic curves](https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/ec/ec_p256_m15.hpp): `include/bearssl/impl/ec/ec_p256_m15.hpp`

### Certificates and keys

- [PEM decoding](https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/codec/pemdec.hpp): `include/bearssl/impl/codec/pemdec.hpp`
- [Certificate decoding](https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/x509/x509_decoder.hpp): `include/bearssl/impl/x509/x509_decoder.hpp`
- [X.509 validation](https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/x509/x509_minimal.hpp): `include/bearssl/impl/x509/x509_minimal.hpp`
- [Private-key decoding](https://github.com/header-only/bearssl/blob/headeronly/include/bearssl/impl/x509/skey_decoder.hpp): `include/bearssl/impl/x509/skey_decoder.hpp`

### Other components

- **Application**

## Connections

- Application → Umbrella API: includes
- Umbrella API → Public APIs: exposes (evidence: `include/bearssl/bearssl.hpp`)
- Public APIs → TLS record engine: declares TLS API (evidence: `include/bearssl.h`)
- Public APIs → Hash functions: declares hashes (evidence: `include/bearssl.h`)
- Public APIs → HMAC: declares HMAC (evidence: `include/bearssl.h`)
- Public APIs → HMAC DRBG: declares PRNG (evidence: `include/bearssl.h`)
- Public APIs → Symmetric ciphers: declares ciphers (evidence: `include/bearssl.h`)
- Public APIs → RSA: declares RSA (evidence: `include/bearssl.h`)
- Public APIs → Elliptic curves: declares curves (evidence: `include/bearssl.h`)
- Public APIs → PEM decoding: declares PEM (evidence: `include/bearssl.h`)
- Public APIs → X.509 validation: declares X.509 (evidence: `include/bearssl.h`)
- TLS client → TLS handshake: uses handshake
- TLS server → TLS handshake: uses handshake
- TLS record engine → TLS handshake: delegates handshake
- TLS record engine → Record defaults: configures records (evidence: `include/bearssl/impl/ssl/ssl_engine_default_aesgcm.hpp`)
- Record defaults → Symmetric ciphers: selects AES (evidence: `include/bearssl/impl/ssl/ssl_engine_default_aesgcm.hpp`)
- Record defaults → Hash functions: selects GHASH (evidence: `include/bearssl/impl/ssl/ssl_engine_default_aesgcm.hpp`)
- X.509 validation → Elliptic curves: uses ECDSA support
- X.509 validation → RSA: validates signatures
- TLS record engine → X.509 validation: matches certificate name
- PEM decoding → Certificate decoding: decodes PEM input
- Certificate decoding → X.509 validation: provides certificates
- Private-key decoding → RSA: decodes keys
