SDK allowlist mechanism

FISCO BCOS 2.0 started to support multiple groups, but did not control the SDK’s access rights to multiple groups. As long as the SDK can establish a connection with the node, it can access all the groups of the node, which will bring security risks.

FISCO BCOS v2.6.0 introduces a group-level SDK allowlist mechanism, controls the SDK’s access rights to groups, and provides scripts to support the dynamic loading of the SDK allowlist list, further improving the security of the blockchain system.

Note

  • When the number of SDK allowlist lists in the configuration item is 0, the node does not enable the SDK allowlist control function, and any SDK can access the group;
  • The SDK allowlist is a node-level access control mechanism. The node that enables this function controls the SDK’s access rights to the node group based on the locally configured allowlist;
  • The SDK allowlist mechanism controls SDK access to all group-level interfaces of the node

Configuration

Note

The SDK allowlist configuration of each group is located in the [sdk_allowlist] configuration item of the group.{group_id}.ini configuration file. For details, please refer to here

Get SDK public key

Before adding the SDK to the allowlist, you first need to obtain the SDK public key, which is used to set the public_key of group.*.ini. The methods for obtaining the SDK public key for each version are as follows:

Newly built chain

The SDK certificate generated by the newly built chain comes with SDK private key information. The standard version is sdk.publickey, and the OSCCA-approved version is gmsdk.publickey:

# Assuming that the certificate has been copied to the SDK, enter the SDK directory and execute the following command (sdk is located in the ~/fisco directory)
$ cd ~/fisco/java-sdk

# Obtain the public key of the OSCCA-approved SDK
$ cat dist/conf/sdk.publickey

# Obtain the public key of the standard SDK
$ cat dist/conf/gmsdk.publickey

Old chain

The old chain needs to use openssl or tassl commands to generate sdk.publickey (the OSCCA-approved version is gmsdk.publickey), and load the public key from the generated file, as follows:

Standard Version

# Enter the SDK directory and execute the following command:
$ openssl ec -in dist/conf/sdk.key -text -noout 2> /dev/null | sed -n '7,11p' | tr -d ": \n" | awk '{print substr($0,3);}' | cat > dist/conf/sdk.publickey
# Obtain the public key
$ cat dist/conf/sdk.publickey

OSCCA-approved Version

# Note: It must be ensured that ~/.fisco/tassl exists
$ ~/.fisco/tassl ec -in dist/conf/gmsdk.key -text -noout 2> /dev/null | sed -n '7,11p' | sed 's/://g' | tr "\n" " " | sed 's/ //g' | awk '{print substr($0,3);}'  | cat > dist/conf/gmsdk.publickey
# Get SDK public key
$ cat dist/conf/gmsdk.publickey

Dynamically modify the SDK allowlist

In order to facilitate users to modify the SDK allowlist list, the reload_sdk_allowlist.sh script is provided in the scripts directory of each node to reload the SDK allowlist.

Note

There is no reload_sdk_allowlist.sh script on the old chain nodes, and the script can be downloaded by the command curl -#LO https://raw.githubusercontent.com/FISCO-BCOS/FISCO-BCOS/master-2.0/tools/reload_sdk_allowlist.sh.

Example

This section takes adding and modifying the console to the whitelist as an example to show in detail how to use the SDK allowlist mechanism.

Build a blockchain and copy the certificate to the console

Please refer to Installation.

Get console public key information

# Enter the console directory
$ cd ~/fisco/console/

# Obtain console public key information through sdk.publickey
$ cat conf/sdk.publickey
ebf5535c92f7116310ed9e0f9fc9bfc66a607415d4fa444d91f528485eff61b15e40a70bc5d73f0441d3959efbc7718c20bd452ac4beed5f6c4feb9fabc1f9f6

Enable the SDK allowlist mechanism

Add the public key of a console to the allowlist of the group.[group_id].ini configuration file of node0:

[sdk_allowlist]
public_key.0=b8acb51b9fe84f88d670646be36f31c52e67544ce56faf3dc8ea4cf1b0ebff0864c6b218fdcd9cf9891ebd414a995847911bd26a770f429300085f37e1131f36

Reload the SDK allowlist

$ bash node0/scripts/reload_sdk_allowlist.sh
 [INFO] node0 is trying to reload sdk allowlist. Check log for more information.

# After the SDK allowlist is successfully hot-loaded, the node outputs the following log:
parseSDKAllowList,sdkAllowList=[b8acb51b9fe84f88d670646be36f31c52e67544ce56faf3dc8ea4cf1b0ebff0864c6b218fdcd9cf9891ebd414a995847911bd26a770f429300085f37e1131f36],enableSDKAllowListControl=true

Console access node

Note

Since the SDK allowlist is a node-level access control mechanism, in order to demonstrate the access control function of node0 to the SDK, the console only connects to node0.

Since node0 does not configure the console’s access rights to the group, the result of the deployment contract is as follows:

# Deploy HelloWorld contract in the console
[group:1]> deploy HelloWorld
sendRawTransaction The SDK is not allowed to access this group

Add the console to the SDK allowlist

Configure the console to the allowlist of node0:

[sdk_allowlist]
public_key.0=b8acb51b9fe84f88d670646be36f31c52e67544ce56faf3dc8ea4cf1b0ebff0864c6b218fdcd9cf9891ebd414a995847911bd26a770f429300085f37e1131f36
public_key.1=ebf5535c92f7116310ed9e0f9fc9bfc66a607415d4fa444d91f528485eff61b15e40a70bc5d73f0441d3959efbc7718c20bd452ac4beed5f6c4feb9fabc1f9f6

Reload the SDK whitelist list:

$ bash node0/scripts/reload_sdk_allowlist.sh
 [INFO] node0 is trying to reload sdk allowlist. Check log for more information.

# After the SDK allowlist is successfully hot-loaded, the node outputs the following log:
parseSDKAllowList,sdkAllowList=[b8acb51b9fe84f88d670646be36f31c52e67544ce56faf3dc8ea4cf1b0ebff0864c6b218fdcd9cf9891ebd414a995847911bd26a770f429300085f37e1131f36,ebf5535c92f7116310ed9e0f9fc9bfc66a607415d4fa444d91f528485eff61b15e40a70bc5d73f0441d3959efbc7718c20bd452ac4beed5f6c4feb9fabc1f9f6],enableSDKAllowListControl=true

Console access node

After node0 is added to the console to the allowlist, the console can deploy the contract normally, as follows:

[group:1]> deploy HelloWorld
contract address: 0xcd4ccd96c86fe8e4f27b056c0fdb7eb4ca201f0f