229 lines
8.3 KiB
Markdown
229 lines
8.3 KiB
Markdown
# 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
|