本文描述ID2接口在設備端如何使用。ID2 Client SDK封裝了底層對ID2載體和接口的操作細節，應用只需調用該接口進行相關操作，即可訪問設備端的ID2服務。

初始化

  • 函數原型：int id2_client_init(void)。
  • 功能描述：ID2 Client SDK初始化。使用ID2設備端其它API之前，需先調用該API進行初始化操作。
  • 參數描述：無。
  • 返回值：成功時返回0；其他返回值，請參考設備端錯誤碼。

獲取ID2

  • 函數原型：int id2_client_get_id(uint8_t* id, uint32_t* len)。
  • 功能描述：獲取ID2字符串。
  • 參數描述：
    參數 參數類型 描述
    id 輸出參數 存放ID2字符串的起始地址，長度不小于24個字節。
    len 輸入參數和輸出參數 輸入參數為ID2的buf長度，輸出參數為ID2字符串的實際長度。
  • 返回值：成功時返回0；其他返回值，請參考設備端錯誤碼。

以挑戰應答模式獲取設備認證碼

  • 函數原型：int id2_client_get_challenge_auth_code(const char* challenge, const uint8_t* extra, uint32_t extra_len, uint8_t* auth_code, uint32_t* auth_code_len)。
  • 功能描述：基于挑戰應答模式生成設備端認證碼。可選擇攜帶額外數據extra，攜帶的extra數據參與設備認證碼的簽名運算。
  • 參數描述：
    參數 參數類型 描述
    challenge 輸入參數 挑戰字起始地址，由SP Server從ID2 Server獲取。
    extra 輸入參數 可選參數。額外數據起始地址，由Device和SP Server根據某種約定分別生成。
    extra_len 輸入參數 額外數據長度，最大長度512字節。
    auth_code 輸出參數 設備認證碼起始地址，長度不小于256字節。
    auth_code_len 輸入參數和輸出參數 輸入參數為authCode的buf長度，輸出參數為設備認證碼的實際長度。
  • 返回值：成功時返回0；其他返回值，請參考設備端錯誤碼。
  • 交互流程圖：1

以時間戳模式獲取設備認證碼

  • 函數原型：int id2_client_get_timestamp_auth_code(const char* timestamp, const uint8_t* extra, uint32_t extra_len, uint8_t* auth_code, uint32_t* auth_code_len)。
  • 功能描述：基于時間戳模式生成設備端認證碼，可選擇攜帶額外數據extra，攜帶的extra數據參與設備認證碼的簽名運算。時間戳可以由設備端RTC生成，或者由SP Server攜帶發送給設備端。
  • 參數描述：
    參數 參數類型 描述
    timestamp 輸入參數 當前系統時間（從1970年1月1日午夜開始經過的毫秒數），時間戳格式，如1500954672653。
    extra 輸入參數 可選參數。額外數據起始地址，由Device和SP Server根據某種約定分別生成。
    extra_len 輸入參數 額外數據長度，最大長度512字節。
    auth_code 輸出參數 設備認證碼起始地址，長度不小于256字節。
    auth_code_len 輸入參數和輸出參數 輸入參數為authCode的buf長度，輸出參數為設備認證碼的實際長度。
  • 返回值：成功時返回0；其他返回值，請參考設備端錯誤碼。
  • 交互流程圖：2

ID2解密

  • 函數原型：int id2_client_decrypt(const uint8_t* in, uint32_t in_len, uint8_t* out, uint32_t* out_len)。
  • 功能描述：使用ID2解密指定的數據。
  • 參數描述：
    參數 參數類型 描述
    in 輸入參數 待解密的數據起始地址。數據如果是base64編碼，需要先進行base64解碼。
    in_len 輸入參數 待解密的數據長度，不超過512字節。
    out 輸出參數 解密后的數據起始地址。
    out_len 輸入參數和輸出參數 輸入參數為參數out的buf長度，輸出參數為解密后的數據長度。
  • 返回值：成功時返回0；其他返回值，請參考設備端錯誤碼。

獲取設備燒錄狀態

  • 函數原型：irot_result_t id2_client_get_prov_stat(bool *is_prov)。
  • 功能描述：獲取設備端ID2的燒錄狀態。
  • 參數描述：
    參數 參數類型 描述
    is_prov 輸出參數 布爾類型，存放ID2的燒錄狀態。
  • 返回值：成功時返回0；其他返回值，請參考設備端錯誤碼。

獲取設備動態下發認證碼

  • 函數原型：irot_result_t id2_client_get_otp_auth_code(const uint8_t *token, uint32_t token_len, uint8_t *auth_code, uint32_t *len)。
  • 功能描述：獲取設備端ID2動態下發的認證碼。
  • 參數描述：
    參數 參數類型 描述
    token 輸入參數 ID2 Server頒發的動態下發token，可在ID2控制臺的產品詳情頁獲取。
    token_len 輸入參數 ID2動態下發token的長度，固定值32字節。
    auth_code 輸出參數 ID2動態下發認證碼的內存，長度小于256字節。
    len 輸入參數和輸出參數 輸入參數為authCode的內存大小，輸出參數為認證碼的實際長度。
  • 返回值：成功時返回0；其他返回值，請參考設備端錯誤碼。

燒錄動態下發數據

  • 函數原型：irot_result_t id2_client_load_otp_data(const uint8_t *otp_data, uint32_t len)。
  • 功能描述：燒錄動態下發數據到設備中。
  • 參數描述：
    參數 參數類型 描述
    otp_data 輸入參數 ID2 Server下發的動態下發數據包。
    len 輸入參數 ID2動態下發數據包的長度。
  • 返回值：成功時返回0；其他返回值，請參考設備端錯誤碼。