# 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).

- `EnvelopeGenerator.Infrastructure`:
  - 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