应用场景

适用于两个设备之间的会话密钥共享，参与双方可以是两个终端、两个业务服务器、或一个终端 + 一个业务服务器。 主叫端先向密服平台申请会话密钥并通知被叫端（携带相同会话ID），被叫端再发起申请——由于会话ID相同， 平台识别为同一业务密钥请求，向双方下发相同的业务密钥（加密下发，SDK 自动解密）。

• 会话ID由应用生成，最大 32 字符，两端必须一致且不可复用
• 加解密方向可互换，密钥使用是本地过程，与平台无关
• 用完即销毁：内存仓库默认最多 64 个密钥句柄，只申请不销毁会导致仓库满
• 需长期保存可用 QCF_ExportKey 导出，导出后 SDK 自动销毁内存密钥

SaaS 平台结合点

• 每次密钥申请经序列号门控校验并计次扣费，配额耗尽即拒绝（fail-closed）
• 密话密信（im_av）模块的端到端加密即基于此模式，按通话/消息密钥次数计费
• 管理后台实时查看密钥配额消耗与计费统计，支持按租户分账

主要涉及接口

QCF_Init QCF_Auth QCF_ApplyKeyWithSessionID QCF_EncryptUpdate QCF_DecryptUpdate QCF_DestoryKey

主被叫模式：双方携带相同会话ID向密服平台申请，获得共享会话密钥

终端数量多、密钥更新频繁时，业务服务器可一次性向平台申请一大块会话密钥（最多 1MB）自行管理， 后续按 keyID（密钥标识 + 起始位置 + 长度）分发给终端，终端凭 keyID 向平台申请对应密钥， 长时间无需再次批量申请。强烈建议启用认证码，确保只有指定终端能用该 keyID 取到密钥。

批量获取：服务器申请大块密钥，终端凭 keyID 获取对应会话密钥

• 密钥明文由业务服务器自行管理，记录每块密钥的分配对象、起始位置与长度
• 一块密钥可分发给多台业务服务器，流程相同
• SaaS 平台侧仅需一次批量申请计费，大幅降低高频小申请的配额压力

QCF_ApplyBulkKey QCF_ApplyKeyWithKeyID QCF_CalcKeyAuthMAC

适用于终端无法直接联网访问密服平台、但可通过自身业务服务器间接连接的场景。 核心思路：把终端的充注密钥当作会话密钥使用——终端读取本地充注密钥并将其 keyID 发给业务服务器， 服务器向平台申请该 keyID 对应的会话密钥，双方即共享相同密钥。终端集成 TSDK，服务端集成 SSDK。

物联网模式总览：终端经业务服务器间接与密服平台共享密钥

模式 1：获取密钥 + 加解密合并

• QCF_EncryptWithWrap / QCF_DecryptWithWrap 将取密钥与加解密打包为一次调用
• 密文中自动携带 keyID，解密方据此先取密钥再解密
• 每次上下行固定消耗 16 字节充注密钥，密钥句柄由 SDK 内部管理
• 适合低频上报：终端定时上报监控数据、服务端偶尔下发指令

模式 2：仅共享会话密钥（分离）

• 终端读本地充注密钥直接作为会话密钥，把 keyID 发给服务器；服务器凭 keyID 向平台申请同一密钥
• 密钥更新节奏、加解密方向由应用自主灵活掌控，充注密钥消耗更省
• 建议启用认证码，防止任意入网账户凭 keyID 申请密钥
• 适合高频交互：终端与服务端业务数据往来频繁

SaaS 平台结合点

• 终端以序列号一机一密接入门控，非法设备直接拒绝入网
• 海量终端的授权、配额与在线状态在管理后台集中管理
• 站点 / 租户两级配额（站点数、租户数、密钥次数）由授权许可统一约束

模式 1 上行：终端 → 业务服务器（EncryptWithWrap）

模式 1 下行：业务服务器 → 终端（DecryptWithWrap）

模式 2：终端与业务服务器凭 keyID 共享充注密钥作为会话密钥

适用于 n（n ≥ 3）个角色需要共享同一会话密钥的场景。创建者向平台申请创建组并指定成员列表， 获得唯一组ID后，所有成员使用相同组ID申请，即可得到相同的组密钥。 成员既可以是终端上的 TSDK 应用，也可以是业务服务器上的 SSDK 应用。

• 一个组最多 200 个成员；创建时不指定成员则任何入网账户均可凭组ID申请，成员数不受限
• 创建组并申请密钥可一步完成，也可拆分为创建组与按组ID申请两个独立动作
• 程序重启后组密钥句柄失效，需长期保存可导出密钥

SaaS 平台结合点

• 量子安全邮件（email）模块的多收件人组密钥自动分发即基于组通信
• IM 多方音视频会议（im_av）共享同一组密钥，全链路端到端加密
• 组密钥申请同样按次计费，后台可审计每个租户的组创建与密钥消耗

主要涉及接口

QCF_CreateGroup QCF_CreateGroupAndApplyKey QCF_ApplyKeyWithGroupID QCF_UpdateGroupMembers QCF_EncryptUpdate QCF_DecryptUpdate QCF_DestoryKey

组通信：创建组 → 分发组ID → 成员凭组ID申请相同组密钥

共享会话密钥的各方分别归属于不同密码服务平台时使用： 如终端 1 在平台 A 充注、终端 2 在平台 B 充注，双方仍希望获得相同会话密钥。 跨平台场景同样支持主被叫与组通信两种模式，分别以 Ex 扩展接口替代原接口（SDK v2.12.0 及以上支持）。 该场景常见于大型集团多平台互联项目。

• 主被叫模式：QCF_ApplyKeyWithSessionIDEx 替代 QCF_ApplyKeyWithSessionID
• 组通信模式：QCF_CreateGroupEx 替代 QCF_CreateGroup
• Ex 接口扩展参数传 NULL 时行为与原接口一致，平滑兼容升级

SaaS 平台结合点

• 集团型客户多站点、多租户架构下的跨平台密钥协同
• 各站点独立计费、统一在管理后台汇总授权与消耗视图

主要涉及接口

QCF_ApplyKeyWithSessionIDEx QCF_CreateGroupEx QCF_ApplyKeyWithGroupID QCF_EncryptUpdate QCF_DecryptUpdate QCF_DestoryKey

跨平台主被叫模式

跨平台组通信模式