# perldoc > Digest::SHA

---
type: CommandReference
command: Digest::SHA
mode: perldoc
section: 3
source: perldoc
---

## Quick Reference

- `sha256_hex("hello world")` — compute SHA-256 hex digest
- `$sha->new(256)->add("data")->hexdigest` — OOP style
- `$sha->addfile("file")` — digest a file
- `$sha->add_bits("110")` — digest partial bits
- `hmac_sha256_hex($data, $key)` — keyed hash (HMAC)
- `shasum file` — command-line digest tool
- `getstate` / `putstate` — save/restore digest state
- `$sha->clone->digest` — preserve state after digest

## Name

Digest::SHA — Perl extension for SHA-1/224/256/384/512

## Synopsis

**Functional style:**

perl
use Digest::SHA qw(sha1 sha1_hex sha1_base64 sha256 sha384_hex sha512_base64);
$digest = sha1($data);
$digest = sha1_hex($data);
$digest = sha1_base64($data);
**Object-oriented style:**

perl
use Digest::SHA;
$sha = Digest::SHA->new($alg);   # $alg: 1,224,256,384,512,512224,512256
$sha->add($data);                 # feed data
$sha->addfile(*F or $filename);
$sha->add_bits($bits);            # partial-byte data
$state = $sha->getstate;          # save state
$sha->putstate($state);           # restore state
$digest = $sha->digest;           # binary
$digest = $sha->hexdigest;        # hex
$digest = $sha->b64digest;        # base64 (no padding)
**HMAC-SHA (functional only):**

perl
use Digest::SHA qw(hmac_sha1 hmac_sha1_hex hmac_sha256_base64);
$digest = hmac_sha1($data, $key);
$digest = hmac_sha224_hex($data, $key);
$digest = hmac_sha256_base64($data, $key);
**Command line:**

`shasum files`

## Functions and Methods

### Functional (all-at-once)

- `sha1($data, ...)`, `sha224(...)`, `sha256(...)`, `sha384(...)`, `sha512(...)`, `sha512224(...)`, `sha512256(...)` — return binary digest.
- `sha1_hex(...)`, `sha224_hex(...)`, `sha256_hex(...)`, `sha384_hex(...)`, `sha512_hex(...)`, `sha512224_hex(...)`, `sha512256_hex(...)` — return hex-encoded digest.
- `sha1_base64(...)`, `sha224_base64(...)`, `sha256_base64(...)`, `sha384_base64(...)`, `sha512_base64(...)`, `sha512224_base64(...)`, `sha512256_base64(...)` — return base64-encoded digest (no padding).

### OOP Methods

- `new($alg)` — create new object; `$alg` defaults to 1 (SHA-1); also accepts strings like "sha256". Calling as instance method resets the object to the given algorithm (or keeps same algorithm if omitted).
- `reset($alg)` — alias for `new`.
- `hashsize` — returns number of digest bits (160, 224, 256, 384, 512, 224, 256).
- `algorithm` — returns numeric algorithm identifier (1, 224, 256, 384, 512, 512224, 512256).
- `clone` — duplicate digest object.
- `add($data, ...)` — append data to current state; returns self.
- `add_bits($data, $nbits)` — append most-significant `$nbits` of `$data` (packed binary string). Alternatively, `$sha->add_bits("0101")` — ASCII bit string.
- `addfile($filehandle)` — read from filehandle until EOF; returns self.
- `addfile($filename, $mode)` — read file; `$mode` can be `"b"` (binary), `"U"` (universal newlines), `"0"` (BITS mode: treat content as ASCII '0'/'1' bits).
- `getstate` — return portable string representation of current SHA state.
- `putstate($str)` — restore state from string; returns self. As class method, returns new object.
- `dump($filename)` — write state to file (default STDOUT).
- `load($filename)` — return new object from state file (default STDIN).
- `digest`, `hexdigest`, `b64digest` — compute final digest (read-once; resets object). Use `clone->digest` to preserve state.

### HMAC-SHA (functional only)

- `hmac_sha1($data, $key)`, `hmac_sha224(...)`, `hmac_sha256(...)`, `hmac_sha384(...)`, `hmac_sha512(...)`, `hmac_sha512224(...)`, `hmac_sha512256(...)` — binary HMAC digest.
- `hmac_sha1_hex(...)`, `hmac_sha224_hex(...)`, `hmac_sha256_hex(...)`, `hmac_sha384_hex(...)`, `hmac_sha512_hex(...)`, `hmac_sha512224_hex(...)`, `hmac_sha512256_hex(...)` — hex-encoded HMAC.
- `hmac_sha1_base64(...)`, `hmac_sha224_base64(...)`, `hmac_sha256_base64(...)`, `hmac_sha384_base64(...)`, `hmac_sha512_base64(...)`, `hmac_sha512224_base64(...)`, `hmac_sha512256_base64(...)` — base64-encoded HMAC (no padding).

## Examples

**All-at-once vs. in-stages (SHA-256):**

perl
use Digest::SHA qw(sha256_hex);
$data = "hello world";
$digest1 = sha256_hex($data);
$state = Digest::SHA->new(256);
$state->add("hello")->add(" ")->add("world");
$digest2 = $state->hexdigest;
print $digest1 eq $digest2 ? "whew!\n" : "oops!\n";
**Partial-byte data (446-bit message, SHA-1):**

perl
use Digest::SHA;
$bits = "110" x 148 . "11";
$sha = Digest::SHA->new(1)->add_bits($bits);
print $sha->hexdigest, "\n";
**HMAC test vector (SHA-256):**

perl
use Digest::SHA qw(hmac_sha256_hex);
print hmac_sha256_hex("Hi There", chr(0x0b) x 32), "\n";
## Unicode and Side Effects

Unicode strings with characters >255 (wide characters) cause the module to croak. Strings with only byte-range characters (0-255) are handled as sequences of byte values. The `add` method silently downgrades UTF-8 input to the native encoding (cf. `utf8::downgrade`).

## Padding of Base64 Digests

CPAN Digest modules do not pad Base64 output. To obtain properly padded encodings, append `"="` characters until the length is a multiple of 4:

perl
while (length($b64_digest) % 4) { $b64_digest .= '='; }
## NIST Statement on SHA-1

NIST acknowledges a practical collision attack on SHA-1 and encourages rapid adoption of SHA-2 (e.g., SHA-256) for strong collision resistance.

## See Also

- [Digest](https://metacpan.org/pod/Digest)
- [Digest::SHA::PurePerl](https://metacpan.org/pod/Digest::SHA::PurePerl)
- [Secure Hash Standard (FIPS 180-4)](http://csrc.nist.gov/publications/drafts/fips180-4/Draft-FIPS180-4_Feb2011.pdf)
- [Keyed-Hash Message Authentication Code (HMAC; FIPS 198)](http://csrc.nist.gov/publications/fips/fips198/fips-198a.pdf)