Tokio Native TLS

https://docs.rs/tokio-native-tls/0.3.1
Admin
This library is an implementation of asynchronous TLS streams using the most appropriate system...
Tokens:23,918
Snippets:242
Trust Score:9.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### TlsConnector::new

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.TlsConnector.html

Creates a new TlsConnector with default settings. This is the primary way to get started with client-side TLS connections.

```APIDOC
## `TlsConnector::new()`

### Description
Returns a new connector with default settings.

### Returns
- `Result<TlsConnector, Error>`: A new `TlsConnector` instance or an error if creation fails.
```

--------------------------------

### Server-side TLS Acceptor Example

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.TlsAcceptor.html

Demonstrates setting up a TLS acceptor, binding to a TCP listener, and handling incoming client connections with TLS.

```rust
use native_tls::{Identity, TlsAcceptor, TlsStream};
use std::fs::File;
use std::io::{Read};
use std::net::{TcpListener, TcpStream};
use std::sync::Arc;
use std::thread;

let mut file = File::open("identity.pfx").unwrap();
let mut identity = vec![];
file.read_to_end(&mut identity).unwrap();
let identity = Identity::from_pkcs12(&identity, "hunter2").unwrap();

let listener = TcpListener::bind("0.0.0.0:8443").unwrap();
let acceptor = TlsAcceptor::new(identity).unwrap();
let acceptor = Arc::new(acceptor);

fn handle_client(stream: TlsStream<TcpStream>) {
    // ...
}

for stream in listener.incoming() {
    match stream {
        Ok(stream) => {
            let acceptor = acceptor.clone();
            thread::spawn(move || {
                let stream = acceptor.accept(stream).unwrap();
                handle_client(stream);
            });
        }
        Err(e) => { /* connection failed */ }
    }
}
```

--------------------------------

### OpenSSL command for PKCS #12 export

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.Identity.html

Example command using OpenSSL to export a PKCS #12 archive. This is useful for creating the `.pfx` or `.p12` files required by `from_pkcs12`.

```bash
openssl pkcs12 -export -out identity.pfx -inkey key.pem -in cert.pem -certfile chain_certs.pem
```

--------------------------------

### TlsConnector::connect

Source: https://docs.rs/tokio-native-tls/0.3.1/src/tokio_native_tls/lib.rs.html

Connects the provided stream with this connector, assuming the provided domain. This function will internally call `TlsConnector::connect` to connect the stream and returns a future representing the resolution of the connection operation. The returned future will resolve to either `TlsStream<S>` or `Error` depending if it's successful or not. This is typically used for clients who have already established, for example, a TCP connection to a remote server. That stream is then provided here to perform the client half of a connection to a TLS-powered server.

```APIDOC
## TlsConnector::connect

### Description
Connects the provided stream with this connector, assuming the provided domain. This function returns a future representing the resolution of the connection operation, which resolves to either `TlsStream<S>` or `Error`.

### Method
`async fn connect<S>(&self, domain: &str, stream: S) -> Result<TlsStream<S>, Error>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
// Example usage (assuming `connector` is a TlsConnector and `stream` is an AsyncRead + AsyncWrite)
let tls_stream = connector.connect("example.com", stream).await;
```

### Response
#### Success Response (Result<TlsStream<S>, Error>)
- `TlsStream<S>`: A TLS-secured stream.
- `Error`: An error if the TLS handshake fails.
```

--------------------------------

### Get Peer Certificate

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.TlsStream.html

Retrieves the peer's leaf certificate from the TLS session, if available. This can be used for authentication or identification purposes.

```rust
pub fn peer_certificate(&self) -> Result<Option<Certificate>, Error>
```

--------------------------------

### Get Mutable Reference to Inner Stream

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.MidHandshakeTlsStream.html

Retrieves a mutable reference to the underlying stream wrapped by MidHandshakeTlsStream.

```rust
pub fn get_mut(&mut self) -> &mut S
```

--------------------------------

### Create and Connect with TlsConnector

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.TlsConnector.html

Demonstrates how to create a `TlsConnector`, establish a TLS connection to a server, send an HTTP request, and read the response. Requires `native_tls` and `std::net::TcpStream`.

```rust
use native_tls::TlsConnector;
use std::io::{Read, Write};
use std::net::TcpStream;

let connector = TlsConnector::new().unwrap();

let stream = TcpStream::connect("google.com:443").unwrap();
let mut stream = connector.connect("google.com", stream).unwrap();

stream.write_all(b"GET / HTTP/1.0\r\n\r\n").unwrap();
let mut res = vec![];
stream.read_to_end(&mut res).unwrap();
println!("{}", String::from_utf8_lossy(&res));
```

--------------------------------

### Get Shared Reference to Inner Stream

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.MidHandshakeTlsStream.html

Retrieves an immutable reference to the underlying stream wrapped by MidHandshakeTlsStream.

```rust
pub fn get_ref(&self) -> &S
```

--------------------------------

### try_from

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/struct.TlsStream.html

Performs the conversion.

```APIDOC
## fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

### Description
Performs the conversion.

### Parameters
- **value** (U) - The value to convert.
```

--------------------------------

### Deprecated Error Cause for HandshakeError

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/enum.HandshakeError.html

Provides a deprecated method for getting the cause of the error. The `Error::source` method is now preferred as it supports downcasting.

```rust
fn cause(&self) -> Option<&dyn Error>
```

--------------------------------

### into

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/struct.TlsStream.html

Calls `U::from(self)`.

```APIDOC
## fn into(self) -> U

### Description
Calls `U::from(self)`.
That is, this conversion is whatever the implementation of `From<T> for U` chooses to do.
```

--------------------------------

### TlsAcceptor::new

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.TlsAcceptor.html

Creates a new TlsAcceptor with default settings. The provided identity is used as the server's certificate chain and private key.

```APIDOC
## `TlsAcceptor::new`

### Description
Creates a acceptor with default settings. The identity acts as the server’s private key/certificate chain.

### Signature
```rust
pub fn new(identity: Identity) -> Result<TlsAcceptor, Error>
```

### Parameters
* `identity`: An `Identity` struct containing the server's certificate and private key.
```

--------------------------------

### Deprecated Error Description for HandshakeError

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/enum.HandshakeError.html

Provides a deprecated method for getting a string description of the error. It is recommended to use the Display implementation or `to_string()` instead.

```rust
fn description(&self) -> &str
```

--------------------------------

### try_into

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/struct.TlsStream.html

Performs the conversion.

```APIDOC
## fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

### Description
Performs the conversion.
```

--------------------------------

### Get Buffered Read Size

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.TlsStream.html

Returns the number of bytes that can be read from the TLS stream without requiring network I/O. This is useful for optimizing read operations.

```rust
pub fn buffered_read_size(&self) -> Result<usize, Error>
```

--------------------------------

### Async TLS Connection with TlsConnector

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/struct.TlsConnector.html

Use this method to establish a TLS connection for clients that have already set up a stream, such as a TCP connection. It takes the domain and the stream, returning a future that resolves to a TlsStream or an Error.

```rust
pub async fn connect<S>(
  &self,
  domain: &str,
  stream: S
) -> Result<TlsStream<S>, Error>
where
  S: AsyncRead + AsyncWrite + Unpin,
```

--------------------------------

### Build TlsAcceptor

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.TlsAcceptorBuilder.html

Creates a new TlsAcceptor instance from the configured TlsAcceptorBuilder. This operation can result in an error.

```rust
pub fn build(&self) -> Result<TlsAcceptor, Error>
```

--------------------------------

### Get TLS Server End Point Channel Binding Data

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.TlsStream.html

Retrieves the TLS-server-end-point channel binding data as defined in RFC 5929. This is often used for security protocols that require proof of the TLS session.

```rust
pub fn tls_server_end_point(&self) -> Result<Option<Vec<u8, Global>>, Error>
```

--------------------------------

### TlsAcceptorBuilder::build

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.TlsAcceptorBuilder.html

Creates a new TlsAcceptor instance based on the builder's configuration.

```APIDOC
## TlsAcceptorBuilder::build

### Description
Creates a new `TlsAcceptor`.

### Method Signature
```rust
pub fn build(&self) -> Result<TlsAcceptor, Error>
```

### Returns
* `Result<TlsAcceptor, Error>` - A `Result` containing the `TlsAcceptor` on success, or an `Error` on failure.
```

--------------------------------

### write_all

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/struct.TlsStream.html

Attempts to write an entire buffer into this writer.

```APIDOC
## fn write_all<'a>(&'a mut self, src: &'a [u8]) -> WriteAll<'a, Self>

### Description
Attempts to write an entire buffer into this writer.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- `src` (&'a [u8]): A slice of bytes to write.

### Request Example
```rust
// Example usage would depend on the specific implementation of AsyncWrite
```

### Response
#### Success Response
- `WriteAll<'a, Self>`: A future that resolves when the entire buffer has been written.
```

--------------------------------

### Async Accept Method for TlsAcceptor

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/struct.TlsAcceptor.html

The async accept method on TlsAcceptor is used to accept a new client connection with a given stream. It returns a future that resolves to a TlsStream or an Error.

```rust
pub async fn accept<S>(&self, stream: S) -> Result<TlsStream<S>, Error>where
  S: AsyncRead + AsyncWrite + Unpin,
```

--------------------------------

### Create By-Reference Reader Adaptor

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.TlsStream.html

Creates a "by reference" adaptor for the TlsStream reader. This allows borrowing the stream as a reader.

```rust
fn by_ref(&mut self) -> &mut Selfwhere
  Self: Sized,
```

--------------------------------

### Create Identity from PKCS #12 archive

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.Identity.html

Parses a DER-formatted PKCS #12 archive using a password. The archive should contain a leaf certificate, its private key, and any intermediate certificates.

```rust
pub fn from_pkcs12(der: &[u8], password: &str) -> Result<Identity, Error>
```

--------------------------------

### Clone Certificate

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.Certificate.html

Returns a copy of the certificate. This allows you to have multiple independent references to the same certificate data.

```rust
fn clone(&self) -> Certificate
```

--------------------------------

### AsRawSocket Implementation for TlsStream (Windows)

Source: https://docs.rs/tokio-native-tls/0.3.1/src/tokio_native_tls/lib.rs.html

Provides access to the raw socket for TlsStream on Windows systems. This enables integration with Windows-specific socket APIs.

```rust
#[cfg(windows)]
impl<S> AsRawSocket for TlsStream<S>
where
    S: AsRawSocket,
{
    fn as_raw_socket(&self) -> RawSocket {
        self.get_ref().get_ref().get_ref().as_raw_socket()
    }
}
```

--------------------------------

### TlsAcceptor::accept

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.TlsAcceptor.html

Initiates a TLS handshake on a given stream. This method is crucial for establishing a secure connection with a client.

```APIDOC
## `TlsAcceptor::accept`

### Description
Initiates a TLS handshake. If the socket is nonblocking and a `WouldBlock` error is returned during the handshake, a `HandshakeError::WouldBlock` error will be returned which can be used to restart the handshake when the socket is ready again.

### Signature
```rust
pub fn accept<S>(&self, stream: S) -> Result<TlsStream<S>, HandshakeError<S>> where S: Read + Write
```

### Parameters
* `stream`: A type implementing `Read` and `Write` traits, representing the underlying network stream.

### Returns
A `Result` containing either a `TlsStream<S>` upon successful handshake, or a `HandshakeError<S>` if the handshake fails or would block.
```

--------------------------------

### TlsAcceptor

Source: https://docs.rs/tokio-native-tls

A wrapper around a native_tls::TlsAcceptor, providing an async `accept` method for accepting incoming TLS connections.

```APIDOC
## TlsAcceptor

### Description
Provides an asynchronous `accept` method for accepting incoming TLS connections.

### Struct
TlsAcceptor

### Methods
- `accept(stream)`: Asynchronously accepts an incoming TLS connection.

### Usage
Configuration of TLS parameters is primarily done through the `native-tls` crate.
```

--------------------------------

### AsRawFd Implementation for TlsStream (Unix)

Source: https://docs.rs/tokio-native-tls/0.3.1/src/tokio_native_tls/lib.rs.html

Provides access to the raw file descriptor for TlsStream on Unix-like systems. This allows integration with systems that require raw file descriptor access.

```rust
#[cfg(unix)]
impl<S> AsRawFd for TlsStream<S>
where
    S: AsRawFd,
{
    fn as_raw_fd(&self) -> RawFd {
        self.get_ref().get_ref().get_ref().as_raw_fd()
    }
}
```

--------------------------------

### TlsConnectorBuilder Methods

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.TlsConnectorBuilder.html

This section details the methods available on TlsConnectorBuilder for configuring TLS connections.

```APIDOC
## `identity`

### Description
Sets the identity to be used for client certificate authentication.

### Method
`identity(&mut self, identity: Identity) -> &mut TlsConnectorBuilder`

### Parameters
- `identity` (Identity) - The identity to set for client authentication.
```

```APIDOC
## `min_protocol_version`

### Description
Sets the minimum supported protocol version. A value of `None` enables support for the oldest protocols supported by the implementation. Defaults to `Some(Protocol::Tlsv10)`.

### Method
`min_protocol_version(&mut self, protocol: Option<Protocol>) -> &mut TlsConnectorBuilder`

### Parameters
- `protocol` (Option<Protocol>) - The minimum protocol version to support.
```

```APIDOC
## `max_protocol_version`

### Description
Sets the maximum supported protocol version. A value of `None` enables support for the newest protocols supported by the implementation. Defaults to `None`.

### Method
`max_protocol_version(&mut self, protocol: Option<Protocol>) -> &mut TlsConnectorBuilder`

### Parameters
- `protocol` (Option<Protocol>) - The maximum protocol version to support.
```

```APIDOC
## `add_root_certificate`

### Description
Adds a certificate to the set of roots that the connector will trust. The connector will use the system’s trust root by default. This method can be used to add to that set when communicating with servers not trusted by the system. Defaults to an empty set.

### Method
`add_root_certificate(&mut self, cert: Certificate) -> &mut TlsConnectorBuilder`

### Parameters
- `cert` (Certificate) - The certificate to add to the trusted roots.
```

```APIDOC
## `disable_built_in_roots`

### Description
Controls the use of built-in system certificates during certificate validation. Defaults to `false` – built-in system certs will be used.

### Method
`disable_built_in_roots(&mut self, disable: bool) -> &mut TlsConnectorBuilder`

### Parameters
- `disable` (bool) - If `true`, built-in system certificates will not be used.
```

```APIDOC
## `danger_accept_invalid_certs`

### Description
Controls the use of certificate validation. Defaults to `false`. Warning: You should think very carefully before using this method. If invalid certificates are trusted, _any_ certificate for _any_ site will be trusted for use. This includes expired certificates. This introduces significant vulnerabilities, and should only be used as a last resort.

### Method
`danger_accept_invalid_certs(&mut self, accept_invalid_certs: bool) -> &mut TlsConnectorBuilder`

### Parameters
- `accept_invalid_certs` (bool) - If `true`, invalid certificates will be accepted.
```

```APIDOC
## `use_sni`

### Description
Controls the use of Server Name Indication (SNI). Defaults to `true`.

### Method
`use_sni(&mut self, use_sni: bool) -> &mut TlsConnectorBuilder`

### Parameters
- `use_sni` (bool) - If `true`, SNI will be used.
```

```APIDOC
## `danger_accept_invalid_hostnames`

### Description
Controls the use of hostname verification. Defaults to `false`. Warning: You should think very carefully before using this method. If invalid hostnames are trusted, _any_ valid certificate for _any_ site will be trusted for use. This introduces significant vulnerabilities, and should only be used as a last resort.

### Method
`danger_accept_invalid_hostnames(&mut self, accept_invalid_hostnames: bool) -> &mut TlsConnectorBuilder`

### Parameters
- `accept_invalid_hostnames` (bool) - If `true`, invalid hostnames will be accepted.
```

```APIDOC
## `build`

### Description
Creates a new `TlsConnector`.

### Method
`build(&self) -> Result<TlsConnector, Error>`

### Response
#### Success Response
- `TlsConnector` - A new `TlsConnector` instance.
- `Error` - An error if the connector could not be built.
```

--------------------------------

### write_all_buf

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/struct.TlsStream.html

Attempts to write an entire buffer into this writer.

```APIDOC
## fn write_all_buf<B, 'a>(&'a mut self, src: &'a mut B) -> WriteAllBuf<'a, Self, B>

### Description
Attempts to write an entire buffer into this writer.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- `src` (&'a mut B): A mutable reference to a buffer implementing the `Buf` trait.

### Request Example
```rust
// Example usage would depend on the specific implementation of AsyncWrite and Buf
```

### Response
#### Success Response
- `WriteAllBuf<'a, Self, B>`: A future that resolves when the entire buffer has been written.
```

--------------------------------

### Sync for AllowStd<S>

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/struct.AllowStd.html

Implementation of the Sync trait for AllowStd<S> where S: Sync.

```APIDOC
### impl<S: Sync> Sync for AllowStd<S>

```rust
impl<S: Sync> Sync for AllowStd<S>
```
```

--------------------------------

### TlsAcceptor::builder

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.TlsAcceptor.html

Returns a new builder for a TlsAcceptor, allowing for more granular configuration of TLS settings.

```APIDOC
## `TlsAcceptor::builder`

### Description
Returns a new builder for a `TlsAcceptor`. The identity acts as the server’s private key/certificate chain.

### Signature
```rust
pub fn builder(identity: Identity) -> TlsAcceptorBuilder
```

### Parameters
* `identity`: An `Identity` struct containing the server's certificate and private key.

### Returns
A `TlsAcceptorBuilder` instance for further configuration.
```

--------------------------------

### From<T> for T Implementation

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/enum.HandshakeError.html

A trivial implementation of `From<T>` for `T`, which simply returns the input value unchanged. Useful in generic contexts.

```rust
fn from(t: T) -> T
```

--------------------------------

### from

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/struct.TlsStream.html

Returns the argument unchanged.

```APIDOC
## fn from(t: T) -> T

### Description
Returns the argument unchanged.

### Parameters
- **t** (T) - The value to return.
```

--------------------------------

### Set minimum protocol version

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.TlsAcceptorBuilder.html

Configures the minimum TLS protocol version supported by the TlsAcceptor. Setting this to None allows support for the oldest protocols. Defaults to Some(Protocol::Tlsv10).

```rust
pub fn min_protocol_version(
  &mut self,
  protocol: Option<Protocol>
) -> &mut TlsAcceptorBuilder
```

--------------------------------

### ToString Implementation

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/enum.HandshakeError.html

Converts a type that implements `Display` into a `String`. This is a common utility for string representations.

```rust
default fn to_string(&self) -> String
```

--------------------------------

### Certificate::from_pem

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.Certificate.html

Parses a PEM-formatted X509 certificate.

```APIDOC
## pub fn from_pem(pem: &[u8]) -> Result<Certificate, Error>

### Description
Parses a PEM-formatted X509 certificate.

### Parameters
* `pem`: A byte slice representing the PEM-encoded certificate.

### Returns
A `Result` containing a `Certificate` on success, or an `Error` on failure.
```

--------------------------------

### TlsConnector

Source: https://docs.rs/tokio-native-tls

A wrapper around a native_tls::TlsConnector, providing an async `connect` method for establishing TLS connections.

```APIDOC
## TlsConnector

### Description
Provides an asynchronous `connect` method for establishing TLS connections.

### Struct
TlsConnector

### Methods
- `connect(domain, stream)`: Asynchronously establishes a TLS connection.

### Usage
Configuration of TLS parameters is primarily done through the `native-tls` crate.
```

--------------------------------

### Clone From Certificate

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.Certificate.html

Performs copy-assignment from a source certificate to the current one. This is an efficient way to update an existing certificate with the data from another.

```rust
fn clone_from(&mut self, source: &Self)
```

--------------------------------

### Take Limited Bytes from TlsStream

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.TlsStream.html

Creates an adapter that reads at most a specified number of bytes from the TlsStream. Useful for reading fixed-size chunks.

```rust
fn take(self, limit: u64) -> Take<Self>where
  Self: Sized,
```

--------------------------------

### Create Identity from PEM encoded data

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.Identity.html

Parses a chain of PEM encoded X509 certificates and a PEM encoded PKCS #8 private key. The certificate chain should include intermediate certificates.

```rust
pub fn from_pkcs8(pem: &[u8], key: &[u8]) -> Result<Identity, Error>
```

--------------------------------

### Certificate::from_der

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.Certificate.html

Parses a DER-formatted X509 certificate.

```APIDOC
## pub fn from_der(der: &[u8]) -> Result<Certificate, Error>

### Description
Parses a DER-formatted X509 certificate.

### Parameters
* `der`: A byte slice representing the DER-encoded certificate.

### Returns
A `Result` containing a `Certificate` on success, or an `Error` on failure.
```

--------------------------------

### Nightly-Only Error Context Provider

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/enum.HandshakeError.html

An experimental, nightly-only API for providing type-based access to error context, intended for error reporting.

```rust
fn provide<'a>(&'a self, demand: &mut Demand<'a>)
```

--------------------------------

### AsyncWrite Implementation for TlsStream

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/struct.TlsStream.html

Provides asynchronous writing capabilities for TlsStream.

```APIDOC
## TlsStream::poll_write

### Description
Attempt to write bytes from `buf` into the object.

### Method
`poll_write`

### Parameters
- `self: Pin<&mut Self>` - A pinned mutable reference to the TlsStream.
- `ctx: &mut Context<'_>` - The polling context.
- `buf: &[u8]` - The buffer containing the bytes to write.

### Returns
`Poll<Result<usize>>` - The polling result indicating the number of bytes written.
```

```APIDOC
## TlsStream::poll_flush

### Description
Attempts to flush the object, ensuring that any buffered data reach their destination.

### Method
`poll_flush`

### Parameters
- `self: Pin<&mut Self>` - A pinned mutable reference to the TlsStream.
- `ctx: &mut Context<'_>` - The polling context.

### Returns
`Poll<Result<()>>` - The polling result indicating if the flush was successful.
```

```APIDOC
## TlsStream::poll_shutdown

### Description
Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down.

### Method
`poll_shutdown`

### Parameters
- `self: Pin<&mut Self>` - A pinned mutable reference to the TlsStream.
- `ctx: &mut Context<'_>` - The polling context.

### Returns
`Poll<Result<()>>` - The polling result indicating if the shutdown was successful.
```

```APIDOC
## TlsStream::poll_write_vectored

### Description
Like `poll_write`, except that it writes from a slice of buffers.

### Method
`poll_write_vectored`

### Parameters
- `self: Pin<&mut Self>` - A pinned mutable reference to the TlsStream.
- `cx: &mut Context<'_>` - The polling context.
- `bufs: &[IoSlice<'_>]` - A slice of buffers to write from.

### Returns
`Poll<Result<usize, Error>>` - The polling result indicating the number of bytes written.
```

```APIDOC
## TlsStream::is_write_vectored

### Description
Determines if this writer has an efficient `poll_write_vectored` implementation.

### Method
`is_write_vectored`

### Parameters
None

### Returns
`bool` - True if `poll_write_vectored` is efficiently implemented, false otherwise.
```

--------------------------------

### TlsAcceptor::clone

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.TlsAcceptor.html

Creates a copy of the TlsAcceptor. This is useful for sharing the acceptor across multiple threads.

```APIDOC
## `TlsAcceptor::clone`

### Description
Returns a copy of the value.

### Signature
```rust
fn clone(&self) -> TlsAcceptor
```

### Returns
A new `TlsAcceptor` instance that is a copy of the original.
```

--------------------------------

### Client TLS Connection with Tokio Native TLS

Source: https://docs.rs/tokio-native-tls/0.3.1/src/tokio_native_tls/lib.rs.html

Establishes a TLS connection to a remote server using the provided domain and an existing asynchronous stream. This is typically used for client-side connections after a TCP connection has been established.

```rust
impl TlsConnector {
    /// Connects the provided stream with this connector, assuming the provided
    /// domain.
    ///
    /// This function will internally call `TlsConnector::connect` to connect
    /// the stream and returns a future representing the resolution of the
    /// connection operation. The returned future will resolve to either
    /// `TlsStream<S>` or `Error` depending if it's successful or not.
    ///
    /// This is typically used for clients who have already established, for
    /// example, a TCP connection to a remote server. That stream is then
    /// provided here to perform the client half of a connection to a
    /// TLS-powered server.
    pub async fn connect<S>(&self, domain: &str, stream: S) -> Result<TlsStream<S>, Error>
    where
        S: AsyncRead + AsyncWrite + Unpin,
    {
        handshake(move |s| self.0.connect(domain, s), stream).await
    }
}
```

--------------------------------

### Implement Send and Sync for AllowStd

Source: https://docs.rs/tokio-native-tls/0.3.1/src/tokio_native_tls/lib.rs.html

Ensures that AllowStd<S> can be safely sent across threads when S is Send or Sync, respectively. This is crucial for concurrent operations in asynchronous environments.

```rust
// *mut () context is neither Send nor Sync
unsafe impl<S: Send> Send for AllowStd<S> {}
unsafe impl<S: Sync> Sync for AllowStd<S> {}
```

--------------------------------

### Set maximum protocol version

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.TlsAcceptorBuilder.html

Configures the maximum TLS protocol version supported by the TlsAcceptor. Setting this to None allows support for the newest protocols. Defaults to None.

```rust
pub fn max_protocol_version(
  &mut self,
  protocol: Option<Protocol>
) -> &mut TlsAcceptorBuilder
```

--------------------------------

### Write All Vectored Buffers to TlsStream

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.TlsStream.html

Attempts to write multiple buffers to the TLS stream. This is a nightly-only experimental API.

```rust
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
```

--------------------------------

### Chain TlsStream with Another Reader

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.TlsStream.html

Creates an adapter that chains the TlsStream with another reader. Reads will be made from this stream first, then the next.

```rust
fn chain<R>(self, next: R) -> Chain<Self, R>where
  R: Read,
  Self: Sized,
```

--------------------------------

### Type Any Implementation

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/enum.HandshakeError.html

Provides runtime type information for types that implement the `Any` trait. This is a standard trait for trait objects.

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### TlsConnector::connect

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/struct.TlsConnector.html

Asynchronously connects a given stream with this connector for a specified domain. This is useful for clients that have an existing stream (like a TCP connection) and want to upgrade it to a TLS connection.

```APIDOC
## pub async fn connect<S>(self, domain: &str, stream: S) -> Result<TlsStream<S>, Error>

### Description
Connects the provided stream with this connector, assuming the provided domain.
This function will internally call `TlsConnector::connect` to connect the stream and returns a future representing the resolution of the connection operation. The returned future will resolve to either `TlsStream<S>` or `Error` depending if it’s successful or not.
This is typically used for clients who have already established, for example, a TCP connection to a remote server. That stream is then provided here to perform the client half of a connection to a TLS-powered server.

### Parameters
#### Path Parameters
- **domain** (str) - Required - The domain name to connect to.
- **stream** (S) - Required - The stream to connect, must implement `AsyncRead + AsyncWrite + Unpin`.

### Returns
- `Result<TlsStream<S>, Error>` - A future that resolves to a `TlsStream` on success or an `Error` on failure.
```

--------------------------------

### TlsStream Blanket Implementations

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.TlsStream.html

This section covers the blanket implementations for the TlsStream struct, showing how it can be used with various standard traits.

```APIDOC
## impl<T> Any for T
where
  T: 'static + ?Sized,

#### fn type_id(&self) -> TypeId
Gets the `TypeId` of `self`.

## impl<T> Borrow<T> for T
where
  T: ?Sized,

#### fn borrow(&self) -> &T
Immutably borrows from an owned value.

## impl<T> BorrowMut<T> for T
where
  T: ?Sized,

#### fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value.

## impl<T> From<T> for T

#### fn from(t: T) -> T
Returns the argument unchanged.

## impl<T, U> Into<U> for T
where
  U: From<T>,

#### fn into(self) -> U
Calls `U::from(self)`.

## impl<T, U> TryFrom<U> for T
where
  U: Into<T>,

#### type Error = Infallible
The type returned in the event of a conversion error.

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
Performs the conversion.

## impl<T, U> TryInto<U> for T
where
  U: TryFrom<T>,

#### type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.

#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
Performs the conversion.
```

--------------------------------

### Debug Implementation for TlsStream

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/struct.TlsStream.html

Provides debugging capabilities for TlsStream.

```APIDOC
## TlsStream::fmt

### Description
Formats the value using the given formatter.

### Method
`fmt`

### Parameters
- `f: &mut Formatter<'_>` - The formatter to use.

### Returns
`Result` - The result of the formatting operation.
```

--------------------------------

### AsyncRead Implementation for TlsStream

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/struct.TlsStream.html

Provides asynchronous reading capabilities for TlsStream.

```APIDOC
## TlsStream::poll_read

### Description
Attempts to read from the `AsyncRead` into `buf`.

### Method
`poll_read`

### Parameters
- `self: Pin<&mut Self>` - A pinned mutable reference to the TlsStream.
- `ctx: &mut Context<'_>` - The polling context.
- `buf: &mut ReadBuf<'_>` - The buffer to read data into.

### Returns
`Poll<Result<()>>` - The polling result indicating if data was read.
```

--------------------------------

### TryInto<U> Implementation

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/enum.HandshakeError.html

Attempts to convert a type `T` into another type `U` using `TryFrom`. Returns `Ok(U)` on success or an error if the conversion fails.

```rust
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
```

--------------------------------

### write_i64_le

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/struct.TlsStream.html

Writes a signed 64-bit integer in little-endian order to the underlying writer.

```APIDOC
## fn write_i64_le<'a>(&'a mut self, n: i64) -> WriteI64Le<&'a mut Self>

### Description
Writes a signed 64-bit integer in little-endian order to the underlying writer.

### Parameters
- **n** (i64) - The signed 64-bit integer to write.
```

--------------------------------

### Write for AllowStd<S>

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/struct.AllowStd.html

Implementation of the Write trait for AllowStd<S> where S: AsyncWrite + Unpin.

```APIDOC
### impl<S> Write for AllowStd<S>

where
    S: AsyncWrite + Unpin,

#### fn write(&mut self, buf: &[u8]) -> Result<usize>

Write a buffer into this writer, returning how many bytes were written.

```rust
fn write(&mut self, buf: &[u8]) -> Result<usize>
```

#### fn flush(&mut self) -> Result<()>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

```rust
fn flush(&mut self) -> Result<()>
```

#### fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like `write`, except that it writes from a slice of buffers.

```rust
fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>
```

#### fn is_write_vectored(&self) -> bool

Determines if this `Write`r has an efficient `write_vectored` implementation.

```rust
fn is_write_vectored(&self) -> bool
```

#### fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

```rust
fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
```

#### fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

Attempts to write multiple buffers into this writer.

```rust
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
```

#### fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

```rust
fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<(), Error>
```

#### fn by_ref(&mut self) -> &mut Self

Creates a “by reference” adapter for this instance of `Write`.

```rust
fn by_ref(&mut self) -> &mut Self
```
```

--------------------------------

### write

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/struct.TlsStream.html

Writes a buffer into this writer, returning how many bytes were written.

```APIDOC
## fn write<'a>(&'a mut self, src: &'a [u8]) -> Write<'a, Self>

### Description
Writes a buffer into this writer, returning how many bytes were written.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Request Example
```rust
// Example usage would depend on the specific implementation of AsyncWrite
```

### Response
#### Success Response
- `Write<'a, Self>`: A future that resolves to the number of bytes written.
```

--------------------------------

### TlsConnector::builder

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.TlsConnector.html

Provides access to a builder for configuring a TlsConnector with custom settings.

```APIDOC
## `TlsConnector::builder()`

### Description
Returns a new builder for a `TlsConnector`.

### Returns
- `TlsConnectorBuilder`: A builder object that can be used to configure TLS settings.
```

--------------------------------

### borrow

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/struct.TlsStream.html

Immutably borrows from an owned value.

```APIDOC
## fn borrow(&self) -> &T

### Description
Immutably borrows from an owned value.
```

--------------------------------

### TlsConnector::connect

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.TlsConnector.html

Initiates a TLS handshake with a given stream and domain. The domain is used for SNI and certificate validation.

```APIDOC
## `TlsConnector::connect()`

### Description
Initiates a TLS handshake. The provided domain will be used for both SNI and certificate hostname validation. If the socket is nonblocking and a `WouldBlock` error is returned during the handshake, a `HandshakeError::WouldBlock` error will be returned which can be used to restart the handshake when the socket is ready again. The domain is ignored if both SNI and hostname verification are disabled.

### Parameters
- **domain**: `&str` - The domain name to use for SNI and certificate validation.
- **stream**: `S` - The underlying stream (e.g., `TcpStream`) to perform the handshake on. Must implement `Read` and `Write`.

### Returns
- `Result<TlsStream<S>, HandshakeError<S>>`: A `TlsStream` on success, or a `HandshakeError` if the handshake fails.
```

--------------------------------

### TlsAcceptor::accept

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/struct.TlsAcceptor.html

Accepts a new client connection with the provided stream. This function internally calls `TlsAcceptor::accept` to connect the stream and returns a future representing the resolution of the connection operation. The returned future will resolve to either `TlsStream<S>` or `Error` depending if it’s successful or not. This is typically used after a new socket has been accepted from a `TcpListener`. That socket is then passed to this function to perform the server half of accepting a client connection.

```APIDOC
## async fn accept<S>(&self, stream: S) -> Result<TlsStream<S>, Error>

### Description
Accepts a new client connection with the provided stream. This function will internally call `TlsAcceptor::accept` to connect the stream and returns a future representing the resolution of the connection operation. The returned future will resolve to either `TlsStream<S>` or `Error` depending if it’s successful or not.

This is typically used after a new socket has been accepted from a `TcpListener`. That socket is then passed to this function to perform the server half of accepting a client connection.

### Parameters
#### Path Parameters
- **stream** (S): An async read/write stream that is Unpin.

### Returns
- `Result<TlsStream<S>, Error>`: A future that resolves to a `TlsStream<S>` on success or an `Error` on failure.
```

--------------------------------

### Parse PEM Certificate

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.Certificate.html

Parses a PEM-formatted X509 certificate. Use this when your certificate data is in PEM format.

```rust
pub fn from_pem(pem: &[u8]) -> Result<Certificate, Error>
```

--------------------------------

### write_i64

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/struct.TlsStream.html

Writes a signed 64-bit integer in big-endian order to the underlying writer.

```APIDOC
## fn write_i64<'a>(&'a mut self, n: i64) -> WriteI64<&'a mut Self>

### Description
Writes a signed 64-bit integer in big-endian order to the underlying writer.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- `n` (i64): The signed 64-bit integer to write.

### Request Example
```rust
// Example usage would depend on the specific implementation of AsyncWrite
```

### Response
#### Success Response
- `WriteI64<&'a mut Self>`: A future that resolves when the integer has been written.
```

--------------------------------

### TlsAcceptorBuilder::min_protocol_version

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.TlsAcceptorBuilder.html

Sets the minimum supported protocol version for TLS connections. Defaults to Some(Protocol::Tlsv10). A value of None enables support for the oldest protocols supported by the implementation.

```APIDOC
## TlsAcceptorBuilder::min_protocol_version

### Description
Sets the minimum supported protocol version for TLS connections.

A value of `None` enables support for the oldest protocols supported by the implementation.

Defaults to `Some(Protocol::Tlsv10)`.

### Method Signature
```rust
pub fn min_protocol_version(&mut self, protocol: Option<Protocol>) -> &mut TlsAcceptorBuilder
```

### Parameters
* `protocol` (Option<Protocol>) - The minimum protocol version to support.
```

--------------------------------

### Server TLS Connection Acceptance with Tokio Native TLS

Source: https://docs.rs/tokio-native-tls/0.3.1/src/tokio_native_tls/lib.rs.html

Accepts a new TLS client connection using the provided asynchronous stream. This is typically used on the server-side after accepting a new socket connection from a `TcpListener`.

```rust
impl TlsAcceptor {
    /// Accepts a new client connection with the provided stream.
    ///
    /// This function will internally call `TlsAcceptor::accept` to connect
    /// the stream and returns a future representing the resolution of the
    /// connection operation. The returned future will resolve to either
    /// `TlsStream<S>` or `Error` depending if it's successful or not.
    ///
    /// This is typically used after a new socket has been accepted from a
    /// `TcpListener`. That socket is then passed to this function to perform
    /// the server half of accepting a client connection.
    pub async fn accept<S>(&self, stream: S) -> Result<TlsStream<S>, Error>
    where
        S: AsyncRead + AsyncWrite + Unpin,
    {
        handshake(move |s| self.0.accept(s), stream).await
    }
}
```

--------------------------------

### write_i32_le

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/struct.TlsStream.html

Writes a signed 32-bit integer in little-endian order to the underlying writer.

```APIDOC
## fn write_i32_le<'a>(&'a mut self, n: i32) -> WriteI32Le<&'a mut Self>

### Description
Writes a signed 32-bit integer in little-endian order to the underlying writer.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- `n` (i32): The signed 32-bit integer to write.

### Request Example
```rust
// Example usage would depend on the specific implementation of AsyncWrite
```

### Response
#### Success Response
- `WriteI32Le<&'a mut Self>`: A future that resolves when the integer has been written.
```

--------------------------------

### Read Exact into Borrowed Cursor

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.TlsStream.html

Reads the exact number of bytes required to fill a borrowed cursor. This is a nightly-only experimental API.

```rust
fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>
```

--------------------------------

### TryFrom<U> for T Implementation

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/enum.HandshakeError.html

Attempts to convert a type `U` into type `T`. Returns `Ok(T)` on success or `Err(Infallible)` if the conversion fails (though this specific implementation is infallible).

```rust
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
```

--------------------------------

### Convert Certificate to DER

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/native_tls/struct.Certificate.html

Returns the DER-encoded representation of this certificate. This is useful for exporting or transmitting the certificate in a standard binary format.

```rust
pub fn to_der(&self) -> Result<Vec<u8, Global>, Error>
```

--------------------------------

### AllowStd Context Handling

Source: https://docs.rs/tokio-native-tls/0.3.1/src/tokio_native_tls/lib.rs.html

Manages the context for TLS operations within the AllowStd wrapper. It asserts the context is not null and handles the polling of the inner stream, converting pending states to WouldBlock errors.

```rust
impl<S>
AllowStd<S>
where
    S: Unpin,
{
    fn with_context<F, R>(&mut self, f: F) -> io::Result<R>
    where
        F: FnOnce(&mut Context<'_>, Pin<&mut S>) -> Poll<io::Result<R>>,
    {
        unsafe {
            assert!(!self.context.is_null());
            let waker = &mut *(self.context as *mut _);
            match f(waker, Pin::new(&mut self.inner)) {
                Poll::Ready(r) => r,
                Poll::Pending => Err(io::Error::from(io::ErrorKind::WouldBlock)),
            }
        }
    }
}
```

--------------------------------

### write_i32

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/struct.TlsStream.html

Writes a signed 32-bit integer in big-endian order to the underlying writer.

```APIDOC
## fn write_i32<'a>(&'a mut self, n: i32) -> WriteI32<&'a mut Self>

### Description
Writes a signed 32-bit integer in big-endian order to the underlying writer.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- `n` (i32): The signed 32-bit integer to write.

### Request Example
```rust
// Example usage would depend on the specific implementation of AsyncWrite
```

### Response
#### Success Response
- `WriteI32<&'a mut Self>`: A future that resolves when the integer has been written.
```

--------------------------------

### write_i8

Source: https://docs.rs/tokio-native-tls/0.3.1/tokio_native_tls/struct.TlsStream.html

Writes a signed 8-bit integer to the underlying writer.

```APIDOC
## fn write_i8<'a>(&'a mut self, n: i8) -> WriteI8<&'a mut Self>

### Description
Writes a signed 8-bit integer to the underlying writer.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- `n` (i8): The signed 8-bit integer to write.

### Request Example
```rust
// Example usage would depend on the specific implementation of AsyncWrite
```

### Response
#### Success Response
- `WriteI8<&'a mut Self>`: A future that resolves when the byte has been written.
```

--------------------------------

### StartedHandshakeFuture Polling Logic

Source: https://docs.rs/tokio-native-tls/0.3.1/src/tokio_native_tls/lib.rs.html

Handles the polling logic for the StartedHandshakeFuture. It unwraps the inner future, creates an AllowStd stream with the current context, and prepares for the handshake operation.

```rust
impl<F, S> Future for StartedHandshakeFuture<F, S>
where
    F: FnOnce(
            AllowStd<S>,
        ) -> Result<native_tls::TlsStream<AllowStd<S>>, HandshakeError<AllowStd<S>>>
        + Unpin,
    S: Unpin,
    AllowStd<S>: Read + Write,
{
    type Output = Result<StartedHandshake<S>, Error>;

    fn poll(
        mut self: Pin<&mut Self>,
        ctx: &mut Context<'_>,
    ) -> Poll<Result<StartedHandshake<S>, Error>> {
        let inner = self.0.take().expect("future polled after completion");
        let stream = AllowStd {
            inner: inner.stream,
            context: ctx as *mut _ as *mut (),
        };

```
Tokens:
Raw