【ZeroRange WebRTC】KVS WebRTC 示例中的 HTTP 通信安全说明

KVS WebRTC 示例中的 HTTP 通信安全说明

本文解释 amazon-kinesis-video-streams-webrtc-sdk-c 的 Sample（例如 ./samples/kvsWebrtcClientMaster）在调用 KVS 管理面 API（如 GetIceServerConfig）时，HTTP 通信如何实现安全：包括 TLS 信道安全、请求级鉴权（SigV4）、时间与重放控制、证书与区域配置，以及与日志/源码的对应关系与实践建议。

---

1. 分层安全模型

• TLS 信道（HTTPS） ：保障传输"保密性/完整性/服务器真实性"。
  • 客户端通过 TLS 握手验证服务端证书（根 CA 由 pChannelInfo->pCertPath 或系统 CA 提供）。
  • 握手后，HTTP 报文在 TLS 信道内加密传输，抵御窃听与篡改。
• 请求级鉴权（AWS SigV4） ：保障"调用者身份与每个请求的不可抵赖性"。
  • 通过 Authorization: AWS4-HMAC-SHA256 ... 对请求进行签名，服务端在零信任网络中验证该签名及所含时间/区域/服务信息。

两者结合：TLS 负责信道安全，SigV4 负责应用级鉴权与审计/配额控制。

为什么在有 TLS 的前提下仍需要 SigV4

• 身份与授权：TLS 只验证"服务器真伪"，无法识别"调用者是谁"。SigV4 用 AccessKeyId/Secret 派生签名，绑定到 IAM 身份与权限策略，从而对 Describe/GetEndpoint/GetIceServerConfig/Create/Delete 等控制面操作做授权判定。
• 请求级完整性与不可抵赖：SigV4对"规范化请求"（方法、URI、查询、已签名头、负载哈希）做 HMAC-SHA256。即便 TLS 在边界终止并内部转发，服务仍能在应用层验证请求未被修改且来自拥有密钥的主体。
• 时间语义与防重放：SigV4携带 X-Amz-Date 并有有效窗口校验；过期或重放请求会被拒绝。TLS 仅保护在途数据，不表达"这次调用的时间有效性"。
• 多租户审计与配额：云服务需按账号/角色做审计、限流/配额与计费。SigV4 将主体与每个请求绑定，便于记录到审计系统并施加配额与信任策略；TLS 不提供账户级治理语义。
• 区域/服务绑定：SigV4 的 Credential Scope（/Date/Region/Service/aws4_request）限定请求作用域，避免跨区/跨服务的误用或滥用；TLS 不包含这层约束。
• 纵深防御：若代理/负载均衡进行 TLS 终止或合规检查，SigV4 作为"信封内的签名"仍能在最终服务端核验请求真实性与完整性。

示例对应（日志/源码映射）：

• 终端日志可见请求头：
  • Authorization: AWS4-HMAC-SHA256 Credential=.../us-west-2/kinesisvideo/aws4_request, SignedHeaders=host;user-agent;x-amz-date, Signature=...
  • X-Amz-Date: 2025...Z
• TLS 握手日志显示：TLS_AES_256_GCM_SHA384, TLSv1.3（传输层已加密）。
• 构造与签名：createRequestInfo(...) 设置 Authorization/X-Amz-Date（src/source/Signaling/LwsApiCalls.c）。
• 时钟偏差修正：checkAndCorrectForClockSkew(...) 保证时间校验通过。

---

2. TLS 握手与配置（源码/日志对应）

• libwebsockets + OpenSSL ：SDK 使用 LWS 创建 TLS 客户端上下文。
  • 日志示例：
    • Compiled with OpenSSL support
    • Doing SSL library init
    • loaded ssl_ca_filepath（已加载根 CA）
    • created client ssl context for default
    • Default ALPN advertisment: h2,http/1.1（通过 ALPN 选择 HTTP/2 或 HTTP/1.1）
• 证书来源 ：
  • 通过 pChannelInfo->pCertPath 指定根 CA（仓库包含示例证书 certs/cert.pem），或使用系统 CA。
  • 作用：为 TLS 客户端提供"受信任的根证书集合"，用于验证 KVS 服务端证书链与主机名匹配，防止中间人攻击与伪造服务。
  • 注意：这是"根 CA 信任链"，并非客户端证书（SDK 默认不启用 mTLS）；路径错误或证书不匹配将导致 TLS 握手失败，从而 REST/WSS 调用均不可用。
  • 建议：生产环境优先使用系统 CA（保持系统更新），开发/隔离环境可显式设置为 certs/cert.pem 以确保握手成功；同时确保目标主机与 Region 正确（SNI/域名匹配）。
• 主机名与 SNI/ALPN ：
  • SNI 在 TLS 握手中声明目标主机，ALPN 协商 HTTP/2/HTTP/1.1。
• 验证要点 ：
  • 验证证书链与主机名匹配；失败则中止连接（防止伪造服务）。

---

3. AWS SigV4 请求签名（字段含义）

• 日志示例（请求头）：
  • Authorization: AWS4-HMAC-SHA256 Credential=AKIA.../20251111/us-west-2/kinesisvideo/aws4_request, SignedHeaders=host;user-agent;x-amz-date, Signature=...
  • X-Amz-Date: 20251111T072740Z
  • Host: r-b8358a07.kinesisvideo.us-west-2.amazonaws.com
• 签名流程（概念） ：
  1. 形成 Canonical Request（方法、URI、查询、已签名的头部与其值、payload 哈希）。
  2. 形成 String to Sign（算法、日期、Credential Scope、Canonical Request 哈希）。
  3. 基于 SecretAccessKey 派生签名密钥：kSecret -> kDate -> kRegion -> kService -> kSigning。
  4. 使用派生密钥对 String to Sign 做 HMAC-SHA256，得到 Signature。
• 字段说明 ：
  • Credential=AccessKeyId/Date/Region/Service/aws4_request：表明凭证作用域。
  • SignedHeaders=...：签名包含的头部列表（防篡改）。
  • Signature=...：最终签名值。
  • X-Amz-Date：UTC 时间戳（避免重放与配合时钟校验）。
  • 若使用临时凭证，还会出现 X-Amz-Security-Token（日志中"Session token is set but empty. Ignoring."表明本次未携带或为空）。

---

4. 时间与重放控制（时钟/TTL）

• 时钟要求：SigV4 对请求时间敏感；本机时钟需与 UTC 同步（否则签名会被判定过期或未生效）。
• 代码中的时钟偏差修正 ：
  • checkAndCorrectForClockSkew(pSignalingClient, pRequestInfo);（src/source/Signaling/LwsApiCalls.c），用于在检测到偏差时进行矫正以避免签名失败。
• 短期有效性 ：
  • 服务端结合 X-Amz-Date 与签名有效窗口拒绝过期/重放请求。
  • TURN 凭证（Username/Password）还具有 Ttl（如 300 秒），过期必须刷新（与 SigV4 请求独立，但同样依赖时钟准确）。

---

5. 与示例请求/响应的关系（GetIceServerConfig）

• 请求 ：POST /v1/get-ice-server-config（REST 管理面，HTTPS）。
  • SDK 通过 createRequestInfo(...) 生成并签名请求（区域 us-west-2、服务 kinesisvideo）。
• 响应 ：JSON 包含 IceServerList（Uris/Username/Password/Ttl）。
  • 日志：lwsHttpCallbackRoutine(): Received client http read response: { "IceServerList": [ ... ] }。
• 后续使用 ：示例通过 signalingClientGetIceConfigInfo* 读取条目，填充 RtcConfiguration.iceServers，用于 ICE 候选收集。

---

6. 实践建议

• 证书与主机：确保根 CA 正确可用、主机名匹配（避免"证书验证失败"）。
• 时钟同步：保持系统时钟准确，避免 SigV4 与 TURN TTL 的时间问题。
• 最小权限 ：限制 IAM 凭证权限（仅允许必要的 kinesisvideo:* 管理面调用）。
• 区域一致：请求的 Region 与信令通道一致（降低跨区时延与出网成本）。
• 日志与审计：保留 Authorization/SignedHeaders/X-Amz-Date 的审计信息，有助诊断签名或时间问题。

---

7. 关联源码与日志

• src/source/Signaling/StateMachine.c: executeGetIceConfigSignalingState()
• src/source/Signaling/LwsApiCalls.h: GET_ICE_CONFIG_API_POSTFIX /v1/get-ice-server-config
• src/source/Signaling/LwsApiCalls.c: createRequestInfo(...)、checkAndCorrectForClockSkew(...)
• 终端日志：Authorization -> AWS4-HMAC-SHA256 ...、X-Amz-Date -> ...、Received client http read response: { "IceServerList": ... }