Windows下编译与使用OpenSSL库指南 – wiki基地

作者： /

Windows 下编译与使用 OpenSSL 库终极指南

摘要

OpenSSL 是一个强大的、开源的、功能齐全的加密库，广泛应用于网络安全、数据加密、数字签名等领域。虽然许多平台提供预编译的 OpenSSL 版本，但在 Windows 环境下，开发者有时需要根据特定需求（例如启用/禁用特定算法、构建特定架构版本、获取最新功能或安全补丁）自行编译。本文将提供一个详细的分步指南，涵盖在 Windows 平台上从源码编译 OpenSSL 库，并在 C/C++ 项目中集成和使用的完整过程，同时探讨常见问题和注意事项。

目录

  1. 引言
    • 什么是 OpenSSL？
    • 为什么要在 Windows 上编译 OpenSSL？
    • 编译的优势与挑战
  2. 准备编译环境
    • 安装 Visual Studio
    • 安装 Perl
    • 安装 NASM 汇编器
    • 获取 OpenSSL 源代码
  3. 配置与编译 OpenSSL
    • 选择合适的命令行环境
    • 解压源代码
    • 配置（Configure）
      • 理解配置选项
      • 常用配置示例（32 位/64 位，静态/动态，Debug/Release）
    • 编译（Build）
    • 测试（Test）
    • 安装（Install）
  4. 在 Visual Studio 项目中使用 OpenSSL
    • 创建示例项目
    • 配置项目属性
      • 包含目录（Include Directories）
      • 库目录（Library Directories）
      • 链接器输入（Linker Input）
    • 理解静态链接与动态链接
      • 静态链接注意事项
      • 动态链接注意事项（DLL 部署）
    • 编写示例代码（如计算 SHA256 哈希）
  5. 常见问题与故障排除
    • Perl 或 NASM 未找到
    • 编译错误
    • 链接器错误（无法解析的外部符号）
    • 运行时错误（DLL 找不到）
  6. 替代方案：使用预编译库
    • 流行的预编译库提供者
    • 包管理器（vcpkg, Conan）
    • 何时选择预编译库
  7. 安全注意事项
    • 及时更新 OpenSSL 版本
    • 安全配置选项
    • 避免硬编码敏感信息
  8. 结论

1. 引言

  • 什么是 OpenSSL？
    OpenSSL 项目是一个开源的、强大的、商业级的、功能齐全的工具包，实现了安全套接字层（SSL v2/v3）和传输层安全（TLS v1.x）协议，以及一个强大的通用密码库。它被广泛用于保护网络通信，如 HTTPS（Web）、SMTPS（Email）、VPNs 等。除了协议实现，它还提供了丰富的加密算法（对称加密、非对称加密、哈希函数）、证书管理工具、密钥生成功能等。

  • 为什么要在 Windows 上编译 OpenSSL？
    虽然存在一些第三方提供的预编译 Windows 版 OpenSSL 库，但自行编译提供了以下优势：

    • 最新版本： 可以获取官方最新的稳定版或开发版，包含最新的功能和安全修复。
    • 定制化： 可以根据项目需求启用或禁用特定的加密算法、协议或功能，减小库的体积或满足特定的合规性要求。
    • 架构与配置： 可以精确控制编译目标（32 位/64 位）、构建类型（Debug/Release）以及链接方式（静态/动态）。
    • 一致性： 确保使用的 OpenSSL 版本与特定依赖项或开发环境完全兼容。
    • 学习与理解： 编译过程有助于更深入地理解 OpenSSL 的构建系统和依赖关系。

  • 编译的优势与挑战
    优势如上所述，主要在于控制力和灵活性。挑战则在于 Windows 平台本身并非 OpenSSL 的原生开发环境，编译过程相对 Linux/macOS 更为复杂，需要配置多个依赖项（Perl, NASM, Visual Studio），并且需要理解其独特的构建脚本和配置选项。

2. 准备编译环境

在开始编译之前，必须确保安装了所有必要的工具。

  • 安装 Visual Studio
    OpenSSL 在 Windows 上的编译主要依赖 Microsoft Visual C++ (MSVC) 编译器。

    • 访问 Visual Studio 官网 下载并安装 Visual Studio（推荐 Community、Professional 或 Enterprise 版本）。
    • 在安装过程中，确保选中 “使用 C++ 的桌面开发” 工作负载。这将安装所需的 C++ 编译器、Windows SDK 和相关工具。
    • 记录下你的 Visual Studio 版本（如 VS 2019, VS 2022），配置时需要用到。

  • 安装 Perl
    OpenSSL 的构建系统（Configure 脚本）是基于 Perl 的。

    • 推荐安装 Strawberry Perl (http://strawberryperl.com/) 或 ActivePerl (https://www.activestate.com/products/perl/)。Strawberry Perl 通常更受推荐，因为它包含了 MinGW 工具链，有时能解决一些依赖问题，并且更接近 *nix 环境。
    • 下载适用于你 Windows 架构（32 位或 64 位）的安装程序并执行安装。
    • 关键： 确保在安装过程中将 Perl 添加到系统的 PATH 环境变量中。安装完成后，可以在命令提示符 (cmd) 或 PowerShell 中运行 perl -v 来验证安装是否成功以及 PATH 配置是否正确。

  • 安装 NASM 汇编器
    Netwide Assembler (NASM) 用于编译 OpenSSL 中性能关键部分的汇编代码，尤其是在 64 位架构上。

    • 访问 NASM 官网 下载最新的稳定版 Windows 安装程序（nasm-X.YY.ZZ-installer-x64.exe 或 x86.exe）。
    • 运行安装程序进行安装。
    • 关键： 同样，确保将 NASM 的安装目录添加到系统的 PATH 环境变量中。安装完成后，运行 nasm -v 验证安装和 PATH 配置。

  • 获取 OpenSSL 源代码

    • 访问 OpenSSL 官网的下载页面。
    • 选择一个最新的稳定版本（例如 openssl-3.x.y.tar.gz 或 openssl-1.1.1x.tar.gz）。除非有特殊需求，通常推荐使用最新的长期支持（LTS）版本或最新的稳定版本。本文以 OpenSSL 3.x 为例，但步骤对 1.1.1 系列也基本适用（配置目标可能略有不同）。
    • 下载 .tar.gz 格式的源代码压缩包。你需要一个解压工具（如 7-Zip）来处理它。

3. 配置与编译 OpenSSL

  • 选择合适的命令行环境
    极其重要： 必须使用 Visual Studio 提供的 开发者命令提示符 (Developer Command Prompt for VS)。不要使用标准的 cmd.exe 或 PowerShell。

    • 在 Windows 开始菜单中搜索 “Developer Command Prompt for VS [你的版本]”（例如 “Developer Command Prompt for VS 2022″）。
    • 根据你要编译的目标架构（32 位/x86 或 64 位/x64），选择对应的提示符，例如 “x64 Native Tools Command Prompt for VS 2022″。
    • 这个特殊的命令提示符会自动设置好指向 MSVC 编译器、链接器、库、头文件等的环境变量，这是成功编译的关键。

  • 解压源代码

    • 使用 7-Zip 或其他解压工具，将下载的 openssl-X.Y.Z.tar.gz 解压到一个你选择的工作目录，例如 C:\dev\openssl-3.1.0。避免使用包含空格或特殊字符的路径。

  • 配置（Configure）

    • 在打开的开发者命令提示符中，cd 进入解压后的 OpenSSL 源代码根目录（例如 cd C:\dev\openssl-3.1.0）。
    • 运行 perl Configure 命令进行配置。你需要指定目标平台和其他选项。

    • 理解配置选项：

      • 目标平台： 这是最重要的选项。
        • 对于 64 位 Windows：通常使用 VC-WIN64A
        • 对于 32 位 Windows：通常使用 VC-WIN32
        • 可以在源代码目录运行 perl Configure 不带参数查看所有支持的平台。
      • --prefix=<path>：指定 nmake install 命令将最终的头文件、库文件、可执行文件安装到的目录。强烈建议指定一个清晰的、位于源代码目录之外的路径，例如 C:\dev\openssl-build\x64-release-shared。如果不指定，默认可能安装到 C:\Program Files\OpenSSL 或类似系统目录，这通常需要管理员权限且可能引起混淆。
      • --openssldir=<path>：指定 OpenSSL 配置文件（openssl.cnf）和其他运行时文件的默认查找路径。通常可以设置为与 --prefix 相同，或其下的 ssl 子目录。例如 --openssldir=C:\dev\openssl-build\x64-release-shared\ssl。
      • shared：构建动态链接库（DLLs：libcrypto-*.dll, libssl-*.dll）和导入库（.lib）。这是 Windows 上的常用方式。
      • no-shared：构建静态库（.lib：libcrypto.lib, libssl.lib）。所有代码会链接到你的最终可执行文件中。
      • debug：构建调试版本，包含调试符号，不进行优化。库文件名可能带有 _d 后缀。
      • release：构建发布版本，进行优化，不含调试符号（默认）。
      • no-asm：禁用汇编代码优化（不推荐，会影响性能）。
      • no-deprecated：禁止使用已标记为废弃的 API。有助于编写更现代、更安全的代码。
      • enable-<feature>, disable-<feature>：启用或禁用特定算法或功能（如 no-rc4, enable-ec_nistp_64_gcc_128）。运行 perl Configure --help 查看所有选项。

    • 常用配置示例：

      • 64 位，动态链接库 (DLL)，Release 版本，安装到 C:\dev\openssl-inst\x64-release-shared：
        bash
        perl Configure VC-WIN64A --prefix=C:\dev\openssl-inst\x64-release-shared --openssldir=C:\dev\openssl-inst\x64-release-shared\ssl shared
      • 64 位，静态库 (.lib)，Release 版本，安装到 C:\dev\openssl-inst\x64-release-static：
        bash
        perl Configure VC-WIN64A --prefix=C:\dev\openssl-inst\x64-release-static --openssldir=C:\dev\openssl-inst\x64-release-static\ssl no-shared
      • 32 位，动态链接库 (DLL)，Debug 版本，安装到 C:\dev\openssl-inst\x86-debug-shared：
        bash
        perl Configure VC-WIN32 --prefix=C:\dev\openssl-inst\x86-debug-shared --openssldir=C:\dev\openssl-inst\x86-debug-shared\ssl shared debug
        (确保使用 x86 Native Tools Command Prompt)

    • 配置过程会检查环境、生成 Makefile。如果遇到错误（如找不到 Perl 或 NASM），请返回第二步检查安装和 PATH 设置。

  • 编译（Build）

    • 配置成功后，运行 nmake 命令开始编译：
      bash
      nmake
    • nmake 是 Microsoft 的 Make 工具，它会读取 Configure 生成的 Makefile 并执行编译步骤。
    • 编译过程可能需要几分钟到几十分钟，具体取决于你的机器性能和 OpenSSL 的配置。大量的 C 和汇编代码会被编译。

  • 测试（Test）

    • 编译完成后，强烈建议运行测试套件以验证库的正确性：
      bash
      nmake test
    • 测试过程会执行大量的自检程序，覆盖密码算法、协议实现等。如果所有测试通过，会显示类似 “PASS” 的信息。
    • 如果出现测试失败，可能表示编译环境有问题、源代码下载不完整或存在 Bug。检查错误信息，可能需要清理（nmake clean）并重新配置编译。

  • 安装（Install）

    • 测试通过后，将编译好的库、头文件和工具安装到之前 --prefix 指定的目录：
      bash
      nmake install

    • 此命令会将以下内容复制到你的 --prefix 目录：

      • include/openssl/：包含所有必需的头文件 (.h)。
      • lib/：包含库文件。
        • 动态链接：.lib 导入库和 .dll 动态链接库。
        • 静态链接：.lib 静态库文件。
      • bin/：包含 openssl.exe 命令行工具和其他可执行文件（以及动态库的 .dll 文件）。
      • ssl/（或 --openssldir 指定的路径）：包含默认的 openssl.cnf 配置文件和证书存储相关目录。

    • 至此，OpenSSL 库已经成功编译并安装到你指定的本地目录了。

4. 在 Visual Studio 项目中使用 OpenSSL

现在，我们将演示如何在 Visual Studio C++ 项目中链接并使用刚刚编译好的 OpenSSL 库。

  • 创建示例项目

    • 打开 Visual Studio，创建一个新的 C++ 项目（例如，“空项目” 或 “控制台应用”）。

  • 配置项目属性

    • 右键点击解决方案资源管理器中的项目名称，选择“属性”。
    • 确保顶部的“配置”设置为你想要构建的类型（例如 Debug 或 Release）以及“平台”设置为与你编译 OpenSSL 时匹配的架构（例如 x64 或 Win32）。
    • 包含目录（Include Directories）：
      • 导航到 配置属性 -> C/C++ -> 常规。
      • 编辑“附加包含目录”。
      • 添加你之前 nmake install 安装的 OpenSSL 头文件所在的 include 目录的路径。例如：C:\dev\openssl-inst\x64-release-shared\include。
    • 库目录（Library Directories）：
      • 导航到 配置属性 -> 链接器 -> 常规。
      • 编辑“附加库目录”。
      • 添加你 OpenSSL 安装目录下 lib 目录的路径。例如：C:\dev\openssl-inst\x64-release-shared\lib。
    • 链接器输入（Linker Input）：
      • 导航到 配置属性 -> 链接器 -> 输入。
      • 编辑“附加依赖项”。
      • 添加需要链接的 OpenSSL 库文件。通常是 libcrypto.lib 和 libssl.lib。
        • 注意： 如果你编译的是 Debug 版本，库文件名可能带有 d 后缀（例如 libcryptod.lib），需要相应修改。
        • 对于 OpenSSL 3.x，可能还需要链接 legacy.lib 或其他 provider 库，取决于你的使用方式。但 libcrypto.lib 和 libssl.lib 是最核心的。
      • 添加示例：libcrypto.lib;libssl.lib;%(AdditionalDependencies)

  • 理解静态链接与动态链接

    • 静态链接 (no-shared 编译的库)：
      • 链接时，libcrypto.lib 和 libssl.lib 包含所有 OpenSSL 代码。这些代码会被复制到你的最终可执行文件 (.exe) 中。
      • 优点：部署简单，只需要分发你的 .exe 文件。
      • 缺点：.exe 文件体积较大；如果 OpenSSL 有安全更新，需要重新编译并分发整个应用程序。
      • 可能需要定义预处理器宏，例如 _LIB 或 OpenSSL 特定的宏，具体查阅 OpenSSL 文档或头文件。
    • 动态链接 (shared 编译的库)：
      • 链接时，libcrypto.lib 和 libssl.lib 是导入库（stub libraries），只包含指向 DLL 中函数的引用。实际的 OpenSSL 代码在 libcrypto-*.dll 和 libssl-*.dll 文件中。
      • 优点：.exe 文件体积较小；多个应用程序可以共享同一套 DLL；更新 OpenSSL 时，理论上只需替换 DLL 文件（需注意 ABI 兼容性）。
      • 缺点：部署时必须确保 .dll 文件与你的 .exe 文件一起分发，并且能被程序找到。
      • DLL 部署:
        • 最简单的方法是将 libcrypto-*.dll 和 libssl-*.dll（从你安装目录的 bin 文件夹复制）放到与你的 .exe 文件相同的目录下。
        • 或者，可以将包含 DLL 的目录添加到系统的 PATH 环境变量中（不推荐用于应用程序部署）。
        • 或者，使用 Windows 的应用程序清单（Manifest）文件指定依赖。

  • 编写示例代码（计算 SHA256 哈希）
    在你的 C++ 源文件（例如 main.cpp）中添加以下代码：

    “`c++

    include

    include

    include

    include

    include // 包含 SHA256 定义

    include // 包含错误处理函数

    // 解决一些旧版 OpenSSL API 在 MSVC 下的 C4996 警告
    // #pragma warning(disable : 4996)
    // 或者在项目属性 C/C++ -> 预处理器 -> 预处理器定义 中添加 _CRT_SECURE_NO_WARNINGS

    void handleOpenSSLErrors(void) {
    ERR_print_errors_fp(stderr);
    // abort(); // In a real app, probably better error handling
    }

    int main() {
    // — OpenSSL Initialization (Important!) —
    // For OpenSSL 1.1.0 and later, explicit initialization is often not needed,
    // but cleanup might be. However, using explicit init/cleanup is safer.
    // OPENSSL_init_crypto(OPENSSL_INIT_LOAD_CRYPTO_STRINGS | OPENSSL_INIT_ADD_ALL_CIPHERS | OPENSSL_INIT_ADD_ALL_DIGESTS, NULL);
    // ERR_load_crypto_strings(); // Load error strings

    // --- Calculate SHA256 Hash ---
EVP_MD_CTX* mdctx = NULL;
const EVP_MD* md = NULL;
unsigned char hash[SHA256_DIGEST_LENGTH];
unsigned int hash_len;

const char* message = "Hello, OpenSSL on Windows!";

// Get the SHA256 message digest algorithm
md = EVP_get_digestbyname("SHA256");
if (md == NULL) {
    fprintf(stderr, "Error: EVP_get_digestbyname failed.\n");
    handleOpenSSLErrors();
    return 1;
}

// Create and initialize the context
mdctx = EVP_MD_CTX_new();
if (mdctx == NULL) {
    fprintf(stderr, "Error: EVP_MD_CTX_new failed.\n");
    handleOpenSSLErrors();
    return 1;
}

if (EVP_DigestInit_ex(mdctx, md, NULL) != 1) {
    fprintf(stderr, "Error: EVP_DigestInit_ex failed.\n");
    handleOpenSSLErrors();
    EVP_MD_CTX_free(mdctx);
    return 1;
}

// Provide the message to be hashed
if (EVP_DigestUpdate(mdctx, message, strlen(message)) != 1) {
    fprintf(stderr, "Error: EVP_DigestUpdate failed.\n");
    handleOpenSSLErrors();
    EVP_MD_CTX_free(mdctx);
    return 1;
}

// Finalize the hash calculation
if (EVP_DigestFinal_ex(mdctx, hash, &hash_len) != 1) {
    fprintf(stderr, "Error: EVP_DigestFinal_ex failed.\n");
    handleOpenSSLErrors();
    EVP_MD_CTX_free(mdctx);
    return 1;
}

// Clean up the context
EVP_MD_CTX_free(mdctx);

// Print the hash
std::cout << "Message: \"" << message << "\"" << std::endl;
std::cout << "SHA256 Hash: ";
for (unsigned int i = 0; i < hash_len; ++i) {
    std::cout << std::hex << std::setw(2) << std::setfill('0') << (int)hash[i];
}
std::cout << std::endl;

// --- OpenSSL Cleanup (Good Practice) ---
// For OpenSSL 1.1.0+, automatic cleanup happens on exit usually.
// Explicit cleanup:
// EVP_cleanup(); // Cleans up digest and cipher contexts
// CRYPTO_cleanup_all_ex_data(); // Frees ex_data
// ERR_free_strings(); // Frees error strings

return 0;

    }
    “`

    • 编译和运行：
      • 在 Visual Studio 中按 F5 或 Ctrl+F5 编译并运行。
      • 如果一切配置正确：
        • 静态链接：程序应该直接运行并输出 SHA256 哈希值。
        • 动态链接：如果 .dll 文件不在 .exe 旁边或 PATH 中，程序会启动失败，提示找不到 libcrypto-*.dll 或 libssl-*.dll。你需要将这些 DLL 复制到输出目录（例如项目的 x64\Debug 或 x64\Release 文件夹）下，然后再次运行。

5. 常见问题与故障排除

  • Perl 或 NASM 未找到:
    • 错误信息：类似 'perl' is not recognized as an internal or external command... 或找不到 nasm。
    • 解决方案：确认 Perl 和 NASM 已安装，并且它们的安装路径已正确添加到系统的 PATH 环境变量中。关闭并重新打开开发者命令提示符以使 PATH 更改生效。在提示符中运行 perl -v 和 nasm -v 验证。
  • 编译错误 (nmake 失败):
    • 错误信息：通常是 C/C++ 编译错误，指出语法问题、类型不匹配等。
    • 解决方案：
      • 确保使用了正确的开发者命令提示符（x86/x64）。
      • 确保 Visual Studio C++ 组件安装完整。
      • 尝试 nmake clean 清理旧的构建文件，然后重新 perl Configure ... 和 nmake。
      • 检查 OpenSSL 版本与 Visual Studio 版本的兼容性（非常旧的 VS 可能不支持新版 OpenSSL）。
      • 查看详细的错误日志，定位问题发生的源文件和行号。
  • 链接器错误 (无法解析的外部符号 LNK2019/LNK2001):
    • 错误信息：unresolved external symbol _FunctionName referenced in function _main。
    • 解决方案：
      • 确认项目属性中“链接器 -> 输入 -> 附加依赖项”已正确添加 libcrypto.lib 和 libssl.lib（以及可能的 d 后缀或 legacy.lib）。
      • 确认项目属性中“链接器 -> 常规 -> 附加库目录”指向了正确的 OpenSSL lib 目录。
      • 确认项目的目标平台（x64/Win32）与编译 OpenSSL 时使用的平台（VC-WIN64A/VC-WIN32）一致。不能混用 32 位和 64 位库。
      • 如果是 C++ 项目链接 C 库，确保 OpenSSL 头文件使用了 extern "C" {} 包裹（OpenSSL 头文件通常已经处理好了，但自定义封装时要注意）。
      • 确认使用的 OpenSSL API 没有被 no-deprecated 或其他配置选项禁用。
  • 运行时错误 (DLL 找不到):
    • 错误信息：应用程序启动时弹出对话框，提示“无法启动此程序，因为计算机中丢失 libcrypto-*.dll。尝试重新安装该程序以解决此问题。”
    • 解决方案（针对动态链接）：
      • 将 OpenSSL 安装目录下 bin 文件夹中的 libcrypto-*.dll 和 libssl-*.dll 文件复制到你的应用程序可执行文件 (.exe) 所在的目录。
      • 或者，将 OpenSSL 安装目录的 bin 文件夹路径添加到系统的 PATH 环境变量（不推荐用于分发）。

6. 替代方案：使用预编译库

虽然编译提供了最大灵活性，但有时使用预编译库更方便快捷。

  • 流行的预编译库提供者:
  • 包管理器:
    • vcpkg (Microsoft): (https://github.com/microsoft/vcpkg) 流行的 C++ 库管理器，可以轻松安装 OpenSSL（它会在后台自动下载源码并编译）。使用 vcpkg install openssl:x64-windows 或 openssl:x86-windows (静态库为 openssl:x64-windows-static 等)。它能很好地与 Visual Studio 集成。
    • Conan: (https://conan.io/) 另一个强大的 C/C++ 包管理器，也支持 OpenSSL。
  • 何时选择预编译库:
    • 项目需求不特殊，标准配置即可满足。
    • 希望快速集成，避免编译的复杂性。
    • 信任提供者的构建过程和及时更新。
    • 使用 vcpkg 或 Conan 等包管理器进行依赖管理。

7. 安全注意事项

使用 OpenSSL（无论编译还是预编译）时，务必关注安全：

  • 及时更新 OpenSSL 版本: OpenSSL 经常发布安全更新以修复漏洞 (CVE)。定期检查官网并更新到最新的安全版本至关重要。如果你是自己编译，需要重新编译和部署。如果使用预编译库或包管理器，依赖提供者及时更新。
  • 安全配置选项: 在编译时，考虑禁用不再安全的旧协议（如 SSLv3, TLSv1.0, TLSv1.1）或弱加密套件（no-ssl3, no-tls1, no-tls1_1, no-weak-ssl-ciphers 等配置选项）。
  • 避免硬编码敏感信息: 不要在代码中硬编码私钥、密码或其他敏感凭证。使用安全的配置管理和密钥存储机制。
  • 正确使用 API: 遵循 OpenSSL 的最佳实践，正确处理错误，管理内存（尤其是 OpenSSL 1.0.x 及更早版本），并理解所使用 API 的安全含义。

8. 结论

在 Windows 上编译 OpenSSL 库虽然比在 Linux/macOS 上稍显复杂，需要仔细配置 Visual Studio、Perl 和 NASM 环境，但它为开发者提供了无与伦比的控制力和灵活性。通过遵循本指南的步骤——准备环境、获取源码、正确配置、编译、测试、安装，以及在 Visual Studio 项目中正确设置包含目录、库目录和链接器依赖——开发者可以成功构建满足特定需求的 OpenSSL 库。理解静态链接与动态链接的区别及其部署要求对于项目的成功至关重要。虽然预编译库和包管理器提供了便捷的替代方案，但掌握自行编译的过程能够加深对 OpenSSL 的理解，并确保在需要时能够应对各种定制化和安全需求。无论选择哪种方式，持续关注 OpenSSL 的安全更新都是保障应用安全的关键一环。

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部