跳到主要内容
版本:3.20.0

使用密钥环加密数据

数据加密是 APISIX 的一个关键考虑因素。在实施身份认证或与其他系统集成时,网关配置中经常会包含用户密码和私钥等敏感信息。APISIX 可以在存储前加密这些信息,并在网关需要使用时通过已配置的密钥环解密。

APISIX 可以在将以下值保存到 etcd 前对其加密:

  • 当 enable_encrypt_fields 为 true 且已配置密钥环时的敏感插件字段
  • 只要已配置密钥环,就会加密 PEM 格式的 TLS 私钥,包括上游客户端私钥

密钥环必须保留解密现有密文所需的每一个密钥。丢失所需密钥可能导致相关敏感信息无法恢复。

启用数据加密​

默认情况下,APISIX 启用了数据加密,并带有两个默认密钥:

apisix/cli/config.lua
apisix ={
...,
data_encryption = {
enable_encrypt_fields = true,
keyring = { "qeddd145sfvddff3", "edd1c9f0985e76a2" }
},
...
}

enable_encrypt_fields 控制插件 Schema 所列字段的加密。密钥环还会独立加密 PEM 私钥。只要密钥环仍然存在,即使禁用了插件字段加密,APISIX 也会继续加密新写入的 PEM 私钥。

要查看数据加密的效果,请创建一个消费者 JohnDoe:

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"username": "JohnDoe"
}'

为 JohnDoe 配置 key-auth 凭证:

curl "http://127.0.0.1:9180/apisix/admin/consumers/JohnDoe/credentials" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "cred-john-key-auth",
"plugins": {
"key-auth": {
"key": "john-key"
}
}
}'

在此配置中,用户密钥是不应以明文存储的敏感信息。

创建凭证时,你应该会看到一个响应,其中显示了加密后的密钥:

{
"key": "/apisix/consumers/JohnDoe/credentials/cred-john-key-auth",
"value": {
"create_time": 1726300662,
"update_time": 1726300662,
"plugins": {
"key-auth": {
"key": "$ENC$v1$a/TGSySA4i1LGn4ZXlYuew=="
}
},
"id": "cred-john-key-auth"
}
}

为了进一步验证密钥已加密,你还可以检查保存到 etcd 的条目:

etcdctl get /apisix/consumers/JohnDoe/credentials/cred-john-key-auth

你应该看到密钥已加密:

{
"update_time":1726300662,
"create_time":1726300662,
"plugins":{
"key-auth":{
"key":"$ENC$v1$a/TGSySA4i1LGn4ZXlYuew=="
}
},
"id": "cred-john-key-auth"
}

APISIX 会为新加密的插件配置和插件元数据值添加 $ENC$v1$ 前缀。此标记表示其余文本是密文。启用插件字段加密时,APISIX 会在使用或返回带标记的字符串前将其解密。即使当前插件 Schema 的 encrypt_fields 中未列出该字段,也会执行解密。未带标记的存储值仍遵循 Schema 中的 encrypt_fields 定义。

警告

不支持 $ENC$v1$ 的 APISIX 版本会将带标记的整个字符串视为字面值。滚动升级期间,请在所有实例都支持此标记之前避免通过 Admin API 写入。如果新版本保存了带标记的值后必须降级,请恢复升级前创建的数据备份。

APISIX 会在将 SSL 资源 key 和 keys 字段中的 PEM 值保存到 etcd 前进行加密。若要验证,请按照配置客户端和 APISIX 之间的 HTTPS 中的步骤操作,然后检查创建或更新响应,或检查 etcd 中存储的资源。Admin API 的 GET 响应会省略 SSL 私钥字段。

APISIX 也会加密 Upstream 和内联 Stream Route 上游中的 upstream.tls.client_key。Admin API 不会以明文返回内联 Stream Route 客户端私钥。有关 Stream 配置,请参阅使用 mTLS 向 TLS 上游进行身份认证。

验证解密​

要验证消费者 key-auth 密钥将被解密并按预期用于身份认证,请创建一个启用了 key-auth 的路由:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "auth-route",
"uri": "/get",
"plugins": {
"key-auth": {}
},
"upstream" : {
"nodes": {
"httpbin.org":1
}
}
}'

使用消费者凭证向路由发送请求:

curl -i "http://127.0.0.1:9080/get" -H 'apikey: john-key'

你应该收到 HTTP/1.1 200 OK 响应,验证密钥已成功解密并用于身份认证。

更新密钥环​

可以使用正确的密钥环将加密数据还原为明文。因此,强烈建议你在生产环境中使用自定义密钥环。

每个密钥必须恰好包含 16 或 32 个字节。请使用 ASCII 字符,以保证字符长度与字节长度一致。16 字节密钥使用 AES-128-CBC,32 字节密钥使用 AES-256-CBC。APISIX 会在启动或重新加载前校验 config.yaml 时拒绝其他长度。

密钥环在轮换期间可以同时包含两种长度。APISIX 使用第一个密钥加密新值,并在解密现有值时依次尝试所有密钥。调整密钥顺序不会重写现有密文。若要从 AES-128 轮换到 AES-256,请先添加新的 32 字节密钥,并在其后保留旧密钥:

config.yaml
apisix:
data_encryption:
enable_encrypt_fields: true
keyring:
- 0123456789abcdef0123456789abcdef
- qeddd145sfvddff3
- edd1c9f0985e76a2

❶ 为 敏感插件字段 启用加密。

❷ 先添加新的 32 字节 ASCII 密钥。请使用安全生成的密钥替换此示例。

❸ 添加第一个和第二个旧密钥。

警告

如果你的 APISIX 已经在运行并且有数据被加密,请不要删除旧密钥。请将新密钥添加到数组开头,并按原有顺序保留其后的每个旧密钥,使 APISIX 仍能解密现有值。

对于使用旧密钥加密的每个插件字段和 TLS 私钥,请以明文重新提交,由 APISIX 使用密钥环中的第一个密钥(即新密钥)重新加密。验证所有值均已重新加密后,才能停用旧密钥。启用解密时,Admin API 的 GET 请求会以明文返回受保护的插件字段,但不会返回 SSL 私钥。请在安全备份中保留原始 PEM 私钥,以便重新提交 SSL 资源。如果无法确认每个加密值都已重写,请保留旧密钥。

如果没有数据被加密,你可以直接使用自定义密钥配置该部分。

如果你的 APISIX 已经在运行,重新加载 APISIX 以使配置更改生效。

排查升级后的解密失败​

升级可能会将现有插件字段新增到 encrypt_fields。因此,早期版本写入的配置可能在当前版本要求加密的位置包含未加密值。如果已配置的密钥环不再包含最初用于加密现有数据的密钥,APISIX 也会无法解密这些数据。

如果错误日志报告解密失败:

  1. 保留完整的旧密钥环。排查期间不要删除旧密钥或调整其顺序。
  2. 将所有新密钥添加到 apisix.data_encryption.keyring 的开头,并在其后保留每个旧密钥。
  3. 重新加载 APISIX,并确认它可以读取现有配置。
  4. 对于插件字段,请通过 Admin API GET 请求获取受影响的资源。旧密钥可用且已启用插件字段加密时,APISIX 会以明文返回受保护字段。请在更新请求中重新提交该明文,使 APISIX 使用当前密钥环中的第一个密钥进行加密。不要复用早期写入响应中的密文,也不要直接使用 etcd 中的密文。
  5. 对于 SSL 资源和上游客户端私钥,请从安全备份中重新提交原始明文私钥。Admin API 读取不会公开这些私钥。
  6. 确认资源正常工作后,再考虑后续停用旧密钥。

不要先删除旧密钥。一旦 APISIX 无法解密某个值,重新保存这份不可读数据也无法恢复原始敏感信息。

禁用插件字段加密​

enable_encrypt_fields 选项仅适用于插件 Schema 中列出的字段。禁用前,请保持完整密钥环不变,并通过已通过身份认证的 Admin API GET 请求安全地获取需要保留的每个加密插件字段的明文。请安排维护窗口,以便在恢复流量前重写这些字段。

在不删除密钥环的情况下,将 enable_encrypt_fields 设置为 false:

config.yaml(接续轮换后的密钥示例)
apisix:
data_encryption:
enable_encrypt_fields: false
keyring:
- 0123456789abcdef0123456789abcdef
- qeddd145sfvddff3
- edd1c9f0985e76a2
警告

禁用插件字段加密时不要删除密钥环。APISIX 仍需要密钥环来解密现有 TLS 私钥,并保留恢复尚未重写的插件密文的能力。enable_encrypt_fields 为 false 时,插件密文不会被解密。如果未提前获取明文,请先使用完整密钥环重新启用插件字段加密,再获取并恢复明文。删除所需密钥可能导致 TLS 失效,并使加密值无法恢复。

如果你的 APISIX 已经在运行,重新加载 APISIX 以使配置更改生效。

重新加载后,APISIX 不再加密或解密插件字段。在重新提交禁用前获取的明文之前,APISIX 会将现有密文直接作为插件值使用;新插件值会以明文存储。

只要密钥环仍存在,TLS 私钥加密就会保持启用。APISIX 会继续加密和解密 SSL 资源私钥及上游客户端私钥。

现在,如果你再次使用 key-auth 配置消费者凭证:

curl "http://127.0.0.1:9180/apisix/admin/consumers/JohnDoe/credentials" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "cred-john-key-auth",
"plugins": {
"key-auth": {
"key": "john-key"
}
}
}'

你应该看到密钥以明文保存的响应:

{
"key": "/apisix/consumers/JohnDoe/credentials/cred-john-key-auth",
"value": {
"create_time": 1726300662,
"update_time": 1726300668,
"plugins": {
"key-auth": {
"key": "john-key"
}
},
"id": "cred-john-key-auth"
}
}

了解插件加密字段​

需要加密的插件字段在每个插件 Schema 的 encrypt_fields 属性中定义。字段路径可以指向顶层字段或嵌套字段。例如:

apisix/plugins/basic-auth.lua
local consumer_schema = {
type = "object",
title = "work with consumer object",
properties = {
username = { type = "string" },
password = { type = "string" },
},
# highlight-next-line
encrypt_fields = {"password"},
required = {"username", "password"},
}

在使用 etcd 存储的部署中,当 enable_encrypt_fields 为 true 且已配置密钥环时,APISIX 会在存储前加密这些字段。

对于嵌套字段,请使用点分隔路径,例如 session.secret、redis.password 或 auth_config.private_key。路径可以具有任意嵌套深度。当中间路径段是数组时,APISIX 会遍历数组中的每个对象,因此支持 ai-proxy-multi 中的 instances.auth.aws.secret_access_key 等字段。

在路径的最后一个字段处,APISIX 会加密以下值类型:

  • 字符串;
  • 字符串数组;
  • 值均为字符串的对象。

最后一个字段中的非字符串项会保持不变。仅添加确实包含敏感信息,且运行时代码在解密后仍预期相同值类型的字段。

下表总结了所有插件的加密插件字段:

对于日志插件,加密字段可以是其字符串值被加密的对象,例如 elasticsearch-logger 和 loki-logger 中的 headers。加密会保护静态存储的数据。启用插件字段加密且所需密钥环可用时,已获授权的 Admin API 读取可以返回解密后的插件配置。

插件字段
authz-casdoorclient_secret
authz-keycloakclient_secret
azure-functionsauthorization.apikey、master_apikey
basic-authpassword
cas-authcookie.secret
clickhouse-loggerpassword
dingtalk-authapp_secret,secret,secret_fallbacks
elasticsearch-loggerauth.password、headers
feishu-authapp_secret,secret,secret_fallbacks
rocketmq-loggersecret_key
sls-loggeraccess_key_secret
error-log-loggerclickhouse.password、kafka.brokers.sasl_config.password
google-cloud-loggingauth_config.private_key
csrfkey
hmac-authsecret_key
http-loggerauth_header
jwt-authsecret
kafka-loggerbrokers.sasl_config.password
key-authkey
lagotoken
logglycustomer_token
loki-loggerheaders
openwhiskservice_token
openfunctionauthorization.service_token
tencent-cloud-clssecret_key
openid-connectclient_secret、client_rsa_private_key、dpop.private_key、session.secret、session.redis.password
kafka-proxysasl.password
jwe-decryptkey、secret
ai-cacheredis_password、semantic.embedding.openai.api_key、semantic.embedding.azure_openai.api_key
ai-aliyun-content-moderationaccess_key_secret
ai-aws-content-moderationcomprehend.secret_access_key
ai-lakera-guardapi_key
ai-proxyauth.header,auth.query,auth.gcp.service_account_json,auth.aws.secret_access_key,auth.aws.session_token
ai-proxy-multiinstances.auth.header,instances.auth.query,instances.auth.gcp.service_account_json,instances.auth.aws.secret_access_key,instances.auth.aws.session_token
ai-ragembeddings_provider.azure_openai.api_key、vector_search_provider.azure_ai_search.api_key
ai-rate-limitingredis_password、sentinel_password
aws-lambdaauthorization.apikey,authorization.iam.accesskey,authorization.iam.secretkey
ldap-auth-advancedldap_password
limit-connredis_password
limit-countredis_password、sentinel_password
limit-reqredis_password
saml-authsp_private_key,secret,secret_fallbacks
splunk-hec-loggingendpoint.token