Security Architecture

Security & HMAC Authentication

Comprehensive breakdown of cryptographic HMAC SHA-256 signing, transport security, and private channel validation.

Security Outline

1. HMAC Authentication Model

OsciWave employs Hash-based Message Authentication Codes (HMAC) with SHA-256 digest hashing to verify the identity and authenticity of API requests and private WebSocket subscriptions.

This dual-key model prevents unauthorized third parties from forging broadcast events or eavesdropping on sensitive user channels.

2. HMAC SHA-256 Signature Algorithm

When authenticating a private channel connection string (`socket_id:channel_name`), your backend generates a hex-encoded HMAC digest using your secret key (`sk_sec_...`):

// PHP HMAC SHA-256 Generation Example
$socketId = "140293.4029402";
$channelName = "private-user.42";
$stringToSign = $socketId . ":" . $channelName;

$signature = hash_hmac('sha256', $stringToSign, $appSecret);
$authPayload = $appKey . ":" . $signature;

3. Private Channel Subscription Workflow

STEP 1

Socket Handshake

Client connects to OsciWave WSS endpoint and receives a unique `socket_id` string.

STEP 2

Backend Auth Challenge

Client sends `socket_id` and channel name to your application backend `/broadcasting/auth` endpoint.

STEP 3

HMAC Validation

OsciWave server verifies the HMAC signature against your App Secret key before granting channel access.

4. Transport Encryption (TLS 1.3)

All production WebSocket connections are mandatory over Secure WebSockets (`wss://`). Data packets in transit are encrypted using TLS 1.3 with Perfect Forward Secrecy (PFS), guaranteeing that past communications cannot be decrypted even if server keys are compromised.

5. Secret Key Revocation & Emergency Rotation

If you suspect an App Secret key has been leaked or exposed in client-side code, immediately revoke the compromised credential via the OsciWave dashboard. Revocation takes effect instantly across all cluster nodes.