-
Notifications
You must be signed in to change notification settings - Fork 2.6k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: support host level dynamic setting of tls protocol version
- Loading branch information
Showing
11 changed files
with
944 additions
and
4 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,248 @@ | ||
| --- | ||
| 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 dynamically specifying different TLS protocol versions for each host. | ||
|
|
||
| ## Configuration instructions | ||
|
|
||
| - Static configuration | ||
| The ssl_protocols parameters in the static configuration will apply globally to apisix, but cannot be modified dynamically. | ||
|
|
||
| ```yaml | ||
| apisix: | ||
| ssl: | ||
| ssl_protocols: TLSv1.2 TLSv1.3 | ||
| ``` | ||
| - Dynamic resource allocation | ||
| Dynamic resource configuration is to create and manage ssl resources through the admin API interface of apisix. The new ssl. ssl_protocols configuration item can control fine grain for the host and dynamically specify the TLS protocol version of each host. | ||
| ```bash | ||
| # curl http://127.0.0.1:9180/admin/apisix/ssls/1 | ||
| { | ||
| "cert": "$cert", | ||
| "key": "$key", | ||
| "snis": ["test.com"], | ||
| "ssl_protocols": [ | ||
| "TLSv1.2", | ||
| "TLSv1.3" | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| The configuration will be subject to the ssl resource, and the static configuration will be overwritten . For example, if you set ssl_protocols: TLSv1.2 TLSv1.3 in config.yaml, but set ssl.ssl_protocols: [TLSv1.3] in the resource configuration, then the final apisix will use the TLSv1.3 protocol. Therefore, when using the ssl configuration of apisix, you need to pay attention to the following points: | ||
|
|
||
| - SSL resource configuration will override static configuration globally, subject to resource configuration. | ||
| - SSL resource configuration can be modified dynamically, while static configuration requires a restart of apisix to take effect. | ||
| - SSL resource configuration can be controlled according to fine grain sni. | ||
|
|
||
| ## Usage examples | ||
|
|
||
| ### Scenario, one-on-one adaptation of multiple TLS protocol versions | ||
|
|
||
| In the communication between end point products and servers, we need to consider the TLS protocol compatibility issues of multiple end point products. For example, some old products, old Android phones, TVs and other end point devices, still use the lower-level TLSv1.1 protocol version, while new products use the higher-level TLS protocol version. If the new product supports TLSv1.1, it may bring some security risks. In order to ensure that the product can establish secure communication, we need to adapt between protocol versions. | ||
| As shown in the following example, app.org is the domain name used by the end point device of the old product and needs to be configured as TLSv1.1, while app2.org belongs to the new product and supports the TLSv1.2 and TLSv1.3 protocols. | ||
|
|
||
| 1. Specify the TLSv1.1 protocol version for app.org legacy products. | ||
|
|
||
| ```bash | ||
| # curl http://127.0.0.1:9180/admin/apisix/ssls/app | ||
| { | ||
| "cert": "$app_cert", | ||
| "key": "$app_key", | ||
| "snis": ["app.org"], | ||
| "ssl_protocols": [ | ||
| "TLSv1.1" | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| 2. app2.org new product line specifies support for the TLSv1.2 and TLSv1.3 protocols. | ||
|
|
||
| ```bash | ||
| # curl http://127.0.0.1:9180/admin/apisix/ssls/app2 | ||
| { | ||
| "cert": "$app2_cert", | ||
| "key": "$app2_key", | ||
| "snis": ["app2.org"], | ||
| "ssl_protocols": [ | ||
| "TLSv1.2", | ||
| "TLSv1.3" | ||
| ] | ||
| } | ||
| curl --tls-max 1.1 --tlsv1.1 https://app.org # tls 1.1 | ||
|
|
||
| curl --tls-max 1.3 --tlsv1.2 https://app2.org # tls 1.2 | ||
| ``` | ||
|
|
||
| ### Scenario, two or more domain names use different protocols, but are associated with the same certificate. | ||
|
|
||
| Sometimes, we may encounter a scenario where multiple domain names are associated with the same certificate, but they need to use different versions of the TLS protocol to ensure security. For example, test.com domain names need to use the TlSv1.2 protocol, while test2.com domain names need to use the TLSv1.3 protocol. In this case, we cannot simply use the same SSL object for all domain names, but need to create a separate SSL object for each domain name and specify the corresponding protocol version. In this way, we can perform correct SSL handshaking and encrypted communication based on different domain names and protocol versions. An example is as follows: | ||
|
|
||
| 1. Create ssl object for test.com using certificate and specify TLSv1.2 protocol | ||
|
|
||
| ```bash | ||
| # curl http://127.0.0.1:9180/admin/apisix/ssls/test | ||
| { | ||
| "cert": "$cert", | ||
| "key": "$key", | ||
| "snis": ["test.com"], | ||
| "ssl_protocols": [ | ||
| "TLSv1.2" | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| 2. Using the same certificate as test.com, create an SSL object for test2.com and specify the TLSv1.3 protocol. | ||
|
|
||
| ```bash | ||
| # curl http://127.0.0.1:9180/admin/apisix/ssls/test2 | ||
| { | ||
| "cert": "$cert", | ||
| "key": "$key", | ||
| "snis": ["test2.com"], | ||
| "ssl_protocols": [ | ||
| "TLSv1.3" | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| 3. verify | ||
|
|
||
| * Successfully to accessed test.com with TLSv1.2 protocol | ||
|
|
||
| ```shell | ||
| $ curl --tls-max 1.2 --tlsv1.2 https://test.com:9443 -v -k -I | ||
| * Trying 127.0.0.1:9443... | ||
| * Connected to test.com (127.0.0.1) port 9443 (#0) | ||
| * ALPN, offering h2 | ||
| * ALPN, offering http/1.1 | ||
| * successfully set certificate verify locations: | ||
| * CAfile: /etc/ssl/certs/ca-certificates.crt | ||
| * CApath: /etc/ssl/certs | ||
| * TLSv1.2 (OUT), TLS handshake, Client hello (1): | ||
| * TLSv1.2 (IN), TLS handshake, Server hello (2): | ||
| * TLSv1.2 (IN), TLS handshake, Certificate (11): | ||
| * TLSv1.2 (IN), TLS handshake, Server key exchange (12): | ||
| * TLSv1.2 (IN), TLS handshake, Server finished (14): | ||
| * TLSv1.2 (OUT), TLS handshake, Client key exchange (16): | ||
| * TLSv1.2 (OUT), TLS change cipher, Change cipher spec (1): | ||
| * TLSv1.2 (OUT), TLS handshake, Finished (20): | ||
| * TLSv1.2 (IN), TLS handshake, Finished (20): | ||
| * SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256 | ||
| * ALPN, server accepted to use h2 | ||
| * Server certificate: | ||
| * subject: C=AU; ST=Some-State; O=Internet Widgits Pty Ltd; CN=test.com | ||
| * start date: Jul 20 15:50:08 2023 GMT | ||
| * expire date: Jul 17 15:50:08 2033 GMT | ||
| * issuer: C=AU; ST=Some-State; O=Internet Widgits Pty Ltd; CN=test.com | ||
| * SSL certificate verify result: EE certificate key too weak (66), continuing anyway. | ||
| * Using HTTP2, server supports multi-use | ||
| * Connection state changed (HTTP/2 confirmed) | ||
| * Copying HTTP/2 data in stream buffer to connection buffer after upgrade: len=0 | ||
| * Using Stream ID: 1 (easy handle 0x5608905ee2e0) | ||
| > HEAD / HTTP/2 | ||
| > Host: test.com:9443 | ||
| > user-agent: curl/7.74.0 | ||
| > accept: */* | ||
|
|
||
| ``` | ||
| * Failed to accessed test.com with TLSv1.3 protocol | ||
| ```shell | ||
| $ curl --tls-max 1.3 --tlsv1.3 https://test.com:9443 -v -k -I | ||
| * Trying 127.0.0.1:9443... | ||
| * Connected to test.com (127.0.0.1) port 9443 (#0) | ||
| * ALPN, offering h2 | ||
| * ALPN, offering http/1.1 | ||
| * successfully set certificate verify locations: | ||
| * CAfile: /etc/ssl/certs/ca-certificates.crt | ||
| * CApath: /etc/ssl/certs | ||
| * TLSv1.3 (OUT), TLS handshake, Client hello (1): | ||
| * TLSv1.3 (IN), TLS alert, protocol version (582): | ||
| * error:1409442E:SSL routines:ssl3_read_bytes:tlsv1 alert protocol version | ||
| * Closing connection 0 | ||
| curl: (35) error:1409442E:SSL routines:ssl3_read_bytes:tlsv1 alert protocol version | ||
|
|
||
| ``` | ||
| * Successfully to accessed test2.com with TLSv1.3 protocol | ||
| ```shell | ||
| $ curl --tls-max 1.3 --tlsv1.3 https://test2.com:9443 -v -k -I | ||
| * Trying 127.0.0.1:9443... | ||
| * Connected to test2.com (127.0.0.1) port 9443 (#0) | ||
| * ALPN, offering h2 | ||
| * ALPN, offering http/1.1 | ||
| * successfully set certificate verify locations: | ||
| * CAfile: /etc/ssl/certs/ca-certificates.crt | ||
| * CApath: /etc/ssl/certs | ||
| * TLSv1.3 (OUT), TLS handshake, Client hello (1): | ||
| * TLSv1.3 (IN), TLS handshake, Server hello (2): | ||
| * TLSv1.3 (IN), TLS handshake, Encrypted Extensions (8): | ||
| * TLSv1.3 (IN), TLS handshake, Certificate (11): | ||
| * TLSv1.3 (IN), TLS handshake, CERT verify (15): | ||
| * TLSv1.3 (IN), TLS handshake, Finished (20): | ||
| * TLSv1.3 (OUT), TLS change cipher, Change cipher spec (1): | ||
| * TLSv1.3 (OUT), TLS handshake, Finished (20): | ||
| * SSL connection using TLSv1.3 / TLS_AES_256_GCM_SHA384 | ||
| * ALPN, server accepted to use h2 | ||
| * Server certificate: | ||
| * subject: C=AU; ST=Some-State; O=Internet Widgits Pty Ltd; CN=test2.com | ||
| * start date: Jul 20 16:05:47 2023 GMT | ||
| * expire date: Jul 17 16:05:47 2033 GMT | ||
| * issuer: C=AU; ST=Some-State; O=Internet Widgits Pty Ltd; CN=test2.com | ||
| * SSL certificate verify result: EE certificate key too weak (66), continuing anyway. | ||
| * Using HTTP2, server supports multi-use | ||
| * Connection state changed (HTTP/2 confirmed) | ||
| * Copying HTTP/2 data in stream buffer to connection buffer after upgrade: len=0 | ||
| * Using Stream ID: 1 (easy handle 0x55569cbe42e0) | ||
| > HEAD / HTTP/2 | ||
| > Host: test2.com:9443 | ||
| > user-agent: curl/7.74.0 | ||
| > accept: */* | ||
| > | ||
| * TLSv1.3 (IN), TLS handshake, Newsession Ticket (4): | ||
| * TLSv1.3 (IN), TLS handshake, Newsession Ticket (4): | ||
| * old SSL session ID is stale, removing | ||
| ``` | ||
| * Failed to accessed test2.com with TLSv1.2 protocol | ||
| ```shell | ||
| $ curl --tls-max 1.2 --tlsv1.2 https://test2.com:9443 -v -k -I | ||
| * Trying 127.0.0.1:9443... | ||
| * Connected to test2.com (127.0.0.1) port 9443 (#0) | ||
| * ALPN, offering h2 | ||
| * ALPN, offering http/1.1 | ||
| * successfully set certificate verify locations: | ||
| * CAfile: /etc/ssl/certs/ca-certificates.crt | ||
| * CApath: /etc/ssl/certs | ||
| * TLSv1.2 (OUT), TLS handshake, Client hello (1): | ||
| * TLSv1.2 (IN), TLS alert, protocol version (582): | ||
| * error:1409442E:SSL routines:ssl3_read_bytes:tlsv1 alert protocol version | ||
| * Closing connection 0 | ||
| curl: (35) error:1409442E:SSL routines:ssl3_read_bytes:tlsv1 alert protocol version | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.