<!-- GENERATED by docs/sphinx/bin/02-reference from Digest/SHA.rs. Do not edit. -->

```{index} single: Digest::SHA; Perl module
```

# Digest::SHA

```{pperl-module-badges} Digest::SHA
```

Compute SHA-1 and SHA-2 family message digests: SHA-1, SHA-224, SHA-256,
SHA-384, SHA-512, SHA-512/224, and SHA-512/256, with optional HMAC keying.

Two call styles are available. The **functional interface** (`sha256_hex`,
`hmac_sha512_base64`, and friends) is a one-shot: hand it the data, get
the digest back. The **object interface** (`Digest::SHA->new(256)`,
`->add`, `->digest`) lets you feed data incrementally — from streams,
files, or a mix of sources — and finalize when you are ready.

Every digest can be rendered in three encodings: raw binary (fixed-length
bytes), lowercase hex, or unpadded Base64. Choose the encoding by the
function suffix (`_hex`, `_base64`, or none for raw). HMAC variants use
the same suffixes and live under the `hmac_*` prefix.

File input is supported through `addfile`, which reads a filehandle or
filename and feeds its contents straight into the context. A `bits`
helper (`add_bits`) lets you hash arbitrary-length bit strings, not just
whole bytes. Context state is serialisable with `getstate` / `putstate`
(text) and `_getstate` / `_putstate` (packed binary), so a long-running
hash can be suspended and resumed across processes.

Pick **SHA-256** by default for new work: it is fast on 32-bit and 64-bit
CPUs alike and has the widest interoperability. Prefer **SHA-512** (or
its truncated `SHA-512/256` cousin) on 64-bit hardware when you want
more performance headroom or a larger internal state; SHA-512 often
outperforms SHA-256 there despite the larger output. Avoid **SHA-1** for
anything collision-sensitive — it survives only for legacy
interoperability.

## Functions

### Functional digests

#### [`sha_functional`](SHA/sha_functional)

Compute a SHA digest of the concatenated arguments in one call.

### OO lifecycle

#### [`newSHA`](SHA/newSHA)

Construct a fresh `Digest::SHA` object for the given algorithm number.

#### [`new`](SHA/new)

Construct or reinitialise a `Digest::SHA` object.

#### [`clone`](SHA/clone)

Copy a `Digest::SHA` object, producing an independent duplicate.

#### [`destroy`](SHA/destroy)

Release the native context attached to a `Digest::SHA` object.

#### [`reset`](SHA/reset)

Rewind a `Digest::SHA` object, optionally switching algorithm.

### OO input

#### [`add`](SHA/add)

Feed byte data into a `Digest::SHA` object incrementally.

#### [`add_bits`](SHA/add_bits)

Feed an arbitrary number of bits into a `Digest::SHA` object.

#### [`addfilebin`](SHA/addfilebin)

Feed the raw byte contents of a filehandle into a `Digest::SHA` object.

#### [`addfileuniv`](SHA/addfileuniv)

Feed a filehandle's contents into a `Digest::SHA` object, reading through the PerlIO text layer.

#### [`addfile`](SHA/addfile)

Feed a filehandle or a file by name into a `Digest::SHA` object.

### OO output

#### [`digest`](SHA/digest)

Finalise the running hash and return the raw binary digest.

#### [`hexdigest`](SHA/hexdigest)

Finalise the running hash and return the digest as a lowercase hex string.

#### [`b64digest`](SHA/b64digest)

Finalise the running hash and return the digest as an unpadded Base64 string.

#### [`algorithm`](SHA/algorithm)

Return the algorithm code of a `Digest::SHA` object.

#### [`hashsize`](SHA/hashsize)

Return the digest length of a `Digest::SHA` object in bits.

### HMAC

#### [`hmac_functional`](SHA/hmac_functional)

Compute a keyed HMAC digest of the data arguments in one call.

### State export

#### [`getstate`](SHA/getstate)

Export a `Digest::SHA` object's state as a packed binary string.

#### [`putstate`](SHA/putstate)

Restore a `Digest::SHA` object's state from a packed binary string.

#### [`getstate_text`](SHA/getstate_text)

Export a `Digest::SHA` object's state as a human-readable text string.

#### [`putstate_text`](SHA/putstate_text)

Construct or restore a `Digest::SHA` object from a text state string.

#### [`dump`](SHA/dump)

Write the current `Digest::SHA` state to a file or STDOUT in text form.

#### [`load`](SHA/load)

Construct a `Digest::SHA` object from a text state file written by `dump`.

```{toctree}
:hidden:
:maxdepth: 1

SHA/sha_functional
SHA/hmac_functional
SHA/newSHA
SHA/new
SHA/clone
SHA/destroy
SHA/reset
SHA/add
SHA/add_bits
SHA/addfilebin
SHA/addfileuniv
SHA/addfile
SHA/digest
SHA/hexdigest
SHA/b64digest
SHA/algorithm
SHA/hashsize
SHA/getstate
SHA/putstate
SHA/getstate_text
SHA/putstate_text
SHA/dump
SHA/load
```