硬件网络防火墙（用户白名单）详细设计

1. 文档目的

本文档用于指导“硬件网络防火墙（用户白名单）”项目的详细设计、RTL 实现、验证和上板联调。本文档以“打开特定用户访问网络”为业务案例，采用用户源 MAC 地址作为唯一身份标识，给出从需求定义、总体架构、报文处理链路、规则组织方式，到顺序查表、二分法查表、布谷鸟哈希三类查表算法的具体实现方法、资源代价与适用边界的完整设计说明。

本文档不是概念性介绍，而是面向项目落地的详细设计输入，支持以下工作：

1. 明确白名单准入型硬件网络防火墙的业务边界。

2. 明确基于源 MAC 地址的 L2 数据面处理链路。

3. 明确三种 MAC 查表算法的实现方式、资源与时延差异。

4. 明确规则装载、联调、上板验证与扩展方向。

---

2. 项目背景

2.1 背景说明

在企业培训网、实验教学网、考试专网、工位办公网和受控生产网中，经常存在这样一种管理需求：网络并不是对所有终端默认开放，而是只对登记用户开放访问权限。该类需求的核心不是识别复杂应用协议，而是回答一个更基础的问题：

1. 当前接入网络的这个终端，是否属于允许接入的用户设备。

2. 若属于授权设备，则允许其访问网络。

3. 若不属于授权设备，则直接在接入侧丢弃其报文。

在很多低复杂度、低成本、低时延的场景里，最直接的设备身份标识就是网卡 MAC 地址。虽然 MAC 地址不是绝对安全身份，但在封闭或半封闭网络环境中，使用源 MAC 作为准入标识可以显著降低系统复杂度，并且适合作为 FPGA 硬件防火墙的首版实现。

2.2 案例选择

本文选取“打开特定用户访问网络”为案例。具体含义为：

1. 网络管理员维护一份允许访问网络的用户设备 MAC 白名单。

2. 当终端报文进入 FPGA 接入口时，硬件从以太网帧头中提取源 MAC 地址。

3. 若源 MAC 在白名单中，则该报文允许通过。

4. 若源 MAC 不在白名单中，则该报文直接丢弃。

该设计不关心用户访问的是哪一个网站、哪个服务器、哪个应用，也不解析 L3/L4 以上内容，而是将“是否允许入网”的判定完全收敛到二层源 MAC 地址匹配上。

2.3 设计边界

本项目边界定义如下：

1. 硬件数据面只解析到 L2，不解析 L3/L4 或应用层内容。

2. 用户身份仅以源 MAC 地址为标识。

3. 白名单生成、导入和更新由控制面完成。

4. 数据面动作仅保留 PASS 和 DROP。

5. 本版不处理基于用户名、IP、端口或应用类型的复合策略。

上述边界决定了本项目是一个“MAC 白名单准入硬件过滤系统”，而不是复杂的多维策略防火墙。

---

3. 设计目标与验收指标

3.1 设计目标

设计一个基于 FPGA 的轻量级硬件网络防火墙，对进入交换口或网关口的以太网流量进行二层解析，并基于源 MAC 地址完成用户白名单放行控制，实现以下目标：

1. 支持 Ethernet II 基础帧解析。

2. 支持提取源 MAC 地址作为查表键值。

3. 支持 MAC 白名单精确匹配。

4. 命中白名单则放行，未命中则丢弃。

5. 支持白名单批量更新与统计计数。

3.2 核心验收指标

| 指标项 | 目标值 |

|---|---|

| 接口速率 | 1GbE |

| 工作时钟 | 125 MHz |

| 解析层级 | L2 |

| 规则对象 | 用户源 MAC 地址 |

| 规则类型 | 源 MAC 精确匹配白名单 |

| 查表方式 | 顺序查表、二分法查表、布谷鸟哈希三种方式可切换验证 |

| 动作类型 | PASS / DROP |

| 规则容量 | 不低于 1K 条 MAC 白名单规则 |

| 统计能力 | 支持总包数、命中数、丢弃数、放行数 |

3.3 非功能目标

1. 结构简洁，便于教学展示和项目演示。

2. 算法模块接口统一，便于替换和横向对比。

3. 资源消耗可控，适配中低端 FPGA。

4. 支持后续扩展到 VLAN、IP、端口等多维策略。

---

4. 需求分析

4.1 业务场景

业务流程如下：

1. 管理员维护“允许访问网络的用户设备 MAC 白名单”。

2. 控制面将白名单整理成规则表镜像。

3. 白名单规则被下发到 FPGA 数据面查表模块。

4. 当终端发送任意以太网帧进入系统时，硬件提取其源 MAC。

5. 若源 MAC 在白名单中，则允许该报文继续转发。

6. 若源 MAC 不在白名单中，则直接丢弃该报文。

在该方案中，网络访问授权是“先验授权”，而不是基于业务内容做后验识别。

4.2 功能需求

1. 支持以太网帧接收与基本帧头解析。

2. 支持提取源 MAC 地址 src_mac。

3. 支持将 src_mac 作为查表键输入规则模块。

4. 支持白名单命中放行、未命中丢弃。

5. 支持规则批量更新。

6. 支持总收包数、放行数、丢弃数、白名单命中数统计。

7. 支持在统一接口下切换三种查表算法。

4.3 非需求说明

以下能力不属于本版实现范围：

1. IPv4/IPv6 深度解析。

2. TCP/UDP 端口过滤。

3. HTTP、TLS、DNS 等应用层识别。

4. 用户名、密码、账号体系联动。

5. 动态认证握手协议。

6. MAC 欺骗检测与高级安全防护。

---

5. 总体方案

5.1 系统结构

系统采用“L2 解析 + MAC 白名单查表 + 动作执行 + 统计管理”的结构：

MAC RX
  -> L2 Parser
  -> src_mac 提取
  -> MAC 白名单查表引擎
  -> 动作执行(PASS/DROP)
  -> MAC TX / DROP
                \
                 -> 统计计数 / 配置接口

5.2 模块划分

1. rx_parser_l2：完成以太网帧头解析。

2. mac_key_builder：提取 src_mac 并形成查表输入键。

3. lookup_seq_mac：顺序查表引擎。

4. lookup_bin_mac：二分法查表引擎。

5. lookup_cuckoo_mac：布谷鸟哈希查表引擎。

6. lookup_ctrl：选择当前启用的查表方式。

7. action_engine：根据命中结果执行放行或丢弃。

8. cfg_if：规则装载、模式配置和状态读取接口。

9. counter_mgr：维护总包数、命中数、放行数、丢弃数。

5.3 关键设计原则

1. 数据面仅围绕 src_mac 做精确匹配。

2. 三种算法使用统一的 48 位 MAC 键值接口。

3. 数据面逻辑尽量固定时延，减少不必要的状态复杂度。

4. 控制面负责规则管理，数据面专注于快速判决。

---

6. 用户白名单案例建模

6.1 识别对象定义

本项目将“允许接入网络的用户”定义为：

1. 持有已登记网卡设备的用户终端。

2. 其报文源 MAC 地址属于控制面预先下发的白名单集合。

因此，硬件侧识别对象不是用户名，不是 IP 地址，也不是业务流量类型，而是“进入链路的帧头中的源 MAC 地址”。

6.2 白名单规则生成逻辑

控制面流程如下：

1. 维护用户设备 MAC 白名单源表。

2. 校验 MAC 地址格式正确性。

3. 去重并剔除非法项。

4. 生成规则镜像文件。

5. 下载到 FPGA 查表模块。

6.3 规则样例

| 规则类型 | 关键字 | 动作 |

|---|---|---|

| 源 MAC 精确匹配 | src_mac = 00:11:22:33:44:55 | PASS |

| 默认规则 | 未命中任意白名单项 | DROP |

本设计采用“白名单优先、默认拒绝”的安全模型。

6.4 判决优先级

本版定义简单判决逻辑：

1. 若源 MAC 命中白名单，则放行。

2. 若源 MAC 未命中白名单，则丢弃。

不引入黑名单、优先级掩码和复杂冲突仲裁，使系统行为清晰可验证。

---

7. 数据面报文处理流程

7.1 报文入口

当网口收到以太网帧后，rx_parser_l2 完成以下步骤：

1. 识别帧起始。

2. 提取目的 MAC 地址。

3. 提取源 MAC 地址。

4. 提取 EtherType。

5. 生成 src_mac_valid 信号送往查表模块。

在本设计中，除源 MAC 地址外，其他字段只作为基础解析存在，不参与准入判决。

7.2 规则键构造

本版规则键定义为：

rule_key = src_mac[47:0]

如果后续需要扩展到 VLAN 级用户隔离，可扩展为：

rule_key = {
  vlan_id[11:0],
  src_mac[47:0]
}

但首版推荐直接以 48 位源 MAC 作为唯一查表键。

7.3 判决流程

1. 数据面提取 src_mac。

2. 将 src_mac 输入当前启用的查表模块。

3. 若命中白名单，则执行 PASS。

4. 若未命中，则执行 DROP。

该流程与 IP 黑名单相比更简单，因为无需继续解析网络层字段。

---

8. 规则格式设计

8.1 表项结构

建议单条规则结构如下：

| 字段 | 位宽 | 说明 |

|---|---:|---|

| valid | 1 | 表项有效位 |

| src_mac | 48 | 用户设备源 MAC 地址 |

| action | 1~2 | PASS 或 DROP |

| counter_idx | 16 | 统计索引 |

由于本设计为白名单放行模型，最简化时表项可以进一步压缩为：

| 字段 | 位宽 | 说明 |

|---|---:|---|

| valid | 1 | 表项有效位 |

| src_mac | 48 | 允许接入的用户 MAC |

此时，命中即 PASS，未命中即 DROP，动作字段无需显式存储。

8.2 动作编码

| 编码 | 动作 |

|---:|---|

| 0 | DROP |

| 1 | PASS |

8.3 存储建议

1. 小规模白名单使用 BRAM 即可满足。

2. 二分法查表使用排序表存储。

3. 布谷鸟哈希采用多表 BRAM 结构。

4. 1K 级规则量在中低端 FPGA 上可用片上资源实现。

---

9. 三类查表算法详细设计

本文保留顺序查表、二分法查表和布谷鸟哈希三种方法，但其匹配对象统一为“48 位源 MAC 地址”。

9.1 顺序查表

9.1.1 适用场景

顺序查表适用于：

1. 白名单数量较少，如 32~128 条。

2. 首版原型开发与课堂演示。

3. 需要最快速度跑通硬件闭环。

9.1.2 基本思路

从规则表首项开始逐条比较：

1. 若 src_mac == table[i].src_mac，则命中白名单。

2. 若遍历结束仍未命中，则判为未授权设备。

9.1.3 硬件实现方法

1. 单比较器串行扫描

• 每拍读取一条表项。

• 使用 48 位比较器逐项判断。

• 最终输出命中或未命中。

2. 多比较器并行分组扫描

• 每拍并行读取和比较 N 条规则。

• 通过归约逻辑判断是否命中。

• 提升吞吐，但会增加资源使用。

9.1.4 推荐接口

module lookup_seq_mac #(
    parameter RULE_NUM = 64
)(
    input  wire        clk,
    input  wire        rst_n,
    input  wire        key_valid,
    input  wire [47:0] src_mac,
    output wire        hit_valid,
    output wire        hit
);

9.1.5 时延分析

最坏时延近似为：

若白名单为 64 条，则最坏约需 64 拍，适合首版实现，但不适合更大规模用户表。

9.1.6 优点

1. 实现最简单。

2. 容易验证正确性。

3. 适合作为基线方案。

9.1.7 缺点

1. 查找时延随规则数线性上升。

2. 大规模用户白名单下性能一般。

---

9.2 二分法查表

9.2.1 适用场景

二分法查表适合已排序的 48 位 MAC 地址表，适用于：

1. 中等规模用户白名单。

2. 规则更新周期较长的受控网络。

3. 希望在较低资源下提升查找效率。

9.2.2 基本思路

将白名单 MAC 地址按数值升序排列，每次比较中间值：

1. 若 src_mac == table[mid]，则命中。

2. 若 src_mac < table[mid]，则查左半区。

3. 若 src_mac > table[mid]，则查右半区。

9.2.3 硬件实现方法

1. 控制面先将 MAC 地址表排序。

2. 将排序表写入 BRAM。

3. 数据面状态机维护 low、high、mid。

4. 每拍读出中间表项并做 48 位比较。

5. 根据比较结果缩小查找区间。

9.2.4 时延分析

当规则表为 1024 条时，理论比较层数约 10 层，远优于顺序查表。

9.2.5 优点

1. 查找时延为对数级。

2. 逻辑复杂度适中。

3. 对资源要求低于多表哈希。

9.2.6 缺点

1. 规则更新前需要重排序。

2. 不适合频繁增删用户。

---

9.3 布谷鸟哈希查表

9.3.1 适用场景

布谷鸟哈希适用于较大规模用户白名单，适用于：

1. 用户终端数量较多。

2. 需要固定且较短的查找时延。

3. 希望构建高性能数据面放行路径。

9.3.2 基本思路

对 48 位 src_mac 计算多个哈希地址，例如：

每个白名单 MAC 可以放在多个候选桶位之一。查找时并行访问多个位置，只要任一位置命中，就视为白名单放行。

9.3.3 硬件实现方法

1. 使用 2 表或 4 表 BRAM 结构。

2. 对 src_mac 同拍生成多个哈希地址。

3. 并行读取候选桶位。

4. 通过比较逻辑判断是否命中。

9.3.4 插入策略

本设计建议由控制面离线建表：

1. 控制面执行 MAC 地址哈希分配。

2. 若冲突则进行踢出重排。

3. 生成稳定的哈希表镜像。

4. 批量写入 FPGA。

这样可以避免数据面包含复杂的在线插入逻辑。

9.3.5 时延分析

在并行 BRAM 结构下通常为固定 2~4 拍，非常适合高性能版本。

9.3.6 优点

1. 查找速度快。

2. 更适合大容量 MAC 白名单。

3. 容易形成固定时延硬件路径。

9.3.7 缺点

1. 控制面建表复杂。

2. 规则更新链路相对复杂。

---

10. 三类查表算法对比与选型

| 维度 | 顺序查表 | 二分法查表 | 布谷鸟哈希 |

|---|---|---|---|

| 匹配对象 | 源 MAC | 源 MAC | 源 MAC |

| 查找时延 | 线性增长 | 对数增长 | 近似常数 |

| 实现复杂度 | 低 | 中 | 中高 |

| 更新复杂度 | 低 | 中 | 高 |

| 适合容量 | 小表 | 中表 | 大表 |

| 首版推荐度 | 高 | 中 | 低 |

| 性能扩展能力 | 低 | 中 | 高 |

10.1 推荐选型

结合本项目目标，推荐实施顺序如下：

1. 首版原型：顺序查表

• 结构清晰，便于最短时间完成闭环验证。

2. 性能优化版：二分法查表

• 在资源增幅不大的前提下提升查找性能。

3. 高性能版：布谷鸟哈希

• 用于大规模用户白名单和高性能展示。

因此，本项目的建议主线是：先用顺序查表跑通基线方案，再以相同接口替换为二分法和布谷鸟哈希，实现性能对比。

---

11. 详细模块设计

11.1 rx_parser_l2

功能

完成以太网帧头解析，提取源 MAC 地址。

输入

1. s_axis_tdata

2. s_axis_tvalid

3. s_axis_tlast

输出

1. meta_valid

2. src_mac

3. dst_mac

4. eth_type

5. parse_error

实现说明

按固定字节偏移状态机实现：

1. 第 0~5 字节提取 dst_mac。

2. 第 6~11 字节提取 src_mac。

3. 第 12~13 字节提取 eth_type。

4. 帧头提取完成后拉高 meta_valid。

11.2 mac_key_builder

功能

将 src_mac 直接作为查表键输入查表模块。

说明

本版无需复杂拼接逻辑，仅需完成键值锁存与有效信号对齐。

11.3 lookup_seq_mac

功能

对源 MAC 执行顺序精确匹配。

11.4 lookup_bin_mac

功能

对排序后的源 MAC 白名单表执行二分查找。

11.5 lookup_cuckoo_mac

功能

对源 MAC 白名单执行布谷鸟哈希精确匹配。

11.6 lookup_ctrl

功能

根据配置寄存器选择当前启用的查表方式：

1. 00：顺序查表

2. 01：二分法查表

3. 10：布谷鸟哈希

说明

首版可只启用顺序查表，其余模式保留扩展接口。

11.7 action_engine

功能

根据查表结果执行：

1. 命中白名单 -> PASS

2. 未命中 -> DROP

首版建议

不做复位注入、不做镜像、不做告警联动，只保留最小准入控制闭环。

11.8 cfg_if

功能

支持规则表写入、查表模式选择和统计寄存器读取。

11.9 counter_mgr

功能

维护以下统计项：

1. 总收包数

2. 白名单命中数

3. 放行包数

4. 丢弃包数

5. 解析异常数

---

12. 控制面与规则装载设计

12.1 控制面职责

本项目明确将以下工作交给控制面完成：

1. 用户设备 MAC 白名单维护。

2. MAC 地址格式校验。

3. 白名单去重和镜像生成。

4. 规则批量下载。

5. 规则版本管理。

12.2 规则生成流程

1. 管理员维护用户 MAC 白名单源文件。

2. 控制面程序校验 MAC 地址格式。

3. 去重后生成 src_mac 规则表。

4. 按选用算法生成对应表结构：

• 顺序表镜像

• 排序表镜像

• 布谷鸟哈希镜像

5. 通过 cfg_if 下载到 FPGA。

12.3 更新策略

1. 顺序表支持直接覆盖写。

2. 二分表更新前重新排序。

3. 布谷鸟哈希由控制面离线建表后整体替换。

---

13. 关键实现步骤

13.1 第 1 步：完成 L2 解析模块

先实现 rx_parser_l2，验证以下内容：

1. src_mac 提取正确。

2. dst_mac 提取正确。

3. 帧头边界处理正确。

13.2 第 2 步：完成顺序查表最小闭环

实现最小可运行版本：

1. 源 MAC 提取。

2. 顺序查表。

3. 命中放行。

4. 未命中丢弃。

这是本项目最重要的首个里程碑。

13.3 第 3 步：增加统计计数

增加命中、放行、丢弃等计数器，形成可观测闭环。

13.4 第 4 步：实现控制面白名单下载

支持上位机将 MAC 白名单规则表下发到 FPGA。

13.5 第 5 步：实现二分法查表

在不改变上层接口的前提下，用二分法替换顺序查表，并统计性能变化。

13.6 第 6 步：实现布谷鸟哈希查表

在控制面离线建表前提下，实现布谷鸟哈希版本，并与前两者对比。

13.7 第 7 步：上板联调

使用白名单设备和非白名单设备分别发包，验证是否符合准入预期。

---

14. 时序与资源估算

14.1 解析路径时延估算

| 模块 | 预计时延（拍） |

|---|---:|

| L2 解析 | 4~8 |

| 键值锁存 | 1~2 |

| 顺序查表 | 16~64 或更高 |

| 二分查表 | 8~16 |

| 布谷鸟哈希 | 2~4 |

| 动作执行 | 1~2 |

14.2 资源估算

以下为首版估算，具体以综合结果为准：

| 模块 | LUT | FF | BRAM | 说明 |

|---|---:|---:|---:|---|

| L2 解析 | 600~1500 | 500~1200 | 0~1 | 明显低于 L3/L4 解析 |

| 顺序查表 | 300~1000 | 300~800 | 1~4 | 与规则数相关 |

| 二分查表 | 500~1200 | 400~900 | 2~6 | 需有序表 |

| 布谷鸟哈希 | 1000~2500 | 800~1800 | 4~12 | 与表数和容量相关 |

| 统计与配置 | 300~800 | 300~700 | 1~2 | |

由于本设计只解析到二层，其总体资源和时序压力会明显低于 IP 级和应用级过滤方案。

---

15. 验证方案

15.1 功能仿真

测试激励建议包括：

1. 白名单 MAC 设备发出的正常以太网帧。

2. 非白名单 MAC 设备发出的以太网帧。

3. 异常短帧或格式不完整的帧。

4. 多个白名单项与边界值测试。

15.2 算法对比验证

使用同一组 src_mac 白名单规则，对三类查表模块分别统计：

1. 命中正确率。

2. 平均查找拍数。

3. 最坏查找拍数。

4. LUT/FF/BRAM 占用。

15.3 上板验证

1. 下发白名单规则。

2. 使用已授权终端发包，确认能正常通过。

3. 使用未授权终端发包，确认被丢弃。

4. 读取计数器，确认统计值与预期一致。

15.4 边界验证

1. 白名单为空时，系统应默认全部拒绝。

2. 白名单包含单条记录时，应仅允许对应设备通过。

3. 白名单更新后，应验证新旧规则切换生效。

---

16. 风险与规避措施

16.1 MAC 欺骗风险

用户可能通过修改网卡 MAC 地址冒充已授权设备。

规避措施

1. 在封闭网络环境中使用该方案。

2. 后续叠加交换机端口绑定。

3. 如有更高安全要求，再引入 802.1X 或多因子准入。

16.2 白名单维护风险

白名单数据若维护不及时，可能导致合法用户无法访问网络。

规避措施

1. 提供控制面批量导入工具。

2. 提供规则版本回滚能力。

3. 提供规则更新校验机制。

16.3 规则容量扩展风险

当授权用户数量较大时，顺序查表可能难以满足性能要求。

规避措施

1. 首版先验证顺序查表功能。

2. 中期替换为二分法查表。

3. 大规模场景采用布谷鸟哈希方案。

---

17. 项目交付清单

1. 详细设计文档 硬件网络防火墙（用户白名单）.md

2. L2 解析 RTL

3. 三类源 MAC 查表 RTL 模块

4. 动作执行与统计模块

5. 配置下发接口模块

6. 控制面白名单生成脚本

7. 仿真测试平台

8. 上板验证报告

---

18. 结论与推荐实施路线

对于“仅以用户 MAC 地址为标识，打开特定用户访问网络”的准入控制场景，采用“L2 解析 + 源 MAC 白名单匹配”的硬件网络防火墙方案是工程上最简洁、最容易落地的做法。该方案具备以下优势：

1. 硬件逻辑短，资源占用低。

2. 业务语义明确，易于演示和验收。

3. 非常适合作为三种查表算法性能对比的平台。

推荐实施路径如下：

1. 先完成 L2 解析 + 顺序查表 的最小闭环。

2. 再实现 二分法查表，作为中等复杂度优化方案。

3. 最后实现 布谷鸟哈希 版本，用于大规模用户白名单和高性能展示。

通过这种分阶段推进方式，可以在保证项目成功率的同时，逐步体现不同查表算法在硬件网络防火墙中的工程价值。