DOCSEARCHbyAlgolia
Submit Docs

AzureTLS Client

repository·main·Indexed 19 days ago

https://github.com/noooste/azuretls-client

An HTTP client for Go designed to bypass bot detection by providing authentic browser fingerprints (TLS JA3/JA4 and HTTP/2). It supports browser emulation for Chrome, Firefox, Opera, Safari, Edge, and iOS, and includes a C FFI library for cross-language integration. Key features include fine-grained control over TLS/HTTP fingerprinting, proxy management, SSL pinning, and support for ordered headers.

Tokens
22.7K
Snippets
95
Records
110
Agent score
65%

What's inside azuretls-client

  1. Memory management rules for AzureTLS CFFI

    main

    Because this is a C FFI, manual memory management is critical to prevent leaks. The library follows a strict ownership model where the caller is responsible for freeing memory allocated by the library.

    Cleanup Checklist

    1. Responses: Call azuretls_free_response(resp) for every CFfiResponse* returned by azuretls_session_do.
    2. Strings: Call azuretls_free_string(str) for any char* returned by utility functions (like azuretls_version or error messages from fingerprinting/proxy functions).
    3. Sessions: Call azuretls_session_close(session_id) to close a session.
    4. Library: Call azuretls_cleanup() once at the very end of your program execution.
    5. Initialization: Call azuretls_init() once at the start of your program.
    // Example of a memory-safe pattern
CFfiResponse* response = azuretls_session_do(session, request);
if (response) {
    // Use response...
    azuretls_free_response(response);
}

char* error = azuretls_session_apply_ja3(session, ja3, navigator);
if (error) {
    printf("Error: %s\n", error);
    azuretls_free_string(error);
}

  2. Handle errors in AzureTLS CFFI

    main

    When using the CFFI, errors manifest in three distinct ways depending on the operation:

    1. Function Errors: Many functions return NULL or 0 to indicate failure (e.g., azuretls_session_new returning 0).
    2. String Errors: Functions that return an error message string require you to check if the pointer is non-NULL. If an error is returned, you must free the string using azuretls_free_string to avoid memory leaks.
    3. Response Errors: For successful function calls that perform network operations, check the error field within the CFfiResponse object. If response->error is non-NULL, the request failed.

    Always free response objects using azuretls_free_response once processing is complete.

    // Check session creation
uintptr_t session = azuretls_session_new(config);
if (session == 0) {
    printf("Failed to create session\n");
    return -1;
}

// Check response
CFfiResponse* response = azuretls_session_do(session, request);
if (!response) {
    printf("Request failed\n");
    return -1;
}

if (response->error) {
    printf("Request error: %s\n", response->error);
    azuretls_free_response(response);
    return -1;
}

// Success case
printf("Status: %d\n", response->status_code);
azuretls_free_response(response);

  4. Quick Start with AzureTLS Client

    main

    To get started, create a new session using azuretls.NewSession(). By default, each session automatically mimics a Chrome browser (including TLS JA3 and HTTP/2 fingerprints), making it look like a real browser to servers without any additional configuration. Remember to call session.Close() to clean up resources.

    package main

import (
    "fmt"
    "log"
    "github.com/Noooste/azuretls-client"
)

func main() {
    session := azuretls.NewSession()
    defer session.Close()

    response, err := session.Get("https://api.github.com")
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Status: %d\n", response.StatusCode)
    fmt.Println(response.String())
}

  6. Create and manage an AzureTLS session

    main

    To use the client, you must first create a session. You can create a session without a context using azuretls.NewSession() or with a context using azuretls.NewSessionWithContext(ctx).

    Important: Always call session.Close() (typically via defer) to free up resources when the session is no longer needed.

    // without context
session := azuretls.NewSession()
defer session.Close() 

// or with context
session := azuretls.NewSessionWithContext(context.Background())
defer session.Close()

  7. Build the AzureTLS CFFI library

    main

    To use the AzureTLS client via C FFI, you must first build the library for your target platform.

    Prerequisites

    • Go 1.24+ with CGO enabled
    • A C compiler (GCC, Clang, or MSVC)
    • Make (GNU Make or compatible)

    Build Commands

    Use make to compile the library. You can build for your current platform, all platforms, or specific OS/Architecture combinations.

    # Build for current platform
make

# Build for all platforms
make build-all

# Build for specific platform
make build-linux-amd64
make build-windows-amd64
make build-darwin-arm64

  8. Emulate predefined browsers and devices

    main

    The module provides predefined configurations for several browsers and devices. Assigning one of these to session.Browser will automatically set the corresponding JA3 and HTTP2 specifications.

    Supported values include:

    • azuretls.Chrome
    • azuretls.Firefox
    • azuretls.Opera
    • azuretls.Safari
    • azuretls.Edge
    • azuretls.Ios
    session := azuretls.NewSession()
defer session.Close() 

session.Browser = azuretls.Firefox // JA3 and HTTP2 specifications will be automatically set

  9. What is JA3 and how does it work?

    main

    JA3 is a method for creating fingerprints from SSL/TLS client hellos, used for client identification or detection.

    A fingerprint is constructed by concatenating specific handshake parameters into a string, which is then MD5-hashed to produce a 32-character representation.

    The string structure is: <SSL Version>|<Accepted Ciphers>|<List of Extensions>|<Elliptic Curves>|<Elliptic Curve Formats>

    In azuretls-client, applying a JA3 fingerprint involves parsing this string and mapping the values to a tls.ClientHelloSpec. If any required field in the client hello is absent in the JA3 string, an error is returned.

  10. How HTTP/3 discovery and Alt-Svc work

    main

    The azuretls client uses the Alt-Svc (Alternative Services) HTTP header to discover HTTP/3 support for hosts.

    1. When a response contains an Alt-Svc header containing h3 or h3- versions, the client caches this host in its altSvcCache.
    2. Subsequent requests to that host will automatically attempt to use the HTTP3Transport.
    3. If ForceHTTP3 is enabled in the HTTP3Config, the client will attempt HTTP/3 for all requests regardless of Alt-Svc discovery.

  11. Handle redirect policies with CheckRedirect

    main

    The Session.CheckRedirect function allows you to define custom logic for following HTTP redirects.

    • If CheckRedirect is nil, the session defaults to stopping after 10 consecutive requests.
    • If it returns an error, the Get method returns the previous Response (with its body closed) and the error.
    • Special Case: If you return azuretls.ErrUseLastResponse, the client will return the most recent response with a nil error, effectively treating the redirect as the final destination.
    session.CheckRedirect = func(req *azuretls.Request, reqs []*azuretls.Request) error {
    if len(reqs) >= 3 {
        // Stop after 3 redirects
        return errors.New("too many redirects")
    }
    // Or return azuretls.ErrUseLastResponse to stop and return the current response
    return nil
}

  12. Browser Fingerprint Profiles (ClientHelloSpec)

    main

    The library provides pre-configured *tls.ClientHelloSpec objects that emulate the TLS fingerprints of major browsers and operating systems. These profiles include specific cipher suites, extensions, and GREASE values to match real-world browser behavior.

    Available profiles via direct functions:

    • GetLastChromeVersion(): Latest Chrome (v133) profile.
    • GetLastFirefoxVersion(): Latest Firefox (v138) profile.
    • GetLastIosVersion(): iOS profile.
    • GetLastSafariVersion(): Safari profile.
    • GetLastChromeVersionForHTTP3(): Chrome profile specifically for HTTP/3 (QUIC) connections.