What is Fernet Encryption?

Fernet is a symmetric encryption scheme built on top of standard cryptographic primitives, designed to be simple, safe, and hard to misuse. It is part of the Python cryptography library and combines AES-128-CBC encryption with HMAC-SHA256 authentication in a single, easy-to-use interface. Fernet guarantees that data encrypted with it cannot be read or tampered with without the correct key.

How Fernet Works

• Key Generation — A 32-byte key is generated (16 bytes for AES-128, 16 bytes for HMAC-SHA256)
• Encryption — Plaintext is padded to AES block size, encrypted with AES-128-CBC using a random IV
• Authentication — HMAC-SHA256 is computed over the version, timestamp, IV, and ciphertext
• Token Assembly — The version byte, timestamp, IV, ciphertext, and HMAC are concatenated and base64-encoded

Why Fernet is Preferred

Fernet is an "authenticated encryption" scheme, meaning it provides both confidentiality (data cannot be read) and integrity (data cannot be modified). Many encryption mistakes happen when developers use AES without authentication, allowing attackers to modify ciphertext and produce valid-looking but corrupted plaintext. Fernet prevents this by design.

Fernet Tokens

A Fernet token is a base64-encoded string containing all the information needed for decryption: version, creation timestamp, initialization vector, ciphertext, and HMAC. The timestamp enables time-based token expiration (TTL), useful for session tokens and temporary access grants. The token is self-contained — no external state is needed beyond the key.

Limitations

Fernet has some limitations: it uses AES-128 rather than AES-256, maximum message size is constrained by memory, and the base64 encoding increases token size by ~33%. For most applications these are not issues, but for large data encryption or post-quantum security requirements, alternative schemes may be preferred.

Fernet in Prometheus Shield

Prometheus Shield uses Fernet encryption as part of its string obfuscation layer. Sensitive strings in Python source code (API endpoints, error messages, configuration values) are encrypted with Fernet at build time and decrypted at runtime. Each build generates unique encryption keys, so the same source code produces different ciphertext in every build. This prevents pattern-matching attacks across multiple copies of the protected software.