Skip to content

Commit

Permalink
doc typo
Browse files Browse the repository at this point in the history
  • Loading branch information
@kvii
kvii committed Jan 24, 2025
1 parent ea592fe commit 02becc6
Show file tree
Hide file tree
Showing 7 changed files with 86 additions and 86 deletions.
20 changes: 10 additions & 10 deletions docs/cfca.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,9 +38,9 @@ SADK 3.2之后的版本，支持下列SM2密文格式(encryptedType)：

| encryptedType | 输出格式 | 用本软件库如何解密 |
| :--- | :--- | :--- |
| 0 | ASN.1编码格式 ```EncryptUtil.encrypt``` 方法默认 | 正常解密 |
| 0 | ASN.1编码格式 `EncryptUtil.encrypt` 方法默认 | 正常解密 |
| 2 | C1C3C2 格式，带0x04这个点非压缩标识 | 正常解密 |
| 4 | C1C3C2 格式，不带0x04这个点非压缩标识 （```EncryptUtil.encryptMessageBySM2 / EncryptUtil.encryptFileBySM2``` 方法默认） | 添加0x04前缀后解密 |
| 4 | C1C3C2 格式，不带0x04这个点非压缩标识 （`EncryptUtil.encryptMessageBySM2 / EncryptUtil.encryptFileBySM2` 方法默认） | 添加0x04前缀后解密 |
| 8 | C1C2C3 格式，带0x04这个点非压缩标识 | 指定解密Opts后解密 |
| 16 | C1C2C3 格式，不带0x04这个点非压缩标识 | 添加0x04前缀，同时指定解密Opts后解密 |

Expand All @@ -57,8 +57,8 @@ SADK 3.2之后的版本，支持下列SM2密文格式(encryptedType)：
### SM2数字信封加解密
互操作性问题主要出在：
1. 数据对称加密所用密钥的SM2密文格式。
2. 对称加密算法的OID。```public static final ASN1ObjectIdentifier id_sm4_CBC = new ASN1ObjectIdentifier("1.2.156.10197.1.104");```。
3. 如果需要用本软件库去解密CFCA生成的SM2数字信封，目前会有问题（从**v0.29.3**开始可以解密）。CFCA实现不符合《GB/T 35275-2017：信息安全技术 SM2密码算法加密签名消息语法规范》，它的**RecipientInfo**默认使用SubjectKeyIdentifier而不是IssuerAndSerialNumber。在SADK 3.7.1.0中，需要指定recipientPolicyType=2（0：从证书扩展中获取SubjectKeyID，找不到抛异常；1：根据公钥数据直接计算SubjectKeyID；2：使用证书的IssuerAndSerialNumber）才会使用IssuerAndSerialNumber。正常情况下，只有CA证书才一定会在证书扩展中有SubjectKeyID信息。如果要产生和CFCA一样的加密信封，请使用```pkcs7.EnvelopeMessageCFCA```方法。
2. 对称加密算法的OID。`public static final ASN1ObjectIdentifier id_sm4_CBC = new ASN1ObjectIdentifier("1.2.156.10197.1.104");`。
3. 如果需要用本软件库去解密CFCA生成的SM2数字信封，目前会有问题（从**v0.29.3**开始可以解密）。CFCA实现不符合《GB/T 35275-2017：信息安全技术 SM2密码算法加密签名消息语法规范》，它的**RecipientInfo**默认使用SubjectKeyIdentifier而不是IssuerAndSerialNumber。在SADK 3.7.1.0中，需要指定recipientPolicyType=2（0：从证书扩展中获取SubjectKeyID，找不到抛异常；1：根据公钥数据直接计算SubjectKeyID；2：使用证书的IssuerAndSerialNumber）才会使用IssuerAndSerialNumber。正常情况下，只有CA证书才一定会在证书扩展中有SubjectKeyID信息。如果要产生和CFCA一样的加密信封，请使用`pkcs7.EnvelopeMessageCFCA`方法。

**v0.29.6**之后，请直接使用
* `cfca.EnvelopeMessage`
Expand All @@ -70,22 +70,22 @@ SADK 3.2之后的版本，支持下列SM2密文格式(encryptedType)：
1. 数据对称加密密钥的密文格式为**C1C2C3 格式，不带0x04这个点非压缩标识**。这个不符合《GM/T 0010-2012 SM2密码算法加密签名消息语法规范》以及《GB/T 35275-2017 信息安全技术 SM2密码算法加密签名消息语法规范》。
2. SM4-CBC的OID，使用了["SM4" block cipher](https://oid-rep.orange-labs.fr/get/1.2.156.10197.1.104)，而不是["SMS4-CBC"](https://oid-rep.orange-labs.fr/get/1.2.156.10197.1.104.2)。

本软件库的```pkcs7.EncryptCFCA```方法```DecryptCFCA```方法提供了SADK 3.2之前版本的信封加解密兼容性，记得cipher参数选择```pkcs.SM4```。但是```pkcs7.EncryptCFCA```方法产生的加密信封依然使用IssuerAndSerialNumber作为RecipientInfo。
本软件库的`pkcs7.EncryptCFCA`方法`DecryptCFCA`方法提供了SADK 3.2之前版本的信封加解密兼容性，记得cipher参数选择`pkcs.SM4`。但是`pkcs7.EncryptCFCA`方法产生的加密信封依然使用IssuerAndSerialNumber作为RecipientInfo。

#### SADK 3.2+版本
1. 数据对称加密密钥的密文格式为**ASN.1编码格式**，这个符合《GB/T 35275-2017 信息安全技术 SM2密码算法加密签名消息语法规范》。
2. SM4-CBC的OID，使用了["SM4" block cipher](https://oid-rep.orange-labs.fr/get/1.2.156.10197.1.104)，而不是["SMS4-CBC"](https://oid-rep.orange-labs.fr/get/1.2.156.10197.1.104.2)。

本软件库的```pkcs7.EncryptSM```方法```Decrypt```方法提供了SADK 3.2+版本的信封加解密兼容性。使用时，请确保`cipher`参数选择```pkcs.SM4```。```pkcs7.EncryptSM```方法符合《GB/T 35275-2017 信息安全技术 SM2密码算法加密签名消息语法规范》，CFCA的SADK可实现相应数据的解密。
本软件库的`pkcs7.EncryptSM`方法`Decrypt`方法提供了SADK 3.2+版本的信封加解密兼容性。使用时，请确保`cipher`参数选择`pkcs.SM4`。`pkcs7.EncryptSM`方法符合《GB/T 35275-2017 信息安全技术 SM2密码算法加密签名消息语法规范》，CFCA的SADK可实现相应数据的解密。

本软件库的```pkcs7.EnvelopeMessageCFCA```方法提供了CFCA SADK更兼容的实现，也就是recipientPolicyType=0。
本软件库的`pkcs7.EnvelopeMessageCFCA`方法提供了CFCA SADK更兼容的实现，也就是recipientPolicyType=0。

从SADK 的向下兼容性来看，SADK 3.2+能够解密SADK 3.2之前版本的数字信封加密数据，反之不行。

### SM2 PKCS7签名数据
```cfca.sadk.util.p7SignMessageAttach / cfca.sadk.util.p7SignMessageDetach```，对应```pkcs7.SignWithoutAttr```，如果要Detach签名，调用```Finish```之前调用```Detach```就行。
`cfca.sadk.util.p7SignMessageAttach / cfca.sadk.util.p7SignMessageDetach`，对应`pkcs7.SignWithoutAttr`，如果要Detach签名，调用`Finish`之前调用`Detach`就行。

```cfca.sadk.util.p7SignFileAttach / cfca.sadk.util.p7SignFileDetach```类似，只是本软件库不提供对应方法，您可以通过```pkcs7.SignWithoutAttr```自己实现。
`cfca.sadk.util.p7SignFileAttach / cfca.sadk.util.p7SignFileDetach`类似，只是本软件库不提供对应方法，您可以通过`pkcs7.SignWithoutAttr`自己实现。

参考[cfca sadk 3.0.2.0](https://github.com/emmansun/gmsm/issues/260)

Expand All @@ -108,4 +108,4 @@ SADK 3.2之后的版本，支持下列SM2密文格式(encryptedType)：
使用`cfca.ParseEscrowPrivateKey`解析CFCA返回的加密用私钥。

### SM2私钥、证书的解析
这个是CFCA自定义的，未见相关标准，可以通过```cfca.ParseSM2```来解析。```cfca.ParseSM2```函数只接受**DER**编码的二进制数据，如果你的数据是**base64**编码的，请先自行解码。
这个是CFCA自定义的，未见相关标准，可以通过`cfca.ParseSM2`来解析。`cfca.ParseSM2`函数只接受**DER**编码的二进制数据，如果你的数据是**base64**编码的，请先自行解码。
20 changes: 10 additions & 10 deletions docs/pkcs12.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,9 @@

| 方法 | 适用 | 具体说明 |
| :--- | :--- | :--- |
| ```DecodeChain``` | 抽取出一个私钥、一个相应证书以及证书链 | 私钥和相应证书必须存在，否则报错 |
| ```Decode``` | 抽取出一个私钥、一个相应证书 | 私钥和相应证书必须存在，否则报错；并且**不能有证书链存在**。 |
| ```DecodeTrustStore``` | 抽取出证书链 | 只支持java的TrustStore, [Difference Between a Java Keystore and a Truststore](https://www.baeldung.com/java-keystore-truststore-difference) |
| `DecodeChain` | 抽取出一个私钥、一个相应证书以及证书链 | 私钥和相应证书必须存在，否则报错 |
| `Decode` | 抽取出一个私钥、一个相应证书 | 私钥和相应证书必须存在，否则报错；并且**不能有证书链存在**。 |
| `DecodeTrustStore` | 抽取出证书链 | 只支持java的TrustStore, [Difference Between a Java Keystore and a Truststore](https://www.baeldung.com/java-keystore-truststore-difference) |

### 解码能处理的算法

Expand Down Expand Up @@ -58,13 +58,13 @@ PBES1属于老旧遗留算法，目前版本未实现。
## PKCS#12的生成
目前只支持下列几种，不支持自由定义：

* ```LegacyRC2```，加密使用PKCS12特有算法；对证书使用RC2加密，对私钥使用3DES加密，一致性保证使用HMAC-SHA1。
* ```LegacyDES```，加密使用PKCS12特有算法；对证书和私钥都是用3DES加密，一致性保证使用HMAC-SHA1。
* ```Passwordless```，无加密、一致性保证模式。
* ```Modern2023```，对应OpenSSL 3+ 默认，加密使用AES-256-CBC with PBKDF2，一致性保证使用HMAC-SHA256。
* ```ShangMi2024```，这个估计目前没什么互操作性。
* `LegacyRC2`，加密使用PKCS12特有算法；对证书使用RC2加密，对私钥使用3DES加密，一致性保证使用HMAC-SHA1。
* `LegacyDES`，加密使用PKCS12特有算法；对证书和私钥都是用3DES加密，一致性保证使用HMAC-SHA1。
* `Passwordless`，无加密、一致性保证模式。
* `Modern2023`，对应OpenSSL 3+ 默认，加密使用AES-256-CBC with PBKDF2，一致性保证使用HMAC-SHA256。
* `ShangMi2024`，这个估计目前没什么互操作性。

目前的全局函数```Encode``` / ```EncodeTrustStore```使用**LegacyRC2**编码器。
目前的全局函数`Encode` / `EncodeTrustStore`使用**LegacyRC2**编码器。

```go
// LegacyRC2 encodes PKCS#12 files using weak algorithms that were
Expand Down Expand Up @@ -180,7 +180,7 @@ var ShangMi2024 = &Encoder{
```

## 解析加密的PKCS#8私钥
[go-pkcs12](https://github.com/emmansun/go-pkcs12) 也提供了```ParsePKCS8PrivateKey```方法，相比**pkcs8**的类似方法，这里特别支持**PBES-PKCS12**加密算法。
[go-pkcs12](https://github.com/emmansun/go-pkcs12) 也提供了`ParsePKCS8PrivateKey`方法，相比**pkcs8**的类似方法，这里特别支持**PBES-PKCS12**加密算法。
* PBE-SHA1-RC2-128
* PBE-SHA1-RC2-40
* PBE-SHA1-3DES
48 changes: 24 additions & 24 deletions docs/pkcs7.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,20 +22,20 @@
#### 主要方法
（是否国密是指OID也使用国密体系）

| 是否国密 | 加密 | 解密（先调用```Parse```） |
| 是否国密 | 加密 | 解密（先调用`Parse`） |
| :--- | :--- | :--- |
| 否 | Encrypt | Decrypt |
| 否 | EncryptUsingPSK | DecryptUsingPSK |
| 是 | EncryptSM | Decrypt |
| 是 | EncryptCFCA | DecryptCFCA |
| 是 | EncryptSMUsingPSK | DecryptUsingPSK |

关于```EncryptSM / EncryptCFCA```的区别，请参考**CFCA互操作性指南**。
关于`EncryptSM / EncryptCFCA`的区别，请参考**CFCA互操作性指南**。
带PSK（Pre-shared key）后缀的方法，其对称加密密钥由调用者提供，而非随机生成。

### 加密数据（Encrypted Data）
加密：对应本项目的```pkcs7.EncryptUsingPSK```和```pkcs7.EncryptSMUsingPSK```方法。
解密：对应本项目的```pkcs7.DecryptUsingPSK```方法（当然要先调用```pkcs7.Parse```）。
加密：对应本项目的`pkcs7.EncryptUsingPSK`和`pkcs7.EncryptSMUsingPSK`方法。
解密：对应本项目的`pkcs7.DecryptUsingPSK`方法（当然要先调用`pkcs7.Parse`）。

### 签名数据（Signed Data）
签名数据，使用证书对应的私钥进行签名，理论上支持多个签名者，但通常使用场景都是单签。和数字信封数据类似，也分国密和非国密。
Expand All @@ -46,15 +46,15 @@

| 是否国密 | 数据是否是哈希值 | 方法 | 默认签名算法 |
| :--- | :--- | :--- | :--- |
| 否 | 否 | ```NewSignedData``` | SHA1 |
| 否 | 是 | ```NewSignedDataWithDigest``` | SHA1 |
| 是 | 否 | ```NewSMSignedData``` | SM3 |
| 是 | 是 | ```NewSMSignedDataWithDigest``` | SM3 |
| 否 | 否 | `NewSignedData` | SHA1 |
| 否 | 是 | `NewSignedDataWithDigest` | SHA1 |
| 是 | 否 | `NewSMSignedData` | SM3 |
| 是 | 是 | `NewSMSignedDataWithDigest` | SM3 |

2. 可选步骤：调用```SetDigestAlgorithm```设置想要的签名算法，通常国密**不需要**修改。
3. 接着调用```AddSigner```或```AddSignerChain```方法，进行签名；可以通过```SignerInfoConfig.SkipCertificates```指定忽略证书项（最终签名数据中不包含证书项）；
4. 如果进行Detach签名，则调用```Detach```方法；
5. 最后调用```Finish```方法，序列化输出结果。
2. 可选步骤：调用`SetDigestAlgorithm`设置想要的签名算法，通常国密**不需要**修改。
3. 接着调用`AddSigner`或`AddSignerChain`方法，进行签名；可以通过`SignerInfoConfig.SkipCertificates`指定忽略证书项（最终签名数据中不包含证书项）；
4. 如果进行Detach签名，则调用`Detach`方法；
5. 最后调用`Finish`方法，序列化输出结果。

**注意**：
1. 如果是直接对哈希值签名，一定是Detach签名。
Expand Down Expand Up @@ -90,17 +90,17 @@ if err := p7.VerifyWithChain(truststore); err != nil {

#### 验证签名
而验证的话，流程如下：
1. 调用```Parse```方法；
2. 如果是Detach签名数据，则手动设置原始数据（参考```testSign```方法）；
3. 如果签名数据中不包含证书项，则手动设置验签证书（参考```TestSkipCertificates```）；
4. 如果Content是原始数据，调用```Verify```或```VerifyWithChain```方法；如果Content是哈希值，调用```VerifyAsDigest```或```VerifyAsDigestWithChain```方法。
1. 调用`Parse`方法；
2. 如果是Detach签名数据，则手动设置原始数据（参考`testSign`方法）；
3. 如果签名数据中不包含证书项，则手动设置验签证书（参考`TestSkipCertificates`）；
4. 如果Content是原始数据，调用`Verify`或`VerifyWithChain`方法；如果Content是哈希值，调用`VerifyAsDigest`或`VerifyAsDigestWithChain`方法。

#### 特殊方法
```DegenerateCertificate```，退化成签名数据中只包含证书，目前没有使用SM2 OID的方法，如果需要可以请求添加。可以参考```TestDegenerateCertificate```和```TestParseSM2CertificateChain```。
`DegenerateCertificate`，退化成签名数据中只包含证书，目前没有使用SM2 OID的方法，如果需要可以请求添加。可以参考`TestDegenerateCertificate`和`TestParseSM2CertificateChain`。


### 签名及数字信封数据（Signed and Enveloped Data）
签名和数字信封数据，使用场景较少，有些实现用它来传输私钥（譬如www.gmcert.org）。具体请参考```sign_enveloped_test.go```。
签名和数字信封数据，使用场景较少，有些实现用它来传输私钥（譬如www.gmcert.org）。具体请参考`sign_enveloped_test.go`。

The "signed and enveloped data" content type is a part of the Cryptographic Message Syntax (CMS), which is used in various Internet Standards. However, it's not recommended for use due to several reasons:

Expand All @@ -113,11 +113,11 @@ The "signed and enveloped data" content type is a part of the Cryptographic Mess
Instead of using the "signed and enveloped data" content type, it's generally recommended to use separate "signed data" and "enveloped data" content types. This allows the operations to be performed in the order that best suits the application's needs, and also simplifies the implementation.

#### 加密签名流程
1. 调用```NewSignedAndEnvelopedData```或者```NewSMSignedAndEnvelopedData```创建```SignedAndEnvelopedData```数据结构，此过程包含了数据加密过程；
2. 调用```AddSigner```或```AddSignerChain```方法，进行签名；
3. 调用```AddRecipient```方法，用Recipient的公钥加密数据密钥；
4. 最后调用```Finish```方法，序列化输出结果。
1. 调用`NewSignedAndEnvelopedData`或者`NewSMSignedAndEnvelopedData`创建`SignedAndEnvelopedData`数据结构，此过程包含了数据加密过程；
2. 调用`AddSigner`或`AddSignerChain`方法，进行签名；
3. 调用`AddRecipient`方法，用Recipient的公钥加密数据密钥；
4. 最后调用`Finish`方法，序列化输出结果。

#### 解密验签流程
1. 调用```Parse```方法；
2. 调用```DecryptAndVerify```或者```DecryptAndVerifyOnlyOne```进行解密和验签。
1. 调用`Parse`方法；
2. 调用`DecryptAndVerify`或者`DecryptAndVerifyOnlyOne`进行解密和验签。
Loading

0 comments on commit 02becc6

Please sign in to comment.