kayx23 commented on code in PR #9903: URL: https://github.com/apache/apisix/pull/9903#discussion_r1280170935
########## docs/en/latest/ssl-protocol.md: ########## @@ -0,0 +1,343 @@ +--- +title: SSL Protocol +--- + +<!-- +# +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +--> + +`APISIX` supports set TLS protocol and also supports dynamically specifying different TLS protocol versions for each [SNI](https://en.wikipedia.org/wiki/Server_Name_Indication). + +**For security reasons, the encryption suite used by default in `APISIX` does not support TLSv1.1 and lower versions.** +**If you need to enable the TLSv1.1 protocol, please add the encryption suite supported by the TLSv1.1 protocol to the configuration item `apisix.ssl.ssl_ciphers` in `config.yaml`.** + +## ssl_protocols Configuration + +### Static Configuration + +The `ssl_protocols` parameter in the static configuration `config.yaml` applies to the entire APISIX, but cannot be dynamically modified. It only takes effect when the matching SSL resource does not set `ssl_protocols`. + +```yaml +apisix: + ssl: + ssl_protocols: TLSv1.2 TLSv1.3 # default TLSv1.2 TLSv1.3 +``` + +### Dynamic Configuration + +Use the `ssl_protocols` field in the `ssl` resource to dynamically specify different TLS protocol versions for each SNI. + +* Specify the `test.com` domain uses the TLSv1.2 and TLSv1.3. + +```bash +{ + "cert": "$cert", + "key": "$key", + "snis": ["test.com"], + "ssl_protocols": [ + "TLSv1.2", + "TLSv1.3" + ] +} +``` + +### Notes + +- Dynamic configuration has a higher priority than static configuration. When the ssl_protocols configuration item in the ssl resource is not empty, the static configuration will be overridden. +- The static configuration applies to the entire APISIX and requires a restart of APISIX to take effect. +- Dynamic configuration can control the TLS protocol version of each SNI in a fine-grained manner and can be dynamically modified, which is more flexible than static configuration. + +## Examples + +### How to specify the TLSv1.1 protocol + +There are some old clients that still use the lower-level TLSv1.1 protocol version, while new products use higher security-level TLS protocol versions. Enabling TLSv1.1 for new products may bring some security risks. To ensure the security of the API, we need to flexibly switch between protocol versions. +For example: test.com is the domain name used by old clients and needs to be configured for TLSv1.1, while test2.com belongs to new products and supports TLSv1.2 and TLSv1.3 protocols. + +1. config.yaml configuration. + +```yaml +apisix: + ssl: + ssl_protocols: TLSv1.3 + # ssl_ciphers is for reference only + ssl_ciphers: ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES256-SHA:DHE-DSS-AES256-SHA +``` + +2. Specify the TLSv1.1 protocol version for the test.com domain. + +```bash +curl http://127.0.0.1:9180/apisix/admin/ssls/1 \ +-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +{ + "cert" : "'"$(cat server.crt)"'", + "key": "'"$(cat server.key)"'", + "snis": ["test.com"], + "ssl_protocols": [ + "TLSv1.1" + ] +}' +``` + +3. Create an SSL object for test.com without specifying the TLS protocol version, which will use the static configuration by default. + +```bash +curl http://127.0.0.1:9180/apisix/admin/ssls/1 \ +-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +{ + "cert" : "'"$(cat server2.crt)"'", + "key": "'"$(cat server2.key)"'", + "snis": ["test2.com"] +}' +``` + +3. Access Verification Review Comment: ``` 3. Access Verification ``` There's already a number 3 above: `3. Create an SSL object for test.com without specifying the TLS protocol version, which will use the static ...` Same for the Chinese doc. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: notifications-unsubscr...@apisix.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
