circles/examples/wss_demo

WSS (WebSocket Secure) Demo

This directory contains a complete demonstration of WSS (WebSocket Secure) functionality with TLS encryption and authentication.

Contents

• cert.pem - Self-signed TLS certificate for testing
• key.pem - Private key for the TLS certificate
• wss_server.rs - WSS server example with authentication
• wss_client.rs - WSS client example for testing

Quick Start

1. Start the WSS Server

# From the project root - specify the correct package and feature
cargo run --manifest-path src/server/Cargo.toml --example wss_server --features circle_ws_lib/auth

# OR run from the wss_demo directory
cd examples/wss_demo
cargo run --bin wss_server

The server will start on:

• WSS (Secure): wss://127.0.0.1:8443/ws
• WS (Regular): ws://127.0.0.1:8080/ws

2. Test with the WSS Client

Run the WSS client that uses the circle_client_ws library:

# Navigate to the wss_demo directory
cd examples/wss_demo

# Run with logging (recommended)
RUST_LOG=info cargo run --bin wss_client

# Or without logging
cargo run --bin wss_client

This will run the wss_client.rs file which demonstrates:

• Automatic credential generation using secp256k1
• WSS connection with TLS encryption
• Full authentication flow
• Script execution over secure WebSocket

Note: The WSS client must be run from the examples/wss_demo directory as it's a standalone project with its own dependencies.

Features Demonstrated

🔒 TLS/WSS Encryption

• Self-signed certificate for development/testing
• Secure WebSocket connections over TLS
• Certificate validation and error handling

🛡️ Authentication

• secp256k1 signature-based authentication
• Nonce generation and verification
• Authenticated vs unauthenticated request handling

📝 JSON-RPC Protocol

• Standard JSON-RPC 2.0 over WebSocket
• Method calls: fetch_nonce, authenticate, play
• Error handling and response validation

Certificate Information

The included certificate is a self-signed certificate for development and testing purposes only.

Certificate Details:

• Subject: /C=US/ST=Demo/L=Demo/O=WSS Demo/CN=localhost
• Validity: 365 days from generation
• Key Size: RSA 4096-bit
• Usage: Development/Testing only

⚠️ Security Notice: Do not use this certificate in production. Generate proper certificates from a trusted Certificate Authority for production use.

Testing with Browser

You can test the WSS connection using browser developer tools:

// Open browser console and run:
const ws = new WebSocket('wss://127.0.0.1:8443/ws');

ws.onopen = () => {
    console.log('WSS Connected!');
    // Send a test message
    ws.send(JSON.stringify({
        jsonrpc: "2.0",
        method: "fetch_nonce",
        params: { pubkey: "test_key" },
        id: 1
    }));
};

ws.onmessage = (event) => {
    console.log('Response:', JSON.parse(event.data));
};

Note: Your browser may show a security warning due to the self-signed certificate. This is expected for development.

Testing with websocat

You can also test with websocat (WebSocket command-line client):

# Install websocat if not already installed
cargo install websocat

# Connect to WSS server (ignoring certificate validation for self-signed cert)
websocat --insecure wss://127.0.0.1:8443/ws

# Or with more explicit options
websocat -k wss://127.0.0.1:8443/ws

# Send a test message (after connecting)
{"jsonrpc":"2.0","method":"fetch_nonce","params":{"pubkey":"test_key"},"id":1}

Note: The --insecure or -k flag is needed because we're using a self-signed certificate.

Authentication Flow

1. Fetch Nonce

{
    "jsonrpc": "2.0",
    "method": "fetch_nonce",
    "params": { "pubkey": "your_public_key_hex" },
    "id": 1
}

2. Authenticate

{
    "jsonrpc": "2.0",
    "method": "authenticate",
    "params": {
        "pubkey": "your_public_key_hex",
        "signature": "signed_nonce_hex"
    },
    "id": 2
}

3. Execute Commands

{
    "jsonrpc": "2.0",
    "method": "play",
    "params": { "script": "40 + 2" },
    "id": 3
}

Troubleshooting

Certificate Issues

If you encounter certificate-related errors:

1. Regenerate certificates:

   cd examples/wss_demo
   rm cert.pem key.pem
   openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes -subj "/C=US/ST=Demo/L=Demo/O=WSS Demo/CN=localhost"
   

2. Check file permissions:

   ls -la cert.pem key.pem
   

Connection Issues

• Ensure no other services are using ports 8080 or 8443
• Check firewall settings
• Verify the server started successfully (look for "✅ WSS Server started successfully!" message)

Authentication Issues

• Ensure you're using valid secp256k1 signatures
• Check that the nonce hasn't expired (default: 5 minutes)
• Verify the public key format is correct hex encoding

Production Deployment

For production use:

1. Use proper certificates from a trusted CA
2. Configure proper hostnames (not localhost)
3. Set up proper firewall rules
4. Use environment variables for sensitive configuration
5. Enable proper logging and monitoring
6. Consider load balancing for high availability

Related Documentation

• WSS Implementation Plan
• Server WS README
• Client WS README