LuYao.TlsClient: An HTTP Client Library with TLS Fingerprint Simulation Features

LuYao.TlsClient

A .NET TLS client library based on bogdanfinn/tls-client, which calls a Go-compiled dynamic link library through native interop (P/Invoke), providing advanced TLS fingerprint simulation capabilities.

Project Overview

LuYao.TlsClient is a cross-platform .NET library that allows developers to utilize advanced TLS client features in .NET applications. This library encapsulates the functionalities of the tls-client Go library, enabling the simulation of various browser and client TLS fingerprints to bypass certain anti-scraping mechanisms based on TLS fingerprints.

Main Features

  • Multi-Browser TLS Fingerprint Simulation: Supports simulating different versions of various browsers such as Chrome, Firefox, Safari, and Opera.
  • Cross-Platform Support: Supports Windows (x86/x64), Linux (x64/ARM64), macOS (x64/ARM64), and Alpine Linux.
  • Multi .NET Version Compatibility: Supports .NET Framework 4.5/4.6.1, .NET Standard 2.0/2.1, .NET 6/7/8.
  • HttpClient Integration: Provides <span>TlsClientHttpMessageHandler</span>, which can be seamlessly integrated into the standard .NET HttpClient workflow.
  • Session Management: Supports cookie session management, custom proxies, redirect control, etc.
  • Flexible Configuration: Supports custom TLS configurations, HTTP header order, timeout settings, etc.

Usage

Installation

Install via NuGet package manager:

dotnet add package LuYao.TlsClient

Or add to your project file:

&lt;PackageReference Include="LuYao.TlsClient" Version="*" /&gt;

Basic Usage Example

1. Directly Using TlsClient

using LuYao.TlsClient;

// Create a TLS client instance
using var client = new TlsClient();

// Configure the client
client.TLSClientIdentifier = ClientIdentifiers.Chrome_124;  // Simulate Chrome 124
client.Proxy = "http://proxy.example.com:8080";             // Optional: Set proxy
client.FollowRedirect = true;                               // Automatically follow redirects
client.Timeout = TimeSpan.FromSeconds(30);                  // Set timeout

// Create request
var request = client.CreateRequest();
request.RequestUrl = "https://example.com";
request.RequestMethod = "GET";
request.Headers["User-Agent"] = "Mozilla/5.0...";

// Send request
var response = client.Request(request);

// Handle response
Console.WriteLine($"Status Code: {response.Status}");
Console.WriteLine($"Response Body: {response.Body}");

2. Using with HttpClient Integration

using System.Net.Http;
using LuYao.TlsClient;

// Create TLS client
var tlsClient = new TlsClient
{
    TLSClientIdentifier = ClientIdentifiers.Chrome_124,
    FollowRedirect = true,
    Timeout = TimeSpan.FromSeconds(30)
};

// Use TlsClientHttpMessageHandler to create HttpClient
using var httpClient = new HttpClient(new TlsClientHttpMessageHandler(tlsClient));

// Use like a normal HttpClient
var response = await httpClient.GetAsync("https://example.com");
var content = await response.Content.ReadAsStringAsync();

Console.WriteLine(content);

3. Cookie Session Management

using var client = new TlsClient();

// Add Cookies
var addCookiesInput = new AddCookiesToSessionInput
{
    SessionId = client.SessionId,
    Url = "https://example.com",
    Cookies = new List&lt;Cookie&gt;
    {
        new Cookie 
        { 
            Name = "session_id", 
            Value = "abc123",
            Domain = "example.com",
            Path = "/"
        }
    }
};
client.AddCookiesToSession(addCookiesInput);

// Get Cookies
var getCookiesInput = new GetCookiesFromSessionInput
{
    SessionId = client.SessionId,
    Url = "https://example.com"
};
var cookies = client.GetCookiesFromSession(getCookiesInput);

foreach (var cookie in cookies.Cookies)
{
    Console.WriteLine($"{cookie.Name}: {cookie.Value}");
}

Supported Browser Identifiers

The library provides various predefined browser TLS fingerprint identifiers (via the <span>ClientIdentifiers</span> class):

  • Chrome: Chrome_103 to Chrome_124
  • Firefox: Firefox_102 to Firefox_110
  • Safari: Safari_15_6_1, Safari_16_0, Safari_IOS_15_5/15_6/16_0, etc.
  • Opera: Opera_89 to Opera_91
  • Mobile Applications: Fingerprints for specific applications like Nike, Zalando, Mesh, Confirmed, etc.
  • Android OkHttp: Okhttp4_Android_7 to Okhttp4_Android_13

Software Architecture

Architecture Overview

┌─────────────────────────────────────┐
│    .NET Application                  │
│                                     │
│  ┌──────────────────────────────┐  │
│  │   HttpClient (Optional)      │  │
│  └──────────┬───────────────────┘  │
│             │                       │
│  ┌──────────▼───────────────────┐  │
│  │ TlsClientHttpMessageHandler  │  │
│  └──────────┬───────────────────┘  │
│             │                       │
│  ┌──────────▼───────────────────┐  │
│  │      TlsClient               │  │
│  │  - Session Management         │  │
│  │  - Configuration Options      │  │
│  │  - JSON Serialization         │  │
│  └──────────┬───────────────────┘  │
│             │                       │
│  ┌──────────▼───────────────────┐  │
│  │    NativeMethods             │  │
│  │  - P/Invoke Calls            │  │
│  │  - Memory Marshaling         │  │
│  └──────────┬───────────────────┘  │
└─────────────┼───────────────────────┘
              │ P/Invoke / FFI
┌─────────────▼───────────────────────┐
│   Native Dynamic Link Library       │
│   tls-client.dll / libtls-client.so │
│                                     │
│  - TLS Handshake Processing        │
│  - Browser Fingerprint Simulation   │
│  - HTTP/HTTPS Request Handling     │
└─────────────────────────────────────┘

Core Component Descriptions

1. TlsClient Class

  • Responsibilities: Main client class managing TLS sessions and requests.
  • Functions:
    • Session lifecycle management
    • Request configuration and execution
    • Cookie management
    • JSON serialization/deserialization

2. TlsClientHttpMessageHandler Class

  • Responsibilities: Implementation of HttpMessageHandler for integration with standard HttpClient.
  • Functions:
    • Convert HttpRequestMessage to RequestInput
    • Convert Response to HttpResponseMessage
    • Support for streaming output and temporary file handling

3. NativeMethods Class

  • Responsibilities: P/Invoke declarations to call the native Go library.
  • Methods:
    • <span>Request</span>: Send HTTP/HTTPS requests
    • <span>DestroySession</span>: Destroy a specified session
    • <span>DestroyAll</span>: Destroy all sessions
    • <span>GetCookiesFromSession</span>: Get session cookies
    • <span>AddCookiesToSession</span>: Add cookies to session
    • <span>FreeMemory</span>: Free native memory

4. Types Class

  • Responsibilities: Define data types for interaction with the Go library.
  • Main Types:
    • <span>RequestInput</span>: Request parameters
    • <span>Response</span>: Response data
    • <span>Cookie</span>: Cookie information
    • <span>CustomTlsClient</span>: Custom TLS configuration
    • <span>TransportOptions</span>: Transport options

5. ClientIdentifiers Class

  • Responsibilities: Provide predefined browser TLS fingerprint identifiers.
  • Includes: 50+ different browser and application TLS fingerprints.

Platform Support

The library supports multiple platforms through Runtime Identifiers (RID):

Platform Architecture RID Native Library Format
Windows x86 win-x86 tls-client.dll
Windows x64 win-x64 tls-client.dll
Linux x64 linux-x64 libtls-client.so
Linux ARM64 linux-arm64 libtls-client.so
Alpine Linux x64 alpine-x64 libtls-client.so
macOS x64 osx-x64 libtls-client.dylib
macOS ARM64 osx-arm64 libtls-client.dylib

Dependency Components

NuGet Package Dependencies

Runtime Dependencies

  • Newtonsoft.Json (v13.0.3)
    • Purpose: JSON serialization and deserialization
    • License: MIT

.NET Framework Specific Dependencies

  • System.Net.Http (only .NET Framework 4.5 and 4.6.1)
    • Purpose: HTTP client functionality
    • Source: Built-in .NET Framework

Native Library Dependencies

  • tls-client (Go-compiled dynamic link library, v1.9.1)
    • Source: bogdanfinn/tls-client
    • Purpose: Provides core TLS client functionality
    • License: BSD 3-Clause

Target Framework

The library supports the following .NET target frameworks:

  • .NET Framework 4.5
  • .NET Framework 4.6.1
  • .NET Standard 2.0
  • .NET Standard 2.1
  • .NET 6.0
  • .NET 7.0
  • .NET 8.0

Build Tool Dependencies

  • Nuke.Common: Build automation framework
  • GitVersion: Version management
  • .NET SDK: For compilation and building

Configuration Options

Main Properties of TlsClient

Property Type Default Value Description
<span>SessionId</span> string GUID Unique session identifier
<span>TLSClientIdentifier</span> string Chrome_124 TLS fingerprint identifier
<span>Proxy</span> string null Proxy server address
<span>FollowRedirect</span> bool false Whether to automatically follow redirects
<span>InsecureSkipVerify</span> bool false Whether to skip SSL certificate verification
<span>DisableIPV6</span> bool false Whether to disable IPv6
<span>DisableIPV4</span> bool false Whether to disable IPv4
<span>LocalAddress</span> string null Local binding address
<span>StreamOutput</span> bool false Whether to use streaming output
<span>Timeout</span> TimeSpan 0 (unlimited) Request timeout duration
<span>WithDebug</span> bool false Whether to enable debug mode
<span>ForceHttp1</span> bool false Whether to force the use of HTTP/1.1

Advanced Options for RequestInput

  • CertificatePinning: Certificate pinning configuration
  • CustomTlsClient: Custom TLS client configuration
  • TransportOptions: Transport layer options (dial timeout, idle connection timeout, etc.)
  • HeaderOrder: Custom HTTP header order
  • ProxyRotation: Proxy rotation configuration

Project Structure

luyao-tls-client/
├── src/
│   └── LuYao.TlsClient/           # Main project source code
│       ├── TlsClient.cs           # Core client class
│       ├── TlsClientHttpMessageHandler.cs  # HttpClient integration
│       ├── NativeMethods.cs       # P/Invoke declarations
│       ├── Types.cs               # Data type definitions
│       ├── ClientIdentifiers.cs   # Browser identifiers
│       ├── CStringMarshaler.cs    # C string marshaler
│       └── ...
├── build/                         # Build scripts and configurations
│   ├── Build.cs                   # Nuke build definitions
│   ├── Consts.cs                  # Constant definitions
│   └── ...
├── .github/
│   └── workflows/                 # GitHub Actions workflows
│       ├── continuous.yml         # Continuous integration
│       └── Publish_NuGet_Manual.yml  # NuGet publishing
├── LuYao.TlsClient.sln           # Visual Studio solution
└── README.md                      # This documentation

Building and Publishing

Local Build

# Windows
.uild.cmd Compile

# Linux/macOS
./build.sh Compile

Pack NuGet

# Windows
.uild.cmd Pack

# Linux/macOS
./build.sh Pack

Publish to NuGet

The project uses GitHub Actions for automated publishing, triggered manually through the <span>Publish_NuGet_Manual</span> workflow.

Notes

  1. Legal and Ethical Use: This library should only be used for legal purposes. Using this library to bypass website protections may violate terms of service or local laws.
  2. Native Library Dependencies: Ensure that the native dynamic link libraries for the target platform are available.
  3. Memory Management: The library implements <span>IDisposable</span>, and resources should be properly released after use.
  4. Thread Safety: Each <span>TlsClient</span> instance maintains an independent session, and it is recommended to use a separate instance for each thread.

License

This project is built on top of bogdanfinn/tls-client, please adhere to the corresponding open-source license.

Related Links

  • Source Code Repository
  • bogdanfinn/tls-client – Underlying Go TLS client library
  • NuGet Package

Contributions

Contributions through Issues and Pull Requests to improve this project are welcome.

Related posts

  1. Data Encryption Techniques in Python: Common Encryption Algorithms and Their Implementation
  2. Basic Functions in Rust
  3. aiohttp: Asynchronous HTTP Framework to Enhance Network Request Performance!
  4. Using HTTP Requests in iOS Shortcuts
  5. Understanding the Underlying Principles of Polymorphism in C++
  6. Understanding TCP/IP: The ‘Universal Language’ of the Internet
  7. What Is the http://router.ctc Telecom Router?
  8. Using Streamable HTTP for Real-Time AI Tool Interaction with MCP
  9. How Should Interface Testing Engineers Learn HTTP/HTTPS Protocols? (Part 19)
  10. OpenFeign: The Remote Messenger for Java HTTP Clients
  11. PHP GuzzleHTTP/Guzzle Package
  12. Chapter 8: W55MH32 HTTP Client Example
  13. How to Call a Web Service via HTTP
  14. In-Depth Analysis of Virtual Functions and Constructors/Destructors in C++
  15. Requests: An Elegant Python Library for Handling HTTP Requests!
  16. Wireshark Case Study (25): The ‘Multiplexing’ of HTTP/2
  17. Correct Handling of File Uploads in Python aiohttp
  18. Engineering Science Popularization: From HTTP to HTTPS – Building a Secure Network
  19. The Simplest and Most Formal Method for Simulating POST Forms (Multipart Form) in Qt HTTP GET and POST

Leave a Comment