How sagiri2004/live-caller-id-lookup-demo works
Project Type and Purpose
– This is a backend microservice (written in Go) that exposes a RESTful HTTP API for Private Information Retrieval (PIR) on an encrypted database.
– It uses the Lattigo v4 library to perform BFV homomorphic‐encryption operations, letting clients retrieve database entries without revealing which entry is accessed.
File‐Structure Analysis
Top‐level files & dirs:
• main.go → HTTP server + handler bootstrapping
• go.mod, go.sum → Go module dependencies (incl. Lattigo)
• Makefile → build/test scripts
• client/ → standalone Go client binary (client/main.go) to invoke the PIR service
• encryption_database/ (implied in README) → JSON config + encrypted data files (.bin, .txtpb)
– Other code files (per README):
• pir_client.go → client library for service calls
• database_utils.go → load/validate database, stats, search utility functions
README Insights
– Defines four logical subsystems:
a) PIR Service (HTTP API + request routing)
b) Database Utils (file‐I/O, integrity checks, in‐memory loading)
c) Homomorphic‐Encryption Engine (Lattigo BFV operations)
d) PIR Client (Go library + binary for testing/integration)
– External dependency: Lattigo v4 for encryption; file‐based encryption_database inputs.
Main Components
– External PIR Client (Go CLI or library)
– HTTP API Layer (main.go):
• Endpoints: /health, /config, /query
– PIR Handler Module (in main.go or a dedicated service package)
– Database Utils Module (database_utils.go): load, validate, retrieve entry by index
– Encryption Engine (Lattigo BFV): key‐gen, encrypt/decrypt, homomorphic ops
– Configuration Loader: reads encryption_database/pir_config.json
– Encryption Database Storage:
• pir-parameters-*.txtpb, block_database-*.bin, evaluation-key-config.txtpb
Interactions & Data Flow
1) Client → HTTP POST /query (payload: { "index": N })
2) API Layer parses request → invokes PIR Handler
3) PIR Handler uses Database Utils to locate and load the requested block from disk (or memory cache)
4) Handler calls Encryption Engine (Lattigo) to perform homomorphic retrieval (e.g., BFV “Rotate” + “Mul” operations)
5) Assembles encrypted response payload → HTTP response → Client
6) Client uses its local decryption ability (via evaluation keys) to recover plaintext data
Architectural Patterns & Principles
– Layered Architecture: clearly separate API, business logic (PIR Handler), data access (Database Utils), and crypto engine.
– Configuration‐Driven: JSON config drives algorithm parameters and file paths.
– Single‐Responsibility Modules: each Go file/package has one focus (API, client, utils).
– In‐Memory Caching: database loaded into memory for performance (per README).