Skip to main content
Version: 10.0

Cluster Secret Key

The secretKey is a critical security component of webPDF Server cluster configuration. It is used to encrypt and authenticate communication between cluster nodes, ensuring that only authorized nodes can join and participate in the cluster.

Overview​

  • Purpose: Encrypt and authenticate inter-node communication
  • Algorithm: AES (Advanced Encryption Standard)
  • Key Size: 256-bit (32 bytes)
  • Format: 64-character hexadecimal string
  • Scope: Cluster-wide (all nodes must use identical key)

What is the Secret Key?​

The secret key is a 256-bit encryption key that serves two primary purposes:

  1. Encryption - All communication between cluster nodes is encrypted using this key
  2. Authentication - Nodes prove their membership by possessing the correct key
Critical Security Component

The secret key is the only mechanism preventing unauthorized nodes from joining your cluster. If an attacker obtains this key, they can join your cluster and potentially access sensitive data or disrupt operations.

Key Format​

The secret key must be:

  • Length: Exactly 64 hexadecimal characters (0-9, a-f)
  • Encoding: Hexadecimal representation of 32 bytes (256 bits)
  • Case: Lowercase or uppercase (typically lowercase)

Valid Example​

4f0a2c8efb1a0f9c79c4b0f5a81e6d5b4a7c8d9e2f0a1b2c3d4e5f60718293ab

Invalid Examples​

# Too short (only 32 characters)
4f0a2c8efb1a0f9c79c4b0f5a81e6d5b

# Contains invalid characters (contains 'g')
4f0a2c8efb1a0f9c79c4b0f5a81e6d5g4a7c8d9e2f0a1b2c3d4e5f60718293ab

# Not hexadecimal (special characters)
my-secret-key-for-cluster-communication-security-2024

Generating a Secret Key​

When creating a cluster through the Admin Portal, webPDF automatically generates a secure secret key for the coordinator node. This is the recommended approach as it ensures:

  • Cryptographically secure random generation
  • Correct key length and format
  • No human error in key creation

Follow the steps in the setup guide to create a cluster.

Manual Generation​

If you need to generate a secret key manually (e.g., for scripted deployments), use cryptographically secure methods:

Using OpenSSL (Linux/macOS/Windows with OpenSSL)​

# Generate 32 random bytes and convert to hex (64 characters)
openssl rand -hex 32

Example output:

a7f3e9c4d2b8f6a1e5c3d7b9f2e8a4c6d3f7e1b5a9c8d4f6e2b7a3f9e5c1d8b6

Using Python​

import secrets

# Generate 32 random bytes and convert to hex
secret_key = secrets.token_hex(32)
print(secret_key)

Using Node.js​

const crypto = require('crypto');

// Generate 32 random bytes and convert to hex
const secretKey = crypto.randomBytes(32).toString('hex');
console.log(secretKey);

Using PowerShell (Windows)​

# Generate 32 random bytes and convert to hex
$bytes = New-Object byte[] 32
[Security.Cryptography.RNGCryptoServiceProvider]::Create().GetBytes($bytes)
($bytes | ForEach-Object { $_.ToString("x2") }) -join ''
warning

Never use weak methods like md5sum, simple timestamps, or predictable patterns to generate secret keys. Always use cryptographically secure random number generators.

Configuration​

Cluster Configuration File​

The secret key is configured in cluster.json:

{
  "mode": "CLUSTER",
  "role": "COORDINATOR",
  "name": "webpdf-prod-cluster",
  "nodeName": "coordinator-1",
  "secretKey": "4f0a2c8efb1a0f9c79c4b0f5a81e6d5b4a7c8d9e2f0a1b2c3d4e5f60718293ab",
  "stopOnError": true,
  "connectTimeout": 60000
}

Environment Variable​

The secret key can also be provided via environment variable:

export WEBPDF_CLUSTER_SETTINGS_SECRET_KEY="4f0a2c8efb1a0f9c79c4b0f5a81e6d5b4a7c8d9e2f0a1b2c3d4e5f60718293ab"
tip

Using environment variables is recommended for containerized deployments and helps keep secrets out of configuration files.

Key Distribution​

Coordinator Node​

When creating a cluster:

  1. The coordinator node generates the secret key automatically
  2. The key is stored in the coordinator's cluster.json
  3. The key is displayed on the Cluster information overview page in the Admin Portal.
  4. Copy the key to use it in the member node configuration

Member Nodes​

Member nodes must be configured with the exact same secret key as the coordinator:

Option 1: Manual Configuration

{
  "mode": "CLUSTER",
  "role": "MEMBER",
  "name": "webpdf-prod-cluster",
  "nodeName": "member-1",
  "secretKey": "4f0a2c8efb1a0f9c79c4b0f5a81e6d5b4a7c8d9e2f0a1b2c3d4e5f60718293ab"
}

Option 2: Environment Variable

export WEBPDF_CLUSTER_SETTINGS_SECRET_KEY="4f0a2c8efb1a0f9c79c4b0f5a81e6d5b4a7c8d9e2f0a1b2c3d4e5f60718293ab"