This is an automated email from the ASF dual-hosted git repository.
traky pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 4f9b59aad docs: use shell instead of python to configure ssls
resources (#10773)
4f9b59aad is described below
commit 4f9b59aadb89931cf8c1ca304dba606e1bdc02ce
Author: baiyun <[email protected]>
AuthorDate: Thu Jan 11 06:19:03 2024 +0800
docs: use shell instead of python to configure ssls resources (#10773)
---
docs/en/latest/mtls.md | 145 +++++++++++++++++++++++-------------------------
docs/zh/latest/mtls.md | 146 +++++++++++++++++++++++--------------------------
2 files changed, 136 insertions(+), 155 deletions(-)
diff --git a/docs/en/latest/mtls.md b/docs/en/latest/mtls.md
index 25a174730..02e5e4b45 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:<APISIX_HTTPS_PORT>:<APISIX_URL>'
"https://<APISIX_URL>:<APISIX_HTTPS_PORT>/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 c96f48f2a..ad098c460 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:<APISIX_HTTPS_PORT>:<APISIX_URL>'
"https://<APISIX_URL>:<APISIX_HTTPS_PORT>/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:<APISIX_HTTPS_PORT>:<APISIX_URL>' "https://<APISIX
该功能需要 APISIX 运行在 [APISIX-Runtime](./FAQ.md#如何构建-apisix-runtime-环境) 上。
-下面是一个与配置 SSL 时相似的 Python 脚本，可为一个已存在的 upstream 资源配置双向认证。如果需要，可修改 API 地址和 API
Key。
-
-```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)
-```
+下面是一个与配置 SSL 时相似的 shell 脚本，可为一个已存在的 upstream 资源配置双向认证。
-为 ID 为 `testmtls` 的 upstream 配置双向认证：
-
-```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)"'"
+ }
+}'
```
