How eballester/certtools works
1. Project type and purpose
- CertTools is a small, file-processing web application focused on certificate operations: building PFX/PKCS#12 bundles and removing passwords from private keys or PFX files.
- The architecture is intentionally simple: a browser UI talks to a FastAPI backend that runs OpenSSL-based transformations.
2. Top-level split: frontend vs backend
- The repository is divided into a static frontend (frontend/) and a Python backend (backend/).
- The frontend is responsible for user interaction, file selection/drag-and-drop, and showing download results.
- The backend owns validation, cryptographic checks, file conversion, and cleanup.
3. Backend application entry point
- backend/main.py is the FastAPI entry point.
- It likely creates the API app, wires in the routers, and exposes the service on port 8000 as described in the README.
- This is the main composition boundary for the backend.
4. Feature-based backend routing
- The backend is split into two domain routers under backend/routers/:
- pfx_generator.py for creating PKCS#12/PFX bundles
- key_decryptor.py for password removal / extraction workflows
- This suggests each tool is isolated as its own API surface rather than being mixed into one handler set.
5. Shared backend utilities
- backend/utils.py contains shared helper logic used by both routers.
- Based on the README, this likely covers temporary file handling, OpenSSL command execution, validation helpers, and common response/download preparation.
- This is the main internal reuse boundary inside the backend.
6. PFX generation flow
- User uploads certificate material from the frontend.
- The backend validates PEM formatting, checks that the private key matches the certificate, and verifies chain/CA trust.
- If validation passes, the backend generates a .pfx file and returns it as a downloadable response.
- This flow is centered around X.509 artifacts and OpenSSL processing.
7. Password removal / decryption flow
- The decryptor route handles two distinct inputs:
- Encrypted private keys (.key, .pem) and returns a decrypted key.
- PFX files (.pfx) and extracts the key/certificate into a .zip archive.
- The ZIP-based output for PFX decryption is a deliberate UX boundary to avoid import issues with passwordless PFX files.
8. Frontend architecture
- The frontend is a plain static client: index.html, style.css, and script.js.
- script.js is the bridge to the backend API, handling upload interactions and response downloads.
- There is no frontend framework or client-side state system visible in the tree, so the UI is likely lightweight and purpose-built.
9. Processing model and security boundary
- All sensitive processing happens server-side in temporary directories only.
- The README explicitly says files are deleted immediately after the output is generated and nothing is persisted to disk or a database.
- This means the primary security boundary is “browser upload → ephemeral backend processing → download response.”
10. External dependency model
- The main runtime dependency is Python 3.9+ with FastAPI/Uvicorn and OpenSSL available.
- The core cryptographic work appears to be delegated to standard OpenSSL commands rather than custom crypto code, which keeps the architecture simple and auditable.
11. Deployment packaging
- The project is containerized with a Dockerfile, and docker-compose.yml is available for local orchestration.
- The documented runtime model is a single container exposing port 8000.
- This suggests the app is designed as one self-contained service rather than multiple deployable services.
12. CI/CD and distribution
- .github/workflows/docker-publish.yml indicates automated Docker image publishing.
- The deployment artifact is therefore likely the container image, not a packaged Python wheel or frontend bundle.
13. What to show in an architecture diagram
- The main diagram should have:
- Browser/UI
- FastAPI backend
- Two backend feature modules: PFX Generator and Key Decryptor
- A shared utilities layer
- OpenSSL / system crypto tools
- Temporary filesystem workspace
- The key arrow is from UI uploads to backend processing and back as downloadable files, with no database in the middle.
14. Key architectural constraint
- This is a stateless, request/response, file-transform service.
- There are no long-lived user sessions, persistence layer, or asynchronous job queue visible in the repository.
- That keeps the design compact and makes each request self-contained from upload to cleanup.
Main entry points: main.py FastAPI App · utils.py Shared Utils · script.js Client Bridge · pfx_generator.py PFX Generator
Components 14
Frontend
Static browser client for upload, conversion requests, and downloads.
- Browser UI · User-facing page for selecting files and starting certificate workflows.
frontend/index.html - Client Bridge · Handles upload interactions and calls the backend API.
frontend/script.js - Styles · Visual styling for the static client.
frontend/style.css
Backend
FastAPI application and feature routers for certificate transforms.
- FastAPI App · Composes the backend service and exposes the HTTP API.
backend/main.py - PFX Generator · API surface for building PKCS#12 / PFX bundles.
backend/routers/pfx_generator.py - Key Decryptor · API surface for password removal and extraction workflows.
backend/routers/key_decryptor.py - Shared Utils · Common validation, temp-file, and OpenSSL orchestration helpers.
backend/utils.py - OpenSSL · External command-line crypto engine used for certificate transformations.
- Temp Workspace · Short-lived filesystem area used for request-scoped processing and cleanup.
- Downloads · Generated PFX, key, or ZIP outputs returned to the browser.
Delivery
Containerization and automated image publishing.
- Dockerfile · Builds the single-service container image.
Dockerfile - Compose · Runs the service locally as a containerized app.
docker-compose.yml - Publish Workflow · Automates Docker image publication.
.github/workflows/docker-publish.yml - Dependencies · Python runtime and package requirements for the backend service.
requirements.txt
Connections 15
- Browser UI → Client Bridge: interacts with · The page and scripts coordinate upload and download behavior.
- Client Bridge → FastAPI App: API calls · The client sends file-processing requests to the FastAPI backend.
- FastAPI App → PFX Generator: mounts · The application wires in the PFX generation routes.
- FastAPI App → Key Decryptor: mounts · The application wires in the key decryption routes.
- PFX Generator → Shared Utils: uses · Generation logic shares validation and file-handling helpers.
- Key Decryptor → Shared Utils: uses · Decrypt/extract logic shares validation and file-handling helpers.
- Shared Utils → OpenSSL: executes · Shared helpers delegate cryptographic work to OpenSSL.
- Shared Utils → Temp Workspace: writes to · Processing happens in request-scoped temporary files only.
- PFX Generator → Downloads: returns · Successful generation produces a downloadable PFX file.
- Key Decryptor → Downloads: returns · Successful decryption returns a key or ZIP archive.
- Client Bridge → Downloads: triggers download · The browser downloads the generated artifact from the response.
- Dockerfile → FastAPI App: packages · The container image bundles the backend service.
- Compose → Dockerfile: runs · Local orchestration starts the built container.
- Publish Workflow → Dockerfile: builds · CI publishes the container image from the Docker build.
- Dependencies → FastAPI App: supplies deps · Python packages support the FastAPI backend runtime.