SHA2(3) BSD Library Functions Manual SHA2(3)
NAME
SHA256_Init, SHA256_Update, SHA256_Pad, SHA256_Final, SHA256_Transform, SHA256_End, SHA256_File, SHA256_FileChunk, SHA256_Data -- calculate
the NIST Secure Hash Standard (version 2)
SYNOPSIS
#include <sys/types.h>
#include <sha2.h>
void
SHA224_Init(SHA224_CTX *context);
void
SHA224_Update(SHA224_CTX *context, const uint8_t *data, size_t len);
void
SHA224_Pad(SHA224_CTX *context);
void
SHA224_Final(uint8_t digest[SHA224_DIGEST_LENGTH], SHA224_CTX *context);
void
SHA224_Transform(uint32_t state[8], const uint8_t buffer[SHA224_BLOCK_LENGTH]);
char *
SHA224_End(SHA224_CTX *context, char *buf);
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(uint8_t *data, size_t len, char *buf);
void
SHA256_Init(SHA256_CTX *context);
void
SHA256_Update(SHA256_CTX *context, const uint8_t *data, size_t len);
void
SHA256_Pad(SHA256_CTX *context);
void
SHA256_Final(uint8_t digest[SHA256_DIGEST_LENGTH], SHA256_CTX *context);
void
SHA256_Transform(uint32_t state[8], const uint8_t buffer[SHA256_BLOCK_LENGTH]);
char *
SHA256_End(SHA256_CTX *context, char *buf);
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(uint8_t *data, size_t len, char *buf);
void
SHA384_Init(SHA384_CTX *context);
void
SHA384_Update(SHA384_CTX *context, const uint8_t *data, size_t len);
void
SHA384_Pad(SHA384_CTX *context);
void
SHA384_Final(uint8_t digest[SHA384_DIGEST_LENGTH], SHA384_CTX *context);
void
SHA384_Transform(uint64_t state[8], const uint8_t buffer[SHA384_BLOCK_LENGTH]);
char *
SHA384_End(SHA384_CTX *context, char *buf);
char *
SHA384_File(char *filename, char *buf);
char *
SHA384_FileChunk(char *filename, char *buf, off_t offset, off_t length);
char *
SHA384_Data(uint8_t *data, size_t len, char *buf);
void
SHA512_Init(SHA512_CTX *context);
void
SHA512_Update(SHA512_CTX *context, const uint8_t *data, size_t len);
void
SHA512_Pad(SHA512_CTX *context);
void
SHA512_Final(uint8_t digest[SHA512_DIGEST_LENGTH], SHA512_CTX *context);
void
SHA512_Transform(uint64_t state[8], const uint8_t buffer[SHA512_BLOCK_LENGTH]);
char *
SHA512_End(SHA512_CTX *context, char *buf);
char *
SHA512_File(char *filename, char *buf);
char *
SHA512_FileChunk(char *filename, char *buf, off_t offset, off_t length);
char *
SHA512_Data(uint8_t *data, size_t len, char *buf);
DESCRIPTION
The SHA2 functions implement the NIST Secure Hash Standard, FIPS PUB 180-2. The SHA2 functions are used to generate a condensed representa-
tion of a message called a message digest, suitable for use as a digital signature. There are four families of functions, with names corre-
sponding to the number of bits in the resulting message digest. The SHA-224 and SHA-256 functions are limited to processing a message of
less than 2^64 bits as input. The SHA-384 and SHA-512 functions can process a message of at most 2^128 - 1 bits as input.
The SHA2 functions are considered to be more secure than the sha1(3) functions with which they share a similar interface. The 224, 256, 384,
and 512-bit versions of SHA2 share the same interface. For brevity, only the 256-bit variants are described below.
The SHA256_Init() function initializes a SHA256_CTX context for use with SHA256_Update(), and SHA256_Final(). The SHA256_Update() function
adds data of length len to the SHA256_CTX specified by context. SHA256_Final() is called when all data has been added via SHA256_Update()
and stores a message digest in the digest parameter.
The SHA256_Pad() function can be used to apply padding to the message digest as in SHA256_Final(), but the current context can still be used
with SHA256_Update().
The SHA256_Transform() function is used by SHA256_Update() to hash 512-bit blocks and forms the core of the algorithm. Most programs should
use the interface provided by SHA256_Init(), SHA256_Update(), and SHA256_Final() instead of calling SHA256_Transform() directly.
The SHA256_End() function is a front end for SHA256_Final() which converts the digest into an ASCII representation of the digest in hexadeci-
mal.
The SHA256_File() function calculates the digest for a file and returns the result via SHA256_End(). If SHA256_File() is unable to open the
file, a NULL pointer is returned.
SHA256_FileChunk() behaves like SHA256_File() but calculates the digest only for that portion of the file starting at offset and continuing
for length bytes or until end of file is reached, whichever comes first. A zero length can be specified to read until end of file. A nega-
tive length or offset will be ignored.
The SHA256_Data() function calculates the digest of an arbitrary string and returns the result via SHA256_End().
For each of the SHA256_End(), SHA256_File(), SHA256_FileChunk(), and SHA256_Data() functions the buf parameter should either be a string
large enough to hold the resulting digest (e.g., SHA224_DIGEST_STRING_LENGTH, SHA256_DIGEST_STRING_LENGTH, SHA384_DIGEST_STRING_LENGTH, or
SHA512_DIGEST_STRING_LENGTH, depending on the function being used) or a NULL pointer. In the latter case, space will be dynamically allo-
cated via malloc(3) and should be freed using free(3) when it is no longer needed.
EXAMPLES
The following code fragment will calculate the SHA-256 digest for the string "abc", which is
``0xba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad''.
SHA256_CTX ctx;
uint8_t results[SHA256_DIGEST_LENGTH];
char *buf;
int n;
buf = "abc";
n = strlen(buf);
SHA256_Init(&ctx);
SHA256_Update(&ctx, (uint8_t *)buf, n);
SHA256_Final(results, &ctx);
/* Print the digest as one long hex value */
printf("0x");
for (n = 0; n < SHA256_DIGEST_LENGTH; n++)
printf("%02x", results[n]);
putchar('
');
Alternately, the helper functions could be used in the following way:
SHA256_CTX ctx;
uint8_t output[SHA256_DIGEST_STRING_LENGTH];
char *buf = "abc";
printf("0x%s
", SHA256_Data(buf, strlen(buf), output));
SEE ALSO
cksum(1), md4(3), md5(3), rmd160(3), sha1(3)
Secure Hash Standard, FIPS PUB 180-2.
HISTORY
The SHA2 functions appeared in OpenBSD 3.4 and NetBSD 3.0.
AUTHORS
This implementation of the SHA functions was written by Aaron D. Gifford.
The SHA256_End(), SHA256_File(), SHA256_FileChunk(), and SHA256_Data() helper functions are derived from code written by Poul-Henning Kamp.
CAVEATS
This implementation of the Secure Hash Standard has not been validated by NIST and as such is not in official compliance with the standard.
If a message digest is to be copied to a multi-byte type (i.e.: an array of five 32-bit integers) it will be necessary to perform byte swap-
ping on little endian machines such as the i386, alpha, and vax.
BSD
May 20, 2009 BSD