Skip to content

TLS ​

TLS settings belong to each proxy, in a tls inline table:

toml
[[proxy]]
name = "office-tls"
type = "http"
server = "proxy.example.org"
port = 8443
tls = { server-name = "proxy.example.org" }

Write the table on one line. A [proxy.tls] header is rejected with tls must be an inline table.

When TLS is on ​

ProtocolTLS
trojan, anytls, hysteria2, tuicalways on. Without a tls table they use TLS with default settings; enabled = false is ignored with a warning
http, socks5, vmess, vlesson when the proxy has a tls table, off without one
ssnot allowed. Any TLS setting rejects the profile; only tls = { enabled = false } is tolerated

A tls table turns TLS on by itself: enabled defaults to true as soon as the table exists. tls = {} is valid and means "TLS with default settings".

Keys ​

KeyAliasesDefaultValue
enabledenabletruefalse turns TLS off for http, socks5, vmess, vless. With false, no other TLS key may be set
server-namesni, server_namethe proxy's servername sent as SNI and checked against the certificate
alpn—nonestring or array of strings. Only vmess, vless, trojan, tuic; see ALPN
skip-cert-verifyinsecure, skip_cert_verifyfalsetrue accepts any certificate. For tests only
certificate—nonePEM text, or an array of lines joined with newlines: the CA certificates to trust
certificate-pathcertificate_pathnonepath to a PEM file with the CA certificates to trust
reality—noneinline table, see Reality

When a key and its alias are both present, the first name in the table above wins (server-name over sni). Other keys inside tls are ignored without a warning, except the rejected keys.

Server name and certificate check ​

  • Without server-name, Specola sends the proxy's server as SNI and checks the certificate against it.
  • When the server name is an IP address, no SNI is sent and the certificate must be issued for that IP address.
  • Set server-name when the certificate is issued for a name other than server, for example when server is an IP address or a CDN address.

Trusted certificates ​

By default Specola trusts the operating system's root certificates. certificate and certificate-path replace them for that proxy: only the certificates you give are trusted.

toml
[[proxy]]
name = "lab-ca"
type = "trojan"
server = "proxy.example.org"
port = 443
password = "change-me"
tls = { server-name = "proxy.example.org", certificate = """
-----BEGIN CERTIFICATE-----
...your CA certificate...
-----END CERTIFICATE-----
""" }

That example is a fragment: replace the placeholder with a real PEM certificate.

  • When both are set, certificate-path is used and certificate is ignored.
  • certificate-path must name an existing file when the profile loads, or the profile is rejected with tls.certificate-path file does not exist; tried .... A relative path is looked up in this order: the profile's directory, the data directory, then resources next to the Specola executable. For an absolute path that does not exist, Specola also tries a file of the same name in the data directory and in resources.
  • skip-cert-verify = true turns every check off, including the name check. Anyone between you and the server can then read the traffic. Use it to confirm that a failure is a certificate problem, then fix the certificate instead.

The data directory is %LOCALAPPDATA%\Specola on Windows (%ProgramData%\Specola when Specola runs as a service), ~/Library/Application Support/com.specola.Specola on macOS and ~/.config/specola on Linux.

ALPN ​

alpn is accepted only for vmess, vless, trojan and tuic. On http, socks5, anytls and hysteria2 it rejects the profile.

ProtocolWithout alpn
trojanoffers h2 and http/1.1
tuicoffers nothing. Most servers expect alpn = ["h3"]
vmess, vlessnothing over raw; http/1.1 with the ws, http and httpupgrade transports; h2 with grpc
hysteria2always h3 (not configurable)

With a VMess or VLESS transport, a configured alpn must contain the protocol the transport needs (http/1.1, or h2 for gRPC). Otherwise the profile loads but every connection fails. See Transports.

Reality ​

Reality is an inline table inside tls. It works with vless, http and socks5.

toml
[[proxy]]
name = "vless-reality"
type = "vless"
server = "proxy.example.org"
port = 443
uuid = "b1479ae4-f64b-4b27-bdab-4fb0f4ecdba9"
flow = "xtls-rprx-vision"
tls = { server-name = "www.example.com", reality = { enabled = true, public-key = "public-key-from-your-server", short-id = "0123456789abcdef" } }
KeyAliasesDefaultValue
enabledenablefalsemust be true to use Reality
public-keypublic_keynonethe server's public key; required when enabled = true
short-idshort_idnoneone short ID, as a string or a one-element array

Rules the profile is checked against:

  • Unlike tls, the reality table does not turn itself on. public-key or short-id without enabled = true is rejected with Reality fields require reality.enabled=true.
  • enabled = true without public-key is rejected.
  • More than one short-id is rejected: the client sends one.
  • Reality needs TLS on: tls.enabled = false together with Reality is rejected.
  • Reality on another protocol is rejected with Reality is not supported by this protocol.
  • server-name is the site the server imitates, as configured on the server.
  • With VLESS, Reality works over the raw and grpc transports only. With another transport the profile loads but connections fail.
  • private-key, handshake and max-time-difference are server settings and are rejected.

Rejected keys ​

These keys are recognized but not supported. Setting any of them rejects the profile with TLS field '<key>' is not supported:

min-version, max-version, cipher-suites, curve-preferences, fingerprint, client-authentication, client-certificate, client-certificate-path, client-certificate-public-key-sha256, key, key-path, kernel-tx, kernel-rx, handshake-timeout, certificate-provider, acme, ech, reality.private-key, reality.handshake, reality.max-time-difference.

Their underscore spellings (min_version) are rejected too. Client certificates (mutual TLS) and TLS fingerprint imitation are therefore not available.

Legacy keys outside tls ​

sni, alpn, skip-cert-verify, certificate, certificate-path and fingerprint written directly in the proxy, outside tls, are ignored with a warning. Move them into the tls table. See Proxies.

Troubleshooting ​

  1. Certificate verify failed: the certificate is not issued for server-name, or it is signed by a CA the system does not trust. Set server-name, or give the CA in certificate / certificate-path.
  2. It works only with skip-cert-verify: the same causes. Remember that certificate replaces the system roots, so a public certificate fails when you also set a private CA.
  3. alpn rejected: the protocol does not take ALPN; remove it.
  4. Reality rejected: add enabled = true and public-key, keep one short-id.
  5. TUIC handshake fails: add alpn = ["h3"].

See also Proxies and Transports.