TLS Support Overview
Relevant source files
The following files were used as context for generating this wiki page:
The TLS (Transport Layer Security) support in librelp provides a secure mechanism for transmitting syslog messages over the Reliable Event Logging Protocol. It enables encryption, data integrity, and peer authentication for RELP transactions. The implementation is designed to be library-agnostic, supporting both GnuTLS and OpenSSL as backends to facilitate secure communication between RELP clients and servers.
TLS is initiated via the starttls command, which switches a standard TCP connection into TLS mode, similar to the ESMTP STARTTLS mechanism. This ensures that while the initial session setup (offers and version negotiation) may occur in plaintext, the subsequent data transmission is protected.
Sources: doc/relp.html:125-126, src/tcp.c:48-73, src/librelp.h:159-160
Architecture and Library Abstraction
Librelp utilizes a generic TLS support layer that abstracts calls between the core RELP engine and specific TLS libraries. The system detects and utilizes either GnuTLS (default) or OpenSSL based on the engine configuration.
Supported Libraries
| Library | Engine ID | Header Files |
|---|---|---|
| GnuTLS | RELP_USE_GNUTLS (0) | gnutls/gnutls.h, gnutls/x509.h |
| OpenSSL | RELP_USE_OPENSSL (1) | openssl/ssl.h, openssl/x509v3.h, openssl/err.h |
Sources: src/tcp.h:58-62, src/librelp.h:163-165, src/tcp.c:48-73
Logical Flow of TLS Initialization
The following diagram illustrates how librelp decides which backend to initialize during a connection attempt.
Sources: src/tcp.c:1326-1343, src/tcp.c:1367-1383
Authentication Modes
Librelp supports several authentication modes to verify the identity of the remote peer. These are defined in the relpAuthMode_t enumeration.
| Mode | Enumeration Value | Description |
|---|---|---|
| None | eRelpAuthMode_None (0) | No authentication; often used with anonymous DH. |
| Fingerprint | eRelpAuthMode_Fingerprint (1) | Peer's certificate SHA1 fingerprint is checked against a permitted list. |
| Name | eRelpAuthMode_Name (2) | Subject Common Name (CN) or Subject Alternative Name (SAN) is verified. |
| CertValid | eRelpAuthMode_CertValid (3) | Validates that the certificate is signed by a trusted CA without specific name checks. |
Sources: src/librelp.h:98-103, src/tcp.c:380-410, src/tcp.c:1130-1175
Peer Name Verification Logic
When eRelpAuthMode_Name is used, the library extracts names from the certificate and compares them against permitted peers.
Sources: src/tcp.c:1130-1175, src/tcp.c:422-480
Configuration and API
Developers configure TLS properties on either the client (relpClt) or server (relpSrv) objects before finalizing the connection.
Key TLS Configuration Functions
relpCltEnableTLS/relpSrvEnableTLS2: Enables the TLS requirement for the object.relpTcpSetCACert: Sets the path to the Certificate Authority (CA) bundle.relpTcpSetOwnCert/relpTcpSetPrivKey: Sets the local identity certificates for mutual authentication.relpTcpSetGnuTLSPriString: Configures the priority string for GnuTLS (ciphers, protocols).relpTcpSetTlsConfigCmd: Provides a mechanism for OpenSSL-specific configuration commands viaSSL_CONF_cmd.
Sources: src/librelp.h:207-225, src/tcp.c:690-755, src/tcp.c:918-984
Permitted Peers and Wildcards
The library supports wildcard matching for permitted peer names (e.g., *.example.com). These are "compiled" into a tcpPermittedPeerWildcardComp_t structure for efficient matching during the handshake.
Sources: src/tcp.h:49-75, src/tcp.c:1040-1100
Handshake and Retry Mechanism
Because TLS operations can be interrupted (returning EAGAIN or WANT_READ/WRITE), librelp implements a retry state machine. The relpTcpRtryState_t tracks whether the engine needs to resume a handshake, a receive operation, or a send operation.
Handshake Retry Sequence
- Initiate:
relpTcpConnectTLSInitis called. - Execution: The backend (GnuTLS/OpenSSL) attempts the handshake.
- Interruption: If the socket would block,
rtryOpis set torelpTCP_RETRY_handshake. - Resumption: The engine calls
relpTcpRtryHandshakewhen the socket is ready for I/O.
Sources: src/tcp.h:38-41, src/tcp.c:880-916, src/tcp.c:1435-1456
Summary
TLS support in librelp is a critical module for secure logging. It leverages a dual-backend architecture supporting GnuTLS and OpenSSL, provides robust peer validation through multiple authentication modes, and handles asynchronous network I/O through a dedicated retry state machine. This ensures that reliable delivery is coupled with industry-standard encryption and identity verification.
Sources: src/tcp.c:1-40, doc/relp.html:125-126