Table of Contents

Encryption

Description

Extension methods for encrypting and decrypting strings and byte arrays using AES CBC, AES GCM, RSA, or the ASP.NET Data Protection key ring. All methods are available directly on string and byte[].

Features

  • AES CBC: symmetric encryption, default algorithm, IV prepended to output
  • AES GCM: symmetric encryption with authentication tag, tamper-evident
  • RSA: asymmetric encryption using auto-generated or custom PEM key files
  • Key Ring: wraps ASP.NET Data Protection API — useful for short-lived tokens and cookies
  • Auto key discovery: key file is located automatically by scanning parent directories — no configuration required in most cases

Behavior

Key resolution order at startup:

  1. CLI argument --slcf-encryption-key=yourkey
  2. Environment variable SLCF_ENCRYPTION_KEY
  3. Key file named enc-*.key in configured or auto-discovered directory
  4. Falls back to default key ABCD...

The resolved key is hashed together with 'app:name' to produce a final 32-byte AES key, meaning the same raw key produces different keys across different app names.

Key file discovery scans parent directories upward from the app root (up to 10 levels) looking for enc-*.key, pem.pub and pem.priv files. If multiple .key files exist the oldest is used — allowing key rotation without breaking existing encrypted values.

RSA key files are auto-generated on first use if none exist in the configured directory. Public key (.pub) is used for encryption, private key (.priv) for decryption.

Decryption caching: frequently decrypted short values (under 255 chars) are cached in memory — up to 64 entries per algorithm — to avoid repeated decryption overhead.

Key Ring uses the app name as the protection purpose — requires app:name to be set in appsettings in production or it throws.

Caveats

  • Default fallback key ABC... is shared across all framework users — never use it in production
  • AES CBC key must be 16, 24 or 32 bytes — throws otherwise
  • AES GCM IV must be 12 bytes, AES CBC IV must be 16 bytes — throws otherwise
  • RSA requires a private key for decryption — throws if private key is missing
  • Key Ring encrypted values cannot be decrypted across applications or after key ring rotation unless persistence is configured
  • Encrypted values in config files may trigger GitHub secret scanning — add config paths to .github/secret_scanning.yml to suppress
Tip

Store your enc-*.key file outside the repository as the filename after enc- is your encryption password.

For stronger keys with unrestricted characters, pass the key via CLI argument --slcf-encryption-key= or environment variable SLCF_ENCRYPTION_KEY.

Use minimum 32 characters mixing uppercase, lowercase, digits and symbols as the key — the longer and more random the better.

AppSettings

View all appsettings here