Alerts & Error Handling

If something goes wrong (invalid certificate, bad MAC, decode error, etc.), TLS sends an Alert:

struct Alert {
    level (1 byte)        // 1 = warning, 2 = fatal
    description (1 byte)  // alert code
}

Common alert codes:

• 0 close_notify
• 10 unexpected_message
• 20 bad_record_mac
• 21 decryption_failed
• 22 record_overflow
• 40 handshake_failure
• 42 bad_certificate
• 43 unsupported_certificate
• 44 certificate_revoked
• 45 certificate_expired
• 46 certificate_unknown
• 47 illegal_parameter
• 48 unknown_ca
• 50 decode_error
• 51 decrypt_error
• 70 protocol_version
• 71 insufficient_security
• 80 internal_error
• 86 inappropriate_fallback
• 90 user_canceled
• 109 missing_extension
• 112 unrecognized_name
• 116 certificate_required

Alert handling rules:

• Most alerts are FATAL → immediately close connection.
• close_notify is the only normal way to end a TLS connection.
• A peer receiving a fatal alert must NOT continue.

Common debugging scenarios:

• bad_certificate (42): cert chain doesn't validate. Check chain order, missing intermediate, expired.
• unknown_ca (48): client doesn't trust the issuer. Add CA to trust store.
• handshake_failure (40): no overlap between client and server cipher suites/groups/sigalgs.
• protocol_version (70): client wants TLS 1.0; server only supports 1.3.

In TLS 1.3, alerts after the handshake are themselves encrypted (alert content type, sent in an ApplicationData record).