Add HSM integration configuration guide for Open Banking

[Jenarththan2001]

Purpose

Add documentation for configuring Hardware Security Module (HSM) integration with WSO2 Open Banking Accelerator. This guide is needed as HSM support has been implemented across the Carbon Kernel, Identity OAuth, Financial Services Accelerator, and APIM Mediation Policies codebases, but no end-user configuration documentation exists yet.

Goals

Provide a complete, vendor-agnostic configuration guide that enables users to set up any PKCS#11-compliant HSM with WSO2 Identity Server and WSO2 API Manager for secure key management in Open Banking deployments.

Approach

• Added a new documentation page: install-and-setup/configuring-hsm-for-ob.md
• Added an architecture diagram: assets/img/install-and-setup/hsm-vs-jks-architecture.png
• Added navigation entry in mkdocs.yml under "Install and Setup"
• The guide covers: PKCS#11 config, key generation, certificate exchange, deployment.toml configuration, consent validation alias setup, server startup verification, disabling HSM, vendor-specific examples (Thales Luna, AWS CloudHSM, Azure Dedicated HSM), and security best practices

Release note

Added documentation for configuring HSM (Hardware Security Module) integration with WSO2 Open Banking Accelerator, covering PKCS#11 setup, key generation, deployment configuration, and vendor-specific examples.

Documentation

This PR is the documentation. No additional doc links required.

Training

N/A

Certification

N/A — This is a configuration guide, not a feature change that impacts certification content.

[coderabbitai]

Important

Review skipped

Review was skipped due to path filters

⛔ Files ignored due to path filters (1)

• en/docs/assets/img/install-and-setup/hsm-vs-jks-architecture.png is excluded by !**/*.png

CodeRabbit blocks several paths by default. You can override this behavior by explicitly including those paths in the path filters. For example, including **/dist/** will override the default block on the dist directory, by removing the pattern from both the lists.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 3027bde6-350e-4db2-ad34-5f158cef2de5

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds a new documentation page and navigation entry detailing how to configure PKCS#11-backed HSM keystores for WSO2 Open Banking Accelerator, covering HSM vs file keystores, which private-key operations use the HSM, provider/key setup, certificate exchange, per-server deployment.toml settings, verification, troubleshooting, and production recommendations.

Changes

Cohort / File(s)	Summary
HSM Configuration Documentation en/docs/install-and-setup/configuring-hsm-for-ob.md, en/mkdocs.yml	Adds a new comprehensive HSM (PKCS#11) integration guide for Open Banking and registers it in the docs navigation. The guide includes PKCS#11 provider (pkcs11.cfg) examples, RSA key generation in HSM, certificate export/import steps, per-server [keystore.hsm] deployment.toml settings, verification/troubleshooting, disablement, and production best practices.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely describes the main change—adding HSM integration configuration documentation for Open Banking.
Description check	✅ Passed	The description covers all critical sections with sufficient detail: Purpose (HSM support implemented but undocumented), Goals (vendor-agnostic guide), Approach (files added and content covered), and Release note. Non-critical sections like Training, Certification, and Marketing are appropriately marked N/A with explanations.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ 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

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

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

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

Inline comments:
In `@en/docs/install-and-setup/configuring-hsm-for-ob.md`:
- Around line 145-157: The docs are unclear whether the key generation step
using keytool (the shown command with -alias wso2carbon, -providerArg
<IS_HOME>/repository/resources/security/pkcs11.cfg, -storetype PKCS11 and
-storepass <HSM_PIN>) must be run per product or can be shared; update the text
around the keytool command and the subsequent export step (the APIM HSM
certificate export described in Step 3) to explicitly state the recommended
approach: either generate separate keys on each server (IS and APIM) and show
the alternative keytool invocation for APIM (replace <IS_HOME> with <APIM_HOME>
in -providerArg and adjust any product-specific aliases/paths), or document a
shared key strategy with instructions on exporting/importing the certificate
between products and any alias/path changes; reference the keytool command,
-providerArg, and the APIM export step so readers know which commands to run for
each product.
- Around line 107-111: Replace the fenced code blocks (``` ... ```) with
indented code blocks (4-space indent) so the markdown uses the repo's expected
indented style; specifically convert the fenced blocks that declare properties
(``` properties ... ```), and the other fenced sections referenced in the
review, to use indented code blocks instead (preserve the exact block content
and spacing, only remove the triple-backticks and indent each line by four
spaces) to satisfy MD046 linting.
- Around line 179-187: The fenced code blocks showing keystore output and log
lines are missing language identifiers; update each of these triple-backtick
blocks (including the shown block with "Keystore type: PKCS11" and the log
blocks like "[INFO] {KeyStoreManager} - Primary keystore..." and "[ERROR]
{KeyStoreManager} - Error loading HSM keystore", and the other occurrences
around lines 360-362 and 366-368) to include a language tag such as text or log
(e.g., change ``` to ```text or ```log) so markdownlint MD040 is satisfied.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 33874402-0706-44db-895b-30784c405294

📥 Commits

Reviewing files that changed from the base of the PR and between d06108f and 439bf45.

⛔ Files ignored due to path filters (1)

• en/docs/assets/img/install-and-setup/hsm-vs-jks-architecture.png is excluded by !**/*.png

📒 Files selected for processing (2)

• en/docs/install-and-setup/configuring-hsm-for-ob.md
• en/mkdocs.yml

[coderabbitai]

Actionable comments posted: 3

♻️ Duplicate comments (1)

en/docs/install-and-setup/configuring-hsm-for-ob.md (1)

205-215: ⚠️ Potential issue | 🟠 Major

HSM PIN exposed in certificate export command.

Similar to the key generation step, the certificate export command exposes the HSM PIN via -storepass in shell history and process listings. Consider adding guidance to use interactive PIN entry in production environments.

🤖 Prompt for AI Agents

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

In `@en/docs/install-and-setup/configuring-hsm-for-ob.md` around lines 205 - 215,
The certificate export command exposes the HSM PIN via the -storepass flag (in
the keytool invocation that uses -keystore NONE -storetype PKCS11 -providerArg),
so remove the hardcoded -storepass and update the instructions to rely on
interactive PIN entry (omit -storepass so keytool prompts) or reference a secure
PIN provider (e.g., PKCS#11 token prompt or OS keyring) for production; ensure
the doc replaces the example using -storepass <HSM_PIN> with guidance to let
keytool prompt or use a secure secret management approach when running the
keytool -exportcert command.

🤖 Prompt for all review comments with AI agents

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

Inline comments:
In `@en/docs/install-and-setup/configuring-hsm-for-ob.md`:
- Around line 397-398: Update the fallback sentence to explicitly state per
product which file-based keystore is used when HSM is disabled: list APIM and
map its purposes to the keystore names shown in the APIM example (e.g., APIM TLS
keys -> [keystore.tls], APIM internal/primary keys -> [keystore.internal]); for
the Open Banking components mention they fall back to [keystore.primary] (or
[keystore.tls] where applicable). Edit the line that currently reads about
falling back to “[keystore.primary] or [keystore.tls]” to enumerate each product
(APIM, Open Banking) and the exact keystore symbols ([keystore.tls],
[keystore.internal], [keystore.primary]) they will use.
- Around line 253-259: Insert a prominent warning block immediately after the
HSM PIN example toml block shown under the keystore.hsm section (the three-line
example with pin = "<HSM_PIN>" and alias = "wso2carbon") that states the HSM PIN
must not be stored in plaintext in production, and directs readers to WSO2's
secure vault documentation (encrypt-passwords-with-cipher-tool) and the existing
"Security best practices" section; then apply the same warning block right after
the APIM HSM configuration example later in the document so both the HSM PIN
introduction in the keystore.hsm example and the APIM configuration example
include the same security guidance.
- Around line 146-159: The keytool invocation shown (keytool -genkeypair ...)
currently passes the HSM PIN via the -storepass parameter which exposes secrets;
remove the -storepass <HSM_PIN> argument from the command and update the doc
text to instruct users to enter the PIN interactively (omitting -storepass) or
reference the secure vault approach described earlier (e.g., use the PKCS11
providerArg and prompt at runtime), and add a short note after the command
saying "You will be prompted to enter the PIN interactively" so readers know to
supply the PIN securely.

---

Duplicate comments:
In `@en/docs/install-and-setup/configuring-hsm-for-ob.md`:
- Around line 205-215: The certificate export command exposes the HSM PIN via
the -storepass flag (in the keytool invocation that uses -keystore NONE
-storetype PKCS11 -providerArg), so remove the hardcoded -storepass and update
the instructions to rely on interactive PIN entry (omit -storepass so keytool
prompts) or reference a secure PIN provider (e.g., PKCS#11 token prompt or OS
keyring) for production; ensure the doc replaces the example using -storepass
<HSM_PIN> with guidance to let keytool prompt or use a secure secret management
approach when running the keytool -exportcert command.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d2e9b297-75c9-4cd7-83c4-51638ec392e5

📥 Commits

Reviewing files that changed from the base of the PR and between 6168334 and dc5db64.

📒 Files selected for processing (1)

• en/docs/install-and-setup/configuring-hsm-for-ob.md