# EntroPy Password Generator (v0.4.9)

<div align="center">

  <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT">
  <img src="https://img.shields.io/badge/Made%20with-Python-blue" alt="Made with Python">
  <img src="https://img.shields.io/badge/Entropy%20Compliant-Proton%20%26%20NIST-green" alt="Entropy Compliant">
  <img src="https://img.shields.io/maintenance/yes/2025?label=Maintained" alt="Maintained">
  <a href="https://test.pypi.org/project/entropy-password-generator/"><img src="https://img.shields.io/badge/Project-Test%20PyPI-blue?logo=pypi" alt="Test PyPI Project"></a>

</div>

<br>

**EntroPy Password Generator** is a secure and customizable password generator developed in Python. It generates strong passwords with configurable character sets and calculates their entropy to evaluate robustness. The project provides 20 modes for secure password generation, ranging from 15 to 128 characters, with entropies between 95.70 bits and 830.98 bits, exceeding the [Proton©](https://proton.me/blog/what-is-password-entropy) recommended minimum of 75 bits and the cryptographic strength best practices outlined in [NIST SP 800-63B](https://pages.nist.gov/800-63-3/sp800-63b.html) and [NIST SP 800-132](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf).

---

## Disclaimer
Do not attempt to memorize the passwords generated by this tool. Instead, use a reliable password manager, such as [Bitwarden©](https://bitwarden.com/), which I personally recommend. The only password you should memorize is the master password for your password manager's vault, created with a strong combination of uppercase and lowercase letters, numbers, and special characters. Enable two-factor authentication (2FA) whenever possible to enhance security.

---

## Features
- Generates passwords with lengths between 15 and 128 characters.
- Supports uppercase letters (A-Z), lowercase letters (a-z), digits (0-9), and special characters (!@#$%^&*()_+-=[]{}|;:,.<>?~\\).
- Option to exclude visually ambiguous characters (e.g., 'I', 'L', 'O', '0') for better readability.
- Calculates password entropy (in bits) to evaluate strength.
- Displays a warning if the generated password's entropy is below 75 bits (Proton© standard), with suggestions to improve security.
- Command-line interface (CLI) for flexible usage.
- Uses Python's `secrets` module for cryptographically secure random generation.

---

## Requirements
- Python 3.8 or higher.
- No external dependencies (uses only standard Python libraries: `secrets`, `string`, `math`, `argparse`).

---

## Installation
1. Ensure you have Python 3.8 or higher installed.
2. Clone the repository:
   ```bash
   git clone https://github.com/gerivanc/entropy-password-generator.git
   cd entropy-password-generator
   ```
3. No additional dependencies are required, as the project uses only Python standard libraries.

---

## Installation from Test PyPI
To test the latest version of the EntroPy Password Generator, you can install it from the Test Python Package Index (Test PyPI):
```bash
pip install -i https://test.pypi.org/simple/ entropy-password-generator
```
Alternatively, install the project locally as a package:
```bash
pip install .
```
Then run with:
```bash
entropy-password-generator
```
Visit the [Test PyPI project page](https://test.pypi.org/project/entropy-password-generator/) or check the [release history](https://test.pypi.org/project/entropy-password-generator/#history) for more details.

> **Note**: Running the script with `python -m` may trigger a `RuntimeWarning` due to module loading issues. To avoid this, use the direct path: `python3 entropy_password_generator/password_generator.py`, or install as a package as shown above.

---

## Password Modes
The project includes 20 predefined password generation modes, divided into two blocks:

- **Block I (Modes 1–10)**: Fixed length of 24 characters, including ambiguous characters (e.g., 'I', 'O', '0'), with varying character sets to balance readability and security. Ideal for general-purpose passwords, such as website logins or application credentials.
- **Block II (Modes 11–20)**: Varying lengths (15 to 128 characters), mostly excluding ambiguous characters for enhanced readability. These modes cater to sensitive applications, from personal accounts to cryptographic keys and enterprise-grade security.

### Password Modes Summary
The table below summarizes the 20 password generation modes, ordered by increasing entropy, highlighting their configurations, character set sizes (\( R \)), and recommended use cases:

| Mode | Length | Character Set | R (Charset Size) | Entropy (bits) | Security Level | Use Case |
|------|--------|---------------|------------------|----------------|----------------|----------|
| 11 | 15 | Full (uppercase, lowercase, digits, symbols, no ambiguous) | 90 | 95.70 | Strong | Personal accounts (email, social media) |
| 13 | 20 | Lowercase + Digits (no ambiguous) | 31 | 99.00 | Strong | Basic application logins |
| 14 | 20 | Uppercase + Digits (no ambiguous) | 31 | 99.00 | Strong | Device authentication |
| 12 | 18 | Full (uppercase, lowercase, digits, symbols, with ambiguous) | 94 | 117.72 | Very Strong | Professional accounts (work email, VPN) |
| 4 | 24 | Uppercase + Digits (with ambiguous) | 36 | 124.08 | Very Strong | Legacy systems requiring uppercase |
| 5 | 24 | Lowercase + Digits (with ambiguous) | 36 | 124.08 | Very Strong | Readable passwords for manual entry |
| 6 | 24 | Digits + Special (with ambiguous) | 42 | 128.64 | Very Strong | API tokens with limited character sets |
| 3 | 24 | Uppercase + Lowercase (with ambiguous) | 52 | 136.80 | Very Strong | General-purpose website logins |
| 1 | 24 | Lowercase + Special (with ambiguous) | 58 | 140.59 | Very Strong | Secure notes or backup codes |
| 2 | 24 | Uppercase + Special (with ambiguous) | 58 | 140.59 | Very Strong | Administrative console access |
| 7 | 24 | Uppercase + Lowercase + Digits (with ambiguous) | 62 | 142.80 | Very Strong | Multi-user system credentials |
| 9 | 24 | Uppercase + Digits + Special (with ambiguous) | 68 | 145.68 | Very Strong | Database access keys |
| 10 | 24 | Lowercase + Digits + Special (with ambiguous) | 68 | 145.68 | Very Strong | Secure file encryption |
| 8 | 24 | Uppercase + Lowercase + Special (with ambiguous) | 84 | 153.12 | Extremely Strong | High-security application logins |
| 15 | 24 | Full (uppercase, lowercase, digits, symbols, no ambiguous) | 90 | 153.12 | Extremely Strong | Enterprise-grade passwords |
| 16 | 32 | Full (uppercase, lowercase, digits, symbols, no ambiguous) | 90 | 204.16 | Cryptographic Grade | API keys for sensitive services |
| 17 | 42 | Full (uppercase, lowercase, digits, symbols, no ambiguous) | 90 | 267.96 | Cryptographic Grade | Server authentication tokens |
| 18 | 60 | Full (uppercase, lowercase, digits, symbols, no ambiguous) | 90 | 382.80 | Ultra Secure | Financial system credentials |
| 19 | 75 | Full (uppercase, lowercase, digits, symbols, no ambiguous) | 90 | 478.50 | Ultra Secure | Master keys for password managers |
| 20 | 128 | Full (uppercase, lowercase, digits, symbols, no ambiguous) | 90 | 830.98 | Ultra Secure (Theoretical Maximum) | Cryptographic keys, blockchain wallets |

> **Note**: Entropy values are theoretical maximums, assuming uniform random selection. The requirement of at least one character per selected type (e.g., uppercase, lowercase) slightly reduces effective entropy for shorter passwords. This reduction is negligible, and all modes exceed Proton© and NIST standards.

---

## CLI Options
- `--mode <number>`: Select a predefined password generation mode (1 to 20). Overrides other configuration options.
- `--length <length>`: Set password length (15 to 128, default: 72). Ignored if `--mode` is specified.
- `--no-uppercase`: Exclude uppercase letters. Ignored if `--mode` is specified.
- `--no-lowercase`: Exclude lowercase letters. Ignored if `--mode` is specified.
- `--no-digits`: Exclude digits. Ignored if `--mode` is specified.
- `--no-special`: Exclude special characters. Ignored if `--mode` is specified.
- `--with-ambiguous`: Include ambiguous characters. Ignored if `--mode` is specified.

---

## Usage
Run the generator via the command-line interface by specifying a mode or custom configuration. After installing from Test PyPI or locally, use:
```bash
entropy-password-generator --mode <number>
```
Alternatively, run directly from the repository:
```bash
python3 entropy_password_generator/password_generator.py --mode <number>
```

else

Alternatively, run directly from the repository:
```bash
python3 entropy_password_generator/password_generator.py --length <number>
```

### Screenshots
Below is an example of the CLI output for **Mode 15**:
![Mode 15 Output](https://github.com/gerivanc/entropy-password-generator/blob/main/entropy_password_generator/screenshots/--mode15.png)
*Note*: Screenshot using the command: `python3 entropy_password_generator/password_generator.py --mode 15`. Demonstration image of the output result of the function.

Below is an example of the CLI output for  **--length**:
![--length 85 Output](https://github.com/gerivanc/entropy-password-generator/blob/main/entropy_password_generator/screenshots/--length85.png)
*Note*: Screenshot using the command: `python3 entropy_password_generator/password_generator.py --length 85`. Demonstration image of the output result of the function. Here you can set the password length between 15-128 characters.

### Using Predefined Modes
Below are examples for each of the 20 predefined modes, showcasing their configurations and entropy:

#### Block I (All with ambiguous characters, length 24)
**Mode 1: Lowercase + Special characters**
```bash
python3 entropy_password_generator/password_generator.py --mode 1
```
```
Generated password: zq!wr#ty&pm$nk%lc*hj=vx
Entropy: 140.59 bits
```

**Mode 2: Uppercase + Special characters**
```bash
python3 entropy_password_generator/password_generator.py --mode 2
```
```
Generated password: PZ#KX!WQ@JY&M-N=HL+R^T
Entropy: 140.59 bits
```

**Mode 3: Uppercase + Lowercase**
```bash
python3 entropy_password_generator/password_generator.py --mode 3
```
```
Generated password: KjZmPqRtYxWvLcFnBsHdIkOg
Entropy: 136.80 bits
```

**Mode 4: Uppercase + Digits**
```bash
python3 entropy_password_generator/password_generator.py --mode 4
```
```
Generated password: AX7ZQ4R9Y2M8P5T3K6W0N1J
Entropy: 124.08 bits
```

**Mode 5: Lowercase + Digits**
```bash
python3 entropy_password_generator/password_generator.py --mode 5
```
```
Generated password: ax7zq4r9y2m8p5t3k6w0n1j
Entropy: 124.08 bits
```

**Mode 6: Digits + Special characters**
```bash
python3 entropy_password_generator/password_generator.py --mode 6
```
```
Generated password: 7!4#9$2&8%5^3*6-0=2+|1~
Entropy: 128.64 bits
```

**Mode 7: Uppercase + Lowercase + Digits**
```bash
python3 entropy_password_generator/password_generator.py --mode 7
```
```
Generated password: Ax7Zq4Ry9Mk2Pl8Tv5Cn3Hw
Entropy: 142.80 bits
```

**Mode 8: Uppercase + Lowercase + Special characters**
```bash
python3 entropy_password_generator/password_generator.py --mode 8
```
```
Generated password: Kj#nPq@Rt!xWv&MbHs$YkLc
Entropy: 153.12 bits
```

**Mode 9: Uppercase + Digits + Special characters**
```bash
python3 entropy_password_generator/password_generator.py --mode 9
```
```
Generated password: AX!7ZQ#4R$9Y@2M&8P%5T*3
Entropy: 145.68 bits
```

**Mode 10: Lowercase + Digits + Special characters**
```bash
python3 entropy_password_generator/password_generator.py --mode 10
```
```
Generated password: zq!9wr#4ty&2pm$8nk%5lc*3
Entropy: 145.68 bits
```

#### Block II (Mixed configurations)
**Mode 11: All character types, no ambiguous characters (length 15)**
```bash
python3 entropy_password_generator/password_generator.py --mode 11
```
```
Generated password: Kj9mPqRtY2xWvN8
Entropy: 95.70 bits
```

**Mode 12: All character types, with ambiguous characters (length 18)**
```bash
python3 entropy_password_generator/password_generator.py --mode 12
```
```
Generated password: Hs#7kQw|Zx9mPv!RtY
Entropy: 117.72 bits
```

**Mode 13: Lowercase + Digits, no ambiguous characters (length 20)**
```bash
python3 entropy_password_generator/password_generator.py --mode 13
```
```
Generated password: zkmpxqrytwvbcfnhdjg2
Entropy: 99.00 bits
```

**Mode 14: Uppercase + Digits, no ambiguous characters (length 20)**
```bash
python3 entropy_password_generator/password_generator.py --mode 14
```
```
Generated password: ZKMPXQRYTWVBCFNHDJG2
Entropy: 99.00 bits
```

**Mode 15: All character types, no ambiguous characters (length 24)**
```bash
python3 entropy_password_generator/password_generator.py --mode 15
```
```
Generated password: Hs7kQwZx9mPvRtY2nB4cF8j
Entropy: 153.12 bits
```

**Mode 16: All character types, no ambiguous characters (length 32)**
```bash
python3 entropy_password_generator/password_generator.py --mode 16
```
```
Generated password: Ax9kQw#Z2vRt$Y4mPv&B6nJcF8tH3x
Entropy: 204.16 bits
```

**Mode 17: All character types, no ambiguous characters (length 42)**
```bash
python3 entropy_password_generator/password_generator.py --mode 17
```
```
Generated password: Kj9mPq@RtY2xWv#N8bZ4cF6kH3tL5nM7pQ2r
Entropy: 267.96 bits
```

**Mode 18: All character types, no ambiguous characters (length 60)**
```bash
python3 entropy_password_generator/password_generator.py --mode 18
```
```
Generated password: Ax9kQw#Z2vRt$Y4mPv&B6nJcF8tH3xK5zL7qM2wN4yP8rT9bV
Entropy: 382.80 bits
```

**Mode 19: All character types, no ambiguous characters (length 75)**
```bash
python3 entropy_password_generator/password_generator.py --mode 19
```
```
Generated password: Kj9mPq@RtY2xWv#N8bZ4cF6kH3tL5nM7pQ2rT9yU4wV6xB8zK2mN5qP7tR9v
Entropy: 478.50 bits
```

**Mode 20: All character types, no ambiguous characters (length 128)**
```bash
python3 entropy_password_generator/password_generator.py --mode 20
```
```
Generated password: Ax9kQw#Z2vRt$Y4mPv&B6nJcF8tH3xK5zL7qM2wN4yP8rT9bV6cW2xZ5kQ7mN3tP9vR4yB8nF2wH6zJ5kL9qT3mV7xP2rN4cY8bW6tK9zQ5vM3nH2xF7pR4yT8k
Entropy: 830.98 bits
```

### Using Custom Configuration
Combine CLI options to create passwords tailored to specific needs. Below are examples for common scenarios, ensuring a balance between security and usability:

#### Wi-Fi Password (32 chars, all types, no ambiguous)
```bash
python3 entropy_password_generator/password_generator.py --length 32
```
```
Generated password: Ax9kQw#Z2vRt$Y4mPv&B6nJcF8tH3x
Entropy: 204.16 bits
```

*Note*: Here you can set the password length between 15-128 characters.

#### Simple Readable Password (15 chars, lowercase + digits, no ambiguous)
```bash
python3 entropy_password_generator/password_generator.py --length 15 --no-uppercase --no-special
```
```
Generated password: ax9zq4r7y2m8p5t
Entropy: 74.25 bits (Warning: Below Proton© standard)
```

#### API Token (24 chars, uppercase + digits + special, with ambiguous)
```bash
python3 entropy_password_generator/password_generator.py --length 24 --no-lowercase --with-ambiguous
```
```
Generated password: AX!7ZQ#4R$9Y@2M&8P%5T*3I
Entropy: 145.68 bits
```

#### Cryptographic Key (128 chars, digits + special, no ambiguous)
```bash
python3 entropy_password_generator/password_generator.py --length 128 --no-uppercase --no-lowercase
```
```
Generated password: 7!4#9$2&8%5^3*6+2=9-1~4#7$2&8%5^3*6+2=9-1~4#7$2&8%5^3*6+2=9-1~4#7$2&8%5^3*6+2=9-1~4#7$2&8%5^3*6+2=9-1~4#7$2&8%5^3*6+2=9-1~4#7$2&
Entropy: 830.98 bits
```

Explore these options to create passwords tailored to your specific requirements, ensuring optimal security.

### Suggestions for Password Types
The table below suggests six of the strongest password **`modes`** for daily use, covering a range of online services:

| Mode (Entropy) | Recommended Service |
|----------------|---------------------|
| `Mode 8 (153.12 bits)` | High-security website logins (e.g., cloud storage, VPNs) |
| `Mode 9 (145.68 bits)` | Database or API access (e.g., developer tools, server management) |
| `Mode 10 (145.68 bits)` | Secure file encryption (e.g., encrypted backups, sensitive documents) |
| `Mode 15 (153.12 bits)` | Enterprise accounts (e.g., corporate email, project management tools) |
| `Mode 19 (478.50 bits)` | Password manager master keys (e.g., Bitwarden, 1Password) |
| `Mode 20 (830.98 bits)` | Cryptographic keys (e.g., blockchain wallets, SSH keys) |

These modes ensure robust protection for critical accounts, balancing entropy and usability.

---

## Password Entropy Calculation

> **Secure by Design**  
> With Python's `secrets` module, the EntroPy Password Generator ensures cryptographically secure randomization, delivering passwords that exceed Proton© (75 bits) and NIST (80+ bits) entropy standards.

The generator calculates password entropy using the formula: \( E(R) = \log_2(R^L) \), where:
- \( R \): Size of the character set.
- \( L \): Password length.
- \( E(R) \): Entropy in bits (higher is stronger).

All 20 modes produce passwords with entropies from 95.70 to 830.98 bits, surpassing Proton© (75 bits) and NIST (80+ bits) standards. For example:
- Mode 11 (15 chars, full no ambiguous, \( R=90 \)): \( \log_2(90) \times 15 \approx 95.70 \) bits.
- Mode 20 (128 chars, full no ambiguous, \( R=90 \)): \( \log_2(90) \times 128 \approx 830.98 \) bits.

> **Note**: Entropy values assume ideal randomness, achieved via the `secrets` module. The requirement of at least one character per selected type slightly reduces effective entropy for shorter passwords, but all modes remain compliant with security standards.

For a detailed analysis, including entropy for each mode and comparisons with mobile authentication methods, see [Password Entropy Calculation](https://github.com/gerivanc/entropy-password-generator/blob/main/PASSWORDENTROPYCALCULATION.md).

---

## Reporting Issues
Help us improve **EntroPy Password Generator** by reporting bugs or suggesting enhancements using our [issue template](https://github.com/gerivanc/entropy-password-generator/blob/main/.github/ISSUE_TEMPLATE/issue_template.md).

---

## Contributing
Want to contribute? Check out our [Contributing Guidelines](https://github.com/gerivanc/entropy-password-generator/blob/main/CONTRIBUTING.md) to get started!

---

## Security - Reporting a Vulnerability 
If you discover a security vulnerability in EntroPy Password Generator, please report it immediately to ensure the safety of all users. See the [Security](https://github.com/gerivanc/entropy-password-generator/blob/main/SECURITY.md) for more details.

---

## Release Notes
See the [RELEASE.md](https://github.com/gerivanc/entropy-password-generator/blob/main/RELEASE.md) for detailed release notes for each version.

---

## Changelog
See the [Changelog](https://github.com/gerivanc/entropy-password-generator/blob/main/CHANGELOG.md) for a detailed history of changes to this project.

---

## Support This Project
If you find EntroPy Password Generator useful, consider supporting its development with a donation:

[<img src="https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif" alt="Donate with PayPal">](https://www.paypal.com/ncp/payment/FYUGSCLQRSQDN)

---

## Contact
For questions or feedback, please contact: dean-grumbly-plop@duck.com.

---

## Visitors
<div align="center">

  ![Visitor Count](https://profile-counter.glitch.me/entropy-password-generator/count.svg)

</div>

---

## License
This project is licensed under the MIT License. See the [License](https://github.com/gerivanc/entropy-password-generator/blob/main/LICENSE.md) for details.

---

## Copyright © 2025 Gerivan Costa dos Santos
