SSL/TLS流封装类更多...

#include <ssl_stream.hpp>

类 neforce::ssl_stream 继承关系图:

Public 类型
using	native_handle_type
	原生文件描述符类型

Public 成员函数
	ssl_stream ()=default
	默认构造函数
	ssl_stream (const ssl_context &ctx)
	从SSL上下文构造
	ssl_stream (ssl_stream &&other) noexcept=default
	移动构造函数
ssl_stream &	operator= (ssl_stream &&other) noexcept=default
	移动赋值运算符
void	reset (const ssl_context &ctx)
	重置SSL流
void	set_fd (native_handle_type fd)
	设置底层socket文件描述符
void	accept ()
	执行服务器端TLS握手
bool	connect ()
	执行客户端TLS握手
void	close () noexcept
	关闭SSL连接
ssize_t	read (void *buffer, size_t size)
	读取加密数据
ssize_t	write (const void *buffer, size_t size)
	写入加密数据
vector< char >	read_all (size_t max_size=8192)
	读取所有可用数据
bool	write_all (const void *data, size_t size)
	写入所有数据
int	pending () const
	获取缓冲区中可读字节数
void	set_sni_hostname (const string &hostname)
	设置SNI主机名（客户端）
x509_ptr	get_peer_certificate () const
	获取对等方证书
bool	verify_peer () const
	验证对等方证书
string	get_cipher_name () const
	获取密码套件名称
string	get_version () const
	获取TLS协议版本
string	get_alpn_negotiated () const
	获取ALPN协商的协议名称
const string &	last_error () const
	获取最后错误信息
bool	is_valid () const noexcept
	检查SSL对象是否有效
	operator bool () const noexcept
	布尔转换运算符
::SSL *	native_handle () const noexcept
	获取原生SSL对象指针
::SSL *	release () noexcept
	释放SSL对象所有权
void	async_handshake (io_context &ctx, function< void(error_code)> handler)
	异步TLS握手
void	async_handshake (io_context &ctx, cancellation_slot &slot, function< void(error_code)> handler)
	异步TLS握手（带取消槽）
void	async_read (io_context &ctx, memory_view< char > buffer, function< void(error_code, size_t)> handler) override
	异步SSL读取
void	async_read (io_context &ctx, memory_view< char > buffer, cancellation_slot &slot, function< void(error_code, size_t)> handler) override
	异步SSL读取（带取消槽）
void	async_write (io_context &ctx, memory_view< const char > buffer, function< void(error_code, size_t)> handler) override
	异步SSL写入
void	async_write (io_context &ctx, memory_view< const char > buffer, cancellation_slot &slot, function< void(error_code, size_t)> handler) override
	异步SSL写入（带取消槽）
template<typename Token, enable_if_t<!is_same_v< decay_t< Token >, function< void(error_code)> >, int > = 0>
void	async_handshake (io_context &ctx, Token &&token)
	异步TLS握手—任意可调用对象
auto	async_handshake (io_context &ctx, use_future_t)
	异步TLS握手—use_future
void	async_handshake (io_context &ctx, detached_t)
	异步TLS握手—detached（即发即忘）
auto	async_handshake (io_context &ctx, use_awaitable_t)
	异步TLS握手—use_awaitable
Public 成员函数继承自 neforce::async_stream
virtual	~async_stream ()=default
	析构函数
template<typename Token, enable_if_t<!is_same_v< decay_t< Token >, function< void(error_code, size_t)> >, int > = 0>
void	async_read (io_context &ctx, memory_view< char > buffer, Token &&token)
	异步读取—任意可调用对象
auto	async_read (io_context &ctx, memory_view< char > buffer, use_future_t)
	异步读取—use_future
void	async_read (io_context &ctx, memory_view< char > buffer, detached_t)
	异步读取—detached（即发即忘）
auto	async_read (io_context &ctx, memory_view< char > buffer, use_awaitable_t)
	异步读取—use_awaitable
template<typename Token, enable_if_t<!is_same_v< decay_t< Token >, function< void(error_code, size_t)> >, int > = 0>
void	async_write (io_context &ctx, memory_view< const char > buffer, Token &&token)
	异步写入—任意可调用对象
auto	async_write (io_context &ctx, memory_view< const char > buffer, use_future_t)
	异步写入—use_future
void	async_write (io_context &ctx, memory_view< const char > buffer, detached_t)
	异步写入—detached（即发即忘）
auto	async_write (io_context &ctx, memory_view< const char > buffer, use_awaitable_t)
	异步写入—use_awaitable
void	async_read (io_context &ctx, mutable_buffers &bufs, function< void(error_code, size_t)> handler)
	异步读取—scatter-gather
void	async_write (io_context &ctx, const_buffers &bufs, function< void(error_code, size_t)> handler)
	异步写入—scatter-gather
void	async_read (io_context &ctx, dynamic_buffer &buf, size_t n, function< void(error_code, size_t)> handler)
	异步读取到 dynamic_buffer

详细描述

SSL/TLS流封装类

提供加密通信流的接口。需要先建立TCP连接，然后在连接上建立SSL/TLS会话。

主要功能：

SSL/TLS握手
加密数据读写
证书验证
SNI（服务器名称指示）支持
密码套件和协议版本查询
非阻塞I/O支持

在文件 ssl_stream.hpp 第 39 行定义.

构造及析构函数说明

◆ ssl_stream() [1/2]

neforce::ssl_stream::ssl_stream ( )

default

默认构造函数

创建未初始化的SSL流对象。

被这些函数引用 operator=() , 以及 ssl_stream().

◆ ssl_stream() [2/2]

neforce::ssl_stream::ssl_stream ( const ssl_context & ctx )

inlineexplicit

从SSL上下文构造

参数

ctx SSL上下文

异常

ssl_exception SSL对象创建失败时抛出

在文件 ssl_stream.hpp 第 87 行定义.

引用了 reset.

成员函数说明

◆ accept()

void neforce::ssl_stream::accept ( )

执行服务器端TLS握手

异常

ssl_exception 握手失败时抛出

作为服务器端接受TLS连接，执行SSL/TLS握手。需要在set_fd()之后调用。

◆ async_handshake() [1/6]

void neforce::ssl_stream::async_handshake	(	io_context &	ctx,
		cancellation_slot &	slot,
		function< void(error_code)>	handler )

异步TLS握手（带取消槽）

参数

ctx	异步 I/O 执行上下文
slot	取消槽
handler	完成回调 void(error_code)

◆ async_handshake() [2/6]

void neforce::ssl_stream::async_handshake	(	io_context &	ctx,
		detached_t	)

inline

异步TLS握手—detached（即发即忘）

参数

ctx	异步 I/O 执行上下文

在文件 ssl_stream.hpp 第 369 行定义.

引用了 async_handshake().

◆ async_handshake() [3/6]

void neforce::ssl_stream::async_handshake	(	io_context &	ctx,
		function< void(error_code)>	handler )

异步TLS握手

参数

ctx	异步 I/O 执行上下文
handler	完成回调 void(error_code)

执行非阻塞TLS握手，由 io_context 驱动 WANT_READ/WANT_WRITE 重试。 handler 在 io_context::run() 线程中执行。

被这些函数引用 async_handshake(), async_handshake(), async_handshake() , 以及 async_handshake().

◆ async_handshake() [4/6]

template<typename Token, enable_if_t<!is_same_v< decay_t< Token >, function< void(error_code)> >, int > = 0>

void neforce::ssl_stream::async_handshake	(	io_context &	ctx,
		Token &&	token )

inline

异步TLS握手—任意可调用对象

模板参数

Token 可调用对象类型，需满足 void(error_code) 签名

参数

ctx	异步 I/O 执行上下文
token	完成令牌

在文件 ssl_stream.hpp 第 350 行定义.

引用了 async_handshake() , 以及 neforce::forward().

◆ async_handshake() [5/6]

auto neforce::ssl_stream::async_handshake	(	io_context &	ctx,
		use_awaitable_t	)

inline

异步TLS握手—use_awaitable

参数

ctx	异步 I/O 执行上下文

返回: awaitable<void> 可协程等待的结果

在文件 ssl_stream.hpp 第 379 行定义.

引用了 async_handshake() , 以及 neforce::use_awaitable.

◆ async_handshake() [6/6]

auto neforce::ssl_stream::async_handshake	(	io_context &	ctx,
		use_future_t	)

inline

异步TLS握手—use_future

参数

ctx	异步 I/O 执行上下文

返回: future<void> 异步操作结果

在文件 ssl_stream.hpp 第 359 行定义.

引用了 async_handshake() , 以及 neforce::use_future.

◆ async_read() [1/2]

void neforce::ssl_stream::async_read	(	io_context &	ctx,
		memory_view< char >	buffer,
		cancellation_slot &	slot,
		function< void(error_code, size_t)>	handler )

overridevirtual

异步SSL读取（带取消槽）

参数

ctx	异步 I/O 执行上下文
buffer	接收缓冲区
slot	取消槽
handler	完成回调 void(error_code, size_t bytes_transferred)

实现了 neforce::async_stream.

◆ async_read() [2/2]

void neforce::ssl_stream::async_read	(	io_context &	ctx,
		memory_view< char >	buffer,
		function< void(error_code, size_t)>	handler )

overridevirtual

异步SSL读取

参数

ctx	异步 I/O 执行上下文
buffer	接收缓冲区
handler	完成回调 void(error_code, size_t bytes_transferred)

从SSL流异步读取解密数据。 handler 在 io_context::run() 线程中执行。

实现了 neforce::async_stream.

◆ async_write() [1/2]

void neforce::ssl_stream::async_write	(	io_context &	ctx,
		memory_view< const char >	buffer,
		cancellation_slot &	slot,
		function< void(error_code, size_t)>	handler )

overridevirtual

异步SSL写入（带取消槽）

参数

ctx	异步 I/O 执行上下文
buffer	发送缓冲区
slot	取消槽
handler	完成回调 void(error_code, size_t bytes_transferred)

实现了 neforce::async_stream.

◆ async_write() [2/2]

void neforce::ssl_stream::async_write	(	io_context &	ctx,
		memory_view< const char >	buffer,
		function< void(error_code, size_t)>	handler )

overridevirtual

异步SSL写入

参数

ctx	异步 I/O 执行上下文
buffer	发送缓冲区
handler	完成回调 void(error_code, size_t bytes_transferred)

向SSL流异步写入加密数据。 handler 在 io_context::run() 线程中执行。

实现了 neforce::async_stream.

◆ close()

void neforce::ssl_stream::close ( )

noexcept

关闭SSL连接

发送close_notify告警，释放SSL对象。底层的socket不会关闭，需要单独关闭。

◆ connect()

bool neforce::ssl_stream::connect ( )

执行客户端TLS握手

返回: 握手成功返回true

异常

ssl_exception 握手失败时抛出

作为客户端发起TLS连接，执行SSL/TLS握手。需要在set_fd()和set_sni_hostname()（可选）之后调用。

◆ get_alpn_negotiated()

string neforce::ssl_stream::get_alpn_negotiated ( ) const

nodiscard

获取ALPN协商的协议名称

返回: 协议名称字符串（如"h2"、"http/1.1"），未协商返回空字符串

返回TLS握手期间通过ALPN（Application-Layer Protocol Negotiation）协商确定的应用层协议。需要在TLS握手（accept/connect）完成后调用。

引用了 get_alpn_negotiated().

被这些函数引用 get_alpn_negotiated().

◆ get_cipher_name()

string neforce::ssl_stream::get_cipher_name ( ) const

nodiscard

获取密码套件名称

返回: 密码套件名称

返回当前TLS连接使用的密码套件名称。

引用了 get_cipher_name().

被这些函数引用 get_cipher_name().

◆ get_peer_certificate()

x509_ptr neforce::ssl_stream::get_peer_certificate ( ) const

nodiscard

获取对等方证书

返回: X509证书指针

获取TLS握手时对等方提供的证书。

引用了 get_peer_certificate().

被这些函数引用 get_peer_certificate().

◆ get_version()

string neforce::ssl_stream::get_version ( ) const

nodiscard

获取TLS协议版本

返回: 协议版本字符串（如"TLSv1.2"）

引用了 get_version().

被这些函数引用 get_version().

◆ is_valid()

bool neforce::ssl_stream::is_valid ( ) const

inlinenodiscardnoexcept

检查SSL对象是否有效

返回: 有效返回true

在文件 ssl_stream.hpp 第 260 行定义.

被这些函数引用 operator bool().

◆ last_error()

const string & neforce::ssl_stream::last_error ( ) const

inlinenodiscard

获取最后错误信息

返回: 错误描述字符串

在文件 ssl_stream.hpp 第 254 行定义.

引用了 last_error().

被这些函数引用 last_error().

◆ native_handle()

::SSL * neforce::ssl_stream::native_handle ( ) const

inlinenodiscardnoexcept

获取原生SSL对象指针

返回: SSL指针

在文件 ssl_stream.hpp 第 272 行定义.

◆ operator bool()

neforce::ssl_stream::operator bool ( ) const

inlineexplicitnoexcept

布尔转换运算符

返回: 有效返回true

在文件 ssl_stream.hpp 第 266 行定义.

引用了 is_valid().

◆ pending()

int neforce::ssl_stream::pending ( ) const

nodiscard

获取缓冲区中可读字节数

返回: 可读字节数

返回SSL对象内部缓冲区中已解密但未读取的字节数。

引用了 pending().

被这些函数引用 pending().

◆ read()

ssize_t neforce::ssl_stream::read	(	void *	buffer,
		size_t	size )

读取加密数据

参数

buffer	接收缓冲区
size	要读取的字节数

返回: 实际读取的字节数，-1表示错误，0表示需要重试（非阻塞模式）

从SSL连接读取解密后的数据。非阻塞模式下，如果没有数据可读返回0。

引用了 read() , 以及 neforce::size().

被这些函数引用 read().

◆ read_all()

vector< char > neforce::ssl_stream::read_all ( size_t max_size = 8192 )

读取所有可用数据

参数

max_size 最大读取字节数

返回: 读取的数据

异常

ssl_exception 读取失败时抛出

持续读取直到连接关闭或达到最大大小。适用于阻塞模式下的完整响应读取。

引用了 read_all().

被这些函数引用 read_all().

◆ release()

::SSL * neforce::ssl_stream::release ( )

inlinenodiscardnoexcept

释放SSL对象所有权

返回: SSL指针

释放SSL对象的所有权，调用方负责释放。

在文件 ssl_stream.hpp 第 280 行定义.

◆ reset()

void neforce::ssl_stream::reset ( const ssl_context & ctx )

重置SSL流

参数

ctx SSL上下文

异常

ssl_exception SSL对象创建失败时抛出

创建新的SSL对象并关联到指定的上下文。如果已有SSL对象，会先关闭并释放。

◆ set_fd()

void neforce::ssl_stream::set_fd ( native_handle_type fd )

设置底层socket文件描述符

参数

fd	socket文件描述符

异常

ssl_exception	设置失败时抛出
value_exception	文件描述符无效时抛出

将SSL对象关联到已连接的TCP socket。必须在握手之前调用。

◆ set_sni_hostname()

void neforce::ssl_stream::set_sni_hostname ( const string & hostname )

设置SNI主机名（客户端）

参数

hostname 服务器主机名

异常

ssl_exception	设置失败时抛出
value_exception	主机名为空时抛出

在客户端TLS握手中设置服务器名称指示（SNI）扩展。用于指示客户端想要连接的服务器名称。

引用了 set_sni_hostname().

被这些函数引用 set_sni_hostname().

◆ verify_peer()

bool neforce::ssl_stream::verify_peer ( ) const

nodiscard

验证对等方证书

返回: 验证通过返回true

检查对等方证书是否有效（未过期、链完整、信任CA）。需要在握手完成后调用。

引用了 verify_peer().

被这些函数引用 verify_peer().

◆ write()

ssize_t neforce::ssl_stream::write	(	const void *	buffer,
		size_t	size )

写入加密数据

参数

buffer	要发送的数据
size	数据大小

返回: 实际写入的字节数，-1表示错误，0表示需要重试（非阻塞模式）

加密并发送数据到SSL连接。非阻塞模式下，如果无法立即发送返回0。

引用了 neforce::size() , 以及 write().

被这些函数引用 write().

◆ write_all()

bool neforce::ssl_stream::write_all	(	const void *	data,
		size_t	size )

写入所有数据

参数

data	要发送的数据
size	数据大小

返回: 成功返回true

持续写入直到所有数据发送完毕。适用于阻塞模式下的完整数据发送。

引用了 neforce::data(), neforce::size() , 以及 write_all().

被这些函数引用 write_all().

该类的文档由以下文件生成:

ssl_stream.hpp

Public 类型

Public 成员函数

详细描述

构造及析构函数说明

◆ ssl_stream() [1/2]

◆ ssl_stream() [2/2]

成员函数说明

◆ accept()

◆ async_handshake() [1/6]

◆ async_handshake() [2/6]

◆ async_handshake() [3/6]

◆ async_handshake() [4/6]

◆ async_handshake() [5/6]

◆ async_handshake() [6/6]

◆ async_read() [1/2]

◆ async_read() [2/2]

◆ async_write() [1/2]

◆ async_write() [2/2]

◆ close()

◆ connect()

◆ get_alpn_negotiated()

◆ get_cipher_name()

◆ get_peer_certificate()

◆ get_version()

◆ is_valid()

◆ last_error()

◆ native_handle()

◆ operator bool()

◆ pending()

◆ read()

◆ read_all()

◆ release()

◆ reset()

◆ set_fd()

◆ set_sni_hostname()

◆ verify_peer()

◆ write()

◆ write_all()