Digest::SHA

📦 std

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

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

OO lifecycle

newSHA

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

new

Construct or reinitialise a Digest::SHA object.

clone

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

destroy

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

reset

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

OO input

add

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

add_bits

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

addfilebin

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

addfileuniv

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

addfile

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

OO output

digest

Finalise the running hash and return the raw binary digest.

hexdigest

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

b64digest

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

algorithm

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

hashsize

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

HMAC

hmac_functional

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

State export

getstate

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

putstate

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

getstate_text

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

putstate_text

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

dump

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

load

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