结构体 ClientConnection 

pub struct ClientConnection { /* private fields */ }

This represents 一个 single TLS client connection.

实现

impl ClientConnection

pub fn new( config: Arc<ClientConfig>, name: ServerName<'static>, ) -> Result<Self, Error>

创建一个新的 ClientConnection config controls how we behave in the TLS protocol, name 是 name of the server we want 到 talk 到.

pub fn new_with_alpn( config: Arc<ClientConfig>, name: ServerName<'static>, alpn_protocols: Vec<Vec<u8>>, ) -> Result<Self, Error>

创建一个带有自定义 ALPN 协议的新 ClientConnection

pub fn early_data(&mut self) -> Option<WriteEarlyData<'_>>

Returns an io::Write implementer you can write bytes 到 到 send TLS 1.3 early data (一个.k.一个. “0-RTT data”) 到 the server.

This returns None in many circumstances when the capability 到 send early data is not available, including but not limited 到:

• The server hasn’t been talked to previously.
• The server does not support resumption.
• The server does not support early data.
• The resumption data for the server has expired.

此 server specifies 一个 maximum amount of early data. You can learn this limit through the returned object, 并 writes through it will process only this many bytes.

此 server can choose not 到 accept any sent early data – in this case 数据 is lost but the connection continues. You can tell this happened using is_early_data_accepted。

pub fn is_early_data_accepted(&self) -> bool

如果服务器信号展秀它将处理早期数据，则返回 True

If you sent early data 并 this returns false at the end of the handshake then the server will not process 数据. This is not an error, but you may wish 到 resend 数据.

pub fn dangerous_extract_secrets(self) -> Result<ExtractedSecrets, Error>

提取密钥，以便在配置 kTLS 时使用，例如。 Should be 用 with care as it exposes secret 密钥材料。

pub fn ech_status(&self) -> EchStatus

返回连接’s 加密客户端问候 (ECH) 状态

pub fn tls13_tickets_received(&self) -> u32

返回数量 TLS 1.3 已接收的票据

pub fn fips(&self) -> bool

返回 true if the connection was made with 一个 ClientConfig ， FIPS compatible.

This is different 从 crate::crypto::CryptoProvider::fips(): it is concerned only with cryptography, whereas this also covers TLS-level configuration that NIST recommends, as well as ECH HPKE suites if applicable.

Methods from Deref<Target = ConnectionCommon<ClientConnectionData>>

pub fn process_new_packets(&mut self) -> Result<IoState, Error>

处理先前调用以下方法读取的所有新数据包： Connection::read_tls。

Errors 从 此函数 relate 到 TLS protocol errors, 并 are fatal 到 the connection. Future calls after an error will do no new work 并 将返回 the same error. After an error is received 从 process_new_packets, you should not call read_tls any more (it will fill up buffers 到 no purpose)。 However, you may call the other methods on the connection, including write, send_close_notify, 并 write_tls。 Most likely you will want 到 call write_tls 到 send any alerts queued by the error 并 then close 底层 connection.

Success 从 此函数 comes with some sundry state data about the connection.

pub fn export_keying_material<T: AsMut<[u8]>>( &self, output: T, label: &[u8], context: Option<&[u8]>, ) -> Result<T, Error>

从已协商的连接密钥派生密钥材料。

This function fills in output with output.len() bytes of key material derived 从 the master session secret using label 并 context 用于 diversification. Ownership of 缓冲区 is taken by 函数 并 returned via the Ok result 到 ensure no key material leaks if 函数 fails.

See RFC5705 用于 more details on what this does 并 is 用于.

For TLS 1.3 connections, 此函数 does not use the “early” exporter at any point.

This function fails if called prior 到 the handshake completing; 检查 with CommonState::is_handshaking first.

This function fails if output.len() is zero.

pub fn set_buffer_limit(&mut self, limit: Option<usize>)

设置内部缓冲区的限制 用 到 缓冲区 unsent 明文 (prior 到 completing the TLS handshake) 并 unsent TLS records. This limit acts only on application data written through Connection::writer。

By default the limit is 64KB. 此 limit can be set at any time, even if the current 缓冲区 use is higher.

None means no limit applies, 并 will mean that written data is buffered without bound – it is up 到 the application 到 appropriately schedule its 明文 并 TLS writes 到 bound memory usage.

For illustration: Some(1) means 一个 limit of one byte applies: Connection::writer will accept only one byte, encrypt it 并 add 一个 TLS header. Once this is sent via Connection::write_tls, another byte may be sent.

Internal write-direction buffering

rustls has two buffers whose size are bounded by this setting:

Buffering of unsent plaintext data prior to handshake completion

Calls 到 Connection::writer before 或 during the handshake are buffered (up 到 the limit specified here)。 Once the handshake completes 此数据 is encrypted 并 the resulting TLS records are added 到 the outgoing 缓冲区.

Buffering of outgoing TLS records

This 缓冲区 is 用 到 store TLS records that rustls needs 到 send 到 the peer. It is 用 in these two circumstances:

• by Connection::process_new_packets when a handshake or alert TLS record needs to be sent.
• by Connection::writer post-handshake: the plaintext is encrypted and the resulting TLS record is buffered.

This 缓冲区 is emptied by Connection::write_tls。

pub fn refresh_traffic_keys(&mut self) -> Result<(), Error>

Sends 一个 TLS 1.3 key_update message 到 refresh 一个 connection’s keys.

This call refreshes our encryption keys. Once the peer receives the message, it refreshes its encryption 并 decryption keys 并 sends 一个 response. Once we receive that response, we refresh our decryption keys 到 match. At the end of this process, keys in both directions have been refreshed.

Note that this process does not happen synchronously: this call just arranges that the key_update message ， included in the next write_tls output.

This fails with Error::HandshakeNotComplete if called before the initial handshake is complete, 或 if 一个 version prior 到 TLS 1.3 is negotiated.

Usage advice

Note that other implementations (including rustls) may enforce limits on the number of key_update messages allowed on 一个 given connection 到 prevent denial of service. Therefore, this should be called sparingly.

rustls implicitly 并 automatically refreshes traffic keys when needed according 到 the selected cipher suite’s cryptographic constraints. There is therefore no need 到 call this manually 到 avoid cryptographic keys “wearing out”。

此 main reason 到 call this manually is 到 roll keys when it is known 一个 connection ， idle 用于 一个 long period.

pub fn reader(&mut self) -> Reader<'_>

返回一个允许读取明文的对象

pub fn writer(&mut self) -> Writer<'_>

返回一个允许写入明文的对象

pub fn complete_io<T>(&mut self, io: &mut T) -> Result<(usize, usize), Error>

where Self: Sized, T: Read + Write,

This function uses io 到 complete any outstanding IO 用于 this connection.

This 是 convenience function which solely uses other parts of the public API.

What this means depends on the connection state:

• If the connection is_handshaking, then IO is performed until the handshake is complete.
• Otherwise, if wants_write is true, write_tls is invoked until it is all written.
• Otherwise, if wants_read is true, read_tls is invoked once.

此 return value 是 number of bytes read 从 并 written 到 io, respectively. Once both read() 并 write() yield WouldBlock, 此函数 will propagate the error.

Errors 从 TLS record handling (i.e., 从 process_new_packets) are wrapped in an io::ErrorKind::InvalidData-kind error.

pub fn read_tls(&mut self, rd: &mut dyn Read) -> Result<usize, Error>

从以下来源读取 TLS 内容 rd into the internal 缓冲区.

Due 到 the internal buffering, rd can supply TLS messages in arbitrary-sized chunks (like 一个 socket 或 pipe might)。

You should call process_new_packets() each time 一个 call 到 此函数 succeeds in order 到 empty the incoming TLS data 缓冲区.

This function returns Ok(0) when 底层 rd does so. This typically happens when 一个 socket is cleanly closed, 或 一个 file is at EOF. Errors may result 从 the IO done through rd; additionally, errors of ErrorKind::Other are emitted 到 signal backpressure:

• In order to empty the incoming TLS data buffer, you should call process_new_packets() each time a call to this function succeeds.
• In order to empty the incoming plaintext data buffer, you should empty it through the reader() after the call to process_new_packets().

This function also returns Ok(0) once 一个 close_notify alert has been successfully received. No additional data is ever read in this state.

pub fn write_tls(&mut self, wr: &mut dyn Write) -> Result<usize, Error>

将 TLS 消息写入 wr。

On success, 此函数 returns Ok(n) where n 是 number of bytes written 到 wr (after encoding 并 encryption)。

After 此函数 returns, the connection 缓冲区 may not yet be fully flushed. 此 CommonState::wants_write function 可用于 检查 if 输出 缓冲区 is empty.

Methods from Deref<Target = CommonState>

pub fn wants_write(&self) -> bool

如果调用者应尽快调用以下方法，则返回 true： Connection::write_tls 尽快。

pub fn is_handshaking(&self) -> bool

如果连接当前正在执行 TLS 握手，则返回 true。

During this time 明文 written 到 the connection is buffered in memory. After Connection::process_new_packets() has been called, this might start 到 return false while the final handshake packets still need 到 be extracted 从 the connection’s buffers.

pub fn peer_certificates(&self) -> Option<&[CertificateDer<'static>]>

检索对等方用于身份验证的证书链或原始公钥。

此 order of 证书 chain is as it appears in the TLS protocol: the first certificate relates 到 the peer, the second certifies the first, the third certifies the second, 并 so on.

When using raw public keys, the first 并 only element 是 raw 公钥.

This is made available 用于 both full 并 resumed handshakes.

For clients, this 是 certificate chain 或 the raw 公钥 of the server.

For servers, this 是 certificate chain 或 the raw 公钥 of the client, if client authentication was completed.

此 return value is None until this value is available.

Note: the return type of the ‘certificate’, when using raw public keys is CertificateDer<'static> even though this should technically be 一个 SubjectPublicKeyInfoDer<'static>。 This choice simplifies the API 并 ensures backwards compatibility.

pub fn alpn_protocol(&self) -> Option<&[u8]>

检索通过 ALPN 与对等方协商的协议。

A return value of None after handshake completion means no protocol was agreed (because no protocols were offered 或 已接受 by the peer)。

pub fn negotiated_cipher_suite(&self) -> Option<SupportedCipherSuite>

检索与对等方协商的密码套件。

在密码套件协商一致之前返回 None。

pub fn negotiated_key_exchange_group( &self, ) -> Option<&'static dyn SupportedKxGroup>

检索与对等方协商的密钥交换组。

This function may return None depending on the state of the connection, the type of handshake, 并 the protocol version.

If CommonState::is_handshaking() 为 true，此函数将返回 None。 Similarly, if the CommonState::handshake_kind() is HandshakeKind::Resumed 并 the CommonState::protocol_version() is TLS 1.2, then no key exchange will have occurred 并 此函数将返回 None。

pub fn protocol_version(&self) -> Option<ProtocolVersion>

检索与对等方协商的协议版本。

This returns None until the version is agreed.

pub fn handshake_kind(&self) -> Option<HandshakeKind>

执行的握手类型。

它会告知握手是否为恢复握手。

This 将返回 None before it is known which sort of handshake occurred.

pub fn send_close_notify(&mut self)

Queues 一个 close_notify warning alert 到 be sent in the next Connection::write_tls 调用。 This informs the peer that the connection is being closed.

Does nothing if any close_notify 或 fatal alert was already sent.

pub fn wants_read(&self) -> bool

如果调用者应尽快调用以下方法，则返回 true： Connection::read_tls as soon as possible.

如果有要读取的待处理明文数据，请使用 Connection::reader, this returns false. If your application respects this mechanism, only one full TLS message ， buffered by rustls.

Trait 实现

impl Debug for ClientConnection

fn fmt(&self, f: &mut Formatter<'_>) -> Result

使用给定的格式化器格式化此值。 更多信息

impl Deref for ClientConnection

type Target = ConnectionCommon<ClientConnectionData>

解引用后得到的类型。

fn deref(&self) -> &Self::Target

解引用此值。

impl DerefMut for ClientConnection

fn deref_mut(&mut self) -> &mut Self::Target

以可变方式解引用此值。

impl From<ClientConnection> for Connection

fn from(conn: ClientConnection) -> Self

从输入类型转换为此类型。