libssl

Active contributors: Matt Caswell, Hugo Landau, Tomas Mraz, Pauli, Neil Horman

Purpose

libssl implements TLS 1.0–1.3 (RFC 8446), DTLS 1.0–1.2 (RFC 6347), and QUIC v1 (RFC 9000, with HTTP/3 demonstrated in demos/http3/). It builds on libcrypto's EVP API for all crypto and exposes a single connection-oriented API surface to applications: SSL_CTX, SSL, the BIO pair (SSL_set_bio, SSL_set_rbio/SSL_set_wbio), and operations like SSL_connect, SSL_accept, SSL_read, SSL_write, SSL_shutdown, SSL_handle_events (for QUIC).

Directory layout

ssl/
├── ssl_lib.c            226 KB  -- main connection state machine façade (largest hand-written file)
├── ssl_local.h          114 KB  -- the core internal struct definitions (SSL, SSL_CTX, …)
├── s3_lib.c             149 KB  -- TLS-version-shared cipher / extension tables
├── t1_lib.c             173 KB  -- TLS 1.0–1.3 protocol-level helpers
├── tls13_enc.c           34 KB  -- TLS 1.3 key schedule / HKDF wiring
├── t1_enc.c              19 KB  -- TLS 1.0–1.2 record protection
├── ssl_cert.c, ssl_cert_comp.c  -- certificate handling and compression
├── ssl_ciph.c            72 KB  -- the ciphersuite list parser ("HIGH:!aNULL:!eNULL:…")
├── ssl_conf.c            38 KB  -- runtime configuration plumbing
├── ssl_sess.c            42 KB  -- session caching, tickets, resumption
├── ssl_stat.c                   -- human-readable handshake state strings
├── d1_lib.c, d1_msg.c, d1_srtp.c -- DTLS top-level
├── methods.c                    -- SSL_METHOD vtables (TLS_method, DTLS_method, …)
├── bio_ssl.c                    -- BIO that wraps an SSL connection
├── pqueue.c, priority_queue.c   -- priority queues used by DTLS / QUIC
├── tls_srp.c, tls_depr.c        -- SRP, deprecated TLS hooks
├── statem/                      -- handshake state machine
│   ├── statem.c, statem_lib.c, statem_local.h
│   ├── statem_clnt.c, statem_srvr.c, statem_dtls.c
│   └── extensions.c, extensions_clnt.c, extensions_srvr.c, extensions_cust.c
├── record/                      -- pluggable record layer
│   ├── methods/                 -- record method implementations (TLS, DTLS, QUIC, SSL3)
│   ├── rec_layer_s3.c           -- TLS record glue
│   ├── rec_layer_d1.c           -- DTLS record glue
│   └── record.h, record_local.h
├── rio/                         -- RIO event-driven I/O abstraction (for QUIC)
├── ech/                         -- Encrypted Client Hello
├── quic/                        -- QUIC v1
└── README.md (under statem/)

Key abstractions

Type	What it is	File
SSL_CTX	Per-listener config (certs, trust store, sessions, callbacks). Shared across many SSL connections.	ssl/ssl_local.h, ssl/ssl_lib.c
SSL	Per-connection state. Owns the handshake state, peer cert, in-flight buffers.	ssl/ssl_local.h, ssl/ssl_lib.c
SSL_METHOD	A vtable selecting protocol family (TLS_method, TLS_client_method, DTLS_method, …).	ssl/methods.c, ssl/ssl_local.h
OSSL_RECORD_METHOD	The pluggable record layer interface.	ssl/record/record.h, ssl/record/methods/
OSSL_HANDSHAKE_STATE, MSG_PROCESS_RETURN, WORK_STATE	The state machine's enums.	ssl/statem/statem_local.h
SSL_SESSION	A resumable session (ID-based or via NewSessionTicket).	ssl/ssl_sess.c
SSL_CIPHER	A single ciphersuite.	ssl/ssl_ciph.c
SSL_QUIC_* (QUIC)	The QUIC channel, port, transport-params, etc.	ssl/quic/quic_*.c

How a TLS connection flows

sequenceDiagram
    participant App
    participant SSL as ssl_lib.c
    participant SM as ssl/statem/
    participant Rec as ssl/record/
    participant BIO as transport BIO
    participant EVP as libcrypto/EVP
    App->>SSL: SSL_connect(ssl)
    SSL->>SM: ossl_statem_client_dispatch
    SM->>Rec: write ClientHello
    Rec->>BIO: BIO_write(transport_bio, record)
    BIO-->>Rec: ServerHello, EncryptedExtensions, Cert, …
    Rec->>SM: process record
    SM->>EVP: EVP_PKEY_verify (cert), EVP_KDF (HKDF), EVP_CIPHER (AEAD), …
    SM->>SSL: state -> CONNECTED
    SSL-->>App: 1
    App->>SSL: SSL_write(buf)
    SSL->>Rec: encrypt application data
    Rec->>BIO: BIO_write

The record layer (ssl/record/) and the state machine (ssl/statem/) are deliberately separate. The state machine generates and consumes message bytes; the record layer wraps them in TLS records (or DTLS datagrams or QUIC packets). The split is what makes the QUIC integration tractable: QUIC reuses the TLS state machine but plugs in its own record method (ssl/quic/quic_record_*.c) and its own packetization (ssl/quic/quic_txp.c, quic_rx_depack.c).

For the handshake walk-through, see features/tls. For QUIC, see features/quic.

Public API

The single biggest header in the project is include/openssl/ssl.h.in (~3,400 lines). The most-used surface:

Function	Purpose
SSL_CTX_new, SSL_CTX_set_*, SSL_CTX_free	Listener config
SSL_new, SSL_set_fd, SSL_set_bio, SSL_free	Connection lifecycle
SSL_connect, SSL_accept, SSL_do_handshake	Drive the handshake
SSL_read, SSL_read_ex, SSL_write, SSL_write_ex	Application data
SSL_shutdown	Close-notify exchange
SSL_get_error	Decode return values
SSL_set_min/max_proto_version, SSL_set_cipher_list, SSL_set_ciphersuites	Version and ciphersuite policy
SSL_use_certificate, SSL_use_PrivateKey, SSL_CTX_load_verify_locations	Identity and trust
SSL_set_alpn_protos, SSL_get0_alpn_selected	ALPN
SSL_set_tlsext_host_name	SNI
SSL_get_session, SSL_set_session	Session resumption
SSL_get_peer_certificate (and SSL_get0_peer_certificate)	Peer identity
QUIC: SSL_new_quic_listener, SSL_new_stream, SSL_handle_events, SSL_get_event_timeout	See features/quic
ECH: SSL_CTX_ech_*, SSL_ech_*	See doc/designs/ech-api.md

Configuration via openssl.cnf

libssl honors an [ssl_conf] section in openssl.cnf for system-wide TLS defaults. The parser hooks in ssl/ssl_mcnf.c, the per-key handlers in ssl/ssl_conf.c. See reference/configuration.

DTLS specifics

DTLS shares 90% of the code with TLS: a different SSL_METHOD vtable, the DTLS-specific state machine in ssl/statem/statem_dtls.c, the DTLS record layer in ssl/record/rec_layer_d1.c, datagram retransmission and out-of-order handling in ssl/d1_lib.c. SRTP keying-material exporter is in ssl/d1_srtp.c.

Integration points

• Below: every record-protection cipher (AES-128-GCM, CHACHA20-POLY1305, AES-128-CCM, …), every signature verification, every HKDF call, every X.509 chain build goes through libcrypto's EVP layer. There is no crypto code in libssl other than tiny glue (e.g. the TLS 1.3 key-schedule label strings).
• Above: applications either use the BIO pair (set a transport BIO with SSL_set_bio) or hand the SSL object a file descriptor with SSL_set_fd. For QUIC the application also drives an event loop via SSL_handle_events + SSL_get_event_timeout.
• apps/s_client and apps/s_server are the canonical reference applications. They are also the largest files in apps/ (~145 KB and ~150 KB).

Entry points for modification

• Adding a TLS extension: edit ssl/statem/extensions.c to add the extension descriptor entry, then implement the per-side handlers in ssl/statem/extensions_clnt.c / extensions_srvr.c. Add tests under test/sslapitest.c.
• Adding a TLS 1.3 named group or signature scheme: extend the tables at the top of ssl/t1_lib.c and add the corresponding KEM/signature call in ssl/tls13_enc.c / the key-share / cert-verify logic.
• Modifying the record layer: add or modify a method under ssl/record/methods/.
• Modifying QUIC behavior: see features/quic for the file-by-file map.

Documentation entry points

• doc/man3/SSL_CTX_*.pod, doc/man3/SSL_*.pod — API reference.
• doc/man7/ssl.pod, doc/man7/ossl-guide-tls-*.pod — concepts and tutorials.
• doc/man7/openssl-quic.pod — QUIC concepts.
• doc/designs/ech-api.md, doc/designs/quic-design/ — design notes.
• ssl/statem/README.md — internal note on the state machine.