readme.md · Codey/PCNGateway-Go-SDK

# BSN PCN Gateway SDK example
Normally，if an off-BSN system wants to communicate with a service (DApp) on the BSN, it has to connect to the public city nodes (PCN) gateway. In this example, we privode a SDK (Software Development Kit) which includes the functions for data transaction and querying. By using this SDK, developer can quickly implement an off-BSN application to call the PCN Gateway. Inside the SDK, we provide PCN gateway API encapsulation which you can use to implement the transaction querying, transaction interface calling, generate public key and private key locally, register user certificate, generate certificate signature, encrypt and decrypt data, etc.

## Go SDK

## SDK in csharp

## framework and key support

>Currently, SDK in Go supports all framework and key combination applications on the official website

The details are as follows：

<table>
<tr>
<th rowspan="2">framework</th>
<th colspan="3" >public key upload mode</th>
<th colspan="3" >key trust mode</th>
</tr>
<tr>
<th>secp256r1</th>
<th>secp256k1</th>
<th>SM2</th>
<th>secp256r1</th>
<th>secp256k1</th>
<th>SM2</th>
</tr>
<tr>
<td>Fabric</td>
<td>√</td>
<td></td>
<td>√</td>
<td>√</td>
<td></td>
<td>√</td>
</tr>
<tr>
<td>FISCO-BCOS</td>
<td></td>
<td>√</td>
<td>√</td>
<td></td>
<td>√</td>
<td>√</td>
</tr>
<tr>
<td>XuperChain</td>
<td></td>
<td></td>
<td>√</td>
<td></td>
<td></td>
<td>√</td>
</tr>	
<tr>
<td>Cita</td>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
<td>√</td>
</tr>
</table>

* Fabric framework application uses two modes: secret key escrow and secret key upload of secp256r1 and SM2;

* Fisco-bcos framework uses two modes: secret key hosting and secret key uploading of secp256k1 and SM2;

* Xuperchain framework uses two modes of SM2 secret key hosting and secret key uploading;

* CITA framework application only supports SM2 key escrow mode;

### 1. Preparation before

#### Application parameters
> Application parameters are some parameters that the user obtains on the application details page after successfully participating in the application, or are set locally, including the following parameters
 * __Node gateway interface address:__ The address of the node gateway of the participating city node
 * __User ID:__ User ID
 * __Application No.:__ Number of participating applications
 * __Application public key:__ Application public key of the node gateway downloaded after successful user participation
 * __Application private key:__ The application public key generated by the BSN after the successful participation of the managed type application, and the non-hosting application is the private key corresponding to the public key uploaded when participating in the application
 * __Https certificate:__ https certificate used when requesting https gateway interface

#### Local parameters
 * __Certificate storage directory:__ Directory used to store user private keys and certificates generated by non-hosting applications when invoking user certificate registration

### 2. Ready to call

#### Import sdk package
The following packages need to be introduced
```
import (
    "github.com/BSNDA/PCNGateway-Go-SDK/pkg/client/fabric"
    "github.com/BSNDA/PCNGateway-Go-SDK/pkg/core/config"
	)
```
#### Initialize config
You can initialize an object that stores all configurations. These specific configuration information should be configured or read by the caller according to their respective projects, and then passed in when called. 
In the 'init' method of config, the operation to obtain the basic information of an app is implemented. Please do not call this operation frequently. This interface will occupy your TPS and traffic, and can be used when the project uses a static object to store 'config' when needed. 
It is worth noting that when configuring the certificate, the applied Certificate (i.e. the certificate used for signing and verification) is the direct transfer of the certificate content, while the HTTPS certificate is the file path
of the certificate to the project root directory (this is consistent with the previous example code).
```
	api:="" //Node gateway address
	userCode:="" //User No.
	appCode :="" //Application No.
	puk :="" //Application public key
	prk :="" //Application private key
	mspDir:="" //Certificate storage directory
	cert :="" //Certificate
	config,err :=config.NewConfig(api, userCode, appCode, puk, prk, mspDir, cert )
	if err !=nil{
	    log.Fatal(err)
	}
```
#### Initialize client
Using the generated configuration object, call the following code to create a Client object to call the node gateway
```
	client,err :=fabric.InitFabricClient(config)
	if err !=nil{
	    log.Fatal(err)
	}
```

####   Call interface
Each gateway interface has encapsulated request and response parameter objects, which can be directly called only by assigning values. The operations of signature and signature verification have been implemented in the method.
The following is the calling operation of the registered sub-users, other similar.
```
	req :=user.RegisterReqDataBody{
	    Name:"abc",
	    Secret:"123456",
 	}
	
 	res,err :=client.RegisterUser(req)
 	if err !=nil{
	    log.Fatal(err)
 	}
	
 	if res.Header.Code != 0{
	    log.Fatal( res.Header.Msg)
 	}
```

### 3.Some other notes

#### Description of user identity certificate of non-hosting application
Because non-hosting applications need user certificates generated by users themselves when they call the gateway for transactions, the process is: Register Users - > Register User Certificates. In the operation of registering user certificate, a pair of secret keys will be generated locally, and then the CSR file (certificate application file) of the certificate will be exported through the secret key, 
and the user certificate registration interface will be called to obtain a valid certificate. Only by using the certificate can the transaction be initiated normally in the transaction processing interface of the hosted application.
It should be noted that when setting the CN in the CSR file, it is not directly the registered Name, but the name stitched by Name and AppCode in the format of `Name @ AppCode`
This operation is implemented in the `EnrollUser` method of` FabricClient`.

__The storage of the certificate __ is realized by `keystore` and` userstore` in `util`. This method only stores the certificate in the form of a local file, if 
other forms of certificate storage are needed. It is only necessary to implement a specific interface, please refer to the specific code for details.
The implementation of `keystore` refers to the implementation in` fabric-sdk-go`. The private key can be distinguished by calculating the SKI of the certificate, and the relationship between the certificate and the private key can also be distinguished by other methods.

#### About encryption
In order to facilitate the encryption and decryption of data during the on-chain operation of data transactions, the SDK implements a symmetric encryption `AES` and an asymmetric encryption` SM2` algorithm 
The symmetric encryption is `AES`. The specific call is as follows
```
	data :=[]byte("abc")
	key :=[]byte("123456")

//CBC mode, the key is less than 16 bits PKCS7 padding key
	key = keystore.Pkcs7PaddingKey(key)
	//Encryption
	cr ,err :=keystore.AESCBCPKCS7Encrypt(key,data)
	if err !=nil{
	    t.Fatal(err)
	}

//Turn hex output
	fmt.Println("After encryption:",hex.EncodeToString(cr))

//Decrypt
	data,err = keystore.AESCBCPKCS7Decrypt(key,cr)
	if err !=nil{
	    t.Fatal(err)
	}

fmt.Println("After decryption:：",string(data))
```
Asymmetric encryption `SM2`, as follows, in this method, both the signature and verification of SM2 are realized
>In asymmetric encryption, it is encrypted by public key and decrypted by private key
```
	puk := ``//Public key
	prik := ``//Private key
	sm, err := sm2.NewSM2Handle(puk, prik)
	if err != nil {
	    t.Fatal(err)
	}
	data :=[]byte("abc")
	cr ,err :=sm.Encrypt(data)
	if err != nil {
	    t.Fatal(err)
	}
	fmt.Println("After encryption：",hex.EncodeToString(cr))
	data,err = sm.Decrypt(cr)
	if err != nil {
	    t.Fatal(err)
	}
	fmt.Println("After decryption：",string(data))
```
#### About key generation
In BSN, the key format of the `fabric` frame is the` secp256r1` curve of `ECDSA`, and the key format of the` fisco-bcos` frame is `SM2`
When a user participates in an non-hosting application, a key in a corresponding format needs to be generated and uploaded.
The following describes the generation of these two keys. The key is generated using `openssl`, and the generation of the` SM2` key requires `1.1.1` and above of` openssl`
> Note: The following commands are executed in linux environment
##### 1. ECDSA (secp256r1) key generation
- Generate private key
```
openssl ecparam -name prime256v1 -genkey -out key.pem
```
- Export public key
```
openssl ec -in key.pem -pubout -out pub.pem
```
- Export private key in pkcs8 format
> Because it is more convenient to use the pkcs8 format key in some languages, you can use the following command to export the pkcs8 format private key 
> The private key used in this SDK is the pkcs8 format
```
openssl pkcs8 -topk8 -inform PEM -in key.pem -outform PEM -nocrypt -out key_pkcs8.pem
```
Three files can be generated by the above command  
__`key.pem`__ :Private key  
__`pub.pem`__ :Public key  
__`key_pkcs8.pem`__ :pkcs8 format private key

##### 2.`SM2` format key generation
First you need to check whether the version of `openssl` supports` SM2` format key generation, you can use the following command
```
openssl ecparam -list_curves | grep SM2
```
If the following content is output, it means support,
```
SM2       : SM2 curve over a 256 bit prime field
```
Otherwise, you need to go to the official website to download `1.1.1` or above,
This is the version used for `1.1.1d`,  
Official website download address：[https://www.openssl.org/source/openssl-1.1.1d.tar.gz](https://www.openssl.org/source/openssl-1.1.1d.tar.gz])

- Generate private key
```
openssl ecparam -genkey -name SM2 -out sm2PriKey.pem
```
- Export public key
```
openssl ec -in sm2PriKey.pem -pubout -out sm2PubKey.pem
```
- Export private key in pkcs8 format
> Because it is more convenient to use the pkcs8 format key in some languages, you can use the following command to export the pkcs8 format private key  
> The private key used in this SDK is the pkcs8 format
```
openssl pkcs8 -topk8 -inform PEM -in sm2PriKey.pem -outform pem -nocrypt -out sm2PriKeyPkcs8.pem
```
Three files can be generated by the above command  
__`sm2PriKey.pem`__ :Private key  
__`sm2PubKey.pem`__ :Public key  
__`sm2PriKeyPkcs8.pem`__ :pkcs8 format private key

Codey/PCNGateway-Go-SDK

简介

发行版

贡献者

近期动态

Codey/PCNGateway-Go-SDK .gitee-modal { width: 500px !important; }

简介

发行版

贡献者

近期动态

搜索帮助

Codey/PCNGateway-Go-SDK