nquic_retry (nquic v1.0.0)

View Source

Server-side Retry packet support per RFC 9000 Section 8.1.2.

Retry allows a server to validate a client's address before allocating connection state. The server sends a Retry packet containing an opaque token. The client must resend its Initial with this token. The server validates the token (HMAC of original DCID, client address, timestamp) before accepting the connection.

Summary

Functions

compute_integrity_tag(ODCID, RetryPacketNoTag)

Compute the Retry Integrity Tag (v1 default).

compute_integrity_tag(ODCID, RetryPacketNoTag, Version)

Compute the Retry Integrity Tag per RFC 9000/9369. Version selects the fixed key and nonce (v1 vs v2).

encode_addr/1
encode_retry_packet(DCID, SCID, ODCID, RetryToken, Version)

Encode a complete Retry packet with integrity tag. DCID/SCID are from the server's perspective (DCID = client's SCID, SCID = server's new CID).

generate_token(StaticKey, ODCID, PeerAddr, TokenLifetime)

Generate a Retry token containing the original DCID, client address, and timestamp. HMAC-SHA256 provides integrity and authentication. Token format: <<HMAC:32/binary, Timestamp:64, ODCIDLen:8, ODCID/binary, AddrBin/binary>>

hmac_equal(A, B)
retry_key/1

Return the retry integrity key for a given QUIC version.

retry_nonce/1

Return the retry integrity nonce for a given QUIC version.

validate_token/4

Validate a Retry token. Returns {ok, ODCID} if the token is valid (correct HMAC, not expired, matching client address), or {error, Reason}.

verify_integrity_tag(ODCID, RetryPacketNoTag, IntegrityTag)
verify_integrity_tag(ODCID, RetryPacketNoTag, IntegrityTag, Version)

Verify the Retry Integrity Tag on a received Retry packet.

Functions

compute_integrity_tag(ODCID, RetryPacketNoTag)

-spec compute_integrity_tag(nquic:connection_id(), binary()) -> binary().

Compute the Retry Integrity Tag (v1 default).

compute_integrity_tag(ODCID, RetryPacketNoTag, Version)

-spec compute_integrity_tag(nquic:connection_id(), binary(), non_neg_integer()) -> binary().

Compute the Retry Integrity Tag per RFC 9000/9369. Version selects the fixed key and nonce (v1 vs v2).

encode_addr/1

-spec encode_addr(nquic_socket:sockaddr()) -> binary().

encode_retry_packet(DCID, SCID, ODCID, RetryToken, Version)

-spec encode_retry_packet(nquic:connection_id(),
                          nquic:connection_id(),
                          nquic:connection_id(),
                          binary(),
                          non_neg_integer()) ->
                             binary().

Encode a complete Retry packet with integrity tag. DCID/SCID are from the server's perspective (DCID = client's SCID, SCID = server's new CID).

generate_token(StaticKey, ODCID, PeerAddr, TokenLifetime)

-spec generate_token(binary(), nquic:connection_id(), nquic_socket:sockaddr(), non_neg_integer()) ->
                        binary().

Generate a Retry token containing the original DCID, client address, and timestamp. HMAC-SHA256 provides integrity and authentication. Token format: <<HMAC:32/binary, Timestamp:64, ODCIDLen:8, ODCID/binary, AddrBin/binary>>

hmac_equal(A, B)

-spec hmac_equal(binary(), binary()) -> boolean().

retry_key/1

-spec retry_key(non_neg_integer()) -> binary().

Return the retry integrity key for a given QUIC version.

retry_nonce/1

-spec retry_nonce(non_neg_integer()) -> binary().

Return the retry integrity nonce for a given QUIC version.

validate_token/4

-spec validate_token(binary(), binary(), nquic_socket:sockaddr(), non_neg_integer()) ->
                        {ok, nquic:connection_id()} | {error, term()}.

Validate a Retry token. Returns {ok, ODCID} if the token is valid (correct HMAC, not expired, matching client address), or {error, Reason}.

verify_integrity_tag(ODCID, RetryPacketNoTag, IntegrityTag)

-spec verify_integrity_tag(nquic:connection_id(), binary(), binary()) ->
                              ok | {error, integrity_check_failed}.

verify_integrity_tag(ODCID, RetryPacketNoTag, IntegrityTag, Version)

-spec verify_integrity_tag(nquic:connection_id(), binary(), binary(), non_neg_integer()) ->
                              ok | {error, integrity_check_failed}.

Verify the Retry Integrity Tag on a received Retry packet.