How can I encode/decode unsigned char* in libsodium c++?

在密码学与安全编程领域，libsodium 凭借其简洁、跨平台且不易误用的 API，成为众多开发者的首选加密库。然而，当面对 unsigned char* 类型的数据时，如何高效地进行编码（如 Base64、十六进制）与解码，仍是许多 C++ 程序员绕不开的痛点。本文将围绕这一核心问题，结合 libsodium 官方函数与社区最佳实践，提供一套清晰可复用的解决方案。

一、为何需要编码/解码 `unsigned char*`？

在加密流程中，unsigned char* 通常用于存储原始密钥、密文或哈希值。这些二进制数据无法直接通过文本协议（如 JSON、HTTP 头）传输，也不能安全地打印到控制台。因此，开发者常需将其转换为可打印字符串（如十六进制或 Base64），传输或存储后再还原为原始字节流。libsodium 内置了 sodium_bin2hex、sodium_hex2bin 以及 Base64 相关函数，可直接对 unsigned char* 进行双向转换。

二、核心函数解析

1. 十六进制编码/解码

编码（binary → hex）
sodium_bin2hex(char *hex, const size_t hexlen, const unsigned char *bin, const size_t binlen)
- hex：目标缓冲区，大小需至少为 binlen * 2 + 1（含 \0）。
- 返回指向 hex 的指针。

解码（hex → binary）
sodium_hex2bin(unsigned char *bin, const size_t binlen, const char *hex, const size_t hexlen, const char *ignore, size_t *bin_len, const char **hex_end)
- ignore：可传入 ":- " 忽略其中的分隔符（如冒号、空格），若不需要则填 NULL。
- bin_len 输出实际解码字节数。

2. Base64 编码/解码

libsodium 提供三种变体：普通 Base64、带 URL 安全字符的 Base64 以及不带填充的变体。常用函数：

编码
sodium_bin2base64(char *b64, const size_t b64len, const unsigned char *bin, const size_t binlen, const int variant)
- variant 可选 sodium_base64_VARIANT_ORIGINAL、sodium_base64_VARIANT_ORIGINAL_NO_PADDING、sodium_base64_VARIANT_URLSAFE 等。

解码
sodium_base642bin(unsigned char *bin, const size_t binlen, const char *b64, const size_t b64len, const char *ignore, size_t *bin_len, const char **b64_end, const int variant)
- 参数含义与十六进制类似，variant 需与编码时一致。

三、C++ 封装实践

由于 libsodium 是 C 风格 API，C++ 开发者常将其封装为 std::vector<unsigned char> 或 std::string 的辅助函数。以下是一段通用代码示例（基于 C++17）：

#include <sodium.h>
#include <string>
#include <vector>
#include <stdexcept>

std::string bin_to_hex(const std::vector<unsigned char>& bin) {
    std::string hex(bin.size() * 2 + 1, '\0');
    sodium_bin2hex(hex.data(), hex.size(), bin.data(), bin.size());
    hex.pop_back(); // 移除结尾 '\0'
    return hex;
}

std::vector<unsigned char> hex_to_bin(const std::string& hex) {
    std::vector<unsigned char> bin(hex.size() / 2);
    size_t bin_len = 0;
    if (sodium_hex2bin(bin.data(), bin.size(), hex.c_str(), hex.size(),
                       NULL, &bin_len, NULL) != 0) {
        throw std::runtime_error("Hexadecimal decoding failed");
    }
    bin.resize(bin_len);
    return bin;
}

std::string bin_to_base64(const std::vector<unsigned char>& bin, int variant) {
    // 计算所需缓冲区大小：((binlen + 2) / 3) * 4 + 1
    size_t b64len = sodium_base64_ENCODED_LEN(bin.size(), variant);
    std::string b64(b64len, '\0');
    sodium_bin2base64(b64.data(), b64len, bin.data(), bin.size(), variant);
    b64.pop_back();
    return b64;
}

std::vector<unsigned char> base64_to_bin(const std::string& b64, int variant) {
    std::vector<unsigned char> bin(b64.size()); // 上限
    size_t bin_len = 0;
    if (sodium_base642bin(bin.data(), bin.size(), b64.c_str(), b64.size(),
                          NULL, &bin_len, NULL, variant) != 0) {
        throw std::runtime_error("Base64 decoding failed");
    }
    bin.resize(bin_len);
    return bin;
}

使用时需注意：libsodium 要求在调用任何函数前执行 sodium_init()，并建议在程序入口处初始化一次。

四、常见陷阱与性能建议

1. 缓冲区大小计算

十六进制：2 * binlen + 1。
Base64：使用宏 sodium_base64_ENCODED_LEN(binlen, variant) 自动计算（含 \0）。
解码时，目标缓冲区可传入 binlen 为 hexlen/2 或 b64len/4*3 的上限，实际长度由 bin_len 返回。

2. 错误处理

所有解码函数返回 -1 表示输入非法（如非 Base64 字符、长度不符合规则）。生产代码中务必检查返回值，避免空指针问题。

3. 安全性

若需处理敏感密钥，建议在编码/解码完成后使用 sodium_memzero() 清除临时缓冲区。
避免将未初始化的 unsigned char* 直接传入解码函数，确保目标内存已清零或使用 std::vector 自动管理。

五、行业应用与总结

libsodium 的编码函数已被广泛应用于密码库（如 libhydrogen）、区块链节点（如 Monero）以及即时通讯软件（如 Signal 的部分组件）中。它们不仅提供了标准的 Base64 / 十六进制转换，还支持原生的“加法”运算，如将两个十六进制字符串直接转换为密文。对于 C++ 开发者而言，掌握 sodium_bin2hex 和 sodium_bin2base64 的封装技巧，能显著提升编码效率并降低内存泄漏风险。

总之，从原始字节到可打印字符串的转换看似简单，但 libsodium 提供的函数兼顾了性能与安全性。结合上述封装范例，您即可在 C++ 项目中无缝处理 unsigned char* 的编码与解码，让加密数据在文本世界畅通无阻。

一、为何需要编码/解码 unsigned char*？