May 20, 2009 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

```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 representation of a message called a message digest, suitable for use as a digital signature. There are four families of functions, with names corresponding 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 hexadecimal.

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 negative ```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 allocated 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('\n');

  `

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\n", SHA256_Data(buf, strlen(buf), output));

  `

### SEE ALSO

cksum(1), md4(3), md5(3), rmd160(3), sha1(3)

### HISTORY

The SHA2 functions appeared in OpenBSD3.4 and NetBSD3.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 swapping on little endian machines such as the i386, alpha, and vax.