usnistgov/ACVP-Server
GitHub: usnistgov/ACVP-Server
NIST 官方的自动化密码验证测试系统服务器实现，用于生成和验证 FIPS 140 密码算法测试向量集。
Stars: 123 | Forks: 38
# 自动化密码验证测试系统 - Gen/Vals
本项目包含美国国家标准与技术研究院 (NIST) 密码算法验证程序 (CAVP) 用于生成和验证联邦信息处理标准 (FIPS) 140 测试向量集的代码。
## ACVP-Server
NIST 对[自动化密码验证协议 (ACVP)](https://github.com/usnistgov/acvp) 的一种实现。本仓库将用于跟踪 NIST 托管的 Demo 和生产环境 ACVP 服务器的部署和问题。服务器实现*可能*与协议规范有所不同。我们将在此仓库中跟踪这些差异。有些修改可能是协议之上 NIST 特有的额外要求。该协议旨在成为通用协议，供任何测试机构托管合规的实例使用。
## 发布
Demo 和生产环境 NIST ACVP 服务器的发布说明通常都会发布在此仓库中。标记为“prerelease”的发布说明适用于 Demo 服务器。标记为“release”的说明适用于生产环境服务器。
## Wiki
* 请参阅 [ACVP-Server Wiki](https://github.com/usnistgov/ACVP-Server/wiki) 获取相关信息，例如关于 ACVP 服务器特定 endpoint 的文档。
* 请参阅 [ACVP 协议 Wiki](https://github.com/usnistgov/ACVP/wiki) 获取有关协议特定用法 / 常见问题解答的信息。
## 问题
请在此仓库中报告在 Demo 或生产环境服务器上发现的问题。可以在此报告的问题包括
* 生成或验证向量集时出错
* 关于服务器/实现的问题
* 关于身份验证的问题
* 注意到与协议规范的差异
* 改进测试的建议
有关规范的问题或疑虑，可以在协议仓库中以 issue 的形式提出。有关 CAVP 使用 ACVP 或 ACVP 如何融入更大的 CMVP 的问题或疑虑，应通过电子邮件发送给 CAVP 的成员。
创建 issue 时，请勿分享任何用于身份验证的机密值。请勿分享 JWT，也请勿分享 TOTP seed。
## 项目结构
ACVTS 可以拆分为两个较大的组件：服务器结构和 Gen/Vals。服务器结构包含多个项目，用于托管 API 并维护 ACVTS 的工作流。Gen/Vals 包含多个专注于生成测试和验证响应正确性的项目。此仓库中的代码仅用于 Gen/Vals。使用此代码，任何人都可以按需为各种算法生成向量集，而无需联系 ACVTS API。
Gen/Vals 可以进一步划分为几个部分：Crypto 代码、Generation 代码和一个 [Orleans](https://github.com/dotnet/orleans) 服务器。此外还有针对这些组件的测试项目。以下是完整的部分列表：
* [示例可执行程序](#samples)
* [GenValAppRunner](#genvalapprunner)
* [Orleans.ServerHost](#orleans-serverhost)
* [src](#src)
* [Common](#common)
* [Generation](#generation)
* [Crypto](#crypto)
* [Orleans](#orleans)
* [Solutions](#solutions)
上述许多部分可能可以进一步细分为更具体的部分，例如抽象与实现及测试，但这些是系统的高层级概念。
### 示例可执行程序
`samples/` 文件夹包含 [GenValAppRunner](#genvalapprunner) 和 [Orleans.ServerHost](#orleans-serverhost) 可运行的应用程序——如果您的意图仅仅是针对算法注册运行生成和验证过程，这是仓库中您唯一需要关注的两个部分。
samples 文件夹中的这两个应用程序是整个程序逻辑和抽象的“包装”应用程序。
#### GenValAppRunner
GenValAppRunner 是一个控制台应用程序，它接受用于其“运行模式”的参数——“check”、“generation”或“validation”。在包含应用程序 `csproj` 文件的文件夹中，可以使用 `dotnet run` 命令调用此应用程序。
有关更多信息，请参阅[运行 Gen/Vals](#runningGenVals)。
#### Orleans ServerHost
Orleans.ServerHost 应用程序是一种将 CPU 密集型工作分配到节点 cluster 的方法。对于本仓库中的 Orleans.ServerHost 示例，应用程序设置为使用“local”集群。采用这种方式可以无需任何额外的基础设施即可运行 GenValAppRunner，但同时也将应用程序的运行限制在本地、单一节点的计算“集群”中。
在更“真实”的场景中，Orleans.ServerHost 应用程序可以作为多个实例启动，并使用高可用性的集群机制，将计算（crypto 调用）分配到 Orleans cluster 内的所有节点中。
此应用程序***必须***处于运行状态，GenValAppRunner 才能运行，因为所有 crypto 调用都是通过 Orleans 计算的。
有关 Orleans 的更多信息，请访问：https://github.com/dotnet/orleans。
Orleans.ServerHost 依赖于 `sharedappsettings.json` 文件中的配置，以告知节点可以并行执行多少个并发工作。Orleans 依赖于客户端和服务器之间的异步通信，因此通过 `MaxConcurrentWork` 属性指定的并发工作量*少于*机器可用的 CPU 数量是非常重要的。必须始终保留一些计算能力，以处理 cluster 中客户端与节点之间的确认和响应。
在运行系统时，如果生成/验证失败，可能是因为 `MaxConcurrentWork` 设置得太高。确定这一点的一种方法是使用 [Orleans.Dashboard](https://github.com/OrleansContrib/OrleansDashboard)，它默认配置为在 Orleans 服务器旁的 8081 端口上运行。
如果 dashboard 上的 CPU 利用率持续超过 95%，您可能需要减少尝试执行的并发工作量，或者为您的 Orleans cluster 启动额外的节点，同时依赖不同于“local clustering”的集群策略。
有关更多信息，请参阅[运行 Orleans Server](#orleans-server)。
### src
应用程序的主要“实质内容”（实现/代码）包含在 src 文件夹及其子文件夹中。
#### Common
可以在其他项目中使用的通用功能。这是构成整个系统的对象依赖关系图的“根”。该项目包含在整个系统其他部分中使用的几个扩展方法、服务和枚举。ACVTS 的一个核心特性是包含在 `~/gen-val/src/common/src/NIST.CVP.ACVTS.Libraries.Math` 中的 `BitString.cs` 类。`NIST.CVP.ACVTS.Libraries.Math` 项目包含许多用于执行密码学操作的数据结构和实用程序。
#### Generation
本部分用于定义贯穿生成和验证过程流程的抽象。对于测试的每个算法，都会针对该抽象的各个部分实现一组新的“策略”。生成过程的一般流程如下：
1. 解析参数 - 将 `registration.json` 解析为 `Parameters.cs`，并通过 `ParameterValidator.cs` 检查其正确性。
2. 生成向量集 - 填充正在测试的算法、模式和 revision 的元数据。
3. 生成测试组 - 测试组是专注于算法内特定属性的一组测试。
4. 生成测试用例 - 测试用例是期望客户端为验证执行的独立工作单元。
5. 分发 Crypto 任务 - 请求 Orleans Server 为定义的测试用例提供内容。测试用例的实际内容生成发生在 `~/gen-val/src/orleans/src/NIST.CVP.ACVTS.Libraries.Orleans.Grains/` 中。
6. 序列化向量集 - 有了内容后，完整的向量集将按照 `ContractResolvers` 的定义被序列化为多个 JSON 文件。
某些算法可能不会完全遵循此过程。有些算法在 Test Group 生成期间需要 crypto 结果，可能会提前发出此类请求。有些算法可能会利用额外的类来区分相似的算法并减少重复代码（例如 CMAC-AES 和 CMAC-TDES）。
验证过程的一般流程如下：
1. 反序列化 InternalProjection 和 SubmittedResults - 必须将 JSON 文件转换回相关的 `TestVectorSet.cs`、`TestGroup.cs` 和 `TestCase.cs` 数据模型。
2. 分配验证器 - 为每个单独的测试用例创建一个 `TestCaseValidator.cs`。
3. 分发验证器 - 执行所有验证器并汇总其结果。
4. 分发 Crypto 任务 - 某些算法可能不允许服务器预先计算结果（即，当 `expectedResults.json` 中提供了来自客户端的输入时），服务器会在此步骤中通过向 Orleans 分发任务来计算结果。
5. 序列化验证文件 - 生成最终的 `validation.json` 文件。
##### Generation.Core
此程序集定义了提供针对算法测试的策略实现所需的接口和基类。除了抽象之外，还有一些实现类，它们遍历尚未提供的策略（通过 `IGenValInvoker` 或 `GenValAppRunner`），以便针对注册/向量集执行生成或验证。
##### Generation
此程序集包含针对 `Generation.Core` 中定义的接口的所有“按算法”的实现。对于测试的每个算法，生成/验证策略都可以在 `Generation` 下找到，并从项目的根目录开始在文件夹或子文件夹中进行组织。协议中的某些算法可能会调用同一套 Gen/Val 代码。
#### Crypto
crypto 程序集定义了抽象 (`Crypto.Common`) 以及系统内使用和测试的所有密码学的实现 (`Crypto`)。通常，生成/验证过程不会直接调用密码学，而是将调用推送到 Orleans cluster；这允许分配 CPU 密集型工作。
#### Orleans
Orleans 下的项目同时定义了 [“Grains”](https://dotnet.github.io/orleans/docs/grains/index.html) 的抽象和实现。这些 grains 是系统中实际执行 crypto 工作的部分。
#### Solutions
包含在 `~/gen-val/src/solutions` 下的解决方案适用于支持生成/验证的每个单独（或一组）算法。
这些解决方案与打开 `GenValAppRunner` 解决方案的不同之处在于，它们包含针对特定算法的 crypto/genvals 测试项目。由于 crypto 和 genvals（集成）测试往往是测试套件中运行时间最长的部分，因此它们不包含在 `GenValAppRunner` 或 `Orleans.ServerHost` 解决方案中。
还有一个 `All.sln`，包含了仓库中的所有项目。在 `All.sln` 上运行测试时请**注意**，这大约需要 12 个小时。
### json-files
此文件夹包含 Gen/Vals 涵盖的所有算法的示例 JSON 文件。当您想快速获取一组完整的文件进行测试时可以使用这些文件。这包括 registration、prompt、internalProjection 和 expectedResults。这些文件由 `~/gen-val/json-files/` 下的 `NIST.CVP.ACVTS.Libraries.Generation..IntegrationTests` 项目中的 `GenValTests.cs` 通过 `GetTestFileLotsOfTestCases()` 测试方法生成。此测试方法成功运行后，将覆盖 `~/gen-val/json-files/` 中现有的算法文件夹。
## 环境配置
提供的代码是使用 .NET6 框架的 C# 代码。这是一个跨平台框架。要运行代码，您需要安装 [.NET6 SDK](https://dotnet.microsoft.com/download/dotnet/6.0)。
创建或修改以下文件：
* 基于现有文件属性修改 `~/gen-val/samples/sharedappsettings.json` 文件。
* 创建如下所述的符号链接。
### 符号链接
符号链接用于将 `Directory.build.props` 和 `Directory.Packages.props` 文件从 `~/_config` 镜像到 `~/`。出于构建目的，它们包含在 `~/config` 中，但出于本地目的，它们需要位于 `~/`。
从项目根目录执行以下 bash 命令将创建所需的符号链接：
```
rm Directory.Build.props
rm Directory.Packages.props
ln -s ./_config/Directory.Build.props
ln -s ./_config/Directory.Packages.props
```
## 运行
为了使 Gen/Vals 正常工作，Orleans Server 必须处于运行状态。
### Gen/Vals
当在调用应用程序时未提供参数时，将打印如上的帮助信息。
要以“generation”模式运行应用程序，应使用 `-g` 标志传入包含要测试的算法注册的文件。请注意，与 ACVP Web API 不同，此 GenValAppRunner 一次仅支持单个算法注册。示例注册文件可以在 `~/gen-val/json-files/` 中找到。
可以使用以下注册来针对 ACVP-AES-CBC 运行 GenValAppRunner 应用程序：
```
{
"vsId": 0,
"algorithm": "ACVP-AES-CBC",
"revision": "1.0",
"isSample": false,
"conformances": [],
"direction": [
"encrypt",
"decrypt"
],
"keyLen": [
128,
192,
256
]
}
```
用户可以在 JSON 中指定 `vsId` 属性。此值将被复制到生成的文件中以用于跟踪。
`algorithm`、`mode` 和 `revision` 属性定义了将要生成或验证的一组算法测试。
`isSample` 布尔标志决定了行为中的某些分支。当 `isSample` 为 true 时，生成代码将生成较少的测试，但同时也会始终生成完整的 `expectedResults.json` 文件。当 `isSample` 为 false 时，情况并非总是如此。
请注意，上述 JSON 对象***并不***包含在“algorithms”对象数组中，而 ACVP Web API 是这样做的。如果上述 JSON 片段保存在“C:/registrations/1971-01-01/registration.json”下，并使用以下命令调用 GenValAppRunner：
```
dotnet run -g "C:/registrations/1971-01-01/registration.json"
```
然后，应用程序将使用 128、192 和 256 的 key 大小，针对 AES-CBC 执行测试向量生成，包含加密和解密操作。
如果成功，生成步骤将产生以下文件：
* `prompt.json`
* 包含要求 IUT 解决的“问题”
* `internalProjection.json`
* 包含向 IUT 提出的“问题”，以及适用的预期答案。
* `expectedResults.json`
* 对 prompt 文件中提出的问题的预期答案。当向量集在生成时使用了 `isSample` 标志，此文件可用作验证文件。
的方法可用于验证一组测试向量：
```
dotnet run -n [answerFile] -b [iutResponsesFile]
```
其中 `answerFile` 是生成步骤生成的 `internalProjection.json`，而 `iutResponsesFile` 可以是 `expectedResults.json` 文件（仅保证在为 sample 注册生成时可用），或者是通过 IUT 测试工具运行 `prompt.json` 后生成的响应文件。这将生成一个 `validation.json` 文件，概述 IUT 答对或答错的测试用例。
也可以在不启动 Orleans Server 的情况下检查算法注册的正确性：
```
dotnet run -c "C:/registrations/1971-01-01/registration.json"
```
### Orleans Server
ACVP 项目使用 [Orleans](https://github.com/dotnet/orleans) 在（潜在的）节点 cluster 中分配 crypto。Gen/Vals 依赖于该可用 cluster，并且配置通过[环境配置](#setting-up)中说明的 `sharedappsettings.json` 提供。
要在本地托管 Orleans Silo，有两个选项：
* 作为控制台应用程序运行
* 在 NIST.CVP.Orleans.ServerHost 目录（即 csproj 所在位置）中运行 `dotnet run --console`
* 从编译好的二进制文件运行：`dotnet NIST.CVP.Orleans.ServerHost.dll --console`
* 作为服务运行
* 在使用 `dotnet publish -c Release` 发布后，从具有管理员权限的命令提示符运行：
sc delete AcvpOrleans # 如果存在
sc create AcvpOrleans binPath= "C:path/to/executable/NIST.CVP.Orleans.ServerHost.dll"
sc start AcvpOrleans
## 测试
仓库中包含了数以万计的单元和集成测试。它们被分类为几个不同的过滤器，以帮助用户了解并运行特定的测试。
* `FastCryptoTest` - 这些测试位于 `NIST.CVP.ACVTS.Libraries.Crypto..Tests` 项目中。每个测试都应在几毫秒内完成。
* `LongCryptoTest` - 这些测试位于 `NIST.CVP.ACVTS.Libraries.Crypto..Tests` 项目中。每个测试可能需要几秒钟到几分钟的时间才能完成。
* `UnitTest` - 这些测试通常用于 `NIST.CVP.ACVTS.Libraries.Generation.Tests` 项目。每个测试都将在几毫秒内完成。
* `FastIntegrationTest` - 这些测试用于 `NIST.CVP.ACVTS.Libraries.Generation..IntegrationTests` 项目。每个测试将需要几秒钟到几分钟的时间。
* `LongRunningIntegrationTest` - 这些测试用于 `NIST.CVP.ACVTS.Libraries.Generation..IntegrationTests` 项目。每个测试将需要几分钟到一个小时的时间。
集成测试类别有两个常见的测试文件。`FireHoseTests.cs` 和 `GenValTests.cs`。`FireHoseTests.cs` 遍历传统的 CAVS 文件，以验证算法的正确序列化和实现。由于通常会覆盖算法的所有功能，因此其中一些文件可能会花费一些时间。`GenValTests.cs` 遍历示例注册以生成 JSON 文件。这需要 Orleans Server 处于运行状态。
要运行与特定 `.csproj` 关联的测试，请在包含 `.csproj` 文件的目录中使用以下命令：
```
dotnet test NIST.CVP.ACVTS.Libraries.Generation.AES_CBC.IntegrationTests.csproj
```
要过滤出特定的测试，请使用以下命令：
```
dotnet test NIST.CVP.ACVTS.Libraries.Generation.AES_CBC.IntegrationTests.csproj --filter Category=FastIntegrationTest
```
## 许可证
NIST 开发的软件由 NIST 作为公共服务提供。您可以在任何介质中使用、复制和分发该软件的副本，前提是您保持本完整声明不变。您可以改进、修改和创建该软件或其任何部分的衍生作品，并且您可以复制和分发此类修改或作品。修改后的作品应带有声明，指出您更改了软件，并应注明任何此类更改的日期和性质。请明确确认美国国家标准与技术研究院为该软件的来源。
NIST 开发的软件明确以“原样”提供。NIST 不作任何明示、暗示、事实上或因法律实施而产生的保证，包括但不限于对适销性、特定用途适用性、不侵权和数据准确性的暗示保证。NIST 既不表示也不保证软件的运行将是不间断的或无差错的，也不保证任何缺陷将被纠正。对于软件的使用或其结果，NIST 不作任何保证或任何表示，包括但不限于软件的正确性、准确性、可靠性或有用性。
您需全权负责确定使用和分发软件的适当性，并承担与其使用相关的所有风险，包括但不限于程序错误、遵守适用法律、数据/程序或设备损坏或丢失以及操作不可用或中断的风险和成本。本软件不适用于任何可能出现故障并导致人身伤害或财产损失风险的情况。NIST 员工开发的软件在美国境内不受版权保护。
## 贡献
通过 PR 为项目做出贡献（尤其是解决已知问题）是非常有帮助的。NIST 有一套接受公开 PR 的流程。对项目贡献的任何代码将被视为来自 NIST，并适用相同的许可协议。如果您正在准备向项目提交较大的 PR，请联系团队以确保这不是我们已经在进行的工作。
## 联系方式
如果您有任何问题或反馈，请联系 Chris Celi，邮箱：christopher.celi (at) nist.gov。
标签：FIPS 140, Homebrew安装, NIST, 加密验证, 合规标准, 密码学, 手动系统调用, 请求拦截