module

Raft::Transport::Handshake

Mutual HMAC-SHA256 cookie authentication for TCP connections.

Uses standard TLV framing (type 0x00 for handshake, 0xFF for error). Both sides exchange a challenge frame and verify the peer holds the same cookie. The responder's HMAC is bound to the initiator's nonce, preventing replay attacks.

Protocol flow:

  1. Initiator sends Handshake(HMAC(cookie, nonce_i), nonce_i)
  2. Responder verifies initiator's HMAC
  3. Responder sends Handshake(HMAC(cookie, nonce_i || nonce_r), nonce_r)
  4. Initiator verifies responder's HMAC using both nonces
  5. Both sides are now authenticated — normal TLV messages follow

Constants

HMAC_SIZE = 32

Size of the HMAC-SHA256 digest in bytes.

NONCE_SIZE = 32

Size of the random nonce in bytes.

Class methods

initiate(io : IO, cookie : String) : Nil

Performs the initiator side of the handshake.

Sends a TLV Handshake challenge, then verifies the responder's challenge which must be bound to the initiator's nonce (replay protection). Raises Error::AuthenticationFailed if the responder's HMAC is invalid or if the responder sends an error frame.

Source
respond(io : IO, cookie : String) : Nil

Performs the responder side of the handshake.

Verifies the initiator's TLV Handshake challenge, then sends its own response with HMAC bound to the initiator's nonce (replay protection). Raises Error::AuthenticationFailed if the initiator's HMAC is invalid. Sends a TLV ErrorMessage frame before raising.

Source