This is an automated email from the ASF dual-hosted git repository.
navendu 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 bfc6a1908 docs: add docs for the new ocsp-stapling plugin (#10900)
bfc6a1908 is described below
commit bfc6a1908367bc0e953942f5d9c5797b34cda5a3
Author: yuweizzz <yuwei764969...@gmail.com>
AuthorDate: Tue Feb 20 11:04:08 2024 +0800
docs: add docs for the new ocsp-stapling plugin (#10900)
---
docs/en/latest/config.json | 3 +-
docs/en/latest/plugins/ocsp-stapling.md | 133 +++++++++++++++++++++++++++++++
docs/zh/latest/config.json | 3 +-
docs/zh/latest/plugins/ocsp-stapling.md | 134 ++++++++++++++++++++++++++++++++
4 files changed, 271 insertions(+), 2 deletions(-)
diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json
index fd9a43f2f..824ac8245 100644
--- a/docs/en/latest/config.json
+++ b/docs/en/latest/config.json
@@ -80,7 +80,8 @@
"plugins/ext-plugin-post-req",
"plugins/ext-plugin-post-resp",
"plugins/inspect",
- "plugins/workflow"
+ "plugins/workflow",
+ "plugins/ocsp-stapling"
]
},
{
diff --git a/docs/en/latest/plugins/ocsp-stapling.md
b/docs/en/latest/plugins/ocsp-stapling.md
new file mode 100644
index 000000000..fe85579de
--- /dev/null
+++ b/docs/en/latest/plugins/ocsp-stapling.md
@@ -0,0 +1,133 @@
+---
+title: ocsp-stapling
+keywords:
+ - Apache APISIX
+ - Plugin
+ - ocsp-stapling
+description: This document contains information about the Apache APISIX
ocsp-stapling Plugin.
+---
+
+<!--
+#
+# 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.
+#
+-->
+
+## Description
+
+The `ocsp-stapling` Plugin dynamically sets the behavior of [OCSP
stapling](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_stapling)
in Nginx.
+
+## Enable Plugin
+
+This Plugin is disabled by default. Modify the config file to enable the
plugin:
+
+```yaml title="./conf/config.yaml"
+plugins:
+ - ...
+ - ocsp-stapling
+```
+
+After modifying the config file, reload APISIX or send an hot-loaded HTTP
request through the Admin API to take effect:
+
+```shell
+curl http://127.0.0.1:9180/apisix/admin/plugins/reload -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT
+```
+
+## Attributes
+
+The attributes of this plugin are stored in specific field `ocsp_stapling`
within SSL Resource.
+
+| Name | Type | Required | Default | Valid
values | Description
|
+|----------------|----------------------|----------|---------------|--------------|-----------------------------------------------------------------------------------------------|
+| enabled | boolean | False | false |
| Like the `ssl_stapling` directive, enables or disables OCSP stapling
feature. |
+| skip_verify | boolean | False | false |
| Like the `ssl_stapling_verify` directive, enables or disables verification
of OCSP responses. |
+| cache_ttl | integer | False | 3600 | >= 60
| Specifies the expired time of OCSP response cache.
|
+
+## Example usage
+
+You should create an SSL Resource first, and the certificate of the server
certificate issuer should be known. Normally the fullchain certificate works
fine.
+
+Create an SSL Resource as such:
+
+```shell
+curl http://127.0.0.1:9180/apisix/admin/ssls/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "cert" : "'"$(cat server.crt)"'",
+ "key": "'"$(cat server.key)"'",
+ "snis": ["test.com"],
+ "ocsp_stapling": {
+ "enabled": true
+ }
+}'
+```
+
+Next, establish a secure connection to the server, request the SSL/TLS session
status, and display the output from the server:
+
+```shell
+echo -n "Q" | openssl s_client -status -connect localhost:9443 -servername
test.com 2>&1 | cat
+```
+
+```
+...
+CONNECTED(00000003)
+OCSP response:
+======================================
+OCSP Response Data:
+ OCSP Response Status: successful (0x0)
+...
+```
+
+To disable OCSP stapling feature, you can make a request as shown below:
+
+```shell
+curl http://127.0.0.1:9180/apisix/admin/ssls/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "cert" : "'"$(cat server.crt)"'",
+ "key": "'"$(cat server.key)"'",
+ "snis": ["test.com"],
+ "ocsp_stapling": {
+ "enabled": false
+ }
+}'
+```
+
+## Delete Plugin
+
+Make sure all your SSL Resource doesn't contains `ocsp_stapling` field
anymore. To remove this field, you can make a request as shown below:
+
+```shell
+curl http://127.0.0.1:9180/apisix/admin/ssls/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -d '
+{
+ "ocsp_stapling": null
+}'
+```
+
+Modify the config file `./conf/config.yaml` to disable the plugin:
+
+```yaml title="./conf/config.yaml"
+plugins:
+ - ...
+ # - ocsp-stapling
+```
+
+After modifying the config file, reload APISIX or send an hot-loaded HTTP
request through the Admin API to take effect:
+
+```shell
+curl http://127.0.0.1:9180/apisix/admin/plugins/reload -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT
+```
diff --git a/docs/zh/latest/config.json b/docs/zh/latest/config.json
index ba732d033..6e5ec2404 100644
--- a/docs/zh/latest/config.json
+++ b/docs/zh/latest/config.json
@@ -68,7 +68,8 @@
"plugins/ext-plugin-pre-req",
"plugins/ext-plugin-post-req",
"plugins/ext-plugin-post-resp",
- "plugins/workflow"
+ "plugins/workflow",
+ "plugins/ocsp-stapling"
]
},
{
diff --git a/docs/zh/latest/plugins/ocsp-stapling.md
b/docs/zh/latest/plugins/ocsp-stapling.md
new file mode 100644
index 000000000..d69862e94
--- /dev/null
+++ b/docs/zh/latest/plugins/ocsp-stapling.md
@@ -0,0 +1,134 @@
+---
+title: ocsp-stapling
+keywords:
+ - Apache APISIX
+ - API 网关
+ - 插件
+ - ocsp-stapling
+description: 本文介绍了 API 网关 Apache APISIX ocsp-stapling 插件的相关信息。
+---
+
+<!--
+#
+# 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.
+#
+-->
+
+## 描述
+
+`ocsp-stapling` 插件可以动态地设置 Nginx 中 [OCSP
stapling](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_stapling)
的相关行为。
+
+## 启用插件
+
+这个插件是默认禁用的，通过修改配置文件 `./conf/config.yaml` 来启用它：
+
+```yaml
+plugins:
+ - ...
+ - ocsp-stapling
+```
+
+修改配置文件之后，重启 APISIX 或者通过插件热加载接口来使配置生效：
+
+```shell
+curl http://127.0.0.1:9180/apisix/admin/plugins/reload -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT
+```
+
+## 属性
+
+插件属性存储在 SSL 资源的 `ocsp_stapling` 字段中。
+
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述
|
+|----------------|----------------------|----------|---------------|--------------|-----------------------------------------------------------------------|
+| enabled | boolean | False | false |
| 与 `ssl_stapling` 指令类似，用于启用或禁用 OCSP stapling 特性 |
+| skip_verify | boolean | False | false |
| 与 `ssl_stapling_verify` 指令类似，用于启用或禁用对于 OCSP 响应结果的校验 |
+| cache_ttl | integer | False | 3600 | >= 60
| 指定 OCSP 响应结果的缓存时间 |
+
+## 使用示例
+
+首先您应该创建一个 SSL 资源，并且证书资源中应该包含颁发者的证书。通常情况下，全链路证书就可以正常工作。
+
+如下示例中，生成相关的 SSL 资源：
+
+```shell
+curl http://127.0.0.1:9180/apisix/admin/ssls/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "cert" : "'"$(cat server.crt)"'",
+ "key": "'"$(cat server.key)"'",
+ "snis": ["test.com"],
+ "ocsp_stapling": {
+ "enabled": true
+ }
+}'
+```
+
+通过上述命令生成 SSL 资源后，可以通过以下方法测试：
+
+```shell
+echo -n "Q" | openssl s_client -status -connect localhost:9443 -servername
test.com 2>&1 | cat
+```
+
+```
+...
+CONNECTED(00000003)
+OCSP response:
+======================================
+OCSP Response Data:
+ OCSP Response Status: successful (0x0)
+...
+```
+
+可以通过以下方法禁用插件：
+
+```shell
+curl http://127.0.0.1:9180/apisix/admin/ssls/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "cert" : "'"$(cat server.crt)"'",
+ "key": "'"$(cat server.key)"'",
+ "snis": ["test.com"],
+ "ocsp_stapling": {
+ "enabled": false
+ }
+}'
+```
+
+## 删除插件
+
+在删除插件之前，需要确保所有的 SSL 资源都已经移除 `ocsp_stapling` 字段，可以通过以下命令实现对单个 SSL 资源的对应字段移除：
+
+```shell
+curl http://127.0.0.1:9180/apisix/admin/ssls/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -d '
+{
+ "ocsp_stapling": null
+}'
+```
+
+通过修改配置文件 `./conf/config.yaml` 来禁用它：
+
+```yaml
+plugins:
+ - ...
+ # - ocsp-stapling
+```
+
+修改配置文件之后，重启 APISIX 或者通过插件热加载接口来使配置生效：
+
+```shell
+curl http://127.0.0.1:9180/apisix/admin/plugins/reload -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT
+```
