Encryption configuration reference

Red Hat Edge Manager configures encryption at rest through a combination of key files on the host filesystem and a service configuration that maps keys to identifiers. Use these details to verify your encryption setup, plan key rotations, or configure monitoring.

Encryption key storage
Copy link

During installation, Red Hat Edge Manager generates a 256-bit AES key by running openssl rand -base64 32 and stores the result on the host filesystem. On upgrades, the existing key is preserved to prevent data loss:

Table 1. Encryption key properties
Property Value

Host path

/etc/flightctl/encryption/key

Mount path (inside containers)

/root/.flightctl/encryption/key

File permissions

0600 (read/write, owner only)

Algorithm

AES-256-GCM (authenticated encryption)

Key size

256 bits (32 bytes), base64-encoded

All Red Hat Edge Manager control-plane containers mount the encryption key directory as a read-only volume. The following services load the encryption key at startup:

  • flightctl-api
  • flightctl-worker
  • flightctl-periodic
  • flightctl-alert-exporter
  • flightctl-alertmanager-proxy
  • flightctl-imagebuilder-api
  • flightctl-imagebuilder-worker
  • flightctl-remote-access

Encryption configuration structure
Copy link

The encryption configuration in /etc/flightctl/service-config.yaml supports multiple keys for rotation scenarios:

encryption:
  activeKeyID: "default"
  keys:
    - id: "default"
      path: "/root/.flightctl/encryption/key"
Table 2. Configuration fields
Field Type Description

keys

Array

List of available encryption keys. Each entry has an id (unique identifier) and a path (file system path to the key file).

activeKeyID

String

The id of the key used to encrypt new data. Must match one of the entries in the keys array.

Encrypted data format
Copy link

Encrypted values are stored in the PostgreSQL database by using the following format:

enc:v1:<key_id>:<base64-encoded payload>

The base64-encoded payload contains a 12-byte GCM nonce prepended to the AES-GCM ciphertext and authentication tag. Values that do not begin with enc: are treated as unencrypted plain text for backward compatibility during migration.

Active key verification
Copy link

Services that initialize encryption log the active encryption configuration during startup. After a key rotation, verify that the new key is reported as active:

$ sudo journalctl -u flightctl-api --no-pager -n 50 | grep -i "encryption"

The log output should report the active key. For example:

Encryption initialized: active=v1/default

The flightctl_encryption_active_key_info metric also reports the active configuration:

flightctl_encryption_active_key_info{algorithm="AES-256-GCM",key_id="default",strategy="v1"} 1

Canary validation
Copy link

Red Hat Edge Manager validates encryption canaries during startup. A canary is a known value encrypted and stored in PostgreSQL for a specific strategy and key ID.

During startup, Red Hat Edge Manager ensures that a canary exists for the active strategy and key, then validates all persisted canaries. Existing canaries must be decryptable with the configured keys and must match the expected value.

If an existing canary cannot be decrypted or does not match the expected value, the affected service fails to start. Canary validation failures are reported through service logs and service status.

Prometheus metrics
Copy link

Red Hat Edge Manager control-plane components expose the following encryption metrics for monitoring:

Table 3. Encryption metrics
Metric Type Description

flightctl_encryption_operations_total

Counter

Total number of encryption and decryption operations, labeled by operation, strategy, key_id, and status.

flightctl_encryption_operation_duration_seconds

Histogram

Latency of encryption and decryption operations in seconds.

flightctl_encryption_errors_total

Counter

Total number of encryption errors, labeled by operation, strategy, key_id, and error_type.

flightctl_encryption_canary_validations_total

Counter

Total number of canary validation checks, labeled by strategy, key_id, and status.

flightctl_encryption_active_key_info

Gauge

Indicates the active encryption configuration, labeled by strategy, key_id, and algorithm. A value of 1 means the key is active.

Tracing
Copy link

When tracing is enabled, Red Hat Edge Manager produces OpenTelemetry spans under the flightctl/encryption tracer. The following spans are available:

  • process
  • encrypt
  • decrypt
  • canary-validate

Span attributes convey the operation type, strategy, key ID, result, and processing action where applicable. Traces do not contain plain text values, ciphertext, encryption keys, nonces, authentication tags, or protected resource contents.

Troubleshooting encryption
Copy link

Table 4. Common encryption issues
Symptom Possible cause Action

Service fails to start after installation or upgrade

Missing, malformed, or incorrectly sized encryption key

Check that the key file is mounted and that it decodes to exactly 32 bytes.

Service fails to start after key rotation

A required historical key was removed too early, or canary validation failed

Check service logs, restore the previous key, and restart the service.

Old key cannot be retired

Migration has not completed, or data still references the old key

Wait for the EncryptionMigrationCompleted event and confirm that no persisted encrypted values reference the old key.

Migration does not complete

Migration worker is failing or cannot decrypt existing data

Check migration events, service logs, and encryption error metrics.