keyChain & identity添加部分注释

src/main/java/minsecurity/identity/Identity.java

@@ -5,12 +5,11 @@ import com.fasterxml.jackson.databind.ObjectMapper;
 import minsecurity.Common;
 import minsecurity.certificate.cert.CertException;
 import minsecurity.certificate.cert.Certificate;
-import minsecurity.crypto.KeyUtils;
-import minsecurity.crypto.PrivateKeyInterface;
-import minsecurity.crypto.PublicKeyInterface;
-import minsecurity.crypto.SM4;
+import minsecurity.crypto.*;
+import minsecurity.crypto.sm2.SM2Exception;
 import minsecurity.crypto.sm2.SM2PrivateKey;
 import minsecurity.crypto.sm2.SM2PublicKey;
+import org.bouncycastle.crypto.AsymmetricCipherKeyPair;
 import org.bouncycastle.crypto.CryptoException;
 import org.bouncycastle.crypto.InvalidCipherTextException;
 import org.bouncycastle.pqc.math.linearalgebra.ByteUtils;
@@ -60,12 +59,36 @@ public class Identity {
         IsDefault = isDefault;
     }
 
+    /**
+     * 参数中不包含PrikeyRawByte
+     * @author hongyu guo
+     * @date 2021/3/12
+    **/
+    public Identity(String name, KeyParam keyParam,
+                    PrivateKeyInterface prikey, PublicKeyInterface pubkey,
+                    String passwd, Certificate cert,
+                    boolean isDefault) {
+        Name = name;
+        KeyParam = keyParam;
+        Prikey = prikey;
+        Pubkey = pubkey;
+        Passwd = passwd;
+        Cert = cert;
+        IsDefault = isDefault;
+    }
+
 
     public Identity(){}
 
 
-
-    public byte[] sign(byte[] digest) throws CryptoException {
+    /***
+     * 使用identity的私钥对数据进行签名
+     * @param content 被签名数据
+     * @return byte[] 签名成功时返回摘要, 失败时返回null
+     * @author hongyu guo
+     * @date 2021/3/12
+    **/
+    public byte[] sign(byte[] content) throws CryptoException {
         if(this.Prikey == null)
             return null;
         switch (this.KeyParam.PublicKeyAlgorithm){
@@ -73,7 +96,7 @@ public class Identity {
                 SM2PrivateKey sm2PrivateKey = (SM2PrivateKey) this.Prikey;
             switch (this.KeyParam.SignatureAlgorithm){
                 case Common.SM3withSM2:
-                    return sm2PrivateKey.sign(digest);
+                    return sm2PrivateKey.sign(content);
                 default:
                     return null;
             }
@@ -82,9 +105,24 @@ public class Identity {
         }
     }
 
-    public boolean verify(byte[] msg, byte[] digest) {
+    /***
+     * 使用identity的公钥进行验签
+     * 目前支持使用sm2公钥进行验签
+     * @param msg
+	 * @param digest
+     * @return boolean
+     * @throws IdentityException
+     * @throws AsymKeyException
+     * @author hongyu guo
+     * @date 2021/3/12
+    **/
+    public boolean verify(byte[] msg, byte[] digest) throws IdentityException, AsymKeyException {
+        if(msg == null)
+            throw new IdentityException("source data should not be null");
+        if(digest == null)
+            throw new IdentityException("digest should not be null");
         if(this.Pubkey == null)
-            return false;
+            throw new IdentityException("pubkey in identity is null");
         switch (this.KeyParam.PublicKeyAlgorithm){
             case Common.SM2:
                 SM2PublicKey sm2PublicKey = (SM2PublicKey) this.Pubkey;
@@ -92,26 +130,57 @@ public class Identity {
                     case Common.SM3withSM2:
                         return sm2PublicKey.verify(msg, digest);
                     default:
-                        return false;
+                        throw new AsymKeyException("unknown signatureAlgorithm");
                 }
             default:
-                return false;
+                throw new AsymKeyException("unknown asymmetric algorithm");
         }
     }
 
-    public byte[] decrypt(byte[] cipher) throws InvalidCipherTextException {
+    /**
+     * 使用identity的密钥对密文进行解密, 返回解密数据.
+     * identity中的私钥为空或密文有误时时将抛出异常
+     * @param cipher 密文
+     * @return byte[]
+     * @throws IdentityException
+     * @throws InvalidCipherTextException
+     * @author hongyu guo
+     * @date 2021/3/12
+    **/
+    public byte[] decrypt(byte[] cipher) throws InvalidCipherTextException, IdentityException {
         if(this.Prikey == null)
-            return null;
+            throw new IdentityException("prikey in identity should not be null");
         return this.Prikey.decrypt(cipher);
     }
-
-    public byte[] encrypt(byte[] content) throws InvalidCipherTextException {
+    /**
+     * 使用identity的密钥对密文进行加密, 返回加密数据.
+     * identity中的公钥为空或原文有误时时将抛出异常
+     * @param content 原文
+     * @return byte[]
+     * @throws IdentityException
+     * @throws InvalidCipherTextException
+     * @author hongyu guo
+     * @date 2021/3/12
+    **/
+    public byte[] encrypt(byte[] content) throws InvalidCipherTextException, IdentityException {
         if(this.Pubkey == null)
-            return null;
+            throw new IdentityException("public in identity should not be null");
         return this.Pubkey.encrypt(content);
     }
 
-    public byte[] dump(String passwd) throws NoSuchPaddingException, InvalidAlgorithmParameterException, CertException, IllegalBlockSizeException, BadPaddingException, NoSuchAlgorithmException, NoSuchProviderException, InvalidKeyException, JsonProcessingException {
+    /**
+     * 对Identity进行序列化, 如果为passwd不为空, 会对序列化后的代码进行SM4对称加密,
+     * 最后返回base64编码后的序列化结果
+     * @param passwd 密码, 不为空(null || "")时进行加密
+     * @return byte[]
+     * @throws IdentityException ...
+     * @author hongyu guo
+     * @date 2021/3/12
+    **/
+    public byte[] dump(String passwd)
+            throws NoSuchPaddingException, InvalidAlgorithmParameterException, CertException,
+                   IllegalBlockSizeException, BadPaddingException, NoSuchAlgorithmException,
+                   NoSuchProviderException, InvalidKeyException, JsonProcessingException, IdentityException {
         ObjectMapper mapper = new ObjectMapper();
         InnerIdentity innerIdentity = IdentityUtil.parseIdentityToInner(this);
         byte[] bytesOfInnerIdentity =  mapper.writeValueAsBytes(innerIdentity);
@@ -124,11 +193,20 @@ public class Identity {
         return Base64.getEncoder().encode(bytesOfInnerIdentity);
     }
 
-    public static Identity load(byte[] data, String passwd)
+    /**
+     * 将序列化的identity byte数组反序列化为identity实例
+     * @param bytesOfSerialization 已经序列化的identity
+	 * @param passwd 密码, 不为空(null || "")时进行解密
+     * @return minsecurity.identity.Identity
+     * @throws CertException
+     * @author hongyu guo
+     * @date 2021/3/12
+    **/
+    public static Identity load(byte[] bytesOfSerialization, String passwd)
             throws BadPaddingException, NoSuchPaddingException, InvalidAlgorithmParameterException,
             NoSuchAlgorithmException, IllegalBlockSizeException, NoSuchProviderException,
             InvalidKeyException, CertException {
-        byte[] bytesOfIdentity = Base64.getDecoder().decode(data);
+        byte[] bytesOfIdentity = Base64.getDecoder().decode(bytesOfSerialization);
         byte[] plain;
         if(passwd != null && passwd.length() != 0){
             byte[] sm4Key = KeyUtils.get16bytePasswd(passwd.getBytes());

src/main/java/minsecurity/identity/IdentityUtil.java

@@ -24,24 +24,43 @@ import java.security.NoSuchProviderException;
  * @Copyright: MIN-Group；国家重大科技基础设施——未来网络北大实验室；深圳市信息论与未来网络重点实验室
  */
 public class IdentityUtil {
+    /**
+     * 将identity转化为内部结构(innerIdentity), 便于编码
+     * identity的公私钥以及证书都不能为空
+     * @param identity
+     * @return minsecurity.identity.InnerIdentity
+     * @throws CertException ...
+     * @author hongyu guo
+     * @date 2021/3/12
+    **/
     public static InnerIdentity parseIdentityToInner(Identity identity)
             throws NoSuchPaddingException, InvalidKeyException, CertException,
             IllegalBlockSizeException, BadPaddingException, NoSuchAlgorithmException,
-            NoSuchProviderException, InvalidAlgorithmParameterException {
+            NoSuchProviderException, InvalidAlgorithmParameterException, IdentityException {
+        if(identity.getPubkey() == null)
+            throw new IdentityException("public key in identity is null");
+        if(identity.getPrikey() == null)
+            throw new IdentityException("private key in identity is null");
+        if(identity.getCert() == null)
+            throw new IdentityException("certificate in identity is null");
         InnerIdentity innerIdentity = new InnerIdentity();
         innerIdentity.setName(identity.getName());
         innerIdentity.setKeyParam(identity.getKeyParam());
-        if(identity.getPrikey() != null){
-            innerIdentity.setPrikey(identity.getPrikey().getBytes());
-        }
-        if(identity.getPubkey() != null){
-            innerIdentity.setPubkey(identity.getPubkey().getBytes());
-        }
+        innerIdentity.setPrikey(identity.getPrikey().getBytes());
+        innerIdentity.setPubkey(identity.getPubkey().getBytes());
         innerIdentity.setPasswd(identity.getPasswd());
         innerIdentity.setCert(CertUtils.toPem(identity.getCert(), identity.getPasswd().getBytes(), Common.SM4CBC));
+
         return innerIdentity;
     }
 
+    /**
+     * @param innerIdentity
+     * @return minsecurity.identity.Identity
+     * @throws CertException ...
+     * @author hongyu guo
+     * @date 2021/3/12
+    **/
     public static Identity parseInnerToIdentity(InnerIdentity innerIdentity)
             throws BadPaddingException, InvalidKeyException, CertException,
             NoSuchPaddingException, NoSuchAlgorithmException, NoSuchProviderException,

src/main/java/minsecurity/identity/InnerIdentity.java

@@ -1,13 +1,10 @@
 package minsecurity.identity;
 
-import minsecurity.certificate.cert.Certificate;
 import org.bouncycastle.pqc.math.linearalgebra.ByteUtils;
 
-import java.util.Arrays;
-
 /*
  * @Author: hongyu guo
- * @Description:
+ * @Description: 将公私钥转化为byte数组格式、 证书转化为pem格式, 方便对identity进行序列化
  * @Version: 1.0.0
  * @Date: 09:41 2021/03/09
  * @Copyright: MIN-Group；国家重大科技基础设施——未来网络北大实验室；深圳市信息论与未来网络重点实验室