SHA-256 hashing library -- documentation/notes

SHA-256 hashing library
-----------------------
Code: http://pastebin.com/WAxMm6Vk
Header file: http://pastebin.com/RAWGGp35

Only one function is defined, sha256(), that does the hashing in whichever format is requested. It takes five parameters -- an opcode, two pointers (called "in" and "out"), and two 64-bit values (called "skip" and "length"). The opcode determines how the hash will be carried out -- that is, what type of data will be read for hashing, and how the results will be output. The opcode also defines the meaning of the other four parameters.

The opcode must contain exactly one input specifier and one output specifier, and it may contain any number (zero or more) flags. All values are ORed.

Input specifiers (determine the meanings of in, skip and length):
SHA256_IN_BUFFER: the input is a buffer in memory. The in pointer points to the buffer, and optionally the skip parameter points to an offset in it where to start the hash (0 to start at the beginning of the buffer). The length parameter indicates the length of the buffer. The in pointer must not be NULL, unless length is 0.
SHA256_IN_FILE: the input is an open file. The in pointer is a FILE * (as defined by <stdio.h>) that was already opened by the program. Hashing will begin at the current read pointer in the file if skip is 0; otherwise, the read pointer will be advanced by skip (which may be negative) before hashing. The length parameter indicates how many bytes to hash across -- a value of 0 indicates to hash until EOF.
SHA256_IN_FILENAME: the input is an unopened file. The in pointer is a const char * that is passed to fopen() to open a file for reading. The rest of the operation is the same as in the previous case.
SHA256_IN_BLOCK: the input is an already prepared 512-bit block, and the current state of the hash. This is intended to build another SHA-256 implementation for a special case not considered here, not for direct usage. The in pointer is a pointer to a buffer containing both the current block (64 bytes) and the state of the hash (32 bytes). The skip parameter is an offset in the buffer to the actual block, and the length parameter is treated as an offset in the buffer to the state of the hash (not as a length). If skip equals length, then the block is treated as the first block of the hash -- the state of the hash is ignored and initialized to the required initial values.

Output specifiers (determine the meaning of out):
SHA256_OUT_WORDS: the native format, out points to a uint32_t[8] where the result of the hash will be saved.
SHA256_OUT_BYTES: the words are broken down into bytes, out points to a uint8_t[32]. Words are broken down in big-endian format, as required by the SHA-256 specification.
SHA256_OUT_LONGS: the words are grouped into 64-bit long words instead (big-endian as required), out points to a uint64_t[4].
SHA256_OUT_STRING: the result of the hash is converted into an hexadecimal string. The out pointer must point to a string buffer at least 65 characters long.

Flags:
SHA256_LENGTH_BITS: indicates that the "length" parameter is in bits, not bytes. (Valid for all input modes other than SHA256_IN_BLOCK.)
SHA256_REVERSE_WORDS: indicates that the 32-bit words in the hash should be returned in reverse order.
SHA256_UPPERCASE_HEX: indicates that the hexadecimal characters A-F should be capitalized in the output. (Valid for SHA256_OUT_STRING only.)
SHA256_REVERSE_ENDIAN: indicates the use of little-endian instead of big-endian for SHA256_OUT_BYTES and SHA256_OUT_LONGS.


The function returns 0 on success, or a non-zero error code on failure, as follows:
SHA256_INVALID_OPCODE: the opcode specified was not valid.
SHA256_FILE_NOT_FOUND: the requested file does not exist or could not be opened for reading. (Valid for SHA256_IN_FILENAME only.)
SHA256_INVALID_ARGUMENT: one of the arguments was incorrect (for instance, an out pointer equaled NULL).
SHA256_IO_ERROR: input error while reading the file. (Valid for SHA256_IN_FILE and SHA256_IN_FILENAME.)
SHA256_PREMATURE_EOF: a length was requested for the data, but EOF was encountered before that many bytes were read. (Valid for SHA256_IN_FILE and SHA256_IN_FILENAME.)



Examples:

1. Find the hash of "abc":
uint32_t hash[8];
int status = sha256(SHA256_IN_BUFFER | SHA256_OUT_WORDS, "abc", hash, 0, 3 /* bytes in the buffer */);

2. Get the hash of a file called a.txt as a string:
char hash[65];
int status = sha256(SHA256_IN_FILENAME | SHA256_OUT_STRING, "a.txt", hash, 0, 0);

3. Get that same hash, but for the 128 bytes starting right at the 1KB mark, and with hex characters in capital letters:
char hash[65];
int status = sha256(SHA256_IN_FILENAME | SHA256_OUT_STRING | SHA256_UPPERCASE_HEX, "a.txt", hash, 1024, 128);