How cossacklabs/acra works
Project Type and Purpose
• Acra is a distributed, microservice-based database security suite written in Go. It provides application-level field encryption, masking, tokenization, SQL firewall, and intrusion detection for relational and NoSQL datastores.
• Key use cases: transparent SQL proxy (AcraServer), encryption-as-a-service API (AcraTranslator), optional transport layer (AcraConnector), client-side SDKs (AcraWriter/AcraReader), and key management utilities.
File Structure Insights
• cmd/… each “cmd/acra-*” directory is a standalone Go service or CLI (acra-server, acra-translator, acra-keys, acra-rotate, etc.).
• encryptor/ and decryptor/ subdirectories: core encryption/decryption logic for MySQL and PostgreSQL protocols.
• keystore/: pluggable storage backends (filesystem, Redis, Vault, AWS KMS).
• network/: wrappers for TLS, Prometheus metrics, GRPC/HTTP servers.
• wrappers/ and examples/: client-side SDKs and sample integrations in various languages.
• configs/ and docker/: deployment manifests, Dockerfiles, and compose files.
• tests/: end‐to‐end integration scenarios with real databases, Consul/Vault, Redis, SSL stacks.
a. Client Applications (Web, Mobile, CLI)
• May embed AcraWriter/AcraReader SDKs for client-side encryption/decryption.
• Or speak plain SQL/HTTP/gRPC to AcraServer/AcraTranslator.
b. AcraConnector (optional)
• Authenticates and terminates TLS for client-to-Acra traffic.
c. AcraServer (SQL Proxy)
• Listens on SQL port, parses queries, applies encryption/masking/tokenization via decryptor/ encryptor modules, enforces SQL firewall, logs events.
• Pulls keys from Key Storage and Master Key Storage when needed.
• Forwards modified queries to the target database (MySQL/PostgreSQL).
d. AcraTranslator (HTTP/gRPC API)
• Exposes REST/gRPC endpoints for encrypt/decrypt/tokenize/detokenize.
• Uses the same core encryptor/decryptor libraries.
e. Datastores
• Primary: SQL databases (MySQL, PostgreSQL), NoSQL, S3, etc.
• Key Storage: Redis or a table in the database, stores encrypted data keys and configuration.
• Master Key Storage: AWS KMS, Google KMS, HashiCorp Vault, HSM (external service).
f. Supporting Services
• Prometheus: metrics from network/, common/prometheus.go.
• Jaeger: tracing via network/tracing.go.
• Logging: structured audit and integrity logs (logging/).
• CI/CD: CircleCI scripts in .circleci/, Docker build scripts.
• Key Management Utilities: cmd/acra-keymaker, cmd/acra-rotate, cmd/acra-backup, cmd/acra-rollback.
Component Interactions and Data Flows
• Client → (TLS) → AcraConnector → (plain SQL/TLS-wrapped) → AcraServer → Database → AcraServer → Client
• Client → (HTTPS/gRPC) → AcraTranslator → Key Storage + Master Key Storage → AcraTranslator → Client → Database
• CLI utilities interact with Master Key Storage and Key Storage to provision and rotate encryption keys.
• Throughout, network/ modules handle TLS, connection pools, and metrics.
• Prometheus scrapes endpoints on AcraServer, AcraTranslator, and network wrappers; logs flow to ELK or output files.
Architectural Patterns and Principles
• Microservices: each “cmd/acra-*” is a separate process with a single responsibility.
• Proxy Pattern: AcraServer intercepts and transforms SQL traffic transparently.
• Adapter/Plugin: encryptor/ and decryptor/ have protocol-specific adapters for MySQL/PostgreSQL.
• Separation of Concerns: key storage, crypto logic, network I/O, and business logic are in distinct packages.
• Configuration-Driven: configs/ and acra-*.yaml define encryption rules, firewall policies, and storage backends.
• Defense in Depth: layered encryption, SQL firewall, intrusion detection via poison records.