# Hashing and encoding

---

# Hashing and encoding

_Peios / Using Peios / Peiosutils / Hashing and encoding_

> The commands that compute checksums and hashes to verify data integrity, and that encode binary data into text and back.

This topic covers two related jobs. **Hashing** reduces a file to a short fixed-size value — a checksum — that can be used to tell whether the file has changed. **Encoding** rewrites binary data as plain text so it can travel safely through channels that only handle text.

## The commands

**Checksums and hashes**

| Command | Purpose |
|---|---|
| [checksum commands](/peios/using-peios/peiosutils/hashing-and-encoding/checksum-commands.md) | `md5sum`, `sha1sum`, `sha256sum`, and the rest — one command per hash algorithm. |
| [`cksum`](/peios/using-peios/peiosutils/hashing-and-encoding/cksum.md) | The general checksum tool — any of the algorithms, selected by an option. |
| [`sum`](/peios/using-peios/peiosutils/hashing-and-encoding/sum.md) | A small, legacy block-checksum. |

**Encoding**

| Command | Purpose |
|---|---|
| [`base32` and `base64`](/peios/using-peios/peiosutils/hashing-and-encoding/base32-and-base64.md) | Encode binary data as text using the base32 or base64 alphabet, and decode it back. |
| [`basenc`](/peios/using-peios/peiosutils/hashing-and-encoding/basenc.md) | The general encoder — base64, base32, base16, and several more, selected by an option. |

## What these commands are not

It is worth being clear up front, because both jobs are easy to mistake for something they are not.

**A hash is not encryption.** Hashing is one-way: a checksum tells you *whether* data has changed, but the original cannot be recovered from it. It protects against corruption and detects tampering — it does not keep anything secret.

**Encoding is not encryption either.** `base64` rewrites data into a text-safe form, but anyone can decode it straight back — it is a change of *representation*, not of secrecy. Encoding something does not protect it.

Neither hashing nor encoding hides data. They are about *integrity* and *transport*, not confidentiality.

## Where to start

To verify a file you downloaded against a published checksum, read the [checksum commands](/peios/using-peios/peiosutils/hashing-and-encoding/checksum-commands.md). To turn binary data into something safe to paste into text, read [`base32` and `base64`](/peios/using-peios/peiosutils/hashing-and-encoding/base32-and-base64.md).

---

# Checksum commands

_Peios / Using Peios / Peiosutils / Hashing and encoding_

> md5sum, sha1sum, sha256sum and the rest — the family of commands that each compute and verify one fixed hash algorithm.

This page covers a family of commands that all work the same way and differ only in **which hash algorithm** they use:

| Command | Algorithm | Digest size |
|---|---|---|
| `md5sum` | MD5 | 128-bit |
| `sha1sum` | SHA-1 | 160-bit |
| `sha224sum` | SHA-224 | 224-bit |
| `sha256sum` | SHA-256 | 256-bit |
| `sha384sum` | SHA-384 | 384-bit |
| `sha512sum` | SHA-512 | 512-bit |
| `b2sum` | BLAKE2b | up to 512-bit |

```
sha256sum [options] [file...]
```

Everything below is written with `sha256sum`, but applies to every command in the table.

## Computing a checksum

Run plainly, the command prints the hash of each file, followed by the file name:

```
$ sha256sum installer.iso
9f86d0818884...b1a5  installer.iso
```

With no file, it reads standard input. The hash is a fingerprint of the file's contents: change a single byte and the hash changes completely.

## Verifying with a checksum

The everyday use is **verification** — confirming a file is exactly what it should be, usually a download.

First, the file's publisher computes a checksum and publishes it, often in a file:

```
$ sha256sum installer.iso > installer.iso.sha256
```

Then anyone with the file and that checksum file can verify:

```
$ sha256sum -c installer.iso.sha256
installer.iso: OK
```

`-c` reads each `hash  filename` line, recomputes the hash, and reports `OK` or `FAILED`. A `FAILED` means the file is not the one the checksum was made from — corrupted in transit, or altered.

| Option | Effect |
|---|---|
| `-c`, `--check` | Read checksums from the given files and verify them. |
| `--ignore-missing` | In check mode, do not fail over files that are listed but absent. |
| `--quiet` | In check mode, print nothing for files that pass — only failures. |
| `--status` | In check mode, print nothing at all; report only through the exit status. |
| `-w`, `--warn` | Warn about improperly formatted lines in the checksum file. |
| `--strict` | In check mode, fail if any checksum line is malformed. |

## Output format

| Option | Effect |
|---|---|
| `--tag` | Produce a tagged line — `SHA256 (file) = hash` — that records which algorithm was used. |
| `--untagged` | Produce the plain `hash  file` line. This is the default. |
| `-z`, `--zero` | End each output line with a NUL character instead of a newline. |
| `-b`, `--binary` | Note the file as read in binary mode. |
| `-t`, `--text` | Note the file as read in text mode. |

`b2sum` additionally accepts `-l`, `--length=BITS` to produce a shorter BLAKE2b digest.

## A note on choosing an algorithm

These commands detect change — but not all of them resist a *deliberate* attempt to forge a match. MD5 and SHA-1 can be defeated by an attacker who wants two different files to share a checksum. They are still fine for catching accidental corruption, but for verifying that a file has not been **tampered with**, use a SHA-2 command (`sha256sum` and up) or `b2sum`.

## Exit status

| Code | Meaning |
|---|---|
| `0` | The checksums were computed, or — in check mode — every file verified. |
| `1` | In check mode, a file failed verification. |
| `2` | An error — a file could not be read, or a checksum file was malformed. |

---

# cksum

_Peios / Using Peios / Peiosutils / Hashing and encoding_

> The general checksum tool — compute or verify a digest with any of the supported algorithms.

`cksum` is the **general** checksum command. Where each of the [checksum commands](/peios/using-peios/peiosutils/hashing-and-encoding/checksum-commands.md) is fixed to one algorithm, `cksum` does any of them — the algorithm is an option.

```
cksum [options] [file...]
```

```
$ cksum installer.iso
3915528286 372736000 installer.iso
$ cksum -a sha256 installer.iso
9f86d0818884...b1a5  installer.iso
```

With no `-a`, `cksum` computes a CRC checksum and prints the CRC value, the file's byte count, and the name. With `-a`, it behaves like the corresponding dedicated command.

## Choosing the algorithm

| Option | Effect |
|---|---|
| `-a`, `--algorithm=NAME` | Use the named algorithm. |

`NAME` may be:

| Name | Algorithm |
|---|---|
| `crc` | The default CRC. |
| `crc32b` | A CRC-32 variant. |
| `md5` | MD5 — as `md5sum`. |
| `sha1` | SHA-1 — as `sha1sum`. |
| `sha224`, `sha256`, `sha384`, `sha512` | The SHA-2 family — as the matching `sha*sum`. |
| `sha3` | SHA-3. |
| `blake2b` | BLAKE2b — as `b2sum`. |
| `sm3` | The SM3 hash. |
| `sysv`, `bsd` | The legacy block checksums — as [`sum`](/peios/using-peios/peiosutils/hashing-and-encoding/sum.md). |

`crc`, `crc32b`, `sha3`, and `sm3` are available *only* through `cksum` — there is no dedicated command for them.

## Verifying

`cksum` checks files the same way the dedicated commands do:

| Option | Effect |
|---|---|
| `-c`, `--check` | Read checksums and verify the files against them. |
| `--ignore-missing` | Do not fail over listed files that are absent. |
| `--quiet` | Print nothing for files that pass. |
| `--status` | Print nothing; report only through the exit status. |
| `-w`, `--warn` | Warn about malformed checksum lines. |
| `--strict` | Fail on a malformed checksum line. |

## Output format

| Option | Effect |
|---|---|
| `--tag` | Produce a tagged `ALGORITHM (file) = hash` line. The default for most algorithms. |
| `--untagged` | Produce a plain `hash  file` line. |
| `--raw` | Output the raw binary digest, with nothing else. |
| `--base64` | Print the digest in base64 rather than hexadecimal. |
| `-l`, `--length=BITS` | For an algorithm that supports it, produce a shorter digest. |
| `-z`, `--zero` | End each output line with a NUL character. |

## Exit status

| Code | Meaning |
|---|---|
| `0` | Success — or, in check mode, every file verified. |
| `1` | In check mode, a file failed verification. |
| `2` | An error — a file could not be read, or an option was invalid. |

---

# sum

_Peios / Using Peios / Peiosutils / Hashing and encoding_

> Compute a small, legacy block checksum of a file.

`sum` computes a small, old-style checksum of a file and reports it along with the file's size in blocks.

```
sum [options] [file...]
```

```
$ sum archive.tar
12345 84 archive.tar
```

The output is the checksum, the block count, and the file name. With no file, `sum` reads standard input.

## Which algorithm

`sum` predates the modern hashes and offers two historical algorithms:

| Option | Algorithm |
|---|---|
| `-r` | The BSD checksum, counted in 1 KiB blocks. This is the default. |
| `-s`, `--sysv` | The System V checksum, counted in 512-byte blocks. |

## When to use it

`sum` exists for compatibility — for reading checksums produced by old tools, and for scripts that still expect its output. Its checksum is short and weak: it catches some accidental corruption, but it is easily fooled and gives no protection against tampering.

For anything new, do not use `sum`. Use a [checksum command](/peios/using-peios/peiosutils/hashing-and-encoding/checksum-commands.md) such as `sha256sum`, or [`cksum`](/peios/using-peios/peiosutils/hashing-and-encoding/cksum.md) — both of which `cksum` can still produce, via `cksum -a bsd` and `cksum -a sysv`, if you need the legacy values.

## Exit status

| Code | Meaning |
|---|---|
| `0` | The checksum was computed. |
| `1` | A file could not be read. |

---

# base32 and base64

_Peios / Using Peios / Peiosutils / Hashing and encoding_

> Encode binary data as text using the base32 or base64 alphabet, and decode it back.

`base32` and `base64` encode binary data as plain text — and decode it back. They are the same command with one difference: the **alphabet** they use.

```
base32 [options] [file]
base64 [options] [file]
```

```
$ echo Peios | base64
UGVpb3MK
$ echo UGVpb3MK | base64 -d
Peios
```

## What encoding is for

Some channels only carry text safely — they mangle or reject arbitrary bytes. Encoding rewrites binary data using a small, safe set of characters, so it can pass through unharmed; decoding reverses it exactly. `base64` uses 64 characters and is the more compact; `base32` uses 32 and is more robust where case might not survive. With no file, both read standard input.

Encoding is **not** encryption — anyone can decode the result. See the [overview](/peios/using-peios/peiosutils/hashing-and-encoding/overview.md).

## Options

By default these commands *encode*. The options below apply identically to both.

| Option | Effect |
|---|---|
| `-d`, `--decode` | Decode instead of encode. |
| `-i`, `--ignore-garbage` | When decoding, skip any characters that are not part of the alphabet, rather than failing on them. |
| `-w`, `--wrap=COLS` | When encoding, wrap the output to lines of `COLS` characters. The default is 76; `-w 0` disables wrapping and produces one unbroken line. |

When decoding, newlines in the input are always tolerated; `-i` is for *other* stray characters.

## Exit status

| Code | Meaning |
|---|---|
| `0` | Success. |
| `1` | A file could not be read, or — when decoding — the input was not valid for the alphabet. |

---

# basenc

_Peios / Using Peios / Peiosutils / Hashing and encoding_

> The general encoder — encode and decode data in base64, base32, base16, and several other encodings.

`basenc` is the **general** encoding command. Where [`base32` and `base64`](/peios/using-peios/peiosutils/hashing-and-encoding/base32-and-base64.md) each do one encoding, `basenc` does many — the encoding is chosen by an option.

```
basenc encoding [options] [file]
```

```
$ echo Peios | basenc --base16
5065696F730A
```

Every run of `basenc` must name an encoding. With no file, it reads standard input.

## The encodings

| Option | Encoding |
|---|---|
| `--base64` | Standard base64 — the same as the `base64` command. |
| `--base64url` | Base64 with a file- and URL-safe alphabet. |
| `--base32` | Standard base32 — the same as the `base32` command. |
| `--base32hex` | Base32 with the extended-hex alphabet. |
| `--base16` | Hexadecimal. |
| `--base2msbf` | A bit string, most-significant bit first. |
| `--base2lsbf` | A bit string, least-significant bit first. |
| `--z85` | A compact, ASCII85-style encoding. When encoding, the input length must be a multiple of 4; when decoding, a multiple of 5. |
| `--base58` | Base58 — an alphabet chosen so its characters are not visually confusable. |

## Options

By default `basenc` *encodes*. These options apply to whichever encoding you chose:

| Option | Effect |
|---|---|
| `-d`, `--decode` | Decode instead of encode. |
| `-i`, `--ignore-garbage` | When decoding, skip characters that are not part of the alphabet. |
| `-w`, `--wrap=COLS` | When encoding, wrap output to lines of `COLS` characters. `-w 0` disables wrapping. |

## `basenc` and the dedicated commands

For plain base64 or base32, `base64` and `base32` are the shorter way to ask. Use `basenc` when you need an encoding the dedicated commands do not offer — hex, URL-safe base64, the bit-string forms, z85, or base58.

## Exit status

| Code | Meaning |
|---|---|
| `0` | Success. |
| `1` | No encoding was named, a file could not be read, or the input was not valid for the chosen encoding. |