§00概述

用计算代替查表

CKD（Channel Key Derivation）是一种轻量级、无状态、可逆的资源标识派生协议。它把"哪个外部 Key 对应哪个内部 ID"这件事,从一张需要维护的映射表,变成一次可重复的计算。

核心目标

一个内部资源ID，面向多用途派生隔离的外部 Key
无数据库映射，Key本身即可逆向恢复出原始ID
不同用途的Key之间不可互相推导
已知任意数量的外部Key,也无法反推主密钥

数学表现

C → A C → B A → C B → C A 推不出 B B 推不出 A 无需存储 A→C / B→C 映射

查库 vs CKD

把"状态驱动路由"换成"计算驱动路由"，减少两次查库,条形长度按数量级示意。

查库CKD

单次路由延迟

1 ~ 10 ms

0.01 ~ 0.1 ms

单机 QPS

1万 ~ 5万

10万 ~ 50万

横向扩容

受 DB 限制

近线性

Redis / MySQL

需要

不需要

§01快速开始

安装与使用

零外部依赖，仅使用 Go 标准库。

bash

go get github.com/doc-war/ckd

main.go

package main

import (
    "fmt"
    "github.com/doc-war/ckd"
)

func main() {
    // 主密钥：32 字节高熵随机字节串（CSPRNG 生成）
    secret := []byte{
        0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
        0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
        0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
        0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    }

    c, err := ckd.New(ckd.Config{
        CurrentVersion: 1,
        SecretsByVersion: map[uint8][]byte{
            1: secret,
        },
    })
    if err != nil {
        panic(err)
    }

    // 派生：内部 ID → 外部 Key
    channelID := []byte("channel_12345")
    webhookKey, _ := c.Derive(channelID, "webhook")
    sseKey, _ := c.Derive(channelID, "sse")

    fmt.Println(webhookKey) // AXnjdNQal5XDP66STw0pQbOzRi3AdGmiX1Xi5ZxO

    // 恢复：外部 Key → 内部 ID
    recovered, _ := c.Parse(webhookKey, "webhook")
    fmt.Println(string(recovered)) // channel_12345
}

核心概念

概念	说明
资源 ID（C）	内部资源标识，如 channel_id、user_id
用途（P）	用途标识，如 webhook、sse、api，仅允许 [a-z0-9_-]，长度 1~64
派生密钥（K）	外部标识，base64url 编码，含版本号和认证标签
主密钥（S）	平台主密钥，推荐 256-bit CSPRNG 字节串

§02协议流程

派生与恢复

整个协议只有三步运算，不依赖任何外部状态。

派生

K = base64url(version_byte || AES-SIV-Encrypt(PurposeKey, C, AAD=P))

恢复

C = AES-SIV-Decrypt(PurposeKey, base64url-decode(K), AAD=P)

密钥

PurposeKey = HKDF(S, salt="", info=P)

C内部资源 ID

P用途标识（AAD）

K对外暴露的派生密钥

S平台主密钥

PurposeKey按用途派生出的子密钥

算法

组件	算法	标准
密钥派生	HKDF (SHA-256)	RFC 5869
确定性 AEAD	AES-256-SIV	RFC 5297
编码	base64url（无 padding）	RFC 4648 §5

测试向量

3 组固定向量用于跨语言验证，见 internal/core_test.go 中的 TestKnownVectors。

#	Secret	Purpose	Ver	ResourceID	K
1	0001...1e1f	webhook	1	channel_12345	AXnjdNQal5XDP66STw0pQbOzRi3AdGmiX1Xi5ZxO
2	0001...1e1f	sse	1	user_67890	Aez5p0zdhSjxmsgy92MfMhiMlhAbRxlldWcl
3	ffee...1100	api_token	2	channel_12345	ApUFLCCTYol1B57b459DrXW8SiQaJLaJRUx246YY

§03API

接口参考

ckd.go

func New(cfg Config) (CKD, error)

type CKD interface {
    Derive(resourceID []byte, purpose string) (string, error)
    Parse(derivedKey string, purpose string) ([]byte, error)
}

Config 字段	类型	说明
CurrentVersion	uint8	当前版本号 [1, 15]
SecretsByVersion	map[uint8][]byte	各版本密钥，需包含 CurrentVersion

错误处理

errors

if errors.Is(err, ckd.ErrInvalidPurpose) {
    // 用途标识格式不合法
}
if errors.Is(err, ckd.ErrInvalidDerivedKey) {
    // 派生密钥解析失败（格式错误、认证失败、版本不存在等）
}

Parse 对认证失败、格式错误、版本不存在等情况统一返回 ErrInvalidDerivedKey，不泄露失败原因。

§04运维

密钥轮换与用途隔离

密钥轮换

main.go

c, _ := ckd.New(ckd.Config{
    CurrentVersion: 2,
    SecretsByVersion: map[uint8][]byte{
        1: oldSecret, // 解析旧 Key
        2: newSecret, // 派生新 Key
    },
})

newKey, _ := c.Derive(channelID, "webhook")
oldID, _ := c.Parse(oldKey, "webhook")

用途隔离

main.go

k1, _ := c.Derive(id, "webhook")
k2, _ := c.Derive(id, "sse")

// k1 ≠ k2
// Parse(k1, "sse")     → 错误
// Parse(k2, "webhook")  → 错误

§05安全

安全特性

用途隔离不同 purpose 使用独立的密钥空间和认证上下文
不可伪造AEAD 认证加密防止篡改
密钥保护给定 K 无法反推主密钥 S
常数时间认证失败统一返回，不泄露失败原因
确定性相同输入始终产出相同输出

已知限制

不支持单点撤销，需要上层维护黑名单
不隐藏资源 ID 长度，AES-SIV 为长度保持型加密
等价性可观察，相同 C 产生的 K 可被关联
协议层只对最终传入的 C 负责，版本派生、撤销、熵扩展等需求下放给上层处理

一个内部 ID，派生出互不相通的外部密钥。

用计算代替查表

核心目标

数学表现

查库 vs CKD

安装与使用

核心概念

派生与恢复

算法

测试向量

接口参考

错误处理

密钥轮换与用途隔离

密钥轮换

用途隔离

安全特性

已知限制

一个内部 ID，
派生出互不相通的
外部密钥。