github.com/sagernet/sing-box@v1.9.0-rc.20/docs/configuration/shared/tls.md (about)

     1  !!! quote "Changes in sing-box 1.8.0"
     2  
     3      :material-alert-decagram: [utls](#utls)  
     4  
     5  ### Inbound
     6  
     7  ```json
     8  {
     9    "enabled": true,
    10    "server_name": "",
    11    "alpn": [],
    12    "min_version": "",
    13    "max_version": "",
    14    "cipher_suites": [],
    15    "certificate": [],
    16    "certificate_path": "",
    17    "key": [],
    18    "key_path": "",
    19    "acme": {
    20      "domain": [],
    21      "data_directory": "",
    22      "default_server_name": "",
    23      "email": "",
    24      "provider": "",
    25      "disable_http_challenge": false,
    26      "disable_tls_alpn_challenge": false,
    27      "alternative_http_port": 0,
    28      "alternative_tls_port": 0,
    29      "external_account": {
    30        "key_id": "",
    31        "mac_key": ""
    32      },
    33      "dns01_challenge": {}
    34    },
    35    "ech": {
    36      "enabled": false,
    37      "pq_signature_schemes_enabled": false,
    38      "dynamic_record_sizing_disabled": false,
    39      "key": [],
    40      "key_path": ""
    41    },
    42    "reality": {
    43      "enabled": false,
    44      "handshake": {
    45        "server": "google.com",
    46        "server_port": 443,
    47  
    48        ... // Dial Fields
    49      },
    50      "private_key": "UuMBgl7MXTPx9inmQp2UC7Jcnwc6XYbwDNebonM-FCc",
    51      "short_id": [
    52        "0123456789abcdef"
    53      ],
    54      "max_time_difference": "1m"
    55    }
    56  }
    57  ```
    58  
    59  ### Outbound
    60  
    61  ```json
    62  {
    63    "enabled": true,
    64    "disable_sni": false,
    65    "server_name": "",
    66    "insecure": false,
    67    "alpn": [],
    68    "min_version": "",
    69    "max_version": "",
    70    "cipher_suites": [],
    71    "certificate": "",
    72    "certificate_path": "",
    73    "ech": {
    74      "enabled": false,
    75      "pq_signature_schemes_enabled": false,
    76      "dynamic_record_sizing_disabled": false,
    77      "config": [],
    78      "config_path": ""
    79    },
    80    "utls": {
    81      "enabled": false,
    82      "fingerprint": ""
    83    },
    84    "reality": {
    85      "enabled": false,
    86      "public_key": "jNXHt1yRo0vDuchQlIP6Z0ZvjT3KtzVI-T4E7RoLJS0",
    87      "short_id": "0123456789abcdef"
    88    }
    89  }
    90  ```
    91  
    92  TLS version values:
    93  
    94  * `1.0`
    95  * `1.1`
    96  * `1.2`
    97  * `1.3`
    98  
    99  Cipher suite values:
   100  
   101  * `TLS_RSA_WITH_AES_128_CBC_SHA`
   102  * `TLS_RSA_WITH_AES_256_CBC_SHA`
   103  * `TLS_RSA_WITH_AES_128_GCM_SHA256`
   104  * `TLS_RSA_WITH_AES_256_GCM_SHA384`
   105  * `TLS_AES_128_GCM_SHA256`
   106  * `TLS_AES_256_GCM_SHA384`
   107  * `TLS_CHACHA20_POLY1305_SHA256`
   108  * `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`
   109  * `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`
   110  * `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`
   111  * `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`
   112  * `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`
   113  * `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`
   114  * `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`
   115  * `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`
   116  * `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`
   117  * `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`
   118  
   119  !!! note ""
   120  
   121      You can ignore the JSON Array [] tag when the content is only one item
   122  
   123  ### Fields
   124  
   125  #### enabled
   126  
   127  Enable TLS.
   128  
   129  #### disable_sni
   130  
   131  ==Client only==
   132  
   133  Do not send server name in ClientHello.
   134  
   135  #### server_name
   136  
   137  Used to verify the hostname on the returned certificates unless insecure is given.
   138  
   139  It is also included in the client's handshake to support virtual hosting unless it is an IP address.
   140  
   141  #### insecure
   142  
   143  ==Client only==
   144  
   145  Accepts any server certificate.
   146  
   147  #### alpn
   148  
   149  List of supported application level protocols, in order of preference.
   150  
   151  If both peers support ALPN, the selected protocol will be one from this list, and the connection will fail if there is
   152  no mutually supported protocol.
   153  
   154  See [Application-Layer Protocol Negotiation](https://en.wikipedia.org/wiki/Application-Layer_Protocol_Negotiation).
   155  
   156  #### min_version
   157  
   158  The minimum TLS version that is acceptable.
   159  
   160  By default, TLS 1.2 is currently used as the minimum when acting as a
   161  client, and TLS 1.0 when acting as a server.
   162  
   163  #### max_version
   164  
   165  The maximum TLS version that is acceptable.
   166  
   167  By default, the maximum version is currently TLS 1.3.
   168  
   169  #### cipher_suites
   170  
   171  A list of enabled TLS 1.0–1.2 cipher suites. The order of the list is ignored. Note that TLS 1.3 cipher suites are not configurable.
   172  
   173  If empty, a safe default list is used. The default cipher suites might change over time.
   174  
   175  #### certificate
   176  
   177  The server certificate line array, in PEM format.
   178  
   179  #### certificate_path
   180  
   181  The path to the server certificate, in PEM format.
   182  
   183  #### key
   184  
   185  ==Server only==
   186  
   187  The server private key line array, in PEM format.
   188  
   189  #### key_path
   190  
   191  ==Server only==
   192  
   193  The path to the server private key, in PEM format.
   194  
   195  ## Custom TLS support
   196  
   197  !!! info "QUIC support"
   198  
   199      Only ECH is supported in QUIC.
   200  
   201  #### utls
   202  
   203  ==Client only==
   204  
   205  !!! note ""
   206  
   207      uTLS is poorly maintained and the effect may be unproven, use at your own risk.
   208  
   209  uTLS is a fork of "crypto/tls", which provides ClientHello fingerprinting resistance.
   210  
   211  Available fingerprint values:
   212  
   213  !!! question "Since sing-box 1.8.0"
   214  
   215      :material-plus: chrome_psk  
   216      :material-plus: chrome_psk_shuffle  
   217      :material-plus: chrome_padding_psk_shuffle  
   218      :material-plus: chrome_pq  
   219      :material-plus: chrome_pq_psk
   220  
   221  * chrome
   222  * chrome_psk
   223  * chrome_psk_shuffle
   224  * chrome_padding_psk_shuffle
   225  * chrome_pq
   226  * chrome_pq_psk
   227  * firefox
   228  * edge
   229  * safari
   230  * 360
   231  * qq
   232  * ios
   233  * android
   234  * random
   235  * randomized
   236  
   237  Chrome fingerprint will be used if empty.
   238  
   239  ### ECH Fields
   240  
   241  ECH (Encrypted Client Hello) is a TLS extension that allows a client to encrypt the first part of its ClientHello
   242  message.
   243  
   244  The ECH key and configuration can be generated by `sing-box generate ech-keypair [--pq-signature-schemes-enabled]`.
   245  
   246  #### pq_signature_schemes_enabled
   247  
   248  Enable support for post-quantum peer certificate signature schemes.
   249  
   250  It is recommended to match the parameters of `sing-box generate ech-keypair`.
   251  
   252  #### dynamic_record_sizing_disabled
   253  
   254  Disables adaptive sizing of TLS records.
   255  
   256  When true, the largest possible TLS record size is always used.  
   257  When false, the size of TLS records may be adjusted in an attempt to improve latency.
   258  
   259  #### key
   260  
   261  ==Server only==
   262  
   263  ECH key line array, in PEM format.
   264  
   265  #### key_path
   266  
   267  ==Server only==
   268  
   269  The path to ECH key, in PEM format.
   270  
   271  #### config
   272  
   273  ==Client only==
   274  
   275  ECH configuration line array, in PEM format.
   276  
   277  If empty, load from DNS will be attempted.
   278  
   279  #### config_path
   280  
   281  ==Client only==
   282  
   283  The path to ECH configuration, in PEM format.
   284  
   285  If empty, load from DNS will be attempted.
   286  
   287  ### ACME Fields
   288  
   289  #### domain
   290  
   291  List of domain.
   292  
   293  ACME will be disabled if empty.
   294  
   295  #### data_directory
   296  
   297  The directory to store ACME data.
   298  
   299  `$XDG_DATA_HOME/certmagic|$HOME/.local/share/certmagic` will be used if empty.
   300  
   301  #### default_server_name
   302  
   303  Server name to use when choosing a certificate if the ClientHello's ServerName field is empty.
   304  
   305  #### email
   306  
   307  The email address to use when creating or selecting an existing ACME server account
   308  
   309  #### provider
   310  
   311  The ACME CA provider to use.
   312  
   313  | Value                   | Provider      |
   314  |-------------------------|---------------|
   315  | `letsencrypt (default)` | Let's Encrypt |
   316  | `zerossl`               | ZeroSSL       |
   317  | `https://...`           | Custom        |
   318  
   319  #### disable_http_challenge
   320  
   321  Disable all HTTP challenges.
   322  
   323  #### disable_tls_alpn_challenge
   324  
   325  Disable all TLS-ALPN challenges
   326  
   327  #### alternative_http_port
   328  
   329  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
   330  listener for the HTTP challenge.
   331  
   332  #### alternative_tls_port
   333  
   334  The alternate port to use for the ACME TLS-ALPN challenge; the system must forward 443 to this port for challenge to
   335  succeed.
   336  
   337  #### external_account
   338  
   339  EAB (External Account Binding) contains information necessary to bind or map an ACME account to some other account known
   340  by the CA.
   341  
   342  External account bindings are "used to associate an ACME account with an existing account in a non-ACME system, such as
   343  a CA customer database.
   344  
   345  To enable ACME account binding, the CA operating the ACME server needs to provide the ACME client with a MAC key and a
   346  key identifier, using some mechanism outside of ACME. §7.3.4
   347  
   348  #### external_account.key_id
   349  
   350  The key identifier.
   351  
   352  #### external_account.mac_key
   353  
   354  The MAC key.
   355  
   356  #### dns01_challenge
   357  
   358  ACME DNS01 challenge field. If configured, other challenge methods will be disabled.
   359  
   360  See [DNS01 Challenge Fields](/configuration/shared/dns01_challenge/) for details.
   361  
   362  ### Reality Fields
   363  
   364  #### handshake
   365  
   366  ==Server only==
   367  
   368  ==Required==
   369  
   370  Handshake server address and [Dial options](/configuration/shared/dial/).
   371  
   372  #### private_key
   373  
   374  ==Server only==
   375  
   376  ==Required==
   377  
   378  Private key, generated by `sing-box generate reality-keypair`.
   379  
   380  #### public_key
   381  
   382  ==Client only==
   383  
   384  ==Required==
   385  
   386  Public key, generated by `sing-box generate reality-keypair`.
   387  
   388  #### short_id
   389  
   390  ==Required==
   391  
   392  A hexadecimal string with zero to eight digits.
   393  
   394  #### max_time_difference
   395  
   396  ==Server only==
   397  
   398  The maximum time difference between the server and the client.
   399  
   400  Check disabled if empty.
   401  
   402  ### Reload
   403  
   404  For server configuration, certificate, key and ECH key will be automatically reloaded if modified.