docs: Add HSM support limitation for JWE payload decryption

[Jenarththan2001]

Purpose

Document HSM support limitations for JWE Payload Processing Policy. Users need to know which algorithms work with HSM before deploying to production.

Relates to: wso2/financial-services-apim-mediation-policies#25

Goals

• Communicate algorithm support status with HSM
• Document unsupported RSA-OAEP algorithms
• Note that limitation will be addressed in future release

Approach

Added warning admonition to jwe-payload-processing-policy.md:

!!! warning "HSM Support Limitation"
    When Hardware Security Module (HSM) is enabled, only **RSA1_5** algorithm 
    is supported for JWE decryption. The following algorithms are **not supported** 
    in HSM mode: `RSA-OAEP-256`, `RSA-OAEP`, `RSA-OAEP-384`, `RSA-OAEP-512`. 
    This limitation will be addressed in a future release.

Placed immediately after algorithm support statement for visibility.

Release Note

Documentation Update: JWE Payload Processing Policy

Added HSM limitation notice:

• RSA1_5 supported with HSM
• RSA-OAEP variants not supported (SunPKCS11 limitation)
• Non-breaking: JKS mode supports all algorithms

Documentation

File: en/docs/learn/jwe-payload-processing-policy.md
Lines added: 3 (warning block)

Test Environment

• MkDocs 1.4+, mkdocs-material 4.6.3
• Rendering verified on desktop/tablet/mobile

---

Files Changed: 1 file, 3 insertions(+)

• en/docs/learn/jwe-payload-processing-policy.md

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 8282237e-e4ab-453d-911a-94dde1c04147

📥 Commits

Reviewing files that changed from the base of the PR and between 5644ff0 and 6b6e7ec.

📒 Files selected for processing (1)

• en/docs/learn/jwe-payload-processing-policy.md

✅ Files skipped from review due to trivial changes (1)

• en/docs/learn/jwe-payload-processing-policy.md

---

📝 Walkthrough

Documentation Update

Added a warning admonition to the JWE Payload Processing Policy documentation clarifying Hardware Security Module (HSM) support limitations. The warning specifies that when HSM is enabled, JWE decryption supports only the RSA1_5 algorithm, while RSA-OAEP-256, RSA-OAEP, RSA-OAEP-384, and RSA-OAEP-512 algorithms are not supported in HSM mode. The documentation notes that JKS mode remains fully supported. The limitation is attributed to the underlying PKCS11 provider and is expected to be addressed in a future release.

Files changed:

• en/docs/learn/jwe-payload-processing-policy.md (+3 lines)

Effort to review: Low

Walkthrough

This change adds a warning section to the JWE Payload Processing Policy documentation. The addition clarifies the algorithmic constraints when Hardware Security Module (HSM) is enabled for JWE decryption. Specifically, it documents that only the RSA1_5 algorithm is supported under HSM, while the RSA-OAEP-256, RSA-OAEP, RSA-OAEP-384, and RSA-OAEP-512 algorithms are explicitly not supported. The warning also notes that this limitation will be addressed in a future update. No functional changes, code logic, or interfaces were modified.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding documentation about HSM support limitations for JWE payload decryption.
Description check	✅ Passed	The description covers Purpose, Goals, Approach, Release Note, and Documentation sections with adequate detail. Some template sections like Automation tests, Security checks, and Migrations are not applicable for a documentation-only change.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Review rate limit: 0/1 reviews remaining, refill in 60 minutes.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

en/docs/learn/jwe-payload-processing-policy.md (1)

14-16: Clear and accurate HSM limitation documentation.

The warning is well-formatted, appropriately scoped to JWE decryption, and correctly identifies the algorithm constraints in HSM mode. The placement after the general algorithm support statement is logical.

Optional enhancement for additional clarity

Consider mentioning that the encryption methods (A128GCM, A192GCM, A256GCM) remain supported when using RSA1_5 in HSM mode, and that JKS mode retains full algorithm support. This would provide complete context for users evaluating HSM adoption:

 !!! warning "HSM Support Limitation"
-    When Hardware Security Module (HSM) is enabled, only **RSA1_5** algorithm is supported for JWE decryption. The following algorithms are **not supported** in HSM mode: `RSA-OAEP-256`, `RSA-OAEP`, `RSA-OAEP-384`, `RSA-OAEP-512`. This limitation will be addressed in a future release.
+    When Hardware Security Module (HSM) is enabled, only **RSA1_5** algorithm is supported for JWE decryption (all encryption methods `A128GCM`, `A192GCM`, `A256GCM` remain supported). The following algorithms are **not supported** in HSM mode: `RSA-OAEP-256`, `RSA-OAEP`, `RSA-OAEP-384`, `RSA-OAEP-512`. JKS keystores retain full algorithm support. This limitation will be addressed in a future release.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@en/docs/learn/jwe-payload-processing-policy.md` around lines 14 - 16, Update
the "HSM Support Limitation" warning to explicitly state that while only RSA1_5
is supported for JWE decryption in HSM mode (and RSA-OAEP-* variants are not),
the content encryption methods A128GCM, A192GCM, and A256GCM remain supported
when using RSA1_5, and that JKS mode continues to support the full set of JWE
algorithms; reference the "HSM Support Limitation" heading and the JWE
decryption context so the added sentences clearly follow the existing limitation
note.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@en/docs/learn/jwe-payload-processing-policy.md`:
- Around line 14-16: Update the "HSM Support Limitation" warning to explicitly
state that while only RSA1_5 is supported for JWE decryption in HSM mode (and
RSA-OAEP-* variants are not), the content encryption methods A128GCM, A192GCM,
and A256GCM remain supported when using RSA1_5, and that JKS mode continues to
support the full set of JWE algorithms; reference the "HSM Support Limitation"
heading and the JWE decryption context so the added sentences clearly follow the
existing limitation note.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4c43cc4a-3da4-472e-8f04-732c951a1386

📥 Commits

Reviewing files that changed from the base of the PR and between 1e6455e and 5644ff0.

📒 Files selected for processing (1)

• en/docs/learn/jwe-payload-processing-policy.md