This article provides sample signature code for you to develop your device. This way, your device can communicate with IoT Platform over MQTT without using a device SDK that is provided by IoT Platform.

Description

We recommend that you use a device SDK that is provided IoT Platform. If a device SDK for any programming language is used, you do not need to configure your own signature mechanism. For information about how to obtain the SDK download URL, see Download device SDKs.

If you use other methods to connect your devices with IoT Platform, take note of the following information:

  • You must ensure connection stability and maintain the keepalive and reconnection mechanisms for MQTT connections.
  • Alibaba Cloud does not provide technical support for any possible connection issues.
  • If you want to use IoT Platform features, such as OTA, TSL models, and unique-certificate-per-product authentication, you must compile your own code to implement these features. This may consume a lot of development time and bug fixing time.

Sample code for signature calculation

If you do not use a device SDK that is provided by IoT Platform, click the following links to view the sample code.

  • sign_mqtt.c: the sample code that is used to implement the signature function.
  • sign_api.h: the sample code that defines the data structure of the signature function.
  • sign_sha256.c: the sample code that defines the algorithm of the signature function. If you already implement the HMACSHA256 algorithm on your own platform, you do not need to compile this code file. However, you must provide the utils_hmac_sha256() function that can be called by the sign_mqtt.c function.
  • Sample code: that sample code that is used to test the signature function.

Description of the signature function

Syntax 
int32_t IOT_Sign_MQTT(iotx_mqtt_region_types_t region,
              iotx_dev_meta_info_t *meta,
              iotx_sign_mqtt_t *signout);
Description Obtains the information that are required to connect a device with IoT Platform based on the specified device identity information. The connection information includes the endpoint, MQTT client ID, MQTT username, and MQTT password. Then, you can provide the information for the MQTT client to connect with IoT Platform.
Input parameters The following input parameters are included:
  • region: the IoT Platform endpoint to which the device connects.

    Example:

    typedef enum {
    IOTX_CLOUD_REGION_SHANGHAI,   /* Shanghai */
    IOTX_CLOUD_REGION_SINGAPORE,  /* Singapore */
    IOTX_CLOUD_REGION_JAPAN,      /* Japan */
    IOTX_CLOUD_REGION_USA_WEST,   /* America */
    IOTX_CLOUD_REGION_GERMANY,    /* Germany */
    IOTX_CLOUD_REGION_CUSTOM,     /* Custom setting */
    IOTX_CLOUD_DOMAIN_MAX         /* Maximum number of domain */
} iotx_mqtt_region_types_t;
  • meta: the identity information of the device.
    Note You must allocate memory for the meta parameter when you call the function.

    Example:

    typedef struct _iotx_dev_meta_info {
    char product_key[IOTX_PRODUCT_KEY_LEN + 1];
    char product_secret[IOTX_PRODUCT_SECRET_LEN + 1];
    char device_name[IOTX_DEVICE_NAME_LEN + 1];
    char device_secret[IOTX_DEVICE_SECRET_LEN + 1];
} iotx_dev_meta_info_t;

    Parameters:

    • product_key: the ProductKey of the product to which the device belongs.
    • product_secret: the ProductSecret of the product to which the device belongs.
    • device_name: the DeviceName of the device.
    • device_secret: the DeviceSecret of the device.
Output parameters signout: the output data. The data is used to establish an MQTT connection.

Example:

typedef struct {
    char hostname[DEV_SIGN_HOSTNAME_MAXLEN];
    uint16_t port;
    char clientid[DEV_SIGN_CLIENT_ID_MAXLEN];
    char username[DEV_SIGN_USERNAME_MAXLEN];
    char password[DEV_SIGN_PASSWORD_MAXLEN];
} iotx_sign_mqtt_t;

Parameters:

  • hostname: the complete endpoint of the IoT Platform server.
  • port: the port number of the IoT Platform server.
  • clientid: the client ID that must be specified to establish an MQTT connection. We recommend that you use the MAC address or serial number (SN) of the device. The client ID can be a maximum of 64 characters in length.
  • username: the username that must be specified to establish an MQTT connection. The username consists of the DeviceName, Ampersand (&), and ProductKey. Format: deviceName+"&"+productKey. Example: Device1&alSseIs****.
  • password: the password that must be specified to establish an MQTT connection. After you sort the parameters that are submitted to the server by using a dictionary and splice the parameters, use the hmacsha256 method and the DeviceSecret of the device to generate a password.

For more information, see Establish MQTT connections over TCP.

Response codes
  • 0: indicates that the call was successful.
  • -1: indicates that the call failed because the input parameters are invalid.

Example of using the signature function

In this example, the sample code in sign_test.c is used.

#include <stdio.h>
#include <string.h>
#include "sign_api.h"  //Defines all data structures that are used in the signature function.

//The following macros are used to define the device identity information: ProductKey, ProductSecret, DeviceName, and DeviceSecret.
//In actual product development, the device identity information must be encrypted by the device manufacturer and stored in the flash of the device or a file.
//These macros are read and used after the device is powered on.
#define EXAMPLE_PRODUCT_KEY     "a1X2bEn****"
#define EXAMPLE_PRODUCT_SECRET  "7jluWm1zql7b****"
#define EXAMPLE_DEVICE_NAME     "example1"
#define EXAMPLE_DEVICE_SECRET   "ga7XA6KdlEeiPXQPpRbAjOZXwG8y****"

int main(int argc, char *argv[])
{
    iotx_dev_meta_info_t meta_info;
    iotx_sign_mqtt_t sign_mqtt;

    memset(&meta_info, 0, sizeof(iotx_dev_meta_info_t));
    //Use the following code to copy the previously defined device identity information to meta_info.
    memcpy(meta_info.product_key, EXAMPLE_PRODUCT_KEY, strlen(EXAMPLE_PRODUCT_KEY));
    memcpy(meta_info.product_secret, EXAMPLE_PRODUCT_SECRET, strlen(EXAMPLE_PRODUCT_SECRET));
    memcpy(meta_info.device_name, EXAMPLE_DEVICE_NAME, strlen(EXAMPLE_DEVICE_NAME));
    memcpy(meta_info.device_secret, EXAMPLE_DEVICE_SECRET, strlen(EXAMPLE_DEVICE_SECRET));

    //Call the signature function to generate the data that is required to establish an MQTT connection.
    IOT_Sign_MQTT(IOTX_CLOUD_REGION_SHANGHAI, &meta_info, &sign_mqtt);

    ...

}