Comprehensive behaviour for HashiCorp Vault Transit secrets engine.

This behaviour provides enterprise-grade encryption-as-a-service functionality. It provides a complete interface for cryptographic operations including encryption, decryption, digital signatures, key management, and HMAC operations with industry-standard algorithms and security practices.

Enterprise Cryptographic Capabilities

Advanced Key Management

• Create, read, update, and delete encryption keys with policies
• Support for multiple key types (AES, RSA, ECDSA, Ed25519, ChaCha20)
• Automated key rotation and comprehensive versioning
• Secure key import and export with HSM integration
• Configurable key policies, constraints, and lifecycle management

High-Performance Encryption

• Symmetric encryption/decryption (AES-GCM, ChaCha20-Poly1305)
• Asymmetric encryption/decryption (RSA-OAEP, RSA-PKCS1)
• Convergent encryption for deterministic, deduplication-friendly results
• Batch operations for high-throughput scenarios
• Associated data support for AEAD ciphers and authenticated encryption

Digital Signature Services

• Sign and verify data with industry-standard algorithms
• Support for RSA-PSS, RSA-PKCS1v15, ECDSA, Ed25519 signatures
• Batch signing and verification for operational efficiency
• Pre-hashed data support for large payloads
• Message recovery and signature format flexibility

HMAC and Authentication

• Generate and verify HMAC signatures with configurable algorithms
• Support for SHA-256, SHA-384, SHA-512 hash functions
• Batch HMAC operations for high-throughput authentication
• Key derivation for context-specific authentication

Enterprise Features

• Cryptographically secure random data generation
• Key derivation and context-based cryptographic operations
• Certificate signing request (CSR) generation and processing
• Secure key backup and disaster recovery
• Performance optimization through intelligent caching

Extended Operations

Beyond the base secrets operations, Transit engines support:

Key Management

• create_key/3 - Create a new encryption key
• read_key/2 - Read key information and metadata
• update_key_config/3 - Update key configuration
• rotate_key/2 - Rotate key to new version
• delete_key/2 - Delete an encryption key
• list_keys/1 - List all available keys
• export_key/3 - Export key material
• import_key/3 - Import external key material

Encryption Operations

• encrypt/3 - Encrypt plaintext data
• decrypt/3 - Decrypt ciphertext data
• rewrap/3 - Re-encrypt data with latest key version
• batch_encrypt/2 - Encrypt multiple items
• batch_decrypt/2 - Decrypt multiple items

Digital Signatures

• sign/3 - Sign data with a key
• verify/4 - Verify signature against data
• batch_sign/2 - Sign multiple items
• batch_verify/2 - Verify multiple signatures

HMAC Operations

• hmac/3 - Generate HMAC for data
• verify_hmac/4 - Verify HMAC signature
• batch_hmac/2 - Generate HMAC for multiple items

Utility Operations

• generate_random/2 - Generate random data
• hash/3 - Hash data with specified algorithm
• generate_data_key/3 - Generate data encryption key

Usage Examples

defmodule MyApp.TransitEngine do
  @behaviour Vaultx.Secrets.Transit.Behaviour

  # Key management
  @impl true
  def create_key(name, key_type, opts) do
    # Implementation for key creation
  end

  # Encryption operations
  @impl true
  def encrypt(key_name, plaintext, opts) do
    # Implementation for data encryption
  end

  # Digital signatures
  @impl true
  def sign(key_name, data, opts) do
    # Implementation for data signing
  end

  # HMAC operations
  @impl true
  def hmac(key_name, data, opts) do
    # Implementation for HMAC generation
  end
end

Key Types and Algorithms

Symmetric Keys

• aes128-gcm96 - AES-128 with GCM (96-bit nonce)
• aes256-gcm96 - AES-256 with GCM (96-bit nonce, default)
• chacha20-poly1305 - ChaCha20-Poly1305 AEAD

Asymmetric Keys

• rsa-2048, rsa-3072, rsa-4096 - RSA keys
• ecdsa-p256, ecdsa-p384, ecdsa-p521 - ECDSA keys
• ed25519 - Ed25519 keys

Special Purpose Keys

• hmac - HMAC key generation and verification
• managed_key - External managed keys (Enterprise)

Error Handling

Transit operations return standardized errors:

{:error, %Vaultx.Base.Error{
  type: :key_not_found,
  message: "Key 'my-key' not found",
  details: %{key_name: "my-key", mount_path: "transit"}
}}

Configuration Options

Transit operations support various options:

• :mount_path - Transit engine mount path (default: "transit")
• :timeout - Request timeout in milliseconds
• :retry_attempts - Number of retry attempts
• :namespace - Vault namespace (Enterprise)
• :token - Override authentication token

Encryption Options

• :context - Key derivation context (base64 encoded)
• :nonce - Nonce for convergent encryption (base64 encoded)
• :key_version - Specific key version to use
• :associated_data - Additional authenticated data for AEAD

Key Creation Options

• :derived - Enable key derivation
• :convergent_encryption - Enable convergent encryption
• :exportable - Allow key export
• :allow_plaintext_backup - Allow plaintext backup
• :auto_rotate_period - Automatic rotation period

References

• Transit Secrets Engine API
• Transit Encryption Guide
• Cryptographic Standards