SHA256(3)

📦
version 15.1 · 2 versions
, in freebsd 15.1

💫 SHA256(3) — the girlies' guide to SHA-256 (and her lil sister SHA-224) 💫

okay so bestie, welcome to the SHA256(3) manual page, literally the library functions manual for the Message Digest family, and we're about to make hashing make sense. no cap. 🎀

✨ NAME ✨

so basically this whole page is about a whole squad of functions that calculate the FIPS 180-2 ``SHA-256'' (or SHA-224) message digest. and yes, the squad is LONG, let me list them all because every single one is invited to the party:

  • SHA224_Init, SHA224_Update, SHA224_Final, SHA224_End, SHA224_Fd, SHA224_FdChunk, SHA224_File, SHA224_FileChunk, SHA224_Data
  • SHA256_Init, SHA256_Update, SHA256_Final, SHA256_End, SHA256_Fd, SHA256_FdChunk, SHA256_File, SHA256_FileChunk, SHA256_Data

that's them. that's the whole roster. 💅

📚 LIBRARY 📚

this lives in the Message Digest (MD4, MD5, etc.) Support Library, aka libmd, and you link it with -lmd. iconique. 🫶

🌸 SYNOPSIS 🌸

first up, the SHA-224 section — she has her own header:

#include <sys/types.h>
#include <sha224.h>

void
SHA224_Init(SHA224_CTX *context);

void
SHA224_Update(SHA224_CTX *context, const unsigned char *data,
    size_t len);

void
SHA224_Final(unsigned char digest[32], SHA224_CTX *context);

char *
SHA224_End(SHA224_CTX *context, char *buf);

char *
SHA224_Fd(int fd, char *buf);

char *
SHA224_FdChunk(int fd, char *buf, off_t offset, off_t length);

char *
SHA224_File(const char *filename, char *buf);

char *
SHA224_FileChunk(const char *filename, char *buf, off_t offset,
    off_t length);

char *
SHA224_Data(const unsigned char *data, unsigned int len, char *buf);

and now the SHA-256 side, different header, same energy:

#include <sha256.h>

void
SHA256_Init(SHA256_CTX *context);

void
SHA256_Update(SHA256_CTX *context, const unsigned char *data,
    size_t len);

void
SHA256_Final(unsigned char digest[32], SHA256_CTX *context);

char *
SHA256_End(SHA256_CTX *context, char *buf);

char *
SHA256_Fd(int fd, char *buf);

char *
SHA256_FdChunk(int fd, char *buf, off_t offset, off_t length);

char *
SHA256_File(const char *filename, char *buf);

char *
SHA256_FileChunk(const char *filename, char *buf, off_t offset,
    off_t length);

char *
SHA256_Data(const unsigned char *data, unsigned int len, char *buf);

like, look at all those signatures. she's thorough. 👑

💖 DESCRIPTION 💖

so the SHA256_ functions calculate a 256-bit cryptographic checksum (that's a digest, bestie) for any number of input bytes. any. number. ✨

a cryptographic checksum is a one-way hash function — meaning it's computationally impractical to find the input that corresponds to a particular output. you can't reverse it, periodt. the net result is a "fingerprint" of the input-data, which does not disclose the actual input. iykyk. 🔥

the core three 🧚

SHA256_Init(), SHA256_Update(), and SHA256_Final() are the core functions — the main characters, honestly. the whole flow is:

  1. allocate an SHA256_CTX
  2. initialize it with SHA256_Init()
  3. run over the data with SHA256_Update()
  4. finally extract the result using SHA256_Final()

and plot twist: SHA256_Final() also erases the SHA256_CTX. she cleans up after herself. we love a tidy queen. 💅

the convenience girlies 🎀

  • SHA256_End() is a wrapper for SHA256_Final() that converts the return value into a 65-character (including the terminating '\0') ASCII string which represents the 256 bits in hexadecimal.
  • SHA256_File() calculates the digest of a file, and uses SHA256_End() to return the result. if the file cannot be opened, a null pointer is returned. 😭
  • SHA256_FileChunk() is similar to SHA256_File(), but it only calculates the digest over a byte-range of the file specified — starting at offset and spanning length bytes. if the length parameter is specified as 0, or more than the length of the remaining part of the file, SHA256_FileChunk() calculates the digest from offset to the end of file. no wasted effort.
  • SHA256_Data() calculates the digest of a chunk of data in memory, and uses SHA256_End() to return the result.
  • SHA256_Fd() and SHA256_FdChunk() are identical to their SHA256_File() and SHA256_FileChunk() counterparts, with one exception: the first argument is an fd instead of a filename. same vibes, different entry point.

the buf situation — pay attention bestie 🫶

when using SHA256_End(), SHA256_File(), or SHA256_Data(), the buf argument can be a null pointer. in that case, the returned string is allocated with malloc(3) and subsequently must be explicitly deallocated using free(3) after use. don't forget. i'm serious. 🙈

if the buf argument is non-null, it must point to at least 65 characters of buffer space. sixty-five. not 64. not "like, around 65". 65. ⭐

SHA-224 tea ☕

SHA224 is identical to SHA256, except it has slightly different initialization vectors, and is truncated to a shorter digest. she's the shorter sister and she still slays. 💜

💀 ERRORS 💀

the SHA256_End() function called with a null buf argument may fail and return NULL if:

  • [ENOMEM] — Insufficient storage space is available.

and SHA256_File() and SHA256_FileChunk() may return NULL when underlying open(2), fstat(2), lseek(2), or SHA256_End(3) fail. so if something upstream is being messy, that's where your NULL came from. 🫠

🌈 SEE ALSO 🌈

go read these next, bestie, they're all in the family:

🦋 HISTORY 🦋

these functions appeared in FreeBSD 6.0. vintage. iconic. a moment in time. ⭐

👑 AUTHORS 👑

the core hash routines were implemented by Colin Percival based on the published FIPS 180-2 standard. shoutout Colin. 🫶

🍓 BUGS 🍓

real talk: no method is known to exist which finds two files having the same hash value, nor to find a file with a specific hash value.

but — there is on the other hand no guarantee that such a method does not exist. so like... we're fine, but we're not that fine. 😭

and that's the whole page, bestie!! now go hash something and feel iconic doing it 💖

this little masterpiece comes to you from Debian, dated March 8, 2022, and it's the SHA256(3) manual page — mwah, love u, see u in the next man 💅🎀

📦 where this page comes from