Copilot commented on code in PR #13873: URL: https://github.com/apache/apisix/pull/13873#discussion_r3850366398
########## 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: For HTTP upstreams, APISIX does not verify the upstream server certificate (`docs/en/latest/FAQ.md:731`; `apisix/schema_def.lua:445-449` limits `tls.verify` to Kafka). Therefore `scheme: https` encrypts traffic but does not authenticate the upstream, so an active MITM can still read sensitive plaintext. The guidance should require a protected path or a TLS-terminating component that validates server 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: This repeats the implication that configuring TLS is sufficient for sensitive data, but APISIX does not validate HTTP upstream certificates. The production guidance should explicitly require an authenticated/protected path rather than only a controlled hostname plus HTTPS. ########## 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: The retrieved content is not always appended to `messages`: the supported OpenAI Responses path appends it to top-level `input` (`apisix/plugins/ai-protocols/openai-responses.lua:384-402`). Describe this as protocol-specific request input so the overview remains accurate for all supported request formats. ########## 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: These prefixes are not valid secret references without the leading `$`; APISIX documents and parses them as `$env://...` and `$secret://...` (`docs/en/latest/terminology/secret.md:49-53`). As written, users will configure literal strings instead of resolved secrets. -- 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]
