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 2022/02/23 09:00:47 UTC
[GitHub] [apisix-website] yzeng25 opened a new pull request #900: docs: add csrf blog
yzeng25 opened a new pull request #900:
URL: https://github.com/apache/apisix-website/pull/900
Fixes: #[Add issue number here]
Changes:
Add the blog for CSRF plugin.
--
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.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] netlify[bot] edited a comment on pull request #900: docs: add csrf blog
Posted by GitBox <gi...@apache.org>.
netlify[bot] edited a comment on pull request #900:
URL: https://github.com/apache/apisix-website/pull/900#issuecomment-1048567476
✔️ Deploy Preview for *apache-apisix* ready!
🔨 Explore the source changes: 6c0cff3e9eab9dd150712895f032f4c1fedeaabd
🔍 Inspect the deploy log: [https://app.netlify.com/sites/apache-apisix/deploys/6216084ac3b7910007477175](https://app.netlify.com/sites/apache-apisix/deploys/6216084ac3b7910007477175)
😎 Browse the preview: [https://deploy-preview-900--apache-apisix.netlify.app](https://deploy-preview-900--apache-apisix.netlify.app)
--
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.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] hf400159 commented on a change in pull request #900: docs: add csrf blog
Posted by GitBox <gi...@apache.org>.
hf400159 commented on a change in pull request #900:
URL: https://github.com/apache/apisix-website/pull/900#discussion_r812702576
##########
File path: website/i18n/zh/docusaurus-plugin-content-blog/2022/02/23/csrf.md
##########
@@ -0,0 +1,144 @@
+---
+title: "如何使用 Apache APISIX CSRF 安全插件拦截跨站点伪造攻击"
+authors:
+ - name: "暴渊"
+ title: "Author"
+ url: "https://github.com/Baoyuantop"
+ image_url: "https://github.com/Baoyuantop.png"
+ - name: "曾奕霖"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://github.com/yzeng25.png"
+keywords:
+- Apache APISIX
+- API 安全
+- 伪造跨站点请求
+- 跨站点请求攻击
+description: 本文介绍了 Apache APISIX 的 CSRF 安全插件 `csrf`，并详细说明如何在 Apache APISIX 中借助 `csrf` 插件来保护您的 API 信息安全。
+tags: [Technology,Ecosystem]
+---
+
+> 本文介绍了 Apache APISIX 的 CSRF 安全插件 `csrf`，并详细说明如何在 Apache APISIX 中借助 `csrf` 插件来保护您的 API 信息安全。
+
+<!--truncate-->
+
+CSRF（Cross-Site Request Forgery），即跨站点请求伪造。发起跨站点请求伪造攻击的关键点在于让目标服务器无法分辨众多请求的来源是真实用户还是攻击者。攻击的一般流程为：首先攻击者会诱导用户导航至攻击者提供的网页上。该网页包含一个自动发送到目标服务器的请求。然后该网页正常加载，这个请求就会自动发送至服务器。在服务器看来，这个请求和用户正常发送的请求一模一样，殊不知这是由攻击者发起，而用户却毫不知情。由于该请求携带了用户的一些凭据，攻击者通过解析这些凭据，就可以获取用户信息，进而产生安全风险。
+
+本文介绍了 Apache APISIX 的 CSRF 安全插件 `csrf`，并详细说明如何在 Apache APISIX 中借助 `csrf` 插件来保护您的 API 信息安全。
+
+## 插件介绍
+
+`csrf` 插件基于 `Double Submit Cookie` 方案实现。根据 [RFC 7231#section-4.2.1](https://datatracker.ietf.org/doc/html/rfc7231.html#section-4.2.1) 的定义，我们把 `GET`、`HEAD` 和 `OPTIONS` 这三种方法称为安全方法。按照这一约定，`csrf` 插件会直接放行这三种方法，但会对其他的方法做检查并拦截其中的不安全请求。
+
+为了抵御 CSRF 攻击，我们需要制造一个无法伪造的令牌或标识符，并且保证这个不会与攻击者的请求一起发送。用户需要将 `csrf` 插件依赖的 token 携带在请求头，token 使用密钥进行签名计算。这样就保证了 token 无法被他人伪造，从而保证了 API 的安全。
+
+
+
+在路由中开启 `csrf` 插件后，访问该路由的所有请求响应中都会包含携带了 `csrf token` 的 Cookie。
+
+用户需要在对该路由的不安全请求中携带这一 Cookie，并在请求头添加额外的字段携带 Cookie 的内容。字段为插件配置中的 `name` 值，这样的请求才能通过 CSRF 插件的校验。
+
+用户在插件的配置中提供一个随机密钥，插件使用该密钥对 token 信息进行 sha256 哈希加密，然后生成 CSRF token，从而保证该 token 不可伪造。
+
+## 如何使用
+
+### 配置开启 CSRF 插件的路由
+
+在 APISIX 中使用 Admin API 创建一条路由并启用 `csrf` 插件：
+
+```shell
+curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/hello",
+ "plugins": {
+ "csrf": {
+ "key": "edd1c9f034335f136f87ad84b625c8f1"
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:9001": 1
+ }
+ }
+}'
+```
+
+其中对于插件有三个配置项：
+
+- `key`：必填项，随机秘钥的值。用户需要提供一个随机密钥。
+- `expires`：选填项，随机秘钥的过期时间，默认值为 7200 秒。由于 CSRF token 使用 Cookie 下发至客户端，该配置会被放置在 Cookie 的配置中，从而控制 Cookie 的过期时间。另外在插件内部也会计算时间来判断 token 是否过期。
+- `name`：选填项， CSRF token 的名称，默认值为 `apisix-csrf-token`。
+
+### 发送请求测试
+
+首先使用 `POST` 请求访问该路由：
+
+```shell
+curl -i http://127.0.0.1:9080/hello -X POST
+```
+
+Apache APISIX 会拦截该请求并返回 `401` 错误。在返回的头部中会发现设置了一个 Cookie，如果没有配置插件的 `name` 字段的话，Cookie 内部应该为默认值 `apisix-csrf-token=....` 。这就是 CSRF 插件生成的 CSRF token。在请求中，需要确保请求携带该 Cookie 并且在请求头写入该 token。
+
+```shell
+HTTP/1.1 401 Unauthorized
+Set-Cookie: apisix-csrf-token=eyJyYW5kb20iOjAuNjg4OTcyMzA4ODM1NDMsImV4cGlyZXMiOjcyMDAsInNpZ24iOiJcL09uZEF4WUZDZGYwSnBiNDlKREtnbzVoYkJjbzhkS0JRZXVDQm44MG9ldz0ifQ==;path=/;Expires=Mon, 13-Dec-21 09:33:55 GMT
+{"error_msg":"no csrf token in headers"}
+```
+
+客户端使用 JavaScript 示例：使用 `js-cookie` 读取 Cookie 并使用 `axios` 发送请求。
+
+```js
+const token = Cookie.get('apisix-csrf-token');
+
+const instance = axios.create({
+ headers: {'apisix-csrf-token': token}
+});
+```
+
+如果 Cookie 中的 token 和请求头中的 token 不一致，请求会被 `csrf` 插件拦截，示例如下：
+
+```shell
+curl -i http://127.0.0.1:9080/hello -X POST -H 'apisix-csrf-token: differenteyJyYW5kb20iOjAuNjg4OTcyMzA4ODM1NDMsImV4cGlyZXMiOjcyMDAsInNpZ24iOiJcL09uZEF4WUZDZGYwSnBiNDlKREtnbzVoYkJjbzhkS0JRZXVDQm44MG9ldz0ifQ==' -b 'apisix-csrf-token=eyJyYW5kb20iOjAuNjg4OTcyMzA4ODM1NDMsImV4cGlyZXMiOjcyMDAsInNpZ24iOiJcL09uZEF4WUZDZGYwSnBiNDlKREtnbzVoYkJjbzhkS0JRZXVDQm44MG9ldz0ifQ=='
+```
+
+```shell
+HTTP/1.1 401 Unauthorized
+Set-Cookie: apisix-csrf-token=eyJyYW5kb20iOjAuNjg4OTcyMzA4ODM1NDMsImV4cGlyZXMiOjcyMDAsInNpZ24iOiJcL09uZEF4WUZDZGYwSnBiNDlKREtnbzVoYkJjbzhkS0JRZXVDQm44MG9ldz0ifQ==;path=/;Expires=Mon, 13-Dec-21 09:33:55 GMT
Review comment:
```suggestion
Set-Cookie: apisix-csrf-token= ${apisix-csrf-token};path=/;Expires=Mon, 13-Dec-21 09:33:55 GMT
```
##########
File path: website/i18n/zh/docusaurus-plugin-content-blog/2022/02/23/csrf.md
##########
@@ -0,0 +1,144 @@
+---
+title: "如何使用 Apache APISIX CSRF 安全插件拦截跨站点伪造攻击"
+authors:
+ - name: "暴渊"
+ title: "Author"
+ url: "https://github.com/Baoyuantop"
+ image_url: "https://github.com/Baoyuantop.png"
+ - name: "曾奕霖"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://github.com/yzeng25.png"
+keywords:
+- Apache APISIX
+- API 安全
+- 伪造跨站点请求
+- 跨站点请求攻击
+description: 本文介绍了 Apache APISIX 的 CSRF 安全插件 `csrf`，并详细说明如何在 Apache APISIX 中借助 `csrf` 插件来保护您的 API 信息安全。
+tags: [Technology,Ecosystem]
+---
+
+> 本文介绍了 Apache APISIX 的 CSRF 安全插件 `csrf`，并详细说明如何在 Apache APISIX 中借助 `csrf` 插件来保护您的 API 信息安全。
+
+<!--truncate-->
+
+CSRF（Cross-Site Request Forgery），即跨站点请求伪造。发起跨站点请求伪造攻击的关键点在于让目标服务器无法分辨众多请求的来源是真实用户还是攻击者。攻击的一般流程为：首先攻击者会诱导用户导航至攻击者提供的网页上。该网页包含一个自动发送到目标服务器的请求。然后该网页正常加载，这个请求就会自动发送至服务器。在服务器看来，这个请求和用户正常发送的请求一模一样，殊不知这是由攻击者发起，而用户却毫不知情。由于该请求携带了用户的一些凭据，攻击者通过解析这些凭据，就可以获取用户信息，进而产生安全风险。
+
+本文介绍了 Apache APISIX 的 CSRF 安全插件 `csrf`，并详细说明如何在 Apache APISIX 中借助 `csrf` 插件来保护您的 API 信息安全。
+
+## 插件介绍
+
+`csrf` 插件基于 `Double Submit Cookie` 方案实现。根据 [RFC 7231#section-4.2.1](https://datatracker.ietf.org/doc/html/rfc7231.html#section-4.2.1) 的定义，我们把 `GET`、`HEAD` 和 `OPTIONS` 这三种方法称为安全方法。按照这一约定，`csrf` 插件会直接放行这三种方法，但会对其他的方法做检查并拦截其中的不安全请求。
+
+为了抵御 CSRF 攻击，我们需要制造一个无法伪造的令牌或标识符，并且保证这个不会与攻击者的请求一起发送。用户需要将 `csrf` 插件依赖的 token 携带在请求头，token 使用密钥进行签名计算。这样就保证了 token 无法被他人伪造，从而保证了 API 的安全。
+
+
+
+在路由中开启 `csrf` 插件后，访问该路由的所有请求响应中都会包含携带了 `csrf token` 的 Cookie。
+
+用户需要在对该路由的不安全请求中携带这一 Cookie，并在请求头添加额外的字段携带 Cookie 的内容。字段为插件配置中的 `name` 值，这样的请求才能通过 CSRF 插件的校验。
+
+用户在插件的配置中提供一个随机密钥，插件使用该密钥对 token 信息进行 sha256 哈希加密，然后生成 CSRF token，从而保证该 token 不可伪造。
+
+## 如何使用
+
+### 配置开启 CSRF 插件的路由
+
+在 APISIX 中使用 Admin API 创建一条路由并启用 `csrf` 插件：
+
+```shell
+curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/hello",
+ "plugins": {
+ "csrf": {
+ "key": "edd1c9f034335f136f87ad84b625c8f1"
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:9001": 1
+ }
+ }
+}'
+```
+
+其中对于插件有三个配置项：
+
+- `key`：必填项，随机秘钥的值。用户需要提供一个随机密钥。
+- `expires`：选填项，随机秘钥的过期时间，默认值为 7200 秒。由于 CSRF token 使用 Cookie 下发至客户端，该配置会被放置在 Cookie 的配置中，从而控制 Cookie 的过期时间。另外在插件内部也会计算时间来判断 token 是否过期。
+- `name`：选填项， CSRF token 的名称，默认值为 `apisix-csrf-token`。
+
+### 发送请求测试
+
+首先使用 `POST` 请求访问该路由：
+
+```shell
+curl -i http://127.0.0.1:9080/hello -X POST
+```
+
+Apache APISIX 会拦截该请求并返回 `401` 错误。在返回的头部中会发现设置了一个 Cookie，如果没有配置插件的 `name` 字段的话，Cookie 内部应该为默认值 `apisix-csrf-token=....` 。这就是 CSRF 插件生成的 CSRF token。在请求中，需要确保请求携带该 Cookie 并且在请求头写入该 token。
+
+```shell
+HTTP/1.1 401 Unauthorized
+Set-Cookie: apisix-csrf-token=eyJyYW5kb20iOjAuNjg4OTcyMzA4ODM1NDMsImV4cGlyZXMiOjcyMDAsInNpZ24iOiJcL09uZEF4WUZDZGYwSnBiNDlKREtnbzVoYkJjbzhkS0JRZXVDQm44MG9ldz0ifQ==;path=/;Expires=Mon, 13-Dec-21 09:33:55 GMT
Review comment:
The token in the code is too long, it is suggested that the code formatting, or use other words to indicate what this code means.
##########
File path: website/i18n/zh/docusaurus-plugin-content-blog/2022/02/23/csrf.md
##########
@@ -0,0 +1,144 @@
+---
+title: "如何使用 Apache APISIX CSRF 安全插件拦截跨站点伪造攻击"
+authors:
+ - name: "暴渊"
+ title: "Author"
+ url: "https://github.com/Baoyuantop"
+ image_url: "https://github.com/Baoyuantop.png"
+ - name: "曾奕霖"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://github.com/yzeng25.png"
+keywords:
+- Apache APISIX
+- API 安全
+- 伪造跨站点请求
+- 跨站点请求攻击
+description: 本文介绍了 Apache APISIX 的 CSRF 安全插件 `csrf`，并详细说明如何在 Apache APISIX 中借助 `csrf` 插件来保护您的 API 信息安全。
+tags: [Technology,Ecosystem]
+---
+
+> 本文介绍了 Apache APISIX 的 CSRF 安全插件 `csrf`，并详细说明如何在 Apache APISIX 中借助 `csrf` 插件来保护您的 API 信息安全。
+
+<!--truncate-->
+
+CSRF（Cross-Site Request Forgery），即跨站点请求伪造。发起跨站点请求伪造攻击的关键点在于让目标服务器无法分辨众多请求的来源是真实用户还是攻击者。攻击的一般流程为：首先攻击者会诱导用户导航至攻击者提供的网页上。该网页包含一个自动发送到目标服务器的请求。然后该网页正常加载，这个请求就会自动发送至服务器。在服务器看来，这个请求和用户正常发送的请求一模一样，殊不知这是由攻击者发起，而用户却毫不知情。由于该请求携带了用户的一些凭据，攻击者通过解析这些凭据，就可以获取用户信息，进而产生安全风险。
+
+本文介绍了 Apache APISIX 的 CSRF 安全插件 `csrf`，并详细说明如何在 Apache APISIX 中借助 `csrf` 插件来保护您的 API 信息安全。
+
+## 插件介绍
+
+`csrf` 插件基于 `Double Submit Cookie` 方案实现。根据 [RFC 7231#section-4.2.1](https://datatracker.ietf.org/doc/html/rfc7231.html#section-4.2.1) 的定义，我们把 `GET`、`HEAD` 和 `OPTIONS` 这三种方法称为安全方法。按照这一约定，`csrf` 插件会直接放行这三种方法，但会对其他的方法做检查并拦截其中的不安全请求。
+
+为了抵御 CSRF 攻击，我们需要制造一个无法伪造的令牌或标识符，并且保证这个不会与攻击者的请求一起发送。用户需要将 `csrf` 插件依赖的 token 携带在请求头，token 使用密钥进行签名计算。这样就保证了 token 无法被他人伪造，从而保证了 API 的安全。
+
+
+
+在路由中开启 `csrf` 插件后，访问该路由的所有请求响应中都会包含携带了 `csrf token` 的 Cookie。
+
+用户需要在对该路由的不安全请求中携带这一 Cookie，并在请求头添加额外的字段携带 Cookie 的内容。字段为插件配置中的 `name` 值，这样的请求才能通过 CSRF 插件的校验。
+
+用户在插件的配置中提供一个随机密钥，插件使用该密钥对 token 信息进行 sha256 哈希加密，然后生成 CSRF token，从而保证该 token 不可伪造。
+
+## 如何使用
+
+### 配置开启 CSRF 插件的路由
+
+在 APISIX 中使用 Admin API 创建一条路由并启用 `csrf` 插件：
+
+```shell
+curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/hello",
+ "plugins": {
+ "csrf": {
+ "key": "edd1c9f034335f136f87ad84b625c8f1"
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:9001": 1
+ }
+ }
+}'
+```
+
+其中对于插件有三个配置项：
+
+- `key`：必填项，随机秘钥的值。用户需要提供一个随机密钥。
+- `expires`：选填项，随机秘钥的过期时间，默认值为 7200 秒。由于 CSRF token 使用 Cookie 下发至客户端，该配置会被放置在 Cookie 的配置中，从而控制 Cookie 的过期时间。另外在插件内部也会计算时间来判断 token 是否过期。
+- `name`：选填项， CSRF token 的名称，默认值为 `apisix-csrf-token`。
+
+### 发送请求测试
+
+首先使用 `POST` 请求访问该路由：
+
+```shell
+curl -i http://127.0.0.1:9080/hello -X POST
+```
+
+Apache APISIX 会拦截该请求并返回 `401` 错误。在返回的头部中会发现设置了一个 Cookie，如果没有配置插件的 `name` 字段的话，Cookie 内部应该为默认值 `apisix-csrf-token=....` 。这就是 CSRF 插件生成的 CSRF token。在请求中，需要确保请求携带该 Cookie 并且在请求头写入该 token。
+
+```shell
+HTTP/1.1 401 Unauthorized
+Set-Cookie: apisix-csrf-token=eyJyYW5kb20iOjAuNjg4OTcyMzA4ODM1NDMsImV4cGlyZXMiOjcyMDAsInNpZ24iOiJcL09uZEF4WUZDZGYwSnBiNDlKREtnbzVoYkJjbzhkS0JRZXVDQm44MG9ldz0ifQ==;path=/;Expires=Mon, 13-Dec-21 09:33:55 GMT
+{"error_msg":"no csrf token in headers"}
+```
+
+客户端使用 JavaScript 示例：使用 `js-cookie` 读取 Cookie 并使用 `axios` 发送请求。
+
+```js
+const token = Cookie.get('apisix-csrf-token');
+
+const instance = axios.create({
+ headers: {'apisix-csrf-token': token}
+});
+```
+
+如果 Cookie 中的 token 和请求头中的 token 不一致，请求会被 `csrf` 插件拦截，示例如下：
+
+```shell
+curl -i http://127.0.0.1:9080/hello -X POST -H 'apisix-csrf-token: differenteyJyYW5kb20iOjAuNjg4OTcyMzA4ODM1NDMsImV4cGlyZXMiOjcyMDAsInNpZ24iOiJcL09uZEF4WUZDZGYwSnBiNDlKREtnbzVoYkJjbzhkS0JRZXVDQm44MG9ldz0ifQ==' -b 'apisix-csrf-token=eyJyYW5kb20iOjAuNjg4OTcyMzA4ODM1NDMsImV4cGlyZXMiOjcyMDAsInNpZ24iOiJcL09uZEF4WUZDZGYwSnBiNDlKREtnbzVoYkJjbzhkS0JRZXVDQm44MG9ldz0ifQ=='
+```
+
+```shell
+HTTP/1.1 401 Unauthorized
+Set-Cookie: apisix-csrf-token=eyJyYW5kb20iOjAuNjg4OTcyMzA4ODM1NDMsImV4cGlyZXMiOjcyMDAsInNpZ24iOiJcL09uZEF4WUZDZGYwSnBiNDlKREtnbzVoYkJjbzhkS0JRZXVDQm44MG9ldz0ifQ==;path=/;Expires=Mon, 13-Dec-21 09:33:55 GMT
+{"error_msg":"csrf token mismatch"}
+```
+
+最后使用 `curl`验证正常的访问：
+
+```shell
+curl -i http://127.0.0.1:9080/hello -X POST -H 'apisix-csrf-token: eyJyYW5kb20iOjAuNjg4OTcyMzA4ODM1NDMsImV4cGlyZXMiOjcyMDAsInNpZ24iOiJcL09uZEF4WUZDZGYwSnBiNDlKREtnbzVoYkJjbzhkS0JRZXVDQm44MG9ldz0ifQ==' -b 'apisix-csrf-token=eyJyYW5kb20iOjAuNjg4OTcyMzA4ODM1NDMsImV4cGlyZXMiOjcyMDAsInNpZ24iOiJcL09uZEF4WUZDZGYwSnBiNDlKREtnbzVoYkJjbzhkS0JRZXVDQm44MG9ldz0ifQ=='
Review comment:
ditto
##########
File path: website/blog/2022/02/23/csrf.md
##########
@@ -0,0 +1,144 @@
+---
+title: "Apache APISIX Enhances API Security by CSRF Plugin"
+authors:
+ - name: "Yuan Bao"
+ title: "Author"
+ url: "https://github.com/Baoyuantop"
+ image_url: "https://github.com/Baoyuantop.png"
+ - name: "Yilin Zeng"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://github.com/yzeng25.png"
+keywords:
+- Apache APISIX
+- API Security
+- cross-site request forgery
+- CSRF Attack
+description: This article introduces `csrf`, the CSRF security plugin for Apache APISIX, and details how to secure your API information in Apache APISIX with the help of the `csrf` plugin.
+tags: [Technology,Ecosystem]
+---
+
+> This article introduces `csrf`, the CSRF security plugin for Apache APISIX, and details how to secure your API information in Apache APISIX with the help of the `csrf` plugin.
+
+<!--truncate-->
+
+The key point of launching a cross-site request forgery attack is to make the target server unable to distinguish whether the source of many requests is a real user or an attacker. The general flow of the attack is that first the attacker will lure the user to navigate to a web page provided by the attacker. This page contains a request that is automatically sent to the target server. The page then loads normally and the request is automatically sent to the server. It appears to the server that the request is exactly the same as the request normally sent by the user, unaware that it was initiated by the attacker without the user's knowledge. Since the request carries some of the user's credentials, the attacker can get access to the user's information by parsing these credentials, thus creating a security risk.
+
+This article introduces `csrf`, the CSRF security plugin for Apache APISIX, and details how to secure your API information in Apache APISIX with the help of the `csrf` plugin.
+
+## Plugin Introduction
+
+The `csrf` plugin is implemented based on the `Double Submit Cookie` scheme. As defined in [RFC 7231#section-4.2.1](https://datatracker.ietf.org/doc/html/rfc7231.html#section-4.2.1), we consider the `GET`, `HEAD` and `OPTIONS` methods as **secure methods**. According to this convention, the `csrf` plug-in will let these three methods go directly, but will check the other methods and intercept any unsafe requests.
+
+To defend against CSRF attacks, we need to create a token or identifier that cannot be forged and ensure that this is not sent with the attacker's request. The user needs to carry the token that the `csrf` plugin relies on in the request header, and the token is computed using a key for signing. This ensures that the token cannot be forged by others, thus securing the API.
+
+
+
+When the `csrf` plugin is enabled in a route, all request responses to that route will contain a Cookie carrying a `csrf token`.
+
+The user needs to carry this Cookie in an unsecured request to the route and add an additional field in the request header to carry the contents of the Cookie. The field is the `name` value in the plugin's configuration so that the request passes the CSRF plugin's checks.
+
+The user provides a random key in the plugin's configuration, which is used by the plugin to encrypt the token information with a sha256 hash and generate a CSRF token, thus ensuring that the token cannot be forged.
+
+## How to Use the Plugin
+
+### Enable CSRF Plugin in a Route
+
+Create a route in APISIX using the Admin API and enable the csrf plugin.
+
+```shell
+curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/hello",
+ "plugins": {
+ "csrf": {
+ "key": "edd1c9f034335f136f87ad84b625c8f1"
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:9001": 1
+ }
+ }
+}'
+```
+
+There are three configuration parameters for the plugin.
+
+- `key`: Required field, the value of the random secret key. The user needs to provide a random key.
+- `expires`: Optional, the expiration time of the random secret key, the default value is 7200 seconds. Since the CSRF token is sent to the client using a Cookie, this configuration is placed in the Cookie's configuration to control the Cookie's expiration time. In addition, the plugin will also calculate the time to determine whether the token expires.
+- `name`: Optional, the name of the CSRF token, the default value is `apisix-csrf-token`.
+
+### Send a Request
+
+The route is first accessed using a `POST` request.
+
+```shell
+curl -i http://127.0.0.1:9080/hello -X POST
+```
+
+Apache APISIX will intercept the request and return a `401` error. In the returned header you will find a Cookie set, which should be the default value `apisix-csrf-token=....` inside the Cookie if the name field of the plugin is not configured . This is the CSRF token generated by the CSRF plugin. In the request, you need to make sure that the request carries this Cookie and that the token is written in the request header.
+
+```shell
+HTTP/1.1 401 Unauthorized
+Set-Cookie: apisix-csrf-token=eyJyYW5kb20iOjAuNjg4OTcyMzA4ODM1NDMsImV4cGlyZXMiOjcyMDAsInNpZ24iOiJcL09uZEF4WUZDZGYwSnBiNDlKREtnbzVoYkJjbzhkS0JRZXVDQm44MG9ldz0ifQ==;path=/;Expires=Mon, 13-Dec-21 09:33:55 GMT
Review comment:
Please refer to Chinese for modification.
##########
File path: website/i18n/zh/docusaurus-plugin-content-blog/2022/02/23/csrf.md
##########
@@ -0,0 +1,144 @@
+---
+title: "如何使用 Apache APISIX CSRF 安全插件拦截跨站点伪造攻击"
+authors:
+ - name: "暴渊"
+ title: "Author"
+ url: "https://github.com/Baoyuantop"
+ image_url: "https://github.com/Baoyuantop.png"
+ - name: "曾奕霖"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://github.com/yzeng25.png"
+keywords:
+- Apache APISIX
+- API 安全
+- 伪造跨站点请求
+- 跨站点请求攻击
+description: 本文介绍了 Apache APISIX 的 CSRF 安全插件 `csrf`，并详细说明如何在 Apache APISIX 中借助 `csrf` 插件来保护您的 API 信息安全。
+tags: [Technology,Ecosystem]
+---
+
+> 本文介绍了 Apache APISIX 的 CSRF 安全插件 `csrf`，并详细说明如何在 Apache APISIX 中借助 `csrf` 插件来保护您的 API 信息安全。
+
+<!--truncate-->
+
+CSRF（Cross-Site Request Forgery），即跨站点请求伪造。发起跨站点请求伪造攻击的关键点在于让目标服务器无法分辨众多请求的来源是真实用户还是攻击者。攻击的一般流程为：首先攻击者会诱导用户导航至攻击者提供的网页上。该网页包含一个自动发送到目标服务器的请求。然后该网页正常加载，这个请求就会自动发送至服务器。在服务器看来，这个请求和用户正常发送的请求一模一样，殊不知这是由攻击者发起，而用户却毫不知情。由于该请求携带了用户的一些凭据，攻击者通过解析这些凭据，就可以获取用户信息，进而产生安全风险。
+
+本文介绍了 Apache APISIX 的 CSRF 安全插件 `csrf`，并详细说明如何在 Apache APISIX 中借助 `csrf` 插件来保护您的 API 信息安全。
+
+## 插件介绍
+
+`csrf` 插件基于 `Double Submit Cookie` 方案实现。根据 [RFC 7231#section-4.2.1](https://datatracker.ietf.org/doc/html/rfc7231.html#section-4.2.1) 的定义，我们把 `GET`、`HEAD` 和 `OPTIONS` 这三种方法称为安全方法。按照这一约定，`csrf` 插件会直接放行这三种方法，但会对其他的方法做检查并拦截其中的不安全请求。
+
+为了抵御 CSRF 攻击，我们需要制造一个无法伪造的令牌或标识符，并且保证这个不会与攻击者的请求一起发送。用户需要将 `csrf` 插件依赖的 token 携带在请求头，token 使用密钥进行签名计算。这样就保证了 token 无法被他人伪造，从而保证了 API 的安全。
+
+
+
+在路由中开启 `csrf` 插件后，访问该路由的所有请求响应中都会包含携带了 `csrf token` 的 Cookie。
+
+用户需要在对该路由的不安全请求中携带这一 Cookie，并在请求头添加额外的字段携带 Cookie 的内容。字段为插件配置中的 `name` 值，这样的请求才能通过 CSRF 插件的校验。
+
+用户在插件的配置中提供一个随机密钥，插件使用该密钥对 token 信息进行 sha256 哈希加密，然后生成 CSRF token，从而保证该 token 不可伪造。
+
+## 如何使用
+
+### 配置开启 CSRF 插件的路由
+
+在 APISIX 中使用 Admin API 创建一条路由并启用 `csrf` 插件：
+
+```shell
+curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/hello",
+ "plugins": {
+ "csrf": {
+ "key": "edd1c9f034335f136f87ad84b625c8f1"
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:9001": 1
+ }
+ }
+}'
+```
+
+其中对于插件有三个配置项：
+
+- `key`：必填项，随机秘钥的值。用户需要提供一个随机密钥。
+- `expires`：选填项，随机秘钥的过期时间，默认值为 7200 秒。由于 CSRF token 使用 Cookie 下发至客户端，该配置会被放置在 Cookie 的配置中，从而控制 Cookie 的过期时间。另外在插件内部也会计算时间来判断 token 是否过期。
+- `name`：选填项， CSRF token 的名称，默认值为 `apisix-csrf-token`。
+
+### 发送请求测试
+
+首先使用 `POST` 请求访问该路由：
+
+```shell
+curl -i http://127.0.0.1:9080/hello -X POST
+```
+
+Apache APISIX 会拦截该请求并返回 `401` 错误。在返回的头部中会发现设置了一个 Cookie，如果没有配置插件的 `name` 字段的话，Cookie 内部应该为默认值 `apisix-csrf-token=....` 。这就是 CSRF 插件生成的 CSRF token。在请求中，需要确保请求携带该 Cookie 并且在请求头写入该 token。
+
+```shell
+HTTP/1.1 401 Unauthorized
+Set-Cookie: apisix-csrf-token=eyJyYW5kb20iOjAuNjg4OTcyMzA4ODM1NDMsImV4cGlyZXMiOjcyMDAsInNpZ24iOiJcL09uZEF4WUZDZGYwSnBiNDlKREtnbzVoYkJjbzhkS0JRZXVDQm44MG9ldz0ifQ==;path=/;Expires=Mon, 13-Dec-21 09:33:55 GMT
+{"error_msg":"no csrf token in headers"}
+```
+
+客户端使用 JavaScript 示例：使用 `js-cookie` 读取 Cookie 并使用 `axios` 发送请求。
+
+```js
+const token = Cookie.get('apisix-csrf-token');
+
+const instance = axios.create({
+ headers: {'apisix-csrf-token': token}
+});
+```
+
+如果 Cookie 中的 token 和请求头中的 token 不一致，请求会被 `csrf` 插件拦截，示例如下：
+
+```shell
+curl -i http://127.0.0.1:9080/hello -X POST -H 'apisix-csrf-token: differenteyJyYW5kb20iOjAuNjg4OTcyMzA4ODM1NDMsImV4cGlyZXMiOjcyMDAsInNpZ24iOiJcL09uZEF4WUZDZGYwSnBiNDlKREtnbzVoYkJjbzhkS0JRZXVDQm44MG9ldz0ifQ==' -b 'apisix-csrf-token=eyJyYW5kb20iOjAuNjg4OTcyMzA4ODM1NDMsImV4cGlyZXMiOjcyMDAsInNpZ24iOiJcL09uZEF4WUZDZGYwSnBiNDlKREtnbzVoYkJjbzhkS0JRZXVDQm44MG9ldz0ifQ=='
Review comment:
```suggestion
curl -i http://127.0.0.1:9080/hello -X POST -H 'apisix-csrf-token: ${apisix-csrf-token}' -b 'apisix-csrf-token= ${apisix-csrf-token}'
```
##########
File path: website/i18n/zh/docusaurus-plugin-content-blog/2022/02/23/csrf.md
##########
@@ -0,0 +1,144 @@
+---
+title: "如何使用 Apache APISIX CSRF 安全插件拦截跨站点伪造攻击"
+authors:
+ - name: "暴渊"
+ title: "Author"
+ url: "https://github.com/Baoyuantop"
+ image_url: "https://github.com/Baoyuantop.png"
+ - name: "曾奕霖"
+ title: "Technical Writer"
+ url: "https://github.com/yzeng25"
+ image_url: "https://github.com/yzeng25.png"
+keywords:
+- Apache APISIX
+- API 安全
+- 伪造跨站点请求
+- 跨站点请求攻击
+description: 本文介绍了 Apache APISIX 的 CSRF 安全插件 `csrf`，并详细说明如何在 Apache APISIX 中借助 `csrf` 插件来保护您的 API 信息安全。
+tags: [Technology,Ecosystem]
+---
+
+> 本文介绍了 Apache APISIX 的 CSRF 安全插件 `csrf`，并详细说明如何在 Apache APISIX 中借助 `csrf` 插件来保护您的 API 信息安全。
+
+<!--truncate-->
+
+CSRF（Cross-Site Request Forgery），即跨站点请求伪造。发起跨站点请求伪造攻击的关键点在于让目标服务器无法分辨众多请求的来源是真实用户还是攻击者。攻击的一般流程为：首先攻击者会诱导用户导航至攻击者提供的网页上。该网页包含一个自动发送到目标服务器的请求。然后该网页正常加载，这个请求就会自动发送至服务器。在服务器看来，这个请求和用户正常发送的请求一模一样，殊不知这是由攻击者发起，而用户却毫不知情。由于该请求携带了用户的一些凭据，攻击者通过解析这些凭据，就可以获取用户信息，进而产生安全风险。
+
+本文介绍了 Apache APISIX 的 CSRF 安全插件 `csrf`，并详细说明如何在 Apache APISIX 中借助 `csrf` 插件来保护您的 API 信息安全。
+
+## 插件介绍
+
+`csrf` 插件基于 `Double Submit Cookie` 方案实现。根据 [RFC 7231#section-4.2.1](https://datatracker.ietf.org/doc/html/rfc7231.html#section-4.2.1) 的定义，我们把 `GET`、`HEAD` 和 `OPTIONS` 这三种方法称为安全方法。按照这一约定，`csrf` 插件会直接放行这三种方法，但会对其他的方法做检查并拦截其中的不安全请求。
+
+为了抵御 CSRF 攻击，我们需要制造一个无法伪造的令牌或标识符，并且保证这个不会与攻击者的请求一起发送。用户需要将 `csrf` 插件依赖的 token 携带在请求头，token 使用密钥进行签名计算。这样就保证了 token 无法被他人伪造，从而保证了 API 的安全。
+
+
+
+在路由中开启 `csrf` 插件后，访问该路由的所有请求响应中都会包含携带了 `csrf token` 的 Cookie。
+
+用户需要在对该路由的不安全请求中携带这一 Cookie，并在请求头添加额外的字段携带 Cookie 的内容。字段为插件配置中的 `name` 值，这样的请求才能通过 CSRF 插件的校验。
Review comment:
```suggestion
用户需要在对该路由的不安全请求中携带这一 Cookie，并在请求头添加额外的字段用来携带 Cookie 的内容。字段为插件配置中的 `name` 值，这样的请求才能通过 CSRF 插件的校验。
```
--
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.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] netlify[bot] commented on pull request #900: docs: add csrf blog
Posted by GitBox <gi...@apache.org>.
netlify[bot] commented on pull request #900:
URL: https://github.com/apache/apisix-website/pull/900#issuecomment-1048567476
👷 Deploy Preview for *apache-apisix* processing.
🔨 Explore the source changes: 9b0374dc94a2be35b680c2cee09bb126eb9e2751
🔍 Inspect the deploy log: [https://app.netlify.com/sites/apache-apisix/deploys/6215f7b67162960008cdadaa](https://app.netlify.com/sites/apache-apisix/deploys/6215f7b67162960008cdadaa)
--
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.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] juzhiyuan merged pull request #900: docs: add csrf blog
Posted by GitBox <gi...@apache.org>.
juzhiyuan merged pull request #900:
URL: https://github.com/apache/apisix-website/pull/900
--
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.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] netlify[bot] edited a comment on pull request #900: docs: add csrf blog
Posted by GitBox <gi...@apache.org>.
netlify[bot] edited a comment on pull request #900:
URL: https://github.com/apache/apisix-website/pull/900#issuecomment-1048567476
✔️ Deploy Preview for *apache-apisix* ready!
🔨 Explore the source changes: 9b0374dc94a2be35b680c2cee09bb126eb9e2751
🔍 Inspect the deploy log: [https://app.netlify.com/sites/apache-apisix/deploys/6215f7b67162960008cdadaa](https://app.netlify.com/sites/apache-apisix/deploys/6215f7b67162960008cdadaa)
😎 Browse the preview: [https://deploy-preview-900--apache-apisix.netlify.app](https://deploy-preview-900--apache-apisix.netlify.app)
--
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.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix-website] netlify[bot] edited a comment on pull request #900: docs: add csrf blog
Posted by GitBox <gi...@apache.org>.
netlify[bot] edited a comment on pull request #900:
URL: https://github.com/apache/apisix-website/pull/900#issuecomment-1048567476
👷 Deploy Preview for *apache-apisix* processing.
🔨 Explore the source changes: 6c0cff3e9eab9dd150712895f032f4c1fedeaabd
🔍 Inspect the deploy log: [https://app.netlify.com/sites/apache-apisix/deploys/6216084ac3b7910007477175](https://app.netlify.com/sites/apache-apisix/deploys/6216084ac3b7910007477175)
--
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.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org