文档 技术细节 从源代码构建VeraCrypt Windows构建指南

本指南介绍了如何设置一个能够编译VeraCrypt的Windows系统。此外，还描述了如何编译VeraCrypt。
这里以Windows 10/11系统为例进行说明，但其他Windows系统的操作过程类似。
编译当前VeraCrypt Windows二进制文件和驱动程序需要以下组件；可选替代项或仅发布时需要的工具会另行标明：

1. Microsoft Visual Studio 2022，或作为命令行替代方案的Build Tools for Visual Studio 2022
2. MSVC v143 C++工具集，包含x86/x64和ARM64组件
3. Windows 10/11 SDK（10.0.19041.0或更高版本），包括签名脚本所需的signtool.exe。如果SDK和WDK分开安装，请使用匹配的内部版本号。
4. 适用于Windows 10/11并带有Visual Studio 2022扩展的Windows Driver Kit
5. NASM
6. YASM
7. WiX Toolset v3.x（生成MSI包时需要）
8. 旧版BIOS引导加载程序工具（可选；仅在重新构建Boot项目时需要）：Microsoft Visual C++ 1.52、gzip、UPX和dd.exe

以下是操作步骤。点击任何链接可直接跳转到相关步骤：

- 安装NASM
- 安装YASM
- 安装旧版BIOS引导加载程序工具（可选）
- 安装WiX Toolset v3.x
- 安装Microsoft Visual Studio 2022
- 安装Windows Driver Kit
- 安装Build Tools for Visual Studio 2022
- 下载VeraCrypt源代码文件
- 编译VeraCrypt的x64、ARM64和驱动程序版本
- 构建VeraCrypt可执行文件
- 导入证书
- 已知问题

安装NASM

1. 在以下链接下载“nasm-2.08-installer.exe”：
   https://www.nasm.us/pub/nasm/releasebuilds/2.08/win32/
2. 以管理员身份运行该文件
3. 使用默认设置安装NASM
4. 将NASM添加到路径变量中。这将使该命令在命令行中全局可用。
   1. 打开文件资源管理器
   2. 在左侧文件树中，右键单击“此电脑”并选择“属性”
   3. 在右侧菜单中，点击“高级系统设置”
   4. 请点击“环境变量”
   5. 在系统变量区域内，请选择“Path”变量并点击“编辑...”
   6. 点击“新建”并添加以下值：

      C:\Program Files (x86)\nasm

   7. 点击“确定”关闭窗口
5. 要检查配置是否正常工作，请打开命令提示符并查看以下命令的输出：

   nasm

YASM的安装

1. 请创建以下文件夹：
   C:\Program Files\YASM
2. 请在以下链接下载预构建的Win64 YASM zip压缩包：
   https://github.com/yasm/yasm/releases/tag/v1.3.0
3. 由于下载率较低或连接未加密，您的浏览器可能会提示该文件存在安全风险。不过，官方网站是该文件最可靠的来源，因此我们建议允许下载
4. 解压ZIP文件并将文件复制到“C:\Program Files\YASM”
5. 请在以下链接下载“Win64 .exe”文件：
   https://github.com/yasm/yasm/releases/tag/v1.3.0
6. 由于下载率较低或连接未加密，您的浏览器可能会提示该文件存在安全风险。不过，官方网站是该文件最可靠的来源，因此我们建议允许下载
7. 将文件重命名为“yasm.exe”并复制到“C:\Program Files\YASM”
8. 将YASM添加到路径变量中，并为YASM创建一个新的系统变量。这样可以使该命令在命令行中全局可用。
   1. 打开文件资源管理器
   2. 在左侧文件树中，右键单击“此电脑”并选择“属性”
   3. 在右侧菜单中，请点击“高级系统设置”
   4. 请点击“环境变量”
   5. 在系统变量区域内，请选择“Path”变量并点击“编辑...”
   6. 点击“新建”并添加以下值：

      C:\Program Files\YASM

   7. 点击“确定”关闭顶部窗口
   8. 在系统变量区域内，请点击“新建...”
   9. 使用以下值填写表单：

      变量名：YASMPATH
      变量值：C:\Program Files\YASM

   10. 点击“确定”关闭窗口
9. 要检查配置是否正常工作，请打开命令提示符并查看以下命令的输出：

   yasm

   以及

   vsyasm

安装旧版BIOS引导加载程序工具（可选）

使用Visual Studio 2022和当前WDK编译标准VeraCrypt应用程序二进制文件或Windows驱动程序不需要这些工具。仅当你需要重新构建“src\Boot\Windows”中的旧版BIOS引导加载程序，或者构建包含Boot项目的解决方案配置（例如“ReleaseCustomEFI”）时才安装它们。

1. 安装Microsoft Visual C++ 1.52。它可通过付费的Microsoft MSDN订阅获取。如果你没有订阅，也可以从互联网档案馆获取ISO镜像：
   https://archive.org/details/ms-vc152
2. 创建文件夹“C:\MSVC15”。挂载ISO文件并将“MSVC”文件夹的内容复制到“C:\MSVC15”。
3. 创建名为“MSVC16_ROOT”的系统变量，其值为“C:\MSVC15”。
4. 安装gzip，并将包含“gzip.exe”的文件夹添加到Path变量。
5. 安装UPX，并将包含“upx.exe”的文件夹添加到Path变量。
6. 安装Windows版本的dd，并将包含“dd.exe”的文件夹添加到Path变量。
7. 打开新的命令提示符，并确认能够找到以下命令：

   nasm
   gzip
   upx
   dd --help

安装WiX Toolset v3.x

1. 请从以下链接下载WiX Toolset v3.x：
   https://github.com/wixtoolset/wix3/releases
2. 以管理员身份运行下载的文件，并使用默认设置安装 WiX 工具集

安装Microsoft Visual Studio 2022

1. 在以下链接下载Visual Studio 2022：
   https://visualstudio.microsoft.com/vs/
2. 以管理员身份运行下载的安装程序。
3. 选择“Desktop development with C++”工作负载。
4. 选择以下单个组件：
   1. MSVC v143 - VS 2022 C++ x64/x86 build tools (Latest)
   2. MSVC v143 - VS 2022 C++ x64/x86 Spectre-mitigated libs (Latest)
   3. MSVC v143 - VS 2022 C++ ARM64 build tools (Latest)
   4. MSVC v143 - VS 2022 C++ ARM64 Spectre-mitigated libs (Latest)
   5. C++ ATL for latest v143 build tools (x86 & x64)
   6. C++ ATL for latest v143 build tools (ARM64)
   7. C++ ATL for latest v143 build tools with Spectre Mitigations (x86 & x64)
   8. C++ ATL for latest v143 build tools with Spectre Mitigations (ARM64)
   9. C++ MFC for latest v143 build tools (x86 & x64)
   10. C++ MFC for latest v143 build tools (ARM64)
   11. C++ MFC for latest v143 build tools with Spectre Mitigations (x86 & x64)
   12. C++ MFC for latest v143 build tools with Spectre Mitigations (ARM64)
   13. Windows 10/11 SDK (10.0.19041.0或更高版本)

安装Windows Driver Kit

1. 请在以下链接下载与Visual Studio 2022兼容的Windows Driver Kit（WDK）：
   https://learn.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk
2. 以管理员身份运行下载的文件，并使用默认设置安装 WDK。
3. 如果Windows SDK和WDK分开安装，请确保它们的内部版本号匹配。
4. 确保已安装WDK Visual Studio扩展。如果WDK安装程序询问是否要“安装 Windows 驱动程序工具包 Visual Studio 扩展”，请在关闭对话框前选择此选项。在当前的Visual Studio 2022安装程序中，也可以在“单个组件”里选择“Windows Driver Kit”进行安装。
5. 如果单独的VSIX安装程序自动启动，它会检测到Visual Studio 2022作为该扩展的可能目标。请选择它并继续安装。

安装Build Tools for Visual Studio 2022

如果已安装上面列出的Visual Studio 2022组件，则可以跳过此步骤。仅在需要不带完整Visual Studio IDE的命令行构建环境时安装Build Tools。

1. 在以下链接下载Build Tools for Visual Studio 2022：
   https://visualstudio.microsoft.com/downloads/
2. 以管理员身份运行下载的安装程序，并选择“C++ build tools”工作负载。
3. 选择以下单个组件：
   1. MSVC v143 - VS 2022 C++ x64/x86 build tools (Latest)
   2. MSVC v143 - VS 2022 C++ x64/x86 Spectre-mitigated libs (Latest)
   3. MSVC v143 - VS 2022 C++ ARM64 build tools (Latest)
   4. MSVC v143 - VS 2022 C++ ARM64 Spectre-mitigated libs (Latest)
   5. C++ ATL for latest v143 build tools (x86 & x64)
   6. C++ ATL for latest v143 build tools (ARM64)
   7. C++ ATL for latest v143 build tools with Spectre Mitigations (x86 & x64)
   8. C++ ATL for latest v143 build tools with Spectre Mitigations (ARM64)
   9. C++ MFC for latest v143 build tools (x86 & x64)
   10. C++ MFC for latest v143 build tools (ARM64)
   11. C++ MFC for latest v143 build tools with Spectre Mitigations (x86 & x64)
   12. C++ MFC for latest v143 build tools with Spectre Mitigations (ARM64)
   13. Windows 10/11 SDK (10.0.19041.0或更高版本)

下载VeraCrypt源代码文件

1. 访问VeraCrypt的Github仓库：
   https://github.com/veracrypt/VeraCrypt
2. 点击绿色的“Code”按钮并下载代码。
   你可以将仓库下载为zip文件，但也可以考虑使用git协议以便跟踪更改。

编译VeraCrypt的x64、ARM64和驱动程序版本

1. 在Visual Studio 2022中打开文件“src/VeraCrypt.sln”
2. 选择“Release|x64”作为活动配置。
3. 点击“Build -> Build Solution”。
4. 编译过程应仅出现警告，而无错误。部分项目可能会被跳过。
5. 选择“Release|ARM64”作为活动配置。
6. 点击“Build -> Build Solution”。
7. 编译过程应仅出现警告，而无错误。部分项目可能会被跳过。
8. 选择“Release|Win32”作为活动配置并构建解决方案，以编译发布打包脚本使用的Win32安装程序/辅助项目。
9. 要构建VeraCrypt驱动程序，请选择“Driver”项目，并分别为“Release|x64”和“Release|ARM64”构建它。
10. 仅当需要自定义EFI/引导加载程序发布配置时，才构建“ReleaseCustomEFI|x64”或“ReleaseCustomEFI|ARM64”。这些配置包含Boot项目，并需要上面列出的可选旧版BIOS引导加载程序工具。
11. 如果使用Build Tools for Visual Studio 2022而不是Visual Studio IDE，请以管理员身份打开“Developer Command Prompt for VS 2022”或“Developer PowerShell for VS 2022”，切换到VeraCrypt源代码根目录，并运行等效的MSBuild命令：
    `msbuild src\VeraCrypt.sln /m /p:Configuration=Release /p:Platform=x64
    msbuild src\VeraCrypt.sln /m /p:Configuration=Release /p:Platform=ARM64
    msbuild src\VeraCrypt.sln /m /p:Configuration=Release /p:Platform=Win32
    msbuild src\Driver\Driver.vcxproj /m /p:Configuration=Release /p:Platform=x64
    msbuild src\Driver\Driver.vcxproj /m /p:Configuration=Release /p:Platform=ARM64`
    要构建可选的自定义EFI/引导加载程序发布配置，还请运行：
    `msbuild src\VeraCrypt.sln /m /p:Configuration=ReleaseCustomEFI /p:Platform=x64
    msbuild src\VeraCrypt.sln /m /p:Configuration=ReleaseCustomEFI /p:Platform=ARM64`
12. 如果是从IDE构建的，请在编译完成后关闭Visual Studio 2022。

构建VeraCrypt可执行文件

1. 以管理员身份打开Visual Studio 2022命令行，以确保Windows SDK签名工具（包括“signtool.exe”）在Path中可用
2. 进入“src/Signing/”文件夹
3. 运行脚本“sign_test.bat”
4. 你将在“src/Release/Setup Files”文件夹中找到生成的可执行文件

导入证书

使用sign_test.bat脚本，你刚刚对VeraCrypt可执行文件进行了签名。这是必要的，因为Windows仅接受由签名证书颁发机构信任的驱动程序。
由于你没有使用官方的VeraCrypt签名证书来签署代码，而是使用了公共开发版本，因此你需要导入并信任所使用的证书。

1. 打开“src/Signing”文件夹
2. 通过双击以下证书，将它们导入到本地计算机证书存储中：
   - GlobalSign_R3Cross.cer
   - GlobalSign_SHA256_EV_CodeSigning_CA.cer
   - TestCertificate/idrix_codeSign.pfx
   - TestCertificate/idrix_Sha256CodeSign.pfx
   - TestCertificate/idrix_SHA256TestRootCA.crt
   - TestCertificate/idrix_TestRootCA.crt
   注意：如果提示输入密码，.pfx证书的密码为 idrix。

已知问题

- 此分发包已损坏
  在Windows 10或更高版本上，你可能会收到上述错误消息。为避免此问题，你需要：
  - 仔细检查颁发测试代码签名证书的根证书是否已安装在“本地计算机受信任的根证书颁发机构”存储中。
  - 计算测试代码签名证书的SHA512指纹，并相应地更新“src/Common/Dlgcode.c”文件中的gpbSha512CodeSignCertFingerprint数组。
  有关详细信息，请参阅 https://sourceforge.net/p/veracrypt/discussion/technical/thread/83d5a2d6e8/#db12。
  另一种方法是在VeraCrypt代码中禁用签名验证。此操作仅应在测试环境中使用，切勿用于生产环境：
  1. 打开“src/Common/Dlgcode.c”文件
  2. 查找“VerifyModuleSignature”函数
  3. 替换以下代码行：
     查找：

     if (!IsOSAtLeast (WIN_10))
     return TRUE;

     替换为：

     return TRUE;

  4. 再次编译VeraCrypt代码
- 自定义构建的VeraCrypt安装过程中驱动程序安装失败
  Windows会验证每个要安装的驱动程序的签名。
  出于安全原因，Windows仅允许由Microsoft签名的驱动程序加载。
  因此，在使用自定义构建时：
  - 如果你未修改VeraCrypt驱动程序源代码，则可以使用VeraCrypt源代码中包含的由Microsoft签名的驱动程序（位于“src\Release\Setup Files”下）。
  - 如果你进行了修改，你需要将Windows启动到“测试模式”。此模式允许Windows加载未由Microsoft签名的驱动程序。但是，即使在“测试模式”下，签名也有特定要求，并且由于以下原因仍可能会失败。
  “测试模式”下安装失败的潜在原因：
  1. 用于签名的证书不受Windows信任
     你可以通过检查可执行文件的属性来验证是否受影响：
     1. 右键单击VeraCrypt安装可执行文件：“src/Release/Setup Files/VeraCrypt Setup 1.XX.exe”
     2. 点击“属性”
     3. 转到顶部菜单“数字签名”。在这里，你会在签名列表中找到两个签名
     通过双击勾选这两个签名。如果标题显示“无法验证签名中的证书”，则相应的签名证书未正确导入。
     点击“查看证书”，然后点击“安装证书...”，将证书导入到本地计算机证书存储区。对于根证书，你可能需要选择“将所有证书放入下列存储区”，并选择“受信任的根证书颁发机构”存储区。
  2. 驱动程序在签名过程之后被修改。
     在这种情况下，请使用脚本“src/Signing/sign_test.bat”，用测试证书再次对你的代码进行签名