sha3sum 1.3.1

![Licence](https://img.shields.io/crates/l/sha3sum)
![Version](https://img.shields.io/crates/v/sha3sum)
[![dependency status](https://deps.rs/repo/gitlab/kurdy/sha3sum/status.svg)](https://deps.rs/repo/gitlab/kurdy/sha3sum)
![Download.io](https://img.shields.io/crates/d/sha3sum)
[![pipeline](https://gitlab.com/kurdy/sha3sum/badges/master/pipeline.svg)](https://gitlab.com/kurdy/sha3sum)

# sha3sum — Print or check SHA3 / Keccak digests

Command-line tool wrapping the [RustCrypto/hashes](https://github.com/RustCrypto/hashes) `sha3` crate.  
Options and output format mirror the GNU `sha256sum` / `sha512sum` family.

One goal of this project is a **cross-platform**, **dependency-light** binary with no external system libraries required.

---

## Supported algorithms

| Flag value | Algorithm |
|---|---|
| `224` / `sha3_224` | SHA3-224 |
| `256` / `sha3_256` | SHA3-256 |
| `384` / `sha3_384` | SHA3-384 |
| `512` / `sha3_512` | SHA3-512 |
| `Keccak224` | Keccak-224 |
| `Keccak256` | Keccak-256 |
| `Keccak256Full` | Keccak-256-full |
| `Keccak384` | Keccak-384 |
| `Keccak512` | Keccak-512 |

---

## Install

### From crates.io (recommended)
```sh
cargo install sha3sum
```

### Pre-built binaries
Binary packages for Linux (x86\_64, aarch64) and Windows (x86\_64) are available in the
[Package Registry](https://gitlab.com/kurdy/sha3sum/-/packages).  
See the [Wiki](https://gitlab.com/kurdy/sha3sum/-/wikis/home) for installation instructions.

### From source
```sh
git clone https://gitlab.com/kurdy/sha3sum.git
cd sha3sum
cargo build --release
# binary is at target/release/sha3sum
```

---

## Usage

```
sha3sum - compute and check SHA3 message digest.

Usage: sha3sum [OPTIONS] [FILES]...

Arguments:
  [FILES]...  Displays the check sum for the files

Options:
  -a, --algorithm <ALGORITHM>
          sha3 algorithm {224 256 384 512 Keccak224 Keccak256 Keccak256Full Keccak384 Keccak512}
  -c, --check <CHECK>
          read SHA3 sums and file path from a file and check them
  -b, --binary
          read using Binary mode (default)
      --quiet
          don't print OK for each successfully verified file
      --status
          don't output anything, status code shows success
      --tag
          create a BSD-style checksum
  -t, --text
          read using Text mode
  -l, --license
          Prints license information
  -h, --help
          Print help
  -V, --version
          Print version
```

### Examples

```sh
# Hash a single file with SHA3-256
sha3sum -a 256 file.bin

# Hash all files in a directory with Keccak-512
sha3sum -a Keccak512 ./data/

# Hash a text file in text mode (line-by-line, strips \r)
sha3sum -a 384 -t document.txt

# BSD-style output  →  SHA3_256 (file.bin) = abc123…
sha3sum -a 256 --tag file.bin

# Hash stdin
echo -n "hello" | sha3sum -a 256

# Verify a check file (GNU format or BSD format)
sha3sum -c checksums.txt

# Verify silently — check exit code only
sha3sum -c checksums.txt --status && echo "all OK"

# Verify and suppress OK lines
sha3sum -c checksums.txt --quiet
```

### Output formats

| Mode | Example |
|---|---|
| Binary (default) | `abc123… *./file.bin` |
| Text (`-t`) | `abc123… ./file.bin` |
| BSD tag (`--tag`) | `SHA3_256 (./file.bin) = abc123…` |
| Check result | `./file.bin Ok` / `./file.bin NOk` |

> **Note:** the separator between hash and filename is a **no-break space** (`U+00A0`),
> which prevents false splits when filenames contain regular spaces.

### Exit codes

| Code | Meaning |
|---|---|
| `0` | Success |
| `1` | Unused (reserved) |
| `2` | Wrong / missing parameters |
| `64` | File open / read error |
| `65` | Hash mismatch |

---

## Performance tuning

By default each file is read in **64 KB blocks**. Set `SHA3_BLOCK_SIZE` at **compile time**
to override (value is embedded in the binary):

```sh
SHA3_BLOCK_SIZE=131072 cargo build --release
```

Multiple files are hashed **in parallel** using one thread per logical CPU
(`std::thread::available_parallelism`).

---

## Development

### Requirements

- Rust ≥ 1.85 (MSRV — required for edition 2024)

### Run tests
```sh
cargo test
```

### Run benchmarks

Benchmarks use [Criterion](https://github.com/bheisler/criterion.rs) and produce
statistical reports with HTML output under `target/criterion/`.

```sh
# Full benchmark suite
cargo bench

# Single group  (algorithms | read_strategy | read_mode | file_sizes)
cargo bench -- algorithms
```

| Group | What it measures |
|---|---|
| `algorithms` | All 9 SHA3/Keccak variants — 2 MB file, MB/s throughput |
| `read_strategy` | Block-loop vs `io::copy` — 10 MB file |
| `read_mode` | Binary vs text mode — 4 KB UTF-8 file |
| `file_sizes` | SHA3-256 scaling: 4 KB / 2 MB / 10 MB |

### Check-file format

Two formats are accepted by `-c`:

**GNU format** (produced by default):
```
<hash><NBSP>*<filename>     # binary mode
<hash><NBSP><filename>      # text mode
```

**BSD tag format** (produced by `--tag`):
```
<ALGORITHM><NBSP>(<filename>)<NBSP>=<NBSP><hash>
```

---

## Tested platforms

| OS | Architecture |
|---|---|
| Linux | x86\_64 |
| Linux | aarch64 |
| Windows | x86\_64 |

---

## License

GPL-3.0-or-later — see [LICENSE](LICENSE).

[Sources on GitLab](https://gitlab.com/kurdy/sha3sum.git)