TLS

[!NOTE] This document is partially generated by AI.

The TLS (Transport Layer Security) protocol provides cryptographic security for communications over a network. in yuhaiin, TLS is a fundamental layer used to secure various proxy and transport protocols.

Network Support

• TCP: Supported (Stream-based).
• UDP: Not supported. TLS is inherently a stream-oriented security layer. For UDP security, use DTLS or QUIC (which incorporates TLS 1.3).

Client Configuration (Outbound)

When used as an outbound layer, the tls block contains the following fields:

Configuration Fields

• enable (bool): Enables or disables TLS for the connection.
• servernames (string array): A list of hostnames to be used for Server Name Indication (SNI). This is critical for connecting to servers that host multiple domains on a single IP.
• ca_cert (bytes array): (Optional) Custom CA certificates to use for verifying the server’s certificate.
• insecure_skip_verify (bool): If set to true, yuhaiin will skip the verification of the server’s certificate chain and hostname. Warning: This makes the connection vulnerable to man-in-the-middle attacks.
• next_protos (string array): ALPN (Application-Layer Protocol Negotiation) values.
  • Examples: ["h2", "http/1.1"] to negotiate HTTP/2 or HTTP/1.1.
• ech_config (bytes): Configuration for Encrypted Client Hello (ECH), providing enhanced privacy by encrypting the SNI.

---

Server Configuration (Inbound)

For an inbound listener (e.g., a Trojan or VMess server), TLS configuration is handled within the tls section of the listener.

Configuration Fields

• certificates (array): A list of certificates the server will present to clients.
  • cert (bytes): The public certificate data.
  • key (bytes): The private key data.
• next_protos (string array): ALPN values the server supports.

Example Configuration

Outbound Example

{
  "tls": {
    "enable": true,
    "servernames": ["www.example.com"],
    "next_protos": ["h2", "http/1.1"]
  }
}

Inbound Example (within a listener)

{
  "tls": {
    "certificates": [
      {
        "cert": "...base64_cert_data...",
        "key": "...base64_key_data..."
      }
    ]
  }
}

Developer Details

Implementation

TLS in yuhaiin is built on top of the standard Go crypto/tls package. It provides a transparent wrapper for net.Conn and netapi.Proxy objects.

Security Features

• ECH Support: Implements the latest drafts for Encrypted Client Hello.
• ALPN: Robust negotiation for modern protocols like HTTP/2 and gRPC.
• Certificate Pinning: Possible via ca_cert field.