# paspio

[![docs](https://img.shields.io/docsrs/paspio)](https://docs.rs/paspio/latest/paspio)
[![version](https://img.shields.io/crates/v/paspio)](https://crates.io/crates/paspio)

paspio, short for _pasvorta entropio_, is a password entropy calculator/library.

## What is password entropy?

The [entropy of a password](https://en.wikipedia.org/wiki/Password_strength#Entropy_as_a_measure_of_password_strength)
measures its unpredictability against brute force attacks in terms of _bits_,
other common techniques of password cracking include dictionary attacks, which
this tool **does not** cover.

## Notice

This tool has not been audited by any third-party entities, and I am
in no way a certified expert in the security field. Use this software
at your own risk.

## Limitations

This tool doesn't cover the use of emojis, or any other character sets
besides the latin alphabet, see "[How does it calculate
entropy](#how-does-it-calculate-entropy)" for more information.

## What is this tool useful for?

paspio solves the simple need of verifying password entropy
**locally**.

## How does it calculate entropy?

```bash
Entropy = L * log2(R)
```

|              Symbol set | Elements                          | Cardinality | Notes               |
|------------------------:|:----------------------------------|:-----------:|:--------------------|
| Lowercase latin letters | [a-z]                             | 26          |                     |
| Uppercase latin letters | [A-Z]                             | 26          |                     |
|                  Digits | [0-9]                             | 10          |                     |
|                 Symbols | !"#$%&'()*+,-.:;<=>?@[]^_`{/\|\\} | 32          | Whitespace included |

Where:
- `L` is the length of the password.
- `R` is the sum of the cardinality of each set a password exists in.

## Usage

### As a program

Pass one or more passwords to paspio to get their entropy.

```bash
paspio "liuLe9ohjub8hu2ie" # 101.22 bits
```

Pipe a pwgen-generated password to paspio.

```bash
pwgen -sync 20 1 | paspio # 137.65 bits
```

### As a library

Add the following to your project's `Cargo.toml`:

```toml
paspio = "0.3"
```

## Installation

### [C](https://crates.io/crates/paspio/)argo

```
cargo install paspio
```

### [A](https://aur.archlinux.org/packages/paspio-git/)rch User Repository

```
git clone https://aur.archlinux.org/paspio-git.git
cd paspio-git
makepkg -si
```

### Build from source

```
git clone https://git.sr.ht/~grtcdr/paspio
cd paspio
cargo build --release
```

## Acknowledgements

- Thank you to Federico Torrielli for shipping and maintaining paspio
  in the Arch User Repository.