AI 助理
文档备案控制台
官方文档
首页 物联网平台（文档停止维护） 操作指南 设备接入 SDK根证书更新操作指引

SDK根证书更新操作指引

更新时间：
复制 MD 格式
我的收藏

Link SDK是阿里云物联网平台提供的设备端软件开发工具包，可简化开发过程，实现设备快速接入阿里云物联网平台，具体见设备接入概述。本文档介绍每种SDK升级根证书的方式，请参照本文档升级相应代码，并做充分的验证。

C语言

4.x（包括4.0.0/4.1.0/4.2.0等）

确认我之前产品开发使用的SDK是否是4.x：

在升级前，需要确认之前存量设备开发时所使用的SDK是否为4.x。确认方式是看是否存在core/utils/core_auth.h这样一个文件，并且其中包含如下内容。如果不是，则跳过本节。

#define CORE_AUTH_SDK_VERSION "sdk-c-4.x.x"

SDK版本：

请参照下载C-SDK获取最新的SDK。

根证书和TLS库：

根证书和mbed TLS库位于external目录下，需要移植两者（或整个sdk）到开发环境中。

external/
├── ali_ca_cert.c
└── mbedtls

SDK中有诸多原子能力，请根据实际使用了哪些原子能力，来判断如何升级。

MQTT/物模型：

需要在原有代码中找到使用AIOT_MQTTOPT_PORT配置项的地方，修改端口的值：

const uint16_t port = 8883;
aiot_mqtt_setopt(mqtt_handle, AIOT_MQTTOPT_PORT, (void *)&port);
说明

若当前设备已经通过8883端口连云，并且没有用到如下的http/bootstrap/CoAP/OTA等功能，则不需要更新设备固件。

基于HTTP的动态注册（参考demos/dynreg_basic_demo.c）:

需要在原有代码中新增如下两句，将host从iot-auth.{region}.aliyuncs.com指向iot-auth-x.{region}.aliyuncs.com，比如：

char       *host = "iot-auth-x.cn-shanghai.aliyuncs.com"; 

int res = aiot_dynreg_setopt(dynreg_handle, AIOT_DYNREGOPT_HOST, (void *)host);

引导服务bootstrap（参考demos/bootstrap_posix_demo.c）：

需要修改bootstrap的接入点，将默认的接入点从iot-auth-global.aliyuncs.com改成iot-auth-global-x.aliyuncs.com。修改方式为在原有代码中新增如下两句：

char *bootstrap_host = "iot-auth-global-x.aliyuncs.com";

int res = aiot_bootstrap_setopt(bootstrap_handle, AIOT_BOOTSTRAPOPT_HOST, (void *)bootstrap_host);

CoAP（参考demos/coap_basic_demo.c）：

需要在原有代码中新增如下两句，将host从iot-auth.{region}.aliyuncs.com指向iot-auth-x.{region}.aliyuncs.com，

char  *host             = "iot-*****-x.coap.iothub.aliyuncs.com";

aiot_coap_setopt(coap_handle, AIOT_COAPOPT_HOST, host);

HTTP连云（参考demos/http_basic_demo.c）：

需要将host从iot-auth.{region}.aliyuncs.com指向iot-auth-x.{region}.aliyuncs.com，修改方式为在原有代码中加上如下两句：

char  *http_host = "iot-****-x.http.iothub.aliyuncs.com";

aiot_http_setopt(http_handle, AIOT_HTTPOPT_HOST, (void *)http_host);

OTA（参考demos/fota_basic_demo.c）：

需要更新external/ali_ca_cert.c和external/mbedtls

2.3.0

确认我之前产品开发使用的SDK是否是2.3.0：

在升级前，需要确认之前存量设备开发时所使用的SDK是否为2.3.0。确认方式是看是否存在include/iot_export.h这样一个文件，并且其中包含如下内容。如果不是，则跳过本节。

#define LINKKIT_VERSION     "2.3.0"

SDK下载：

git clone https://github.com/aliyun/iotkit-embedded.git -b v2.3.0

根证书和TLS库：

根证书位于src/infra/system/ca.c，mbedtls库位于src/ref-impl/tls，用户需要移植这两者（或整个sdk）到开发环境中。

MQTT：

    int userPort=8883;
    IOT_Ioctl(IOTX_IOCTL_SET_MQTT_PORT, &userPort);

动态注册和预认证：

#define CUSTOME_DOMAIN_HTTP     "iot-auth-x.{region}.aliyuncs.com"

IOT_Ioctl(IOTX_IOCTL_SET_HTTP_DOMAIN, (void *)CUSTOME_DOMAIN_HTTP);

其中region字段要替换成您物联网实例所属的region。

OTA：

无需修改用户代码，但要确保根证书和tls库按照上述要求更新。

3.1.0/3.2.0

确认我之前产品开发使用的SDK是否是3.1.0/3.2.0：

在升级前，需要确认之前存量设备开发时所使用的SDK是否为3.1.0/3.2.0。确认方式是看是否存在./src/infra/infra_defs.h这样一个文件，并且其中包含如下内容。如果不是，则跳过本节。

#define IOTX_SDK_VERSION                "3.1.0"
或者
#define IOTX_SDK_VERSION                "3.2.0"

SDK下载：

git clone https://github.com/aliyun/iotkit-embedded.git -b v3.2.0
git clone https://github.com/aliyun/iotkit-embedded.git -b v3.1.0

根证书和TLS库：

根证书位于certs/root_ca.c，mbedtls库位于external_libs/mbedtls，用户需要移植这两者（或整个sdk）到开发环境中。

MQTT：

    int userPort=8883;
    IOT_Ioctl(IOTX_IOCTL_SET_MQTT_PORT, &userPort);

动态注册和预认证：

#define CUSTOME_DOMAIN_HTTP     "iot-auth-x.{region}.aliyuncs.com"

IOT_Ioctl(IOTX_IOCTL_SET_HTTP_DOMAIN, (void *)CUSTOME_DOMAIN_HTTP);

其中region字段要替换成您物联网实例所属的region。

OTA：

无需修改用户代码，但要确保根证书和tls库按照上述要求更新。

3.0.1

确认我之前产品开发使用的SDK是否是3.0.1：

在升级前，需要确认之前存量设备开发时所使用的SDK是否为3.0.1。确认方式是看是否存在./src/infra/infra_defs.h这样一个文件，并且其中包含如下内容。如果不是，则跳过本节。

#define IOTX_SDK_VERSION                "3.0.1"

SDK下载：

git clone https://github.com/aliyun/iotkit-embedded.git -b v3.0.1

MQTT连接, 根证书和TLS库：

根证书位于certs/root_ca.c，mbedtls库位于external_libs/mbedtls，用户需移植整个SDK到开发环境中，或者参照GitHub中的commitId (0d3beeedb31a39f4b54fb4c521e8ce63f23e817c)进行修改

动态注册和预认证：

#define CUSTOME_DOMAIN_HTTP     "iot-auth-x.{region}.aliyuncs.com"

IOT_Ioctl(IOTX_IOCTL_SET_HTTP_DOMAIN, (void *)CUSTOME_DOMAIN_HTTP);

其中region字段要替换成您物联网实例所属的region。

OTA：

无需修改用户代码，但要确保根证书和tls库按照上述要求更新。

5.x Extended扩展版

确认我之前产品开发使用的SDK是否是5.x：

在升级前，需要确认之前存量设备开发时所使用的SDK是否为5.x。确认方式是看是否存在device-core和device-module两个文件夹。如果不存在，则跳过本节。

SDK版本：获取SDK

  • 版本号：1.0.1

  • 日期：2026-07-14

  • 下载链接：https://linkkit-export.oss-cn-shanghai.aliyuncs.com/c-sdk-ext/publish/aliyun-iot-device-c-extend-1.0.1.zip

  • 新增特性：1. 支持并默认使用新证书域名； 2. 增加R46证书

其他版本的C-SDK：

如果您的SDK不在上述范围内，请提工单咨询。

Android SDK

SDK版本：

1.7.3.5 或更高版本，参考发布记录。

用户代码变更：

  • MQTT连云：

    请参考认证与连接，使用8883端口。

    MqttConfigure.mqttHost = "{YourInstanceId}.mqtt.iothub.aliyuncs.com:8883";

或者

IoTMqttClientConfig clientConfig = new IoTMqttClientConfig();
clientConfig.channelHost = "a18wP******.iot-as-mqtt.cn-shanghai.aliyuncs.com:8883";
linkKitInitParams.mqttClientConfig = clientConfig;

  • 动态注册：

    如果您的代码中使用了已废弃（deprecated）的动态注册接口（基于HTTP协议）

     deviceRegister(LinkKitInitParams initParams, CommonRequest request, IoTCallback listener)

    请改用基于MQTT的新版动态注册接口

    deviceDynamicRegister(MqttInitParams initParams, IOnCallListener listener)

    具体使用方式请参考认证与连接。

Python SDK

SDK版本：

1.2.11或更高版本，参考发布记录。

用户代码变更：

  • MQTT连云：

    请参考认证与连接，使用8883端口。

    lk.config_mqtt(port=8883, protocol="MQTTv311", transport="TCP",
            secure="TLS", keep_alive=60, clean_session=True,
            max_inflight_message=20, max_queued_message=0,
            auto_reconnect_min_sec=1,
            auto_reconnect_max_sec=60,
            check_hostname=True,   
            cadata=None)

  • 动态注册：

    如果您的代码中使用了已废弃（deprecated）的动态注册方式（device_secret为空字符串或未赋值，同时auth_type字段为空字符串或未赋值）。

    lk_auth = linkkit.LinkKit(
    host_name="cn-shanghai",
    product_key=product_key,
    device_name=device_name,
    device_secret="",
    auth_type="",
    instance_id=instance_id,
    product_secret=product_secret)

    请将auth_type修改为"register"，以使用基于MQTT的新版动态注册方式。

Java SDK

SDK版本：

1.2.3.7 或更高版本，参考发布记录。

用户代码变更：

  • MQTT连云：

    请参考认证与连接，使用8883端口。

    MqttConfigure.mqttHost = "{YourInstanceId}.mqtt.iothub.aliyuncs.com:8883";

或者

IoTMqttClientConfig clientConfig = new IoTMqttClientConfig();
clientConfig.channelHost = "a18wP******.iot-as-mqtt.cn-shanghai.aliyuncs.com:8883";
linkKitInitParams.mqttClientConfig = clientConfig;

  • 动态注册：

    如果您的代码中使用了已废弃（deprecated）的动态注册接口（基于HTTP协议）

     deviceRegister(LinkKitInitParams initParams, CommonRequest request, IoTCallback listener)

    请改用基于MQTT的新版动态注册接口

    deviceDynamicRegister(MqttInitParams initParams, IOnCallListener listener)

    具体使用方式请参考认证与连接。

iOS SDK

SDK版本：

不变

用户代码变更：

  • MQTT连云：

    参照协议文档，修改接入域名，参考原有认证与连接，其中参考的接入方式如下：

    #import <IotLinkKit/IotLinkKit.h>

    //初始化前请先注册监听器，监听长连接通道的连接状态变化
    [[LinkKitEntry sharedKit] registerChannelListener:self];

    ////输入设备认证信息
    self.productKey = self.textFieldProductKey.text ;
    self.deviceName = self.textFieldDeviceName.text ;
    self.deviceSecret = self.textFieldDeviceSecret.text;

    LinkkitChannelConfig * channelConfig = [[LinkkitChannelConfig alloc] init];
    channelConfig.productKey = self.productKey;
    channelConfig.deviceName = self.deviceName;
    channelConfig.deviceSecret = self.deviceSecret;
    channelConfig.cleanSession = (self.cleanSession == 1);
    //channelConfig.server = @"your custom server url";
    //channelConfig.port = 1883;
    LinkkitSetupParams * setupParams = [[LinkkitSetupParams alloc] init];
    setupParams.appVersion = self.appVersion;
    setupParams.channelConfig = channelConfig;
    [[LinkKitEntry sharedKit] setup:setupParams resultBlock:^(BOOL succeeded, NSError * _Nullable error) {
        LinkkitLogDebug(@"setup error : %@", error);
        dispatch_async(dispatch_get_main_queue(), ^{
            [self ims_showHUDWithMessage:[NSString stringWithFormat:@"Linkkit 初始化 : %@",
                                          succeeded ? @"成功" : @"失败"]];
        });
    }];

    其中第16行的channelConfig.server，字段不能再用默认值，必须将其显式地指向新的接入地址。

    • 如果您的实例是公共实例（设备接入域名是a18wP******.iot-as-mqtt.cn-shanghai.aliyuncs.com这种格式），代码中要调用channelConfig.server = a18wP********-x.iot-as-mqtt.cn-shanghai.aliyuncs.com来指定新的接入点，注意域名前缀中必须带上-x的结尾。

    • 如果您的实例是企业实例(设备接入域名是iot-06*****l.mqtt.iothub.aliyuncs.com这种格式)，代码中要调用channelConfig.server = iot-06*****l-x.mqtt.iothub.aliyuncs.com来指定新的接入点，注意域名前缀中必须带上-x的结尾。

JS SDK

SDK版本：

不变

用户代码变更：

  • MQTT连云：

    需要显式指定brokerUrl。

    const iot = require('alibabacloud-iot-device-sdk');
const device = iot.device({
  productKey: `${productKey}`,
  deviceName: `${deviceName}`,
  deviceSecret: `${deviceSecret}`,
  brokerUrl: `wss://${productKey}-x.iot-as-mqtt.${regionId}.aliyuncs.com:443`,
});
​
device.on('connect', () => {
  console.log('connect sucessfully!');
});

    注意brokerUrl字段需要带-x后缀，比如${productKey}-x.iot-as-mqtt.${regionId}.aliyuncs.com（公共实例），或者"iot-******-x.http.iothub.aliyuncs.com" （企业实例）

  • 动态注册：

    需要显式指定registerURL字段

    const iot = require('alibabacloud-iot-device-sdk');
const params = {
  productKey: `${productKey}`,
  productSecret: `${productSecret}`,
  deviceName: `${deviceName}`,
  registerURL: 'https://iot-auth-x.cn-shanghai.aliyuncs.com/auth/register/device'
};
let device;
iot.register(params, (res) => {
  console.log("register:", res);
  if (res.code == '200') {
    // res.data.deviceSecret 是物联网平台返回的设备密钥，请妥善保存该密钥，
    // 设备使用设备认证信息连接物联网平台成功后，不可再次使用本函数获取DeviceSecret。
    // 创建设备对象连接阿里云物联网平台
    device = iot.device({
      productKey: `${productKey}`,
      deviceName: `${deviceName}`,
      // res.data.deviceSecret 是物联网平台返回的设备密钥
      deviceSecret: res.data.deviceSecret,
    });
  }
});

    注意registerURL字段需要带-x后缀。

    package.json中要增加的内容：

      "overrides": {
    "mqtt": "^4.3.8"
  }

注意事项

需要确保TLS库开启了SNI功能

当前的C-SDK的tls库(mbedtls)默认都开启了SNI功能(server name indication)，用以支持上述提到的新域名和OSS的cdn下载。具体见mbedtls库中的config.h文件，其中的如下的宏是打开的。

#define MBEDTLS_SSL_SERVER_NAME_INDICATION

如果用户使用其他TLS库，需要确保SNI功能也是打开的，否则会导致连接失败。

上一篇：阿里云IoT平台根证书更新方案下一篇：注册产品