Yilialinn commented on code in PR #13873: URL: https://github.com/apache/apisix/pull/13873#discussion_r3850796813
########## docs/en/latest/plugins/jwe-decrypt.md: ########## @@ -37,27 +37,39 @@ import TabItem from '@theme/TabItem'; ## Description -The `jwe-decrypt` Plugin decrypts [JWE](https://datatracker.ietf.org/doc/html/rfc7516) authorization headers in requests sent to APISIX [Routes](../terminology/route.md) or [Services](../terminology/service.md). +The `jwe-decrypt` Plugin reads a five-part compact token from a request header, selects a [Consumer](../terminology/consumer.md) by the token's `kid`, decrypts the ciphertext with AES-256-GCM, and writes the plaintext to a configured header before proxying the request. You can enable the Plugin on APISIX [Routes](../terminology/route.md) or [Services](../terminology/service.md). -The decryption key should be configured in [Consumer](../terminology/consumer.md). +The token resembles [JWE Compact Serialization](https://datatracker.ietf.org/doc/html/rfc7516#section-3.1), but the current Plugin uses a Plugin-specific format. Configure a 32-byte decryption secret on the Consumer. + +:::warning + +The current implementation reads `kid` from the decoded header but does not validate the `alg` or `enc` fields and does not use the protected-header segment as AES-GCM additional authenticated data (AAD). Standard RFC 7516 JWE libraries are therefore not directly interoperable. Generate tokens with the exact format described below, use a fixed trusted token generator, and do not treat header fields as authenticated. + +::: + +:::caution + +The decrypted plaintext is forwarded in a request header. Use TLS on the upstream connection when the plaintext is sensitive, restrict access to the upstream, and avoid logging the configured forwarding header. + +::: ## Attributes ### Consumer -| Name | Type | Required | Default | Valid values | Description | -| ----------------- | ------- | -------- | ------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| key | string | True | | | A unique key that identifies the Credential for a Consumer. | -| secret | string | True | | 32 characters | The shared symmetric encryption/decryption key. You can also store it in an environment variable and reference it using the `env://` prefix, or in a secret manager such as HashiCorp Vault's KV secrets engine, and reference it using the `secret://` prefix. | -| is_base64_encoded | boolean | False | false | | Set to true if the secret is base64 encoded. Note that after enabling `is_base64_encoded`, the `secret` length may exceed 32 characters. You only need to make sure the decoded length is still 32 characters. | +| Name | Type | Required | Default | Valid values | Description | +| ----------------- | ------- | -------- | ------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| key | string | True | | | A unique key that identifies the Credential for a Consumer. | +| secret | string | True | | 32 bytes | The shared symmetric key. It can be stored in an environment variable using `env://` or in a supported secret manager using `secret://`. | Review Comment: Fixed in 031fc71f. The documented references now use the required `$env://...` and `$secret://...` prefixes and link to the Secret reference documentation. ########## docs/en/latest/plugins/jwe-decrypt.md: ########## @@ -37,27 +37,39 @@ import TabItem from '@theme/TabItem'; ## Description -The `jwe-decrypt` Plugin decrypts [JWE](https://datatracker.ietf.org/doc/html/rfc7516) authorization headers in requests sent to APISIX [Routes](../terminology/route.md) or [Services](../terminology/service.md). +The `jwe-decrypt` Plugin reads a five-part compact token from a request header, selects a [Consumer](../terminology/consumer.md) by the token's `kid`, decrypts the ciphertext with AES-256-GCM, and writes the plaintext to a configured header before proxying the request. You can enable the Plugin on APISIX [Routes](../terminology/route.md) or [Services](../terminology/service.md). -The decryption key should be configured in [Consumer](../terminology/consumer.md). +The token resembles [JWE Compact Serialization](https://datatracker.ietf.org/doc/html/rfc7516#section-3.1), but the current Plugin uses a Plugin-specific format. Configure a 32-byte decryption secret on the Consumer. + +:::warning + +The current implementation reads `kid` from the decoded header but does not validate the `alg` or `enc` fields and does not use the protected-header segment as AES-GCM additional authenticated data (AAD). Standard RFC 7516 JWE libraries are therefore not directly interoperable. Generate tokens with the exact format described below, use a fixed trusted token generator, and do not treat header fields as authenticated. + +::: + +:::caution + +The decrypted plaintext is forwarded in a request header. Use TLS on the upstream connection when the plaintext is sensitive, restrict access to the upstream, and avoid logging the configured forwarding header. Review Comment: Fixed in 031fc71f. The caution now states that an APISIX HTTPS Upstream alone does not authenticate a standard HTTP upstream and requires an authenticated, protected path that validates upstream identity. ########## docs/en/latest/plugins/jwe-decrypt.md: ########## @@ -240,6 +254,8 @@ adc sync -f adc.yaml <Tabs groupId="k8s-api"> <TabItem value="gateway-api" label="Gateway API"> +The following Gateway API configuration uses public HTTPBin only with the non-sensitive demonstration payload shown on this page. Before forwarding real decrypted data, replace it with a controlled upstream and configure TLS for the entire upstream connection. Review Comment: Fixed in 031fc71f. The Gateway API note now limits HTTPBin to non-sensitive demonstration use and requires an authenticated, protected path with upstream identity validation for real decrypted data. ########## docs/en/latest/plugins/ai-rag.md: ########## @@ -38,9 +38,9 @@ import TabItem from '@theme/TabItem'; ## Description -The `ai-rag` Plugin provides Retrieval-Augmented Generation (RAG) capabilities with LLMs. It facilitates the efficient retrieval of relevant documents or information from external data sources, which are used to enhance the LLM responses, thereby improving the accuracy and contextual relevance of the generated outputs. +The `ai-rag` Plugin implements the retrieval step of a Retrieval-Augmented Generation (RAG) request flow. It generates an embedding from the request, performs a vector search, appends the retrieved content to the LLM messages, and removes the `ai_rag` request object before the request is proxied. Review Comment: Fixed in 031fc71f. The description now says protocol-specific LLM request input, covering both Chat Completions `messages` and Responses API top-level `input`. -- 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: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
