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