安全

本章演示 OnePath 的两种入网安全机制：TLS 加密通信 与 用户名密码认证。两者都通过统一的会话配置入口设置——onepath_config_set_tls_ca 设证书、onepath_config_set_auth 设凭据——加密/鉴权在 onepath_open_with_config 打开会话时发生。

这两个示例都需要一个预先启动并正确配置的路由节点（TLS 需配置证书链、认证需配置凭据文件）。缺少时会在会话打开阶段返回连接/认证失败并退出，属预期行为。

TLS 加密

客户端用 CA 证书向路由节点发起 TLS 握手，建立加密会话后通过 tls/ 端点加密发布/订阅消息。

关键 OnePath API

• onepath_config_set_mode(cfg, "client") — 设为 client 运行模式
• onepath_config_add_endpoint(cfg, "tls/localhost:7447") — 注入 TLS 连接端点
• onepath_config_set_tls_ca(cfg, ca_cert) — 设置 CA 证书路径，触发 TLS 握手（TLS 配置关键入口）
• onepath_open_with_config — 打开加密会话（握手在此发生）
• onepath_open_config_file — 备选：直接加载配置文件打开会话

onepath_config_t cfg;
onepath_config_new(&cfg);
onepath_config_set_mode(cfg, "client");
onepath_config_add_endpoint(cfg, "tls/localhost:7447");  /* tls/ 端点 */
onepath_config_set_tls_ca(cfg, "./certs/ca.pem");        /* CA 证书 */

if (onepath_open_with_config(&session, cfg) < 0) {       /* 触发 TLS 握手 */
    onepath_config_destroy(cfg);
    return 1;
}
onepath_config_destroy(cfg);
/* 之后声明 Publisher / Subscriber，走加密通道收发 */

cd examples/certs && ./gen_certs.sh && cd ../..      # 生成证书
./examples/build/release/full/onepath_tls_sub        # 订阅端（先启动）
./examples/build/release/full/onepath_tls_pub        # 发布端
./examples/build/release/tiny/onepath_tls_pub --ca /path/to/ca.pem

[ OK ] session established (TLS encrypted)
[ OK ] publisher declared (key=demo/tls/hello)
[ OK ] published: [0] Hello from onepath_tls_pub (encrypted)
[ OK ] subscriber declared (key=demo/tls/**)
[INFO] received PUT: key='demo/tls/hello', value='[0] Hello from onepath_tls_pub (encrypted)'

变体：双后端（v0.8.0 起两个后端均支持 TLS）。TLS client 模式连接路由节点在两个后端完全可用。

TLS 连接失败时，确认证书未过期、CA 路径正确、SAN 包含实际连接的地址。

用户认证

客户端携带 user:password 凭据向已配置认证的路由节点发起鉴权会话，认证通过后发布/订阅消息。

关键 OnePath API

• onepath_config_set_mode(cfg, "client") / onepath_config_add_endpoint — client 模式 + 连接端点
• onepath_config_set_auth(cfg, user, password) — 设置用户名密码凭据（认证关键入口）
• onepath_open_with_config — 打开会话（认证在此发生，被拒返回 < 0）
• onepath_open_config_file — 备选：加载配置文件打开会话

onepath_config_t cfg;
onepath_config_new(&cfg);
onepath_config_set_mode(cfg, "client");
onepath_config_add_endpoint(cfg, "tcp/localhost:7447");
onepath_config_set_auth(cfg, "user1", "password1");   /* 凭据 */

if (onepath_open_with_config(&session, cfg) < 0) {    /* 认证被拒则失败 */
    onepath_config_destroy(cfg);
    return 1;
}
onepath_config_destroy(cfg);
/* 之后声明 Publisher / Subscriber 收发数据 */

echo "user1:password1" > credentials.txt              # 路由节点侧凭据文件（每行 user:password）
./examples/build/release/full/onepath_auth_sub        # 订阅端（先启动）
./examples/build/release/full/onepath_auth_pub        # 发布端
./examples/build/release/full/onepath_auth_pub -u myuser -p mypassword

[ OK ] session established (authenticated as user1)
[ OK ] publisher declared (key=demo/auth/hello)
[ OK ] published: [0] Hello from onepath_auth_pub (user=user1)
[ OK ] subscriber declared (key=demo/auth/**)
[INFO] received PUT: key='demo/auth/hello', value='[0] Hello from onepath_auth_pub (user=user1)'

变体：仅 full。用户名密码认证是完整版的能力边界——精简版不构建该示例，对应配置在精简版返回 ONEPATH_ERR_UNSUPPORTED。

认证失败时，检查路由节点凭据文件格式（每行 username:password）并确认配置已指向该文件。