Development Guidelines on Trusted Device Group Management

• When to Use
• Available APIs
• How to Develop
• Debugging and Verification

When to Use

When a distributed service needs to exploit the secure communication channel provided by the distributed virtual bus for different devices, it can use the trusted device group management component to create groups of trusted devices. Distributed applications can establish and use secure, trusted relationships between devices based on the authentication capabilities for devices using different HUAWEI IDs, such as PIN code, QR code, and OneHop, and the capabilities for grouped devices using the same HUAWEI ID. For a device on which you have not logged in using your HUAWEI ID, you can enter the PIN code or scan the QR code to obtain the connection and PIN code information of the device. Then you can create a group of trusted devices and add this device to the group. If other applications have created and shared their groups of trusted devices, or have logged in using the same HUAWEI ID as yours, you can call APIs to query and use the groups.

Available APIs

The following tables list the innerkits APIs provided by trusted device group management. These APIs are intended for system applications only.

Table 1 Java APIs provided by trusted device group management

Table 2 C++ APIs provided by trusted device group management for internal applications to query group information using SA

How to Develop

To develop trusted device group management, first obtain a management instance (a callback to obtain group operation results is registered during the process). Then you can use the instance to add or delete members, set a friend list for a group, and perform related query operations.

Scenario 1: Create a group.

private HwDeviceGroupManager hwDeviceGroupManager;
...
private HichainGroupCallback groupCallbackByA = new HichainGroupCallback() {
    @Override public void onFinish(long requestId, GroupOperation operationCode, String returnData) {

    }    
    @Override public void onError(long requestId, GroupOperation operationCode, int errorCode, String errorReturn) { 

    }    
    @Override public String onRequest(long requestId, GroupOperation operationCode, String reqParams) {
        JSONObject onRequestJson = generateConfirmation(REQUEST_ACCEPTED);       
        return onRequestJson.toString();
    }
};
...
Optional<Context> context = convertAbilityToContext(mAbility);
Context ctxt = context.get();
hwDeviceGroupManager = HwDeviceGroupManager.getInstance(ctxt, APP_ID, groupCallbackByA);
int ret = hwDeviceGroupManager.createGroup(APP_ID, GROUP_NAME, GROUP_TYPE, GROUP_INFO);

1. Declare the private member variable of the HwDeviceGroupManager instance.

   private HwDeviceGroupManager hwDeviceGroupManager;
   

2. Create a callback for group management operations.

   private HichainGroupCallback groupCallbackByA = new HichainGroupCallback();
   

3. Obtain a HwDeviceGroupManager instance. (In distributed scenarios, the same application on different devices must use the same APP_ID.)

   hwDeviceGroupManager = HwDeviceGroupManager.getInstance(ctxt, APP_ID, groupCallbackByA);
   

4. Call the createGroup function to create a group. If 0 is returned, the creation request is submitted successfully.

   int ret = hwDeviceGroupManager.createGroup(APP_ID, GROUP_NAME, GROUP_TYPE, GROUP_INFO);
   

5. After the group is created, onFinish is called. In this callback, the value of operationCode is OperationCode.CREATE, indicating a group creation operation. returnData is in JSON format and contains the groupId field, indicating the ID of the created group.

Scenario 2: Add an authenticated device (member) to a group so that you can initiate trusted, encrypted connections to the device through the distributed virtual bus.

deviceGroupManager = DeviceGroupManager.getInstance(mAbility, APP_ID, hichainGroupCallback);
private static final String CONN_PARAM ="{\"DEVICE_ID\":\"11111111\",\"WIFI_IP\":\"192.168.43.149\",\"WIFI_PORT\":\"30000\",\"BLE_MAC\":\"\"}";
private static final String ADD_PARAM ="{\"groupId\":\"344C1C8B149\",\"groupName\":\"myGroup\",\"addId\":\"11111111\",\"isAdmin\":\"false\"}";
private static final int GROUP_TYPE = 256;
int result = deviceGroupManager.addMemberToGroup(APP_ID, reqId, ADD_PARAM, CONN_PARAM, GROUP_TYPE);

1. Obtain an HwDeviceGroupManager instance.

   deviceGroupManager = HwDeviceGroupManager.getInstance(mAbility, APP_ID, hichainGroupCallback);
   

2. Set network connection parameters for the member to add (in JSON format), which are network parameters supported by the distributed virtual bus, such as WIFI_IP, WIFI_PORT, BLR_MAC, and DEVICE_ID. For details about the parameters, see the distributed virtual bus development guidelines.

   String CONN_PARAM ="{\"DEVICE_ID\":\"11111111\",\"WIFI_IP\":\"192.168.43.149\",\"WIFI_PORT\":\"30000\",\"BLE_MAC\":\"\"}";
   

3. Set parameters for the member to add (in JSON format), including the group ID, name, and whether the member is an administrator. If the member is invited to add a group, the value of isAdmin is true; otherwise, the value of isAdmin is false.

   String ADD_PARAM ="{\"groupId\":\"344C1C8B149\",\"groupName\":\"myGroup\",\"addId\":\"11111111\",\"isAdmin\":\"false\"}";
   

4. Set the type of the target group to 256, indicating a P2P group.

   private static final int GROUP_TYPE = 256;
   

5. Set generateConfirmation of the onRequest function in HichainGroupCallback. PIN_CODE indicates the PIN code, which is input by users on the UI of the service. (In a distributed communication, two devices must use the same PIN code.)

   private JSONObject generateConfirmation(int confirmation) {    
       JSONObject jsonObject = new JSONObject();    
       try {    jsonObject.put("pinCode", PIN_CODE);
                jsonObject.put("confirmation", confirmation);    
       } catch (JSONException e) {
           LogUtil.error(TAG, "" + e.getMessage());    
       }
       return jsonObject;
   }
   

6. Call the addMemberToGroup function to add the member to the group.

   result = deviceGroupManager.addMemberToGroup(APP_ID, reqId, ADD_PARAM, CONN_PARAM, GROUP_TYPE);
   

7. Check whether HichainGroupCallback.onFinish is called (operationCode is OperationCode.JOIN). If it is called, the member is added successfully.

8. Call APIs of the distributed virtual bus to create secure sessions between devices.

Debugging and Verification

1. Develop an application with OpenHarmony.

2. Develop an application by following the development guidelines.

3. Create a group. If the onFinish callback is invoked, the group is created successfully.

4. Deploy the same application on two devices, A and B.

5. Transmit the connection parameters of device B to device A through a QR code.

6. In the application on device A, create group1 and call the API to add device B to group1. If HichainGroupCallback.onFinish is called, device B is successfully added to group1.