Skip to content

Latest commit

 

History

History
149 lines (106 loc) · 5.32 KB

README.md

File metadata and controls

149 lines (106 loc) · 5.32 KB
Raw

Craftls is a fork of the Rustls library with customizable ClientHello fingerprint.

Status

Craftls is under active development. We aim to maintain reasonable API surface stability but the API may evolve as we make changes to accommodate new features or performance improvements.

Changelog

The detailed list of changes in each release can be found at https://github.com/3andne/craftls/releases.

Documentation

https://docs.rs/craftls/

Approach

Craftls is a TLS library that aims to be a drop-in replacement of Rustls, offering customizable ClientHello while maintaining robust security and ease of use.

Current functionality (with default crate features)

  • Capabilities inherited from Rustls
  • Customization options for ClientHello extensions
  • Customization options for ClientHello cipher suites.
  • Support for client-side Certificate Compression using zlib, zstd, and brotli compression methods (rfc8879).
  • ClientHello padding extension (rfc7685).
  • Grease extension (rfc8701)
  • TLS ClientHello extension permutation (chrome)
  • Predefined browser fingerprints
    • CHROME_108
    • CHROME_112
    • SAFARI_17_1
    • FIREFOX_105

Non-features

We will not be supporting any non-features listed in Rustls README, including deprecated TLS versions and outdated cipher suites.

While these non-features may be included in browser fingerprints for completeness, any server attempt to use them will result in the termination of the connection. Most modern and secure servers do not utilize these outdated options, so this measure should not impact regular use.

Example code

See examples/src/bin/craftclient.rs

Configuration

Direct Usage

To use craftls directly, just add craftls in your Cargo.toml.

As a rustls Replacement

If you wish to replace rustls with craftls in nested dependencies (dependencies of dependencies), you can use the [patch.crates-io] section in your Cargo.toml:

[patch.crates-io]
rustls = { git = 'https://github.com/3andne/craftls.git', tag = "your version" }

Make sure to substitute "your version" with the specific version tag of craftls you intend to use. This patch will ensure that craftls is used in place of rustls throughout your project, including within libraries like tokio-rustls.

Usage

Craftls is designed to be a drop-in replacement for Rustls with an additional feature for specifying TLS fingerprints. Below is a guide on how to configure the ClientConfig in Craftls to use a specific fingerprint.

let mut config: rustls::ClientConfig = rustls::ClientConfig::builder()
    .with_root_certificates(root_store)
    .with_no_client_auth()
    .with_fingerprint( // Specifies the fingerprint we want to use, i.e., CHROME v108
        rustls::craft::CHROME_108
            .builder(),
    );

After setting up the ClientConfig with the preferred fingerprint, you can proceed as you would with Rustls. The rest of the API remains consistent with the Rustls library.

Use with http clients

Http clients such as hyper internally manage ALPN settings. They may raise issues if ALPN is set externally. Use the following configuration to avoid the panic:

let mut config: rustls::ClientConfig = rustls::ClientConfig::builder()
    .with_root_certificates(root_store)
    .with_no_client_auth()
    .with_fingerprint(
        rustls::craft::CHROME_108
            .builder()
            .do_not_override_alpn(), // let the http client manage the alpn
    );

Use with http/1.1 or non-http clients

Warning: browsers are h2 clients. Http1.1 and non-http variations deviate from browsers standard browser behaviors and should be used carefully.

let mut config: rustls::ClientConfig = rustls::ClientConfig::builder()
    .with_root_certificates(root_store)
    .with_no_client_auth()
    .with_fingerprint(
        rustls::craft::CHROME_108
            .test_alpn_http1 // alpn: ["http/1.1"]
            .builder(),
    );

Or

let mut config: rustls::ClientConfig = rustls::ClientConfig::builder()
    .with_root_certificates(root_store)
    .with_no_client_auth()
    .with_fingerprint(
        rustls::craft::CHROME_108
            .test_no_alpn // no alpn extension
            .builder(),
    );

License

Craftls is distributed under the following three licenses:

  • Apache License version 2.0.
  • MIT license.
  • ISC license.

These are included as LICENSE-APACHE, LICENSE-MIT and LICENSE-ISC respectively. You may use this software under the terms of any of these licenses, at your option.

Code of conduct

This project adopts the Rust Code of Conduct. Please email [email protected] to report any instance of misconduct, or if you have any comments or questions on the Code of Conduct.

Icons by icons8