BSNDA / PCNGateway-Java-SDK

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.

PCN Gateway Java SDK Reference

SDK in Java

1. Before calling

System Requirements

• JDK: ORACLE JDK8 must meet

App parameter

Application parameters are obtained from the application details page after the user participates in the application, or some parameters are set locally, specifically including

• Node gateway interface address: gateway address of the user's participated city node, used to call the smart contract
• Usercode: usercode
• Appcode: appcode
• Public key: the public key of the DApp Access key pair downloaded by the user after successfully participates in the application
• Private key: for Key Trust Mode, it is the private key generated by BSN after the user successfully participated in the application; for Public Key Upload Mode, it is generated by the user locally and is corresponding to the public key that the user uploads to the BSN.
• User certificate storage directory: The user certificate storage directory required by the non-hosted applications of Fabric when calling the gateway for transactions

2. Preparation

Import bsn-sdk-java-jar-with-dependencies.jar to the project

Import the SDK package

The following package needs to be introduced

import (
    "bsn-sdk-java.com.example.javacc.fabric"
    "bsn-sdk-java.com.example.javacc.entity.config.Config"
	)

Initialize config

An object can be initialized to store all the configuration information, which should be passed in at the time of invocation after being configured or read by the caller according to their respective project. In config's 'Init' method, the operation to get the basic information of an App is realized. Please do not call this operation frequently, because this interface will occupy your TPS and traffic. You can use a static object to store 'config' in the project when you need it.Among them, the application private key, the node gateway public key, and the HTTPS certificate are stored in the directory 'resources', and only need to configure the path relative to the directory. The certificate storage directory is the absolute path to the disk. You can modify the way child user certificates are stored by modifying the implementation in 'util. Keystore'.

	api:="" //Node gateway address
	userCode:="" //User ID
	appCode :="" //AppID
	puk :="cert/public_Key.pem" //Public key
	prk :="cert/private_Key.pem" //Private key
	mspDir:="" //cert directory

Initialize Config

Use the generated configuration object, call the following code to create a Config object to invoke the node gateway

	Config config = new Config();
	config.setAppCode(appCode );
	config.setUserCode(userCode);
	config.setCert(cert) 
	config.setPrk(prk)
	config.setApi(api);
	config.setPuk(puk);
	config.setMspDir(cert);
	config.initConfig(config);

Call interface

Each gateway interface has encapsulated the parameter object of the request and response, which can be directly called just by assigning the value, and the operation of signing and checking the signature has been realized in the method. The following is the call operation for the registered child user, and others are similar.

//Initialize config。
public void initConfig() throws IOException {
    Config config = new Config();
    config.setAppCode("app0001202004161020152918451");
    config.setUserCode("USER0001202004151958010871292");
    config.setApi("http://192.168.1.43:17502");
    config.setPrk(Common.readFile("cert/private_key.pem"));
    config.setPuk(Common.readFile("cert/public_Key.pem"));
    config.setMspDir("D:/test");
    config.initConfig(config);
}
//Invoke the interface of user registration
public void userRegister() {
    try {
        initConfig(); //For example, in practice, the value needs to be called once during the program's life cycle
    } catch (IOException e) {
        e.printStackTrace();
        return ;
    }
    ReqUserRegister register = new ReqUserRegister();
    register.setName("test19");
    register.setSecret("123456");
    try {
        UserService.userRegister(register);
    } catch(GlobalException g) {
        g.printStackTrace();
    }catch (IOException e) {
        e.printStackTrace();
        return;
    }
}

3.Other instructions

Description of user ID cert on the unmanaged application

Since the user certificate needed by the unmanaged application when calling the gateway for transaction needs to be generated by the user himself, the process is: registered user -> registered user certificate. In the operation of registering a user certificate, a pair of secret keys are generated locally, the certificate's CSR file (certificate application file) is exported through the secret key, and the user certificate is invoked. The registration interface gets a valid certificate that can be used to normally initiate a transaction through the managed application transaction processing interface. It should be noted that when setting CN in the CSR file, it is not the registered Name directly, but a Name spliced by Name and AppCode in the format of 'nam@appcode'. This operation is implemented in the ' keyEscrowNoRegister' method of 'KeyEscrowFabric'.

cert storage implemented through the util.keystore method, which stores only certificates in the form of local files if required

About encryption

In order to facilitate data encryption and decryption in the chain operation of data transaction, the SDK implements symmetric encryption 'AES', 'DES' and an asymmetric encryption 'SM2' algorithm. Symmetric encryption for 'AES' is specifically called as follows.

		String prk="";//Private key
        String content="";//encrypted content
        System.out.println("encrypted ciphertext: "+AESEncode(encodeRules,content));
        System.out.println("decrypted ciphertext: "+AESDncode(encodeRules,AESEncode(encodeRules,content)));
    /*
     * Encryption
     * 1.Construct KeyGenerator
     * 2.Initialize the key generator according to ecnodeRules
     * 3.Generate a secret key
     * 4.Create and initialze the password
     * 5.Content encryption
     * 6.Return string
     */
    public static String AESEncode(String encodeRules,String content){
        try {
            
            KeyGenerator keygen=KeyGenerator.getInstance("AES");
            keygen.init(128, new SecureRandom(encodeRules.getBytes()));
           
            SecretKey original_key=keygen.generateKey();
            byte [] raw=original_key.getEncoded();
           
            SecretKey key=new SecretKeySpec(raw, "AES");
            
            Cipher cipher=Cipher.getInstance("AES");
            cipher.init(Cipher.ENCRYPT_MODE, key);
            byte [] byte_encode=content.getBytes("utf-8");
            byte [] byte_AES=cipher.doFinal(byte_encode);
            String AES_encode=new String(new BASE64Encoder().encode(byte_AES));
            return AES_encode;
        } catch (Exception e) {
            e.printStackTrace();
        }
        return null;
    }

    /*
     * Decryption
     * Steps: 
     * 1.Step 1-4 with encryption
     * 2.The encrypted string is converted into a byte[] array
     * 3.Decrypt the encrypted content
     */
    public static String AESDncode(String encodeRules,String content){
        try {
            KeyGenerator keygen=KeyGenerator.getInstance("AES");
            keygen.init(128, new SecureRandom(encodeRules.getBytes()));
            SecretKey original_key=keygen.generateKey();
            byte [] raw=original_key.getEncoded();
            SecretKey key=new SecretKeySpec(raw, "AES");
            Cipher cipher=Cipher.getInstance("AES");
            cipher.init(Cipher.DECRYPT_MODE, key);
            byte [] byte_content= new BASE64Decoder().decodeBuffer(content);
            /*
             * Decrypt
             */
            byte [] byte_decode=cipher.doFinal(byte_content);
            String AES_decode=new String(byte_decode,"utf-8");
            return AES_decode;
        } catch (Exception e) {
            e.printStackTrace();
        }
        return null;
    }

Asymmetric encryption 'SM2', the details are as follows. In this method, both the signature and the check sign of SM2 are realized

Asymmetric encryption is encrypted by the public key and decrypted by the private key

	puk := ``//Public key
	prik := ``//Private key
	String src = "encrypted string";
	SM2Algorithm sm2Algorithm = new SM2Algorithm();
    String signResult = sm2Algorithm.sign(prik, src);
    boolean result = sm2Algorithm.verify(puk, signResult, src);
    System.out.println(result);

Secret key

In BSN, the key format of 'fabric' framework is' secp256r1 'curve of' ECDSA ', while the key format of 'fisco-bcos' framework is' SM2' When a user connects to an unmanaged application, a key of the corresponding format needs to be generated and uploaded. The generation of these two keys is described below. The generation of the secret key is generated using 'openssl', where the generation of 'SM2' secret key requires the '1.1.1' version of 'openssl' and above

note: the following commands are executed in a Linux environment

1. Key generation of ECDSA(secp256r1)

• Generate a private key

openssl ecparam -name prime256v1 -genkey -out key.pem

• Export the public key

openssl ec -in key.pem -pubout -out pub.pem

• Export the pkcs8 format private key

Since it is convenient to use the pkcs8 format key in some languages, you can export the pkcs8 format private key using the following command
The private key used in this SDK is in the form of pkcs8

openssl pkcs8 -topk8 -inform PEM -in key.pem -outform PEM -nocrypt -out key_pkcs8.pem

Three files can be generated from the above command key.pem :Private key
pub.pem :Public key
key_pkcs8.pem : private key in Pkcs8 format

2.SM2secret key generation

First you need to check whether the version of 'openssl' supports' SM2 'format secret key generation using the following command

openssl ecparam -list_curves | grep SM2

Support if you output the following,

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 1.1.1'. Download address: https://www.openssl.org/source/openssl-1.1.1d.tar.gz

• Generate a private key

openssl ecparam -genkey -name SM2 -out sm2PriKey.pem

• Export a public key

openssl ec -in sm2PriKey.pem -pubout -out sm2PubKey.pem

• Export the private key in pkcs8 format

Since it is convenient to use the pkcs8 format key in some languages, you can export the pkcs8 format private key using the following command The private key used in this SDK is in the form of pkcs8

openssl pkcs8 -topk8 -inform PEM -in sm2PriKey.pem -outform pem -nocrypt -out sm2PriKeyPkcs8.pem

Three files can be generated from the above command sm2PriKey.pem :Private key sm2PubKey.pem :Public key sm2PriKeyPkcs8.pem :Private key in pkcs8 format