优化 PKCS8 及其文档

deatil · Jan 4, 2025 · 617d575 · 617d575
1 parent e4a430e
commit 617d575
Show file tree

Hide file tree

Showing 11 changed files with 117 additions and 111 deletions.
diff --git a/docs/pkcs8.md b/docs/pkcs8.md
@@ -9,7 +9,7 @@ import (
 ~~~
 
 
-#### 加密证书 / Encrypt key
+#### 加密私钥证书 / Encrypt Private Key
 
 ~~~go
 import (
@@ -19,53 +19,67 @@ import (
 )
 
 func main() {
-    var data []byte = []byte("...")
+    var prikey []byte = []byte("...")
     var pass []byte = []byte("...")
 
+    // 默认设置 / default options
     var opts = pkcs8.DefaultOpts
 
-    // 可用默认设置: [DefaultPBKDF2Opts | DefaultSMPBKDF2Opts | DefaultScryptOpts | DefaultOpts | DefaultSMOpts]
-    block, err := EncryptPEMBlock(rand.Reader, "ENCRYPTED PRIVATE KEY", data, pass, opts)
+    // 可用默认设置 / can use default options:
+    // DefaultPBKDF2Opts | DefaultSMPBKDF2Opts | DefaultScryptOpts | DefaultOpts | DefaultSMOpts
+    block, err := pkcs8.EncryptPEMBlock(rand.Reader, "ENCRYPTED PRIVATE KEY", prikey, pass, opts)
 
     // 自定义设置
+    // use struct to make options
     var opts1 = pkcs8.Opts{
-        Cipher:  pkcs8.SM4CFB,
+        Cipher:  pkcs8.SM4CBC,
         KDFOpts: pkcs8.SMPBKDF2Opts{
             SaltSize:       8,
             IterationCount: 5000,
             HMACHash:       pkcs8.DefaultSMHash,
         },
     }
-    var opts2 = pkcs8.PBKDF2Opts{
-        SaltSize:       16,
-        IterationCount: 10000,
+    var opts2 = pkcs8.Opts{
+        Cipher:  pkcs8.AES256CBC,
+        KDFOpts: pkcs8.PBKDF2Opts{
+            SaltSize:       16,
+            IterationCount: 10000,
+        },
     }
-    var opts3 = pkcs8.SMPBKDF2Opts{
-        SaltSize:       16,
-        IterationCount: 10000,
-        HMACHash:       DefaultSMHash,
+    var opts3 = pkcs8.Opts{
+        Cipher:  pkcs8.AES256CBC,
+        KDFOpts: pkcs8.PBKDF2Opts{
+            SaltSize:       16,
+            IterationCount: 10000,
+            // HMACHash:    pkcs8.DefaultHash
+            HMACHash:       pkcs8.GetHashFromName("SHA256"),
+        },
     }
-    var opts4 = pkcs8.ScryptOpts{
-        SaltSize:                 16,
-        CostParameter:            1 << 2,
-        BlockSize:                8,
-        ParallelizationParameter: 1,
+    var opts4 = pkcs8.Opts{
+        Cipher:  pkcs8.AES256CBC,
+        KDFOpts: pkcs8.ScryptOpts{
+            SaltSize:                 16,
+            CostParameter:            1 << 2,
+            BlockSize:                8,
+            ParallelizationParameter: 1,
+        },
     }
     var opts5 = pkcs8.Opts{
         Cipher:  pkcs8.AES256CBC,
         KDFOpts: pkcs8.DefaultPBKDF2Opts,
     }
 
     // 使用铺助函数生成设置
+    // use helper function to get options
     opts, err := pkcs8.MakeOpts("AES256CBC", "SHA256")
-    opts, err := pkcs8.MakeOpts(pkcs8.AES256CBC, SHA256)
+    opts, err := pkcs8.MakeOpts(pkcs8.AES256CBC, pkcs8.SHA256)
     opts, err := pkcs8.MakeOpts(pkcs8.SHA1AndDES)
 
 }
 ~~~
 
 
-#### 解密加密证书 / Decrypt key
+#### 解密已加密私钥证书 / Decrypt encrypted Private Key
 
 ~~~go
 import (
@@ -80,7 +94,7 @@ func main() {
 
     block, _ := pem.Decode(pemkey)
 
-    dekey, err := DecryptPEMBlock(block, password)
+    dekey, err := pkcs8.DecryptPEMBlock(block, password)
     if err != nil {
         // return error
     }

diff --git a/pkcs8/pbes1/cipher.go b/pkcs8/pbes1/cipher.go
@@ -8,7 +8,6 @@ import(
 // BmpStringZeroTerminated returns s encoded in UCS-2 with a zero terminator.
 var BmpStringZeroTerminated = bmp_string.BmpStringZeroTerminated
 
-// 别名
 type (
     Cipher = pbes1.Cipher
 )
@@ -17,14 +16,13 @@ var (
     AddCipher = pbes1.AddCipher
     GetCipher = pbes1.GetCipher
 
-    // 帮助函数
+    // helper funcions
     GetCipherFromName   = pbes1.GetCipherFromName
     CheckCipherFromName = pbes1.CheckCipherFromName
     GetCipherName       = pbes1.GetCipherName
     CheckCipher         = pbes1.CheckCipher
 )
 
-// 加密方式
 var (
     // pkcs12
     SHA1AndRC4_128 = pbes1.SHA1AndRC4_128
@@ -37,7 +35,7 @@ var (
     MD5AndCAST5   = pbes1.MD5AndCAST5
     SHAAndTwofish = pbes1.SHAAndTwofish
 
-    // PBES1
+    // pkcs8 - PBES1
     MD2AndDES     = pbes1.MD2AndDES
     MD2AndRC2_64  = pbes1.MD2AndRC2_64
     MD5AndDES     = pbes1.MD5AndDES

diff --git a/pkcs8/pbes1/pkcs8.go b/pkcs8/pbes1/pkcs8.go
@@ -11,15 +11,15 @@ import (
     "github.com/deatil/go-cryptobin/pkcs1"
 )
 
-// 结构体数据可以查看以下文档
+// struct info see:
 // RFC5208 at https://tools.ietf.org/html/rfc5208
 // RFC5958 at https://tools.ietf.org/html/rfc5958
 type encryptedPrivateKeyInfo struct {
     EncryptionAlgorithm pkix.AlgorithmIdentifier
     EncryptedData       []byte
 }
 
-// 加密 PKCS8 私钥
+// Encrypt PKCS8 Private Key
 func EncryptPKCS8PrivateKey(
     rand      io.Reader,
     blockType string,
@@ -68,7 +68,7 @@ func EncryptPKCS8PrivateKey(
     }, nil
 }
 
-// 解出 PKCS8 私钥
+// Decrypt PKCS8 Private Key
 func DecryptPKCS8PrivateKey(data, password []byte) ([]byte, error) {
     var pki encryptedPrivateKeyInfo
     if _, err := asn1.Unmarshal(data, &pki); err != nil {
@@ -98,7 +98,7 @@ func DecryptPKCS8PrivateKey(data, password []byte) ([]byte, error) {
     return decryptedKey, nil
 }
 
-// 加密 PKCS8 私钥，不处理密码
+// Encrypt PKCS8 Private Key and not format password
 func EncryptPKCS8Privatekey(
     rand      io.Reader,
     blockType string,
@@ -139,7 +139,7 @@ func EncryptPKCS8Privatekey(
     }, nil
 }
 
-// 解出 PKCS8 私钥，不处理密码
+// Decrypt PKCS8 Private Key and not format password
 func DecryptPKCS8Privatekey(data, password []byte) ([]byte, error) {
     var pki encryptedPrivateKeyInfo
     if _, err := asn1.Unmarshal(data, &pki); err != nil {
@@ -161,7 +161,7 @@ func DecryptPKCS8Privatekey(data, password []byte) ([]byte, error) {
     return decryptedKey, nil
 }
 
-// 解出 PEM 块
+// Decrypt PEM Block
 func DecryptPEMBlock(block *pem.Block, password []byte) ([]byte, error) {
     if block.Headers["Proc-Type"] == "4,ENCRYPTED" {
         return pkcs1.DecryptPEMBlock(block, password)

diff --git a/pkcs8/pbes2/cipher.go b/pkcs8/pbes2/cipher.go
@@ -4,7 +4,6 @@ import(
     "github.com/deatil/go-cryptobin/pkcs/pbes2"
 )
 
-// 别名
 type (
     Cipher = pbes2.Cipher
 )
@@ -13,14 +12,13 @@ var (
     AddCipher = pbes2.AddCipher
     GetCipher = pbes2.GetCipher
 
-    // 帮助函数
+    // helper funcions
     GetCipherFromName   = pbes2.GetCipherFromName
     CheckCipherFromName = pbes2.CheckCipherFromName
     GetCipherName       = pbes2.GetCipherName
     CheckCipher         = pbes2.CheckCipher
 )
 
-// 加密方式
 var (
     DESCBC     = pbes2.DESCBC
     DESEDE3CBC = pbes2.DESEDE3CBC

diff --git a/pkcs8/pbes2/helper.go b/pkcs8/pbes2/helper.go
@@ -1,7 +1,7 @@
 package pbes2
 
-// hash 列表
-var HashMap = map[string]Hash{
+// hash map
+var hashMap = map[string]Hash{
     "MD5":             MD5,
     "SHA1":            SHA1,
     "SHA224":          SHA224,
@@ -15,16 +15,16 @@ var HashMap = map[string]Hash{
     "GOST34112012512": GOST34112012512,
 }
 
-// 获取 hash 类型
+// Get Hash From hash Name
 func GetHashFromName(name string) Hash {
-    if data, ok := HashMap[name]; ok {
+    if data, ok := hashMap[name]; ok {
         return data
     }
 
-    return HashMap["SHA1"]
+    return hashMap["SHA1"]
 }
 
-// 生成设置
+// make options
 func MakeOpts(opts ...any) (Opts, error) {
     if len(opts) == 0 {
         return DefaultOpts, nil
@@ -93,7 +93,7 @@ func MakeOpts(opts ...any) (Opts, error) {
     return DefaultOpts, nil
 }
 
-// 解析生成设置
+// parse and make options
 func ParseOpts(opts ...any) (Opts, error) {
     return MakeOpts(opts...)
 }
diff --git a/pkcs8/pbes2/kdf.go b/pkcs8/pbes2/kdf.go
@@ -4,9 +4,9 @@ import (
     "encoding/asn1"
 )
 
-// KDF 设置接口
+// KDF options interface
 type KDFOpts interface {
-    // 随机数大小
+    // Salt Size
     GetSaltSize() int
 
     // oid
@@ -15,25 +15,24 @@ type KDFOpts interface {
     // PBES oid
     PBESOID() asn1.ObjectIdentifier
 
-    // 设置是否有 KeyLength
+    // with HasKeyLength option
     WithHasKeyLength(hasKeyLength bool) KDFOpts
 
-    // 生成密钥
+    // DeriveKey
     DeriveKey(password, salt []byte, size int) (key []byte, params KDFParameters, err error)
 }
 
-// 数据接口
+// KDFParameters
 type KDFParameters interface {
     // PBES oid
     PBESOID() asn1.ObjectIdentifier
 
-    // 生成密钥
+    // DeriveKey
     DeriveKey(password []byte, size int) (key []byte, err error)
 }
 
 var kdfs = make(map[string]func() KDFParameters)
 
-// 添加 kdf 方式
 // add kdf type
 func AddKDF(oid asn1.ObjectIdentifier, params func() KDFParameters) {
     kdfs[oid.String()] = params

diff --git a/pkcs8/pbes2/kdf_pbkdf2.go b/pkcs8/pbes2/kdf_pbkdf2.go
@@ -36,7 +36,7 @@ const (
 )
 
 var (
-    // 默认 hash
+    // default hash
     DefaultHash = SHA1
 )
 
@@ -45,7 +45,7 @@ var (
     oidPKCS5       = asn1.ObjectIdentifier{1, 2, 840, 113549, 1, 5}
     oidPKCS5PBKDF2 = asn1.ObjectIdentifier{1, 2, 840, 113549, 1, 5, 12}
 
-    // hash 方式
+    // hash oid
     oidDigestAlgorithm    = asn1.ObjectIdentifier{1, 2, 840, 113549, 2}
     oidHMACWithMD5        = asn1.ObjectIdentifier{1, 2, 840, 113549, 2, 6}
     oidHMACWithSHA1       = asn1.ObjectIdentifier{1, 2, 840, 113549, 2, 7}
@@ -61,7 +61,7 @@ var (
     oidHMACWithGOST34112012512 = asn1.ObjectIdentifier{1, 2, 643, 7, 1, 1, 4, 2}
 )
 
-// 返回使用的 Hash 方式
+// get Hash func
 func prfByOID(oid asn1.ObjectIdentifier) (func() hash.Hash, error) {
     switch {
         case oid.Equal(oidHMACWithMD5):
@@ -91,7 +91,7 @@ func prfByOID(oid asn1.ObjectIdentifier) (func() hash.Hash, error) {
     return nil, fmt.Errorf("go-cryptobin/pkcs8: unsupported hash (OID: %s)", oid)
 }
 
-// 返回使用的 Hash 对应的 asn1
+// get hash oid
 func oidByHash(h Hash) (asn1.ObjectIdentifier, error) {
     switch h {
         case MD5:
@@ -121,7 +121,7 @@ func oidByHash(h Hash) (asn1.ObjectIdentifier, error) {
     return nil, errors.New("go-cryptobin/pkcs8: unsupported hash function")
 }
 
-// pbkdf2 数据，作为包装
+// pbkdf2 params
 type pbkdf2Params struct {
     Salt           []byte
     IterationCount int
@@ -137,7 +137,7 @@ func (this pbkdf2Params) DeriveKey(password []byte, size int) (key []byte, err e
     var alg asn1.ObjectIdentifier
     var h func() hash.Hash
 
-    // 如果有自定义长度，使用自定义长度
+    // size use it if KeyLength > 0
     if this.KeyLength > 0 {
         size = this.KeyLength
     }
@@ -164,7 +164,7 @@ func (this pbkdf2Params) DeriveKey(password []byte, size int) (key []byte, err e
     return
 }
 
-// PBKDF2 配置
+// PBKDF2 options
 type PBKDF2Opts struct {
     hasKeyLength   bool
     SaltSize       int
@@ -226,7 +226,7 @@ func (this PBKDF2Opts) DeriveKey(password, salt []byte, size int) (key []byte, p
         PrfParam:       prfParam,
     }
 
-    // 设置 KeyLength
+    // set KeyLength
     if this.hasKeyLength {
         parameters.KeyLength = size
     }

diff --git a/pkcs8/pbes2/kdf_scrypt.go b/pkcs8/pbes2/kdf_scrypt.go
@@ -10,7 +10,7 @@ var (
     oidScrypt = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 11591, 4, 11}
 )
 
-// scrypt 数据
+// scrypt params
 type scryptParams struct {
     Salt                     []byte
     CostParameter            int
@@ -36,7 +36,7 @@ func (this scryptParams) DeriveKey(password []byte, size int) (key []byte, err e
     )
 }
 
-// ScryptOpts 设置
+// Scrypt options
 type ScryptOpts struct {
     hasKeyLength             bool
     SaltSize                 int