新增接口文档，增加国密签名错误返回

2072eb1e · pengjun · d2271f7a · 2072eb1e · 2072eb1e · 2072eb1e
Commit 2072eb1e authored Sep 18, 2020 by pengjun
Showing with 237 additions and 191 deletions

README.md README.md +28 -184

crypto_test.go crypto/crypto_test.go +1 -1

sm2.go crypto/gm/sm2.go +5 -5

transaction.go transaction.go +4 -1

接口文档.md 接口文档.md +199 -0

No files found.
--- a/README.md
+++ b/README.md
 # chain33-sdk-go
 chain33 sdk golang

-### 接口文档
+## 版本
+golang1.13 or latest

-#### 1. 账户相关
-#### 1.1 创建账户
+## 安装

-**函数原型**
-```
-NewAccount(signType string) (*Account, error)
-```
-
-**请求参数**
-
-|参数|类型|是否必填|说明|
-|----|----|----|----|
-|signType|string|是|签名类型,支持"secp256k1",默认"secp256k1"|
-
-**返回字段：**
-
-|返回字段|字段类型|说明|
-|----|----|----|
-|Account|PrivateKey  []byte | 私钥
-|	    |PublicKey   []byte|  公钥
-|       |Address     string | 地址
-|       |SignType    string|  签名类型
-
-#### 1.2 交易签名
-
-**函数原型**
-```
-SignRawTransaction(raw string, privateKey string, signType string) (string, error)
-```
-
-**请求参数**
-
-|参数|类型|是否必填|说明|
-|----|----|----|----|
-|raw|string|是|原始交易数据|
-|privateKey|string|是|私钥|
-|signType|string|是|签名类型|
-
-**返回字段：**
-
-|返回字段|字段类型|说明|
-|----|----|----|
-|result|string | 签名后的交易
-
-#### 2. 代理重加密
-#### 2.1 生成对称加密秘钥
-
-**函数原型**
-```
-GenerateEncryptKey(pubOwner []byte) ([]byte, string, string)
-```
-**请求参数**
-
-|参数|类型|是否必填|说明|
-|----|----|----|----|
-|pubOwner|[]byte|是|加密用户非对称秘钥公钥|
-
-**返回字段：**
-
-|返回字段|字段类型|说明|
-|----|----|----|
-|key |[]byte | 对称加密秘钥
-|pub_r |string | 随机公钥r，用于重加密授权
-|pub_u |string | 随机公钥u，用于重加密授权
-
-#### 2.2 生成重加密秘钥分片
-
-**函数原型**
-```
-GenerateKeyFragments(privOwner []byte, pubRecipient []byte, numSplit, threshold int) ([]*KFrag, error) 
-```
-**请求参数**
-
-|参数|类型|是否必填|说明|
-|----|----|----|----|
-|privOwner |[]byte|是|共享用户私钥|
-|pubRecipient |[]byte|是|授权用户公钥|
-|numSplit |int |是|秘钥分片数|
-|threshold |int|是|最小秘钥分片重组阈值，不得大于numSplit|
-
-**返回字段：**
+```text
+//开启mod功能
+export GO111MODULE=on

-|返回字段|字段类型|说明|
-|----|----|----|
-|KFrag |Random    string  | 随机数，每个分片不同
-| |Value     string | 重加密证明，每个分片不同
-| |PrecurPub string | 随机公钥，所有分片相同
-|err  |error | 错误返回
-
-#### 2.3 重组重加密秘钥分片
-
-**函数原型**
+//国内用户需要导入阿里云代理，用于下载依赖包
+export GOPROXY=https://mirrors.aliyun.com/goproxy
 ```
-AssembleReencryptFragment(privRecipient []byte, reKeyFrags []*ReKeyFrag) ([]byte, error)
-```
-**请求参数**
-
-|参数|类型|是否必填|说明|
-|----|----|----|----|
-|privRecipient |[]byte|是|授权用户私钥|
-|reKeyFrags |ReKeyFrag|是|重加密秘钥分片，从各个重加密节点获取|
-```
-type ReKeyFrag struct {
-	ReKeyR    string // 重加密证明R
-	ReKeyU    string // 重加密证明U
-	Random    string // 随机数，每个分片不同
-	PrecurPub string // 随机公钥，所有分片相同
-}
-```
-
-**返回字段：**

-|返回字段|字段类型|说明|
-|----|----|----|
-|key |[]byte  | 重组后的对称秘钥
-|err  |error | 错误返回
+## 使用

-#### 3. RPC客户端
-#### 3.1 创建jsonRPC客户端
-
-**函数原型**
-```
-NewJSONClient(prefix, url string) (*JSONClient, error)
+### RPC客户端
+通过jclient调用rpc接口发送交易和查询交易
+```go
+client, err := client.NewJSONClient(name, server)
+client.SendTransaction(signedTx) 
 ```
-**请求参数**
-
-|参数|类型|是否必填|说明|
-|----|----|----|----|
-|prefix |string|是|前缀|
-|url |string|是|rpc服务端连接|
-
-**返回字段：**

-|返回字段|字段类型|说明|
-|----|----|----|
-|JSONClient |JSONClient | 客户端对象
-|err  |error | 错误返回
+### 加解密
+crypto包实现了常用的加解密算法，签名算法，sha256哈希算法，密码生成和区块链地址生成，可通过crypto包直接调用。
+```go
+// 国密签名
+sig, _ := crypto.gm.SM2Sign(priv, msg,nil)

-#### 3.2 rpc调用
-
-**函数原型**
-```
-JSONClient.Call(method string, params, resp interface{}) error
-```
-**请求参数**
-
-|参数|类型|是否必填|说明|
-|----|----|----|----|
-|method |string|是|rpc调用方法|
-|params |interface|是|调用方法对应的参数|
-|resp |interface|是|调用方法对应的返回值|
-
-**返回字段：**
-
-|返回字段|字段类型|说明|
-|----|----|----|
-|err  |error | 错误返回
-
-#### 3.3 发送交易
-
-**函数原型**
-```
-JSONClient.SendTransaction(signedTx string) (string, error)
-```
-**请求参数**
-
-|参数|类型|是否必填|说明|
-|----|----|----|----|
-|signedTx |string|是|已签名的交易|
-
-**返回字段：**
-
-|返回字段|字段类型|说明|
-|----|----|----|
-|string  |string | 返回哈希
-|err  |error | 错误返回
-
-#### 3.4 交易查询
-
-**函数原型**
-```
-JSONClient.QueryTransaction(hash string) (*TransactionDetail, error)
+// 国密验签
+result := crypto.gm.SM2Verify(pub, msg, nil, sig)
 ```
-**请求参数**

-|参数|类型|是否必填|说明|
-|----|----|----|----|
-|hash |string|是|交易哈希|
+### 代理重加密
+代理重加密密钥生成和本地加解密

-**返回字段：**
+### 存证接口
+创建存证合约原始交易

-|返回字段|字段类型|说明|
-|----|----|----|
-|TransactionDetail  |TransactionDetail | 交易详情
-|err  |error | 错误返回
+## 接口文档
+[chain33-sdk-go API](./接口文档.md)
\ No newline at end of file
--- a/crypto/crypto_test.go
+++ b/crypto/crypto_test.go
@@ -48,7 +48,7 @@ func TestSM2(t *testing.T) {

 	msg := []byte("sign test")

-	sig := gm.SM2Sign(priv, msg,nil)
+	sig, _ := gm.SM2Sign(priv, msg,nil)
 	fmt.Printf("sig = %x\n", sig)

 	result := gm.SM2Verify(pub, msg, nil, sig)

--- a/crypto/gm/sm2.go
+++ b/crypto/gm/sm2.go
@@ -119,7 +119,7 @@ func GenerateKey() ([]byte, []byte) {
 	return SerializePrivateKey(priv), SerializePublicKey(pub)
 }

-func SM2Sign(privateKey []byte, msg []byte, uid []byte) []byte {
+func SM2Sign(privateKey []byte, msg []byte, uid []byte) ([]byte, error) {
 	if uid == nil {
 		uid = DefaultUID
 	}
@@ -127,13 +127,13 @@ func SM2Sign(privateKey []byte, msg []byte, uid []byte) []byte {
 	priv, _ := PrivKeyFromBytes(sm2.P256Sm2(), privateKey)
 	r, s, err := sm2.Sm2Sign(priv, msg, uid)
 	if err != nil {
-		return nil
+		return nil, err
 	}

-	return SerializeSignature(r, s)
+	return SerializeSignature(r, s), nil
 }

-func SM2Verify(publicKey []byte, msg []byte, uid []byte, sig []byte,) bool {
+func SM2Verify(publicKey []byte, msg []byte, uid []byte, sig []byte) bool {
 	if uid == nil {
 		uid = DefaultUID
 	}
@@ -141,7 +141,7 @@ func SM2Verify(publicKey []byte, msg []byte, uid []byte, sig []byte,) bool {
 	pub := parsePubKey(publicKey[:])
 	r, s, err := DeserializeSignature(sig)
 	if err != nil {
-		fmt.Errorf("unmarshal sign failed")
+		fmt.Errorf("unmarshal sign failed:"+err.Error())
 		return false
 	}


--- a/transaction.go
+++ b/transaction.go
@@ -28,7 +28,10 @@ func Sign(tx *Transaction, privateKey []byte, signType string) (*Transaction, er
 		pub := gm.PubKeyFromPrivate(privateKey)

 		data := Encode(tx)
-		signature := gm.SM2Sign(data, privateKey, nil)
+		signature, err := gm.SM2Sign(data, privateKey, nil)
+		if err != nil {
+			return nil, err
+		}
 		tx.Signature = &Signature{
 			Ty:        3,
 			Pubkey:    pub,

--- a/接口文档.md
+++ b/接口文档.md
+# chain33-sdk-go
+# chain33-sdk-go
+### 接口文档
+
+#### 1. 账户相关
+#### 1.1 创建账户
+
+**函数原型**
+```
+NewAccount(signType string) (*Account, error)
+```
+
+**请求参数**
+
+|参数|类型|是否必填|说明|
+|----|----|----|----|
+|signType|string|是|签名类型,支持"secp256k1",默认"secp256k1"|
+
+**返回字段：**
+
+|返回字段|字段类型|说明|
+|----|----|----|
+|Account|PrivateKey  []byte | 私钥
+|	    |PublicKey   []byte|  公钥
+|       |Address     string | 地址
+|       |SignType    string|  签名类型
+
+#### 1.2 交易签名
+
+**函数原型**
+```
+SignRawTransaction(raw string, privateKey string, signType string) (string, error)
+```
+
+**请求参数**
+
+|参数|类型|是否必填|说明|
+|----|----|----|----|
+|raw|string|是|原始交易数据|
+|privateKey|string|是|私钥|
+|signType|string|是|签名类型|
+
+**返回字段：**
+
+|返回字段|字段类型|说明|
+|----|----|----|
+|result|string | 签名后的交易
+
+#### 2. 代理重加密
+#### 2.1 生成对称加密秘钥
+
+**函数原型**
+```
+GenerateEncryptKey(pubOwner []byte) ([]byte, string, string)
+```
+**请求参数**
+
+|参数|类型|是否必填|说明|
+|----|----|----|----|
+|pubOwner|[]byte|是|加密用户非对称秘钥公钥|
+
+**返回字段：**
+
+|返回字段|字段类型|说明|
+|----|----|----|
+|key |[]byte | 对称加密秘钥
+|pub_r |string | 随机公钥r，用于重加密授权
+|pub_u |string | 随机公钥u，用于重加密授权
+
+#### 2.2 生成重加密秘钥分片
+
+**函数原型**
+```
+GenerateKeyFragments(privOwner []byte, pubRecipient []byte, numSplit, threshold int) ([]*KFrag, error) 
+```
+**请求参数**
+
+|参数|类型|是否必填|说明|
+|----|----|----|----|
+|privOwner |[]byte|是|共享用户私钥|
+|pubRecipient |[]byte|是|授权用户公钥|
+|numSplit |int |是|秘钥分片数|
+|threshold |int|是|最小秘钥分片重组阈值，不得大于numSplit|
+
+**返回字段：**
+
+|返回字段|字段类型|说明|
+|----|----|----|
+|KFrag |Random    string  | 随机数，每个分片不同
+| |Value     string | 重加密证明，每个分片不同
+| |PrecurPub string | 随机公钥，所有分片相同
+|err  |error | 错误返回
+
+#### 2.3 重组重加密秘钥分片
+
+**函数原型**
+```
+AssembleReencryptFragment(privRecipient []byte, reKeyFrags []*ReKeyFrag) ([]byte, error)
+```
+**请求参数**
+
+|参数|类型|是否必填|说明|
+|----|----|----|----|
+|privRecipient |[]byte|是|授权用户私钥|
+|reKeyFrags |ReKeyFrag|是|重加密秘钥分片，从各个重加密节点获取|
+```
+type ReKeyFrag struct {
+	ReKeyR    string // 重加密证明R
+	ReKeyU    string // 重加密证明U
+	Random    string // 随机数，每个分片不同
+	PrecurPub string // 随机公钥，所有分片相同
+}
+```
+
+**返回字段：**
+
+|返回字段|字段类型|说明|
+|----|----|----|
+|key |[]byte  | 重组后的对称秘钥
+|err  |error | 错误返回
+
+#### 3. RPC客户端
+#### 3.1 创建jsonRPC客户端
+
+**函数原型**
+```
+NewJSONClient(prefix, url string) (*JSONClient, error)
+```
+**请求参数**
+
+|参数|类型|是否必填|说明|
+|----|----|----|----|
+|prefix |string|是|前缀|
+|url |string|是|rpc服务端连接|
+
+**返回字段：**
+
+|返回字段|字段类型|说明|
+|----|----|----|
+|JSONClient |JSONClient | 客户端对象
+|err  |error | 错误返回
+
+#### 3.2 rpc调用
+
+**函数原型**
+```
+JSONClient.Call(method string, params, resp interface{}) error
+```
+**请求参数**
+
+|参数|类型|是否必填|说明|
+|----|----|----|----|
+|method |string|是|rpc调用方法|
+|params |interface|是|调用方法对应的参数|
+|resp |interface|是|调用方法对应的返回值|
+
+**返回字段：**
+
+|返回字段|字段类型|说明|
+|----|----|----|
+|err  |error | 错误返回
+
+#### 3.3 发送交易
+
+**函数原型**
+```
+JSONClient.SendTransaction(signedTx string) (string, error)
+```
+**请求参数**
+
+|参数|类型|是否必填|说明|
+|----|----|----|----|
+|signedTx |string|是|已签名的交易|
+
+**返回字段：**
+
+|返回字段|字段类型|说明|
+|----|----|----|
+|string  |string | 返回哈希
+|err  |error | 错误返回
+
+#### 3.4 交易查询
+
+**函数原型**
+```
+JSONClient.QueryTransaction(hash string) (*TransactionDetail, error)
+```
+**请求参数**
+
+|参数|类型|是否必填|说明|
+|----|----|----|----|
+|hash |string|是|交易哈希|
+
+**返回字段：**
+
+|返回字段|字段类型|说明|
+|----|----|----|
+|TransactionDetail  |TransactionDetail | 交易详情
+|err  |error | 错误返回