Device signature

Background information

Alibaba Cloud IoT Platform uses the Message Queuing Telemetry Transport (MQTT) protocol for communication between devices and the platform. When an MQTT client connects to IoT Platform, the username, password, and clientID must conform to the format required by IoT Platform. These credentials, known as device signature information, are used to authenticate the device. The dev_sign feature provides an encapsulation for calculating these signature fields. This process is called device signing.

Scenarios

If your device has an existing MQTT client and you want to communicate directly with IoT Platform over MQTT without using other software development kit (SDK) features, you can call the device signature API operation. This retrieves the MQTT parameters required to connect to IoT Platform. You can then use these parameters with your MQTT client to establish a connection.

Example program walkthrough

This topic uses Link SDK 3.2.0 as an example. For more information about how to download other versions of the Link SDK, see Obtain the SDK.

For a device signing code example, see the src/dev_sign/examples/dev_sign_example.c file. The following steps walk you through the code:

1. To use the dev_sign feature, include its API header file dev_sign_api.h:

   #include "dev_sign_api.h"

2. Create a new device in the IoT Platform console and record its credentials:

   #define EXAMPLE_PRODUCT_KEY     "a1X2bEn****"
   #define EXAMPLE_PRODUCT_SECRET  "7jluWm1zql7b****"
   #define EXAMPLE_DEVICE_NAME     "example1"
   #define EXAMPLE_DEVICE_SECRET   "ga7XA6KdlEeiPXQPpRbAjOZXwG******" 

3. Declare the required underlying interface:
   Note The dev_sign feature has no dependencies. You can use it without any Hardware Abstraction Layer (HAL) adaptation. HAL_Printf is declared here only because it is required for printing output in the example.

   /* Implement this HAL or use the "printf" of your own system if you want to print something in the example */
   void HAL_Printf(const char *fmt, ...);

4. Prepare the input and output parameter structs:

   int main(int argc, char *argv[])
   {
       iotx_mqtt_region_types_t region = IOTX_CLOUD_REGION_SHANGHAI;
       iotx_dev_meta_info_t meta;
       iotx_sign_mqtt_t sign_mqtt;
   
       memset(&meta,0,sizeof(iotx_dev_meta_info_t));
       memcpy(meta.product_key,EXAMPLE_PRODUCT_KEY,strlen(EXAMPLE_PRODUCT_KEY));
       memcpy(meta.product_secret,EXAMPLE_PRODUCT_SECRET,strlen(EXAMPLE_PRODUCT_SECRET));
       memcpy(meta.device_name,EXAMPLE_DEVICE_NAME,strlen(EXAMPLE_DEVICE_NAME));
       memcpy(meta.device_secret,EXAMPLE_DEVICE_SECRET,strlen(EXAMPLE_DEVICE_SECRET));

5. Declare a struct variable of the iotx_dev_meta_info_t type. Populate it with the device credentials for which you want to calculate the signature.
   Then, call the API operation for the dev_sign feature, IOT_Sign_MQTT(), to calculate the signature:

   if (IOT_Sign_MQTT(region,&meta,&sign_mqtt) < 0) {
           return -1; 
       }

6. The result is stored in the output parameter sign_mqtt, which is a struct variable of the iotx_sign_mqtt_t type.
   You can then print the signature result or use it to connect to the MQTT server:

   #if 0   /* Uncomment this if you want to show more information */
       HAL_Printf("sign_mqtt.hostname: %s\n",sign_mqtt.hostname);
       HAL_Printf("sign_mqtt.port    : %d\n",sign_mqtt.port);
       HAL_Printf("sign_mqtt.username: %s\n",sign_mqtt.username);
       HAL_Printf("sign_mqtt.password: %s\n",sign_mqtt.password);
       HAL_Printf("sign_mqtt.clientid: %s\n",sign_mqtt.clientid);
   #endif         

The members of the output parameter are described as follows:

Feature API operations

• Prototype:

  int32_t IOT_Sign_MQTT(iotx_mqtt_region_types_t region, iotx_dev_meta_info_t *meta, iotx_sign_mqtt_t *signout);

• Description: Call this operation to calculate the signature for the specified device credentials. The operation returns the result in the output parameter signout.
• Parameters:

  Parameter	Data type	Direction	Description
  region	iotx_mqtt_region_types_t	Input	The region where the device will operate, such as China (Shanghai), Asia Pacific NE 1 (Tokyo), US West 1 (Silicon Valley), or Asia Pacific SE 1 (Singapore). For a complete list, see Regions and zones.
  meta	iotx_dev_meta_info_t *	Input	Stores the device's ID strings, including ProductKey and DeviceName.
  signout	iotx_sign_mqtt_t *	Output	Stores the calculated signature information, including the MQTT server address and port, and the username and password for the connection.

• Return values:

  Return Value	Description
  =0	Success
  <0	Failure

Required HAL interfaces

The dev_sign feature has no dependencies. You do not need to implement any HAL interfaces.