认证说明
一、设备动态注册
URL模板:
https://${域名}/auth/register/device
HTTP方法:POST
请求数据格式:
POST /auth/register/device HTTP/1.1
Content-Type: application/x-www-form-urlencoded
productKey=a1234******&deviceName=deviceName1234&random=567345&sign=adfv123hdfdh&signMethod=HmacMD5
请求参数说明
参数 | 类型 | 说明 |
---|---|---|
Method | String | POST |
Content-Type | String | application/x-www-form-urlencoded |
productKey | String | 产品唯一标识。 |
deviceName | String | 动态注册时,此参数为设备的唯一标识,如:设备 sn、设备 Mac 等。接口返回的 deviceName 才是设备真实设备名。 |
random | String | 随机数。 |
sign | String | 签名。加签方法:将所有提交给服务器的参数(sign、signMethod除外)按照字母顺序排序,然后将参数和值依次拼接(无拼接符号)。通过signMethod指定的加签算法,使用产品的ProductSecret,对加签内容进行加签。加签计算示例如下:hmac_sha1(productSecret, deviceNamedeviceName1234productKeya1234******random123) |
signMethod | String | 签名方法,目前支持hmacmd5、hmacsha1、hmacsha256。 |
响应数据格式:
{
"code": 200,
"data": {
"productKey": "a1234******",
"deviceName": "deviceName1234",
"deviceSecret": "adsfw******"
},
"message": "success"
}
响应参数说明
参数 | 类型 | 说明 |
---|---|---|
code | Integer | 结果信息,200 为成功 |
productKey | String | 产品唯一标识。 |
deviceName | String | 设备名,用于设备 mqtt 认证参数。 |
deviceSecret | String | 设备密钥,用于设备 mqtt 认证密码签名 |
二、MQTT连接认证
设备或网关设备与物联网平台通过MQTT协议连接通信,在进行通信前,设备必须与MQTT服务端进行认证,认证通过后,设备才能发布和订阅消息,本文主要对MQTT CONNECT协议规范进行说明。
在进行MQTT CONNECT协议设置时,需注意:
- 如果同一个设备证书(ProductKey、DeviceName和DeviceSecret)同时用于多个物理设备连接,可能会导致客户端频繁上下线。因为新设备连接认证时,原设备会被迫下线,而设备被下线后,又会自动尝试重新连接。
- (可选)为保障通信安全,推荐使用TLS加密的连接方式。
认证协议规范
建议直接使用物联网平台提供的设备SDK接入物联网平台,如果需要自行开发接入,连接参数如下。
1、参数:接入域名、IP 。根据具体的平台部署情况,选择合适的地址接入
2、参数:可变报头(variable header):Keep Alive。
CONNECT指令中需包含Keep Alive(保活时间)。保活心跳时间取值范围为30秒~1200秒,建议取值300秒以上。若网络不稳定,请将心跳时间设置长一些。如果心跳时间不在保活时间内,物联网平台会拒绝连接。
3、参数:MQTT的CONNECT报文。
一机一密设备认证方式:使用设备证书(ProductKey、DeviceName和DeviceSecret)连接。
一型一密预注册设备,需要先从平台获取设备证书(ProductKey、DeviceName和DeviceSecret),完成获取设备证书后, 认证方式同一机一密设备认证。
所以,一机一密设备认证,一型一密预注册设备认证最终的MQTT连接认证方式相同。
参数如下:
mqttClientid: clientId+"|clienttype=0,signmethod=hmacmd5,timestamp=132323232|"
mqttUsername: deviceName+"&"+productKey
mqttPassword: sign_hmac(deviceSecret,content)
- mqttClientId:格式中
| |
内为扩展参数,如果没有扩展参数或者全为默认值,只需要传递原始 clientId。 - mqttUsername:productKey 和 deviceName 使用 “&”拼接。
- mqttPassword:sign签名需把提交给服务器的参数按字典排序后,根据signmethod加签。签名计算示例下文有说明,对于低功耗设备,可以只传前16位。
参数 | 说明 |
---|---|
clientId | 表示客户端ID,可自定义,长度不可超过64个字符。建议使用设备的MAC地址或SN码,方便您识别区分不同的客户端。 |
clienttype | 标识客户端类型,0:直连设备/网关设备,1:appuser,app端用户认证(app也是作为一个通用设备接入mqtt组件中), 2:web模拟器模拟设备连接认证(需要校验时间)。可不传,如果不传则默认为0。 |
signmethod | 表示签名算法类型。支持hmacmd5,hmacsha1和hmacsha256,默认为hmacmd5。 |
timestamp | 表示当前时间毫秒值,添加了此参数重连时需要重新签名,可选。 |
encoding | 消息内容编码方式,支持 plain(原始)、hex(16进制)、base64,当然也可以指定字符集,如:plain_gb2312 |
注意: mqttPassword 签名 content 的值为提交给服务器的参数(productKey、deviceName、clientId、timestamp),按照参数名称首字母字典排序, 然后将参数值依次拼接。
示例:
假设clientId = 12345,deviceName = device, productKey = pk, timestamp = 789,signmethod=hmacmd5,deviceSecret=secret123
,那么使用TCP方式提交给MQTT的参数如下:
mqttclientId=12345|signmethod=hmacmd5,timestamp=789|
mqttUsername=device&pk
mqttPassword=hmacmd5("secret123","clientId12345deviceNamedeviceproductKeypktimestamp789";
加密后的Password的值示例为:566bcda5123424ce529006afd27bbf7b