protocol-security

• SKILL.mdcore · 6,057 bytes
• SKILL.mdcore · 6,057 bytes
• metadata.jsonasset · 1,384 bytes
• references/tls-configuration.mddoc · 9,194 bytes
• references/verifying-findings.mddoc · 4,018 bytes

<!-- Native skill bundle for agent-skills (cross-tool convention). Generated by `secure-vibe dev regenerate`. -->
<!-- Do not edit by hand; the source of truth is skills/protocol-security/SKILL.md. -->

# Protocol Security

Transport security where the client establishes trust: TLS version floor, certificate chain and hostname verification, the trust store, connecting by IP, mTLS and workload identity as authentication, gRPC channel credentials, and SMTP STARTTLS. Use when generating HTTP, gRPC, or SMTP clients and servers, configuring TLS in code or platform config, wiring service-to-service authentication, or when tempted to disable certificate verification.

## 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.