81 lines
2.5 KiB
Markdown
81 lines
2.5 KiB
Markdown
# SigSocket: WebSocket Signing Server
|
|
|
|
SigSocket is a WebSocket server that handles cryptographic signing operations. It allows clients to connect via WebSocket, identify themselves with a public key, and sign messages on demand.
|
|
|
|
## Features
|
|
|
|
- Accept WebSocket connections from clients
|
|
- Allow clients to identify themselves with a secp256k1 public key
|
|
- Forward messages to clients for signing
|
|
- Verify signatures using the client's public key
|
|
- Support for request timeouts
|
|
- Clean API for application integration
|
|
|
|
## Architecture
|
|
|
|
SigSocket follows a modular architecture with the following components:
|
|
|
|
1. **SigSocket Manager**: Handles WebSocket connections and manages connection lifecycle
|
|
2. **Connection Registry**: Maps public keys to active WebSocket connections
|
|
3. **Message Handler**: Processes incoming messages and implements the message protocol
|
|
4. **Signature Verifier**: Verifies signatures using secp256k1
|
|
5. **SigSocket Service**: Provides a clean API for applications to use
|
|
|
|
## Message Protocol
|
|
|
|
The protocol is designed to be simple and efficient:
|
|
|
|
1. **Client Introduction** (first message after connection):
|
|
```
|
|
<hex_encoded_public_key>
|
|
```
|
|
|
|
2. **Sign Request** (sent from server to client):
|
|
```
|
|
<base64_encoded_message>
|
|
```
|
|
|
|
3. **Sign Response** (sent from client to server):
|
|
```
|
|
<base64_encoded_message>.<base64_encoded_signature>
|
|
```
|
|
|
|
## API Usage
|
|
|
|
```rust
|
|
// Create and initialize the service
|
|
let registry = Arc::new(RwLock::new(ConnectionRegistry::new()));
|
|
let sigsocket_service = Arc::new(SigSocketService::new(registry.clone()));
|
|
|
|
// Use the service to send a message for signing
|
|
async fn sign_message(
|
|
service: Arc<SigSocketService>,
|
|
public_key: String,
|
|
message: Vec<u8>
|
|
) -> Result<(Vec<u8>, Vec<u8>), SigSocketError> {
|
|
service.send_to_sign(&public_key, &message).await
|
|
}
|
|
```
|
|
|
|
## Security Considerations
|
|
|
|
- All public keys are validated to ensure they are properly formatted secp256k1 keys
|
|
- Messages are hashed using SHA-256 before signature verification
|
|
- WebSocket connections have heartbeat checks to automatically close inactive connections
|
|
- All inputs are validated to prevent injection attacks
|
|
|
|
## Running the Example Server
|
|
|
|
Start the example server with:
|
|
|
|
```bash
|
|
RUST_LOG=info cargo run
|
|
```
|
|
|
|
This will launch a server on `127.0.0.1:8080` with the following endpoints:
|
|
|
|
- `/ws` - WebSocket endpoint for client connections
|
|
- `/sign` - HTTP POST endpoint to request message signing
|
|
- `/status` - HTTP GET endpoint to check connection count
|
|
- `/connected/{public_key}` - HTTP GET endpoint to check if a client is connected
|