provisioning-platform/prov-ecosystem/crates/encrypt/README.md

# Encrypt - Multi-Backend Encryption

A unified encryption framework supporting multiple cloud and on-premises secret management providers.

## Overview

Encrypt provides a unified API for secret management and encryption across different backends:

- 🔐 **SOPS** - Secrets Operations with multi-KMS support (AWS, GCP, Azure)
- 🔑 **RustyVault** - HashiCorp Vault alternative
- ☁️ **AWS KMS** - Amazon Key Management Service
- 🌐 **GCP KMS** - Google Cloud Key Management
- 💎 **Azure Key Vault** - Microsoft Azure secret management

## Features

- 🔄 **Unified API** - Same interface for all backends
- 🎯 **Backend Detection** - Auto-detect available backends
- 🔍 **Secret Detection** - Pattern-based secret detection (7 default patterns)
- ⚠️ **False Positive Filtering** - Intelligent filtering of detected "secrets"
- 🔧 **Flexible Configuration** - Extensive configuration options
- 🚀 **Async Support** - Built for modern async Rust

## Supported Backends

### SOPS (Secrets Operations)
Multi-KMS support with git-friendly encrypted YAML/JSON/TOML files

```rust
use encrypt::config::{EncryptionConfig, BackendType, SopsConfig};

let sops = SopsConfig {
    kms_provider: "aws".to_string(),
    gcp_project: None,
    pgp_fingerprints: vec![],
    ..Default::default()
};
```

### RustyVault
HashiCorp Vault-compatible secret management

```rust
use encrypt::config::RustyVaultConfig;

let vault = RustyVaultConfig {
    vault_addr: "https://vault.example.com".to_string(),
    namespace: Some("myapp".to_string()),
    ..Default::default()
};
```

### AWS KMS
Amazon Key Management Service for secrets

```rust
use encrypt::config::AwsKmsConfig;

let aws = AwsKmsConfig {
    region: "us-east-1".to_string(),
    key_id: "arn:aws:kms:us-east-1:123456789012:key/12345678".to_string(),
    ..Default::default()
};
```

### GCP KMS
Google Cloud Key Management Service

```rust
use encrypt::config::GcpKmsConfig;

let gcp = GcpKmsConfig {
    project_id: "my-project".to_string(),
    key_ring: "myapp-keys".to_string(),
    crypto_key: "default".to_string(),
    ..Default::default()
};
```

### Azure Key Vault
Microsoft Azure secret management

```rust
use encrypt::config::AzureKmsConfig;

let azure = AzureKmsConfig {
    vault_name: "myapp-vault".to_string(),
    tenant_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx".to_string(),
    ..Default::default()
};
```

## Quick Start

```rust
use encrypt::config::EncryptionConfig;

// Create configuration
let config = EncryptionConfig {
    backends: vec![/* backend configs */],
    default_backend: "sops".to_string(),
    auto_detect: true,
    ..Default::default()
};

// Use encryption backend
let backend = config.get_default_backend()?;
backend.encrypt(secret_data)?;
backend.decrypt(encrypted_data)?;
```

## Secret Detection

Detect secrets in code or configuration:

```rust
use encrypt::detect::detect_secrets;

let patterns = detect_secrets(code_content);
for detected in patterns {
    println!("Found: {} with confidence: {}",
        detected.name, detected.confidence);
}
```

### Default Patterns

- AWS Access Keys (`AKIA[0-9A-Z]{16}`)
- AWS Secret Keys
- GitHub Tokens (`gh[pousr]{1}_...`)
- Vault Tokens (`hvs.*`)
- Private Keys (RSA, DSA, OpenSSH, EC)
- API Keys
- Database Passwords

## Architecture

- `error.rs` - Error types for encryption operations
- `config.rs` - Configuration for backends
- `backend/mod.rs` - Backend trait definition
- `backend/sops.rs` - SOPS implementation
- `backend/rustyvault.rs` - RustyVault implementation
- `backend/kms.rs` - AWS/GCP/Azure KMS implementations
- `detect.rs` - Secret pattern detection

## Use Cases

### Secret Management
Centralized secrets across environments

### Compliance
Encrypt sensitive data to meet regulatory requirements

### DevOps
Automate secret rotation and management

### Security
Prevent accidental secret exposure

### Multi-Cloud
Work consistently across AWS, GCP, Azure

## Configuration Files

### SOPS Example
```yaml
# .sops.yaml
creation_rules:
  - path_regex: secrets/.*
    kms: 'arn:aws:kms:us-east-1:123456789012:key/12345678'
    age: age1xxx...
```

### Vault Example
```toml
[vault]
address = "https://vault.example.com"
token = "hvs.xxx..."
namespace = "myapp"
```

## Testing

Run tests with:

```bash
cargo test --lib
```

All 27 tests pass with full coverage of:
- Configuration management
- All 5 backend implementations
- Secret detection with filtering
- Error handling

## Performance

- Fast secret detection
- Minimal overhead
- Supports large files
- Efficient pattern matching

## API Documentation

Full API documentation available with:

```bash
cargo doc --open
```

## Integration

Encrypt can be integrated with:
- CI/CD systems for secret management
- Configuration management systems
- Deployment automation (provctl, provisioning)
- Secret scanning tools
- Compliance automation

## Security Considerations

- ✅ Never log secrets
- ✅ Use secure credential storage
- ✅ Rotate credentials regularly
- ✅ Use TLS for backend communication
- ✅ Principle of least privilege for access

## License

Same as prov-ecosystem parent project

## Contributing

Contributions welcome! See parent project guidelines.

## See Also

- [prov-ecosystem README](../../README.md) - Parent project overview
- [valida](../valida/README.md) - Validation rules engine
- [runtime](../runtime/README.md) - Container runtime abstraction
- [init-servs](../init-servs/README.md) - Init system abstraction