消息队列 MQTT 版 C SDK

功能概述
Eclipse Paho C 与 Eclipse Paho Embedded C 均为 Eclipse Paho 项目下的 C 语言客户端库（MQTT C Client），均为使用 ANSI C 编写的功能齐全的 MQTT 客户端。
Eclipse Paho Embedded C 可以在桌面操作系统上使用，但主要针对 Mbed，Arduino 和 FreeRTOS 等嵌入式环境。
该客户端有同步/异步两种 API ，分别以 MQTTClient 和 MQTTAsync 开头：
同步 API 旨在更简单，更有用，某些调用将阻塞直到操作完成为止，使用编程上更加容易。
异步 API 中只有一个调用块 API-waitForCompletion ，通过回调进行结果通知，更适用于非主线程的环境。
云资源准备
请您先参见 创建资源 操作步骤完成云资源准备。
环境准备
注意：
Paho MQTT C SDK 需要 CMake 版本3.5+。
安装 paho.mqtt.c SDK 示例
 git clone https://github.com/eclipse-paho/paho.mqtt.c.git﻿
 cd paho.mqtt.c && cmake .
 make && make install
 echo '/usr/local/lib64' > /etc/ld.so.conf.d/paho.conf
 echo '/usr/local/lib' >> /etc/ld.so.conf.d/paho.conf
 ldconfig
示例代码
将下面内容复制到 /root/mqtt-example.c
#include "stdio.h"
#include "stdlib.h"
#include "string.h"
﻿
#include "MQTTClient.h"
﻿
#define ADDRESS     "tcp://mqtt-********.mqtt.tencenttdmq.com:1883"
#define CLIENTID    "sample_client"
#define TOPIC       "testtopic/1"
#define PAYLOAD     "Hello World!"
#define QOS         1
#define TIMEOUT     10000L
#define USERNAME    "your-username"
#define PASSWORD    "your-password"
﻿
int main(int argc, char* argv[])
{
    MQTTClient client;
    MQTTClient_connectOptions conn_opts = MQTTClient_connectOptions_initializer;
    MQTTClient_message pubmsg = MQTTClient_message_initializer;
    MQTTClient_deliveryToken token;
    int rc;
﻿
    MQTTClient_create(&client, ADDRESS, CLIENTID,
        MQTTCLIENT_PERSISTENCE_NONE, NULL);
  
    // MQTT 连接参数
    conn_opts.keepAliveInterval = 20;
    conn_opts.cleansession = 1;
    conn_opts.MQTTVersion = MQTTVERSION_3_1_1;
    conn_opts.username = USERNAME;
    conn_opts.password = PASSWORD;
﻿
    if ((rc = MQTTClient_connect(client, &conn_opts)) != MQTTCLIENT_SUCCESS)
    {
        printf("Failed to connect, return code %d\\n", rc);
        exit(-1);
    }
  
    // 发布消息
    pubmsg.payload = PAYLOAD;
    pubmsg.payloadlen = strlen(PAYLOAD);
    pubmsg.qos = QOS;
    pubmsg.retained = 0;
    MQTTClient_publishMessage(client, TOPIC, &pubmsg, &token);
    printf("Waiting for up to %d seconds for publication of %s\\n"
            "on topic %s for client with ClientID: %s\\n",
            (int)(TIMEOUT/1000), PAYLOAD, TOPIC, CLIENTID);
    rc = MQTTClient_waitForCompletion(client, token, TIMEOUT);
    printf("Message with delivery token %d delivered\\n", token);
  
    // 断开连接
    MQTTClient_disconnect(client, 10000);
    MQTTClient_destroy(&client);
    return rc;
}
参数说明
参数
说明
ADDRESS
broker 连接地址，在控制台目标集群基本信息 > 接入信息模块中复制。位置如下图所示。格式：mqtt-xxx-gz.mqtt.qcloud.tencenttdmq.com:1883。
﻿
CLIENTID
客户端 ID，在控制台集群详情页客户端管理页面获取。
﻿
USERNAME
连接至集群使用的用户名，需提前创建。
PASSWORD
连接用户名匹配的密码。
编译示例
cd /root
gcc mqtt-example.c -lpaho-mqtt3c -o mqtt-example
Paho C MQTT 5.0 支持
目前 Paho C 已经完整支持 MQTT 5.0。
﻿
一机一证示例
场景介绍
对于高价值设备等安全要求较高的场景, 建议使用“一机一证”的方式对客户端认证。“一机一证”是双向认证 mTLS 的加强：在双向认证的基础上，云端对设备客户端证书的状态进行管理，包括激活、取消激活、吊销等操作。
生成证书
生成 CA 证书
ECDSA
RSA
openssl ecparam -genkey -name prime256v1 -out CA.key
openssl req -new -x509 -key CA.key -sha256 -subj "/C=CN/ST=ZheJiang/L=HangZhou/O=TencentCloud/CN=MQTT-CA" -days 3650 -out CA.crt
openssl genrsa -out CA.key 2048
openssl req -new -x509 -key CA.key -sha256 -subj "/C=CN/ST=ZheJiang/L=HangZhou/O=TencentCloud/CN=MQTT-CA" -days 3650 -out CA.crt
验证 CA 证书
your_registration_code 指注册码，可在注册 CA 证书的弹窗中获取，详情请参考配置 CA 证书。
ECDSA
RSA
openssl ecparam -genkey -name prime256v1 -out VerificationCert.key
openssl req -new -key VerificationCert.key -out VerificationCert.csr -subj "/C=CN/ST=ZheJiang/L=HangZhou/O=IoV/CN=your_registration_code"
openssl x509 -req -in VerificationCert.csr -CA CA.crt -CAkey CA.key -CAcreateserial -out VerificationCert.crt -days 3 -sha256
openssl genrsa -out VerificationCert.key 4096
openssl req -new -key VerificationCert.key -out VerificationCert.csr -subj "/C=CN/ST=ZheJiang/L=HangZhou/O=Tencent/OU=IT/CN=your_registration_code"
openssl x509 -req -in VerificationCert.csr -CA CA.crt -CAkey CA.key -CAcreateserial -out VerificationCert.crt -days 600 -sha512
签发服务端证书
创建配置文件 server.conf
[req]
distinguished_name = req_distinguished_name
req_extensions = v3_req
prompt = no
﻿
[req_distinguished_name]
C = CN
ST = ZheJiang
L = HangZhou
O = Example
CN = mqtt.example.com
﻿
[v3_req]
basicConstraints = critical, CA:FALSE
# Common Key Usage Combinations
#   TLS Server: keyUsage=digitalSignature,keyEncipherment + extendedKeyUsage=serverAuth
#   TLS Client: keyUsage=digitalSignature + extendedKeyUsage=clientAuth
#   Code Signing: keyUsage=digitalSignature + extendedKeyUsage=codeSigning
keyUsage = critical, digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names
﻿
[alt_names]
DNS.1 = mqtt.example.com
DNS.2 = www.example.com
DNS.3 = api.example.com
DNS.4 = *.example.com
IP.1 = 192.168.1.100
IP.2 = 10.0.0.50
﻿
ECDSA
RSA
openssl ecparam -genkey -name prime256v1 -out server.key
openssl req -new -key server.key -out server.csr -config server.conf
openssl x509 -req -in server.csr -CA CA.crt -CAkey CA.key -CAcreateserial -out server.crt -days 365 -sha256 -extensions v3_req -extfile server.conf
openssl genrsa -out server.key 2048
openssl req -new -key server.key -out server.csr -config server.conf
openssl x509 -req -in server.csr -CA CA.crt -CAkey CA.key -CAcreateserial -out server.crt -days 365 -sha256 -extensions v3_req -extfile server.conf
验证服务端证书
openssl x509 -in server.crt -text -noout
openssl verify -CAfile CA.crt server.crt
openssl x509 -in server.crt -text -noout | grep -A 10 "Subject Alternative Name"
创建完整服务端证书链文件
cat server.crt > server.chain.crt
cat CA.crt >> server.chain.crt
签发客户端证书
创建配置文件 client.conf
[v3_req]
basicConstraints = critical, CA:FALSE
keyUsage = critical, digitalSignature
extendedKeyUsage = clientAuth
﻿
ECDSA
RSA
openssl ecparam -genkey -name prime256v1 -out client.key
openssl req -new -key client.key -out client.csr -subj "/C=CN/ST=ZheJiang/L=HangZhou/O=IoV/CN=SN0001"
openssl x509 -req -in client.csr -CA CA.crt -CAkey CA.key -CAcreateserial -out client.crt -days 365 -sha256 -extfile client.conf -extensions v3_req
openssl genrsa -out client.key 2048
openssl req -new -key client.key -out client.csr -subj "/C=CN/ST=ZheJiang/L=HangZhou/O=IoV/CN=SN0001"
openssl x509 -req -in client.csr -CA CA.crt -CAkey CA.key -CAcreateserial -out client.crt -days 365 -sha256 -extfile client.conf -extensions v3_req
﻿
配置 MQTT 实例为一机一证模式
配置服务端证书
1. 登录 MQTT 控制台。
2. 在左侧导航栏单击资源管理 > 集群管理，选择好地域后，单击要配置证书的集群的“ID”，进入集群基本信息页面。
3. 在认证管理页面，进入 X.509 证书管理页签，单击右侧的编辑图标 
﻿
，在弹窗中完成证书配置。
认证方式：选择 “一机一证” 选项。
服务端证书配置：可以使用 MQTT 提供的默认服务端证书，也可以后续绑定自定义证书。详情请参考配置服务端证书。
CA 证书配置：当前仅支持手动上传 CA 证书并注册。开启一机一证认证后，在集群详情页面的 CA 证书管理页面添加 CA 证书。详情请参考配置 CA 证书﻿
客户端证书配置：支持自动注册和手动注册两种方式。详情请参考配置客户端证书。
自动注册：客户端在连接时自动注册客户端证书，只需要将客户端证书关联的 CA 证书手动注册即可。
手动注册：客户端在连接前，需要手动在客户端证书管理页面先手动上传并注册客户端证书。
﻿
﻿
配置 CA 证书
﻿
注册 CA 证书, 需签发一份验证证书, Common Name 为给定的随机值即注册码
﻿
﻿
﻿
配置 CNAME
服务端证书 Subject Alternative Name 扩展中包含以下几个域名:
DNS.1 = mqtt.example.com
DNS.2 = www.example.com
DNS.3 = api.example.com
DNS.4 = *.example.com
域名系统增加 CNAME 记录, 将 mqtt.example.com 指向实例接入点:  mqtt-xxxx-nj-public.mqtt.tencenttdmq.com.
测试环境下, 也可以修改本地 hosts 文件, 将 mqtt.example.com 指向接入点的 IP 地址.
验证域名、证书及一机一证配置
openssl s_client -connect mqtt.example.com:8883 -CAfile CA.crt -cert client.crt -key client.key  -verify_hostname mqtt.example.com
应输出类似下面结果
Connecting to 109.244.152.235
CONNECTED(00000005)
depth=1 C=CN, ST=ZheJiang, L=HangZhou, O=TencentCloud, CN=MQTT-CA
verify return:1
depth=0 C=CN, ST=ZheJiang, L=HangZhou, O=Example, CN=mqtt.example.com
verify return:1
---
Certificate chain
 0 s:C=CN, ST=ZheJiang, L=HangZhou, O=Example, CN=mqtt.example.com
   i:C=CN, ST=ZheJiang, L=HangZhou, O=TencentCloud, CN=MQTT-CA
   a:PKEY: RSA, 4096 (bit); sigalg: sha256WithRSAEncryption
   v:NotBefore: Jul 24 02:48:06 2025 GMT; NotAfter: Jul 24 02:48:06 2026 GMT
 1 s:C=CN, ST=ZheJiang, L=HangZhou, O=TencentCloud, CN=MQTT-CA
   i:C=CN, ST=ZheJiang, L=HangZhou, O=TencentCloud, CN=MQTT-CA
   a:PKEY: RSA, 4096 (bit); sigalg: sha256WithRSAEncryption
   v:NotBefore: Jul 24 02:47:18 2025 GMT; NotAfter: Jul 22 02:47:18 2035 GMT
---
Server certificate
...
Acceptable client certificate CA names
...
---
SSL handshake has read 3950 bytes and written 5058 bytes
Verification: OK
Verified peername: mqtt.example.com
---
New, TLSv1.3, Cipher is TLS_AES_256_GCM_SHA384
Protocol: TLSv1.3
Server public key is 4096 bit
This TLS version forbids renegotiation.
Compression: NONE
Expansion: NONE
No ALPN negotiated
Early data was not sent
Verify return code: 0 (ok)
开发环境
安装依赖
以 Ubuntu 24.04.2 LTS 为例:
apt install build-essential openssl libssl-dev cmake wget dnsutils -y
安装 paho.mqtt.c
wget https://github.com/eclipse-paho/paho.mqtt.c/archive/refs/tags/v1.3.14.tar.gz
tar -xzvf v1.3.14.tar.gz 
cd paho.mqtt.c-1.3.14/
mkdir _build && cd _build
cmake -DPAHO_WITH_SSL=true .. && make && make install
一机一证示例文件
详情可单击 byoc-demo。
编译
tar -xzvf byoc-demo.tar.gz
cd byoc-demo && mkdir _build && cmake .. && make
运行
./paho_cs_pub -t home -i c_client_byoc -V 5 --cafile /root/byoc-test/CA.crt --cert /root/byoc-test/client.crt --key /root/byoc-test/client.key -c ssl://mqtt.example.com:8883 --trace protocol
控制台验证
客户端列表页面, 可以查看到使用"一机一证”连接至集群的客户端
﻿
客户端证书管理页面, 客户端证书已自动注册
﻿
﻿
参数	说明
ADDRESS	broker 连接地址，在控制台目标集群基本信息 > 接入信息模块中复制。位置如下图所示。格式：`mqtt-xxx-gz.mqtt.qcloud.tencenttdmq.com:1883`。
CLIENTID	客户端 ID，在控制台集群详情页客户端管理页面获取。
USERNAME	连接至集群使用的用户名，需提前创建。
PASSWORD	连接用户名匹配的密码。
C SDK

本页目录：

功能概述

云资源准备

环境准备

安装 paho.mqtt.c SDK 示例

示例代码

参数说明

编译示例

Paho C MQTT 5.0 支持

一机一证示例

场景介绍

生成证书

生成 CA 证书

验证 CA 证书

签发服务端证书

﻿

验证服务端证书

签发客户端证书

配置 MQTT 实例为一机一证模式

配置服务端证书

配置 CA 证书

配置 CNAME

验证域名、证书及一机一证配置

开发环境

安装依赖

安装 paho.mqtt.c

一机一证示例文件

编译

运行

控制台验证
