Request Signing

Add an extra layer of security to your routes with cryptographic request signing. Verify that requests haven’t been tampered with and prevent replay attacks.

What is Request Signing?

Request signing uses HMAC-SHA256 (Hash-based Message Authentication Code) to create a cryptographic signature of each request. This signature proves:

✅ Authenticity: Request came from a trusted source
✅ Integrity: Request wasn’t modified in transit
✅ Non-repudiation: Sender cannot deny sending the request

Why Use Request Signing?

Without Request Signing

Attacker intercepts request
    ↓
Modifies payload amount: $10 → $1,000
    ↓
Forwards modified request
    ↓
Your backend processes fraudulent request ❌

With Request Signing

Attacker intercepts request
    ↓
Modifies payload amount: $10 → $1,000
    ↓
Signature verification fails ❌
    ↓
Request rejected before reaching backend ✅

How It Works

Signature Creation (Client Side)

Get current timestamp (Unix seconds):

timestamp = 1640000000

Create payload to sign:

payload = "timestamp.requestBody"
Example: "1640000000.{\"orderId\":\"123\",\"amount\":99.99}"

Create HMAC-SHA256 signature:

signature = HMAC-SHA256(apiKey, payload)

Format signature header:

X-KnoxCall-Signature: t=1640000000,v1=abc123def456...

Format: t=<timestamp>,v1=<signature>

t=: Unix timestamp when request was created
v1=: HMAC-SHA256 signature in hexadecimal

Include in request headers:

X-KnoxCall-Key: your-api-key
X-KnoxCall-Signature: t=1640000000,v1=abc123def456...

Signature Verification (KnoxCall)

Extract signature and timestamp from headers
Recreate the message from request components
Compute expected signature using shared secret
Compare signatures:
- Match → Request is valid ✅
- Mismatch → Request is rejected ❌

Setting Up Request Signing

Step 1: Enable on Route

Navigate to Routes → Select your route
Scroll to Security section
Toggle Require Signature to ON
Configure settings:

Signature Header:

X-Signature

(Default, can be customized) Timestamp Header:

X-Timestamp

(Default, can be customized) Signature Algorithm:

HMAC-SHA256

(Most secure and widely supported) Timestamp Tolerance:

300 seconds (5 minutes)

Allows clock skew between client and server.

Click Save

Step 2: Create Signing Secret

Navigate to Secrets → Add Secret
Configure:

Name:

my-signing-secret

Type:

Static Secret

Value:

[Generate a strong random key]

Recommended: Use a cryptographically secure random string:

openssl rand -hex 32

Click Save

Step 3: Assign Secret to Client

Navigate to Clients → Select your client
Go to Signing Configuration tab
Select the signing secret
Click Save

Now this client must sign all requests to protected routes.

Client Implementation

JavaScript/Node.js

const crypto = require('crypto');

function signRequest(body, apiKey) {
  // 1. Get current timestamp (Unix seconds)
  const timestamp = Math.floor(Date.now() / 1000);

  // 2. Stringify body (use empty string for GET requests)
  const bodyStr = body ? JSON.stringify(body) : '';

  // 3. Create message to sign: "timestamp.body"
  const payload = `${timestamp}.${bodyStr}`;

  // 4. Create HMAC-SHA256 signature
  const signature = crypto
    .createHmac('sha256', apiKey)
    .update(payload)
    .digest('hex');

  // 5. Format signature header: "t=timestamp,v1=signature"
  const signatureHeader = `t=${timestamp},v1=${signature}`;

  return { signatureHeader, timestamp };
}

// Usage
const body = { orderId: '123', amount: 99.99 };
const apiKey = 'your-tenant-api-key'; // Use your KnoxCall API key as signing secret

const { signatureHeader } = signRequest(body, apiKey);

// Make request with signature
fetch('https://your-subdomain.knoxcall.com/api/orders', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-knoxcall-route': 'my-route',
    'x-knoxcall-key': apiKey,
    'x-knoxcall-signature': signatureHeader,
  },
  body: JSON.stringify(body),
});

Python

import hmac
import hashlib
import time
import json
import requests

def sign_request(body, api_key):
    # 1. Get current timestamp
    timestamp = int(time.time())

    # 2. Stringify body (empty string for GET requests)
    body_str = json.dumps(body) if body else ''

    # 3. Create payload: "timestamp.body"
    payload = f"{timestamp}.{body_str}"

    # 4. Create HMAC-SHA256 signature
    signature = hmac.new(
        api_key.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()

    # 5. Format signature header: "t=timestamp,v1=signature"
    signature_header = f"t={timestamp},v1={signature}"

    return signature_header

# Usage
body = {'orderId': '123', 'amount': 99.99}
api_key = 'your-tenant-api-key'

signature_header = sign_request(body, api_key)

# Make request with signature
response = requests.post(
    'https://your-subdomain.knoxcall.com/api/orders',
    headers={
        'Content-Type': 'application/json',
        'x-knoxcall-route': 'my-route',
        'x-knoxcall-key': api_key,
        'x-knoxcall-signature': signature_header,
    },
    json=body
)

Go

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "encoding/json"
    "fmt"
    "time"
)

func signRequest(body interface{}, apiKey string) string {
    // 1. Get current timestamp
    timestamp := time.Now().Unix()

    // 2. Stringify body (empty string for GET requests)
    var bodyStr string
    if body != nil {
        bodyJSON, _ := json.Marshal(body)
        bodyStr = string(bodyJSON)
    }

    // 3. Create payload: "timestamp.body"
    payload := fmt.Sprintf("%d.%s", timestamp, bodyStr)

    // 4. Create HMAC-SHA256 signature
    h := hmac.New(sha256.New, []byte(apiKey))
    h.Write([]byte(payload))
    signature := hex.EncodeToString(h.Sum(nil))

    // 5. Format signature header: "t=timestamp,v1=signature"
    signatureHeader := fmt.Sprintf("t=%d,v1=%s", timestamp, signature)

    return signatureHeader
}

// Usage
func main() {
    body := map[string]interface{}{
        "orderId": "123",
        "amount":  99.99,
    }
    apiKey := "your-tenant-api-key"

    signatureHeader := signRequest(body, apiKey)

    // Include in request headers:
    // x-knoxcall-key: apiKey
    // x-knoxcall-signature: signatureHeader
}

PHP

<?php

function signRequest($body, $apiKey) {
    // 1. Get current timestamp
    $timestamp = time();

    // 2. Stringify body (empty string for GET requests)
    $bodyStr = $body ? json_encode($body) : '';

    // 3. Create payload: "timestamp.body"
    $payload = $timestamp . '.' . $bodyStr;

    // 4. Create HMAC-SHA256 signature
    $signature = hash_hmac('sha256', $payload, $apiKey);

    // 5. Format signature header: "t=timestamp,v1=signature"
    $signatureHeader = "t={$timestamp},v1={$signature}";

    return $signatureHeader;
}

// Usage
$body = ['orderId' => '123', 'amount' => 99.99];
$apiKey = 'your-tenant-api-key';

$signatureHeader = signRequest($body, $apiKey);

// Make request with signature
$ch = curl_init('https://your-subdomain.knoxcall.com/api/orders');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'x-knoxcall-route: my-route',
    'x-knoxcall-key: ' . $apiKey,
    'x-knoxcall-signature: ' . $signatureHeader,
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
$response = curl_exec($ch);
curl_close($ch);
?>

Signature Verification Process

KnoxCall performs the following checks:

1. Timestamp Validation

Current Time: 15:30:00
Request Timestamp: 15:28:30
Tolerance: 5 minutes

Time difference: 1.5 minutes ✅ VALID

Rejected if:

Timestamp is more than 5 minutes old
Timestamp is in the future (clock skew)

2. Signature Recreation

Extract from request:
- Signature header: t=1640000000,v1=abc123def456...
- Body: {"orderId":"123","amount":99.99}

Parse signature header:
- Timestamp (t): 1640000000
- Signature (v1): abc123def456...

Recreate payload:
payload = "1640000000.{\"orderId\":\"123\",\"amount\":99.99}"

Compute expected signature:
HMAC-SHA256(apiKey, payload) = abc123def456...

3. Signature Comparison

Request Signature:  abc123def456...
Expected Signature: abc123def456...

Match? ✅ Request is authentic

Preventing Replay Attacks

Request signing combined with timestamps prevents replay attacks:

Attacker intercepts valid request
    ↓
Timestamp: 15:00:00
Signature: abc123... (valid at 15:00:00)
    ↓
Attacker replays request at 15:10:00
    ↓
Timestamp check fails (> 5 minutes old)
    ↓
Request rejected ❌

Replay Attack Window

Request signing uses timestamp validation to prevent replays. A request signed at time T is accepted for signature_tolerance_sec seconds (default 300 / 5 minutes). After that window, the same signed request is rejected.

Attacker intercepts valid request at T=0
Attacker replays it at T=360 (6 minutes later)
→ Rejected: signature expired (age: 360s, tolerance: 300s)

Within the tolerance window, a replay technically passes signature validation — because KnoxCall does not track request nonces. For endpoints where this matters (e.g. idempotency-critical mutations), enforce your own deduplication at the application layer using a request ID or idempotency key.

Error Responses

Invalid Signature

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "Unauthorized"
}

Timestamp Too Old

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "Unauthorized"
}

Missing Headers

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Missing signature headers",
  "message": "x-signature and x-timestamp headers are required",
  "required_headers": ["x-signature", "x-timestamp"]
}

Best Practices

1. Use Strong Secrets

Generate cryptographically secure signing secrets:

# Good: 64 hex characters (256 bits)
openssl rand -hex 32

❌ Bad:

password123
my-secret-key
Short or predictable strings

2. Rotate Secrets Regularly

Rotate signing secrets every 90 days:

Create new secret
Update clients with new secret (gracefully)
Support both old and new secrets for 24 hours
Remove old secret

3. Use HTTPS Always

Request signing protects integrity, but not confidentiality:

HTTPS encrypts the entire request (including signature)
Signature prevents tampering after decryption

Always use HTTPS + request signing together.

4. Include All Relevant Data

Sign everything that matters:

// Good: Includes body and important headers
const message = `${timestamp}.${method}.${path}.${body}.${contentType}`;

// Bad: Only timestamp
const message = `${timestamp}`;

5. Handle Clock Skew

Allow 5-minute tolerance for client clock differences:

Server Time: 15:30:00
Client Time: 15:29:00 (1 minute behind)

Still accepted ✅

Use Cases

Payment Processing

Route: /api/payments
Require Signature: ON
Reason: Prevent payment amount tampering

Administrative Actions

Route: /api/admin/*
Require Signature: ON
Reason: Ensure admin requests are authentic

Webhook Validation

Route: /webhooks/external
Require Signature: ON
Reason: Verify webhooks came from real source

High-Value Transactions

Routes: /api/transfers, /api/withdrawals
Require Signature: ON
Reason: Prevent unauthorized financial transactions

Troubleshooting

”Invalid signature” errors

Check:

✓ Using the correct signing secret
✓ Message format matches exactly (order matters)
✓ Body is JSON-stringified identically
✓ No extra whitespace in headers

Debug: Log the message before signing:

console.log('Message to sign:', message);
console.log('Signature:', signature);

“Timestamp expired” errors

Causes:

Client clock is out of sync
Request took too long to reach KnoxCall
Network latency

Fix:

Sync client clock with NTP
Increase timestamp tolerance (temporarily for testing)
Reduce request queuing on client side

Signature works in test but not production

Check:

✓ Using production signing secret (not test secret)
✓ Correct route configuration in production
✓ Client is assigned to production environment

Next Steps

Rate Limiting

Add rate limits for additional protection

Secret Management

Learn about managing signing secrets

Client Permissions

Configure client-level security

OAuth2 Flow

Set up OAuth2 authentication

📊 Statistics

Level: advanced
Time: 20 minutes

🏷️ Tags

security, hmac, signatures, authentication, integrity

​Request Signing

​What is Request Signing?

​Why Use Request Signing?

​Without Request Signing

​With Request Signing

​How It Works

​Signature Creation (Client Side)

​Signature Verification (KnoxCall)

​Setting Up Request Signing

​Step 1: Enable on Route

​Step 2: Create Signing Secret

​Step 3: Assign Secret to Client

​Client Implementation

​JavaScript/Node.js

​Python

​Go

​PHP

​Signature Verification Process

​1. Timestamp Validation

​2. Signature Recreation

​3. Signature Comparison

​Preventing Replay Attacks

​Replay Attack Window

​Error Responses

​Invalid Signature

​Timestamp Too Old

​Missing Headers

​Best Practices

​1. Use Strong Secrets

​2. Rotate Secrets Regularly

​3. Use HTTPS Always

​4. Include All Relevant Data

​5. Handle Clock Skew

​Use Cases

​Payment Processing

​Administrative Actions

​Webhook Validation

​High-Value Transactions

​Troubleshooting

​”Invalid signature” errors

​“Timestamp expired” errors

​Signature works in test but not production

​Next Steps