C 语言接入

SDK 1.2.0 提供真正的 C ABI。纯 C 项目只需包含 guangnian/c_api.h，不需要接触 C++ 类、JSON 类型、HMAC 或 nonce 实现；底层仍复用与 C++ SDK 相同的 libcurl、OpenSSL 和 /api/v1 会话协议。

官方 C ABI

gn_config config;
memset(&config, 0, sizeof(config));
config.base_url = "https://你的域名";
config.app_id = "程序ID";
config.sign_key = "项目密钥";
config.sdk_version = gn_sdk_version();

gn_client *client = gn_client_create(&config);
if (client == NULL) {
    fprintf(stderr, "%s\n", gn_last_create_error());
    return 1;
}

gn_result *login = gn_card_login(client, "卡密", gn_machine_id());
if (login == NULL || !gn_result_success(login)) {
    fprintf(stderr, "%s [%s]\n",
        gn_result_message(login), gn_result_request_id(login));
    gn_result_free(login);
    gn_client_free(client);
    return 1;
}
gn_result_free(login);

gn_result *heartbeat = gn_card_heartbeat(client);
/* 处理 success / relogin_required 后释放结果 */
gn_result_free(heartbeat);
gn_client_free(client);

gn_client 和 gn_result 都是不透明对象。任何从 gn_result_message()、gn_result_request_id() 或 gn_result_data_json() 获得的指针只在对应结果释放前有效。每个结果只释放一次；gn_client_free() 会清理 SDK 内存中的签名密钥、会话令牌和设备缓存。

构建

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

CMake 会用 C 编译器编译 examples/quick_start.c，再通过 C++ 链接器连接安全核心。生产构建默认只允许 HTTPS，并启用证书校验、TLS 1.2 下限、HMAC-SHA256、随机 nonce、响应大小限制和编译器加固。

手写 HTTP V3

无法链接官方 SDK 时，才直接使用 libcurl 和 OpenSSL 实现 HTTP V3：

基本流程

1. 使用 curl_easy_escape 对表单值编码。
2. 先生成最终 BODY，再对完全相同的字节计算 SHA-256。
3. 拼接 V3 规范串并计算 HMAC-SHA256。
4. 设置 X-GN-* 请求头后发送 POST。
5. 限制响应体大小并解析 JSON。
6. 使用业务 code 判断结果。

curl_easy_setopt(curl, CURLOPT_URL,
    "https://你的域名/api/legacy/v3/cards/login");
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, body);
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
curl_easy_setopt(curl, CURLOPT_TIMEOUT, 15L);
curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 1L);
curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 2L);

DANGER

不要关闭 TLS 证书校验，不要使用固定 nonce，也不要把卡密、令牌或签名密钥完整写入日志。

需要登录会话和心跳时应优先使用上面的官方 C ABI，不要重复手写同一套协议。