安全通信：TLS 加密与认证

可用性：TLS 传输加密两个变体均支持；用户名密码认证为完整版（Full）专属， 精简版（Tiny）下该 API 在头文件中即被声明剔除，误用在编译期即报错。

概述

OnePath 在会话配置阶段提供两类安全能力，都通过配置构建器 onepath_config_t 一次性设置， 随后用 onepath_open_with_config 打开会话：

• TLS 传输加密：为节点间链路启用 TLS，保护数据在传输中的机密性与完整性。两个变体均 支持，只需提供 CA 证书路径。
• 用户名密码认证：在建立连接时校验对端身份，拒绝未授权节点接入。完整版专属。

两者可单独使用，也可叠加（加密链路 + 身份认证）。

TLS 传输加密

两个变体均支持。

int onepath_config_set_tls_ca(onepath_config_t cfg, const char *ca_path);

设置用于校验对端的 CA 证书路径。配合启用 TLS 的端点（如 tls/host:port 形式的端点地址） 即可让链路走加密传输。

参数	说明
cfg	配置句柄
ca_path	CA 证书文件路径

返回 ONEPATH_OK 成功。

onepath_config_t cfg;
onepath_config_new(&cfg);
onepath_config_set_mode(cfg, "client");
onepath_config_add_endpoint(cfg, "tls/192.168.1.10:7447");  /* 加密端点 */
onepath_config_set_tls_ca(cfg, "/etc/onepath/ca.pem");      /* 校验对端证书 */

onepath_session_t s;
onepath_open_with_config(&s, cfg);
onepath_config_destroy(cfg);

用户名密码认证

完整版（Full）专属。 精简版下 onepath_config_set_auth 在头文件中即被声明剔除， 误用在编译期即报错——这是一条明确的能力边界。

int onepath_config_set_auth(onepath_config_t cfg, const char *user, const char *password);

为会话设置用户名 / 密码凭据，在建立连接时进行身份认证。

参数	说明
cfg	配置句柄
user	用户名
password	密码

返回 ONEPATH_OK 成功。

onepath_config_t cfg;
onepath_config_new(&cfg);
onepath_config_set_mode(cfg, "client");
onepath_config_add_endpoint(cfg, "tls/192.168.1.10:7447");
onepath_config_set_tls_ca(cfg, "/etc/onepath/ca.pem");      /* 加密 */
onepath_config_set_auth(cfg, "alice", "s3cr3t");            /* 认证（仅 Full） */

onepath_session_t s;
onepath_open_with_config(&s, cfg);
onepath_config_destroy(cfg);

加密与认证叠加使用

生产环境建议同时启用 TLS 加密与身份认证：TLS 保护链路上的数据不被窃听 / 篡改， 认证拒绝未授权节点接入。两者通过同一个配置构建器设置，互不冲突。

配置生命周期

onepath_config_new(&cfg);          /* 创建配置构建器 */
/* ... set_mode / add_endpoint / set_tls_ca / set_auth ... */
onepath_open_with_config(&s, cfg); /* 内部拷贝配置，cfg 仍有效 */
onepath_config_destroy(cfg);       /* 用完务必销毁 */

onepath_open_with_config 内部拷贝配置，调用后 cfg 仍有效；无论是否传给过它，最终都 须 onepath_config_destroy 释放。完整的会话与配置接口见 会话管理。

创建 / 销毁配对

创建	销毁
onepath_config_new	onepath_config_destroy
onepath_open_with_config	onepath_close