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.

This is Digest::SHA 6.04; Digest/SHA.pm is upstream’s.

Synopsis#

use Digest::SHA qw(sha256_hex sha1_base64 hmac_sha256_hex);

print sha256_hex('abc'), "\n";                  # ba7816bf8f01...f20015ad
print sha1_base64('abc'), "\n";                 # qZk+NkcGgWq6PiVxeFDCbJzQ2J0
print hmac_sha256_hex('data', 'key'), "\n";     # 5031fe3d989c...ce221bd0

my $sha = Digest::SHA->new(256);
$sha->add('a', 'b');
$sha->add('c');
print $sha->hexdigest, "\n";                    # the same as sha256_hex('abc')

open my $fh, '<', $file or die;
print Digest::SHA->new(512)->addfile($fh)->b64digest, "\n";

The functional digests#

One function per algorithm and encoding, each taking any number of strings, hashed as their concatenation:

algorithm

raw bytes

hex

base64 (unpadded)

SHA-1

sha1

sha1_hex

sha1_base64

SHA-224

sha224

sha224_hex

sha224_base64

SHA-256

sha256

sha256_hex

sha256_base64

SHA-384

sha384

sha384_hex

sha384_base64

SHA-512

sha512

sha512_hex

sha512_base64

SHA-512/224

sha512224

sha512224_hex

sha512224_base64

SHA-512/256

sha512256

sha512256_hex

sha512256_base64

hmac_ before each name (hmac_sha256_hex($data, $key)) gives the keyed HMAC; the key is the last argument. Strings must be bytes: a character above 0xFF dies “Wide character”.

Differences from upstream#

Two, each where perl 5.44 with SHA.xs fails (t/81-xs-native/Digest-SHA/495-or-better.t):

  • The low-level entry points Digest/SHA.pm builds on (shainit, shawrite, sharewind), given an object that is not a Digest::SHA, refuse it: shainit and shawrite return 0. perl5 crashes.

  • shawrite($bits, $count, $sha) with a count past the end of $bits writes the bits the string has and returns their number; perl5 reads past the end of the string. (add_bits, the documented way in, never passes such a count.)

Functions#

Functional digests#

sha1#

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

Also available as Digest::SHA::sha1_base64, Digest::SHA::sha1_hex, Digest::SHA::sha224, Digest::SHA::sha224_base64, Digest::SHA::sha224_hex, Digest::SHA::sha256, Digest::SHA::sha256_base64, Digest::SHA::sha256_hex, Digest::SHA::sha384, Digest::SHA::sha384_base64, Digest::SHA::sha384_hex, Digest::SHA::sha512, Digest::SHA::sha512224, Digest::SHA::sha512224_base64, Digest::SHA::sha512224_hex, Digest::SHA::sha512256, Digest::SHA::sha512256_base64, Digest::SHA::sha512256_hex, Digest::SHA::sha512_base64, Digest::SHA::sha512_hex.

OO lifecycle#

shainit#

(Re)initialise a Digest::SHA object for an algorithm; the low-level entry point behind $sha->new($alg) on an existing object.

sharewind#

Rewind a Digest::SHA object to the empty message of its algorithm; the low-level entry point behind $sha->reset.

newSHA#

Construct a Digest::SHA object of class $classname for an algorithm number: 1, 224, 256, 384, 512, 512224 or 512256. Any other number returns undef.

clone#

Copy a Digest::SHA object, current state included, into a new object of the same class.

Synopsis

my $partial = $sha->clone;
print $partial->hexdigest;   # digest so far; $sha keeps going

new#

Construct or reinitialise a Digest::SHA object.

reset#

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

OO input#

shawrite#

Feed the first $bitcnt bits of $bitstr into a Digest::SHA object; the low-level entry point behind add_bits.

add#

Append data to the message being hashed.

add_bits#

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

addfile#

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

OO output#

digest#

Finish the message and return its digest as raw bytes, then rewind the object to the empty message.

hexdigest#

Finish the message and return its digest as lowercase hex, then rewind the object to the empty message.

b64digest#

Finish the message and return its digest as unpadded Base64, then rewind the object to the empty message.

algorithm#

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

hashsize#

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

HMAC#

hmac_sha1#

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

Also available as Digest::SHA::hmac_sha1_base64, Digest::SHA::hmac_sha1_hex, Digest::SHA::hmac_sha224, Digest::SHA::hmac_sha224_base64, Digest::SHA::hmac_sha224_hex, Digest::SHA::hmac_sha256, Digest::SHA::hmac_sha256_base64, Digest::SHA::hmac_sha256_hex, Digest::SHA::hmac_sha384, Digest::SHA::hmac_sha384_base64, Digest::SHA::hmac_sha384_hex, Digest::SHA::hmac_sha512, Digest::SHA::hmac_sha512224, Digest::SHA::hmac_sha512224_base64, Digest::SHA::hmac_sha512224_hex, Digest::SHA::hmac_sha512256, Digest::SHA::hmac_sha512256_base64, Digest::SHA::hmac_sha512256_hex, Digest::SHA::hmac_sha512_base64, Digest::SHA::hmac_sha512_hex.

Other Functions#

getstate#

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

putstate#

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.