Qalá LogoQaláv0.9.0
Back to Documentation

Core Concepts

This guide explains the fundamental concepts and architecture of Qalá's secrets management system.

Secrets Management Fundamentals

What is a Secret?

In Qalá, a secret is any sensitive information that needs protection, including:

  • API keys and tokens
  • Database credentials
  • Private keys and certificates
  • Connection strings
  • Configuration values with security implications

Secrets are distinct from regular configuration by their sensitive nature and security requirements.

The Secret Lifecycle

Every secret in Qalá follows a lifecycle:

  1. Creation: Initial secure generation or storage
  2. Access: Controlled retrieval and usage
  3. Rotation: Periodic or event-triggered updates
  4. Revocation: Controlled invalidation
  5. Deletion: Secure removal from storage

Qalá provides tools to manage each stage of this lifecycle securely.

Qalá Architecture

System Components

Qalá consists of several core components:

  • Client SDK: Libraries for different programming languages
  • CLI: Command-line interface for developers
  • API Server: Central service managing secret storage and retrieval
  • Storage Backend: Encrypted persistent storage
  • Auth Service: Authentication and authorization

These components work together to provide a comprehensive secrets management solution.

Security Model

Qalá's security is built on several principles:

End-to-End Encryption

All secrets are encrypted before transmission and remain encrypted at rest:

  1. Client-side encryption using AES-256-GCM
  2. TLS for all network communications
  3. Encrypted storage even in the backend database

Multiple Authentication Methods

Qalá supports various authentication mechanisms:

  • API keys for service accounts
  • JWT tokens for users
  • OAuth integration for SSO (Business/Enterprise)
  • IP-based restrictions

Access Control

Fine-grained permissions control who can access which secrets:

  • User-level permissions
  • Team-based access
  • Role-based access control (RBAC)
  • Environment-based segmentation

Key Concepts

Projects

A project is the top-level organizational unit in Qalá, typically representing an application or service. Projects contain:

  • A collection of secrets
  • Environment configurations
  • Team members and access controls
  • Audit logs and settings

Environments

Environments separate secrets for different deployment stages:

  • Development
  • Staging
  • Production
  • Custom environments

Each environment has its own isolated set of secrets, allowing for proper separation of concerns.

Secret Versioning

Qalá maintains a history of changes to each secret:

  • Each update creates a new version
  • Previous versions are retained based on policy
  • Version history enables auditing and rollback

Encryption Keys

Qalá uses a hierarchical key structure:

  • Master Keys: Protect the key encryption keys
  • Key Encryption Keys (KEKs): Encrypt the data encryption keys
  • Data Encryption Keys (DEKs): Encrypt the actual secrets

This structure enables secure key rotation and compartmentalization.

Working Models

Qalá supports different operational models to fit various needs:

Standalone Mode

A complete, self-contained secrets management system:

  • Independent server deployment
  • Dedicated encryption keys
  • Full control over all aspects

Ideal for organizations requiring complete control of their security infrastructure.

Integrated Mode

Designed to work alongside existing systems:

  • Connects to existing authentication systems
  • Can use external key management services
  • Integrates with CI/CD pipelines

Perfect for organizations with established security infrastructure.

Environment Provider Mode

Focused solely on injecting secrets into applications:

  • Lightweight deployment
  • Minimal configuration
  • Optimized for development workflows

Best for development teams seeking simplicity.

Best Practices Foundations

Understanding these core concepts enables effective implementation of best practices:

Principle of Least Privilege

  • Grant minimal access required for each user/service
  • Time-bound access when possible
  • Regular access review

Secret Isolation

  • Separate secrets by environment
  • Unique secrets for different services
  • Avoid secret reuse across projects

Audit and Compliance

  • Comprehensive logging of all actions
  • Non-repudiation of secret access
  • Retention policies aligned with compliance requirements

Technical Implementation Details

Secret Storage

Secrets are stored using a layered approach:

  1. Secret value encrypted with a unique Data Encryption Key (DEK)
  2. DEK encrypted with a Key Encryption Key (KEK)
  3. Metadata stored separately from encrypted values
  4. Optional hardware security module (HSM) integration

Client-Server Communication

All communication follows secure protocols:

  1. Mutual TLS authentication
  2. JWT-based authorization
  3. Rate limiting to prevent brute force attacks
  4. Encrypted payload even over TLS

High Availability

For production deployments, Qalá supports:

  • Multi-node clustering
  • Database replication
  • Geographical redundancy
  • Automatic failover

Next Steps

Now that you understand Qalá's core concepts, you can explore: