cell/examples/seif_handshake_README.md

Seif Handshake Examples

This directory contains examples demonstrating the Seif Protocol handshake implementation in Prosperon.

Files

• seif_simple.js - A standalone demonstration of the Seif handshake cryptographic operations
• seif_server.js - A server that accepts Seif handshake connections
• seif_client.js - A client that initiates Seif handshake with a server

Running the Examples

Simple Demo

To see the cryptographic operations in action:

./prosperon examples/seif_simple.js

Client-Server Demo

1. First, start the server:

./prosperon examples/seif_server.js

2. Note the server's public key that is printed

3. Create a file bob_public.key with the server's public key:

echo "SERVER_PUBLIC_KEY_HERE" > bob_public.key

4. In another terminal, run the client:

./prosperon examples/seif_client.js

The Seif Protocol

The Seif handshake establishes a secure session in one round trip:

1. Alice's Message:

   • Generates random handshake_key
   • Sends: {seif: 1, handshake: encrypt_pk(bob_public, handshake_key), payload: encrypt(handshake_key, alice_public)}

2. Bob's Response:

   • Decrypts handshake_key using his private key
   • Decrypts Alice's public key from payload
   • Generates session_key
   • Sends: encrypt(handshake_key, {session: encrypt_pk(alice_public, session_key)})

3. Result: Both parties share session_key for symmetric encryption

Actor System Integration

In Prosperon's actor system:

• Actor objects can serve as public key identifiers (they contain unique IDs)
• The $_.portal() function creates a listening endpoint
• The $_.contact() function initiates connections
• Messages are automatically routed through the actor system

Security Properties

• Authentication: Both parties prove possession of their private keys
• Forward Secrecy: Session keys are ephemeral
• Man-in-the-Middle Protection: Requires knowledge of both private keys
• One Round Trip: Efficient session establishment

Notes on Implementation

The current implementation uses the actor object's ID as part of the identity system. In a production system, you might want to:

1. Store the public key as part of the actor's data
2. Use a proper key derivation function for session keys
3. Add additional metadata in the handshake (timestamps, nonces, etc.)
4. Implement key rotation and session management

The crypto module provides:

• crypto.keypair() - Generate X25519 key pairs
• crypto.encrypt_pk(public_key, data) - Public key encryption
• crypto.decrypt_pk(private_key, data) - Public key decryption
• crypto.encrypt(key, data) - Symmetric encryption
• crypto.decrypt(key, data) - Symmetric decryption