sts

Documentation

Index

• type AWSConfig
• type AWSProvider
  • func NewAWSProvider(cfg AWSConfig) *AWSProvider
  • func (p *AWSProvider) IssueCredential(ctx context.Context, keyPrefix string) (*types.STSCredential, error)
• type AliyunConfig
• type AliyunProvider
  • func NewAliyunProvider(cfg AliyunConfig) *AliyunProvider
  • func (p *AliyunProvider) IssueCredential(ctx context.Context, keyPrefix string) (*types.STSCredential, error)
  • func (p *AliyunProvider) VerifyCallback(req *http.Request) (*types.DirectUploadResult, error)
• type HuaweiConfig
• type HuaweiProvider
  • func NewHuaweiProvider(cfg HuaweiConfig) *HuaweiProvider
  • func (p *HuaweiProvider) IssueCredential(ctx context.Context, keyPrefix string) (*types.STSCredential, error)
  • func (p *HuaweiProvider) VerifyCallback(req *http.Request) (*types.DirectUploadResult, error)
• type TencentConfig
• type TencentProvider
  • func NewTencentProvider(cfg TencentConfig) *TencentProvider
  • func (p *TencentProvider) IssueCredential(ctx context.Context, keyPrefix string) (*types.STSCredential, error)
  • func (p *TencentProvider) VerifyCallback(req *http.Request) (*types.DirectUploadResult, error)

Types

type AWSConfig

type AWSConfig struct {
	AccessKeyID     string
	SecretAccessKey string

	// IAM 角色 ARN
	RoleArn         string
	RoleSessionName string

	// 临时凭证有效期（秒），范围 900-3600，默认 3600
	DurationSeconds int

	STSEndpoint string
	S3Endpoint  string
	Bucket      string
	Region      string
}

AWSConfig AWS STS 配置。

type AWSProvider

type AWSProvider struct {
	// contains filtered or unexported fields
}

AWSProvider AWS STS 实现。 使用 AWS SigV4 签名调用 AssumeRole API，不引入 AWS SDK。

func NewAWSProvider

func NewAWSProvider(cfg AWSConfig) *AWSProvider

NewAWSProvider 创建 AWS STS Provider。

func (*AWSProvider) IssueCredential

func (p *AWSProvider) IssueCredential(ctx context.Context, keyPrefix string) (*types.STSCredential, error)

IssueCredential 调用 AWS STS AssumeRole API 签发临时凭证。

type AliyunConfig

type AliyunConfig struct {
	// 用于调用 STS AssumeRole 的 AccessKey（需要有 sts:AssumeRole 权限）
	AccessKeyID     string
	AccessKeySecret string

	// RAM 角色 ARN，如 "acs:ram::123456789:role/oss-upload-role"
	RoleArn string

	// 角色会话名称，用于审计追踪
	RoleSessionName string

	// 临时凭证有效期（秒），范围 900-3600，默认 3600
	DurationSeconds int

	// STS 服务 Endpoint，默认 "sts.aliyuncs.com"
	STSEndpoint string

	// OSS 公网 Endpoint（返回给前端使用），如 "oss-cn-hangzhou.aliyuncs.com"
	OSSEndpoint string

	// OSS Bucket 名称
	Bucket string

	// 区域
	Region string
}

AliyunConfig 阿里云 STS 配置。

type AliyunProvider

type AliyunProvider struct {
	// contains filtered or unexported fields
}

AliyunProvider 阿里云 STS 实现。 使用 HTTP REST API + V1 签名，不引入阿里云 SDK。

func NewAliyunProvider

func NewAliyunProvider(cfg AliyunConfig) *AliyunProvider

NewAliyunProvider 创建阿里云 STS Provider。

func (*AliyunProvider) IssueCredential

func (p *AliyunProvider) IssueCredential(ctx context.Context, keyPrefix string) (*types.STSCredential, error)

IssueCredential 调用阿里云 STS AssumeRole API 签发临时凭证。

func (*AliyunProvider) VerifyCallback

func (p *AliyunProvider) VerifyCallback(req *http.Request) (*types.DirectUploadResult, error)

VerifyCallback 验证阿里云 OSS PutObject 回调签名。

算法（来源：阿里云 OSS 官方回调验签文档）：

1. 从请求头 x-oss-pub-key-url 取 base64 URL-safe 编码的公钥 URL
2. 校验公钥 URL 必须以白名单前缀开头（gosspublic.alicdn.com / gosspub.alicdn.com）
3. 拉取公钥（带缓存）
4. 构造待签字符串： - URL.RawQuery == ""：URL.Path + "\n" + body - URL.RawQuery != ""：URL.Path + "?" + URL.RawQuery + "\n" + body URL.Path 必须先 URL-decode
5. 对待签字符串先做 MD5，再用 RSA 公钥（PKCS1v15 + MD5）验签 Authorization 头

验签通过后，回调 body 应为 JSON：

{"bucket":"...","object":"...","size":123,"etag":"\"...\""}

业务方在 OSS 控制台配置回调时需把 callbackBody 模板写为以上格式。

type HuaweiConfig

type HuaweiConfig struct {
	AccessKeyID     string
	SecretAccessKey string

	// IAM Endpoint，默认 "iam.myhuaweicloud.com"
	IAMEndpoint string

	// 委托方的 Domain ID
	DomainID string

	// 委托名称
	AgencyName string

	// 临时凭证有效期（秒），范围 900-86400，默认 3600
	DurationSeconds int

	// OBS 公网 Endpoint，如 "obs.cn-north-4.myhuaweicloud.com"
	OBSEndpoint string

	Bucket string
	Region string
}

HuaweiConfig 华为云 OBS STS 配置。

type HuaweiProvider

type HuaweiProvider struct {
	// contains filtered or unexported fields
}

HuaweiProvider 华为云 OBS STS 实现。

func NewHuaweiProvider

func NewHuaweiProvider(cfg HuaweiConfig) *HuaweiProvider

NewHuaweiProvider 创建华为云 STS Provider。

func (*HuaweiProvider) IssueCredential

func (p *HuaweiProvider) IssueCredential(ctx context.Context, keyPrefix string) (*types.STSCredential, error)

IssueCredential 调用华为云 IAM API 签发临时凭证。

func (*HuaweiProvider) VerifyCallback

func (p *HuaweiProvider) VerifyCallback(req *http.Request) (*types.DirectUploadResult, error)

VerifyCallback 验证华为云 OBS PostObject 回调签名。

算法（HMAC-SHA256，密钥使用账号 SecretAccessKey）：

待签字符串 = URL.Path（URL-decode）+ "?" + URL.RawQuery + "\n" + body
（RawQuery 为空时省略 "?...". 形式与 OSS 一致）
expected = base64.StdEncoding(HMAC-SHA256(SecretAccessKey, stringToSign))
expected ?= 请求头 obs-callback-signature

比较使用 hmac.Equal 防时序攻击。验签通过后解析 body JSON 提取 bucket / key / size / etag。

注意：OBS 仅 PostObject（浏览器表单上传）支持服务端回调，PutObject 不支持。

type TencentConfig

type TencentConfig struct {
	SecretId  string
	SecretKey string

	// 临时凭证有效期（秒），范围 900-7200，默认 3600
	DurationSeconds int

	// COS 公网 Endpoint，如 "cos.ap-guangzhou.myqcloud.com"
	COSEndpoint string

	// Bucket 名称（含 AppId），如 "mybucket-1250000000"
	Bucket string

	// 区域
	Region string

	// AppId
	AppId string

	// CallbackToken 回调请求的共享密钥。
	// 配置后启用 VerifyCallback；客户端在 OSS / COS 控制台配置回调时把 token
	// 透传到回调 body 模板的 "callback_token" 字段（或通过 X-Callback-Token 头），
	// 服务端用 constant-time 比较防时序攻击。
	//
	// 腾讯云 COS 不像阿里云 OSS 提供 RSA 签名链路，官方推荐做法是 Token 比对 +
	// HTTPS。生产环境建议同时启用 CallbackAllowedIPs 做 IP 白名单。
	CallbackToken string

	// CallbackAllowedIPs 限制只接受来自这些 IP / CIDR 的回调请求。
	// 留空表示不做 IP 校验。仅校验 RemoteAddr 的直接对端，不解析 X-Forwarded-For；
	// 如需信任反向代理头，由业务方在中间件中将真实 IP 写入 RemoteAddr 后再调用。
	CallbackAllowedIPs []string
}

TencentConfig 腾讯云 STS 配置。

type TencentProvider

type TencentProvider struct {
	// contains filtered or unexported fields
}

TencentProvider 腾讯云 STS 实现。

func NewTencentProvider

func NewTencentProvider(cfg TencentConfig) *TencentProvider

NewTencentProvider 创建腾讯云 STS Provider。

func (*TencentProvider) IssueCredential

func (p *TencentProvider) IssueCredential(ctx context.Context, keyPrefix string) (*types.STSCredential, error)

IssueCredential 调用腾讯云 GetFederationToken API 签发临时凭证。

func (*TencentProvider) VerifyCallback

func (p *TencentProvider) VerifyCallback(req *http.Request) (*types.DirectUploadResult, error)

VerifyCallback 验证腾讯云 COS 回调请求。

腾讯云 COS 不像阿里云 OSS 提供 RSA 签名链路，官方推荐做法是：

• HTTPS（强制）
• Token 比对（业务在控制台配置回调时把 token 透传到 body 或 header）
• IP 白名单（可选）

本实现按以下顺序校验：

1. 若配置了 CallbackAllowedIPs，校验对端 IP（req.RemoteAddr 直接对端，不解析 XFF）
2. 必须配置 CallbackToken（否则视作未启用回调验签，直接拒绝）
3. 优先从 X-Callback-Token 头读取 token，缺失时 fallback 到 body 的 callback_token 字段
4. constant-time 比较 token，等长且全等才视作合法
5. 解析 body 的 bucket / object|key / size / etag 返回

CallbackToken 必须由业务方使用足够熵的随机字符串（≥ 32 字节）。