perldoc > Digest

man perldoc info pydoc3 ri search

📛 NAME

Digest - Modules that calculate message digests

🚀 Quick Reference

Use Case	Command	Description
Create MD5 digest object	$md5 = Digest->new("MD5");	🔨 Instantiate a new MD5 digest calculator
Create SHA-256 digest object	$sha256 = Digest->new("SHA-256");	🔨 Instantiate a new SHA-256 digest calculator
Add data to digest	$ctx->add($data);	📥 Append data to the message being hashed
Get binary digest	$digest = $ctx->digest;	🔢 Return the binary digest (compact, not printable)
Get hex digest	$hex = $ctx->hexdigest;	🔢 Return the digest as lowercase hexadecimal string
Get base64 digest (no padding)	$b64 = $ctx->b64digest;	🔢 Return the digest as base64 without trailing padding
HMAC-MD5	$hmac = Digest->HMAC_MD5($key);	🔑 Create an HMAC-MD5 digest using a key
Read file into digest	$ctx->addfile($io_handle);	📄 Read file handle content and append to message

📖 SYNOPSIS

$md5  = Digest->new("MD5");
$sha1 = Digest->new("SHA-1");
$sha256 = Digest->new("SHA-256");
$sha384 = Digest->new("SHA-384");
$sha512 = Digest->new("SHA-512");

$hmac = Digest->HMAC_MD5($key);

📝 DESCRIPTION

The Digest:: modules calculate digests, also called fingerprints or hashes, of some data, called a message. The digest is (usually) some small/fixed size string. The actual size of the digest depends on the algorithm used. The message is simply a sequence of arbitrary bytes or bits.

An important property of the digest algorithms is that the digest is likely to change if the message changes in some way. Another property is that digest functions are one-way functions, that is it should be hard to find a message that corresponds to some given digest. Algorithms differ in how likely and how hard, as well as how efficient they are to compute.

Note that the properties of the algorithms change over time, as the algorithms are analyzed and machines grow faster. If your application for instance depends on it being impossible to generate the same digest for a different message it is wise to make it easy to plug in stronger algorithms as the one used grows weaker. Using the interface documented here should make it easy to change algorithms later.

All Digest:: modules provide the same programming interface. A functional interface for simple use, as well as an object oriented interface that can handle messages of arbitrary length and which can read files directly.

The digest can be delivered in three formats:

• binary — This is the most compact form, but it is not well suited for printing or embedding in places that can't handle arbitrary data.
• hex — A twice as long string of lowercase hexadecimal digits.
• base64 — A string of portable printable characters. This is the base64 encoded representation of the digest with any trailing padding removed. The string will be about 30% longer than the binary version. MIME::Base64 tells you more about this encoding.

The functional interface is simply importable functions with the same name as the algorithm. The functions take the message as argument and return the digest. Example:

use Digest::MD5 qw(md5);
$digest = md5($message);

There are also versions of the functions with _hex or _base64 appended to the name, which returns the digest in the indicated form.

🔧 OO INTERFACE

The following methods are available for all Digest:: modules:

• $ctx = Digest->XXX($arg,...) / $ctx = Digest->new(XXX => $arg,...) / $ctx = Digest::XXX->new($arg,...) — Constructor that returns an object encapsulating the digest state. The first two forms automatically load the right module. The second form allows algorithm names with non-perl identifiers (e.g. "SHA-1"). Raises an exception if no implementation is found. When called as an instance method ($ctx->new), it resets the object state.
• $other_ctx = $ctx->clone — Creates a copy of the digest state object.
• $ctx->reset — Alias for $ctx->new, resets the state.
• $ctx->add( $data ) / $ctx->add( $chunk1, $chunk2, ... ) — Appends the string value of arguments to the message. Returns the $ctx object. Multiple arguments are all appended. Most algorithms are byte-based and croak if arguments contain characters above 255.
  Example (all lines have the same effect):
  

  $ctx->add("a"); $ctx->add("b"); $ctx->add("c");
  $ctx->add("a")->add("b")->add("c");
  $ctx->add("a", "b", "c");
  $ctx->add("abc");

• $ctx->addfile( $io_handle ) — Reads the file handle until EOF and appends content to the message. Returns the $ctx object. Croaks on read failure. The object state may be undefined if partial read occurs. It is wise to binmode the handle before passing.
• $ctx->add_bits( $data, $nbits ) / $ctx->add_bits( $bitstring ) — Alternative to add() that allows partial bytes. Two-argument form adds the first $nbits bits from $data (high order bits of last partial byte). One-argument form takes a string of "1" and "0" chars. Returns the $ctx object. Byte-based algorithms croak if bits are not a multiple of 8.
• $ctx->digest — Returns the binary digest. This is a destructive read-once operation; the object is automatically reset after the call. Use $ctx->clone->digest to keep the state.
• $ctx->hexdigest — Same as digest but returns hexadecimal string.
• $ctx->b64digest — Same as digest but returns base64 string without padding.
• $ctx->base64_padded_digest — Same as digest but returns base64 string with padding.

⚡ Digest Speed

This table gives an indication of relative speed of different algorithms. Sorted by throughput based on a benchmark (ActivePerl-5.8.3, Linux P4 2.8 GHz CPU, Apr 2004).

🔢 Algorithm	📏 Size	📦 Implementation	🚀 MB/s
MD4	128	Digest::MD4 v1.3	165.0
MD5	128	Digest::MD5 v2.33	98.8
SHA-256	256	Digest::SHA2 v1.1.0	66.7
SHA-1	160	Digest::SHA v4.3.1	58.9
SHA-1	160	Digest::SHA1 v2.10	48.8
SHA-256	256	Digest::SHA v4.3.1	41.3
Haval-256	256	Digest::Haval256 v1.0.4	39.8
SHA-384	384	Digest::SHA2 v1.1.0	19.6
SHA-512	512	Digest::SHA2 v1.1.0	19.3
SHA-384	384	Digest::SHA v4.3.1	19.2
SHA-512	512	Digest::SHA v4.3.1	19.2
Whirlpool	512	Digest::Whirlpool v1.0.2	13.0
MD2	128	Digest::MD2 v2.03	9.5
Adler-32	32	Digest::Adler32 v0.03	1.3
CRC-16	16	Digest::CRC v0.05	1.1
CRC-32	32	Digest::CRC v0.05	1.1
MD5	128	Digest::Perl::MD5 v1.5	1.0
CRC-CCITT	16	Digest::CRC v0.05	0.8

The last 5 entries are pure Perl implementations, explaining their slower speed.

📚 SEE ALSO

Digest::Adler32, Digest::CRC, Digest::Haval256, Digest::HMAC, Digest::MD2, Digest::MD4, Digest::MD5, Digest::SHA, Digest::SHA1, Digest::SHA2, Digest::Whirlpool

New digest implementations should consider subclassing from Digest::base.

MIME::Base64

http://en.wikipedia.org/wiki/Cryptographic_hash_function

✍️ AUTHOR

Gisle Aas <gisle AT aas.no>

The Digest:: interface is based on the interface originally developed by Neil Winton for his MD5 module.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Copyright 1998-2006 Gisle Aas.
Copyright 1995,1996 Neil Winton.

📛 NAME 🚀 Quick Reference 📖 SYNOPSIS 📝 DESCRIPTION 🔧 OO INTERFACE ⚡ Digest Speed 📚 SEE ALSO ✍️ AUTHOR