Encrypt

Security Elastic Compatible

Synopsis

Encrypts string values using AES encryption with optional compression.

Schema

encrypt:
  algorithm: <string>
  encryption_key: <string>
  field: <ident>
  iv_field: <ident>
  description: <text>
  if: <script>
  ignore_failure: <boolean>
  ignore_missing: <boolean>
  on_failure: <processor[]>
  on_success: <processor[]>
  tag: <string>
  with_compression: <boolean>

Configuration

Field	Required	Default	Description
algorithm	N	AES-256-GCM	Encryption algorithm. Valid values: AES-256-GCM or AES-256-CFB
encryption_key	Y	-	32-byte key for encryption
field	Y	-	Field containing the value to encrypt
iv_field	Y	-	Field to store the initialization vector
description	N	-	Explanatory note
if	N	-	Conditional expression
ignore_failure	N	false	Continue if encryption fails
ignore_missing	N	false	Continue if source field is missing
on_failure	N	-	Processors to run on failure
on_success	N	-	Processors to run on success
tag	N	-	Identifier for logging
with_compression	N	false	Compress data before encryption

Details

The processor encrypts string values using AES encryption, with support for two encryption modes:

• AES-256-GCM (Recommended) - more secure against tampering, but has slightly slower performance
• AES-256-CFB - has faster performance but no built-in authentication

note

The impact of encryption is minimal on previously compressed content.

When with_compression is enabled, the data is compressed before encryption. This reduces encrypted data size, and therefore is most effective for text-based data.

note

Encryption keys are cached for performance.

Use environment variables or secure key management for encryption keys. For keys, 32-byte encryption and cryptographically secure random number generators must be preferred.

Never reuse initialization vectors (IVs) with the same key, and store encrypted data and IVs separately from encryption keys. Recommended IV sizes:

• GCM mode: 12 bytes (96 bits)
• CFB mode: 16 bytes (128 bits)

Protect encryption keys rigorously, i.e. implement regular key rotation (every 90 days) and store keys using:

• Key Management Services (KMS)
• Hardware Security Modules (HSM)

tip

Implement filesystem-level encryption as a policy, and always use authenticated encryption (GCM mode), following the principle of least privilege.

Examples

Basic

Encrypting a sensitive field using GCM mode...	{ "password": "mysecret123" } encrypt: field: password iv_field: password_iv encryption_key: "${ENCRYPTION_KEY}" algorithm: AES-256-GCM
result:	{ "password": "KZh/JR2baS2MkZpseKZYoBN2tQ==", "password_iv": "F+e8YorshrvFiFTC" }

Compression

Compressing while encrypting the data...	{ "log_data": "2024-01-01 DEBUG User logged in from IP 192.168.1.1\n2024-01-01 DEBUG User logged in from IP 192.168.1.1\n..." } encrypt: field: log_data iv_field: log_iv encryption_key: "${ENCRYPTION_KEY}" algorithm: AES-256-GCM with_compression: true
reduces its size:	{ "log_data": "Yh8dR2S2kZpsMkYoBN2tQ==", "log_iv": "K+r8YorvFiFTC" }

Error Handling

Handling missing or invalid fields...	{ "other_field": "value" } encrypt: field: missing_field iv_field: missing_iv encryption_key: "${ENCRYPTION_KEY}" ignore_missing: true on_failure: - set: field: error_status value: "encryption_failed"
continues the execution:	{ "other_field": "value", "error_status": "encryption_failed" }