Documentation
¶
Index ¶
- func BuildRequestObject(path string, requestObj interface{}, secret string, encrypted ...bool) ([]byte, error)
- type SDK
- func (s *SDK) AuthObject(object func() (interface{}, error))
- func (s *SDK) AuthToken(object wire.AuthToken)
- func (s *SDK) GetAuth() wire.AuthToken
- func (s *SDK) GetPublicKey() (*crypto.MLKEM1024Object, *wire.PublicKey, crypto.Cipher, error)
- func (s *SDK) PostByPlan01(path string, requestObj, responseObj interface{}, encrypted bool) error
- func (s *SDK) PostByPlan2(path string, requestObj, responseObj interface{}) error
- func (s *SDK) ResetAuth() error
- func (s *SDK) SetClientNo(usr int64)
- func (s *SDK) SetLanguage(language string)
- func (s *SDK) SetMLDSA87Object(usr int64, prkB64, peerPubB64 string) error
- func (s *SDK) SetTimeout(timeout int64)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BuildRequestObject ¶
func BuildRequestObject(path string, requestObj interface{}, secret string, encrypted ...bool) ([]byte, error)
BuildRequestObject 构建标准的API请求数据 用于生成符合FreeGo协议的请求JSON数据
协议格式:
{
"d": "数据(Base64或AES加密)",
"t": 时间戳,
"n": Nonce随机数,
"p": Plan模式(0=Base64, 1=AES),
"s": HMAC-SHA256签名
}
构建流程: 1. JSON序列化请求对象 2. 根据encrypted参数选择编码方式 3. 生成时间戳和Nonce 4. 计算HMAC-SHA256签名 5. 构建完整的请求JSON
参数:
- path: API路径，用于签名计算
- requestObj: 请求数据对象，会被JSON序列化
- secret: HMAC签名密钥
- encrypted: 可选参数，是否使用AES加密 (默认false)
返回值:
- []byte: 构建好的请求JSON字节数组
- error: 构建失败时的错误信息
兼容性: - 这是早期版本的构建函数 - 新代码推荐使用PostByPlan01或PostByPlan2方法 - 主要用于向后兼容和简单场景
注意: - 不支持 ML-DSA 外层签名（仅 Plan2 路径使用） - 使用固定的AES-CBC加密 (非GCM模式) - HMAC签名算法略有不同
Types ¶
type SDK ¶
type SDK struct {
Domain string // API域名 (如: https://api.example.com)
AuthDomain string // 认证域名 (可选，用于/key和/login接口)
KeyPath string // 公钥获取路径 (默认: /key)
LoginPath string // 登录路径 (默认: /login)
ClientNo int64 // 客户端编号
// contains filtered or unexported fields
}
HttpSDK FreeGo HTTP客户端SDK Plan0/1：JWT + HMAC（可选 AES-GCM）；Plan2：ML-KEM + ML-DSA + AES-GCM
使用模式: - PostByPlan2: Plan2 匿名访问（ML-KEM + ML-DSA，须 SetMLDSA87Object） - PostByPlan01: Plan0/1 登录后访问（JWT + HMAC，无外层 Valid）
func New ¶
func New() *SDK
NewHttpSDK 创建新的HttpSDK实例并设置默认值 提供便捷的构造函数，避免手动初始化所有字段
默认值: - KeyPath: "/key" - LoginPath: "/login" - timeout: 120秒 - language: "zh-CN"
返回值:
- *SDK: 初始化的HttpSDK实例
使用示例:
sdk := NewHttpSDK() sdk.Domain = "https://api.example.com" sdk.ClientNo = 12345
func (*SDK) AuthObject ¶
AuthObject 设置登录认证对象 用于存储用户名、密码等登录凭据 自动登录时会使用此对象调用登录接口
参数:
- object: 认证对象，包含用户名密码等信息
注意: 请使用指针对象以避免数据拷贝
func (*SDK) AuthToken ¶
AuthToken 设置JWT认证令牌 设置登录成功后获得的令牌，用于后续API调用的身份认证
参数:
- object: AuthToken结构体，包含token、secret、expired字段
安全特性: - Token: JWT令牌，用于身份验证 - Secret: 动态生成的AES密钥，用于数据加密 - Expired: 令牌过期时间
注意: 此方法会覆盖之前设置的令牌
func (*SDK) GetPublicKey ¶
GetPublicKey 获取服务端 ML-KEM 封装公钥并执行客户端封装（Plan2 /key）。
func (*SDK) PostByPlan01 ¶
PostByPlan01 通过 JWT 认证发送 POST 请求（Plan0/1，无外层 Valid 签名） 适用于登录后的业务 API 调用，使用令牌进行身份认证
安全协议栈: 1. TLS 1.2+ (网络层加密) 2. JWT令牌认证 (身份验证) 3. AES-GCM或Base64 (数据加密，可选) 4. HMAC-SHA256 (数据完整性)
执行流程: 1. 检查认证状态，自动登录 (如果需要) 2. 获取认证令牌 (Token + Secret) 3. 根据encrypted参数选择加密方式 4. 生成HMAC-SHA256签名 5. 发送HTTP请求 (Authorization头) 6. 验证响应HMAC签名 7. 解密响应数据
参数:
- path: API路径，如"/user/info"
- requestObj: 请求数据对象
- responseObj: 响应数据对象指针
- encrypted: 是否使用AES-GCM加密 (true=Plan1, false=Plan0)
返回值:
- error: 请求失败时的错误信息
安全特性: - JWT令牌认证: 身份验证和授权 - 动态Secret: 每次登录生成新的AES密钥 - 可选加密: 支持明文(Base64)和加密传输 - 外层 Valid 签名仅 Plan2（PostByPlan2）使用 ML-DSA
使用场景: - 用户登录后的业务API调用 - 需要身份认证的接口 - 中等安全要求的场景
性能特点: - 比 PostByPlan2（Plan2 / ML-KEM 协商）更快：复用令牌，无每请求协商 - 支持高并发 (令牌复用) - 适合高频API调用
注意: - 需要预先登录或设置有效的authToken - 会自动处理令牌过期和续期
func (*SDK) PostByPlan2 ¶
PostByPlan2 通过 ML-KEM + HKDF + AES-GCM + ML-DSA 发送 POST（Plan2，匿名场景）
安全协议栈 (从下到上): 1. TLS 1.2+（传输层，由部署保证） 2. ML-KEM 共享秘密 + HKDF → 会话密钥，再 AES-256-GCM 3. HMAC-SHA256 完整性 4. 双向 ML-DSA
执行流程: 1. GetPublicKey：服务端 ML-KEM 封装公钥 + 客户端封装 2. ML-KEM 得到共享字节 3. HKDF 派生对称密钥 4. AES-GCM 加密请求体 5. HMAC-SHA256 6. ML-DSA 签名 7. 发送请求 8. 校验响应 HMAC / ML-DSA 9. AES-GCM 解密响应
参数:
- path: API路径，如"/user/info"
- requestObj: 请求数据对象 (会自动JSON序列化)
- responseObj: 响应数据对象指针 (会自动JSON反序列化)
返回值:
- error: 请求失败时的错误信息
安全特性: - 前向保密性 (PFS): 每次请求使用新密钥 - 完美前向保密: ML-KEM 每次协商独立共享秘密 - 双向认证: 客户端和服务端相互验证身份 - 防重放攻击: 时间戳 + Nonce机制
使用场景: - 金融交易API - 敏感数据传输 - 匿名访问但需要高安全性的接口
注意: - 每次调用都会执行完整的密钥协商流程 - 适合低频但高安全要求的API调用
func (*SDK) SetClientNo ¶
func (*SDK) SetLanguage ¶
SetLanguage 设置HTTP请求语言头 用于服务端国际化支持
参数:
- language: 语言代码，如"zh-CN"、"en-US"等
HTTP头: 设置为"Language: {language}"
func (*SDK) SetMLDSA87Object ¶
SetMLDSA87Object 配置 Plan2 客户端身份：本端 ML-DSA-87 私钥 + 服务端 ML-DSA 公钥（与 HttpNode.AddCipher 镜像）。
func (*SDK) SetTimeout ¶
SetTimeout 设置HTTP请求超时时间 控制单个API请求的最大等待时间
参数:
- timeout: 超时时间(秒)，0表示使用默认120秒
默认值: 120秒 建议值: 根据网络状况设置，如30-300秒
Source Files