SHA1(3)

📦
version 2.13 · 9 versions
, in opensuse-leap 16.0

🦋 SHA1(3) — the Digest::SHA1 era

okay bestie, so this is the SHA1(3) page from the User Contributed Perl Documentation, and it's literally your cheat sheet for talking to SHA-1 from Perl. It's the Digest::SHA1 module, and yes we're gonna go through every single bit of it together. grab a strawberry drink 🍓

✨ NAME ✨

Digest::SHA1 — Perl interface to the SHA-1 algorithm. that's the whole vibe. a Perl door into SHA-1. 🎀

🌸 SYNOPSIS 🌸

two ways to live your life here — functional style or OO style. both iconic, pick your fighter:

 # Functional style
 use Digest::SHA1  qw(sha1 sha1_hex sha1_base64);

 $digest = sha1($data);
 $digest = sha1_hex($data);
 $digest = sha1_base64($data);
 $digest = sha1_transform($data);

 # OO style
 use Digest::SHA1;

 $sha1 = Digest::SHA1->new;

 $sha1->add($data);
 $sha1->addfile(*FILE);

 $sha1_copy = $sha1->clone;

 $digest = $sha1->digest;
 $digest = $sha1->hexdigest;
 $digest = $sha1->b64digest;
 $digest = $sha1->transform;

💜 DESCRIPTION 💜

so the Digest::SHA1 module lets you use the NIST SHA-1 message digest algorithm from inside your Perl programs. the way it works: you feed it a message of arbitrary length, and it hands you back a 160-bit "fingerprint" — aka a "message digest" — of that input. cute, deterministic, iconic. ✨

⚠️ okay important lore: in 2005, security flaws were identified in SHA-1 — namely that a possible mathematical weakness might exist, which suggests a stronger hash function would be desirable. the Digest::SHA module implements the stronger algorithms in the SHA family. so like… SHA-1 is giving legacy, bestie. 😭

the Digest::SHA1 module provides a procedural interface for simple use, plus an object oriented interface that can handle messages of arbitrary length and which can read files directly. both hands on deck 🫶

🔥 FUNCTIONS 🔥

these are the functions you can export from Digest::SHA1. no functions are exported by default — you have to ask for them, respectfully 💅

  • sha1($data,...) — concatenates all the arguments, calculates the SHA-1 digest of that "message", and returns it in binary form. the returned string will be 20 bytes long.

and the result of sha1("a", "b", "c") will be exactly the same as the result of sha1("abc"). no cap, that's the whole point 🎀

  • sha1_hex($data,...) — same as sha1(), but returns the digest in hexadecimal form. the length of the returned string will be 40, and it will only contain characters from this set: '0'..'9' and 'a'..'f'.
  • sha1_base64($data,...) — same as sha1(), but returns the digest as a base64 encoded string. the length of the returned string will be 27, and it will only contain characters from this set: 'A'..'Z', 'a'..'z', '0'..'9', '+' and '/'.
⚠️ note that the base64 encoded string returned is not padded to be a multiple of 4 bytes long. if you want interoperability with other base64 encoded sha1 digests, you might want to append the redundant string "=" to the result. that's it, that's the fix 💀
  • sha1_transform($data) — implements the basic SHA1 transform on a 64 byte block. the $data argument and the returned $digest are in binary form. this algorithm is used in NIST FIPS 186-2. raw and unfiltered, we respect her 🌈

👑 METHODS 👑

this section is the object oriented interface to Digest::SHA1, and honestly it's giving main character energy. after a Digest::SHA1 object has been created, you add data to it and finally ask for the digest in a suitable format. and here's the slay: a single object can be used to calculate multiple digests. reusable queen 👑

the following methods are provided:

  • $sha1 = Digest::SHA1->new — the constructor returns a new Digest::SHA1 object which encapsulates the state of the SHA-1 message-digest algorithm.

and plot twist: if called as an instance method (i.e. $sha1->new) it will just reset the state of the object to the state of a newly created object. no new object is created in this case. literally not a new object. read that again 📖

  • $sha1->reset — this is just an alias for $sha1->new. that's the whole method, she's short and she knows it 💅
  • $sha1->clone — this is a copy of the $sha1 object. it's useful when you do not want to destroy the digest's state, but you need an intermediate value of the digest — e.g. when calculating digests iteratively on a continuous data stream. example:
 my $sha1 = Digest::SHA1->new;
 while (<>) {
     $sha1->add($_);
     print "Line $.: ", $sha1->clone->hexdigest, "\n";
 }
  • $sha1->add($data,...) — the $data provided as arguments are appended to the message we calculate the digest for. the return value is the $sha1 object itself (chaining supremacy 🔗).

all these lines will have the same effect on the state of the $sha1 object:

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

four different fits, same energy. that's range ✨

  • $sha1->addfile($io_handle) — the $io_handle will be read until EOF, and its content appended to the message we calculate the digest for. the return value is the $sha1 object itself.
💀 the addfile() method will croak() if it fails reading data for some reason. and if it croaks, it's unpredictable what the state of the $sha1 object will be in — addfile() might have been able to read the file partially before it failed. it's probably wise to discard or reset the $sha1 object if this occurs. like, just throw the whole object away, bestie, don't try to salvage it 🙈

in most cases you want to make sure that the $io_handle is in "binmode" before you pass it as an argument to the addfile() method. do that, please 🫶

  • $sha1->add_bits($data, $nbits) $sha1->add_bits($bitstring) — this implementation of SHA-1 only supports byte oriented input, so you might only add bits as multiples of 8. if you need bit level support, please consider using the "Digest::SHA" module instead. the add_bits() method is provided here for compatibility with other digest implementations. see Digest for a description of the arguments that add_bits() take. she's here for the compatibility vibes, not the bit-level ones 😌
  • $sha1->digest — returns the binary digest for the message. the returned string will be 20 bytes long.
⚠️ note that the "digest" operation is effectively a destructive, read-once operation. once it has been performed, the "Digest::SHA1" object is automatically "reset" and can be used to calculate another digest value. call $sha1->clone->digest if you want to calculate the digest without resetting the digest state. one-time use, like a limited edition drop 💅
  • $sha1->hexdigest — same as $sha1->digest, but returns the digest in hexadecimal form. the length of the returned string will be 40, and it will only contain characters from this set: '0'..'9' and 'a'..'f'.
  • $sha1->b64digest — same as $sha1->digest, but returns the digest as a base64 encoded string. the length of the returned string will be 27, and it will only contain characters from this set: 'A'..'Z', 'a'..'z', '0'..'9', '+' and '/'.
⚠️ the base64 encoded string returned is not padded to be a multiple of 4 bytes long. if you want interoperability with other base64 encoded SHA-1 digests, you might want to append the string "=" to the result. same deal as sha1_base64, said twice because it matters twice 🎀

🌈 SEE ALSO 🌈

go read these too, bestie, they're in the group chat:

this library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. free as in freedom, we love to see it 🦋

 Copyright 1999-2004 Gisle Aas.
 Copyright 1997 Uwe Hollerbach.

⭐ AUTHORS ⭐

Peter C. Gutmann, Uwe Hollerbach <uh@alumni.caltech.edu>, Gisle Aas <gisle@aas.no>

legends, all three of them 👑✨

and that's the whole page, bestie — no skipped sections, no details dropped, we ate and left zero crumbs 💅 this was perl v5.42.0, dated 2013-04-15, page SHA1(3) — mwah, go hash something 🍓💖

📦 where this page comes from