protocol-security

Protocol Security

Rules (for AI agents)

ALWAYS

• Default to TLS 1.3, and permit TLS 1.2 only where a peer genuinely requires it. Disable TLS 1.0, 1.1, and every SSL version. Cipher-suite selection is a consequence of the version floor rather than a separate decision — references/tls-configuration.md carries the suite lists and the per-platform config keys.
• Verify the full certificate chain on every connection: a trusted issuer, an unexpired validity window, and a hostname that matches a subjectAltName dNSName entry. The hostname is checked against the SAN — SAN is not an alternative place to look, and a CN match is not a fallback, because current browsers and TLS libraries removed CN as a hostname source.
• When connecting to an IP address rather than a name, set the expected name explicitly (ServerName in Go's tls.Config, the equivalent SNI/verification hostname elsewhere) so verification has something to check, or require a certificate carrying an iPAddress SAN. Reaching an endpoint by IP is the single most common reason a developer disables verification — this is the fix that keeps it on.
• Resolve a self-signed or internal-CA endpoint by adding that CA to the client's trust configuration, not by turning verification off. Every language has a way to supply a custom root pool; using it keeps hostname and expiry checks intact, which is exactly what the shortcut discards.
• Use mutual TLS for service-to-service traffic inside a trust domain, and treat it as what it is: a cryptographic caller identity, which is authentication — unlike network position, which is not. A SPIFFE workload identity (spiffe://trust-domain/...) with short-lived certificates is the form of this worth reaching for over a long-lived shared API key.
• For gRPC, build the channel with credentials: Python grpc.secure_channel(target, grpc.ssl_channel_credentials()), Go grpc.WithTransportCredentials( credentials.NewTLS(cfg)). The insecure variants exist for local development and say so in their names.
• For SMTP, either connect with implicit TLS (submissions, port 465) or issue STARTTLS on submission (port 587) and fail if the upgrade does not happen. An on-path attacker strips the server's STARTTLS advertisement and a client that treats TLS as opportunistic then sends credentials in plaintext without error. Verify the certificate after the upgrade, exactly as for any other connection.
• Track certificate expiry and automate renewal. An expired certificate is among the most common real transport incidents, and the pressure it creates is what produces the InsecureSkipVerify that outlives it.
• Consult frontend-security for HSTS and the browser response-header set, websocket-security for Origin validation and handshake authentication, database-security for database transport, and mobile-security before adding certificate pinning — that skill owns the rotation planning that decides whether a pin is a control or a future outage.