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

framework and key support

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

The details are as follows：

framework	public key upload mode			key trust mode
	secp256r1	secp256k1	SM2	secp256r1	secp256k1	SM2
Fabric	√		√	√		√
FISCO-BCOS		√	√		√	√
XuperChain			√			√
Cita						√

• 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 private 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

• 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