Skip to content

Implement group-level uTLS fingerprint selection#443

Open
akellavk wants to merge 1 commit into
ExclaveNetwork:devfrom
akellavk:dev
Open

Implement group-level uTLS fingerprint selection#443
akellavk wants to merge 1 commit into
ExclaveNetwork:devfrom
akellavk:dev

Conversation

@akellavk

@akellavk akellavk commented Jul 7, 2026

Copy link
Copy Markdown

Summary

Adds ability to set a group-level uTLS fingerprint that overrides individual profile configurations. This feature allows centralized uTLS management for all profiles within a group.

Changes

1. Database (ProxyGroup.kt)

  • Added groupUtlsFingerprint: String field to ProxyGroup data class
  • Updated serialization/deserialization to persist the value

2. UI (group_preferences.xml, GroupSettingsActivity.kt)

  • Added ListPreference for uTLS fingerprint selection in group settings
  • Uses existing utls_entry and utls_value arrays from arrays.xml
  • Added GROUP_UTLS_FINGERPRINT constant to Constants.kt
  • Added groupUtlsFingerprint variable to DataStore.kt
  • Updated init() and serialize() methods in GroupSettingsActivity
  • Setting name: "Force uTLS" (EN), "Принудительный uTLS" (RU)
  • Added summary display showing currently selected value

3. Logic (ConfigBuilder.kt)

  • In buildChain() function, added group retrieval for each profile
  • Applied group uTLS fingerprint in 5 locations:
    • StandardV2RayBean with TLS (2 locations)
    • StandardV2RayBean with Reality (2 locations)
    • TrustTunnelBean with HTTPS (1 location)

Priority Logic

When building configuration, fingerprint is selected in this order:

  1. Experimental override from settings (overrideUTLSFingerprintForREALITY/TLS)
  2. Group uTLS fingerprint (if set in group settings)
  3. Profile-specific fingerprint (bean.realityFingerprint or bean.utlsFingerprint)

Benefits

  • Centralized uTLS management for all profiles in a group
  • Especially useful for circumventing blocks
  • No need to manually edit each profile's uTLS settings
  • Easy to test different fingerprints across multiple profiles

…le config values

Changes made:

1. Database field addition (ProxyGroup.kt):
- Added groupUtlsFingerprint: String field to ProxyGroup data class
- Updated serialization/deserialization to persist the value

2. UI implementation (group_preferences.xml, GroupSettingsActivity.kt):
- Added ListPreference for uTLS fingerprint selection in group settings
- Uses existing utls_entry and utls_value arrays from arrays.xml
- Added GROUP_UTLS_FINGERPRINT constant to Constants.kt
- Added groupUtlsFingerprint variable to DataStore.kt
- Updated init() and serialize() methods in GroupSettingsActivity to handle the new field
- Named setting: "Force uTLS" (EN), "Принудительный uTLS" (RU)
- Added summary display showing currently selected value

3. Application logic (ConfigBuilder.kt):
- In buildChain() function, added group retrieval for each profile
- Group uTLS is applied with priority: experimental override → group uTLS → profile uTLS
- Updated all five locations where uTLS fingerprint is applied:
- For StandardV2RayBean with TLS (2 locations)
- For StandardV2RayBean with Reality (2 locations)
- For TrustTunnelBean with HTTPS (1 location)

Priority logic:

When building configuration, the system checks in the following order:
1. Experimental override from settings (overrideUTLSFingerprintForREALITY/TLS)
2. Group uTLS fingerprint (groupUtlsFingerprint - if set in group settings)
3. Profile-specific fingerprint (bean.realityFingerprint or bean.utlsFingerprint)

This allows centralized uTLS management for all profiles in a group, which is especially useful for circumventing blocks.
@xchacha20-poly1305

Copy link
Copy Markdown

What is the expected/correct a balancer or a proxy chain includes a config outside of the main group?

@akellavk

akellavk commented Jul 7, 2026

Copy link
Copy Markdown
Author

What is the expected/correct a balancer or a proxy chain includes a config outside of the main group?

It is expected that the original fingerprint from the group's profile will be used.

@dyhkwong

dyhkwong commented Jul 8, 2026

Copy link
Copy Markdown
Collaborator

uTLS is a temporary workaround for some special scenarios and is not a long-term solution. It lacks maintenance and mimic failure always occur. I don't see why so many people rely on it. uTLS should be treated as deprecated.

@akellavk

akellavk commented Jul 8, 2026

Copy link
Copy Markdown
Author

In Russia, VLESS + Reality is widely deployed. Some fingerprints (particularly Chrome) have been identified and are now being throttled by DPI systems. When a VPN provider provisions most of their servers with Chrome
fingerprints, and traffic shaping begins targeting that specific fingerprint, users need a way to switch fingerprints across multiple profiles without reconfiguring each one individually.

This PR addresses that exact use case: centralized fingerprint rotation at the group level. While uTLS may be a temporary solution architecturally, it remains actively functional today and serves a critical need for users
facing targeted throttling.

As long as uTLS works and provides value for circumvention, group-level fingerprint management is a practical feature, not technical debt.

@dyhkwong

dyhkwong commented Jul 8, 2026

Copy link
Copy Markdown
Collaborator

What if we replace the uTLS REALITY implementation with our own Go crypto/tls based implementation (or at least make it the default one)? If a TLS implementation is outdated and always problematic, we should not make the app tightly couple to it.

@akellavk

akellavk commented Jul 8, 2026

Copy link
Copy Markdown
Author

I agree that uTLS isn't a great long-term solution, and your idea of replacing it with a custom crypto/tls-based generator makes sense architecturally.

That said, the throttling issues are happening right now, and users need a way to rotate fingerprints at the group level without manually touching each server. This PR is about that management layer — it doesn't care which TLS implementation sits underneath.

My suggestion:

· Merge this PR now as a pragmatic fix for current user pain.
· When your new generator is ready, we can swap the underlying implementation behind the same fingerprint interface — minimal changes on my side.
· Once your solution proves stable and covers all cases, we can deprecate or simplify my group management logic entirely.

So this PR doesn't create debt — it buys users a solution today while keeping the door wide open for your future refactor. No breaking changes, no lock-in.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants