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.

This guide also covers SSL/TLS Certificate Generation, which you need if you run the server over HTTPS.

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.

SSL/TLS Certificate Generation

When enabling SSL/TLS mode on the Verify MCP Server, you need a public certificate (server.crt) and a private key (server.key) in PEM format. The openssl commands below follow the same approach as the !obf and !enc procedures above. When you configure SSL/TLS in the Installation Guide, it directs you back to this section for these files.

Option A — Self-signed certificate (development / testing)

Use openssl to generate a self-signed certificate and an unencrypted private key in one step:

openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout server.key \
  -out server.crt \
  -days 365 \
  -subj "/CN=verify-mcp-server" \
  -addext "subjectAltName=DNS:verify-mcp-server,DNS:localhost,IP:127.0.0.1"

⚠️

Self-signed certificates require MCP clients to explicitly trust the certificate. See Self-Signed Certificates in the Configuring MCP Clients guide. For production, use a certificate issued by a trusted CA.

Option B — Certificate signed by a custom CA (production / internal PKI)

If your organisation uses an internal CA, generate a Certificate Signing Request (CSR) and have the CA sign it:

# 1. Generate the private key
openssl genrsa -out server.key 2048

# 2. Generate a CSR
openssl req -new \
  -key server.key \
  -out server.csr \
  -subj "/CN=verify-mcp-server" \
  -addext "subjectAltName=DNS:your-server-hostname,IP:your-server-ip"

# 3. Submit server.csr to your CA — the CA returns server.crt (and optionally ca-bundle.crt)

After you have the certificate and key files, follow the SSL/TLS steps in the Installation Guide:

• Kubernetes: Enable SSL/TLS (optional)
• Docker: Enable SSL/TLS (optional)

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.