发 帖  
原厂入驻New
[问答]

常用的API及使用说明

53 API
分享
为了方便用户使用,这里列出了常用的API,并给出了相关的使用说明

0
2021-3-30 06:20:22   评论 分享淘帖 邀请回答
2个回答
应用层 API

应用层 API 是提供给用户在 App 中直接使用的 API,这部分 API 屏蔽了 mbedtls 内部具体的操作步骤,简化了用户使用。
mbedtls 初始化

int mbedtls_client_init(MbedTLSSession *session, void *entropy, size_t entropyLen);mbedtls 客户端初始化函数,用于初始化底层网络接口、设置证书、设置 SSL 会话等。
[tr]参数描述[/tr]
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)等。
[tr]参数描述[/tr]
session入参,mbedtls 会话对象 MbedTLSSession
返回描述
= 0成功
!0失败
建立 SSL/TLS 连接

int mbedtls_client_connect(MbedTLSSession *session);使用 mbedtls_client_connect 函数为 SSL/TLS 连接建立通道。这里包含整个的握手连接过程,以及证书校验结果。
[tr]参数描述[/tr]
session入参,mbedtls 会话对象 MbedTLSSession
返回描述
= 0成功
!0失败
读取数据

  • 向加密连接写入数据
int mbedtls_client_write(MbedTLSSession *session, const unsigned char *buf , size_t len);[tr]参数描述[/tr]
session入参,mbedtls 会话对象 MbedTLSSession
buf入参,待写入的数据缓冲区
len入参,待写入的数据长度
返回描述
= 0成功
!0失败

  • 从加密连接读取数据
int mbedtls_client_read(MbedTLSSession *session, unsigned char *buf , size_t len);[tr]参数描述[/tr]
session入参,mbedtls 会话对象 MbedTLSSession
buf入参,mbedtls 读取内容的缓冲区
len入参,mbedtls 待读取内容长度
返回描述
= 0成功
!0失败
关闭 mbedtls 客户端

int mbedtls_client_close(MbedTLSSession *session);客户端主动关闭连接或者因为异常错误关闭连接,都需要使用 mbedtls_client_close 关闭连接并释放资源。
[tr]参数描述[/tr]
session入参,mbedtls 会话对象 MbedTLSSession
返回描述
= 0成功
!0失败
mbedtls 相关 API

设置调试级别

void mbedtls_debug_set_threshold( int threshold );如果开启了 MBEDTLS_DEBUG_C,可以使用该函数设置调试级别,用于控制不同级别的调试日志输出。
[tr]参数描述[/tr]
threshold入参,Debug 级别,默认为 0 没有调试日志
返回描述
mbedtls 定义了 5 种调试级别,如下所示:
[tr]调试级别描述[/tr]
0No debug
1Error
2State change
3Informational
4Verbose
初始化阶段相关 API

  • 网络上下文初始化
void mbedtls_net_init( mbedtls_net_context *ctx );初始化 TLS 网络上下文,目前只有 fd 描述符。
[tr]参数描述[/tr]
ctx入参,网络上下文对象
返回描述

  • SSL 上下文初始化
void mbedtls_ssl_init( mbedtls_ssl_context *ssl );SSL 上下文初始化,主要是清空 SSL 上下文对象,为 SSL 连接做准备。
[tr]参数描述[/tr]
ssl入参,SSL 上下文对象
返回描述

  • 初始化 SSL 配置
void mbedtls_ssl_config_init( mbedtls_ssl_config *conf );SSL 配置初始化,主要是清空 SSL 配置结构体对象,为 SSL 连接做准备。
[tr]参数描述[/tr]
conf入参,SSL 配置结构体对象
返回描述

  • 初始化 SSL 随机字节发生器
void mbedtls_ctr_drbg_init( mbedtls_ctr_drbg_context *ctx );清空 CTR_DRBG(SSL 随机字节发生器)上下文结构体对象,为 mbedtls_ctr_drbg_seed 做准备。
[tr]参数描述[/tr]
ctx入参,CTR_DRBG 结构体对象
返回描述

  • 初始化 SSL 熵
void mbedtls_entropy_init( mbedtls_entropy_context *ctx );初始化 SSL 熵结构体对象。
[tr]参数描述[/tr]
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 熵设置熵源,方便产生子种子。
[tr]参数描述[/tr]
ctx入参,CTR_DRBG 结构体对象
f_entropy入参,熵回调
p_entropy入参,熵结构体(mbedtls_entropy_context)对象
custom入参,个性化数据(设备特定标识符),可以为空
len个性化数据长度
返回描述

  • 设置根证书列表
void mbedtls_x509_crt_init( mbedtls_x509_crt *crt );初始化根证书链表。
[tr]参数描述[/tr]
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 数组中。
[tr]参数描述[/tr]
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 配置结构体对象。
[tr]参数描述[/tr]
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 表示证书验证失败也可以继续通讯。
[tr]参数描述[/tr]
conf入参,SSL 配置结构体对象
authmode入参,证书验证模式
返回描述

  • 设置验证对等证书所需的数据
void mbedtls_ssl_conf_ca_chain( mbedtls_ssl_config *conf,                                mbedtls_x509_crt *ca_chain,                                mbedtls_x509_crl *ca_crl );将受信的证书链配置到 SSL 配置结构体对象中。
[tr]参数描述[/tr]
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 );[tr]参数描述[/tr]
conf入参,SSL 配置结构体对象
f_rng入参,随机数生成器函数
p_rng入参,随机数生成器函数参数
返回描述

  • 设置 SSL 上下文
int mbedtls_ssl_setup( mbedtls_ssl_context *ssl,                       const mbedtls_ssl_config *conf );将 SSL 配置结构体对象设置到 SSL 上下文中。
[tr]参数描述[/tr]
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 协议建立网络连接。
[tr]参数描述[/tr]
ctx入参,NET 网络配置结构体对象
host入参,指定的待连接主机名
port入参,指定的主机端口号
proto入参,指定的协议类型,MBEDTLS_NET_PROTO_TCP 或者 MBEDTLS_NET_PROTO_UDP
返回描述
= 0成功
- 0x0042socket 创建失败
- 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 回调函数
[tr]参数描述[/tr]
ssl入参,SSL 上下文结构体对象
p_bio入参,socket 描述符
f_send入参,网络层写回调函数
f_recv入参,网络层读回调函数
f_recv_timeout入参,网络层非阻塞带超时读回调函数
返回描述

  • SSL/TLS 握手接口
int mbedtls_ssl_handshake( mbedtls_ssl_context *ssl );执行 SSL/TLS 握手操作。
[tr]参数描述[/tr]
ssl入参,SSL 上下文结构体对象
返回描述
= 0成功
- 0x6900SSL 客户端需要读取调用
- 0x6880SSL 客户端需要写入调用
- 0x6A80DTLS 客户端必须重试才能进行 hello 验证
其它其它 SSL 指定的错误码
注意,如果您使用的是 DTLS,你需要单独处理 - 0x6A80 错误,因为它是预期的返回值而不是实际错误。
  • 获取证书验证结果
uint32_t mbedtls_ssl_get_verify_result( const mbedtls_ssl_context *ssl );[tr]参数描述[/tr]
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 成员中。
[tr]参数描述[/tr]
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' 字节长度数据字节。
[tr]参数描述[/tr]
ssl入参,SSL 上下文结构体对象
buf入参,接收读取数据的缓冲区
len入参,要读取的数据长度
返回描述
> 0读取到的数据长度
= 0读取到结束符
- 0x6900SSL 客户端需要读取调用
- 0x6880SSL 客户端需要写入调用
- 0x6780SSL 客户端需要重连
其它其它 SSL 指定的错误码
SSL/TLS 读函数
int mbedtls_ssl_write( mbedtls_ssl_context *ssl, const unsigned char *buf, size_t len );向 SSL/TLS 写入数据,最多写入 'len' 字节长度数据。
[tr]参数描述[/tr]
ssl入参,SSL 上下文结构体对象
buf入参,待写入数据的缓冲区
len入参,待写入数据的长度
返回描述
> 0实际写入的数据长度
= 0读取到结束符
- 0x6900SSL 客户端需要读取调用
- 0x6880SSL 客户端需要写入调用
其它其它 SSL 指定的错误码

2021-3-31 16:03:35 评论

举报

撰写答案

你正在撰写答案

如果你是对答案或其他答案精选点评或询问,请使用“评论”功能。

高级模式
您需要登录后才可以回帖 登录 | 注册

声明:本文内容及配图由入驻作者撰写或者入驻合作网站授权转载。文章观点仅代表作者本人,不代表电子发烧友网立场。文章及其配图仅供工程师学习之用,如有内容图片侵权或者其他问题,请联系本站作侵删。 侵权投诉
我要提问
快速回复 返回顶部 返回列表