Encryption & Obfuscation

Sensitive values in config.yaml — client secrets, the obfuscation passphrase, and similar credentials — can be protected by using two independent mechanisms. Both are resolved before the application starts, so your code always receives plaintext.

After you have your ciphertexts, place them in config.yaml and follow the deployment steps in the Installation Guide.

Obfuscation (!obf)

Requires OpenSSL 1.1.1 or later.

Step 1 — Choose a passphrase

Pick a strong, random passphrase (minimum 32 characters) and store it securely in a secrets manager. You need to supply it at runtime as secrets.obf_key in config.yaml.

my-strong-passphrase-32chars+

⚠️

Never store the passphrase in config.yaml as plain text. Use !enc !obf, !secret, or !file to inject it at runtime.

Step 2 — Obfuscate a secret value

Run the following command for each secret you want to obfuscate:

echo -n "<secret-value>" | openssl enc -aes256 \
    -pbkdf2 -pass pass:"<obfuscation-passphrase>" -md sha512 \
    -base64 | tr -d '\n'; echo

Example:

echo -n "my-client-secret-value" | openssl enc -aes256 \
    -pbkdf2 -pass pass:"my-strong-passphrase" -md sha512 \
    -base64 | tr -d '\n'; echo

Example Output:

U2FsdGVkX19iBh23scd53+QkybjO6RjFHhSbz4VRudYHA==

Each run produces a different ciphertext because the encryption is salted, however, every ciphertext decrypts correctly with the same passphrase.

Step 3 — Place the ciphertext in config.yaml

client_secret: "!obf U2FsdGVkX19iBh23scd53+QkybjO6RjFHhSbz4VRudYHA=="

Step 4 — Verify decryption of obfuscated value (optional)

echo "<base64-ciphertext>" | openssl enc -d -aes256 \
    -pbkdf2 -pass pass:"<obfuscation-passphrase>" -md sha512 \
    -base64; echo

Expected output: the original plaintext secret.

Encryption (!enc)

Step 1 — Generate an RSA key pair

# Generate a 2048-bit RSA private key (4096-bit recommended for higher security)
openssl genrsa -out private.pem 2048

# Derive the public key
openssl rsa -in private.pem -pubout -out public.pem

Keep private.pem secure. Store it in a safe location immediately after generating it — it is required to decrypt !enc values at deployment time and cannot be recovered if lost.

Step 2 — Encrypt a secret value

Use the public key to encrypt each secret:

echo -n "<secret-value>" | openssl pkeyutl -encrypt \
    -pubin -inkey public.pem \
    -pkeyopt rsa_padding_mode:pkcs1 \
    | base64 | tr -d '\n'; echo

Example:

echo -n "my-client-secret-value" | openssl pkeyutl -encrypt \
    -pubin -inkey public.pem \
    -pkeyopt rsa_padding_mode:pkcs1 \
    | base64 | tr -d '\n'; echo

Output (truncated):

QUORyJfiB3cQdlLQXDFQ6nC6btMq4e7llaniT2M1NaRKbnmR80Yy2ufAO8+mNGteGuDj7px2x71AtmvPNpkoF729PHGRjlAnE66qPXh4ypuLZYV2JQq39Ja/KgYUnO4=

Run once per secret value.

Step 3 — Place the ciphertext in config.yaml

client_secret: "!enc QUORyJfiB3cQdlLQXDFQ6nC6btMq4e7llaniT2M1NaRKbnmR80Yy..."

Step 4 — Verify decryption (optional)

echo -n "<base64-ciphertext>" | base64 -d | openssl pkeyutl -decrypt \
    -inkey private.pem \
    -pkeyopt rsa_padding_mode:pkcs1; echo

Expected output: the original plaintext secret.

Next Steps

• Return to the Installation Guide to place your ciphertexts in config.yaml and configure the runtime key delivery (secrets.obf_key / ENC_KEY).
• See Troubleshooting if the server fails to start after adding encrypted values.