perlab-uc3m/ais31_headless

# ais31-headless (AIS 31 V1) `ais31-headless` 是官方 BSI AIS 31 Java 参考实现 `AIS 31 (V1) Referenzimplementierung - v1.0` 的 CLI 框架。 该项目将 BSI 实现作为外部工件保留。它不会就地编辑原始的 `Evaluator.java`。在安装过程中，它将 BSI Java 源代码/类复制到 `.ais31/bsi`，使用正确的 Latin-1 源编码编译它们，并在旁边编译一个无头 Java 运行器。 ## 理由 BSI 实现是一个 Swing GUI 应用程序。其统计逻辑位于一个包私有的 `Tester` 类中，与 `Evaluator` 中的 GUI 字段耦合。这个框架给 `Tester` 提供了它期望的字段，在没有窗口的情况下运行它，并捕获原始的日志消息。Python CLI 处理安装、执行、解析和结构化输出。 ## 安装 ``` python -m venv .venv source .venv/bin/activate python -m pip install -U pip python -m pip install -e .[dev] ``` 您需要一个 JDK，而不仅仅是 JRE，因为框架会编译 Java 源代码： ``` sudo apt-get install default-jdk ``` 从官方 BSI ZIP 或提取的 BSI 目录安装： ``` ais31 install --archive ~/Downloads/AIS_31_testsuit_zip.zip ``` 或者： ``` ais31 install --source-dir ../AIS_31_testsuit_zip ``` ## 命令行界面 检查已安装的框架： ``` ais31 check ``` 该包还安装了 `ais31v1` 作为同一 CLI 的显式别名。 运行程序 A，P1:T1-T5，在解释为每字节 8 个随机位的原始字节上： ``` ais31 run --input sample.bin --format raw --suite p1-t1-t5 --bit-width 8 --out results/p1.json ``` 运行 P1:T0： ``` ais31 run --input sample.bin --format raw --suite p1-t0 --bit-width 8 --out results/t0.json ``` 运行 P2 特定测试： ``` ais31 run --input sample.bin --format raw --suite p2 --bit-width 8 --out results/p2.json ``` 当使用 `--out` 时，stdout 保持紧凑，并将完整的结构化结果写入该文件。添加 `--json` 也会将完整的 JSON 打印到 stdout。 ## 生成样本 输入必须是支持编码之一中的随机数据。为了快速烟雾测试，从 `/dev/urandom` 生成原始字节。 ``` mkdir -p samples results head -c 393216 /dev/urandom > samples/p1-t0.raw ais31 run --input samples/p1-t0.raw --format raw --suite p1-t0 --bit-width 8 --out results/p1-t0.json ``` 对于具有 `--bit-width 8` 的较大套件： ``` head -c 652500 /dev/urandom > samples/p1-t1-t5.raw ais31 run --input samples/p1-t1-t5.raw --format raw --suite p1-t1-t5 --bit-width 8 --out results/p1-t1-t5.json head -c 900000 /dev/urandom > samples/p2.raw ais31 run --input samples/p2.raw --format raw --suite p2 --bit-width 8 --out results/p2.json ``` 通过大小检查意味着套件可以运行。但这并不意味着样本会通过。统计结果在 CLI 摘要和 JSON 文件中。 默认输出是简短的。完整的 BSI 日志保留在 JSON 文件中。 ``` p1-t0: passed; outcomes 1/1 passed; consumed 393216 of 393216 bytes; rest samples/p1-t0.raw_rest json: results/p1-t0.json ``` 输入格式： - `raw`：每个文件字节包含 8 个随机位，最高有效位首先。 - `bit-bytes`：每个文件字节是一个随机位，并且必须具有值 `0x00` 或 `0x01`。 在 Java 运行器开始之前检查输入大小。最小大小遵循 BSI AIS 31 V1 实现公式： | 套件 | 所需随机位 | `raw` 所需字节 | `bit-bytes` 所需字节 | | --- | ---: | ---: | ---: | | `p1-t0` | `bit_width * ceil(48 / bit_width) * 65536` | `ceil(bits / 8)` | `bits` | | `p1-t1-t5` | `ceil(257 / (bit_width + 1)) * (ceil(20000 / bit_width) * bit_width + bit_width * 20000)` | `ceil(bits / 8)` | `bits` | | `p2` | `7200000` | `900000` | `7200000` | 例如，使用 `--bit-width 8`，`p1-t0` 需要 393,216 个原始字节，`p1-t1-t5` 需要 652,500 个原始字节，`p2` 需要 900,000 个原始字节。这些都是最小大小，不是通过保证。统计上较弱或不走运的数据仍然可能失败测试。在 `bit-bytes` 模式下，框架还验证所需文件部分只包含 `0x00` 和 `0x01` 字节值。 如果输入文件大于所选套件所需的大小，BSI V1 实现只测试所需的前几个字节/位。完整的 JSON 结果报告 `input.consumed_bits`、`input.consumed_bytes` 和 `input.untested_remainder_bytes`，以便调用者可以确切地看到评估了多少文件。原始 BSI 程序将未使用的尾部写入一个同级的 `_rest` 文件，并在存在时在 `artifacts` 中报告该路径。在 `bit-bytes` 模式下，原始 BSI 剩余文件字节计数似乎不一致：测试消耗了第一个 `required_bits` 字节，但生成 `_rest` 文件可能不会跳过相同数量的字节。此框架保留并报告该参考行为，而不是静默地纠正它。 对于 `p2`，BSI 实现读取高达 7,200,000 个随机位。非常退化的输入仍然可能在 BSI 程序内部失败，因为“测试数据太少”，因为条件测试需要足够多个位模式的出现；预飞检查只能证明文件在物理上足够大并且正确编码。 套件： - `p1-t0`：不相交性测试，AIS 准则 `P1.i(i)`。 - `p1-t1-t5`：单比特、扑克、运行、长运行、自相关，AIS 准则 `P1.i(ii)`。 - `p2`：P2 特定测试 `T6a`、`T6b`、`T7a`、`T7b` 和 `T8`。 JSON 结果包含： - `summary`：通过/失败，结果计数，失败的测试名称，消耗的字节，剩余字节，剩余文件，和警告计数 - 命令/配置元数据 - 总体状态 - 在 BSI 日志中可见的每个测试的解析结果 - 从 BSI 日志中解析的结构化测量值，例如单比特计数、扑克统计、运行计数、自相关值和 P2 统计 - 生成的工件，包括存在时 BSI `_rest` 文件路径 - 消耗的字节和未测试的剩余字节 - 原始 BSI 日志行 - 如果有的话，JVM 的 stderr ## 注意 这是一个框架，而不是重写。Java 运行器从官方源调用 BSI `Tester` 逻辑。 原始实现将 `_rest` 文件写入输入旁边。框架在预期时报告此路径。注意 `bit-bytes` 模式和重复工作流程：原始代码在该模式下似乎有可疑的剩余文件字节计数，因此此框架保留并报告参考行为，而不是静默地更改它。 ## 参考 - [BSI AIS20/31 Java 测试套件页面](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Zertifizierung/Interpretationen/AIS_31_testsuit_zip.zip) - [BSI 随机数生成器概述](https://www.bsi.bund.de/dok/randomnumbergenerators) - [AIS 20/31 功能类，版本 2.0，2011 年 9 月 18 日](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Zertifizierung/Interpretationen/AIS_31_Functionality_classes_for_random_number_generators_e.pdf?__blob=publicationFile&v=2) - [AIS 20/31 功能类，版本 3.0，2024 年 9 月 10 日](https://www.bsi.bund.de/SharedDocs/Downloads/EN/BSI/Certification/Interpretations/AIS_31_Functionality_classes_for_random_number_generators_e_2024.pdf?__blob=publicationFile&v=3) - [非官方 Saarinen BSI AIS 31 V1.0 测试套件存档](https://github.com/mjosaarinen/ais31-testsuite-v1.0) - [NIST IR 8446 最终版：连接随机数生成标准之间的差距](https://csrc.nist.gov/pubs/ir/8446/final) - [NIST IR 8446 初始公开草案，现在已被最终报告取代](https://csrc.nist.gov/pubs/ir/8446/ipd) 截至 2026 年 5 月，BSI 发布 AIS 20/31 功能类版本 3.0 作为当前的数学-技术参考。这里包装的 Java 测试套件仍然是围绕版本 2.0 描述的统计测试 A 和 B 的较老的 AIS 31 V1.0 参考实现；将此项目作为该参考实现的框架使用，而不是作为 BSI Java 版本 3.0 的新实现的证据。

标签：Automated Testing, Bit Width, BSI AIS 31 V1, Command Line Interface, Data Parsing, Execution, External Artifact, Headless Application, Installation, JDK, JSON Output, JS文件枚举, Log Message Capture, Python CLI, Random Data, Software Harness, Source Encoding, Structured Data, Swing GUI, Test Suite, Test Suite Execution, Test Suite Parsing, 文档结构分析, 逆向工具