webassembly/README.md

Rust WebAssembly Cryptography Module

This project provides a WebAssembly module written in Rust that offers cryptographic functionality for web applications.

Features

• Key Space Management

  • Password-protected encrypted spaces
  • Multiple spaces with different passwords
  • Persistent storage in browser's localStorage
  • Auto-logout after 15 minutes of inactivity

• Asymmetric Cryptography

  • Multiple named ECDSA keypairs
  • Keypair selection for operations
  • Message signing
  • Signature verification

• Symmetric Cryptography

  • ChaCha20Poly1305 encryption/decryption
  • Secure key generation
  • Password-based encryption

Prerequisites

Before you begin, ensure you have the following installed:

• Rust (1.70.0 or later)
• wasm-pack (0.10.0 or later)
• Node.js (14.0.0 or later)
• A modern web browser that supports WebAssembly

Running the Example

The easiest way to run the example is to use the provided start script:

./start.sh

This script will:

1. Build the WebAssembly module using wasm-pack
2. Start a local HTTP server

Then open your browser and navigate to http://localhost:8080.

Building Manually

If you prefer to build and run the example manually:

1. Build the WebAssembly module:

wasm-pack build --target web

2. Start the local server:

cd www && npm install && node server.js

3. Open your browser and navigate to http://localhost:8080.

Running Tests

To run the tests:

cargo test

API Reference

Key Space Management

// Create a new key space
const result = await wasm.create_key_space("my_space");
if (result === 0) {
  console.log("Space created successfully");
}

// Encrypt the current space with a password
const encryptedSpace = await wasm.encrypt_key_space("my_password");
localStorage.setItem("crypto_space_my_space", encryptedSpace);

// Decrypt and load a space
const storedSpace = localStorage.getItem("crypto_space_my_space");
const decryptResult = await wasm.decrypt_key_space(storedSpace, "my_password");
if (decryptResult === 0) {
  console.log("Space loaded successfully");
}

// Logout (clear current session)
wasm.logout();

Keypair Operations

// Create a new keypair in the current space
const result = await wasm.create_keypair("my_keypair");
if (result === 0) {
  console.log("Keypair created successfully");
}

// Select a keypair for use
const selectResult = await wasm.select_keypair("my_keypair");
if (selectResult === 0) {
  console.log("Keypair selected successfully");
}

// List all keypairs in the current space
const keypairs = await wasm.list_keypairs();
console.log("Available keypairs:", keypairs);

// Get the public key of the selected keypair
const pubKey = await wasm.keypair_pub_key();

// Sign a message with the selected keypair
const message = new TextEncoder().encode("Hello, world!");
const signature = await wasm.keypair_sign(message);

// Verify a signature with the selected keypair
const isValid = await wasm.keypair_verify(message, signature);
console.log("Signature valid:", isValid);

Symmetric Encryption

// Generate a symmetric key
const key = wasm.generate_symmetric_key();

// Encrypt a message
const message = new TextEncoder().encode("Secret message");
const ciphertext = await wasm.encrypt_symmetric(key, message);

// Decrypt a message
const decrypted = await wasm.decrypt_symmetric(key, ciphertext);
const decryptedText = new TextDecoder().decode(decrypted);
console.log("Decrypted:", decryptedText);

// Derive a key from a password
const derivedKey = wasm.derive_key_from_password("my_password");

// Encrypt with a password
const passwordMessage = new TextEncoder().encode("Password protected message");
const passwordCiphertext = await wasm.encrypt_with_password("my_password", passwordMessage);

// Decrypt with a password
const passwordDecrypted = await wasm.decrypt_with_password("my_password", passwordCiphertext);
const passwordDecryptedText = new TextDecoder().decode(passwordDecrypted);
console.log("Password decrypted:", passwordDecryptedText);

Security Considerations

• Key spaces are encrypted using ChaCha20Poly1305 with a key derived from the user's password.
• Keypairs are stored in encrypted spaces and persisted in localStorage when the space is saved.
• The system implements auto-logout after 15 minutes of inactivity for additional security.
• The symmetric encryption uses ChaCha20Poly1305, which provides authenticated encryption.
• The nonce for symmetric encryption is generated randomly and appended to the ciphertext.
• Password-based key derivation uses SHA-256 (consider using a more secure KDF like Argon2 for production).

License

This project is licensed under the MIT License - see the LICENSE file for details.