Update document

emmansun · Dec 14, 2023 · aa4e023 · aa4e023
1 parent 0dfbe03
commit aa4e023
Show file tree

Hide file tree

Showing 4 changed files with 16 additions and 5 deletions.
diff --git a/README-EN.md b/README-EN.md
@@ -12,6 +12,8 @@
 
 English | [简体中文](README.md)
 
+ShangMi (SM) cipher suites for Golang, referred to as **GMSM**, is a secure, high-performance, easy-to-use Golang ShangMi (SM) cipher suites library, covering public algorithms SM2/SM3/SM4/SM9/ZUC.
+
 ## Packages
 * **SM2** - This is a SM2 sm2p256v1 implementation whose performance is similar like golang native NIST P256 under **amd64** and **arm64**, for implementation detail, please refer [SM2实现细节](https://github.com/emmansun/gmsm/wiki/SM2%E6%80%A7%E8%83%BD%E4%BC%98%E5%8C%96). It supports ShangMi sm2 digital signature, public key encryption algorithm and also key exchange.
 

diff --git a/README.md b/README.md
@@ -11,6 +11,8 @@
 
 [English](README-EN.md) | 简体中文
 
+Go语言商用密码软件，简称**GMSM**，一个安全、高性能、易于使用的Go语言商用密码软件库，涵盖商用密码公开算法SM2/SM3/SM4/SM9/ZUC。
+
 ## 包结构
 * **SM2** - SM2椭圆曲线公钥密码算法，曲线的具体实现位于[internal/sm2ec](https://github.com/emmansun/gmsm/tree/main/internal/sm2ec) package中。SM2曲线实现性能和Golang SDK中的NIST P256椭圆曲线原生实现（非BoringCrypto）类似，也对**amd64** 和 **arm64**架构做了专门汇编优化实现，您也可以参考[SM2实现细节](https://github.com/emmansun/gmsm/wiki/SM2%E6%80%A7%E8%83%BD%E4%BC%98%E5%8C%96)及相关Wiki和代码，以获得更多实现细节。SM2包实现了SM2椭圆曲线公钥密码算法的数字签名算法、公钥加密算法、密钥交换算法，以及《GB/T 35276-2017信息安全技术 SM2密码算法使用规范》中的密钥对保护数据格式。
 
@@ -22,7 +24,7 @@
 
 * **ZUC** - 祖冲之序列密码算法实现。使用SIMD、AES指令以及无进位乘法指令，分别对**amd64**、**arm64**架构做了优化实现, 您也可以参考[ZUC实现及优化](https://github.com/emmansun/gmsm/wiki/Efficient-Software-Implementations-of-ZUC)和相关代码，以获得更多实现细节。ZUC包实现了基于祖冲之序列密码算法的机密性算法、128/256位完整性算法。
 
-* **CFCA** - CFCA特定实现，目前实现的是SM2私钥、证书封装处理，对应SADK中的**PKCS12_SM2**。
+* **CFCA** - CFCA（中金）特定实现，目前实现的是SM2私钥、证书封装处理，对应SADK中的**PKCS12_SM2**。
 
 * **CIPHER** - ECB/CCM/XTS/HCTR/BC/OFBNLF加密模式实现。XTS模式同时支持NIST规范和国标 **GB/T 17964-2021**。当前的XTS模式由于实现了BlockMode，其结构包含一个tweak数组，所以其**不支持并发使用**。**分组链接（BC）模式**和**带非线性函数的输出反馈（OFBNLF）模式**为分组密码算法的工作模式标准**GB/T 17964**的遗留模式，**带泛杂凑函数的计数器（HCTR）模式**是**GB/T 17964-2021**中的新增模式。分组链接（BC）模式和CBC模式类似；而带非线性函数的输出反馈（OFBNLF）模式的话，从软件实现的角度来看，基本没有性能优化的空间。
 

diff --git a/docs/sm2.md b/docs/sm2.md
@@ -7,18 +7,22 @@
 * 《GB/T 32918.4-2016 信息安全技术 SM2椭圆曲线公钥密码算法 第4部分：公钥加密算法》
 * 《GB/T 32918.5-2016 信息安全技术 SM2椭圆曲线公钥密码算法 第5部分：参数定义》
 * 《GB/T 35276-2017 信息安全技术 SM2密码算法使用规范》
+* 《GB/T 35275-2017 信息安全技术 SM2密码算法加密签名消息语法规范》(对应PKCS#7)
 
 您可以从[国家标准全文公开系统](https://openstd.samr.gov.cn/)在线阅读这些标准。
 
 ## 概述
-既然是椭圆曲线公钥密码算法，它就和NIST P系列椭圆曲线公钥密码算法类似，特别是P-256。NIST P 系列椭圆曲线公钥密码算法主要用于数字签名和密钥交换，NIST没有定义基于椭圆曲线的公钥加密算法标准，[SEC 1: Elliptic Curve Cryptography](https://www.secg.org/sec1-v2.pdf)第五章定义了“Elliptic Curve Integrated Encryption Scheme (ECIES)”，不过应用不广。感兴趣的同学可以进一步对比一下：
+既然是椭圆曲线公钥密码算法，它就和NIST P系列椭圆曲线公钥密码算法类似，特别是P-256。NIST P 系列椭圆曲线公钥密码算法主要用于数字签名和密钥交换，NIST没有定义基于椭圆曲线的公钥加密算法标准，[SEC 1: Elliptic Curve Cryptography](https://www.secg.org/sec1-v2.pdf)第五章定义了“Elliptic Curve Integrated Encryption Scheme (ECIES)”，不过应用不广。SM2公钥加密算法与其相似，只是MAC不同。感兴趣的同学可以进一步对比一下：
 
 | SM2 | SEC 1 |
 | :--- | :--- |
 | 数字签名算法 | ECDSA |
 | 密钥交换协议 | ECMQV |
 | 公钥加密算法 | ECIES |
 
+**注**：最新的阿里KMS支持ECIES，难道客户有这个需求？
+ECIES_DH_SHA_1_XOR_HMAC：遵循[SEC 1: Elliptic Curve Cryptography, Version 2.0](https://www.secg.org/sec1-v2.pdf)标准，密钥协商算法采用ECDH，密钥派生算法采用 KDF2 with SHA-1，MAC算法采用HMAC-SHA-1，对称加密算法采用XOR。
+
 ## SM2公私钥对
 SM2公私钥对的话，要么是自己产生，要么是别的系统产生后通过某种方式传输给您的。
 
@@ -64,9 +68,11 @@ func getPublicKey(pemContent []byte) (any, error) {
 * RFC 5915 / SEC1 - http://www.secg.org/sec1-v2.pdf
 * PKCS#12
 * PKCS#8
-* PKCS#7
+* PKCS#7（《GB/T 35275-2017 信息安全技术 SM2密码算法加密签名消息语法规范》）
 * CFCA自定义封装
-* 《GB/T 35276-2017 信息安全技术 SM2密码算法使用规范》
+* 《GB/T 35276-2017 信息安全技术 SM2密码算法使用规范》  
+
+（存在于智能密码钥匙中，符合《GB/T 35291-2017 信息安全技术 智能密码钥匙应用接口规范》的，不在这里说明。）
 
 所以，当您拿到一个密钥文件，您需要知道它的封装格式，然后选用合适的方法。PEM编码的密钥文本通常第一行会有相关信息。如果您得到的是一个ASN.1编码，那可能需要通过ASN.1结构和一些其中的OID来判断了。私钥信息是非常关键的信息，通常密钥文件被加密保护。可能是标准落后于应用的原因，目前这一块的互操作性可能差一点。
 

diff --git a/pkcs7/pkcs7.go b/pkcs7/pkcs7.go
@@ -80,7 +80,8 @@ var (
 )
 
 var (
-	//SM2 Signed Data OIDs
+	// SM2 Signed Data OIDs
+	// 《GB/T 35275-2017 信息安全技术 SM2密码算法加密签名消息语法规范》
 	SM2OIDData                = asn1.ObjectIdentifier{1, 2, 156, 10197, 6, 1, 4, 2, 1}
 	SM2OIDSignedData          = asn1.ObjectIdentifier{1, 2, 156, 10197, 6, 1, 4, 2, 2}
 	SM2OIDEnvelopedData       = asn1.ObjectIdentifier{1, 2, 156, 10197, 6, 1, 4, 2, 3}