TLS Authentication & Configuration

Relevant source files

The following files were used as context for generating this wiki page:

• src/tcp.c
• src/tcp.h
• src/librelp.h
• src/relp.h
• doc/relp.html
• tests/receive.c
• tests/send.c

The Transport Layer Security (TLS) implementation in librelp provides secure, encrypted communication channels for the Reliable Event Logging Protocol (RELP). It supports multiple backend libraries, primarily GnuTLS and OpenSSL, to handle the encryption handshake, certificate validation, and data integrity. TLS can be initiated via the starttls command, which switches a standard TCP connection into a secure mode.

The system is designed to be flexible, supporting various authentication modes ranging from anonymous Diffie-Hellman to strict certificate-based validation with peer name or fingerprint checking. This ensures that RELP transactions, which involve monotonically increasing transaction numbers (TXNR) for reliable delivery, are protected against eavesdropping and man-in-the-middle attacks.

Sources: doc/relp.html:150-151, src/tcp.c:48-90, src/librelp.h:68-74

Architecture and Backend Support

Librelp abstracts TLS operations through a generic support layer, allowing the engine to switch between GnuTLS and OpenSSL backends at runtime. The relpEngine_t structure maintains a tls_lib flag to determine which implementation to invoke for handshakes, sends, and receives.

The diagram shows how librelp routes generic TCP/TLS calls to specific library implementations based on the engine configuration.
Sources: src/relp.h:170, src/tcp.c:1662-1715

Key Data Structures

The relpTcp_t structure is the primary container for TLS state, including library-specific session handles and configuration parameters.

Field	Description	Source
bEnableTLS	Boolean flag to enable TLS mode.	src/tcp.h:120
bTLSActive	Indicates if the TLS handshake was successful and session is active.	src/tcp.h:121
session	GnuTLS session handle (GnuTLS backend).	src/tcp.h:134
ssl	OpenSSL SSL object (OpenSSL backend).	src/tcp.h:138
authmode	Defined authentication strategy (None, Name, Fingerprint, CertValid).	src/tcp.h:126
permittedPeers	ACL structure for validating peer identities.	src/tcp.h:128

Authentication Modes

Librelp supports four distinct authentication modes, configured via relpAuthMode_t.

1. Anonymous (None)

In this mode, encryption is provided without identity verification. It often uses Anonymous Diffie-Hellman (ADH).

• GnuTLS: Uses gnutls_anon_allocate_client_credentials.
• OpenSSL: Uses priority strings like ALL:+ADH:+aNULL.
  Sources: src/tcp.c:537-555, src/tcp.c:1345-1351

2. Certificate Validation (CertValid)

Verifies that the peer certificate is signed by a trusted Certificate Authority (CA) but does not check specific identities (Subject Names).
Sources: src/tcp.c:854-856, src/librelp.h:73

3. Peer Name (Name)

Extends CertValid by checking the Common Name (CN) or Subject Alternative Name (SAN) against a list of permitted peers.

• Logic: The system extracts DNS names from the SAN extension and the CN from the Distinguished Name (DN).
• Wildcards: Supports wildcard patterns (e.g., *.example.com).
  Sources: src/tcp.c:704-740, src/tcp.c:1145-1175

4. Fingerprint

Validates the peer based on a SHA1 hash of their certificate. This is useful for self-signed certificates or pinned-identity scenarios.
Sources: src/tcp.c:662-675, src/tcp.c:1086-1110

Connection Flow and Handshake

The TLS handshake occurs either during initial connection setup (for clients) or upon receiving a connection request (for servers). Because librelp uses non-blocking I/O, handshakes often require retries.

This sequence illustrates the transition from a plaintext RELP session to an encrypted one via the starttls mechanism.
Sources: doc/relp.html:150-155, src/tcp.c:1662-1678

Handshake Retry Logic

Librelp manages non-blocking handshakes using the rtryOp state in relpTcp_t. If gnutls_handshake() or SSL_connect() returns an "again" or "interrupted" status, the operation is flagged for retry during the next event loop cycle.
Sources: src/tcp.h:46-49, src/tcp.c:1010-1035

Configuration Interface

Configuration is handled through the API by setting attributes on the Client (relpClt) or Server (relpSrv) objects before finalizing the connection.

API Function	Purpose	File
relpSrvSetAuthMode	Sets the authentication strategy for the listener.	src/librelp.h:204
relpSrvSetCACert	Specifies the path to the CA bundle.	src/librelp.h:201
relpSrvSetTlsConfigCmd	Passes raw configuration strings to the underlying library (e.g., CipherString).	src/librelp.h:200
relpCltAddPermittedPeer	Adds an authorized identity for the client to verify against the server.	src/librelp.h:220
relpSrvSetDHBits	Configures the strength of Diffie-Hellman parameters (default 1024).	src/relp.h:54, src/librelp.h:196

Priority Strings and Custom Commands

Users can fine-tune TLS behavior using priority strings (GnuTLS) or configuration commands (OpenSSL).

• GnuTLS: Configured via relpTcpSetGnuTLSPriString, typically defaults to NORMAL.
• OpenSSL: Uses SSL_CONF_cmd to process key-value pairs like Protocol=ALL, CipherString=DEFAULT.
  Sources: src/tcp.c:537-560, src/tcp.c:882-944

Security Considerations

The implementation addresses several security risks through technical measures:

• Hostname Validation: To prevent malicious DNS attacks, the system can be configured to validate hostnames or reject connections from hosts with malicious PTR records.
• Certificate Expiration: The verify_callback handles certificate lifecycle events, logging warnings or aborting connections if certificates are expired.
• Encryption Strength: The default DH bits are set to 1024 to balance performance and security, though this is configurable.
  Sources: src/relp.h:54, src/tcp.c:612-635, src/tcp.c:800-820

Conclusion

TLS Authentication & Configuration in librelp provides a robust security layer for reliable logging. By supporting both GnuTLS and OpenSSL and offering granular authentication modes (Anonymous, Name, Fingerprint), it allows developers to secure data transmission according to specific organizational requirements. The integration of non-blocking handshake logic ensures that security does not compromise the high-concurrency architecture of the RELP engine.