diff --git a/docs/en/latest/mtls.md b/docs/en/latest/mtls.md index 25a1747308e5..02e5e4b4550e 100644 --- a/docs/en/latest/mtls.md +++ b/docs/en/latest/mtls.md @@ -108,52 +108,69 @@ We provide a [tutorial](./tutorials/client-to-apisix-mtls.md) that explains in d 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. Please refer to [Admin API](./admin-api.md#ssl) for details. -Here is an example Python script to create SSL with mTLS (id is `1`, changes admin API url if needed): - -```python title="create-ssl.py" -#!/usr/bin/env python -# coding: utf-8 -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:9180/apisix/admin/ssls/1", json=reqParam, headers={ - "X-API-KEY": api_key, -}) -print(resp.status_code) -print(resp.text) +Here is an example shell script to create SSL with mTLS (id is `1`, changes admin API url if needed): + +```shell +curl http://127.0.0.1:9180/apisix/admin/ssls/1 \ +-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +{ + "cert": "'"$(cat t/certs/mtls_server.crt)"'", + "key": "'"$(cat t/certs/mtls_server.key)"'", + "snis": [ + "admin.apisix.dev" + ], + "client": { + "ca": "'"$(cat t/certs/mtls_ca.crt)"'", + "depth": 10 + } +}' ``` -Create SSL: +Send a request to verify: ```bash -./create-ssl.py ./server.pem ./server.key 'mtls.test.com' ./client_ca.pem 10 - -# test it curl --resolve 'mtls.test.com::' "https://:/hello" -k --cert ./client.pem --key ./client.key + +* Added admin.apisix.dev:9443:127.0.0.1 to DNS cache +* Hostname admin.apisix.dev was found in DNS cache +* Trying 127.0.0.1:9443... +* Connected to admin.apisix.dev (127.0.0.1) port 9443 (#0) +* ALPN: offers h2 +* ALPN: offers http/1.1 +* CAfile: t/certs/mtls_ca.crt +* CApath: none +* [CONN-0-0][CF-SSL] (304) (OUT), TLS handshake, Client hello (1): +* [CONN-0-0][CF-SSL] (304) (IN), TLS handshake, Server hello (2): +* [CONN-0-0][CF-SSL] (304) (IN), TLS handshake, Unknown (8): +* [CONN-0-0][CF-SSL] (304) (IN), TLS handshake, Request CERT (13): +* [CONN-0-0][CF-SSL] (304) (IN), TLS handshake, Certificate (11): +* [CONN-0-0][CF-SSL] (304) (IN), TLS handshake, CERT verify (15): +* [CONN-0-0][CF-SSL] (304) (IN), TLS handshake, Finished (20): +* [CONN-0-0][CF-SSL] (304) (OUT), TLS handshake, Certificate (11): +* [CONN-0-0][CF-SSL] (304) (OUT), TLS handshake, CERT verify (15): +* [CONN-0-0][CF-SSL] (304) (OUT), TLS handshake, Finished (20): +* SSL connection using TLSv1.3 / AEAD-AES256-GCM-SHA384 +* ALPN: server accepted h2 +* Server certificate: +* subject: C=cn; ST=GuangDong; L=ZhuHai; CN=admin.apisix.dev; OU=ops +* start date: Dec 1 10:17:24 2022 GMT +* expire date: Aug 18 10:17:24 2042 GMT +* subjectAltName: host "admin.apisix.dev" matched cert's "admin.apisix.dev" +* issuer: C=cn; ST=GuangDong; L=ZhuHai; CN=ca.apisix.dev; OU=ops +* SSL certificate verify ok. +* Using HTTP2, server supports multiplexing +* Copying HTTP/2 data in stream buffer to connection buffer after upgrade: len=0 +* h2h3 [:method: GET] +* h2h3 [:path: /hello] +* h2h3 [:scheme: https] +* h2h3 [:authority: admin.apisix.dev:9443] +* h2h3 [user-agent: curl/7.87.0] +* h2h3 [accept: */*] +* Using Stream ID: 1 (easy handle 0x13000bc00) +> GET /hello HTTP/2 +> Host: admin.apisix.dev:9443 +> user-agent: curl/7.87.0 +> accept: */* ``` Please make sure that the SNI fits the certificate domain. @@ -170,41 +187,15 @@ When configuring `upstreams`, we could use parameter `tls.client_cert` and `tls. This feature requires APISIX to run on [APISIX-Runtime](./FAQ.md#how-do-i-build-the-apisix-runtime-environment). -Here is a similar Python script to patch a existed upstream with mTLS (changes admin API url if needed): - -```python title="patch_upstream_mtls.py" -#!/usr/bin/env python -# coding: utf-8 -import sys -# sudo pip install requests -import requests - -if len(sys.argv) < 4: - print("bad argument") - sys.exit(1) -with open(sys.argv[2]) as f: - cert = f.read() -with open(sys.argv[3]) as f: - key = f.read() -id = sys.argv[1] -api_key = "edd1c9f034335f136f87ad84b625c8f1" # Change it - -reqParam = { - "tls": { - "client_cert": cert, - "client_key": key, - }, -} - -resp = requests.patch("http://127.0.0.1:9180/apisix/admin/upstreams/"+id, json=reqParam, headers={ - "X-API-KEY": api_key, -}) -print(resp.status_code) -print(resp.text) -``` - -Patch existed upstream with id `testmtls`: +Here is a similar shell script to patch a existed upstream with mTLS (changes admin API url if needed): -```bash -./patch_upstream_mtls.py testmtls ./client.pem ./client.key +```shell +curl http://127.0.0.1:9180/apisix/admin/upstreams/1 \ +-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -d ' +{ + "tls": { + "client_cert": "'"$(cat t/certs/mtls_client.crt)"'", + "client_key": "'"$(cat t/certs/mtls_client.key)"'" + } +}' ``` diff --git a/docs/zh/latest/mtls.md b/docs/zh/latest/mtls.md index c96f48f2ad62..ad098c460d29 100644 --- a/docs/zh/latest/mtls.md +++ b/docs/zh/latest/mtls.md @@ -103,52 +103,68 @@ apisix: 在配置 `ssl` 资源时，同时需要配置 `client.ca` 和 `client.depth` 参数，分别代表为客户端证书签名的 CA 列表，和证书链的最大深度。可参考：[SSL API 文档](./admin-api.md#ssl)。 -下面是一个可用于生成带双向认证配置的 SSL 资源的 Python 脚本示例。如果需要，可修改 API 地址、API Key 和 SSL 资源的 ID。 - -```python title="create-ssl.py" -#!/usr/bin/env python -# coding: utf-8 -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:9180/apisix/admin/ssls/1", json=reqParam, headers={ - "X-API-KEY": api_key, -}) -print(resp.status_code) -print(resp.text) +下面是一个可用于生成带双向认证配置的 SSL 资源的 shell 脚本示例（如果需要，可修改 API 地址、API Key 和 SSL 资源的 ID。）： + +```shell +curl http://127.0.0.1:9180/apisix/admin/ssls/1 \ +-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' + "cert": "'"$(cat t/certs/mtls_server.crt)"'", + "key": "'"$(cat t/certs/mtls_server.key)"'", + "snis": [ + "admin.apisix.dev" + ], + "client": { + "ca": "'"$(cat t/certs/mtls_ca.crt)"'", + "depth": 10 + } +}' ``` -使用上述 Python 脚本创建 SSL 资源： +测试： ```bash -./create-ssl.py ./server.pem ./server.key 'mtls.test.com' ./client_ca.pem 10 - -# 测试 -curl --resolve 'mtls.test.com::' "https://:/hello" -k --cert ./client.pem --key ./client.key +curl -vvv --resolve 'admin.apisix.dev:9443:127.0.0.1' https://admin.apisix.dev:9443/hello --cert t/certs/mtls_client.crt --key t/certs/mtls_client.key --cacert t/certs/mtls_ca.crt + +* Added admin.apisix.dev:9443:127.0.0.1 to DNS cache +* Hostname admin.apisix.dev was found in DNS cache +* Trying 127.0.0.1:9443... +* Connected to admin.apisix.dev (127.0.0.1) port 9443 (#0) +* ALPN: offers h2 +* ALPN: offers http/1.1 +* CAfile: t/certs/mtls_ca.crt +* CApath: none +* [CONN-0-0][CF-SSL] (304) (OUT), TLS handshake, Client hello (1): +* [CONN-0-0][CF-SSL] (304) (IN), TLS handshake, Server hello (2): +* [CONN-0-0][CF-SSL] (304) (IN), TLS handshake, Unknown (8): +* [CONN-0-0][CF-SSL] (304) (IN), TLS handshake, Request CERT (13): +* [CONN-0-0][CF-SSL] (304) (IN), TLS handshake, Certificate (11): +* [CONN-0-0][CF-SSL] (304) (IN), TLS handshake, CERT verify (15): +* [CONN-0-0][CF-SSL] (304) (IN), TLS handshake, Finished (20): +* [CONN-0-0][CF-SSL] (304) (OUT), TLS handshake, Certificate (11): +* [CONN-0-0][CF-SSL] (304) (OUT), TLS handshake, CERT verify (15): +* [CONN-0-0][CF-SSL] (304) (OUT), TLS handshake, Finished (20): +* SSL connection using TLSv1.3 / AEAD-AES256-GCM-SHA384 +* ALPN: server accepted h2 +* Server certificate: +* subject: C=cn; ST=GuangDong; L=ZhuHai; CN=admin.apisix.dev; OU=ops +* start date: Dec 1 10:17:24 2022 GMT +* expire date: Aug 18 10:17:24 2042 GMT +* subjectAltName: host "admin.apisix.dev" matched cert's "admin.apisix.dev" +* issuer: C=cn; ST=GuangDong; L=ZhuHai; CN=ca.apisix.dev; OU=ops +* SSL certificate verify ok. +* Using HTTP2, server supports multiplexing +* Copying HTTP/2 data in stream buffer to connection buffer after upgrade: len=0 +* h2h3 [:method: GET] +* h2h3 [:path: /hello] +* h2h3 [:scheme: https] +* h2h3 [:authority: admin.apisix.dev:9443] +* h2h3 [user-agent: curl/7.87.0] +* h2h3 [accept: */*] +* Using Stream ID: 1 (easy handle 0x13000bc00) +> GET /hello HTTP/2 +> Host: admin.apisix.dev:9443 +> user-agent: curl/7.87.0 +> accept: */* ``` 注意，测试时使用的域名需要符合证书的参数。 @@ -165,41 +181,15 @@ curl --resolve 'mtls.test.com::' "https://