github.com/inazumav/sing-box@v0.0.0-20230926072359-ab51429a14f1/docs/configuration/shared/tls.md (about)

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