This PR fixes a critical bug in the mutual TLS implementation and improves documentation to clarify the distinction between different uses of CA certificates in node-to-node communication.

Issues Fixed

1. Critical Bug: Ignored Mutual Parameter

The NewTLSMux function was ignoring the mutual parameter, always passing false to the internal implementation:

// Before (buggy)
func NewTLSMux(ln net.Listener, adv net.Addr, cert, key, caCert string, insecure, mutual bool) (*Mux, error) {
    return newTLSMux(ln, adv, cert, key, caCert, false) // Always false!
}

// After (fixed)  
func NewTLSMux(ln net.Listener, adv net.Addr, cert, key, caCert string, insecure, mutual bool) (*Mux, error) {
    return newTLSMux(ln, adv, cert, key, caCert, mutual) // Now respects the parameter
}

This meant the -node-verify-client flag had no effect, as mutual TLS was never actually enabled.

2. Unclear Documentation

The documentation didn't clearly distinguish between two different uses of CA certificates:

• Server certificate validation: When a client connects to a server, it uses a CA cert to verify the server's certificate
• Mutual TLS client verification: When a server requires clients to present certificates, it uses a CA cert pool to verify client certificates

Changes Made

Enhanced Documentation

• Updated all TLS configuration function comments to clearly explain CA certificate usage
• Improved flag descriptions to clarify the roles of -node-ca-cert and -node-verify-client
• Added explanatory comments distinguishing server validation vs mutual TLS scenarios

Improved Logging

Enhanced startup logging to clarify CA certificate purpose based on configuration:

if cfg.NodeVerifyClient {
    b.WriteString(fmt.Sprintf(", CA cert %s (for client verification)", cfg.NodeX509CACert))
} else {
    b.WriteString(fmt.Sprintf(", CA cert %s (for server verification)", cfg.NodeX509CACert))
}

Comprehensive Testing

Added focused tests that verify:

• Mutual TLS is properly enabled when mutual=true
• Mutual TLS is properly disabled when mutual=false
• TLS configuration reflects the intended settings

Impact

This fix ensures that:

• The -node-verify-client flag now works as documented
• Users can properly configure mutual TLS for enhanced security
• Documentation clearly explains the distinction between different CA certificate uses
• Future development has better clarity around TLS configuration

The changes are surgical and focused, fixing the specific bug while improving clarity without breaking existing functionality.

Fixes #2209.

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.