feat(infrastructure): add PKCS#11 PDF signing infrastructure
This commit is contained in:
@@ -0,0 +1,228 @@
|
||||
# FES (Advanced Electronic Signature) Summary and Integration Plan - EN
|
||||
|
||||
This document summarizes the shared diagram flow (`Ablauf SignFlow Unternehmenszertifikat`) and provides a small-step integration plan for the `EnvelopeGenerator` solution.
|
||||
|
||||
---
|
||||
|
||||
## 1) Simplified flow summary
|
||||
|
||||
Flow logic:
|
||||
|
||||
1. The sender uploads a document and defines signers.
|
||||
2. If a valid company certificate already exists in HSM, it is used with the company key pair.
|
||||
3. If no valid company certificate exists, CA issuance/renewal flow is required.
|
||||
4. The signer receives an e-mail with a signing link.
|
||||
5. The signer completes SMS OTP (2FA) and performs UI signature interaction.
|
||||
6. Backend computes the hash for the current signing stage and sends it to HSM.
|
||||
7. HSM signs the hash with the private key and returns signature + certificate context.
|
||||
8. Backend embeds digital signature and certificate into PDF and writes audit trail.
|
||||
9. After all signers complete, the final artifact is archived.
|
||||
10. The final signed document is distributed to signers.
|
||||
|
||||
Important: The visible UI signature is not yet the legal electronic signature. The legal signature is produced in backend+HSM steps.
|
||||
|
||||
---
|
||||
|
||||
## 2) Relation to current codebase (as-is)
|
||||
|
||||
- `EnvelopeGenerator.Server` is the presentation layer host (Blazor + API hosting).
|
||||
- Business flow is handled in `Application` via MediatR pipelines.
|
||||
- Current receiver flow is centered around UI overlay/signature capture.
|
||||
- Missing FES core: PKCS#11 hash-sign-verify + certificate-based PDF embedding pipeline.
|
||||
|
||||
Critical deployment fact:
|
||||
|
||||
- `EnvelopeGenerator.Server` is planned to run on Windows.
|
||||
- SoftHSM is currently planned to run on Linux.
|
||||
- A Windows process cannot directly load Linux PKCS#11 module (`libsofthsm2.so`).
|
||||
- Therefore, architecture must include a compatibility bridge (service or proxy) unless HSM/SoftHSM is local to Windows.
|
||||
|
||||
Conclusion: FES is not a replacement of the current flow; it is a cryptographic hardening layer behind it.
|
||||
|
||||
---
|
||||
|
||||
## 3) Why SoftHSM tests are foundational
|
||||
|
||||
The tests defined in `SOFTHSM_TEST_KILAVUZU_TR.md` are the technical prerequisite for FES:
|
||||
|
||||
- `slots/login` -> HSM connectivity and authentication
|
||||
- `certificate` -> certificate retrieval path
|
||||
- `sign` -> hash signing with private key
|
||||
- `verify` -> signature and certificate consistency validation
|
||||
|
||||
Without these tests passing, diagram steps 6-8 should not go live.
|
||||
|
||||
---
|
||||
|
||||
## 4) Target architecture (clean architecture aligned)
|
||||
|
||||
### Deployment topology options (must choose one)
|
||||
|
||||
1. **Linux signing service (recommended)**
|
||||
- Windows `EnvelopeGenerator.Server` calls Linux signing API over HTTPS.
|
||||
- Linux signing service performs PKCS#11 operations against SoftHSM.
|
||||
- Private keys never leave Linux/HSM boundary.
|
||||
|
||||
2. **PKCS#11 proxy bridge**
|
||||
- Windows host loads a Windows PKCS#11 proxy client DLL.
|
||||
- Proxy forwards PKCS#11 operations to Linux side connected to SoftHSM.
|
||||
|
||||
3. **Windows-local SoftHSM (dev/test)**
|
||||
- SoftHSM also installed on Windows and used locally.
|
||||
- Useful for local testing, not preferred production topology.
|
||||
|
||||
Decision note:
|
||||
|
||||
- For production-critical FES, choose option 1 by default unless enterprise HSM policy requires option 2.
|
||||
- Keep option 3 for development convenience only.
|
||||
|
||||
### Layer responsibilities
|
||||
|
||||
- `EnvelopeGenerator.Server`:
|
||||
- API endpoints, auth orchestration, input validation.
|
||||
- FES branch routing: standard-sign path vs external signing-service/proxy path.
|
||||
- No private-key material handling.
|
||||
|
||||
- `EnvelopeGenerator.Application`:
|
||||
- Use cases such as `SignWithHsmCommand`.
|
||||
- MediatR pipeline orchestration for status/history/audit.
|
||||
- FES evidence model aggregation (ip/email/phone/user-agent/otp proof/timestamps).
|
||||
|
||||
- `DocumentService.Infrastructure.Crypt`:
|
||||
- Implementations for `IPkcs11Service`, `IPdfSignatureService`, `ITimestampService`.
|
||||
- Pkcs11Interop integration and cryptographic operations.
|
||||
- Optional client for Linux signing service if topology option 1 is selected.
|
||||
|
||||
- `Domain`:
|
||||
- Signature evidence and audit-trail models.
|
||||
|
||||
---
|
||||
|
||||
## 5) Small-step integration plan
|
||||
|
||||
## Phase 0 - Scope and contracts
|
||||
|
||||
1. Finalize signing algorithms (for example `SHA256_RSA_PKCS`).
|
||||
2. Confirm strategy: company certificate vs signer-specific certificate.
|
||||
3. Freeze mandatory audit fields:
|
||||
- identity, OTP proof, IP, user-agent, transaction id, timestamps, hash metadata.
|
||||
4. Freeze deployment topology decision:
|
||||
- option 1 (Linux signing service), option 2 (PKCS#11 proxy), or option 3 (Windows-local SoftHSM).
|
||||
5. Define production host mapping:
|
||||
- where `EnvelopeGenerator.Server` runs,
|
||||
- where HSM/SoftHSM runs,
|
||||
- where certificate lifecycle is managed.
|
||||
|
||||
Deliverable: Technical decision record (ADR-style markdown).
|
||||
|
||||
## Phase 1 - PKCS#11 connector (infrastructure)
|
||||
|
||||
1. Define `IPkcs11Service` interface.
|
||||
2. Add `Pkcs11Interop` implementation.
|
||||
3. Add config model:
|
||||
- library path, slot, token label, key label, certificate label.
|
||||
4. Ensure secure secret handling for PIN.
|
||||
5. Ensure host-compatible module loading:
|
||||
- Windows server must load Windows DLL,
|
||||
- Linux server must load Linux `.so`.
|
||||
|
||||
Deliverable: Testable PKCS#11 service with health/slot/login/sign/verify capabilities.
|
||||
|
||||
## Phase 1.5 - Cross-host bridge implementation
|
||||
|
||||
1. If option 1 selected:
|
||||
- implement Linux signing service API contract (`/sign`, `/certificate`, `/health`),
|
||||
- implement authenticated HTTP client in `EnvelopeGenerator.Server`.
|
||||
2. If option 2 selected:
|
||||
- install/configure PKCS#11 proxy client DLL on Windows,
|
||||
- install/configure proxy server on Linux and bind to SoftHSM.
|
||||
|
||||
Deliverable: Windows-to-Linux signing communication path proven end-to-end.
|
||||
|
||||
## Phase 2 - Application use case
|
||||
|
||||
1. Add `SignDocumentHashCommand` (or equivalent).
|
||||
2. Pipeline flow:
|
||||
- compute/receive hash,
|
||||
- sign with HSM,
|
||||
- attach certificate context,
|
||||
- verify,
|
||||
- produce evidence object.
|
||||
3. Add resilient error mapping and retry strategy.
|
||||
|
||||
Deliverable: HSM signing use case in Application layer.
|
||||
|
||||
## Phase 3 - PDF signature embedding
|
||||
|
||||
1. Implement PDF signature embedding via `IPdfSignatureService`.
|
||||
2. Build signer-specific audit-trail pages.
|
||||
3. Append all audit pages to final PDF artifact.
|
||||
|
||||
Deliverable: Signed PDF with certificate context and audit trail pages.
|
||||
|
||||
## Phase 4 - Presentation/API integration
|
||||
|
||||
1. Integrate FES option into submit flow (feature flag guarded).
|
||||
2. Add operational endpoints:
|
||||
- HSM health/check
|
||||
- signature evidence query (restricted roles)
|
||||
3. Keep DTOs safe; avoid exposing sensitive cryptographic material.
|
||||
4. In `SignatureController.Submit`, add FES branch that sends signing payload + audit context to selected signing backend.
|
||||
|
||||
Deliverable: API-level orchestration with minimal UI disruption.
|
||||
|
||||
## Phase 5 - Audit, archive, distribution
|
||||
|
||||
1. Persist signature evidence records.
|
||||
2. Include hash/cert metadata in archival package.
|
||||
3. Add signed artifact reference to distribution e-mails.
|
||||
|
||||
Deliverable: Alignment with diagram steps 9-10.
|
||||
|
||||
## Phase 6 - Testing and operations
|
||||
|
||||
1. Postman collection + Newman automation.
|
||||
2. Positive/negative matrix:
|
||||
- wrong pin, wrong slot, missing cert, expired cert, HSM timeout.
|
||||
3. Observability:
|
||||
- structured logs, correlation id, latency metrics.
|
||||
|
||||
Deliverable: Production readiness checklist.
|
||||
|
||||
---
|
||||
|
||||
## 6) Transition strategy from test API to production flow
|
||||
|
||||
1. Keep `/api/pkcs11-test/*` only for non-production.
|
||||
2. In production, use the same internal services through business endpoints only.
|
||||
3. Roll out by feature flag:
|
||||
- `FesEnabled=false` initially
|
||||
- pilot sender group
|
||||
- full rollout
|
||||
|
||||
4. Keep explicit environment matrix:
|
||||
- local dev (option 3),
|
||||
- integration/staging (option 1 or 2),
|
||||
- production (option 1 or 2 only).
|
||||
|
||||
---
|
||||
|
||||
## 7) Risks and mitigations
|
||||
|
||||
- Certificate expiry risk -> proactive monitoring and renewal alerting.
|
||||
- HSM connectivity risk -> retry policy, circuit breaker, fallback queue.
|
||||
- PIN/secret exposure risk -> vault-backed secrets and rotation policy.
|
||||
- Verification failure risk -> block PDF sealing and move envelope to technical hold state.
|
||||
- Cross-host connectivity risk -> mTLS/JWT auth + timeout/retry/circuit breaker + health probe.
|
||||
|
||||
---
|
||||
|
||||
## 8) Short done checklist
|
||||
|
||||
- [ ] PKCS#11 service interface + implementation
|
||||
- [ ] Application command + pipeline behaviors
|
||||
- [ ] PDF signature embedding
|
||||
- [ ] Audit-trail generation
|
||||
- [ ] API integration + feature flag
|
||||
- [ ] Postman/Newman regression suite
|
||||
- [ ] Operational runbook and alerting rules
|
||||
Reference in New Issue
Block a user