sing-box/docs/configuration/shared/tls.md

408 lines
8.5 KiB
Markdown
Raw Normal View History

### Inbound
2022-07-27 04:03:07 +00:00
```json
{
"enabled": true,
"server_name": "",
"alpn": [],
"min_version": "",
"max_version": "",
"cipher_suites": [],
2023-08-29 14:43:48 +00:00
"certificate": [],
2022-07-27 04:03:07 +00:00
"certificate_path": "",
2023-08-29 14:43:48 +00:00
"key": [],
"key_path": "",
"acme": {
"domain": [],
"data_directory": "",
"default_server_name": "",
"email": "",
"provider": "",
"disable_http_challenge": false,
"disable_tls_alpn_challenge": false,
"alternative_http_port": 0,
2022-08-24 09:04:15 +00:00
"alternative_tls_port": 0,
"external_account": {
"key_id": "",
"mac_key": ""
},
"dns01_challenge": {}
},
2023-08-29 14:43:48 +00:00
"ech": {
"enabled": false,
"pq_signature_schemes_enabled": false,
"dynamic_record_sizing_disabled": false,
"key": [],
"key_path": ""
},
"reality": {
"enabled": false,
"handshake": {
"server": "google.com",
"server_port": 443,
... // Dial Fields
},
"private_key": "UuMBgl7MXTPx9inmQp2UC7Jcnwc6XYbwDNebonM-FCc",
"short_id": [
"0123456789abcdef"
],
"max_time_difference": "1m"
}
2022-07-27 04:03:07 +00:00
}
```
### Outbound
2022-07-27 04:03:07 +00:00
```json
{
"enabled": true,
2022-08-26 10:36:49 +00:00
"disable_sni": false,
2022-07-27 04:03:07 +00:00
"server_name": "",
"insecure": false,
"alpn": [],
"min_version": "",
"max_version": "",
"cipher_suites": [],
"certificate": "",
2022-09-10 14:42:20 +00:00
"certificate_path": "",
"ech": {
"enabled": false,
"pq_signature_schemes_enabled": false,
"dynamic_record_sizing_disabled": false,
2023-08-29 14:43:48 +00:00
"config": [],
"config_path": ""
2022-09-10 14:42:20 +00:00
},
"utls": {
"enabled": false,
"fingerprint": ""
},
"reality": {
"enabled": false,
"public_key": "jNXHt1yRo0vDuchQlIP6Z0ZvjT3KtzVI-T4E7RoLJS0",
"short_id": "0123456789abcdef"
2022-09-10 14:42:20 +00:00
}
2022-07-27 04:03:07 +00:00
}
```
TLS version values:
* `1.0`
* `1.1`
* `1.2`
* `1.3`
Cipher suite values:
* `TLS_RSA_WITH_AES_128_CBC_SHA`
* `TLS_RSA_WITH_AES_256_CBC_SHA`
* `TLS_RSA_WITH_AES_128_GCM_SHA256`
* `TLS_RSA_WITH_AES_256_GCM_SHA384`
* `TLS_AES_128_GCM_SHA256`
* `TLS_AES_256_GCM_SHA384`
* `TLS_CHACHA20_POLY1305_SHA256`
* `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`
* `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`
* `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`
* `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`
* `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`
* `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`
* `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`
* `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`
* `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`
* `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`
!!! note ""
You can ignore the JSON Array [] tag when the content is only one item
2022-07-27 04:03:07 +00:00
### Fields
#### enabled
Enable TLS.
2022-07-27 04:03:07 +00:00
2022-08-26 10:36:49 +00:00
#### disable_sni
==Client only==
Do not send server name in ClientHello.
2022-07-27 04:03:07 +00:00
#### server_name
Used to verify the hostname on the returned certificates unless insecure is given.
It is also included in the client's handshake to support virtual hosting unless it is an IP address.
#### insecure
==Client only==
Accepts any server certificate.
#### alpn
List of supported application level protocols, in order of preference.
If both peers support ALPN, the selected protocol will be one from this list, and the connection will fail if there is
no mutually supported protocol.
See [Application-Layer Protocol Negotiation](https://en.wikipedia.org/wiki/Application-Layer_Protocol_Negotiation).
#### min_version
The minimum TLS version that is acceptable.
By default, TLS 1.2 is currently used as the minimum when acting as a
client, and TLS 1.0 when acting as a server.
2022-07-27 04:03:07 +00:00
#### max_version
The maximum TLS version that is acceptable.
By default, the maximum version is currently TLS 1.3.
2022-07-27 04:03:07 +00:00
#### cipher_suites
The elliptic curves that will be used in an ECDHE handshake, in preference order.
If empty, the default will be used. The client will use the first preference as the type for its key share in TLS 1.3.
This may change in the future.
#### certificate
2023-08-29 14:43:48 +00:00
The server certificate line array, in PEM format.
2022-07-27 04:03:07 +00:00
#### certificate_path
The path to the server certificate, in PEM format.
#### key
==Server only==
2023-08-29 14:43:48 +00:00
The server private key line array, in PEM format.
2022-07-27 04:03:07 +00:00
#### key_path
==Server only==
2022-07-30 14:00:04 +00:00
The path to the server private key, in PEM format.
## Custom TLS support
!!! info "QUIC support"
Only ECH is supported in QUIC.
2022-09-10 14:42:20 +00:00
#### utls
==Client only==
!!! warning ""
uTLS is not included by default, see [Installation](./#installation).
2022-09-10 14:42:20 +00:00
!!! note ""
uTLS is poorly maintained and the effect may be unproven, use at your own risk.
uTLS is a fork of "crypto/tls", which provides ClientHello fingerprinting resistance.
Available fingerprint values:
* chrome
* firefox
* edge
* safari
* 360
* qq
2022-09-10 14:42:20 +00:00
* ios
* android
* random
2023-02-28 13:10:11 +00:00
* randomized
2022-09-10 14:42:20 +00:00
Chrome fingerprint will be used if empty.
2022-09-10 14:42:20 +00:00
### ECH Fields
2023-08-29 14:43:48 +00:00
!!! warning ""
ECH is not included by default, see [Installation](./#installation).
2023-08-29 14:43:48 +00:00
ECH (Encrypted Client Hello) is a TLS extension that allows a client to encrypt the first part of its ClientHello
message.
2023-09-28 08:02:54 +00:00
The ECH key and configuration can be generated by `sing-box generate ech-keypair [--pq-signature-schemes-enabled]`.
2023-08-29 14:43:48 +00:00
#### pq_signature_schemes_enabled
Enable support for post-quantum peer certificate signature schemes.
It is recommended to match the parameters of `sing-box generate ech-keypair`.
#### dynamic_record_sizing_disabled
Disables adaptive sizing of TLS records.
When true, the largest possible TLS record size is always used.
When false, the size of TLS records may be adjusted in an attempt to improve latency.
#### key
==Server only==
ECH key line array, in PEM format.
#### key_path
==Server only==
The path to ECH key, in PEM format.
#### config
==Client only==
ECH configuration line array, in PEM format.
If empty, load from DNS will be attempted.
#### config_path
==Client only==
The path to ECH configuration, in PEM format.
If empty, load from DNS will be attempted.
### ACME Fields
2022-09-10 14:42:20 +00:00
!!! warning ""
ACME is not included by default, see [Installation](./#installation).
2022-09-10 14:42:20 +00:00
#### domain
List of domain.
ACME will be disabled if empty.
#### data_directory
The directory to store ACME data.
`$XDG_DATA_HOME/certmagic|$HOME/.local/share/certmagic` will be used if empty.
#### default_server_name
Server name to use when choosing a certificate if the ClientHello's ServerName field is empty.
#### email
The email address to use when creating or selecting an existing ACME server account
#### provider
The ACME CA provider to use.
| Value | Provider |
|-------------------------|---------------|
2022-08-23 15:15:56 +00:00
| `letsencrypt (default)` | Let's Encrypt |
| `zerossl` | ZeroSSL |
| `https://...` | Custom |
#### disable_http_challenge
Disable all HTTP challenges.
#### disable_tls_alpn_challenge
Disable all TLS-ALPN challenges
#### alternative_http_port
The alternate port to use for the ACME HTTP challenge; if non-empty, this port will be used instead of 80 to spin up a
listener for the HTTP challenge.
#### alternative_tls_port
The alternate port to use for the ACME TLS-ALPN challenge; the system must forward 443 to this port for challenge to
succeed.
2022-08-24 09:04:15 +00:00
#### external_account
EAB (External Account Binding) contains information necessary to bind or map an ACME account to some other account known
by the CA.
External account bindings are "used to associate an ACME account with an existing account in a non-ACME system, such as
a CA customer database.
To enable ACME account binding, the CA operating the ACME server needs to provide the ACME client with a MAC key and a
key identifier, using some mechanism outside of ACME. §7.3.4
#### external_account.key_id
The key identifier.
#### external_account.mac_key
2022-09-10 14:42:20 +00:00
The MAC key.
#### dns01_challenge
ACME DNS01 challenge field. If configured, other challenge methods will be disabled.
2023-12-14 14:23:52 +00:00
See [DNS01 Challenge Fields](/configuration/shared/dns01_challenge/) for details.
### Reality Fields
!!! warning ""
reality server is not included by default, see [Installation](./#installation).
!!! warning ""
uTLS, which is required by reality client is not included by default, see [Installation](./#installation).
#### handshake
==Server only==
==Required==
2023-12-14 14:23:52 +00:00
Handshake server address and [Dial options](/configuration/shared/dial/).
#### private_key
==Server only==
==Required==
2023-03-05 02:50:51 +00:00
Private key, generated by `sing-box generate reality-keypair`.
#### public_key
==Client only==
==Required==
2023-03-05 02:50:51 +00:00
Public key, generated by `sing-box generate reality-keypair`.
#### short_id
==Required==
A hexadecimal string with zero to eight digits.
#### max_time_difference
==Server only==
The maximum time difference between the server and the client.
Check disabled if empty.
2022-09-10 14:42:20 +00:00
### Reload
2023-08-29 14:43:48 +00:00
For server configuration, certificate, key and ECH key will be automatically reloaded if modified.