TLS
TLS settings belong to each proxy, in a tls inline table:
[[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
| Protocol | TLS |
|---|---|
trojan, anytls, hysteria2, tuic | always on. Without a tls table they use TLS with default settings; enabled = false is ignored with a warning |
http, socks5, vmess, vless | on when the proxy has a tls table, off without one |
ss | not 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
| Key | Aliases | Default | Value |
|---|---|---|---|
enabled | enable | true | false turns TLS off for http, socks5, vmess, vless. With false, no other TLS key may be set |
server-name | sni, server_name | the proxy's server | name sent as SNI and checked against the certificate |
alpn | — | none | string or array of strings. Only vmess, vless, trojan, tuic; see ALPN |
skip-cert-verify | insecure, skip_cert_verify | false | true accepts any certificate. For tests only |
certificate | — | none | PEM text, or an array of lines joined with newlines: the CA certificates to trust |
certificate-path | certificate_path | none | path to a PEM file with the CA certificates to trust |
reality | — | none | inline 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'sserveras 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-namewhen the certificate is issued for a name other thanserver, for example whenserveris 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.
[[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-pathis used andcertificateis ignored. certificate-pathmust name an existing file when the profile loads, or the profile is rejected withtls.certificate-path file does not exist; tried .... A relative path is looked up in this order: the profile's directory, the data directory, thenresourcesnext 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 inresources.skip-cert-verify = trueturns 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.
| Protocol | Without alpn |
|---|---|
trojan | offers h2 and http/1.1 |
tuic | offers nothing. Most servers expect alpn = ["h3"] |
vmess, vless | nothing over raw; http/1.1 with the ws, http and httpupgrade transports; h2 with grpc |
hysteria2 | always 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.
[[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" } }| Key | Aliases | Default | Value |
|---|---|---|---|
enabled | enable | false | must be true to use Reality |
public-key | public_key | none | the server's public key; required when enabled = true |
short-id | short_id | none | one short ID, as a string or a one-element array |
Rules the profile is checked against:
- Unlike
tls, therealitytable does not turn itself on.public-keyorshort-idwithoutenabled = trueis rejected withReality fields require reality.enabled=true. enabled = truewithoutpublic-keyis rejected.- More than one
short-idis rejected: the client sends one. - Reality needs TLS on:
tls.enabled = falsetogether with Reality is rejected. - Reality on another protocol is rejected with
Reality is not supported by this protocol. server-nameis the site the server imitates, as configured on the server.- With VLESS, Reality works over the
rawandgrpctransports only. With another transport the profile loads but connections fail. private-key,handshakeandmax-time-differenceare 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
- Certificate verify failed: the certificate is not issued for
server-name, or it is signed by a CA the system does not trust. Setserver-name, or give the CA incertificate/certificate-path. - It works only with
skip-cert-verify: the same causes. Remember thatcertificatereplaces the system roots, so a public certificate fails when you also set a private CA. alpnrejected: the protocol does not take ALPN; remove it.- Reality rejected: add
enabled = trueandpublic-key, keep oneshort-id. - TUIC handshake fails: add
alpn = ["h3"].
See also Proxies and Transports.
