wen/luban-lite-t3e-pro
1
0
Fork 0
mirror of https://gitee.com/Vancouver2017/luban-lite-t3e-pro.git synced 2025-12-13 18:08:54 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
724d6bf65e00d688d002c2fe4fc1eb2ff3763eb9
luban-lite-t3e-pro/packages/third-party/mbedtls/docs/api.md
刘可亮 0a13af6a1d V1.0.5
2024-06-04 19:00:30 +08:00

494 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# API 说明
为了方便用户使用，这里列出了常用的 API，并给出了相关的使用说明。
> 注：更多详细 API 内容请参阅 [**ARM mbedtls API 手册**](https://tls.mbed.org/api/)。
## 应用层 API
应用层 API 是提供给用户在 App 中直接使用的 API，这部分 API 屏蔽了 mbedtls 内部具体的操作步骤，简化了用户使用。
### mbedtls 初始化
```c
int mbedtls_client_init(MbedTLSSession *session, void *entropy, size_t entropyLen);
```
mbedtls 客户端初始化函数，用于初始化底层网络接口、设置证书、设置 SSL 会话等。
| 参数 | 描述 |
| :----- | :----- |
| session | 入参，mbedtls 会话对象 MbedTLSSession |
| entropy | 入参，mbedtls 熵字符串 |
| entropyLen | 入参，mbedtls 熵字符串长度 |
| **返回** | **描述** |
| `= 0` | 成功 |
| `!0` | 失败 |
### 配置 mbedtls 上下文
```c
int mbedtls_client_context(MbedTLSSession *session);
```
SSL 层配置，应用程序使用 `mbedtls_client_context` 函数配置客户端上下文信息，包括证书解析、设置主机名、设置默认 SSL 配置、设置认证模式（默认 MBEDTLS_SSL_VERIFY_OPTIONAL）等。
| 参数 | 描述 |
| :----- | :----- |
| session | 入参，mbedtls 会话对象 MbedTLSSession |
| **返回** | **描述** |
| `= 0` | 成功 |
| `!0` | 失败 |
### 建立 SSL/TLS 连接
```c
int mbedtls_client_connect(MbedTLSSession *session);
```
使用 `mbedtls_client_connect` 函数为 SSL/TLS 连接建立通道。这里包含整个的握手连接过程，以及证书校验结果。
| 参数 | 描述 |
| :----- | :----- |
| session | 入参，mbedtls 会话对象 MbedTLSSession |
| **返回** | **描述** |
| `= 0` | 成功 |
| `!0` | 失败 |
### 读取数据
- **向加密连接写入数据**
```c
int mbedtls_client_write(MbedTLSSession *session, const unsigned char *buf , size_t len);
```
| 参数 | 描述 |
| :----- | :----- |
| session | 入参，mbedtls 会话对象 MbedTLSSession |
| buf | 入参，待写入的数据缓冲区 |
| len | 入参，待写入的数据长度 |
| **返回** | **描述** |
| `= 0` | 成功 |
| `!0` | 失败 |
- **从加密连接读取数据**
```c
int mbedtls_client_read(MbedTLSSession *session, unsigned char *buf , size_t len);
```
| 参数 | 描述 |
| :----- | :----- |
| session | 入参，mbedtls 会话对象 MbedTLSSession |
| buf | 入参，mbedtls 读取内容的缓冲区 |
| len | 入参，mbedtls 待读取内容长度 |
| **返回** | **描述** |
| `= 0` | 成功 |
| `!0` | 失败 |
### 关闭 mbedtls 客户端
```c
int mbedtls_client_close(MbedTLSSession *session);
```
客户端主动关闭连接或者因为异常错误关闭连接，都需要使用 `mbedtls_client_close` 关闭连接并释放资源。
| 参数 | 描述 |
| :----- | :----- |
| session | 入参，mbedtls 会话对象 MbedTLSSession |
| **返回** | **描述** |
| `= 0` | 成功 |
| `!0` | 失败 |
## mbedtls 相关 API
### 设置调试级别
```c
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
- **网络上下文初始化**
```c
void mbedtls_net_init( mbedtls_net_context *ctx );
```
初始化 TLS 网络上下文，目前只有 fd 描述符。
| 参数 | 描述 |
| :----- | :----- |
| ctx | 入参，网络上下文对象 |
| **返回** | **描述** |
| 无 | 无 |
- **SSL 上下文初始化**
```c
void mbedtls_ssl_init( mbedtls_ssl_context *ssl );
```
SSL 上下文初始化，主要是清空 SSL 上下文对象，为 SSL 连接做准备。
| 参数 | 描述 |
| :----- | :----- |
| ssl | 入参，SSL 上下文对象 |
| **返回** | **描述** |
| 无 | 无 |
- **初始化 SSL 配置**
```c
void mbedtls_ssl_config_init( mbedtls_ssl_config *conf );
```
SSL 配置初始化，主要是清空 SSL 配置结构体对象，为 SSL 连接做准备。
| 参数 | 描述 |
| :----- | :----- |
| conf | 入参，SSL 配置结构体对象 |
| **返回** | **描述** |
| 无 | 无 |
- **初始化 SSL 随机字节发生器**
```c
void mbedtls_ctr_drbg_init( mbedtls_ctr_drbg_context *ctx );
```
清空 CTR_DRBG（SSL 随机字节发生器）上下文结构体对象，为 `mbedtls_ctr_drbg_seed` 做准备。
| 参数 | 描述 |
| :----- | :----- |
| ctx | 入参，CTR_DRBG 结构体对象 |
| **返回** | **描述** |
| 无 | 无 |
- **初始化 SSL 熵**
```c
void mbedtls_entropy_init( mbedtls_entropy_context *ctx );
```
初始化 SSL 熵结构体对象。
| 参数 | 描述 |
| :----- | :----- |
| ctx | 入参，熵结构体对象 |
| **返回** | **描述** |
| 无 | 无 |
- **设置 SSL/TLS 熵源**
```c
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 | 个性化数据长度 |
| **返回** | **描述** |
| 无 | 无 |
- **设置根证书列表**
```c
void mbedtls_x509_crt_init( mbedtls_x509_crt *crt );
```
初始化根证书链表。
| 参数 | 描述 |
| :----- | :----- |
| crt | 入参，x509 证书结构体对象 |
| **返回** | **描述** |
| 无 | 无 |
- **解析根证书**
```c
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 大小 |
| **返回** | **描述** |
| 无 | 无 |
- **设置主机名**
```c
int mbedtls_ssl_set_hostname( mbedtls_ssl_context *ssl, const char *hostname );
```
注意，这里设置的 `hostname` 必须对应服务器证书中的 `common name`，即 CN 字段。
- **加载默认的 SSL 配置**
```c
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 |
| **返回** | **描述** |
| 无 | 无 |
- **设置证书验证模式**
```c
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 | 入参，证书验证模式 |
| **返回** | **描述** |
| 无 | 无 |
- **设置验证对等证书所需的数据**
```c
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，可为空|
| **返回** | **描述** |
| 无 | 无 |
- **设置随机数生成器回调**
```c
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 上下文**
```c
int mbedtls_ssl_setup( mbedtls_ssl_context *ssl,
const mbedtls_ssl_config *conf );
```
将 SSL 配置结构体对象设置到 SSL 上下文中。
| 参数 | 描述 |
| :----- | :----- |
| ssl | 入参，SSL 上下文结构体对象 |
| conf | 入参，SSL 配置结构体对象 |
| **返回** | **描述** |
| `= 0` | 成功 |
| `- 0x7F00` | 内存分配失败 |
### 连接阶段相关 API
```c
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` | 网络连接失败 |
- **设置网络层读写接口**
```c
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 握手接口**
```c
int mbedtls_ssl_handshake( mbedtls_ssl_context *ssl );
```
执行 SSL/TLS 握手操作。
| 参数 | 描述 |
| :----- | :----- |
| ssl | 入参，SSL 上下文结构体对象 |
| **返回** | **描述** |
| `= 0` | 成功 |
| `- 0x6900` | SSL 客户端需要读取调用 |
| `- 0x6880` | SSL 客户端需要写入调用 |
| `- 0x6A80` | DTLS 客户端必须重试才能进行 hello 验证 |
| 其它 | 其它 SSL 指定的错误码 |
注意，如果您使用的是 DTLS，你需要单独处理 `- 0x6A80` 错误，因为它是预期的返回值而不是实际错误。
- **获取证书验证结果**
```c
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` 接口获取。
```c
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 写函数**
```c
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 读函数**
```c
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 指定的错误码 |
Reference in New Issue View Git Blame Copy Permalink