crypto

README

简介

crypto 模块提供了一些密码学算法 (包括加密、签名、哈希等) 能力及其相关的协议的接口。

密码学算法

非对称密码学算法接口

定义了如下的非对称体系公私钥接口：

// Signing options
type SignOpts struct {
	Hash HashType
	UID  string
}

// === 秘钥接口 ===
type Key interface {
	// 获取秘钥字节数组
	Bytes() ([]byte, error)

	// 获取秘钥类型
	Type() KeyType

	// 获取编码后秘钥(PEM格式)
	String() (string, error)
}

// === 非对称秘钥签名+验签接口 ===
// 私钥签名接口
type PrivateKey interface {
	Key

	// 私钥签名
	Sign(data []byte) ([]byte, error)

	SignWithOpts(data []byte, opts *SignOpts) ([]byte, error)

	// 返回公钥
	PublicKey() PublicKey

	// 转换为crypto包中的 PrivateKey 接口类
	ToStandardKey() crypto.PrivateKey
}

// 公钥验签接口
type PublicKey interface {
	Key

	// 公钥验签
	Verify(data []byte, sig []byte) (bool, error)

	VerifyWithOpts(data []byte, sig []byte, opts *SignOpts) (bool, error)

	// 转换为crypto包中的 PublicKey 接口类
	ToStandardKey() crypto.PublicKey
}

SignOpts 结构用于为一个签名、验签操作提供灵活的流程变化。其中，Hash 字段可以设置哈希算法，例如 SHA256、SM3 等。UID 字段是 SM2-SM3 签名套件专用字段，用于设置国密局规定的 user ID。

Key 接口定义了密码学公私钥通用的序列化接口，和一个返回密钥算法的 Type() 接口。

PrivateKey 接口用于签名私钥，通常使用的是 SighWithOpts() 接口，其中入参 data 是数据原文，opts是一个 SignOpts 类型的结构，用于指定哈希算法，在 SM2-SM3 签名套件中也用于指定 user ID。在 herbt 中应用时，这个哈希算法可能读取自证书中指定的算法套件，也可能来自配置文件设置。

公私钥的序列化

在应用中，公钥、私钥通常会以字符串形式保存在配置文件中或用于传输。前面提到的 Key 接口中的 String() 为公钥提供了序列化为 PEM 格式字符串的能力。

要把字符串形式的公私钥反序列化为对象，可以调用 crypto/asym 包中的 PublicKeyFromPEM() 或 PrivateKeyFromPEM() 接口。herbt 支持的算法都可以用这两个通用接口反序列化公私钥。

证书

herbt 使用的节点、客户端证书需要满足一下要求：

1. O 字段需要指明节点或客户端所属的组织的名称。
2. OU 字段需要指明节点或客户端的身份，默认身份有四种：admin、client、consensus、common，分别代表管理员、普通用户、共识节点、普通节点。

Documentation

Index

• Constants
• Variables
• type BitsSize
• type DecryptKey
• type EncOpts
• type EncryptKey
• type Encryptor
• type HashType
• type Key
• type KeyType
• type PrivateKey
• type PublicKey
• type SignOpts
• type SymmetricKey

Constants

const (
	// 密码算法默认值，若是此项，将采用配置文件中配置的密码算法
	CRYPTO_ALGO_HASH_DEFAULT = ""
	CRYPTO_ALGO_SYM_DEFAULT  = ""
	CRYPTO_ALGO_ASYM_DEFAULT = ""

	// 哈希算法
	CRYPTO_ALGO_SHA256   = "SHA256"
	CRYPTO_ALGO_SHA3_256 = "SHA3_256"
	CRYPTO_ALGO_SM3      = "SM3"

	// 对称加密
	CRYPTO_ALGO_AES    = "AES"
	CRYPTO_ALGO_AES128 = "AES128"
	CRYPTO_ALGO_AES192 = "AES192"
	CRYPTO_ALGO_AES256 = "AES256"
	CRYPTO_ALGO_SM4    = "SM4"

	// 非对称秘钥
	CRYPTO_ALGO_RSA512        = "RSA512"
	CRYPTO_ALGO_RSA1024       = "RSA1024"
	CRYPTO_ALGO_RSA2048       = "RSA2048"
	CRYPTO_ALGO_RSA3072       = "RSA3072"
	CRYPTO_ALGO_SM2           = "SM2"
	CRYPTO_ALGO_ECC_P256      = "ECC_P256"
	CRYPTO_ALGO_ECC_P384      = "ECC_P384"
	CRYPTO_ALGO_ECC_P521      = "ECC_P521"
	CRYPTO_ALGO_ECC_Ed25519   = "ECC_Ed25519"
	CRYPTO_ALGO_ECC_Secp256k1 = "ECC_Secp256k1"
)

const CRYPTO_DEFAULT_UID = "1234567812345678"

constant UID for SM2-SM3

const (
	SM3 = crypto.Hash(HASH_TYPE_SM3)
)

Variables

var AsymAlgoMap = map[string]KeyType{

	CRYPTO_ALGO_RSA512:        RSA512,
	CRYPTO_ALGO_RSA1024:       RSA1024,
	CRYPTO_ALGO_RSA2048:       RSA2048,
	CRYPTO_ALGO_RSA3072:       RSA3072,
	CRYPTO_ALGO_SM2:           SM2,
	CRYPTO_ALGO_ECC_P256:      ECC_NISTP256,
	CRYPTO_ALGO_ECC_P384:      ECC_NISTP384,
	CRYPTO_ALGO_ECC_P521:      ECC_NISTP521,
	CRYPTO_ALGO_ECC_Ed25519:   ECC_Ed25519,
	CRYPTO_ALGO_ECC_Secp256k1: ECC_Secp256k1,
}

var HashAlgoMap = map[string]HashType{
	CRYPTO_ALGO_SHA256:   HASH_TYPE_SHA256,
	CRYPTO_ALGO_SHA3_256: HASH_TYPE_SHA3_256,
	CRYPTO_ALGO_SM3:      HASH_TYPE_SM3,
}

var KeyType2NameMap = map[KeyType]string{
	AES:           CRYPTO_ALGO_AES,
	SM4:           CRYPTO_ALGO_SM4,
	RSA512:        CRYPTO_ALGO_RSA512,
	RSA1024:       CRYPTO_ALGO_RSA1024,
	RSA2048:       CRYPTO_ALGO_RSA2048,
	RSA3072:       CRYPTO_ALGO_RSA3072,
	SM2:           CRYPTO_ALGO_SM2,
	ECC_Secp256k1: CRYPTO_ALGO_ECC_Secp256k1,
	ECC_NISTP256:  "ECC_NISTP256",
	ECC_NISTP384:  "ECC_NISTP384",
	ECC_NISTP521:  "ECC_NISTP521",
	ECC_Ed25519:   CRYPTO_ALGO_ECC_Ed25519,
}

var Name2KeyTypeMap = map[string]KeyType{
	CRYPTO_ALGO_AES:           AES,
	CRYPTO_ALGO_SM4:           SM4,
	CRYPTO_ALGO_RSA512:        RSA512,
	CRYPTO_ALGO_RSA1024:       RSA1024,
	CRYPTO_ALGO_RSA2048:       RSA2048,
	CRYPTO_ALGO_RSA3072:       RSA3072,
	CRYPTO_ALGO_SM2:           SM2,
	CRYPTO_ALGO_ECC_Secp256k1: ECC_Secp256k1,
	"ECC_NISTP256":            ECC_NISTP256,
	"ECC_NISTP384":            ECC_NISTP384,
	"ECC_NISTP521":            ECC_NISTP521,
	CRYPTO_ALGO_ECC_Ed25519:   ECC_Ed25519,
}

var SymAlgoMap = map[string]KeyType{

	CRYPTO_ALGO_AES:    AES,
	CRYPTO_ALGO_AES128: AES,
	CRYPTO_ALGO_AES192: AES,
	CRYPTO_ALGO_AES256: AES,
	CRYPTO_ALGO_SM4:    SM4,
}

Types

type BitsSize

type BitsSize int

const (
	BITS_SIZE_128  BitsSize = 128
	BITS_SIZE_192  BitsSize = 192
	BITS_SIZE_256  BitsSize = 256
	BITS_SIZE_512  BitsSize = 512
	BITS_SIZE_1024 BitsSize = 1024
	BITS_SIZE_2048 BitsSize = 2048
	BITS_SIZE_3072 BitsSize = 3072
)

type DecryptKey

type DecryptKey interface {
	Key
	Decrypt(ciphertext []byte) ([]byte, error)
	DecryptWithOpts(ciphertext []byte, opts *EncOpts) ([]byte, error)
	EncryptKey() EncryptKey
}

type EncOpts

type EncOpts struct {
	EncodingType string
	BlockMode    string
	EnableMAC    bool
	Hash         HashType
	Label        []byte
	EnableASN1   bool
}

Encryption options

type EncryptKey

type EncryptKey interface {
	Key
	Encrypt(data []byte) ([]byte, error)
	EncryptWithOpts(data []byte, opts *EncOpts) ([]byte, error)
}

type Encryptor

type Encryptor interface {
	Encrypt(data []byte) ([]byte, error)
	Decrypt(ciphertext []byte) ([]byte, error)
}

type HashType

type HashType uint

const (
	HASH_TYPE_SM3      HashType = 20
	HASH_TYPE_SHA256   HashType = HashType(crypto.SHA256)
	HASH_TYPE_SHA3_256 HashType = HashType(crypto.SHA3_256)
)

type Key

type Key interface {
	// 获取秘钥字节数组
	Bytes() ([]byte, error)
	// 获取秘钥类型
	Type() KeyType
	// 获取编码后秘钥(PEM格式)
	String() (string, error)
}

=== 秘钥接口 ===

type KeyType

type KeyType int

秘钥类型

const (
	// 对称秘钥
	AES KeyType = iota
	SM4
	// 非对称秘钥
	RSA512
	RSA1024
	RSA2048
	RSA3072
	SM2
	ECC_Secp256k1
	ECC_NISTP256
	ECC_NISTP384
	ECC_NISTP521
	ECC_Ed25519
)

type PrivateKey

type PrivateKey interface {
	Key
	// 私钥签名
	Sign(data []byte) ([]byte, error)
	SignWithOpts(data []byte, opts *SignOpts) ([]byte, error)
	// 返回公钥
	PublicKey() PublicKey
	// 转换为crypto包中的 PrivateKey 接口类
	ToStandardKey() crypto.PrivateKey
}

=== 非对称秘钥签名+验签接口 === 私钥签名接口

type PublicKey

type PublicKey interface {
	Key
	// 公钥验签
	Verify(data []byte, sig []byte) (bool, error)
	VerifyWithOpts(data []byte, sig []byte, opts *SignOpts) (bool, error)
	// 转换为crypto包中的 PublicKey 接口类
	ToStandardKey() crypto.PublicKey
}

公钥验签接口

type SignOpts

type SignOpts struct {
	Hash         HashType
	UID          string
	EncodingType string
}

Signing options

type SymmetricKey

type SymmetricKey interface {
	Key
	// 加密接口
	Encrypt(plain []byte) ([]byte, error)
	EncryptWithOpts(plain []byte, opts *EncOpts) ([]byte, error)
	// 解密接口
	Decrypt(ciphertext []byte) ([]byte, error)
	DecryptWithOpts(ciphertext []byte, opts *EncOpts) ([]byte, error)
}

=== 对称秘钥加解密接口 ===