You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by GitBox <gi...@apache.org> on 2021/05/31 23:24:43 UTC
[GitHub] [apisix] lingsamuel opened a new pull request #4348: docs: add route and upstream mtls
lingsamuel opened a new pull request #4348:
URL: https://github.com/apache/apisix/pull/4348
Signed-off-by: Ling Samuel <li...@gmail.com>
### What this PR does / why we need it:
Fixes #4327
### Pre-submission checklist:
* [x] Did you explain what problem does this PR solve? Or what new features have been added?
* [ ] Have you added corresponding test cases?
* [x] Have you modified the corresponding document?
* [ ] Is this PR backward compatible? **If it is not backward compatible, please discuss on the [mailing list](https://github.com/apache/apisix/tree/master#community) first**
--
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.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] spacewander commented on a change in pull request #4348: docs: add route and upstream mtls
Posted by GitBox <gi...@apache.org>.
spacewander commented on a change in pull request #4348:
URL: https://github.com/apache/apisix/pull/4348#discussion_r648054675
##########
File path: docs/zh/latest/mtls.md
##########
@@ -66,7 +66,7 @@ curl --cacert /data/certs/mtls_ca.crt --key /data/certs/mtls_client.key --cert /
### 如何配置
-你需要构建 [APISIX-Openresty](./how-to-build.md#6-build-openresty-for-apisix)，并且需要在配置文件中设定 `etcd.tls` 来使 ETCD 的双向认证功能正常工作。
+你需要构建 [APISIX-Openresty](./how-to-build.md#为-APISIX-构建-OpenResty)，并且需要在配置文件中设定 `etcd.tls` 来使 ETCD 的双向认证功能正常工作。
Review comment:
Should be `6-为-apisix-构建-openresty`
--
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.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] Yiyiyimu commented on a change in pull request #4348: docs: add route and upstream mtls
Posted by GitBox <gi...@apache.org>.
Yiyiyimu commented on a change in pull request #4348:
URL: https://github.com/apache/apisix/pull/4348#discussion_r642736080
##########
File path: docs/en/latest/mtls.md
##########
@@ -59,3 +61,115 @@ Please replace the following certificate paths and domain name with your real on
```shell
curl --cacert /data/certs/mtls_ca.crt --key /data/certs/mtls_client.key --cert /data/certs/mtls_client.crt https://admin.apisix.dev:9180/apisix/admin/routes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
```
+
+## Protect Route
+
+### Why use it
+
+Using mTLS is a way to verify clients cryptographically. It is useful and important in cases where you want to have encrypted and secure traffic in both directions.
+
+### How to configure
+
+When configuring `ssl`, use parameter `client.ca` and `client.depth` to configure the root CA that signing client certificates and the max length of certificate chain.
+
+Here is an example Python script to create SSL with mTLS (id is `1`):
+
+```py
+#!/usr/bin/env python
+# coding: utf-8
+# save this file as ssl.py
+import sys
+# sudo pip install requests
+import requests
+
+if len(sys.argv) <= 4:
+ print("bad argument")
+ sys.exit(1)
+with open(sys.argv[1]) as f:
+ cert = f.read()
+with open(sys.argv[2]) as f:
+ key = f.read()
+sni = sys.argv[3]
+api_key = "edd1c9f034335f136f87ad84b625c8f1" # Change it
+
+reqParam = {
+ "cert": cert,
+ "key": key,
+ "snis": [sni],
+}
+if len(sys.argv) >= 6:
+ print("Setting mTLS")
+ reqParam["client"] = {}
+ with open(sys.argv[4]) as f:
+ clientCert = f.read()
+ reqParam["client"]["ca"] = clientCert
+ reqParam["client"]["depth"] = int(sys.argv[5])
+resp = requests.put("http://127.0.0.1:9180/apisix/admin/ssl/1", json=reqParam, headers={
+ "X-API-KEY": api_key,
+})
+print(resp.status_code)
+print(resp.text)
+```
+
+Create SSL:
+
+```bash
+./ssl.py ./server.pem ./server.key 'mtls.test.com' ./client_ca.pem 10
+
+# test it
+curl --resolve 'mtls.test.com:<APISIX_HTTPS_PORT>:<APISIX_URL>' "https://<APISIX_URL>:<APISIX_HTTPS_PORT>/hello" -k --cert ./client.pem --key ./client.key
+```
+
+Please make sure that the SNI fits the certificate domain.
+
+## mTLS Between APISIX and Upstream
+
+### Why use it
+
+Sometimes the upstream enabled mTLS. In this situation, the APISIX acts as the client, it needs to provide client certificate to communicate with upstream.
+
+### How to config
+
+When configuring `upstreams`, we could use parameter `tls.client_cert` and `tls.client_key` to configure the client certificate APISIX used to communicate with upstreams.
+
+This feature requires APISIX to run on [APISIX-OpenResty](./how-to-build.md#6-build-openresty-for-apisix).
Review comment:
```suggestion
This feature requires APISIX to run with [APISIX-OpenResty](./how-to-build.md#6-build-openresty-for-apisix).
```
--
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.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] spacewander commented on a change in pull request #4348: docs: add route and upstream mtls
Posted by GitBox <gi...@apache.org>.
spacewander commented on a change in pull request #4348:
URL: https://github.com/apache/apisix/pull/4348#discussion_r642718320
##########
File path: docs/en/latest/mtls.md
##########
@@ -59,3 +61,115 @@ Please replace the following certificate paths and domain name with your real on
```shell
curl --cacert /data/certs/mtls_ca.crt --key /data/certs/mtls_client.key --cert /data/certs/mtls_client.crt https://admin.apisix.dev:9180/apisix/admin/routes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
```
+
+## Protect Route
+
+### Why use it
+
+Using mTLS is a way to verify clients cryptographically. It is useful and important in cases where you want to have encrypted and secure traffic in both directions.
+
+### How to config
+
+When configuring `ssl`, use parameter `client.ca` and `client.depth` to config the root CA that signing client certificates and the max length of certificate chain.
+
+Here is an example Python script to create SSL with mTLS (id is `1`):
+
+```py
+#!/usr/bin/env python
+# coding: utf-8
+# save this file as ssl.py
+import sys
+# sudo pip install requests
+import requests
+
+if len(sys.argv) <= 3:
+ print("bad argument")
+ sys.exit(1)
+with open(sys.argv[1]) as f:
+ cert = f.read()
+with open(sys.argv[2]) as f:
+ key = f.read()
+sni = sys.argv[3]
+api_key = "edd1c9f034335f136f87ad84b625c8f1" # Change it
+
+reqParam = {
+ "cert": cert,
+ "key": key,
+ "snis": [sni],
+}
+if len(sys.argv) >= 5:
+ print("Setting mTLS")
+ reqParam["client"] = {}
+ with open(sys.argv[4]) as f:
+ clientCert = f.read()
+ reqParam["client"]["ca"] = clientCert
+ reqParam["client"]["depth"] = int(sys.argv[5])
Review comment:
Will there be an error when len(sys.argv) == 5?
##########
File path: docs/en/latest/mtls.md
##########
@@ -59,3 +61,115 @@ Please replace the following certificate paths and domain name with your real on
```shell
curl --cacert /data/certs/mtls_ca.crt --key /data/certs/mtls_client.key --cert /data/certs/mtls_client.crt https://admin.apisix.dev:9180/apisix/admin/routes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
```
+
+## Protect Route
+
+### Why use it
+
+Using mTLS is a way to verify clients cryptographically. It is useful and important in cases where you want to have encrypted and secure traffic in both directions.
+
+### How to config
+
+When configuring `ssl`, use parameter `client.ca` and `client.depth` to config the root CA that signing client certificates and the max length of certificate chain.
+
+Here is an example Python script to create SSL with mTLS (id is `1`):
+
+```py
+#!/usr/bin/env python
+# coding: utf-8
+# save this file as ssl.py
+import sys
+# sudo pip install requests
+import requests
+
+if len(sys.argv) <= 3:
+ print("bad argument")
+ sys.exit(1)
+with open(sys.argv[1]) as f:
+ cert = f.read()
+with open(sys.argv[2]) as f:
+ key = f.read()
+sni = sys.argv[3]
+api_key = "edd1c9f034335f136f87ad84b625c8f1" # Change it
+
+reqParam = {
+ "cert": cert,
+ "key": key,
+ "snis": [sni],
+}
+if len(sys.argv) >= 5:
+ print("Setting mTLS")
+ reqParam["client"] = {}
+ with open(sys.argv[4]) as f:
+ clientCert = f.read()
+ reqParam["client"]["ca"] = clientCert
+ reqParam["client"]["depth"] = int(sys.argv[5])
+resp = requests.put("http://127.0.0.1:9180/apisix/admin/ssl/1", json=reqParam, headers={
+ "X-API-KEY": api_key,
+})
+print(resp.status_code)
+print(resp.text)
+```
+
+Create SSL:
+
+```bash
+./ssl.py ./server.pem ./server.key 'mtls.test.com' ./client_ca.pem 10
+
+# test it
+curl --resolve 'mtls.test.com:<APISIX_HTTPS_PORT>:<APISIX_URL>' "https://<APISIX_URL>:<APISIX_HTTPS_PORT>/hello" -k --cert ./client.pem --key ./client.key
+```
+
+Please make sure that the SNI fits the certificate domain.
+
+## mTLS Between APISIX and Upstream
+
+### Why use it
+
+Sometimes the upstream enabled mTLS. In this situation, the APISIX acts as the client, it needs to provide client certificate to communicate with upstream.
Review comment:
enabled => enables
It happens now.
##########
File path: docs/en/latest/mtls.md
##########
@@ -59,3 +61,115 @@ Please replace the following certificate paths and domain name with your real on
```shell
curl --cacert /data/certs/mtls_ca.crt --key /data/certs/mtls_client.key --cert /data/certs/mtls_client.crt https://admin.apisix.dev:9180/apisix/admin/routes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
```
+
+## Protect Route
+
+### Why use it
+
+Using mTLS is a way to verify clients cryptographically. It is useful and important in cases where you want to have encrypted and secure traffic in both directions.
+
+### How to config
+
+When configuring `ssl`, use parameter `client.ca` and `client.depth` to config the root CA that signing client certificates and the max length of certificate chain.
+
+Here is an example Python script to create SSL with mTLS (id is `1`):
+
+```py
+#!/usr/bin/env python
+# coding: utf-8
+# save this file as ssl.py
+import sys
+# sudo pip install requests
+import requests
+
+if len(sys.argv) <= 3:
+ print("bad argument")
+ sys.exit(1)
+with open(sys.argv[1]) as f:
+ cert = f.read()
+with open(sys.argv[2]) as f:
+ key = f.read()
+sni = sys.argv[3]
+api_key = "edd1c9f034335f136f87ad84b625c8f1" # Change it
+
+reqParam = {
+ "cert": cert,
+ "key": key,
+ "snis": [sni],
+}
+if len(sys.argv) >= 5:
+ print("Setting mTLS")
+ reqParam["client"] = {}
+ with open(sys.argv[4]) as f:
+ clientCert = f.read()
+ reqParam["client"]["ca"] = clientCert
+ reqParam["client"]["depth"] = int(sys.argv[5])
+resp = requests.put("http://127.0.0.1:9180/apisix/admin/ssl/1", json=reqParam, headers={
Review comment:
We use 9080 by default.
##########
File path: docs/en/latest/mtls.md
##########
@@ -59,3 +61,115 @@ Please replace the following certificate paths and domain name with your real on
```shell
curl --cacert /data/certs/mtls_ca.crt --key /data/certs/mtls_client.key --cert /data/certs/mtls_client.crt https://admin.apisix.dev:9180/apisix/admin/routes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
```
+
+## Protect Route
+
+### Why use it
+
+Using mTLS is a way to verify clients cryptographically. It is useful and important in cases where you want to have encrypted and secure traffic in both directions.
+
+### How to config
Review comment:
Use configure but not config in the doc
##########
File path: docs/en/latest/mtls.md
##########
@@ -59,3 +61,115 @@ Please replace the following certificate paths and domain name with your real on
```shell
curl --cacert /data/certs/mtls_ca.crt --key /data/certs/mtls_client.key --cert /data/certs/mtls_client.crt https://admin.apisix.dev:9180/apisix/admin/routes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
```
+
+## Protect Route
+
+### Why use it
+
+Using mTLS is a way to verify clients cryptographically. It is useful and important in cases where you want to have encrypted and secure traffic in both directions.
+
+### How to config
+
+When configuring `ssl`, use parameter `client.ca` and `client.depth` to config the root CA that signing client certificates and the max length of certificate chain.
+
+Here is an example Python script to create SSL with mTLS (id is `1`):
+
+```py
+#!/usr/bin/env python
+# coding: utf-8
+# save this file as ssl.py
+import sys
+# sudo pip install requests
+import requests
+
+if len(sys.argv) <= 3:
+ print("bad argument")
+ sys.exit(1)
+with open(sys.argv[1]) as f:
+ cert = f.read()
+with open(sys.argv[2]) as f:
+ key = f.read()
+sni = sys.argv[3]
+api_key = "edd1c9f034335f136f87ad84b625c8f1" # Change it
+
+reqParam = {
+ "cert": cert,
+ "key": key,
+ "snis": [sni],
+}
+if len(sys.argv) >= 5:
+ print("Setting mTLS")
+ reqParam["client"] = {}
+ with open(sys.argv[4]) as f:
+ clientCert = f.read()
+ reqParam["client"]["ca"] = clientCert
+ reqParam["client"]["depth"] = int(sys.argv[5])
+resp = requests.put("http://127.0.0.1:9180/apisix/admin/ssl/1", json=reqParam, headers={
+ "X-API-KEY": api_key,
+})
+print(resp.status_code)
+print(resp.text)
+```
+
+Create SSL:
+
+```bash
+./ssl.py ./server.pem ./server.key 'mtls.test.com' ./client_ca.pem 10
+
+# test it
+curl --resolve 'mtls.test.com:<APISIX_HTTPS_PORT>:<APISIX_URL>' "https://<APISIX_URL>:<APISIX_HTTPS_PORT>/hello" -k --cert ./client.pem --key ./client.key
+```
+
+Please make sure that the SNI fits the certificate domain.
+
+## mTLS Between APISIX and Upstream
+
+### Why use it
+
+Sometimes the upstream enabled mTLS. In this situation, the APISIX acts as the client, it needs to provide client certificate to communicate with upstream.
+
+### How to config
+
+When configuring `upstreams`, we could use parameter `tls.client_cert` and `tls.client_key` to config the client certificate APISIX used to communicate with upstreams.
+
+This feature requires APISIX to run on [APISIX-OpenResty](../how-to-build.md#6-build-openresty-for-apisix).
Review comment:
Bad link
--
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.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] lingsamuel commented on a change in pull request #4348: docs: add route and upstream mtls
Posted by GitBox <gi...@apache.org>.
lingsamuel commented on a change in pull request #4348:
URL: https://github.com/apache/apisix/pull/4348#discussion_r647914929
##########
File path: docs/zh/latest/mtls.md
##########
@@ -21,15 +21,19 @@ title: Admin API TLS 双向认证
#
-->
+## 保护 Admin API
+
### 为什么使用
-双向认证可以更好的防止未经授权访问 APISIX ，客户端将向服务器提供其证书，服务器将检查证书是否由提供的 CA 签名并决定是否响应请求。
+双向认证提供了一种更好的方法来阻止未经授权的对 APISIX Admin API 的访问。
+
+客户端需要向服务器提供证书，服务器将检查该客户端证书是否由受信的 CA 签名，并决定是否响应其请求。
-### 如何开启
+### 如何配置
Review comment:
It's to ensure consistency with other subsections.
--
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.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] Yiyiyimu merged pull request #4348: docs: add route and upstream mtls
Posted by GitBox <gi...@apache.org>.
Yiyiyimu merged pull request #4348:
URL: https://github.com/apache/apisix/pull/4348
--
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.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] spacewander commented on a change in pull request #4348: docs: add route and upstream mtls
Posted by GitBox <gi...@apache.org>.
spacewander commented on a change in pull request #4348:
URL: https://github.com/apache/apisix/pull/4348#discussion_r642735161
##########
File path: docs/en/latest/mtls.md
##########
@@ -59,3 +61,115 @@ Please replace the following certificate paths and domain name with your real on
```shell
curl --cacert /data/certs/mtls_ca.crt --key /data/certs/mtls_client.key --cert /data/certs/mtls_client.crt https://admin.apisix.dev:9180/apisix/admin/routes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
```
+
+## Protect Route
+
+### Why use it
+
+Using mTLS is a way to verify clients cryptographically. It is useful and important in cases where you want to have encrypted and secure traffic in both directions.
+
+### How to config
+
+When configuring `ssl`, use parameter `client.ca` and `client.depth` to config the root CA that signing client certificates and the max length of certificate chain.
+
+Here is an example Python script to create SSL with mTLS (id is `1`):
+
+```py
+#!/usr/bin/env python
+# coding: utf-8
+# save this file as ssl.py
+import sys
+# sudo pip install requests
+import requests
+
+if len(sys.argv) <= 3:
+ print("bad argument")
+ sys.exit(1)
+with open(sys.argv[1]) as f:
+ cert = f.read()
+with open(sys.argv[2]) as f:
+ key = f.read()
+sni = sys.argv[3]
+api_key = "edd1c9f034335f136f87ad84b625c8f1" # Change it
+
+reqParam = {
+ "cert": cert,
+ "key": key,
+ "snis": [sni],
+}
+if len(sys.argv) >= 5:
+ print("Setting mTLS")
+ reqParam["client"] = {}
+ with open(sys.argv[4]) as f:
+ clientCert = f.read()
+ reqParam["client"]["ca"] = clientCert
+ reqParam["client"]["depth"] = int(sys.argv[5])
+resp = requests.put("http://127.0.0.1:9180/apisix/admin/ssl/1", json=reqParam, headers={
Review comment:
This section is not relative to admin mTLS.
People won't read through the whole doc. They just jump into a section.
--
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.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] spacewander commented on a change in pull request #4348: docs: add route and upstream mtls
Posted by GitBox <gi...@apache.org>.
spacewander commented on a change in pull request #4348:
URL: https://github.com/apache/apisix/pull/4348#discussion_r647922671
##########
File path: docs/zh/latest/mtls.md
##########
@@ -21,15 +21,19 @@ title: Admin API TLS 双向认证
#
-->
+## 保护 Admin API
+
### 为什么使用
-双向认证可以更好的防止未经授权访问 APISIX ，客户端将向服务器提供其证书，服务器将检查证书是否由提供的 CA 签名并决定是否响应请求。
+双向认证提供了一种更好的方法来阻止未经授权的对 APISIX Admin API 的访问。
+
+客户端需要向服务器提供证书，服务器将检查该客户端证书是否由受信的 CA 签名，并决定是否响应其请求。
-### 如何开启
+### 如何配置
Review comment:
Should fix the English doc first.
--
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.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] lingsamuel commented on a change in pull request #4348: docs: add route and upstream mtls
Posted by GitBox <gi...@apache.org>.
lingsamuel commented on a change in pull request #4348:
URL: https://github.com/apache/apisix/pull/4348#discussion_r642733675
##########
File path: docs/en/latest/mtls.md
##########
@@ -59,3 +61,115 @@ Please replace the following certificate paths and domain name with your real on
```shell
curl --cacert /data/certs/mtls_ca.crt --key /data/certs/mtls_client.key --cert /data/certs/mtls_client.crt https://admin.apisix.dev:9180/apisix/admin/routes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
```
+
+## Protect Route
+
+### Why use it
+
+Using mTLS is a way to verify clients cryptographically. It is useful and important in cases where you want to have encrypted and secure traffic in both directions.
+
+### How to config
+
+When configuring `ssl`, use parameter `client.ca` and `client.depth` to config the root CA that signing client certificates and the max length of certificate chain.
+
+Here is an example Python script to create SSL with mTLS (id is `1`):
+
+```py
+#!/usr/bin/env python
+# coding: utf-8
+# save this file as ssl.py
+import sys
+# sudo pip install requests
+import requests
+
+if len(sys.argv) <= 3:
+ print("bad argument")
+ sys.exit(1)
+with open(sys.argv[1]) as f:
+ cert = f.read()
+with open(sys.argv[2]) as f:
+ key = f.read()
+sni = sys.argv[3]
+api_key = "edd1c9f034335f136f87ad84b625c8f1" # Change it
+
+reqParam = {
+ "cert": cert,
+ "key": key,
+ "snis": [sni],
+}
+if len(sys.argv) >= 5:
+ print("Setting mTLS")
+ reqParam["client"] = {}
+ with open(sys.argv[4]) as f:
+ clientCert = f.read()
+ reqParam["client"]["ca"] = clientCert
+ reqParam["client"]["depth"] = int(sys.argv[5])
+resp = requests.put("http://127.0.0.1:9180/apisix/admin/ssl/1", json=reqParam, headers={
+ "X-API-KEY": api_key,
+})
+print(resp.status_code)
+print(resp.text)
+```
+
+Create SSL:
+
+```bash
+./ssl.py ./server.pem ./server.key 'mtls.test.com' ./client_ca.pem 10
+
+# test it
+curl --resolve 'mtls.test.com:<APISIX_HTTPS_PORT>:<APISIX_URL>' "https://<APISIX_URL>:<APISIX_HTTPS_PORT>/hello" -k --cert ./client.pem --key ./client.key
+```
+
+Please make sure that the SNI fits the certificate domain.
+
+## mTLS Between APISIX and Upstream
+
+### Why use it
+
+Sometimes the upstream enabled mTLS. In this situation, the APISIX acts as the client, it needs to provide client certificate to communicate with upstream.
Review comment:
*Existed upstream* uses mTLS, so we need to configure mTLS in APISIX. The upstream mTLS already configured before we configure APISIX.
--
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.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] spacewander commented on a change in pull request #4348: docs: add route and upstream mtls
Posted by GitBox <gi...@apache.org>.
spacewander commented on a change in pull request #4348:
URL: https://github.com/apache/apisix/pull/4348#discussion_r642735445
##########
File path: docs/en/latest/mtls.md
##########
@@ -97,7 +97,7 @@ reqParam = {
"key": key,
"snis": [sni],
}
-if len(sys.argv) >= 5:
+if len(sys.argv) >= 6:
Review comment:
The `depth` is optional to the mTLS feature. We should not require it.
##########
File path: docs/en/latest/mtls.md
##########
@@ -130,9 +130,9 @@ Sometimes the upstream enabled mTLS. In this situation, the APISIX acts as the c
### How to config
Review comment:
Need to fix it
--
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.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] lingsamuel commented on a change in pull request #4348: docs: add route and upstream mtls
Posted by GitBox <gi...@apache.org>.
lingsamuel commented on a change in pull request #4348:
URL: https://github.com/apache/apisix/pull/4348#discussion_r642738459
##########
File path: docs/en/latest/mtls.md
##########
@@ -59,3 +61,115 @@ Please replace the following certificate paths and domain name with your real on
```shell
curl --cacert /data/certs/mtls_ca.crt --key /data/certs/mtls_client.key --cert /data/certs/mtls_client.crt https://admin.apisix.dev:9180/apisix/admin/routes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
```
+
+## Protect Route
+
+### Why use it
+
+Using mTLS is a way to verify clients cryptographically. It is useful and important in cases where you want to have encrypted and secure traffic in both directions.
+
+### How to config
+
+When configuring `ssl`, use parameter `client.ca` and `client.depth` to config the root CA that signing client certificates and the max length of certificate chain.
+
+Here is an example Python script to create SSL with mTLS (id is `1`):
+
+```py
+#!/usr/bin/env python
+# coding: utf-8
+# save this file as ssl.py
+import sys
+# sudo pip install requests
+import requests
+
+if len(sys.argv) <= 3:
+ print("bad argument")
+ sys.exit(1)
+with open(sys.argv[1]) as f:
+ cert = f.read()
+with open(sys.argv[2]) as f:
+ key = f.read()
+sni = sys.argv[3]
+api_key = "edd1c9f034335f136f87ad84b625c8f1" # Change it
+
+reqParam = {
+ "cert": cert,
+ "key": key,
+ "snis": [sni],
+}
+if len(sys.argv) >= 5:
+ print("Setting mTLS")
+ reqParam["client"] = {}
+ with open(sys.argv[4]) as f:
+ clientCert = f.read()
+ reqParam["client"]["ca"] = clientCert
+ reqParam["client"]["depth"] = int(sys.argv[5])
+resp = requests.put("http://127.0.0.1:9180/apisix/admin/ssl/1", json=reqParam, headers={
+ "X-API-KEY": api_key,
+})
+print(resp.status_code)
+print(resp.text)
+```
+
+Create SSL:
+
+```bash
+./ssl.py ./server.pem ./server.key 'mtls.test.com' ./client_ca.pem 10
+
+# test it
+curl --resolve 'mtls.test.com:<APISIX_HTTPS_PORT>:<APISIX_URL>' "https://<APISIX_URL>:<APISIX_HTTPS_PORT>/hello" -k --cert ./client.pem --key ./client.key
+```
+
+Please make sure that the SNI fits the certificate domain.
+
+## mTLS Between APISIX and Upstream
+
+### Why use it
+
+Sometimes the upstream enabled mTLS. In this situation, the APISIX acts as the client, it needs to provide client certificate to communicate with upstream.
Review comment:
What about: `upstream requires mTLS`?
--
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.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] lingsamuel commented on a change in pull request #4348: docs: add route and upstream mtls
Posted by GitBox <gi...@apache.org>.
lingsamuel commented on a change in pull request #4348:
URL: https://github.com/apache/apisix/pull/4348#discussion_r647113525
##########
File path: docs/en/latest/mtls.md
##########
@@ -59,3 +61,115 @@ Please replace the following certificate paths and domain name with your real on
```shell
curl --cacert /data/certs/mtls_ca.crt --key /data/certs/mtls_client.key --cert /data/certs/mtls_client.crt https://admin.apisix.dev:9180/apisix/admin/routes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
```
+
+## Protect Route
+
+### Why use it
+
+Using mTLS is a way to verify clients cryptographically. It is useful and important in cases where you want to have encrypted and secure traffic in both directions.
+
+### How to configure
+
+When configuring `ssl`, use parameter `client.ca` and `client.depth` to configure the root CA that signing client certificates and the max length of certificate chain.
+
+Here is an example Python script to create SSL with mTLS (id is `1`):
+
+```py
+#!/usr/bin/env python
+# coding: utf-8
+# save this file as ssl.py
+import sys
+# sudo pip install requests
+import requests
+
+if len(sys.argv) <= 4:
+ print("bad argument")
+ sys.exit(1)
+with open(sys.argv[1]) as f:
+ cert = f.read()
+with open(sys.argv[2]) as f:
+ key = f.read()
+sni = sys.argv[3]
+api_key = "edd1c9f034335f136f87ad84b625c8f1" # Change it
+
+reqParam = {
+ "cert": cert,
+ "key": key,
+ "snis": [sni],
+}
+if len(sys.argv) >= 6:
+ print("Setting mTLS")
+ reqParam["client"] = {}
+ with open(sys.argv[4]) as f:
+ clientCert = f.read()
+ reqParam["client"]["ca"] = clientCert
+ reqParam["client"]["depth"] = int(sys.argv[5])
+resp = requests.put("http://127.0.0.1:9180/apisix/admin/ssl/1", json=reqParam, headers={
+ "X-API-KEY": api_key,
+})
+print(resp.status_code)
+print(resp.text)
+```
+
+Create SSL:
+
+```bash
+./ssl.py ./server.pem ./server.key 'mtls.test.com' ./client_ca.pem 10
+
+# test it
+curl --resolve 'mtls.test.com:<APISIX_HTTPS_PORT>:<APISIX_URL>' "https://<APISIX_URL>:<APISIX_HTTPS_PORT>/hello" -k --cert ./client.pem --key ./client.key
+```
+
+Please make sure that the SNI fits the certificate domain.
+
+## mTLS Between APISIX and Upstream
+
+### Why use it
+
+Sometimes the upstream enabled mTLS. In this situation, the APISIX acts as the client, it needs to provide client certificate to communicate with upstream.
+
+### How to config
+
+When configuring `upstreams`, we could use parameter `tls.client_cert` and `tls.client_key` to configure the client certificate APISIX used to communicate with upstreams.
+
+This feature requires APISIX to run on [APISIX-OpenResty](./how-to-build.md#6-build-openresty-for-apisix).
Review comment:
This line copied from https://github.com/apache/apisix/blob/master/docs/en/latest/admin-api.md#request-body-parameters-3
--
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.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] spacewander commented on a change in pull request #4348: docs: add route and upstream mtls
Posted by GitBox <gi...@apache.org>.
spacewander commented on a change in pull request #4348:
URL: https://github.com/apache/apisix/pull/4348#discussion_r647206781
##########
File path: docs/zh/latest/mtls.md
##########
@@ -21,15 +21,19 @@ title: Admin API TLS 双向认证
#
-->
+## 保护 Admin API
+
### 为什么使用
-双向认证可以更好的防止未经授权访问 APISIX ，客户端将向服务器提供其证书，服务器将检查证书是否由提供的 CA 签名并决定是否响应请求。
+双向认证提供了一种更好的方法来阻止未经授权的对 APISIX Admin API 的访问。
+
+客户端需要向服务器提供证书，服务器将检查该客户端证书是否由受信的 CA 签名，并决定是否响应其请求。
-### 如何开启
+### 如何配置
Review comment:
The English version is "How to enable"...
##########
File path: docs/zh/latest/mtls.md
##########
@@ -50,10 +54,136 @@ apisix reload
### 客户端如何调用
-请将以下证书及域名替换为您的真实内容。
+需要将证书文件的路径与域名按实际情况替换。
-* 注意：需要和服务器使用相同的 CA 证书 *
+* 注意：提供的 CA 证书需要与服务端的相同。*
```shell
curl --cacert /data/certs/mtls_ca.crt --key /data/certs/mtls_client.key --cert /data/certs/mtls_client.crt https://admin.apisix.dev:9180/apisix/admin/routes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
```
+
+## 保护 ETCD
+
+### 如何配置
+
+你需要构建 [APISIX-Openresty](./how-to-build.md#6-build-openresty-for-apisix)，并且需要在配置文件中设定 `etcd.tls` 来使 ETCD 的双向认证功能正常工作。
+
+```yaml
+etcd:
+ tls:
+ cert: /data/certs/etcd_client.pem # path of certificate used by the etcd client
+ key: /data/certs/etcd_client.key # path of key used by the etcd client
+```
+
+## 保护路由
+
+### 为什么使用
+
+双向认证是一种密码学安全的验证客户端身份的手段。当你需要加密并保护流量的双向安全时很有用。
+
+### 如何配置
+
+在配置 `ssl` 资源时，同时需要配置 `client.ca` 和 `client.depth` 参数，分别代表为客户端证书签名的 CA 列表，和证书链的最大深度。可参考：[SSL API 文档](./admin-api.md#ssl)。
+
+下面是一个可用于生成带双向认证配置的 SSL 资源的 Python 脚本示例。如果需要，可修改 API 地址、API Key 和 SSL 资源的 ID。
+
+```py
+#!/usr/bin/env python
+# coding: utf-8
+# 保存该文件为 ssl.py
+import sys
+# sudo pip install requests
+import requests
+
+if len(sys.argv) <= 4:
+ print("bad argument")
+ sys.exit(1)
+with open(sys.argv[1]) as f:
+ cert = f.read()
+with open(sys.argv[2]) as f:
+ key = f.read()
+sni = sys.argv[3]
+api_key = "edd1c9f034335f136f87ad84b625c8f1" # Change it
+
+reqParam = {
+ "cert": cert,
+ "key": key,
+ "snis": [sni],
+}
+if len(sys.argv) >= 5:
+ print("Setting mTLS")
+ reqParam["client"] = {}
+ with open(sys.argv[4]) as f:
+ clientCert = f.read()
+ reqParam["client"]["ca"] = clientCert
+ if len(sys.argv) >= 6:
+ reqParam["client"]["depth"] = int(sys.argv[5])
+resp = requests.put("http://127.0.0.1:9080/apisix/admin/ssl/1", json=reqParam, headers={
+ "X-API-KEY": api_key,
+})
+print(resp.status_code)
+print(resp.text)
+```
+
+使用上述 Python 脚本创建 SSL 资源：
+
+```bash
+./ssl.py ./server.pem ./server.key 'mtls.test.com' ./client_ca.pem 10
+
+# 测试
+curl --resolve 'mtls.test.com:<APISIX_HTTPS_PORT>:<APISIX_URL>' "https://<APISIX_URL>:<APISIX_HTTPS_PORT>/hello" -k --cert ./client.pem --key ./client.key
+```
+
+注意，测试时使用的域名需要符合证书的参数。
+
+## APISIX 与上游间的双向认证
+
+### 为什么使用
+
+有时候上游的服务启用了双向认证。在这种情况下，APISIX 作为上游服务的客户端，需要提供客户端证书来正常与其进行通信。
+
+### 如何配置
+
+在配置 upstream 资源时，可以使用参数 `tls.client_cert` 和 `tls.client_key` 来配置 APISIX 用于与上游进行通讯时使用的证书。可参考 [Upstream API 文档](./admin-api.md#upstream)。
+
+该功能需要 APISIX 运行在 [APISIX-OpenResty](./how-to-build.md#6-build-openresty-for-apisix) 上。
Review comment:
The link should be corrected.
##########
File path: docs/zh/latest/mtls.md
##########
@@ -50,10 +54,136 @@ apisix reload
### 客户端如何调用
-请将以下证书及域名替换为您的真实内容。
+需要将证书文件的路径与域名按实际情况替换。
-* 注意：需要和服务器使用相同的 CA 证书 *
+* 注意：提供的 CA 证书需要与服务端的相同。*
```shell
curl --cacert /data/certs/mtls_ca.crt --key /data/certs/mtls_client.key --cert /data/certs/mtls_client.crt https://admin.apisix.dev:9180/apisix/admin/routes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
```
+
+## 保护 ETCD
+
+### 如何配置
+
+你需要构建 [APISIX-Openresty](./how-to-build.md#6-build-openresty-for-apisix)，并且需要在配置文件中设定 `etcd.tls` 来使 ETCD 的双向认证功能正常工作。
+
+```yaml
+etcd:
+ tls:
+ cert: /data/certs/etcd_client.pem # path of certificate used by the etcd client
+ key: /data/certs/etcd_client.key # path of key used by the etcd client
+```
+
+## 保护路由
+
+### 为什么使用
+
+双向认证是一种密码学安全的验证客户端身份的手段。当你需要加密并保护流量的双向安全时很有用。
+
+### 如何配置
+
+在配置 `ssl` 资源时，同时需要配置 `client.ca` 和 `client.depth` 参数，分别代表为客户端证书签名的 CA 列表，和证书链的最大深度。可参考：[SSL API 文档](./admin-api.md#ssl)。
+
+下面是一个可用于生成带双向认证配置的 SSL 资源的 Python 脚本示例。如果需要，可修改 API 地址、API Key 和 SSL 资源的 ID。
+
+```py
+#!/usr/bin/env python
+# coding: utf-8
+# 保存该文件为 ssl.py
+import sys
+# sudo pip install requests
+import requests
+
+if len(sys.argv) <= 4:
+ print("bad argument")
+ sys.exit(1)
+with open(sys.argv[1]) as f:
+ cert = f.read()
+with open(sys.argv[2]) as f:
+ key = f.read()
+sni = sys.argv[3]
+api_key = "edd1c9f034335f136f87ad84b625c8f1" # Change it
+
+reqParam = {
+ "cert": cert,
+ "key": key,
+ "snis": [sni],
+}
+if len(sys.argv) >= 5:
+ print("Setting mTLS")
+ reqParam["client"] = {}
+ with open(sys.argv[4]) as f:
+ clientCert = f.read()
+ reqParam["client"]["ca"] = clientCert
+ if len(sys.argv) >= 6:
+ reqParam["client"]["depth"] = int(sys.argv[5])
+resp = requests.put("http://127.0.0.1:9080/apisix/admin/ssl/1", json=reqParam, headers={
+ "X-API-KEY": api_key,
+})
+print(resp.status_code)
+print(resp.text)
+```
+
+使用上述 Python 脚本创建 SSL 资源：
+
+```bash
+./ssl.py ./server.pem ./server.key 'mtls.test.com' ./client_ca.pem 10
+
+# 测试
+curl --resolve 'mtls.test.com:<APISIX_HTTPS_PORT>:<APISIX_URL>' "https://<APISIX_URL>:<APISIX_HTTPS_PORT>/hello" -k --cert ./client.pem --key ./client.key
+```
+
+注意，测试时使用的域名需要符合证书的参数。
+
+## APISIX 与上游间的双向认证
+
+### 为什么使用
+
+有时候上游的服务启用了双向认证。在这种情况下，APISIX 作为上游服务的客户端，需要提供客户端证书来正常与其进行通信。
+
+### 如何配置
+
+在配置 upstream 资源时，可以使用参数 `tls.client_cert` 和 `tls.client_key` 来配置 APISIX 用于与上游进行通讯时使用的证书。可参考 [Upstream API 文档](./admin-api.md#upstream)。
Review comment:
The English version doesn't have it
##########
File path: docs/zh/latest/mtls.md
##########
@@ -50,10 +54,136 @@ apisix reload
### 客户端如何调用
-请将以下证书及域名替换为您的真实内容。
+需要将证书文件的路径与域名按实际情况替换。
-* 注意：需要和服务器使用相同的 CA 证书 *
+* 注意：提供的 CA 证书需要与服务端的相同。*
```shell
curl --cacert /data/certs/mtls_ca.crt --key /data/certs/mtls_client.key --cert /data/certs/mtls_client.crt https://admin.apisix.dev:9180/apisix/admin/routes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
```
+
+## 保护 ETCD
+
+### 如何配置
+
+你需要构建 [APISIX-Openresty](./how-to-build.md#6-build-openresty-for-apisix)，并且需要在配置文件中设定 `etcd.tls` 来使 ETCD 的双向认证功能正常工作。
Review comment:
The link should be corrected.
##########
File path: docs/zh/latest/mtls.md
##########
@@ -50,10 +54,136 @@ apisix reload
### 客户端如何调用
-请将以下证书及域名替换为您的真实内容。
+需要将证书文件的路径与域名按实际情况替换。
-* 注意：需要和服务器使用相同的 CA 证书 *
+* 注意：提供的 CA 证书需要与服务端的相同。*
```shell
curl --cacert /data/certs/mtls_ca.crt --key /data/certs/mtls_client.key --cert /data/certs/mtls_client.crt https://admin.apisix.dev:9180/apisix/admin/routes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
```
+
+## 保护 ETCD
+
+### 如何配置
+
+你需要构建 [APISIX-Openresty](./how-to-build.md#6-build-openresty-for-apisix)，并且需要在配置文件中设定 `etcd.tls` 来使 ETCD 的双向认证功能正常工作。
+
+```yaml
+etcd:
+ tls:
+ cert: /data/certs/etcd_client.pem # path of certificate used by the etcd client
+ key: /data/certs/etcd_client.key # path of key used by the etcd client
+```
+
+## 保护路由
+
+### 为什么使用
+
+双向认证是一种密码学安全的验证客户端身份的手段。当你需要加密并保护流量的双向安全时很有用。
+
+### 如何配置
+
+在配置 `ssl` 资源时，同时需要配置 `client.ca` 和 `client.depth` 参数，分别代表为客户端证书签名的 CA 列表，和证书链的最大深度。可参考：[SSL API 文档](./admin-api.md#ssl)。
Review comment:
`可参考：[SSL API 文档](./admin-api.md#ssl)。`
The English version doesn't have it
--
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.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] lingsamuel commented on a change in pull request #4348: docs: add route and upstream mtls
Posted by GitBox <gi...@apache.org>.
lingsamuel commented on a change in pull request #4348:
URL: https://github.com/apache/apisix/pull/4348#discussion_r642734069
##########
File path: docs/en/latest/mtls.md
##########
@@ -59,3 +61,115 @@ Please replace the following certificate paths and domain name with your real on
```shell
curl --cacert /data/certs/mtls_ca.crt --key /data/certs/mtls_client.key --cert /data/certs/mtls_client.crt https://admin.apisix.dev:9180/apisix/admin/routes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
```
+
+## Protect Route
+
+### Why use it
+
+Using mTLS is a way to verify clients cryptographically. It is useful and important in cases where you want to have encrypted and secure traffic in both directions.
+
+### How to config
+
+When configuring `ssl`, use parameter `client.ca` and `client.depth` to config the root CA that signing client certificates and the max length of certificate chain.
+
+Here is an example Python script to create SSL with mTLS (id is `1`):
+
+```py
+#!/usr/bin/env python
+# coding: utf-8
+# save this file as ssl.py
+import sys
+# sudo pip install requests
+import requests
+
+if len(sys.argv) <= 3:
+ print("bad argument")
+ sys.exit(1)
+with open(sys.argv[1]) as f:
+ cert = f.read()
+with open(sys.argv[2]) as f:
+ key = f.read()
+sni = sys.argv[3]
+api_key = "edd1c9f034335f136f87ad84b625c8f1" # Change it
+
+reqParam = {
+ "cert": cert,
+ "key": key,
+ "snis": [sni],
+}
+if len(sys.argv) >= 5:
+ print("Setting mTLS")
+ reqParam["client"] = {}
+ with open(sys.argv[4]) as f:
+ clientCert = f.read()
+ reqParam["client"]["ca"] = clientCert
+ reqParam["client"]["depth"] = int(sys.argv[5])
+resp = requests.put("http://127.0.0.1:9180/apisix/admin/ssl/1", json=reqParam, headers={
Review comment:
YAML above uses 9180 https://github.com/apache/apisix/pull/4348/files#diff-245d1b166ec738da077d9e8fa92c62adf28099b762a9806bb63132a6c20b0efaR39
--
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.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] spacewander commented on a change in pull request #4348: docs: add route and upstream mtls
Posted by GitBox <gi...@apache.org>.
spacewander commented on a change in pull request #4348:
URL: https://github.com/apache/apisix/pull/4348#discussion_r642734902
##########
File path: docs/en/latest/mtls.md
##########
@@ -59,3 +61,115 @@ Please replace the following certificate paths and domain name with your real on
```shell
curl --cacert /data/certs/mtls_ca.crt --key /data/certs/mtls_client.key --cert /data/certs/mtls_client.crt https://admin.apisix.dev:9180/apisix/admin/routes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
```
+
+## Protect Route
+
+### Why use it
+
+Using mTLS is a way to verify clients cryptographically. It is useful and important in cases where you want to have encrypted and secure traffic in both directions.
+
+### How to config
+
+When configuring `ssl`, use parameter `client.ca` and `client.depth` to config the root CA that signing client certificates and the max length of certificate chain.
+
+Here is an example Python script to create SSL with mTLS (id is `1`):
+
+```py
+#!/usr/bin/env python
+# coding: utf-8
+# save this file as ssl.py
+import sys
+# sudo pip install requests
+import requests
+
+if len(sys.argv) <= 3:
+ print("bad argument")
+ sys.exit(1)
+with open(sys.argv[1]) as f:
+ cert = f.read()
+with open(sys.argv[2]) as f:
+ key = f.read()
+sni = sys.argv[3]
+api_key = "edd1c9f034335f136f87ad84b625c8f1" # Change it
+
+reqParam = {
+ "cert": cert,
+ "key": key,
+ "snis": [sni],
+}
+if len(sys.argv) >= 5:
+ print("Setting mTLS")
+ reqParam["client"] = {}
+ with open(sys.argv[4]) as f:
+ clientCert = f.read()
+ reqParam["client"]["ca"] = clientCert
+ reqParam["client"]["depth"] = int(sys.argv[5])
+resp = requests.put("http://127.0.0.1:9180/apisix/admin/ssl/1", json=reqParam, headers={
+ "X-API-KEY": api_key,
+})
+print(resp.status_code)
+print(resp.text)
+```
+
+Create SSL:
+
+```bash
+./ssl.py ./server.pem ./server.key 'mtls.test.com' ./client_ca.pem 10
+
+# test it
+curl --resolve 'mtls.test.com:<APISIX_HTTPS_PORT>:<APISIX_URL>' "https://<APISIX_URL>:<APISIX_HTTPS_PORT>/hello" -k --cert ./client.pem --key ./client.key
+```
+
+Please make sure that the SNI fits the certificate domain.
+
+## mTLS Between APISIX and Upstream
+
+### Why use it
+
+Sometimes the upstream enabled mTLS. In this situation, the APISIX acts as the client, it needs to provide client certificate to communicate with upstream.
Review comment:
The past tense looks like the upstream used to enable upstream, but it doesn't now.
--
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.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org