zctoken

README

zctoken相关工具包

BuildTokenWithECC / CheckTokenWithECC

使用椭圆曲线签名算法构建/校验凭证，支持以下算法:

• SM2-SM3 : 国密算法，使用SM2签名，使用SM3散列
• ECDSA-SHA256 : 使用ecdsa签名，使用SHA256散列
• ED25519-SHA256 : 使用ed25519签名，使用SHA256散列

BuildTokenWithGM / CheckTokenWithGM

使用gitee.com/zhaochuninhefei/gmgo的SM2与SM3算法实现国密token的创建与校验。

与使用BuildTokenWithECC/CheckTokenWithECC时采用SM2-SM3算法相同，只是入参出参不同。

BuildTokenWithHMAC / CheckTokenWithHMAC

使用HMAC算法构建/校验凭证，支持以下算法:

• HMAC-SM3 : 采用国密散列算法SM3的HMAC认证码算法
• HMAC-SHA256 : 采用散列算法SHA256的HMAC认证码算法

性能测试结果

毫无疑问，采用HMAC算法的凭证构造与校验函数在性能上是有很大优势的。

但采用椭圆曲线签名算法来构造和校验凭证的话，在密码学安全性上更有优势。

以下是性能测试结果:

GOROOT=/usr/golang/go_1.17.5 #gosetup
GOPATH=/home/zhaochun/work/sources/go_path #gosetup
/usr/golang/go_1.17.5/bin/go test -c -o /tmp/GoLand/___gobench_gitee_com_zhaochuninhefei_zcutils_go_zctoken.test gitee.com/zhaochuninhefei/zcutils-go/zctoken #gosetup
/tmp/GoLand/___gobench_gitee_com_zhaochuninhefei_zcutils_go_zctoken.test -test.v -test.paniconexit0 -test.bench . -test.run ^$
goos: linux
goarch: amd64
pkg: gitee.com/zhaochuninhefei/zcutils-go/zctoken
cpu: 12th Gen Intel(R) Core(TM) i7-12700H
BenchmarkBuildTokenWithSM2SM3
BenchmarkBuildTokenWithSM2SM3-20        	   32943	     37864 ns/op	    7111 B/op	     142 allocs/op
BenchmarkBuildTokenWithECDSA
BenchmarkBuildTokenWithECDSA-20         	   37602	     32474 ns/op	    6257 B/op	     122 allocs/op
BenchmarkBuildTokenWithED25519
BenchmarkBuildTokenWithED25519-20       	   41622	     29124 ns/op	    2473 B/op	      58 allocs/op
BenchmarkBuildTokenWithHMACSM3
BenchmarkBuildTokenWithHMACSM3-20       	  546943	      2132 ns/op	    1793 B/op	      30 allocs/op
BenchmarkBuildTokenWithHMACSHA256
BenchmarkBuildTokenWithHMACSHA256-20    	  586698	      1913 ns/op	    1825 B/op	      28 allocs/op
BenchmarkCheckTokenWithSM2SM3
BenchmarkCheckTokenWithSM2SM3-20        	   20446	     58128 ns/op	    4620 B/op	     101 allocs/op
BenchmarkCheckTokenWithECDSA
BenchmarkCheckTokenWithECDSA-20         	   21111	     57371 ns/op	    4500 B/op	      91 allocs/op
BenchmarkCheckTokenWithED25519
BenchmarkCheckTokenWithED25519-20       	   32475	     36449 ns/op	    2264 B/op	      58 allocs/op
BenchmarkCheckTokenWithHMACSM3
BenchmarkCheckTokenWithHMACSM3-20       	  407744	      3128 ns/op	    1992 B/op	      38 allocs/op
BenchmarkCheckTokenWithHMACSHA256
BenchmarkCheckTokenWithHMACSHA256-20    	  404240	      3069 ns/op	    2008 B/op	      36 allocs/op
PASS

Process finished with the exit code 0

Documentation

Overview

Package zctoken 凭证处理包

Index

• Constants
• func BuildTokenWithECC(token *Token, exp time.Time, priKeyPem []byte) (string, error)
• func BuildTokenWithGM(payloads map[string]string, exp time.Time, priKey *sm2.PrivateKey) (string, error)
• func BuildTokenWithHMAC(token *Token, exp time.Time, keyBytes []byte) (string, error)
• func CheckTokenWithGM(token string, pubKey *sm2.PublicKey) (map[string]string, error)
• func CreateSplPayloads(aud string, expSeconds uint64) map[string]string
• func CreateStdPayloads(iss string, sub string, aud string, jti string, expSeconds uint64) map[string]string
• type Alg
  • func (a *Alg) IsECC() bool
  • func (a *Alg) IsHMAC() bool
• type Token
  • func CheckTokenWithECC(tokenStr string, pubKeyPem []byte) (*Token, error)
  • func CheckTokenWithHMAC(tokenStr string, keyBytes []byte) (*Token, error)
  • func PrepareSplTokenStruct(aud string, expSeconds uint64, alg Alg) (*Token, error)
  • func PrepareStdTokenStruct(iss string, sub string, aud string, jti string, expSeconds uint64, alg Alg) (*Token, error)
• type TokenHeader
  • func CreateTokenHeader(alg Alg, typ string) *TokenHeader
  • func CreateTokenHeaderGM() *TokenHeader

Constants

const (
	ALG_SM2_SM3        Alg = "SM2-SM3"
	ALG_ECDSA_SHA256   Alg = "ECDSA-SHA256"
	ALG_ED25519_SHA256 Alg = "ED25519-SHA256"
	ALG_HMAC_SM3       Alg = "HMAC-SM3"
	ALG_HMAC_SHA256    Alg = "HMAC-SHA256"

	// ALG_DEFAULT 默认凭证算法
	ALG_DEFAULT = ALG_HMAC_SM3
	// TYP_DEFAULT 默认凭证类型
	TYP_DEFAULT = "JWT"

	// HMAC_KEY_DEFAULT_HEX HMAC默认密钥，长度64的字节数组转为hex字符串，使用`zcrandom.GenerateRandomBytes`生成。
	HMAC_KEY_DEFAULT_HEX = "" /* 128-byte string literal not displayed */
)

zctoken支持的凭证算法列表、默认算法以及默认凭证类型(目前只有JWT)

Functions

func BuildTokenWithECC

func BuildTokenWithECC(token *Token, exp time.Time, priKeyPem []byte) (string, error)

BuildTokenWithECC 使用椭圆曲线签名算法构建凭证

@param token 凭证结构体
@param exp 凭证过期时间，如果不打算重置token.Payloads中的过期时间，则这里传入time零值(`time.Time{}`)即可。
@param priKeyPem 私钥pem
@return error

func BuildTokenWithGM

func BuildTokenWithGM(payloads map[string]string, exp time.Time, priKey *sm2.PrivateKey) (string, error)

BuildTokenWithGM 使用SM2-SM3算法构建凭证

@param payloads 凭证有效负载
@param exp 凭证过期时间，如果不打算重置payloads中的过期时间，则这里传入time零值(`time.Time{}`)即可。
@param priKey 签名私钥(sm2)
@return string 凭证字符串
@return error

func BuildTokenWithHMAC

func BuildTokenWithHMAC(token *Token, exp time.Time, keyBytes []byte) (string, error)

BuildTokenWithHMAC 使用HMAC算法构建凭证

@param token 凭证结构体
@param exp 凭证过期时间，如果不打算重置payloads中的过期时间，则这里传入time零值(`time.Time{}`)即可。
@param keyBytes HMAC密钥
@return error

func CheckTokenWithGM

func CheckTokenWithGM(token string, pubKey *sm2.PublicKey) (map[string]string, error)

CheckTokenWithGM 使用SM2-SM3算法校验凭证

@param token 凭证字符串
@param pubKey 验签公钥(sm2)
@return map[string]string 凭证有效负载
@return error

func CreateSplPayloads

func CreateSplPayloads(aud string, expSeconds uint64) map[string]string

CreateSplPayloads 创建简易凭证有效负载

@param aud 受众
@param expSeconds
@return map[string]string

func CreateStdPayloads

func CreateStdPayloads(iss string, sub string, aud string, jti string, expSeconds uint64) map[string]string

CreateStdPayloads 创建标准凭证有效负载

其中，过期时间使用 `当前时间 + expSeconds过期时间秒数` ，生效时间与签发时间均采用当前时间

@param iss 签发者
@param sub 主题
@param aud 受众
@param jti 编号
@param expSeconds 过期时间秒数
@return map[string]string 凭证有效负载

Types

type Alg

type Alg string

Alg 凭证算法类型，目前支持:"SM2-SM3","ECDSA-SHA256","ED25519-SHA256","HMAC-SM3","HMAC-SHA256"。

• "SM2-SM3","ECDSA-SHA256","ED25519-SHA256"，使用椭圆曲线签名算法生成token，算法前半部是签名算法，后半部是散列算法(用于签名前计算凭证内容摘要)。
• "HMAC-SM3","HMAC-SHA256"，表示为凭证生成HMAC而不是签名，算法后半部是HMAC对应的散列算法。

func (*Alg) IsECC

func (a *Alg) IsECC() bool

IsECC 凭证算法是否是椭圆曲线算法

@receiver a
@return bool

func (*Alg) IsHMAC

func (a *Alg) IsHMAC() bool

IsHMAC 凭证算法是否是HMAC算法

@receiver a
@return bool

type Token

type Token struct {
	// Header 凭证头
	Header TokenHeader `json:"header"`
	// Payloads 凭证有效负载
	Payloads map[string]string `json:"payloads"`
	// TokenStr 凭证字符串
	TokenStr string `json:"token_str"`
}

Token 凭证结构体

func CheckTokenWithECC

func CheckTokenWithECC(tokenStr string, pubKeyPem []byte) (*Token, error)

CheckTokenWithECC 使用椭圆曲线签名算法校验凭证

@param tokenStr 凭证字符串
@param pubKeyPem 验签公钥pem
@return *Token 凭证结构体(指针)
@return error

func CheckTokenWithHMAC

func CheckTokenWithHMAC(tokenStr string, keyBytes []byte) (*Token, error)

CheckTokenWithHMAC 使用HMAC算法校验凭证

@param tokenStr 凭证字符串
@param keyBytes HMAC密钥
@return *Token 凭证结构体(指针)
@return error

func PrepareSplTokenStruct

func PrepareSplTokenStruct(aud string, expSeconds uint64, alg Alg) (*Token, error)

PrepareSplTokenStruct 准备简易凭证结构体

@param aud 受众
@param expSeconds 过期时间秒数
@param alg 凭证算法
@return *Token 凭证结构体(指针)
@return error

func PrepareStdTokenStruct

func PrepareStdTokenStruct(
	iss string,
	sub string,
	aud string,
	jti string,
	expSeconds uint64,
	alg Alg) (*Token, error)

PrepareStdTokenStruct 准备标准凭证结构体

@param iss 签发者
@param sub 主题
@param aud 受众
@param jti 编号
@param expSeconds 过期时间秒数
@param alg 凭证算法
@return *Token 凭证结构体(指针)
@return error

type TokenHeader

type TokenHeader struct {
	// Alg 凭证算法
	Alg Alg `json:"alg"`
	// Typ 凭证类型
	Typ string `json:"typ"`
}

TokenHeader 凭证头部

func CreateTokenHeader

func CreateTokenHeader(alg Alg, typ string) *TokenHeader

CreateTokenHeader 创建凭证头部

@param alg 凭证算法
@param typ 凭证类型
@return *TokenHeader

func CreateTokenHeaderGM

func CreateTokenHeaderGM() *TokenHeader

CreateTokenHeaderGM 使用SM2-SM3配置创建凭证头部

@return *TokenHeader