TLS Record Protocol

Hex Dump Annotator

Each TLS record begins with a 5-byte header. Paste or inspect a hex dump to see each field annotated. The first byte is the content type (23 = application_data in TLS 1.3), followed by version, length, and the encrypted payload.

Encryption / Decryption Flow

Walk through how a plaintext TLS record becomes ciphertext and back. Each step is annotated; hover or click the steps to highlight them.

TLS 1.2 Record Layer

TLS 1.2 uses a composition of separate primitives: a stream or block cipher for encryption, plus a separate HMAC for integrity. The order of operations (MAC-then-encrypt vs encrypt-then-MAC) matters enormously for security.

TLS 1.3 AEAD Record Protocol

TLS 1.3 uses only AEAD ciphers. AEAD means authentication and encryption are combined into a single primitive — there's no way to separate them, no padding to worry about, and no MAC-then-encrypt vs encrypt-then-MAC debate.

{`# AEAD encryption in TLS 1.3 (RFC 8446 §5.2)
#
# Each record is encrypted as:
#   nonce = XOR(sequence_number, write_iv)
#   ciphertext = AEAD-Encrypt(write_key, nonce, aad, plaintext)
#   auth_tag   = last 16 bytes of AEAD output
#
# AAD (Additional Authenticated Data) = TLS record header:
#   stream_protocol_version || content_type || 0..0 padding to length 13
#   i.e., the first 13 bytes of the TLS 1.3 record header (before length)
#
# This binds the ciphertext to the record metadata, preventing
# an attacker from stripping the record and re-appending it to another connection.

# For AES-GCM (TLS_AES_128_GCM_SHA256):
#   key    = 16 bytes (128-bit AES key)
#   nonce  = 12 bytes (sequence_number XOR write_iv)
#   AAD    = 13 bytes (TLS record header)
#   tag    = 16 bytes (GMAC output)
#   overhead per record = 16 bytes (authentication tag)

# For ChaCha20-Poly1305 (TLS_CHACHA20_POLY1305_SHA256):
#   key    = 32 bytes
#   nonce  = 12 bytes (same XOR construction)
#   AAD    = 13 bytes (same record header)
#   tag    = 16 bytes (Poly1305 output)
#   overhead per record = 16 bytes

# For the receiver:
#   nonce = XOR(decrypted_sequence_number, read_iv)
#   plaintext = AEAD-Decrypt(read_key, nonce, aad, ciphertext || auth_tag)
#   If decryption fails → fatal alert: bad_record_mac
#   This is an ALL-OR-NOTHING check: no partial plaintext leaks timing info.

# QUIC (RFC 9000) replaces the TLS record layer entirely.
# QUIC data is encrypted frame-by-frame with per-frame AAD,
# where the AAD is the QUIC packet header (not the TLS record header).
# This gives QUIC additional metadata protection that TLS 1.3 doesn't have.`}

Sequence Numbers and Replay Prevention

Every TLS record carries a 64-bit sequence number incremented per record. The sequence number is used to construct the per-record nonce for AEAD ciphers, and a separate counter per direction (read vs write) ensures records from each direction are independent.

{`# TLS sequence number: 64-bit unsigned integer
# Per connection, per direction:
#   client_write_sequence_number  (incremented per sent record)
#   server_write_sequence_number  (incremented per sent record)
#   client_read_sequence_number   (incremented per received record)
#   server_read_sequence_number   (incremented per received record)
#
# The sequence number is NOT sent on the wire as plaintext — it's implicit.
# The receiver knows which record it's receiving based on arrival order.
# The 64-bit counter overflow wraps at 2^64-1.

# Why sequence numbers matter:
# 1. Nonce uniqueness for AEAD ciphers:
#      nonce = seq_num XOR write_iv
#    If the same (key, nonce) pair is ever reused, GCM breaks catastrophically.
#    (GCM mode with nonce reuse: keystream leaks, authentication breaks)
#
# 2. Replay detection (0-RTT in TLS 1.3):
#    The server maintains a anti-replay window of accepted 0-RTT records.
#    Records with sequence numbers outside the window are rejected.
#    A record with a duplicate sequence number (inside the window) is dropped.
#    This prevents an attacker from replaying previously recorded 0-RTT data.
#
# 3. Connection drying:
#    After a KeyUpdate, both sides increment sequence numbers from 0
#    for the new epoch. The AEAD key is bound to the epoch number.

# Python: demonstrate AEAD nonce construction
python3 << 'EOF'
import struct
seq_num = 0x0000000000000041   # 65th record
write_iv = bytes.fromhex('00112233445566778899aabbcc')  # 12 bytes
nonce = bytes(a ^ b for a, b in zip(
    struct.pack('!Q', seq_num).rjust(12, b'\x00'),  # seq num as 12 bytes
    write_iv
))
print("Seq num (hex):", hex(seq_num))
print("Write IV:     ", write_iv.hex())
print("Nonce:        ", nonce.hex())
# Nonce = write_iv XOR seq_num (with leading zeros)
EOF`}

Key Derivation: Master Secret and Key Expansion

TLS 1.2 derives a 48-byte master_secret from the pre-master secret (from the key exchange), then expands it into write keys, IVs, and MAC keys for each direction. TLS 1.3 replaced this with the HKDF key schedule.

{`# TLS 1.2 key derivation (RFC 5246 §6.3)
#
# master_secret = PRF(pre_master_secret, "master secret", client_random || server_random)
#
# Key block (extracted from master_secret):
#   client_write_MAC_key[0..hash_length-1]
#   server_write_MAC_key[0..hash_length-1]
#   client_write_key[0..key_length-1]
#   server_write_key[0..key_length-1]
#   client_write_IV[0..IV_length-1]
#   server_write_IV[0..IV_length-1]
#
# key_block = PRF(master_secret, "key expansion", server_random || client_random)
# Keys are sliced from key_block sequentially.
# For AES-128-GCM: 16-byte write_key + 4-byte salt (IV partial) = 20 bytes per direction.
# For ChaCha20: 32-byte key.

# TLS 1.3 HKDF key schedule (RFC 8446 §7.1)
# HKDF-Extract(ZERO, ECDHE_shared_secret) = handshake_secret
# HKDF-Expand-Label derives per-secret traffic secrets.
#
# Each traffic secret is expanded into key + nonce:
#   client_write_key = HKDF-Expand-Label(
#       client_application_traffic_secret_0,
#       "key", "", 16)       # 16-byte AES key
#   client_write_iv  = HKDF-Expand-Label(
#       client_application_traffic_secret_0,
#       "iv",  "", 12)       # 12-byte IV
#
# KeyUpdate is an explicit message that rotates to a new traffic secret
# without a new handshake — much simpler than renegotiation in TLS 1.2.

# Verify key derivation with OpenSSL
openssl s_client -connect example.com:443 -tls1_3 &1 \
  | grep -E "SSL-Session|key material"
# Or dump with traffic secret logging (requires debug build):
#   OPENSSL_ENABLE_DEBUG_TLS=1 openssl s_server ...`}

TLS 1.2 CBC Mode Details

For CBC-based TLS 1.2 cipher suites (now discouraged), the block cipher processes 16-byte blocks with padding appended. This padding is the source of the POODLE attack — an attacker who can inject a record into a connection can exploit the padding oracle to recover plaintext.

{`# AES-CBC in TLS 1.2:
# Block size: 16 bytes. Padding: 1..16 bytes appended.
# Padded plaintext: [data][MAC][padding_length_bytes]
# If data+MAC is not a multiple of 16: pad.
# padding_length byte = number of padding bytes (including itself).
# Example: if 9 bytes needed to fill block, padding_length = 0x09.
#
# Encryption:
#   IV = client_write_IV (first record: random; subsequent: prev_ciphertext)
#   Block 0: CIPH(IV XOR plaintext[0:16])
#   Block 1: CIPH(ciphertext[0:16] XOR plaintext[16:32])
#   ...
#   ciphertext = IV || cblock0 || cblock1 || ...
#
# Decryption (vulnerable to padding oracle):
#   Decrypt all blocks
#   Check last byte of last block: value = padding_length
#   Remove padding_length bytes
#   Strip MAC bytes, verify HMAC
#
# POODLE (CVE-2014-3566): TLS uses block cipher padding in a way that
# some servers accept a padding_length byte that is inside the MAC,
# allowing an attacker to guess one byte of plaintext per attempt.
# Mitigation: disable all CBC cipher suites (use GCM/ChaCha20).

# Lucky13 (CVE-2013-0169): timing side-channel in CBC processing.
# An attacker measures response time differences when MAC verification
# fails at different stages. Fix: constant-time MAC verification.
# TLS 1.3 eliminates CBC modes entirely → no Lucky13.

# Check which cipher modes your server offers:
openssl s_client -connect example.com:443 -tls1_2 -cipher 'AES128' 2>&1 \
  | grep -i "cipher\|error"
# If any AES-CBC cipher is negotiated, consider disabling TLS 1.2 or
# using a cipher string like: ECDHE+AESGCM:ECDHE+CHACHA20`}

Record Types and Content Types

TLS carries multiple record types over the same connection after the handshake, distinguished by the content type in the record header. TLS 1.3 encrypts all types post-handshake, making traffic analysis harder.

{`# In TLS 1.3, the content type is wrapped in a "outer" record:
#   outer: content_type = 23 (application_data)
#   inner: content_type = payload type inside the encrypted payload
#
# This means the content type visible to the network is always 23
# for application_data records — traffic analysis becomes harder.
# In TLS 1.2, an observer could see that record type 22 (handshake)
# was still being exchanged after ClientHello, leaking metadata.

# Heartbleed (CVE-2014-0160):
# The heartbeat extension (RFC 6520) lets a client send:
#   heartbeat_request: payload || padding
#   Server responds with: payload (echoed back) || padding
# No bounds check: server reads beyond payload length into adjacent memory.
# Fix: always bounds-check reads; OpenSSL 1.0.1g adds the check.
# Detection: check for heartbeat in server hello:
openssl s_client -connect example.com:443 -tls1_2 &1 \
  | grep -i "heartbeat"

# Alert levels (content type 21 = alert)
#   1 = warning  (e.g., close_notify, no_certificate)
#   2 = fatal   (e.g., bad_record_mac, handshake_failure, internal_error)
# Alert descriptions: ~30 defined alert types.
# All alerts are encrypted in TLS 1.3 (even close_notify was visible in TLS 1.2).`}

Tradeoffs

FAQ