ssl_stream类 参考

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

#include <ssl_stream.hpp>

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

Public 成员函数
	ssl_stream ()=default
	默认构造函数
	ssl_stream (const ssl_context &ctx)
	从SSL上下文构造
void	reset (const ssl_context &ctx)
	重置SSL流
void	set_fd (native_handle_type fd)
	设置底层socket文件描述符
void	accept ()
	执行服务器端TLS握手
bool	connect ()
	执行客户端TLS握手
void	close ()
	关闭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)
	写入所有数据
NEFORCE_NODISCARD int	pending () const
	获取缓冲区中可读字节数
void	set_sni_hostname (const string &hostname)
	设置SNI主机名（客户端）
NEFORCE_NODISCARD x509_ptr	get_peer_certificate () const
	获取对等方证书
NEFORCE_NODISCARD bool	verify_peer () const
	验证对等方证书
NEFORCE_NODISCARD string	get_cipher_name () const
	获取密码套件名称
NEFORCE_NODISCARD string	get_version () const
	获取TLS协议版本
NEFORCE_NODISCARD const string &	last_error () const
	获取最后错误信息
NEFORCE_NODISCARD bool	is_valid () const noexcept
	检查SSL对象是否有效
	operator bool () const noexcept
	布尔转换运算符
NEFORCE_NODISCARD::SSL *	native_handle () const noexcept
	获取原生SSL对象指针
NEFORCE_NODISCARD::SSL *	release () noexcept
	释放SSL对象所有权

详细描述

SSL/TLS流封装类

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

主要功能：

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

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

构造及析构函数说明

ssl_stream() [1/2]

ssl_stream::ssl_stream ( )

default

默认构造函数

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

ssl_stream() [2/2]

ssl_stream::ssl_stream ( const ssl_context & ctx )

inlineexplicit

从SSL上下文构造

参数

ctx

SSL上下文

异常

ssl_exception

SSL对象创建失败时抛出

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

引用了 reset().

成员函数说明

accept()

void ssl_stream::accept

(

)

执行服务器端TLS握手

异常

ssl_exception

握手失败时抛出

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

close()

void ssl_stream::close

(

)

关闭SSL连接

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

connect()

bool ssl_stream::connect

(

)

执行客户端TLS握手

返回

握手成功返回true

异常

ssl_exception

握手失败时抛出

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

get_cipher_name()

NEFORCE_NODISCARD string ssl_stream::get_cipher_name

(

)

const

获取密码套件名称

返回

密码套件名称

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

get_peer_certificate()

NEFORCE_NODISCARD x509_ptr ssl_stream::get_peer_certificate

(

)

const

获取对等方证书

返回

X509证书指针

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

get_version()

NEFORCE_NODISCARD string ssl_stream::get_version

(

)

const

获取TLS协议版本

返回

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

is_valid()

NEFORCE_NODISCARD bool ssl_stream::is_valid ( ) const

inlinenoexcept

检查SSL对象是否有效

返回

有效返回true

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

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

last_error()

NEFORCE_NODISCARD const string & ssl_stream::last_error ( ) const

inline

获取最后错误信息

返回

错误描述字符串

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

native_handle()

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

inlinenoexcept

获取原生SSL对象指针

返回

SSL指针

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

operator bool()

ssl_stream::operator bool ( ) const

inlineexplicitnoexcept

布尔转换运算符

返回

有效返回true

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

引用了 is_valid().

pending()

NEFORCE_NODISCARD int ssl_stream::pending

(

)

const

获取缓冲区中可读字节数

返回

可读字节数

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

read()

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

读取加密数据

参数

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

返回

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

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

引用了 size().

read_all()

vector< char > ssl_stream::read_all

(

size_t

max_size = 8192

)

读取所有可用数据

参数

max_size

最大读取字节数

返回

读取的数据

异常

ssl_exception

读取失败时抛出

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

release()

NEFORCE_NODISCARD::SSL * ssl_stream::release ( )

inlinenoexcept

释放SSL对象所有权

返回

SSL指针

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

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

reset()

void ssl_stream::reset

(

const ssl_context &

ctx

)

重置SSL流

参数

ctx

SSL上下文

异常

ssl_exception

SSL对象创建失败时抛出

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

被这些函数引用 ssl_stream().

set_fd()

void ssl_stream::set_fd

(

native_handle_type

fd

)

设置底层socket文件描述符

参数

fd	socket文件描述符

异常

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

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

set_sni_hostname()

void ssl_stream::set_sni_hostname

(

const string &

hostname

)

设置SNI主机名（客户端）

参数

hostname

服务器主机名

异常

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

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

verify_peer()

NEFORCE_NODISCARD bool ssl_stream::verify_peer

(

)

const

验证对等方证书

返回

验证通过返回true

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

write()

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

写入加密数据

参数

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

返回

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

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

引用了 size().

write_all()

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

写入所有数据

参数

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

返回

成功返回true

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

引用了 data() , 以及 size().

---

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

• ssl_stream.hpp