mbedtls學習3.mbedtls_API分析

1.API 說明

爲了方便用戶使用，這裏列出了常用的 API，並給出了相關的使用說明。

注：更多詳細 API 內容請參閱 ARM mbedtls API 手冊。

應用層 API

應用層 API 是提供給用戶在 App 中直接使用的 API，這部分 API 屏蔽了 mbedtls 內部具體的操作步驟，簡化了用戶使用。

mbedtls 初始化

int mbedtls_client_init(MbedTLSSession *session, void *entropy, size_t entropyLen);

mbedtls 客戶端初始化函數，用於初始化底層網絡接口、設置證書、設置 SSL 會話等。

參數	描述
session	入參，mbedtls 會話對象 MbedTLSSession
entropy	入參，mbedtls 熵字符串
entropyLen	入參，mbedtls 熵字符串長度
返回	描述
= 0	成功
!0	失敗

配置 mbedtls 上下文

int mbedtls_client_context(MbedTLSSession *session);

SSL 層配置，應用程序使用 mbedtls_client_context 函數配置客戶端上下文信息，包括證書解析、設置主機名、設置默認 SSL 配置、設置認證模式（默認 MBEDTLS_SSL_VERIFY_OPTIONAL）等。

參數	描述
session	入參，mbedtls 會話對象 MbedTLSSession
返回	描述
= 0	成功
!0	失敗

建立 SSL/TLS 連接

int mbedtls_client_connect(MbedTLSSession *session);

使用 mbedtls_client_connect 函數爲 SSL/TLS 連接建立通道。這裏包含整個的握手連接過程，以及證書校驗結果。

參數	描述
session	入參，mbedtls 會話對象 MbedTLSSession
返回	描述
= 0	成功
!0	失敗

讀取數據

• 向加密連接寫入數據

int mbedtls_client_write(MbedTLSSession *session, const unsigned char *buf , size_t len);

參數	描述
session	入參，mbedtls 會話對象 MbedTLSSession
buf	入參，待寫入的數據緩衝區
len	入參，待寫入的數據長度
返回	描述
= 0	成功
!0	失敗

• 從加密連接讀取數據

int mbedtls_client_read(MbedTLSSession *session, unsigned char *buf , size_t len);

參數	描述
session	入參，mbedtls 會話對象 MbedTLSSession
buf	入參，mbedtls 讀取內容的緩衝區
len	入參，mbedtls 待讀取內容長度
返回	描述
= 0	成功
!0	失敗

關閉 mbedtls 客戶端

int mbedtls_client_close(MbedTLSSession *session);

客戶端主動關閉連接或者因爲異常錯誤關閉連接，都需要使用 mbedtls_client_close 關閉連接並釋放資源。

參數	描述
session	入參，mbedtls 會話對象 MbedTLSSession
返回	描述
= 0	成功
!0	失敗

mbedtls 相關 API

設置調試級別

void mbedtls_debug_set_threshold( int threshold );

如果開啓了 MBEDTLS_DEBUG_C，可以使用該函數設置調試級別，用於控制不同級別的調試日誌輸出。

參數	描述
threshold	入參，Debug 級別，默認爲 0 沒有調試日誌
返回	描述
無	無

mbedtls 定義了 5 種調試級別，如下所示：

調試級別	描述
0	No debug
1	Error
2	State change
3	Informational
4	Verbose

初始化階段相關 API

• 網絡上下文初始化

void mbedtls_net_init( mbedtls_net_context *ctx );

初始化 TLS 網絡上下文，目前只有 fd 描述符。

參數	描述
ctx	入參，網絡上下文對象
返回	描述
無	無

• SSL 上下文初始化

void mbedtls_ssl_init( mbedtls_ssl_context *ssl );

SSL 上下文初始化，主要是清空 SSL 上下文對象，爲 SSL 連接做準備。

參數	描述
ssl	入參，SSL 上下文對象
返回	描述
無	無

• 初始化 SSL 配置

void mbedtls_ssl_config_init( mbedtls_ssl_config *conf );

SSL 配置初始化，主要是清空 SSL 配置結構體對象，爲 SSL 連接做準備。

參數	描述
conf	入參，SSL 配置結構體對象
返回	描述
無	無

• 初始化 SSL 隨機字節發生器

void mbedtls_ctr_drbg_init( mbedtls_ctr_drbg_context *ctx );

清空 CTR_DRBG（SSL 隨機字節發生器）上下文結構體對象，爲 mbedtls_ctr_drbg_seed 做準備。

參數	描述
ctx	入參，CTR_DRBG 結構體對象
返回	描述
無	無

• 初始化 SSL 熵

void mbedtls_entropy_init( mbedtls_entropy_context *ctx );

初始化 SSL 熵結構體對象。

參數	描述
ctx	入參，熵結構體對象
返回	描述
無	無

• 設置 SSL/TLS 熵源

int mbedtls_ctr_drbg_seed( mbedtls_ctr_drbg_context *ctx,
                   int (*f_entropy)(void *, unsigned char *, size_t),
                   void *p_entropy,
                   const unsigned char *custom,
                   size_t len );

爲 SSL/TLS 熵設置熵源，方便產生子種子。

參數	描述
ctx	入參，CTR_DRBG 結構體對象
f_entropy	入參，熵回調
p_entropy	入參，熵結構體（mbedtls_entropy_context）對象
custom	入參，個性化數據（設備特定標識符），可以爲空
len	個性化數據長度
返回	描述
無	無

• 設置根證書列表

void mbedtls_x509_crt_init( mbedtls_x509_crt *crt );

初始化根證書鏈表。

參數	描述
crt	入參，x509 證書結構體對象
返回	描述
無	無

• 解析根證書

int mbedtls_x509_crt_parse( mbedtls_x509_crt *chain, const unsigned char *buf, size_t buflen );

解釋性地解析。解析 buf 中一個或多個證書並將其添加到根證書鏈接列表中。如果可以解析某些證書，則結果是它遇到的失敗證書的數量。 如果沒有正確完成，則返回第一個錯誤。

根證書位於 ports/src/tls_certificate.c 文件 mbedtls_root_certificate 數組中。

參數	描述
chain	入參，x509 證書結構體對象
buf	入參，存儲根證書的 buffer，mbedtls_root_certificate 數組
buflen	入參，存儲根證書的 buffer 大小
返回	描述
無	無

• 設置主機名

int mbedtls_ssl_set_hostname( mbedtls_ssl_context *ssl, const char *hostname );

注意，這裏設置的 hostname 必須對應服務器證書中的 common name，即 CN 字段。

• 加載默認的 SSL 配置

int mbedtls_ssl_config_defaults( mbedtls_ssl_config *conf,
                                 int endpoint, int transport, int preset );

使用前，需要先調用 mbedtls_ssl_config_init 函數初始化 SSL 配置結構體對象。

參數	描述
conf	入參，SSL 配置結構體對象
endpoint	入參，MBEDTLS_SSL_IS_CLIENT 或者 MBEDTLS_SSL_IS_SERVER
transport	入參，TLS: MBEDTLS_SSL_TRANSPORT_STREAM; DTLS: MBEDTLS_SSL_TRANSPORT_DATAGRAM
preset	入參， 預定義的 MBEDTLS_SSL_PRESET_XXX 類型值，默認使用 MBEDTLS_SSL_PRESET_DEFAULT
返回	描述
無	無

• 設置證書驗證模式

void mbedtls_ssl_conf_authmode( mbedtls_ssl_config *conf, int authmode );

設置證書驗證模式默認值：服務器上爲 MBEDTLS_SSL_VERIFY_NONE，客戶端上爲 MBEDTLS_SSL_VERIFY_REQUIRED 或者 MBEDTLS_SSL_VERIFY_OPTIONAL（默認使用）。

MBEDTLS_SSL_VERIFY_OPTIONAL 表示證書驗證失敗也可以繼續通訊。

參數	描述
conf	入參，SSL 配置結構體對象
authmode	入參，證書驗證模式
返回	描述
無	無

• 設置驗證對等證書所需的數據

void mbedtls_ssl_conf_ca_chain( mbedtls_ssl_config *conf,
                                mbedtls_x509_crt *ca_chain,
                                mbedtls_x509_crl *ca_crl );

將受信的證書鏈配置到 SSL 配置結構體對象中。

參數	描述
conf	入參，SSL 配置結構體對象
ca_chain	入參，受信的 CA 證書鏈，存儲在 MbedTLSSession 的成員對象 cacert 中
ca_crl	入參，受信的 CA CRLs，可爲空
返回	描述
無	無

• 設置隨機數生成器回調

void mbedtls_ssl_conf_rng( mbedtls_ssl_config *conf,
                           int (*f_rng)(void *, unsigned char *, size_t),
                           void *p_rng );

參數	描述
conf	入參，SSL 配置結構體對象
f_rng	入參，隨機數生成器函數
p_rng	入參，隨機數生成器函數參數
返回	描述
無	無

• 設置 SSL 上下文

int mbedtls_ssl_setup( mbedtls_ssl_context *ssl,
                       const mbedtls_ssl_config *conf );

將 SSL 配置結構體對象設置到 SSL 上下文中。

參數	描述
ssl	入參，SSL 上下文結構體對象
conf	入參，SSL 配置結構體對象
返回	描述
= 0	成功
- 0x7F00	內存分配失敗

連接階段相關 API

int mbedtls_net_connect( mbedtls_net_context *ctx,
                         const char *host, const char *port,
                         int proto );

與給定的 host、port 及 proto 協議建立網絡連接。

參數	描述
ctx	入參，NET 網絡配置結構體對象
host	入參，指定的待連接主機名
port	入參，指定的主機端口號
proto	入參，指定的協議類型，MBEDTLS_NET_PROTO_TCP 或者 MBEDTLS_NET_PROTO_UDP
返回	描述
= 0	成功
- 0x0042	socket 創建失敗
- 0x0052	未知的主機名，DNS 解析失敗
- 0x0044	網絡連接失敗

• 設置網絡層讀寫接口

void mbedtls_ssl_set_bio( mbedtls_ssl_context *ssl,
                          void *p_bio,
                          mbedtls_ssl_send_t *f_send,
                          mbedtls_ssl_recv_t *f_recv,
                          mbedtls_ssl_recv_timeout_t *f_recv_timeout );

爲網絡層設置讀寫函數，被 mbedtls_ssl_read 和 mbedtls_ssl_write 函數調用。

• 對於 TLS，用戶提供 f_recv 和 f_recv_timeout 其中之一即可，如果都有提供，默認使用 f_recv_timeout 回調
• 對於 DTLS，用戶需要提供 f_recv_timeout 回調函數

參數	描述
ssl	入參，SSL 上下文結構體對象
p_bio	入參，socket 描述符
f_send	入參，網絡層寫回調函數
f_recv	入參，網絡層讀回調函數
f_recv_timeout	入參，網絡層非阻塞帶超時讀回調函數
返回	描述
無	無

• SSL/TLS 握手接口

int mbedtls_ssl_handshake( mbedtls_ssl_context *ssl );

執行 SSL/TLS 握手操作。

參數	描述
ssl	入參，SSL 上下文結構體對象
返回	描述
= 0	成功
- 0x6900	SSL 客戶端需要讀取調用
- 0x6880	SSL 客戶端需要寫入調用
- 0x6A80	DTLS 客戶端必須重試才能進行 hello 驗證
其它	其它 SSL 指定的錯誤碼

注意，如果您使用的是 DTLS，你需要單獨處理 - 0x6A80 錯誤，因爲它是預期的返回值而不是實際錯誤。

• 獲取證書驗證結果

uint32_t mbedtls_ssl_get_verify_result( const mbedtls_ssl_context *ssl );

參數	描述
ssl	入參，SSL 上下文結構體對象
返回	描述
= 0	成功
- 1	返回結果不可用
其它	BADCERT_xxx 和 BADCRL_xxx 標誌的組合，請參閱 x509.h

或者證書驗證結果的 API 接口，具體的錯誤信息需要使用 mbedtls_x509_crt_verify_info 接口獲取。

int mbedtls_x509_crt_verify_info( char *buf, size_t size,
                                  const char *prefix,
                                  uint32_t flags );

使用 mbedtls_x509_crt_verify_info 函數獲取有關證書驗證狀態的信息字符串，存儲在 MbedTLSSession 的對象的 buffer 成員中。

參數	描述
buf	入參，存儲驗證狀態信息字符串的緩衝區
size	入參，緩衝區大小
prefix	入參，行前綴
flags	入參，由 mbedtls_x509_crt_verify_info 函數返回的值
返回	描述
整數	寫入的字符串的長度（不包括結束符）或負的錯誤代碼

讀寫 API

SSL/TLS 寫函數

int mbedtls_ssl_read( mbedtls_ssl_context *ssl, unsigned char *buf, size_t len );

從 SLL/TLS 讀取數據，最多讀取 ‘len’ 字節長度數據字節。

參數	描述
ssl	入參，SSL 上下文結構體對象
buf	入參，接收讀取數據的緩衝區
len	入參，要讀取的數據長度
返回	描述
> 0	讀取到的數據長度
= 0	讀取到結束符
- 0x6900	SSL 客戶端需要讀取調用
- 0x6880	SSL 客戶端需要寫入調用
- 0x6780	SSL 客戶端需要重連
其它	其它 SSL 指定的錯誤碼

SSL/TLS 讀函數

int mbedtls_ssl_write( mbedtls_ssl_context *ssl, const unsigned char *buf, size_t len );

向 SSL/TLS 寫入數據，最多寫入 ‘len’ 字節長度數據。

參數	描述
ssl	入參，SSL 上下文結構體對象
buf	入參，待寫入數據的緩衝區
len	入參，待寫入數據的長度
返回	描述
> 0	實際寫入的數據長度
= 0	讀取到結束符
- 0x6900	SSL 客戶端需要讀取調用
- 0x6880	SSL 客戶端需要寫入調用
其它	其它 SSL 指定的錯誤碼