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 指定的錯誤碼 |