# openziti/tlsuv architecture

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

- Interactive diagram: https://gitdiagram.com/openziti/tlsuv
- Repository: https://github.com/openziti/tlsuv

## Overview

TLSUV is a cross-platform asynchronous TLS communication library built around libuv. The main workflow is an application establishing a stream connection, driving a TLS handshake and encrypted I/O, then optionally using the HTTP or WebSocket client APIs. Its TLS engine is selectable, with documented OpenSSL, mbedTLS, Windows crypto, and BoringSSL implementations; certificate/key support and PKCS#11 are additional capabilities. The README documents these capabilities, but several implementation excerpts are incomplete, so uncertain internal wiring is omitted.

Main entry points: [`src/http.c`](https://github.com/openziti/tlsuv/blob/main/src/http.c) (HTTP client), [`src/tls_engine.c`](https://github.com/openziti/tlsuv/blob/main/src/tls_engine.c) (Engine selection), [`src/tlsuv.c`](https://github.com/openziti/tlsuv/blob/main/src/tlsuv.c) (TLS stream), [`include/tlsuv/tls_engine.h`](https://github.com/openziti/tlsuv/blob/main/include/tlsuv/tls_engine.h) (TLS engine API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_transport["Async transport"]
  node_stream["TLS stream<br/>[tlsuv.c]"]
  node_connector["Connector<br/>[connector.c]"]
  node_socket["Socket I/O<br/>[socket.c]"]
  node_tlslink["TLS link<br/>[tls_link.c]"]
end

subgraph group_clients["Protocol clients"]
  node_http["HTTP client<br/>[http.c]"]
  node_httpreq["HTTP requests<br/>[http_req.c]"]
  node_url["URL parsing<br/>[url.c]"]
  node_websocket["WebSocket client<br/>[websocket.c]"]
  node_compression["HTTP compression<br/>[compression.c]"]
end

subgraph group_tls["TLS engines"]
  node_engineapi["TLS engine API<br/>[tls_engine.h]"]
  node_factory["Engine selection<br/>[tls_engine.c]"]
  node_openssl["OpenSSL engine<br/>[engine.c]"]
  node_mbedtls["mbedTLS engine<br/>[engine.c]"]
  node_boringssl["BoringSSL engine<br/>[engine.c]"]
  node_wincrypto["Windows crypto<br/>[engine.c]"]
end

subgraph group_identity["Keys and identity"]
  node_keychain["Platform keychain<br/>[keychain.c]"]
  node_applekey["Apple keychain<br/>[keychain.c]"]
  node_winkey["Windows keychain<br/>[win32_keychain.c]"]
  node_pkcs["PKCS&#35;11 support<br/>[p11.c]"]
end

node_app(("Application"))
node_uv["libuv"]
node_peer(("Remote peer"))
node_pkcsprovider["PKCS&#35;11 provider"]

node_app -->|"creates stream"| node_stream
node_stream -->|"connects through"| node_connector
node_connector -->|"uses event loop"| node_uv
node_connector -->|"establishes I/O"| node_socket
node_socket -->|"exchanges bytes"| node_peer
node_stream -->|"drives TLS I/O"| node_tlslink
node_tlslink -->|"gets context"| node_factory
node_factory -->|"selects implementation"| node_openssl
node_factory -.->|"selects implementation"| node_mbedtls
node_factory -.->|"selects implementation"| node_boringssl
node_factory -.->|"selects implementation"| node_wincrypto
node_openssl -->|"implements API"| node_engineapi
node_mbedtls -->|"implements API"| node_engineapi
node_boringssl -->|"implements API"| node_engineapi
node_wincrypto -->|"implements API"| node_engineapi
node_app -->|"uses client"| node_http
node_http -->|"handles requests"| node_httpreq
node_http -->|"parses addresses"| node_url
node_http -->|"uses transport"| node_stream
node_http -->|"compresses content"| node_compression
node_app -->|"uses client"| node_websocket
node_websocket -->|"uses transport"| node_stream
node_keychain -.->|"uses platform backend"| node_applekey
node_keychain -.->|"uses platform backend"| node_winkey
node_openssl -.->|"supports keys"| node_pkcs
node_pkcs -.->|"accesses tokens"| node_pkcsprovider

click node_stream "https://github.com/openziti/tlsuv/blob/main/src/tlsuv.c"
click node_connector "https://github.com/openziti/tlsuv/blob/main/src/connector.c"
click node_socket "https://github.com/openziti/tlsuv/blob/main/src/socket.c"
click node_tlslink "https://github.com/openziti/tlsuv/blob/main/src/tls_link.c"
click node_http "https://github.com/openziti/tlsuv/blob/main/src/http.c"
click node_httpreq "https://github.com/openziti/tlsuv/blob/main/src/http_req.c"
click node_url "https://github.com/openziti/tlsuv/blob/main/src/url.c"
click node_websocket "https://github.com/openziti/tlsuv/blob/main/src/websocket.c"
click node_compression "https://github.com/openziti/tlsuv/blob/main/src/compression.c"
click node_engineapi "https://github.com/openziti/tlsuv/blob/main/include/tlsuv/tls_engine.h"
click node_factory "https://github.com/openziti/tlsuv/blob/main/src/tls_engine.c"
click node_openssl "https://github.com/openziti/tlsuv/blob/main/src/openssl/engine.c"
click node_mbedtls "https://github.com/openziti/tlsuv/blob/main/src/mbedtls/engine.c"
click node_boringssl "https://github.com/openziti/tlsuv/blob/main/src/boringssl/engine.c"
click node_wincrypto "https://github.com/openziti/tlsuv/blob/main/src/win32crypto/engine.c"
click node_keychain "https://github.com/openziti/tlsuv/blob/main/src/keychain.c"
click node_applekey "https://github.com/openziti/tlsuv/blob/main/src/apple/keychain.c"
click node_winkey "https://github.com/openziti/tlsuv/blob/main/src/win32/win32_keychain.c"
click node_pkcs "https://github.com/openziti/tlsuv/blob/main/src/p11.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_stream,node_connector,node_socket,node_tlslink toneBlue
class node_http,node_httpreq,node_url,node_websocket,node_compression toneAmber
class node_engineapi,node_factory,node_openssl,node_mbedtls,node_boringssl,node_wincrypto toneMint
class node_keychain,node_applekey,node_winkey,node_pkcs toneRose
class node_app,node_uv,node_peer,node_pkcsprovider toneIndigo
```

## Components

### Async transport

- [TLS stream](https://github.com/openziti/tlsuv/blob/main/src/tlsuv.c): `src/tlsuv.c`
- [Connector](https://github.com/openziti/tlsuv/blob/main/src/connector.c): `src/connector.c`
- [Socket I/O](https://github.com/openziti/tlsuv/blob/main/src/socket.c): `src/socket.c`
- [TLS link](https://github.com/openziti/tlsuv/blob/main/src/tls_link.c): `src/tls_link.c`

### Protocol clients

- [HTTP client](https://github.com/openziti/tlsuv/blob/main/src/http.c): `src/http.c`
- [HTTP requests](https://github.com/openziti/tlsuv/blob/main/src/http_req.c): `src/http_req.c`
- [URL parsing](https://github.com/openziti/tlsuv/blob/main/src/url.c): `src/url.c`
- [WebSocket client](https://github.com/openziti/tlsuv/blob/main/src/websocket.c): `src/websocket.c`
- [HTTP compression](https://github.com/openziti/tlsuv/blob/main/src/compression.c): `src/compression.c`

### TLS engines

- [TLS engine API](https://github.com/openziti/tlsuv/blob/main/include/tlsuv/tls_engine.h): `include/tlsuv/tls_engine.h`
- [Engine selection](https://github.com/openziti/tlsuv/blob/main/src/tls_engine.c): `src/tls_engine.c`
- [OpenSSL engine](https://github.com/openziti/tlsuv/blob/main/src/openssl/engine.c): `src/openssl/engine.c`
- [mbedTLS engine](https://github.com/openziti/tlsuv/blob/main/src/mbedtls/engine.c): `src/mbedtls/engine.c`
- [BoringSSL engine](https://github.com/openziti/tlsuv/blob/main/src/boringssl/engine.c): `src/boringssl/engine.c`
- [Windows crypto](https://github.com/openziti/tlsuv/blob/main/src/win32crypto/engine.c): `src/win32crypto/engine.c`

### Keys and identity

- [Platform keychain](https://github.com/openziti/tlsuv/blob/main/src/keychain.c): `src/keychain.c`
- [Apple keychain](https://github.com/openziti/tlsuv/blob/main/src/apple/keychain.c): `src/apple/keychain.c`
- [Windows keychain](https://github.com/openziti/tlsuv/blob/main/src/win32/win32_keychain.c): `src/win32/win32_keychain.c`
- [PKCS#11 support](https://github.com/openziti/tlsuv/blob/main/src/p11.c): `src/p11.c`

### Other components

- **Application**
- **libuv**
- **Remote peer**
- **PKCS#11 provider**

## Connections

- Application → TLS stream: creates stream
- TLS stream → Connector: connects through
- Connector → libuv: uses event loop
- Connector → Socket I/O: establishes I/O
- Socket I/O → Remote peer: exchanges bytes
- TLS stream → TLS link: drives TLS I/O
- TLS link → Engine selection: gets context
- Engine selection → OpenSSL engine: selects implementation
- Engine selection → mbedTLS engine: selects implementation
- Engine selection → BoringSSL engine: selects implementation
- Engine selection → Windows crypto: selects implementation
- OpenSSL engine → TLS engine API: implements API
- mbedTLS engine → TLS engine API: implements API
- BoringSSL engine → TLS engine API: implements API
- Windows crypto → TLS engine API: implements API
- Application → HTTP client: uses client
- HTTP client → HTTP requests: handles requests
- HTTP client → URL parsing: parses addresses
- HTTP client → TLS stream: uses transport
- HTTP client → HTTP compression: compresses content
- Application → WebSocket client: uses client
- WebSocket client → TLS stream: uses transport
- Platform keychain → Apple keychain: uses platform backend
- Platform keychain → Windows keychain: uses platform backend
- OpenSSL engine → PKCS#11 support: supports keys
- PKCS#11 support → PKCS#11 provider: accesses tokens