gmsm/docs/pkcs12.md

# [go-pkcs12](https://github.com/emmansun/go-pkcs12)应用指南
[PKCS #12: Personal Information Exchange Syntax v1.1](https://datatracker.ietf.org/doc/html/rfc7292)，PKCS12目前似乎没有相应的国密标准。
定制PKCS12的目的是：
1. 可以处理**SM2**私钥和证书。
2. 可以替代、使用一些商密算法，主要是**SM3**和**SM4**。

## PKCS#12的解析
[go-pkcs12](https://github.com/emmansun/go-pkcs12)提供三个方法：

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

### 解码能处理的算法

#### 证书及私钥加密算法
这里主要是**PBES(Password-Based Encryption Scheme)**, 它主要涉及几方面：  
1. 密码处理  
2. 从密码派生出加密密钥
3. 具体对称加密算法

**PBES-PKCS12**
* pbeWithSHAAnd3-KeyTripleDES-CBC OBJECT IDENTIFIER ::= {pkcs-12PbeIds 3}
* pbeWithSHAAnd128BitRC2-CBC      OBJECT IDENTIFIER ::= {pkcs-12PbeIds 5}
* pbewithSHAAnd40BitRC2-CBC       OBJECT IDENTIFIER ::= {pkcs-12PbeIds 6}  

不同于**PKCS#5 v1.5**中的**PBES1**，上述这些是**PKCS#12**的独有算法，特别是它的**KDF**和**密码处理**。

**PBES1**  
PBES1属于老旧遗留算法，目前版本未实现。

**PBES2**  
由两部分组成，分别为**KDF**和加密算法。目前KDF只支持**KDF2**, KDF2中支持的**PRF**方法有：
* id-hmacWithSHA1
* id-hmacWithSHA256
* id-hmacWithSM3

具体可参考[PKCS #5: Password-Based Cryptography Specification Version 2.1](https://datatracker.ietf.org/doc/html/rfc8018)

加密算法有：  
* AES-CBC-Pad，密钥长度支持16/24/32字节
* SM4-CBC-Pad，密钥长度支持16字节

#### 数据完整性保护(PBMAC)
这里只支持基于密码的完整性保护：**PKCS12-KDF + HMAC**。支持的HASH算法有：
* SHA1
* SHA256
* SM3

**PBMAC**目前的实现还是基于**PKCS12-KDF**，将来看情况是否要实现**PBMAC1**，主要看**OpenSSL**的支持进度：
* [Support FIPS-compliant PKCS#12 files and create them by default in FIPS mode](https://github.com/openssl/openssl/issues/24546)
* [RFC 9579 implementation: add PBMAC1 with PBKDF2 to PKCS#12](https://github.com/openssl/openssl/pull/24577)

从**v0.4.1**开始支持**PBMAC1**。

## 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```，这个估计目前没什么互操作性。

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

```go
// LegacyRC2 encodes PKCS#12 files using weak algorithms that were
// traditionally used in PKCS#12 files, including those produced
// by OpenSSL before 3.0.0, go-pkcs12 before 0.3.0, and Java when
// keystore.pkcs12.legacy is defined.  Specifically, certificates
// are encrypted using PBE with RC2, and keys are encrypted using PBE
// with 3DES, using keys derived with 2048 iterations of HMAC-SHA-1.
// MACs use HMAC-SHA-1 with keys derived with 1 iteration of HMAC-SHA-1.
//
// Due to the weak encryption, it is STRONGLY RECOMMENDED that you use [DefaultPassword]
// when encoding PKCS#12 files using this encoder, and protect the PKCS#12 files
// using other means.
//
// By default, OpenSSL 3 can't decode PKCS#12 files created using this encoder.
// For better compatibility, use [LegacyDES].  For better security, use
// [Modern2023].
var LegacyRC2 = &Encoder{
	macAlgorithm:         oidSHA1,
	certAlgorithm:        oidPBEWithSHAAnd40BitRC2CBC,
	keyAlgorithm:         oidPBEWithSHAAnd3KeyTripleDESCBC,
	kdfPrf:               nil,
	encryptionScheme:     nil,
	macIterations:        1,
	encryptionIterations: 2048,
	saltLen:              8,
	rand:                 rand.Reader,
}

// LegacyDES encodes PKCS#12 files using weak algorithms that are
// supported by a wide variety of software.  Certificates and keys
// are encrypted using PBE with 3DES using keys derived with 2048
// iterations of HMAC-SHA-1.  MACs use HMAC-SHA-1 with keys derived
// with 1 iteration of HMAC-SHA-1.  These are the same parameters
// used by OpenSSL's -descert option.  As of 2023, this encoder is
// likely to produce files that can be read by the most software.
//
// Due to the weak encryption, it is STRONGLY RECOMMENDED that you use [DefaultPassword]
// when encoding PKCS#12 files using this encoder, and protect the PKCS#12 files
// using other means.  To create more secure PKCS#12 files, use [Modern2023].
var LegacyDES = &Encoder{
	macAlgorithm:         oidSHA1,
	certAlgorithm:        oidPBEWithSHAAnd3KeyTripleDESCBC,
	keyAlgorithm:         oidPBEWithSHAAnd3KeyTripleDESCBC,
	kdfPrf:               nil,
	encryptionScheme:     nil,
	macIterations:        1,
	encryptionIterations: 2048,
	saltLen:              8,
	rand:                 rand.Reader,
}

// Passwordless encodes PKCS#12 files without any encryption or MACs.
// A lot of software has trouble reading such files, so it's probably only
// useful for creating Java trust stores using [Encoder.EncodeTrustStore]
// or [Encoder.EncodeTrustStoreEntries].
//
// When using this encoder, you MUST specify an empty password.
var Passwordless = &Encoder{
	macAlgorithm:     nil,
	certAlgorithm:    nil,
	keyAlgorithm:     nil,
	kdfPrf:           nil,
	encryptionScheme: nil,
	rand:             rand.Reader,
}

// Modern2023 encodes PKCS#12 files using algorithms that are considered modern
// as of 2023.  Private keys and certificates are encrypted using PBES2 with
// PBKDF2-HMAC-SHA-256 and AES-256-CBC.  The MAC algorithm is HMAC-SHA-2.  These
// are the same algorithms used by OpenSSL 3 (by default), Java 20 (by default),
// and Windows Server 2019 (when "stronger" is used).
//
// Files produced with this encoder can be read by OpenSSL 1.1.1 and higher,
// Java 12 and higher, and Windows Server 2019 and higher.
//
// For passwords, it is RECOMMENDED that you do one of the following:
// 1) Use [DefaultPassword] and protect the file using other means, or
// 2) Use a high-entropy password, such as one generated with `openssl rand -hex 16`.
//
// You SHOULD NOT use a lower-entropy password with this encoder because the number of KDF
// iterations is only 2048 and doesn't provide meaningful protection against
// brute-forcing.  You can increase the number of iterations using [Encoder.WithIterations],
// but as https://neilmadden.blog/2023/01/09/on-pbkdf2-iterations/ explains, this doesn't
// help as much as you think.
var Modern2023 = &Encoder{
	macAlgorithm:         oidSHA256,
	certAlgorithm:        oidPBES2,
	keyAlgorithm:         oidPBES2,
	kdfPrf:               oidHmacWithSHA256,
	encryptionScheme:     oidAES256CBC,	
	macIterations:        2048,
	encryptionIterations: 2048,
	saltLen:              16,
	rand:                 rand.Reader,
}

// ShangMi2024 encodes PKCS#12 files using algorithms that are all ShangMi.
// Private keys and certificates are encrypted using PBES2 with	 PBKDF2-HMAC-SM3 and SM4-CBC.
// The MAC algorithm is PBMAC1-HMAC-SM3.
var ShangMi2024 = &Encoder{
	macAlgorithm:         oidPBMAC1,
	certAlgorithm:        oidPBES2,
	keyAlgorithm:         oidPBES2,
	kdfPrf:               oidHmacWithSM3,
	encryptionScheme:     oidSM4CBC,
	messageAuthScheme:    oidHmacWithSM3,
	macIterations:        2048,
	encryptionIterations: 2048,
	saltLen:              16,
	rand:                 rand.Reader,
}
```

## 解析加密的PKCS#8私钥
[go-pkcs12](https://github.com/emmansun/go-pkcs12) 也提供了```ParsePKCS8PrivateKey```方法，相比**pkcs8**的类似方法，这里特别支持**PBES-PKCS12**加密算法。
* PBE-SHA1-RC2-128
* PBE-SHA1-RC2-40
* PBE-SHA1-3DES