tencent cloud

Overview

IoT Hub assigns a unique product ID to each created product. You can customize the DeviceName to identify devices and use the product ID + device ID + device certificate/key to authenticate devices. Devices need to store such identity information. The C-SDK provides APIs for reading and writing the device information and reference implementations for adaptation as needed.

Device Identity Information

• Certificate-authenticated devices must carry the following four pieces of information before it can pass the authentication by the platform: product ID (ProductId), device name (DeviceName), device certificate (DeviceCert), and device private key (DevicePrivateKey), among which, the certificate and private key files are generated by the platform and correspond to each other.
• Key-authenticated devices must carry the following three pieces of information before it can pass the authentication by the platform: product ID (ProductId), device name (DeviceName), and device key (DeviceSecret), among which, the device key is generated by the platform.

Device Identity Information Burning

Device information burning is divided into preset burning and dynamic burning, which differ in terms of convenience and security.

Preset burning

After a product is created, you can create devices one by one in the IoT Hub console or through TencentCloud API, get their corresponding device information, and burn the above three or four pieces of information into a non-volatile medium in a specific step of device production, so that the device SDK can read the stored device information during running for device authentication.

Dynamic burning

• Preset burning: this involves performing personalized production actions in the mass production process and thus affects the production efficiency. To improve the ease of use, the platform supports dynamic burning. This feature is implemented as follows: after a product is created, its dynamic registration feature can be enabled to generate a product key (ProductSecret). Unified product information can be burned for all devices under it in the production process, i.e., product ID (ProductId) and product key (ProductSecret). After the devices are shipped, the device identity information can be obtained through dynamic registration and then saved, and then obtained three or four pieces of information can be used for device authentication.
• Device name (DeviceName) generation for dynamic burning: if automatic device creation is enabled during dynamic registration, device names can be generated by devices themselves, which are generally device IMEIs or MAC addresses but must be unique under the same product ID (ProductId). If automatic device creation is not enabled during dynamic registration, device names should be entered on the platform in advance, and the platform will verify whether the requested device names are validly entered during dynamic device registration. This can reduce the security risks in case of product key leakage.

Note：

For dynamic registration, you should ensure the security of the product key (ProductSecret); otherwise, major security risks may arise.

Device Information Read/Write HAL APIs

The SDK provides HAL APIs for reading and writing device information, which must be implemented. For more information on how to implement device information read/write, please see HAL_Device_Linux.c on Linux.

Device information HAL APIs:

Device Information Configuration in Development Phase

After a device is created, you need to configure its information (ProductID/DeviceName/DeviceSecret/Cert/Key file) in the SDK first before the demo can run properly. In the development phase, the SDK provides two methods of storing the device information:

1. If the device information is stored in the code (compilation option DEBUG_DEV_INFO_USED = ON), you should modify the device information in platform/os/xxx/HAL_Device_xxx.c. This method can be used on platforms without a file system.

/* product Id  */
static char sg_product_id[MAX_SIZE_OF_PRODUCT_ID + 1]     = "PRODUCT_ID";

/* device name */
static char sg_device_name[MAX_SIZE_OF_DEVICE_NAME + 1]  = "YOUR_DEV_NAME";

#ifdef DEV_DYN_REG_ENABLED
/* product secret for device dynamic Registration  */
static char sg_product_secret[MAX_SIZE_OF_PRODUCT_SECRET + 1]  = "YOUR_PRODUCT_SECRET";
#endif

#ifdef AUTH_MODE_CERT
/* public cert file name of certificate device */
static char sg_device_cert_file_name[MAX_SIZE_OF_DEVICE_CERT_FILE_NAME + 1]      = "YOUR_DEVICE_NAME_cert.crt";
/* private key file name of certificate device */
static char sg_device_privatekey_file_name[MAX_SIZE_OF_DEVICE_SECRET_FILE_NAME + 1] = "YOUR_DEVICE_NAME_private.key";
#else
/* device secret of PSK device */
static char sg_device_secret[MAX_SIZE_OF_DEVICE_SECRET + 1] = "YOUR_IOT_PSK";
#endif

2. If the device information is stored in the configuration file (compilation option DEBUG_DEV_INFO_USED = OFF), you should modify the device information in the device_info.json file with no need to recompile the SDK. This method is recommended for development on Linux and Windows.

{
    "auth_mode":"KEY/CERT",

    "productId":"PRODUCT_ID",
    "productSecret":"YOUR_PRODUCT_SECRET",
    "deviceName":"YOUR_DEV_NAME",

    "key_deviceinfo":{    
        "deviceSecret":"YOUR_IOT_PSK"
    },

    "cert_deviceinfo":{
        "devCertFile":"YOUR_DEVICE_CERT_FILE_NAME",
        "devPrivateKeyFile":"YOUR_DEVICE_PRIVATE_KEY_FILE_NAME"
    },

    "subDev":{
        "sub_productId":"YOUR_SUBDEV_PRODUCT_ID",
        "sub_devName":"YOUR_SUBDEV_DEVICE_NAME"
    }
}

Use Cases

• Initialize the connection parameters

static DeviceInfo sg_devInfo;

static int _setup_connect_init_params(MQTTInitParams* initParams)
{
    int ret;
    
    ret = HAL_GetDevInfo((void *)&sg_devInfo);    
    if(QCLOUD_ERR_SUCCESS != ret){
        return ret;
    }
        
    initParams->device_name = sg_devInfo.device_name;
    initParams->product_id = sg_devInfo.product_id;
     ......
}    

• Generate the parameters for authenticating a key-authenticated device

static int _serialize_connect_packet(unsigned char *buf, size_t buf_len, MQTTConnectParams *options, uint32_t *serialized_len) {
            ......
            ......
    int username_len = strlen(options->client_id) + strlen(QCLOUD_IOT_DEVICE_SDK_APPID) + MAX_CONN_ID_LEN + cur_timesec_len + 4;
    options->username = (char*)HAL_Malloc(username_len);
    get_next_conn_id(options->conn_id);
    HAL_Snprintf(options->username, username_len, "%s;%s;%s;%ld", options->client_id, QCLOUD_IOT_DEVICE_SDK_APPID, options->conn_id, cur_timesec);

#if defined(AUTH_WITH_NOTLS) && defined(AUTH_MODE_KEY)
     if (options->device_secret != NULL && options->username != NULL) {
         char                sign[41]   = {0};
         utils_hmac_sha1(options->username, strlen(options->username), sign, options->device_secret, options->device_secret_len);
         options->password = (char*) HAL_Malloc (51);
         if (options->password == NULL) IOT_FUNC_EXIT_RC(QCLOUD_ERR_INVAL);
         HAL_Snprintf(options->password, 51, "%s;hmacsha1", sign);
     }
#endif
            ......
}