Skip to content

README.md

Latest commit

 

History

History
282 lines (215 loc) · 12 KB

README.md

File metadata and controls

282 lines (215 loc) · 12 KB

Python Security License Platform

🔐 Local Password Manager

A secure, zero-knowledge CLI password manager with military-grade encryption

Fernet PBKDF2 SHA-256

✨ Features

Feature Description
🔒 Zero-Knowledge Your passwords are never stored in plain text
🔐 Fernet Encryption AES-128-CBC + HMAC-SHA256 for data protection
🔑 PBKDF2HMAC 480,000 iterations for secure key derivation
🔄 Recovery System Recovery key + security questions for account recovery
💻 Cross-Platform Works on Windows, Linux, and macOS
🎨 Beautiful CLI Colorful terminal interface with ASCII art
📦 Modular Design Clean, maintainable codebase

� Screenshots

Login Screen

                          ██████████████                          
                    ██████░░░░░░░░░░░░░░██████                    
                ████░░░░░░░░░░░░░░░░░░░░░░░░░░████                
              ██░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░██              
            ██░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░██            

    ╔═══════════════════════════════════════════════════════════════════════════╗
    ║   ██████╗  █████╗ ███████╗███████╗██╗    ██╗ ██████╗ ██████╗ ██████╗      ║
    ║   ██╔══██╗██╔══██╗██╔════╝██╔════╝██║    ██║██╔═══██╗██╔══██╗██╔══██╗     ║
    ║   ██████╔╝███████║███████╗███████╗██║ █╗ ██║██║   ██║██████╔╝██║  ██║     ║
    ║   ██║     ██║  ██║███████║███████║╚███╔███╔╝╚██████╔╝██║  ██║██████╔╝     ║
    ╚═══════════════════════════════════════════════════════════════════════════╝

    ═══════════════════════════════════════════════════════════════════════════
    ║ ⚠  WARNING: UNAUTHORIZED ACCESS IS STRICTLY PROHIBITED ⚠               ║
    ═══════════════════════════════════════════════════════════════════════════

🚀 Quick Start

Prerequisites

  • Python 3.8 or higher
  • pip (Python package manager)

Installation

# Clone the repository
git clone https://github.com/YOUR_USERNAME/password-manager.git
cd password_manager

# Install dependencies
pip install -r requirements.txt

# Run the application
python main.py

First Run

  1. Create Master PIN - This is your main password (minimum 4 characters)
  2. Set Security Questions - Choose 3 questions for identity verification
  3. Save Recovery Key - Store this key safely! It's your only way to recover access

� Usage

Main Menu

    ┌─────────────────────────────────────┐
    │            MENU UTAMA               │
    ├─────────────────────────────────────┤
    │  [1] 📋 View All Passwords          │
    │  [2] ➕ Add New Password            │
    │  [3] 🔍 Search Password             │
    │  [4] 🗑️  Delete Password            │
    │  [5] 🔄 Change Master PIN           │
    │  [6] 🚪 Exit                        │
    └─────────────────────────────────────┘

Commands

Command Description
1 Display all stored passwords in a table
2 Add a new password entry (Service, Username, Password)
3 Search passwords by service name or username
4 Delete a password entry
5 Change your Master PIN
6 Exit the application

🔒 Security Architecture

┌─────────────────────────────────────────────────────────────┐
│                      USER INPUT                              │
│                    (Master PIN)                              │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                     PBKDF2HMAC                               │
│  • Algorithm: SHA-256                                        │
│  • Iterations: 480,000 (OWASP 2023 Standard)                │
│  • Salt: 32 bytes cryptographically random                  │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                   FERNET ENCRYPTION                          │
│  • AES-128-CBC for confidentiality                          │
│  • HMAC-SHA256 for authentication                           │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                     data.vault                               │
│              (Encrypted Binary File)                         │
└─────────────────────────────────────────────────────────────┘

Security Features

  • Zero-Knowledge: Passwords are encrypted locally; even if someone gets your vault file, they can't read it without the PIN
  • Key Derivation: Uses PBKDF2 with 480,000 iterations to resist brute-force attacks
  • Authenticated Encryption: Fernet provides both encryption and authentication
  • Secure Recovery: Two-factor recovery using both Recovery Key and Security Questions

🔑 Recovery System

If You Forget Your PIN

  1. Run python main.py
  2. Type R when prompted for PIN
  3. Enter your Recovery Key (format: XXXX-XXXX-XXXX-XXXX-XXXX)
  4. Answer at least 2 out of 3 security questions correctly
  5. Create a new PIN or view your current PIN

Recovery Key Tips

  • ✅ Write it on paper and store in a safe
  • ✅ Store in a different password manager
  • ✅ Keep in a physical vault
  • ❌ Don't store on the same computer
  • ❌ Don't share with anyone
  • ❌ Don't take photos with unsecured devices

📁 Project Structure

password-manager/
├── main.py                     # Entry point
├── requirements.txt            # Dependencies
├── README.md                   # Documentation
├── .gitignore                  # Git ignore rules
│
└── password_manager/           # Main package
    ├── __init__.py            # Package metadata
    ├── config.py              # Configuration & constants
    ├── crypto.py              # Encryption & key derivation
    ├── storage.py             # Database operations
    ├── auth.py                # Authentication
    ├── recovery.py            # Recovery system
    ├── menu.py                # Menu handlers
    ├── ui.py                  # User interface
    └── styles.py              # Colors & ASCII art

Module Responsibilities

Module Purpose
config.py Constants, paths, security settings
crypto.py Encryption, decryption, hashing, key derivation
storage.py CRUD operations for vault files
auth.py Login and vault creation
recovery.py Security questions and recovery process
menu.py Handler for each menu option
ui.py Display functions and formatting
styles.py ANSI colors and ASCII art

⚠️ Important Security Notes

Files Generated (DO NOT COMMIT!)

File Description
data.vault Your encrypted passwords
salt.key Unique salt for encryption
recovery.vault Encrypted recovery data
security.vault Encrypted security questions

These files are already in .gitignore and should NEVER be committed to version control.

Best Practices

  1. Use a strong Master PIN - Combine letters, numbers, and symbols
  2. Keep backups - Copy your .vault and .key files to secure locations
  3. Store Recovery Key safely - This is your only way to recover if you forget the PIN
  4. Don't share files - Each installation should have its own vault

�️ Development

Requirements

cryptography>=41.0.0

Running Tests

# Run the application
python main.py

Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📜 License

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

🙏 Acknowledgments

  • cryptography - Python cryptographic library
  • Fernet - Symmetric encryption recipe
  • PBKDF2 - Password-Based Key Derivation Function

Made with ❤️ for secure password management

⚠️ Use at your own risk. Always maintain backups of your vault files.