How clearbank/fi-api-signtool-java works
Project type and purpose
• This is a small Java “sample tool” / command-line utility whose sole purpose is to demonstrate how to digitally sign a payload (using a private key from disk for demo, but meant to be replaced by an HSM in production) and integrate with ClearBank®’s API.
File structure
• Top level: Main.java (entry point), README.md, .gitignore
• Data/: contains sample private/public key PEM files
• No formal src/ or lib/ directories—everything is in one module.
• No build scripts shown (Maven/Gradle would be typical in a larger Java project).
README for additional insights
• Describes that in production the private key should reside in a FIPS-compliant HSM.
• Mentions integration with ClearBank®’s live API, implying the sample may also show an HTTP client or at least produce a signature ready to be sent.
Main components
a. User / Client: someone invokes the program (CLI or embedded library).
b. Main Application (Main.java): orchestrates reading the payload, invoking the signing logic, optionally calling the API.
c. Signing Module / Service: encapsulates all JCA (Java Cryptography Architecture) logic—loading keys, applying the digital signature algorithm (e.g., SHA256withRSA).
d. Key Provider Abstraction:
• FileSystemKeyProvider (demo) reads PEM files under Data/.
• HSMKeyProvider (prod) would call the HSM via PKCS#11/JCE.
e. Payload Store/Input: wherever the input data comes from (could be CLI args, a file, or an API request).
f. ClearBank® API Endpoint: external HTTP(S) service that validates the signed payload.
Relationships and data flows
• The User invokes Main → Main reads the payload → Main invokes Signing Service
• Signing Service calls Key Provider → either reads PEM file or calls HSM → signing operation → returns signature
• Main attaches signature to payload → Main sends HTTP request to ClearBank API (or prints the signature) → receives response
Architectural patterns and design principles
• Separation of concerns:
• Main.java handles orchestration
• Signing Service handles cryptography
• Key Provider abstraction hides file vs HSM details
• Dependency inversion: Main depends on an interface IKeyProvider rather than concrete file logic.
• Single responsibility: each component does one thing.
Technologies, frameworks, libraries
• Java SE (JDK) – java.security, java.nio.file
• BouncyCastle or built-in JCA providers for PEM parsing and signature
• HTTP client (e.g., HttpURLConnection or Apache HttpClient) for the ClearBank API call
• (In production) PKCS#11 provider for HSM integration