[GitHub] [apisix] lingsamuel commented on a change in pull request #4348: docs: add route and upstream mtls

[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