Skip to content

_tls.md

Latest commit

 

History

History
211 lines (200 loc) · 12.2 KB

_tls.md

File metadata and controls

211 lines (200 loc) · 12.2 KB
Raw

tls

A shared registry sub-schema (contract/registry/tls.json): its fields are substituted into the body of every scheme that refers to it.

← index · diagnosed problems

Core the schema was checked against: 1.14.2-lx.11

The whole block is dropped entirely and silently when enabled is false — that is how the core reads it ("not configured", not "configured and switched off"). The block is then absent for every presence check, including its own nested blocks.

Link parameters

These are repeated on the page of every scheme that carries a TLS block, together with the rule of the body field each one maps to.

  • security — Whether the link asks for TLS, and in which flavour.
    • Type: enum: "", none, tls, reality · Default: ""
    • Maps to: tls.enabled
  • sni — Server name sent in SNI.
    • Also spelled: peer
    • Type: string · Default: ""
    • Maps to: tls.server_name
  • alpn — Comma-separated list of ALPN protocols.
    • Type: string · Default: ""
    • Maps to: tls.alpn
  • insecure — Skip server certificate verification.
    • Also spelled: allowInsecure, allowinsecure, allow_insecure, allow-insecure, skipCertVerify, skipcertverify, skip_cert_verify, skip-cert-verify, noverify
    • Type: bool · Default: false
    • Maps to: tls.insecure
  • fp — Browser fingerprint mimicked in the ClientHello.
    • Also spelled: fingerprint
    • Type: enum (other spellings of the same value are accepted): chrome, chrome_psk, chrome_psk_shuffle, chrome_padding_psk_shuffle, chrome_pq, chrome_pq_psk, firefox, edge, safari, 360, qq, ios, android, random, randomized (allowlist utls_fingerprints) · Default: ""
    • Maps to: tls.utls.fingerprint
  • ech — Encrypted Client Hello parameters in the Xray form.
    • Also spelled: echfq
    • Type: string · Default: ""
    • Maps to: nothing — the parameter is read and then deliberately dropped
  • pbk — Server REALITY public key.
    • Type: string — X25519 public key: base64url or base64std, padded or not, decoding to exactly 32 bytes; anything else is not a valid key
    • Maps to: tls.reality.public_key
  • sid — REALITY short ID.
    • Type: string — hex only, lowercase, even length and at most 16 characters; an empty short_id is legal (a zero [8]byte)
    • Maps to: tls.reality.short_id
  • key_share — Key exchange used in the REALITY ClientHello.
    • Type: enum: "", hybrid, classical — a closed core enum, hybrid or classical; trimmed and lower-cased; an empty string means the key is absent, not invalid · Default: ""
    • Maps to: tls.reality.key_share

Body fields

  • enabled — Enable TLS for this outbound.
    • Type: bool
    • Default: false
  • engine — TLS implementation used for the handshake.
    • Type: enum, "", go, apple, windows, normalized: trim_lower
    • Default: go
    • If invalid: removed → type_invalid
    • Not supported by: naive
  • disable_sni — Do not send the SNI extension.
    • Type: bool
    • Default: false
    • Not supported by: naive
    • Conflicts with: tls.reality.enabled
  • server_name — Server name sent in SNI and verified in the certificate.
    • Type: string, format host
    • If invalid: removed → type_invalid
  • insecure — Skip server certificate verification.
    • Type: bool
    • Default: false
    • Accepted with a notice for true → tls_insecure
    • Not supported by: naive
  • alpn — ALPN protocols offered in the handshake.
    • Type: listable_string, normalized: trim
    • Not supported by: naive, masque
  • min_version — Minimum accepted TLS version.
    • Type: enum, 1.0, 1.1, 1.2, 1.3
    • If invalid: removed → type_invalid
    • Not supported by: naive
  • max_version — Maximum accepted TLS version.
    • Type: enum, 1.0, 1.1, 1.2, 1.3
    • If invalid: removed → type_invalid
    • Not supported by: naive
  • cipher_suites — Allowed TLS cipher suites.
    • Type: listable_string
    • Not supported by: naive
  • curve_preferences — Preferred elliptic curves / key exchange groups.
    • Type: listable_string, P256, P384, P521, X25519, X25519MLKEM768
    • If invalid: removed → type_invalid
    • Not supported by: naive
  • certificate — Trusted server certificate in PEM form.
    • Type: listable_string
  • certificate_path — Path to a file with the trusted certificate.
    • Type: string
  • certificate_public_key_sha256 — Pinned SHA-256 hashes of the server public key.
    • Type: string_array, format base64
    • If invalid: removed → type_invalid
    • Not supported by: naive
    • Conflicts with: tls.certificate
    • Conflicts with: tls.certificate_path
  • client_certificate — Client certificate for mTLS, PEM form.
    • Type: listable_string
    • Not supported by: naive
    • Meaningless without: tls.client_key
  • client_certificate_path — Path to the client certificate file.
    • Type: string
    • Not supported by: naive
  • client_key — Client private key for mTLS, PEM form.
    • Type: listable_string, secret
    • Not supported by: naive
    • Meaningless without: tls.client_certificate
  • client_key_path — Path to the client private key file.
    • Type: string, secret
    • Not supported by: naive
  • fragment — Split the ClientHello across TCP segments.
    • Type: bool
    • Default: false
    • Not supported by: naive
    • Conflicts with: vhttp when vhttp is h3
    • Conflicts with: tls.engine when tls.engine is one of apple, windows
    • Conflicts with: detour
  • fragment_fallback_delay — Delay before falling back when fragmenting.
    • Type: duration
    • Not supported by: naive
  • record_fragment — Split the ClientHello across TLS records.
    • Type: bool
    • Default: false
    • Not supported by: naive
    • Conflicts with: vhttp when vhttp is h3
    • Conflicts with: tls.engine when tls.engine is one of apple, windows
  • spoof — Domain used for the spoofed ClientHello.
    • Type: string, format host
    • If invalid: removed → type_invalid
    • Not supported by: naive
    • Conflicts with: tls.reality.enabled
    • Conflicts with: tls.disable_sni
  • spoof_method — How the spoofed packet is made invalid.
    • Type: enum, "", wrong-sequence, wrong-checksum, wrong-ack, wrong-md5, wrong-timestamp, normalized: trim_lower
    • Default: wrong-sequence
    • If invalid: removed → type_invalid
    • Not supported by: naive
    • Meaningless without: tls.spoof
  • kernel_tx — Offload TLS transmission to the kernel (kTLS).
    • Type: bool
    • Default: false
    • Not supported by: naive, masque
    • Only written when: OS linux
  • kernel_rx — Offload TLS reception to the kernel (kTLS).
    • Type: bool
    • Default: false
    • Not supported by: naive, masque
    • Only written when: OS linux
  • handshake_timeout — Timeout for the TLS handshake.
    • Type: duration
    • Not supported by: naive
  • ech — Encrypted Client Hello settings.
    • Type: object, dropped entirely and silently when enabled is false (the object then counts as "not set" for every presence check)
    • Not supported by: masque
  • ech.enabled — Enable Encrypted Client Hello.
    • Type: bool
    • Default: false
    • Conflicts with: tls.reality.enabled
  • ech.config — Inline ECH config (PEM block).
    • Type: listable_string
  • ech.config_path — Path to a file with the ECH config.
    • Type: string
  • ech.query_server_name — Domain queried over DNS for the ECH config.
    • Type: string
  • ech.pq_signature_schemes_enabled — Deprecated post-quantum signature switch.
    • Type: bool, deprecated
  • ech.dynamic_record_sizing_disabled — Deprecated dynamic record sizing switch.
    • Type: bool, deprecated
  • utls — uTLS fingerprint settings.
    • Type: object, dropped entirely and silently when enabled is false (the object then counts as "not set" for every presence check)
    • Not supported by: naive, hysteria, hysteria2, tuic, masque
  • utls.enabled — Enable uTLS ClientHello mimicry.
    • Type: bool
    • Default: false
    • Not supported by: naive
  • utls.fingerprint — Browser fingerprint used for the ClientHello.
    • Type: enum, "", chrome, chrome_psk, chrome_psk_shuffle, chrome_padding_psk_shuffle, chrome_pq, chrome_pq_psk, firefox, edge, safari, 360, qq, ios, android, random, randomized, normalized: trim_lower
    • Default: chrome
    • If invalid: replaced with chrome → utls_fp_unknown
    • Accepted with a notice for anything except chrome, chrome_psk, chrome_psk_shuffle, chrome_padding_psk_shuffle, chrome_pq, chrome_pq_psk, firefox, safari, random, when tls.reality.enabled is set → reality_fp_not_chrome
    • Replaced: random → chrome when tls.reality.enabled is true → reality_fp_random_pinned
  • reality — REALITY settings.
    • Type: object, dropped entirely and silently when enabled is false (the object then counts as "not set" for every presence check)
    • Not supported by: naive, hysteria, hysteria2, tuic, masque
  • reality.enabled — Enable REALITY handshake camouflage.
    • Type: bool
    • Default: false
    • Not supported by: naive
    • Conflicts with: tls.ech.enabled
    • Conflicts with: tls.disable_sni
    • Conflicts with: tls.spoof
    • Requires: tls.utls.enabled — if missing, filled in with true
  • reality.public_key — Server REALITY public key (x25519).
    • Type: string, format base64_32, normalized: base64_rawurl
    • Required: the node is dropped without it
    • If invalid: removed → reality_pbk_invalid
  • reality.short_id — REALITY short ID (hex, even length).
  • reality.key_share — Key exchange used in the REALITY ClientHello.
    • Type: enum, "", hybrid, classical, normalized: trim_lower
    • Default: ""
    • If invalid: removed → reality_key_share_invalid
    • Meaningless without: tls.reality.public_key
    • Only written when: core ≥ 1.14.1-lx.4, lx fork only