secretumvault/docs/development/build-features.md

Build Features & Configuration

Cargo features and build options for SecretumVault.

Quick Build Commands

Standard Build (OpenSSL only)

cargo build --release

Default compilation: OpenSSL crypto, filesystem storage, basic features.

Full Featured Build

cargo build --release --all-features

Enables: All crypto backends, all storage backends, Cedar policies, everything.

Minimal Build

cargo build --release --no-default-features

Bare minimum for development testing.

Custom Features

cargo build --release --features aws-lc,pqc,postgresql-storage,etcd-storage

---

Available Features

Cryptography Features

aws-lc (Post-Quantum Ready)

Status: ✅ Complete Requires: Feature flag Adds: 20 KB binary size Depends on: aws-lc-rs crate

Enables AWS-LC cryptographic backend:

• RSA-2048, RSA-4096
• ECDSA P-256, P-384, P-521
• Key generation and encryption

cargo build --features aws-lc

Use in config:

[vault]
crypto_backend = "aws-lc"

pqc (Post-Quantum Cryptography)

Status: ✅ Complete Requires: Feature flag + aws-lc Adds: 100 KB binary size NIST Standard: ML-KEM-768, ML-DSA-65

Enables post-quantum algorithms:

• ML-KEM-768 (key encapsulation mechanism - KEM)
• ML-DSA-65 (digital signatures)
• Requires aws-lc feature enabled
• Requires Rust feature flags

cargo build --features aws-lc,pqc

Use in config:

[vault]
crypto_backend = "aws-lc"

Then select PQC algorithms in policy/usage (implementation in engines).

rustcrypto (Planned)

Status: 🔄 Planned Description: Pure Rust cryptography

Pure Rust implementation without FFI dependencies.

# cargo build --features rustcrypto  # Not yet implemented

Storage Features

etcd-storage (Distributed HA)

Status: ✅ Complete Requires: Feature flag Adds: 2 MB binary size Depends on: etcd-client crate

Enables etcd storage backend:

• Distributed key-value store
• High availability with multiple nodes
• Production-ready

cargo build --features etcd-storage

Use in config:

[storage]
backend = "etcd"

[storage.etcd]
endpoints = ["http://localhost:2379"]

surrealdb-storage (Document Store)

Status: ✅ Complete (in-memory) Requires: Feature flag Adds: 1 MB binary size Depends on: surrealdb crate

Enables SurrealDB storage backend:

• Document database with rich queries
• In-memory implementation (stable)
• Real SurrealDB support can be added

cargo build --features surrealdb-storage

Use in config:

[storage]
backend = "surrealdb"

[storage.surrealdb]
url = "ws://localhost:8000"

postgresql-storage (Relational)

Status: ✅ Complete Requires: Feature flag Adds: 1.5 MB binary size Depends on: sqlx with postgres driver

Enables PostgreSQL storage backend:

• Industry-standard relational database
• Strong consistency guarantees
• Production-ready

cargo build --features postgresql-storage

Use in config:

[storage]
backend = "postgresql"

[storage.postgresql]
connection_string = "postgres://vault:pass@localhost:5432/secretumvault"

Feature Combinations

Development (all backends, testing only):

cargo build --all-features

Binary size: ~30 MB Features: OpenSSL, AWS-LC, PQC, etcd, SurrealDB, PostgreSQL, filesystem, Cedar

Production - High Security:

cargo build --release --features aws-lc,pqc,etcd-storage

Binary size: ~15 MB Includes: Post-quantum crypto, distributed storage

Production - Standard:

cargo build --release --features postgresql-storage

Binary size: ~8 MB Includes: OpenSSL crypto, PostgreSQL storage

Minimal (OpenSSL only):

cargo build --release

Binary size: ~5 MB Includes: OpenSSL, filesystem storage

---

Default Features

When building without --no-default-features:

default = ["server", "cli"]

• server - Enables HTTP server
• cli - Enables command-line tools

---

Feature Dependencies

[aws-lc]
  ├── aws-lc-rs crate
  └── openssl (system dependency)

[pqc]
  ├── aws-lc (required)
  ├── ml-kem-768 support
  └── ml-dsa-65 support

[etcd-storage]
  ├── etcd-client crate
  └── tokio async runtime

[surrealdb-storage]
  ├── surrealdb crate
  └── tokio async runtime

[postgresql-storage]
  ├── sqlx crate
  ├── postgres driver
  └── tokio async runtime

---

Cargo.toml Configuration

View in root Cargo.toml:

[features]
default = ["server", "cli"]

# Crypto backends
aws-lc = ["aws-lc-rs", "openssl"]
pqc = ["aws-lc"]
rustcrypto = ["rust-crypto"]

# Storage backends
etcd-storage = ["etcd-client"]
surrealdb-storage = ["surrealdb"]
postgresql-storage = ["sqlx"]

# Components
server = ["axum", "tokio-util"]
cli = ["clap", "colored"]
cedar = ["cedar-policy"]

[dependencies]
# Core
tokio = { version = "1", features = ["full"] }
axum = { version = "0.7", optional = true }
serde = { version = "1", features = ["derive"] }

# Optional crypto
aws-lc-rs = { version = "1.15", optional = true }

# Optional storage
etcd-client = { version = "0.17", optional = true }
surrealdb = { version = "1.0", optional = true }
sqlx = { version = "0.7", features = ["postgres", "runtime-tokio-native-tls"], optional = true }

# Optional CLI
clap = { version = "4", features = ["derive"], optional = true }

---

Conditional Compilation

Features enable conditional code:

#[cfg(feature = "aws-lc")]
pub mod aws_lc;

#[cfg(feature = "aws-lc")]
pub fn create_aws_lc_backend() -> Result<Box<dyn CryptoBackend>> {
    Ok(Box::new(AwsLcBackend::new()?))
}

#[cfg(feature = "pqc")]
pub fn has_pqc_support() -> bool {
    true
}

#[cfg(not(feature = "pqc"))]
pub fn has_pqc_support() -> bool {
    false
}

Registry dispatch fails gracefully if feature not enabled:

pub fn create(backend: &str) -> Result<Box<dyn CryptoBackend>> {
    match backend {
        "openssl" => Ok(Box::new(OpenSSLBackend::new()?)),
        "aws-lc" => {
            #[cfg(feature = "aws-lc")]
            return Ok(Box::new(AwsLcBackend::new()?));

            #[cfg(not(feature = "aws-lc"))]
            return Err(ConfigError::FeatureNotEnabled("aws-lc"));
        }
        unknown => Err(ConfigError::UnknownBackend(unknown.to_string()))
    }
}

---

Build Optimization

Release Build

cargo build --release

Optimizations:

• Optimize for speed (opt-level = 3)
• Strip debug symbols
• Link time optimization (LTO)
• ~50% smaller, 2-3x faster than debug

Debug Build

cargo build

Use for development:

• Full debug symbols
• Fast compilation
• Easier debugging

Optimized for Size

cargo build --release -Z unstable-options --space-opt

Reduces binary size for container deployments.

Profiling Build

RUSTFLAGS="-g" cargo build --release

Keeps debug symbols for profiling tools.

---

Dependency Management

Check for Vulnerabilities

cargo audit

Scans dependencies for known security issues.

Update Dependencies

cargo update

Updates to latest compatible versions.

Verify Dependencies

cargo tree

Shows dependency tree and versions.

cargo tree --duplicates

Identifies duplicate dependencies.

---

Feature-Specific Testing

Test with All Features

cargo test --all-features

Runs all tests with every feature enabled.

Test Specific Feature

cargo test --features aws-lc,pqc

Tests only with those features.

Test Minimal Build

cargo test --no-default-features

Tests core functionality without optional features.

---

Docker Build Optimization

Multi-stage Build with Minimal Runtime

# Stage 1: Builder
FROM rust:1.82-alpine as builder
RUN apk add --no-cache libssl-dev
WORKDIR /build
COPY . .
RUN cargo build --release --features aws-lc,pqc,etcd-storage

# Stage 2: Runtime
FROM alpine:latest
RUN apk add --no-cache libssl3 ca-certificates
COPY --from=builder /build/target/release/svault /usr/local/bin/
ENTRYPOINT ["svault"]

Results:

• Builder stage: ~500 MB
• Runtime image: ~50 MB (with all libraries)

Feature-Specific Docker Images

Development (all features):

docker build -t vault-dev --build-arg FEATURES="--all-features" .

Production (minimal):

docker build -t vault-prod --build-arg FEATURES="--release" .

---

Benchmark Features

Enable Benchmarking

cargo bench --all-features

Benchmarks operations with all features enabled.

Specific Benchmark

cargo bench encrypt --features aws-lc,pqc

Benchmark encryption operations with PQC.

---

Cross-Compilation

Build for Different Architecture

# ARM64 (aarch64)
cargo build --release --target aarch64-unknown-linux-gnu

# x86-64
cargo build --release --target x86_64-unknown-linux-gnu

# macOS ARM (Apple Silicon)
cargo build --release --target aarch64-apple-darwin

Install target:

rustup target add aarch64-unknown-linux-gnu

---

Feature Combinations Reference

Build	Command	Binary Size	Use Case
Minimal	cargo build --release	~5 MB	Testing, education
Standard	cargo build --release --features postgresql-storage	~8 MB	Production standard
HA	cargo build --release --features etcd-storage	~9 MB	High availability
Secure	cargo build --release --features aws-lc,pqc,postgresql-storage	~18 MB	Post-quantum production
Full	cargo build --all-features	~30 MB	Development, testing

---

Troubleshooting Build Issues

Feature Not Found

error: feature `xyz` not found

Solution: Check Cargo.toml for correct feature name.

Dependency Conflict

error: conflicting versions for dependency `tokio`

Solution: Run cargo update to resolve.

Compilation Error with Feature

error[E0433]: cannot find function `aws_lc_function` in this scope

Solution: Ensure feature is enabled: cargo build --features aws-lc

Linking Error

error: linking with `cc` failed

Solution: Install system dependencies:

# macOS
brew install openssl

# Ubuntu/Debian
sudo apt-get install libssl-dev

# Alpine
apk add --no-cache libssl-dev

Out of Memory During Compilation

Solution: Use incremental builds:

cargo build -Z incremental

Or reduce parallel jobs:

cargo build -j 2

---

Production Build Checklist

• Run cargo audit - no vulnerabilities
• Run cargo clippy -- -D warnings - no warnings
• Run cargo test --all-features - all tests pass
• Build with --release flag
• Test with intended feature set
• Verify binary size acceptable
• Test on target platform (if cross-compiling)
• Verify dependencies lock file is committed

---

CI/CD Integration

GitHub Actions Example

name: Build

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: dtolnay/rust-toolchain@stable
      - run: cargo audit
      - run: cargo clippy -- -D warnings
      - run: cargo test --all-features
      - run: cargo build --release --all-features

---

Next steps: See Deployment Guide for building and running in production.