Cryptography & Security

These commands provide cryptographic operations including keypair generation, encryption, decryption, and password management.

keypair

Manage encryption and signing keypairs.

Purpose

Generate and use Curve25519 (or NIST) keypairs for encryption and signing operations in Rspamd.

Common Scenarios

Generate Encryption Keypair

# Generate encryption keypair (default)
rspamadm keypair

# Output as JSON
rspamadm keypair -j

# Output as UCL
rspamadm keypair -u

# Save to file
rspamadm keypair -o encryption.key

Output includes both public and private keys in a single structure.

Generate Signing Keypair

# Generate signing keypair
rspamadm keypair -s

# Save to file
rspamadm keypair -s -o signing.key

Use NIST Curves

# Generate NIST P-256 keypair
rspamadm keypair -n

# NIST signing keypair
rspamadm keypair -s -n

Subcommands

Generate Keypair

# Explicit generate command
rspamadm keypair generate

# Short forms
rspamadm keypair gen
rspamadm keypair g

Sign Files

# Sign a file
rspamadm keypair sign -k keypair.key file.txt

# Verify signature
rspamadm keypair verify -k keypair.key file.txt file.txt.sig

Encrypt Files

# Encrypt with recipient's public key
rspamadm keypair encrypt -k recipient-pubkey.key file.txt > encrypted.bin

# Decrypt with your private key
rspamadm keypair decrypt -k your-keypair.key encrypted.bin > decrypted.txt

Options

-s, --sign              Generate signing keypair
-n, --nist              Use NIST P-256 curves
-j, --json              Output as JSON
-u, --ucl               Output as UCL
-o, --output <file>     Write to file

Subcommand options:
-k, --key <file>        Keypair or public key file

Use Cases

Controller Authentication: Encrypt controller passwords
Map Signing: Sign maps for integrity verification
Secure Configuration: Encrypt sensitive config values
Inter-Server Communication: Encrypt data exchanged between servers

Example: Secure Controller Setup

# Generate keypair for controller
rspamadm keypair -o controller.key

# Extract public key for workers
grep 'pubkey' controller.key

# Configure in rspamd.conf
# controller { 
#   password = "$2$<encrypted_password>"; 
# }

secret_box

Symmetric encryption and decryption utility.

Purpose

Encrypt and decrypt text using symmetric cryptography (NaCl secretbox). Useful for encrypting sensitive configuration values.

Common Scenarios

Generate Encryption Key

# Generate a new symmetric key
rspamadm secret_box keygen

Outputs a base64-encoded key like:

key: rWKukFxPz3p1HPtN3K4xGg==

Store this key securely - you'll need it for encryption/decryption.

Encrypt Text

# Encrypt text (interactive)
rspamadm secret_box encrypt
# Paste your text, press Ctrl+D
# Enter key when prompted

# Encrypt from command line
echo "sensitive-password" | rspamadm secret_box encrypt

# Different output formats
echo "secret" | rspamadm secret_box encrypt --base64  # Base64 (default)
echo "secret" | rspamadm secret_box encrypt --base32  # Base32
echo "secret" | rspamadm secret_box encrypt --hex     # Hexadecimal

Output format:

nonce: <24-byte nonce>
encrypted: <ciphertext>

Decrypt Text

# Decrypt (interactive)
rspamadm secret_box decrypt
# Paste nonce and encrypted text
# Enter key when prompted

# Decrypt from environment
export SECRET_KEY="rWKukFxPz3p1HPtN3K4xGg=="
echo "nonce=...; encrypted=..." | rspamadm secret_box decrypt

Options

-R, --raw               Raw binary format
-H, --hex               Hexadecimal encoding
-b, --base32            Base32 encoding
-B, --base64            Base64 encoding (default)

Use Cases

Encrypt Database Passwords

# Generate key (save this securely)
rspamadm secret_box keygen > /etc/rspamd/secret.key

# Encrypt database password
echo "MySecretPassword123" | rspamadm secret_box encrypt -B

# Use in configuration
# clickhouse {
#   password = "$SECRET_BOX{nonce=...; encrypted=...}";
# }

Encrypt API Keys

# Encrypt API key
echo "sk-1234567890abcdef" | rspamadm secret_box encrypt > api-key.enc

# Store encrypted, decrypt when needed
rspamadm secret_box decrypt < api-key.enc

Secure Configuration Distribution

#!/bin/bash
# Encrypt sensitive config values before committing to git

KEY=$(cat /secure/location/secret.key)

# Encrypt Redis password
REDIS_PASS=$(echo "redis-password" | \
  rspamadm secret_box encrypt -B <<< "$KEY")

# Update config template
sed -i "s/REDIS_PASSWORD/$REDIS_PASS/" config.template

pw

Generate and verify password hashes for Rspamd.

Purpose

Create password hashes for controller authentication and verify existing hashes.

Common Scenarios

Generate Password Hash

# Interactive (password hidden)
rspamadm pw

# From command line (avoid - shows in history)
rspamadm pw -p "mypassword"

# Quiet mode (only output hash)
rspamadm pw -q

Output example:

$2$g6crbhd33hb3jwzh6r6yq9d1ynq4uqkj$8wdq6hjzfbzwq4m7crmzn5k8qyxzg1ygkbqx7dj1y8n

Choose Hash Algorithm

# List available algorithms
rspamadm pw -l

# Use specific algorithm
rspamadm pw -t pbkdf2

Verify Password

# Check if password matches hash
rspamadm pw --check -p "mypassword"
# Paste the hash when prompted

# Verify from file
rspamadm pw --check -p "mypassword" < hash.txt

Options

-e, --encrypt           Encrypt password (default)
-c, --check             Verify password against hash
-p, --password <pass>   Specify password (not recommended)
-t, --type <type>       Hash algorithm
-l, --list              List available algorithms
-q, --quiet             Suppress output, only show hash

Available Algorithms

pbkdf2 - PBKDF2-HMAC-SHA256 (default, recommended)
catena - Catena (memory-hard)

Use Cases

Set Controller Password

# Generate hash
HASH=$(rspamadm pw -q)

# Add to local.d/worker-controller.inc
echo "password = \"$HASH\";" >> /etc/rspamd/local.d/worker-controller.inc

# Restart Rspamd
systemctl restart rspamd

Rotate Passwords

#!/bin/bash
# Script to rotate controller password

echo "Enter new password:"
NEW_HASH=$(rspamadm pw -q)

# Backup config
cp /etc/rspamd/local.d/worker-controller.inc{,.bak}

# Update config
sed -i "s|password = \".*\";|password = \"$NEW_HASH\";|" \
  /etc/rspamd/local.d/worker-controller.inc

# Test config
if rspamadm configtest -q; then
  systemctl restart rspamd
  echo "Password updated successfully"
else
  # Restore backup
  mv /etc/rspamd/local.d/worker-controller.inc{.bak,}
  echo "Configuration error, password not changed"
fi

Verify Stored Hash

# Check if current password still works
STORED_HASH=$(grep password /etc/rspamd/local.d/worker-controller.inc | \
  cut -d'"' -f2)

echo "$STORED_HASH" | rspamadm pw --check -p "current-password"

Practical Examples

Complete Secure Configuration Setup

#!/bin/bash
# Set up secure configuration with encrypted values

# 1. Generate symmetric key for encrypting secrets
echo "=== Generating encryption key ==="
rspamadm secret_box keygen > /etc/rspamd/secret.key
chmod 600 /etc/rspamd/secret.key
SECRET_KEY=$(cat /etc/rspamd/secret.key | cut -d' ' -f2)

# 2. Generate controller password
echo "=== Generating controller password ==="
CONTROLLER_HASH=$(rspamadm pw -q)

# 3. Encrypt Redis password
echo "=== Encrypting Redis password ==="
read -sp "Enter Redis password: " REDIS_PASS
echo
REDIS_ENCRYPTED=$(echo "$REDIS_PASS" | rspamadm secret_box encrypt -B <<< "$SECRET_KEY")

# 4. Generate keypair for signing
echo "=== Generating signing keypair ==="
rspamadm keypair -s -o /etc/rspamd/signing.key

# 5. Update configuration
cat > /etc/rspamd/local.d/options.inc << EOF
# Secure configuration
secret_key = "$SECRET_KEY";
EOF

cat > /etc/rspamd/local.d/worker-controller.inc << EOF
password = "$CONTROLLER_HASH";
EOF

cat > /etc/rspamd/local.d/redis.conf << EOF
servers = "localhost";
password = "\$SECRET_BOX{$REDIS_ENCRYPTED}";
EOF

echo "=== Configuration complete ==="
rspamadm configtest

Encrypting Multiple Configuration Values

#!/bin/bash
# Encrypt multiple sensitive values

KEY=$(rspamadm secret_box keygen | cut -d' ' -f2)
echo "Encryption key: $KEY" > encryption-key.txt

declare -A secrets=(
  ["clickhouse_password"]="ch_pass_123"
  ["redis_password"]="redis_pass_456"
  ["api_key"]="api_key_789"
)

echo "Encrypted values:"
for name in "${!secrets[@]}"; do
  encrypted=$(echo "${secrets[$name]}" | \
    rspamadm secret_box encrypt -B <<< "$KEY")
  echo "$name = \$SECRET_BOX{$encrypted}"
done

Key Rotation Workflow

#!/bin/bash
# Rotate encryption keys and re-encrypt all secrets

OLD_KEY=$(cat /etc/rspamd/secret.key | cut -d' ' -f2)
NEW_KEY=$(rspamadm secret_box keygen | cut -d' ' -f2)

# List of encrypted values to rotate
ENCRYPTED_VARS=(
  "clickhouse_password"
  "redis_password"
)

for var in "${ENCRYPTED_VARS[@]}"; do
  # Extract encrypted value from config
  encrypted=$(grep "$var" /etc/rspamd/local.d/*.conf | \
    cut -d'{' -f2 | cut -d'}' -f1)
  
  # Decrypt with old key
  decrypted=$(echo "$encrypted" | \
    rspamadm secret_box decrypt <<< "$OLD_KEY")
  
  # Re-encrypt with new key
  new_encrypted=$(echo "$decrypted" | \
    rspamadm secret_box encrypt -B <<< "$NEW_KEY")
  
  echo "Rotated $var"
  # Update config files (implementation depends on your setup)
done

# Save new key
echo "key: $NEW_KEY" > /etc/rspamd/secret.key.new

Interactive Security Setup

#!/bin/bash
# Interactive setup for Rspamd security

echo "=== Rspamd Security Setup ==="

# Controller password
echo -e "\n1. Controller Password"
echo "Enter password for web interface:"
CONTROLLER_HASH=$(rspamadm pw -q)
echo "Generated hash: $CONTROLLER_HASH"

# Encryption key
echo -e "\n2. Encryption Key"
ENCRYPTION_KEY=$(rspamadm secret_box keygen | cut -d' ' -f2)
echo "Generated key: $ENCRYPTION_KEY"
echo "Save this key securely!"

# Signing keypair
echo -e "\n3. Signing Keypair"
rspamadm keypair -s -o /etc/rspamd/signing.key
echo "Signing keypair saved to /etc/rspamd/signing.key"

# Summary
echo -e "\n=== Configuration Summary ==="
cat << EOF

Add these to your configuration:

# local.d/worker-controller.inc
password = "$CONTROLLER_HASH";

# local.d/options.inc
secret_key = "$ENCRYPTION_KEY";

# For encrypted values in config, use:
\$SECRET_BOX{<encrypted_value>}

EOF

Tips and Best Practices

Key Management

Secure storage - Store keys with 600 permissions, owned by rspamd
Backup keys - Keep secure backups of all keys
Rotate regularly - Change passwords and keys periodically
Document keys - Maintain a secure record of what each key is for
Separate keys - Use different keys for different purposes

Password Security

Use strong passwords - Minimum 16 characters, mix of types
Use pw quietly - Use -q flag and capture output
Avoid command line - Use interactive mode to avoid shell history
Regular rotation - Change passwords quarterly
Verify hashes - Test password after setting

Encryption

Use secret_box for configs - Built-in support in Rspamd
Base64 for configs - Most compatible encoding
Document encrypted values - Comment what each is for
Test decryption - Verify encrypted values work
Key rotation - Plan for periodic key rotation

Security

Protect private keys - Never commit to version control
Use environment variables - For sensitive runtime values
Audit access - Monitor who accesses keys
Principle of least privilege - Only encrypt what's necessary
Disaster recovery - Have procedures for key loss

DKIM Management - DKIM key generation
Configuration - Using encrypted values in config
Operations - Controller commands

keypair​

Purpose​

Common Scenarios​

Generate Encryption Keypair​

Generate Signing Keypair​

Use NIST Curves​

Subcommands​

Generate Keypair​

Sign Files​

Encrypt Files​

Options​

Use Cases​

Example: Secure Controller Setup​

secret_box​

Purpose​

Common Scenarios​

Generate Encryption Key​

Encrypt Text​

Decrypt Text​

Options​

Use Cases​

Encrypt Database Passwords​

Encrypt API Keys​

Secure Configuration Distribution​

pw​

Purpose​

Common Scenarios​

Generate Password Hash​

Choose Hash Algorithm​

Verify Password​

Options​

Available Algorithms​

Use Cases​

Set Controller Password​

Rotate Passwords​

Verify Stored Hash​

Practical Examples​

Complete Secure Configuration Setup​

Encrypting Multiple Configuration Values​

Key Rotation Workflow​

Interactive Security Setup​

Tips and Best Practices​

Key Management​

Password Security​

Encryption​

Security​

Related Documentation​

keypair

Purpose

Common Scenarios

Generate Encryption Keypair

Generate Signing Keypair

Use NIST Curves

Subcommands

Generate Keypair

Sign Files

Encrypt Files

Options

Use Cases

Example: Secure Controller Setup

secret_box

Purpose

Common Scenarios

Generate Encryption Key

Encrypt Text

Decrypt Text

Options

Use Cases

Encrypt Database Passwords

Encrypt API Keys

Secure Configuration Distribution

pw

Purpose

Common Scenarios

Generate Password Hash

Choose Hash Algorithm

Verify Password

Options

Available Algorithms

Use Cases

Set Controller Password

Rotate Passwords

Verify Stored Hash

Practical Examples

Complete Secure Configuration Setup

Encrypting Multiple Configuration Values

Key Rotation Workflow

Interactive Security Setup

Tips and Best Practices

Key Management

Password Security

Encryption

Security

Related Documentation