xgcl/README.md

Summary

xdx (Golang) Crypto Library

Author: xdx

Package gcl is the xdx (Golang) Crypto Library of GOLANG(Go语言版的密码函数库)

包说明：

• identifier (GM/T 0006 密码标识常量定义)
• rsa - pkcs #1 v1.5 签名、SDF_XX_RSA接口实现 - Wrapping of crypto/rsa
• sm/sm1
• sm/sm2
• sm/sm3
• sm/sm4 包括CTR and GCM模式, sm4_mac
• pbkd P5，口令派生密钥规范
• grand 随机数
  • drgb(确定性随机数发生器，软件实现的伪随机数生成器，密标草案稿，包括sm3_rng和sm4_ctr两个发生器)
  • statistics - deprecated, use xdx.jelly/rts instead。
• MAC - 包括cbcmac, hmac_sm3 - hmac建议直接用hmac.New
• utils
  • p7 padding (p5 padding is a special case of p7,utils/padding)
• tpc - SM2和SM9的协同签名(for HooFoo)
• x 新功能开发, 开发完成会放到gcl包下(不保证接口不变)
  • 合并签名(x/seal/concentration)

HOWTO

• gcl文件夹需放在GOPATH/xdx.jelly/文件夹下
• 需要golang.org/x/sys包

Endian

SM2和SM9可以设置按0018中序列化时，ULONG转换的大小端序。比如10进制数256:

• 大端：256 => 00 00 01 00
• 小端：256 => 00 01 00 00

默认是大端序。若要指定端序，使用下面的函数（只需执行一次）

// 设置SM2，SM9转换端序
sm.SetToBigEndian()
sm.SetToLittleEndian()

// 设置SM2转换端序
sm2.SetToBigEndian()
sm2.SetToLittleEndian()

// 设置SM9转换端序
sm9.SetToBigEndian()
sm9.SetToLittleEndian()

注：反序列化Unmarshal的时候，默认忽略输入的bits的大小端序，不做严格检查。

函数调用约定

若返回错误，则保证输入不变，输出无意义。

out, err = fn(param)

若err != nil, 则param不变，out可能为nil，空Slice，零值或其他无意义数据。

如果函数调用可能发生错误，则下面这样调用发生错误时原输入值会丢失。

a, err = fn(a)

输入随机数

函数需要输入随机数的地方均可用nil代替，则函数内部使用grand的随机数发生器。

避免堆上分配空间

SM4的加解密，可以提前栈上分配好内存空间，传入函数调用。 例如

func EncryptECB(dst, key, src []byte) ([]byte, error)

dst和src要么完全重叠，要么不重叠

dst可以有三种情况

• nil, 内部分配空间,必须接收函数返回
• len(dst) >= len(src), 结果写入dst[:len(src)]并返回
• len(dst) < len(src), 分两种情况：
  • cap(dst) >= len(src), 则不会发生内存重分配, 返回dst[:len(src)]
  • cap(dst) < len(src), 内存重分配, 返回dst[:len(src)], 注意这时输入的dst和返回值是指向不同的内存地址。

应尽量避免内存重分配。涉及内存分配和拷贝

示例

data := [128]byte // set enough length on stack
src := data[:64]


// first case
dst, err := EncryptECB(nil, key, src) // dst is allocate in EncryptECB
if (err != nil){
    // error handle
}

// second case
// 原地加密，src中现在存的是密文。
_, err := EncryptECB(src, key, src)
if (err != nil){
    // error handle
    // 若出错，src中内容不变，为明文
}

dst := data[96:]
dst, err = EncryptECB(dst, key, src) // len(dst)不够，且cap(dst) < len(src), 重分配内存。
if (err != nil){
    // error handle
}

最后，如果还是不知道dst应该输入什么，那就输入nil

• 输入参数应该尽量保证不变（除说明外）。但有几个例外:

func CBCEncrypt(dst, iv, key, src []byte) ([]byte, error)

CBC模式会改变iv的值，作为下一次调用的输入。

• SM4的相关加解密函数如果确保输入数据长度都是正确的，那么可以不检查返回error
• SM4可以使用与go标准库一样的步骤。进行其他modes的加解密。

block, err := NewCipher(key)
decrypter := cipher.NewCBCDecrypter(block, iv)
decrypter.CryptBlocks(out, in)

Marshal & Unmarshal

• gcl/util/encoding/{UtilMarshaler,UtilUnmarshaler}接口实现gmt0018的数据格式和类型的序列化。（增加输入缓存区和返回销毁字节数）
• x.MarshalBinary/x.UnmarshalBinary-弃用，使用上一条代替。
• x.MarshalSDF/x.UnmarshalSDF实现和SDF数据结构的相互转换。
• x.MarshalASN1/x.UnmarshalANS1 (TODO), 实现SM{2,9}算法使用规范的ANS.1编解码转换。

Benchmark

SM2 on amd64

• sign: 40000
• Verify: 13500

SM3 on amd64

• AVX2: ~400MBps

SM4 on amd64

• ECB: 250MBps(SM4-AESNI)
• GCM: (TODO: use SM4-AESNI and PCLMULQDQ)

SM9 on amd64

• sign: 1500

RoadMap

• 按sm2/sm9使用规范的ASN.1序列化和反序列化。