Encryption

EndpointVault uses AES-256 encryption to protect your captured data. Your encryption key never leaves the device — only encrypted payloads are sent to the server.

How It Works

You provide a secret encryption passphrase during initialization
Request/response payloads are encrypted client-side before transmission
Only encrypted data is stored on the server
You decrypt data using your key when viewing events

Important: EndpointVault cannot read your encrypted data. If you lose your encryption key, the data cannot be recovered.

Encryption Algorithm

Algorithm: AES-256-CBC
Key size: 256 bits — derived from your passphrase as SHA-256(utf8(passphrase))
IV: Random 16-byte IV generated per encryption
Format: Base64-encoded [IV][ciphertext]

Key Management

Choosing a key

Any passphrase works — the SDK always derives the AES-256 key from it via SHA-256, so the passphrase's length doesn't matter. Generate a high-entropy one:

openssl rand -hex 16

await EndpointVault.init(
  apiKey: 'your-api-key',
  encryptionKey: 'your-secret-passphrase',
);

Security tip: Use a strong, randomly generated key for production — a human-chosen password is guessable. Store it securely (e.g., in environment variables or a secrets manager), and use different keys per environment.

Manual Encryption

You can use the encryption service directly:

final encryption = EncryptionService('your-encryption-key');

// Encrypt a string
final encrypted = encryption.encrypt('sensitive data');

// Decrypt
final decrypted = encryption.decrypt(encrypted);

// Encrypt JSON
final encryptedJson = encryption.encryptJson({'user': 'data'});
final decryptedJson = encryption.decryptJson(encryptedJson);

// Generate a fingerprint (for deduplication)
final fingerprint = encryption.fingerprint('data');

File Encryption

File attachments are also encrypted using AES-256:

// Encrypt bytes
final encryptedBytes = encryption.encryptBytes(fileBytes);

// Decrypt bytes
final decryptedBytes = encryption.decryptBytes(encryptedBytes);

// Encrypt to file
await encryption.encryptBytesToFile(
  data: fileBytes,
  outputPath: '/path/to/encrypted.enc',
);

// Decrypt from file
final bytes = await encryption.decryptFileToBytes('/path/to/encrypted.enc');

What Gets Encrypted

The following data is encrypted before being sent to the server:

Request headers (after redaction)
Request body
Response headers
Response body
File attachment metadata (filename, field name, content type)
File attachment data

The following is not encrypted (for analytics/filtering):

Request method (GET, POST, etc.)
URL/endpoint path
Status code
Error type
Timestamp
App version and environment
Request duration

Best Practices

Generate a strong key: Use a cryptographically random string (e.g. openssl rand -hex 16)
Store securely: Never hardcode keys in source code; use environment variables
Rotate periodically: Consider rotating keys for new projects
Backup your key: Store a backup in a secure location
Don't share: Each project should have its own unique key