Cryptographic Signing Service
Relevant source files
The following files were used as context for generating this wiki page:
The Cryptographic Signing Service is a core security component of the TrueLens platform designed to provide document authenticity and tamper detection. It enables the system to generate unique digital fingerprints for documents and secure them using asymmetric cryptography, ensuring that any modification to the original file can be detected by the Verification System.
The service facilitates the creation of a "Security Ledger" by signing document hashes and issuing evidence packs that include public keys and verifiable timestamps. This ensures that documents like Aadhaar cards, invoices, and legal contracts maintain their integrity after being analyzed by the platform.
Sources: truelens-backend/app/services/document_signing.py, truelens-backend/app/services/evidence_pack.py:31, truelens-app/src/app/documents/page.tsx:244-250
Architecture and Key Management
The signing architecture centers around the KeyManager class, which abstracts the complexity of cryptographic primitive initialization and signing operations. It supports multiple asymmetric algorithms to provide flexibility and future-proofing.
KeyManager Implementation
The KeyManager is responsible for generating and holding the signing keys. While the current implementation generates keys in-memory, it is architected to interface with Hardware Security Modules (HSM) or cloud services like AWS KMS in production environments.
The diagram shows the KeyManager class structure and its relationship with various cryptographic algorithms.
Sources: truelens-backend/app/services/document_signing.py:22-30
Supported Algorithms
The service defaults to high-performance Edwards-curve Digital Signature Algorithm (Ed25519) but provides fallbacks and alternatives via environment configuration.
| Algorithm | Implementation Detail | Use Case |
|---|---|---|
| Ed25519 | Default; fast signatures with small keys | General document signing |
| RSA-4096 | Uses PSS padding and SHA-256 | Legacy compatibility |
| ECDSA | Uses SECP256R1 (NIST P-256) | Standard elliptic curve signing |
Sources: truelens-backend/app/services/document_signing.py:16-19, truelens-backend/app/services/document_signing.py:46-60
Document Hashing and Signing Workflow
The signing process follows a standard hash-then-sign paradigm to ensure efficiency regardless of document size.
The Signing Pipeline
- Hash Generation: The service computes a SHA-256 fingerprint of the raw document bytes.
- Cryptographic Signing: The
KeyManagersigns the resulting hex string using the active private key. - Metadata Association: The signature is packaged with a UTC timestamp and the public key required for later verification.
The flow represents the transformation of raw document data into a verifiable cryptographic signature.
Sources: truelens-backend/app/services/document_signing.py:65-85
Implementation Example
The following snippet demonstrates how document hashes are signed and packaged into a metadata dictionary.
def sign_document_hash(doc_hash: str) -> dict:
"""Signs the document hash and returns signature metadata."""
signature_bytes = key_manager.sign(doc_hash.encode('utf-8'))
return {
"signature": signature_bytes.hex(),
"public_key": key_manager.get_public_key_pem(),
"timestamp": datetime.now(timezone.utc),
"algorithm": SIGNING_ALGORITHM
}
Sources: truelens-backend/app/services/document_signing.py:73-85
Verification System
The verification system allows users and external applications to validate the authenticity of a document using its original hash and the issued signature.
Verification Logic
Verification is handled by verify_document_signature. It loads the PEM-encoded public key and uses the corresponding algorithm's verification logic to confirm the signature was produced by the TrueLens private key for that specific hash.
Frontend Verification Interface
Users can verify documents via a dedicated UI that supports manual entry of SHA-256 hashes or scanning QR codes from Evidence Packs.
- Endpoint:
POST /api/v1/verify - Request Body:
{ "hash": "a3f2b8c9d1e4f5...", "scanId": "optional_doc_id" }
Sources: truelens-app/src/app/developers/page.tsx:37-43, truelens-app/src/app/verify/page.tsx:106-125
Evidence Packs and QR Verification
For documents deemed authentic, the service generates an "Evidence Pack"—a verifiable bundle containing a manifest and a QR code for mobile verification.
Evidence Pack Components
The evidence pack includes:
- JSON Manifest: Contains the document ID, SHA-256 hash, trust score, and cryptographic signature.
- QR Code: A Base64-encoded PNG containing a URL that points to the TrueLens verification portal with the document hash pre-filled.
- Issuer: Labeled as "TrueLens Security Ledger".
Sources: truelens-backend/app/services/evidence_pack.py:19-40
Manifest Structure
| Field | Description |
|---|---|
document_id | Unique identifier for the scan |
hash_sha256 | The fingerprint of the document |
signature | The hex-encoded digital signature |
public_key | PEM-encoded key used for validation |
findings | List of analysis results (e.g., tamper detection hits) |
Sources: truelens-backend/app/services/evidence_pack.py:23-32, truelens-app/src/lib/types.ts:60-67
Summary
The Cryptographic Signing Service provides the final layer of the TrueLens trust pipeline. By combining robust document analysis with Ed25519 digital signatures, the service ensures that once a document is verified, its status is permanently and cryptographically provable. The integration of QR-based evidence packs allows for seamless physical-to-digital verification, making it a critical tool for identifying fraudulent documents and maintaining data integrity.