quic_lb (quic v3.0.0)
View SourceQUIC Load Balancer Connection ID encoding and decoding.
This module implements the QUIC-LB (draft-ietf-quic-load-balancers-22) Connection ID encoding schemes that allow load balancers to route QUIC packets to the correct server based on server identity encoded in the Connection ID.
CID Format
The first byte contains: - CR (Config Rotation): 3 bits identifying the configuration - Length: 5 bits, the number of bytes after the first octet
+--------+----------------+--------+
| CR:3 | Server ID | Nonce |
| Len:5 | (1-15 bytes) | (4-18) |
+--------+----------------+--------+
Server ID and nonce together are at most 19 bytes (Section 5.3).
Algorithms
1. Plaintext: No encryption, server_id visible in CID 2. Encrypted: AES-128-ECB single pass for a 16-byte server ID and nonce, four-pass Feistel network otherwise (draft-ietf-quic-load-balancers-22 Section 5.4)
The stream_cipher and block_cipher algorithms of earlier drafts are refused with {error, {unsupported_lb_algorithm, Algorithm}}.
Summary
Functions
Extract the server ID from a CID.
Calculate the expected CID length from configuration.
Generate a CID using the configuration. Uses a random nonce.
Generate a CID with an explicit nonce.
Get the config rotation bits from a CID's first byte.
Check if a CID is LB-routable (CR != 0b111).
Create a CID generation configuration from options map.
Create a new LB configuration from options map.
Validate an LB configuration.
Functions
-spec decode_server_id(binary(), #lb_config{config_rotation :: 0..6, algorithm :: plaintext | encrypted, server_id :: binary(), server_id_len :: 1..15, nonce_len :: 4..18, key :: binary() | undefined}) -> {ok, binary()} | {error, term()}.
Extract the server ID from a CID.
-spec expected_cid_len(#lb_config{config_rotation :: 0..6, algorithm :: plaintext | encrypted, server_id :: binary(), server_id_len :: 1..15, nonce_len :: 4..18, key :: binary() | undefined}) -> pos_integer().
Calculate the expected CID length from configuration.
-spec generate_cid(#cid_config{lb_config :: #lb_config{config_rotation :: 0..6, algorithm :: plaintext | encrypted, server_id :: binary(), server_id_len :: 1..15, nonce_len :: 4..18, key :: binary() | undefined} | undefined, cid_len :: 1..20, reset_secret :: binary() | undefined}) -> binary().
Generate a CID using the configuration. Uses a random nonce.
-spec generate_cid(#cid_config{lb_config :: #lb_config{config_rotation :: 0..6, algorithm :: plaintext | encrypted, server_id :: binary(), server_id_len :: 1..15, nonce_len :: 4..18, key :: binary() | undefined} | undefined, cid_len :: 1..20, reset_secret :: binary() | undefined}, binary()) -> binary().
Generate a CID with an explicit nonce.
-spec get_config_rotation(binary()) -> 0..7.
Get the config rotation bits from a CID's first byte.
Check if a CID is LB-routable (CR != 0b111).
-spec new_cid_config(map()) -> {ok, #cid_config{lb_config :: #lb_config{config_rotation :: 0..6, algorithm :: plaintext | encrypted, server_id :: binary(), server_id_len :: 1..15, nonce_len :: 4..18, key :: binary() | undefined} | undefined, cid_len :: 1..20, reset_secret :: binary() | undefined}} | {error, term()}.
Create a CID generation configuration from options map.
Options: - lb_config: #lb_config{} | undefined - LB configuration - cid_len: 1..20 (default: 8) - Target CID length - reset_secret: binary() - Secret for reset token generation
-spec new_config(map()) -> {ok, #lb_config{config_rotation :: 0..6, algorithm :: plaintext | encrypted, server_id :: binary(), server_id_len :: 1..15, nonce_len :: 4..18, key :: binary() | undefined}} | {error, term()}.
Create a new LB configuration from options map.
Options: - server_id: binary() (required) - Server identifier (1-15 bytes) - algorithm: plaintext | encrypted (default: plaintext) - config_rotation: 0..6 (default: 0) - nonce_len: 4..18 (default: 4) - key: binary() - 16-byte AES key (required for encrypted)
The server ID and nonce lengths sum to 19 bytes or less.
-spec validate_config(#lb_config{config_rotation :: 0..6, algorithm :: plaintext | encrypted, server_id :: binary(), server_id_len :: 1..15, nonce_len :: 4..18, key :: binary() | undefined}) -> ok | {error, term()}.
Validate an LB configuration.