DVault

DVault is a Docker-based secrets manager that provides a secure REST API for storing and retrieving encrypted secrets. Built with Rust and Redis, DVault offers high performance and enterprise-grade security for managing sensitive data.

Features

• REST API: Simple HTTP API for secret management
• Encryption: AES-256-GCM encryption for all stored secrets
• Redis Backend: Fast, reliable storage with Redis
• Docker Native: Containerized deployment with Docker Compose
• Schema-First: JSON Schema-driven API design with type-safe code generation

Architecture Overview

graph TB
    subgraph "DVault Server"
        A[Client Request] --> B[Actix-web Handler]
        B --> C{Request Type}
        
        C -->|Set Cipher Key| D[Validate Key]
        D --> E[Store in AppData]
        E --> F[Return Success]
        
        C -->|Secret Operation| G[Get AppData]
        G --> H[Create DVault Instance]
        H --> I[Apply Cipher Key]
        I --> J[Perform Operation]
        
        subgraph "Shared State"
            E -.-> K[AppData.cipher_key<br/>RwLock&lt;Option&lt;String&gt;&gt;]
            G -.-> K
        end
        
        subgraph "Storage"
            J --> L[(Redis)]
        end
    end
    
    style K fill:#f9f,stroke:#333,stroke-width:2px
    style L fill:#ff9,stroke:#333,stroke-width:2px

Loading

Quick Start

Prerequisites

• Docker and Docker Compose
• Make (for build automation)
• Rust (for local development)

Running DVault

1. Clone the repository

   git clone https://github.com/cabeaulac/dvault
   cd dvault

2. Configure environment (optional)

   cd src/rust/dvault
   # Create a .env file with your Docker registry settings
   cat > .env << EOF
   USERNAME=your-docker-username
   NAMESPACE=dvault
   REGISTRY=ghcr.io
   # CR_PAT=your_github_token_here
   EOF

3. Generate schemas and build

   cd ../../..  # Back to project root
   make gen-schemas
   cd src/rust/dvault
   make build-local-dev

4. Start services

   make compose-up

5. DVault is now running

   • HTTP: http://localhost:8080

API Endpoints

DVault provides the following REST API endpoints:

• POST /api/v1/cipher-key - Set the master encryption key (stored in app state)
• POST /api/v1/secret - Store a new secret
• POST /api/v1/secret/get - Retrieve a secret by key
• GET /api/v1/secrets - List all secret keys
• DELETE /api/v1/secret/{key} - Delete a secret

Example Usage

# Set cipher key (persists in app state)
curl -X POST http://localhost:8080/api/v1/cipher-key \
  -H "Content-Type: application/json" \
  -d '{"key": "your-encryption-key"}'

# Store a secret
curl -X POST http://localhost:8080/api/v1/secret \
  -H "Content-Type: application/json" \
  -d '{"key": "db-password", "value": "super-secret-password"}'

# Retrieve a secret
curl -X POST http://localhost:8080/api/v1/secret/get \
  -H "Content-Type: application/json" \
  -d '{"key": "db-password"}'

Development

Project Structure

dvault/
├── schemas/                    # JSON Schema definitions
├── src/rust/dvault/           # Rust workspace
│   ├── dvault_bin/            # Main API server binary
│   ├── dvault_lib/            # Core encryption/storage library
│   ├── dvault_schema_lib/     # Generated schema types
│   └── docker-compose.yml     # Development environment
├── Makefile                   # Root build automation
└── CLAUDE.md                  # Development guide

Building from Source

# Build all components
cd src/rust/dvault
# Build and run tests
make build-local-dev

# Run tests without build
make test

Running Tests

# Run unit tests with cargo
cargo test

# Run integration tests
make test

Manual Testing with Docker Compose

DVault includes a test environment with an Alpine container for manual API testing:

# Start the test environment
make compose-test-up

# Access the test client container
docker exec -it test-client sh

# Inside the container, test the API:
# Health check
curl http://dvault:8080/health

# Set cipher key
curl -X POST http://dvault:8080/api/v1/cipher-key \
  -H "Content-Type: application/json" \
  -d '{"key": "test-encryption-key-123"}'

# Store a secret
curl -X POST http://dvault:8080/api/v1/secret \
  -H "Content-Type: application/json" \
  -d '{"key": "test-secret", "value": "my-secret-value"}' | jq

# Retrieve a secret
curl -X POST http://dvault:8080/api/v1/secret/get \
  -H "Content-Type: application/json" \
  -d '{"key": "test-secret"}' | jq

# List all secrets
curl http://dvault:8080/api/v1/secrets | jq

# Stop the test environment
exit
make compose-test-down

The test client includes curl and jq pre-installed for easy API testing.

Configuration

Environment Variables

DVault runtime can be configured using environment variables:

• REDIS_HOST - Redis server hostname (default: redis)
• REDIS_PORT - Redis server port (default: 6379)
• HTTP_PORT - HTTP server port (default: 8080)

Build Configuration

For Docker registry and deployment, configure the .env file in src/rust/dvault/:

# Create .env file with your settings
cd src/rust/dvault
cat > .env << EOF
USERNAME=your-docker-username
NAMESPACE=dvault
REGISTRY=ghcr.io
# CR_PAT=your_github_token_here
EOF

Required variables in .env:

• USERNAME - Docker registry username (default: cabeaulac)
• NAMESPACE - Docker image namespace (default: dvault)
• REGISTRY - Docker registry URL (default: ghcr.io)
• CR_PAT - GitHub Container Registry Personal Access Token (required for pushing images)

To generate a GitHub token:

1. Go to https://github.com/settings/tokens
2. Create a token with write:packages permission
3. Add it to your .env file as CR_PAT=your_token_here

Security Considerations

• Encryption: All secrets are encrypted using AES-256-GCM before storage
• Key Management: Master encryption key is stored in application state (memory only)
• Key Persistence: Cipher keys persist across HTTP requests within the same server instance
• Network Security: HTTPS recommended for production deployments
• Access Control: Consider implementing authentication/authorization
• Data at Rest: Redis persistence should be configured appropriately

Deployment

Production Deployment

1. Build production images

   cd src/rust/dvault
   make docker-push-prod

2. Deploy with Docker Compose

   make deploy-build
   # Transfer dvault-deploy.tar.gz to production server

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For questions and support, please open an issue on GitHub.