Skip to content

getting-started.md

Latest commit

 

History

History
359 lines (236 loc) · 11.9 KB

getting-started.md

File metadata and controls

359 lines (236 loc) · 11.9 KB

Getting Started

🚀 Quick Start Guide

Get up and running with Privacy Engine in minutes

📦 Installation

Prerequisites

  • Rust 1.70+ - Latest stable Rust compiler
  • Cargo - Rust package manager
  • Git - Version control system

Add to Your Project

[dependencies]
privacy-engine = "0.1.0"

Build the Project

cargo build

🎯 Basic Usage

1. Import the Library

use privacy_engine::encrypt::encrypt_message;
use privacy_engine::decrypt::decrypt_shared_secret;
use privacy_engine::types::{RecipientInfo, Protocol, EncryptResult};
use aes_gcm::{Aes256Gcm, aead::{Aead, KeyInit}, Key, Nonce};

2. Encrypt a Message

// Prepare your message
let message = b"Hello, secure world!";

// Define recipients
let recipients = vec![
    RecipientInfo {
        pubkey: user1_pubkey,  // Vec<u8> - recipient's public key
        protocol: Protocol::Starknet,
    },
    RecipientInfo {
        pubkey: user2_pubkey,  // Vec<u8> - recipient's public key
        protocol: Protocol::X25519,
    },
];

// Encrypt the message
let result: EncryptResult = encrypt_message(message, recipients)?;

3. Decrypt a Message

// For each recipient, decrypt using their private key
let recipient_key = &result.recipient_keys[0]; // Get the first recipient's wrapped key

// Unwrap the symmetric key using recipient's private key
let symmetric_key = decrypt_shared_secret(&recipient_private_key, recipient_key)?;

// Decrypt the message using the symmetric key
let cipher = Aes256Gcm::new(Key::<Aes256Gcm>::from_slice(&symmetric_key));
let nonce = Nonce::from_slice(&result.nonce);
let plaintext = cipher.decrypt(nonce, result.ciphertext.as_ref())?;

println!("Decrypted message: {}", String::from_utf8_lossy(&plaintext));

🔧 Environment Setup

For Testing with Starknet

Create a .env file in your project root:

# User 1 (Primary)
TEST_PRIVKEY=0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
TEST_PUBKEY=0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890
TEST_MSG_HASH=0xdeadbeef1234567890abcdef1234567890abcdef1234567890abcdef1234567890

# User 2 (Optional)
USER2_PRIVATEKEY=0x9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba
USER2_PUBLICKEY=0xfedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210

Key Formats

🔗 Starknet

Use Felt (Field Element) format as hex strings

🔐 X25519

Use raw 32-byte keys (can be hex-encoded)

🧪 Running Tests

Basic Tests

cargo test

Integration Test with Pretty Output

cargo test --test starknet_multi -- --nocapture

This will run the multi-recipient encryption test with detailed, formatted output showing each stage of the encryption/decryption process.

📁 Project Structure

privacy-engine/
├── src/
│   ├── encrypt.rs          # Main encryption functionality
│   ├── decrypt.rs          # Decryption utilities
│   ├── types.rs            # Core data structures
│   ├── traits/
│   │   └── crypto.rs       # Cryptographic protocol trait
│   └── chains/
│       ├── starknet.rs     # Starknet protocol implementation
│       └── x25519.rs       # X25519 protocol implementation
├── tests/
│   └── starknet_multi.rs   # Integration tests
└── docs/                   # Documentation

🚀 Quick Examples

Multi-Recipient Encryption

use privacy_engine::encrypt::encrypt_message;
use privacy_engine::types::{RecipientInfo, Protocol};

// Encrypt for multiple recipients with different protocols
let message = b"Hello, secure world!";
let recipients = vec![
    RecipientInfo {
        pubkey: starknet_user_pubkey,
        protocol: Protocol::Starknet,
    },
    RecipientInfo {
        pubkey: x25519_user_pubkey,
        protocol: Protocol::X25519,
    },
];

let result = encrypt_message(message, recipients)?;
println!("Encrypted for {} recipients", result.recipient_keys.len());

Protocol-Specific Operations

use privacy_engine::chains::starknet::StarknetProtocol;
use privacy_engine::chains::x25519::X25519Protocol;

// Starknet signing and verification
let starknet = StarknetProtocol;
let signature = starknet.sign_message(&private_key, &message_hash)?;
let is_valid = starknet.verify_signature(&public_key, &message_hash, &signature)?;

// X25519 key generation
let x25519 = X25519Protocol::new();
let (private_key, public_key) = x25519.generate_keypair()?;

🔍 Troubleshooting

❌ Compilation Errors

Ensure you're using Rust 1.70+ and all dependencies are properly installed.

🔑 Missing Dependencies

Run `cargo build` to download and compile all required dependencies.

🌍 Environment Variables

Check that your `.env` file is properly formatted and located in the project root.

🔐 Key Format

Ensure keys are in the correct format for your chosen protocol.

📚 Next Steps

Ready to Learn More?

🏗️ Architecture

Understand the design principles

🔧 Protocols

Learn about supported protocols

💡 Examples

See practical use cases

🔒 Security

Security best practices

🆘 Getting Help

  • 📖 Documentation: Check the API Reference for detailed function documentation
  • 💡 Examples: Review the Examples for working code samples
  • 🐛 Issues: Open an issue on GitHub for bugs or feature requests
  • 💬 Discussions: Join community discussions for help and ideas

Ready to build secure, multi-protocol applications? 🚀



Continue to Architecture →

Explore Protocols →