168 lines
4.8 KiB
Markdown
168 lines
4.8 KiB
Markdown
# 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](https://www.rust-lang.org/tools/install) (1.70.0 or later)
|
|
- [wasm-pack](https://rustwasm.github.io/wasm-pack/installer/) (0.10.0 or later)
|
|
- [Node.js](https://nodejs.org/) (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:
|
|
|
|
```bash
|
|
./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:
|
|
```bash
|
|
wasm-pack build --target web
|
|
```
|
|
|
|
2. Start the local server:
|
|
```bash
|
|
cd www && npm install && node server.js
|
|
```
|
|
|
|
3. Open your browser and navigate to http://localhost:8080.
|
|
|
|
## Running Tests
|
|
|
|
To run the tests:
|
|
|
|
```bash
|
|
cargo test
|
|
```
|
|
|
|
## API Reference
|
|
|
|
### Key Space Management
|
|
|
|
```javascript
|
|
// 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
|
|
|
|
```javascript
|
|
// 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
|
|
|
|
```javascript
|
|
// 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.
|