SHA1(3)

SHA1(3) | Library Functions Manual | SHA1(3)

# NAME

`SHA1Init`, `SHA1Update`, `SHA1Final`, `SHA1Transform`, `SHA1End`, `SHA1File`, `SHA1FileChunk`, `SHA1Data` —
calculate the NIST Secure Hash Algorithm

# SYNOPSIS

`#include <sys/types.h>`
`#include <sha1.h>`

void
`SHA1Init`(SHA1_CTX *context);

void
`SHA1Update`(SHA1_CTX *context, const uint8_t *data, u_int len);

void
`SHA1Final`(uint8_t digest[20], SHA1_CTX *context);

void
`SHA1Transform`(uint32_t state[5], uint8_t buffer[64]);

char *
`SHA1End`(SHA1_CTX *context, char *buf);

char *
`SHA1File`(char *filename, char *buf);

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

char *
`SHA1Data`(uint8_t *data, size_t len, char *buf);

# DESCRIPTION

The SHA1 functions implement the NIST Secure Hash Algorithm (SHA-1), FIPS PUB 180-1. SHA-1 is used to generate a condensed representation of a message called a message digest. The algorithm takes a message less than 2^64 bits as input and produces a 160-bit digest suitable for use as a digital signature.

The SHA1 functions are considered to be more secure than the md4(3) and md5(3) functions with which they share a similar interface.

The `SHA1Init`() function initializes a SHA1_CTX context for use with `SHA1Update`(), and `SHA1Final`(). The `SHA1Update`() function adds data of length len to the SHA1_CTX specified by context. `SHA1Final`() is called when all data has been added via `SHA1Update`() and stores a message digest in the digest parameter. When a null pointer is passed to `SHA1Final`() as first argument only the final padding will be applied and the current context can still be used with `SHA1Update`().

The `SHA1Transform`() function is used by `SHA1Update`() to hash 512-bit blocks and forms the core of the algorithm. Most programs should use the interface provided by `SHA1Init`(), `SHA1Update`() and `SHA1Final`() instead of calling `SHA1Transform`() directly.

The `SHA1End`() function is a front end for `SHA1Final`() which converts the digest into an ASCII representation of the 160 bit digest in hexadecimal.

The `SHA1File`() function calculates the digest for a file and returns the result via `SHA1End`(). If `SHA1File`() is unable to open the file a NULL pointer is returned.

`SHA1FileChunk`() behaves like `SHA1File`() 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 `SHA1Data`() function calculates the digest of an arbitrary string and returns the result via `SHA1End`().

For each of the `SHA1End`(), `SHA1File`(), and `SHA1Data`() functions the buf parameter should either be a string of at least 41 characters in size 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 follow code fragment will calculate the digest for the string "abc" which is ``0xa9993e36476816aba3e25717850c26c9cd0d89d''.

    SHA1_CTX sha;
    uint8_t results[20];
    char *buf;
    int n;

    buf = "abc";
    n = strlen(buf);
    SHA1Init(&sha);
    SHA1Update(&sha, (uint8_t *)buf, n);
    SHA1Final(results, &sha);

    /* Print the digest as one long hex value */
    printf("0x");
    for (n = 0; n < 20; n++)
    	printf("%02x", results[n]);
    putchar('\n');

Alternately, the helper functions could be used in the following way:

    SHA1_CTX sha;
    uint8_t output[41];
    char *buf = "abc";

    printf("0x%s", SHA1Data(buf, strlen(buf), output));

# SEE ALSO

md5(1), md4(3), md5(3)

J. Burrows, The Secure Hash Standard, FIPS PUB 180-1.

# HISTORY

The SHA-1 functions appeared in NetBSD 1.4.

# AUTHORS

This implementation of SHA-1 was written by Steve Reid.

The `SHA1End`(), `SHA1File`(), `SHA1FileChunk`(), and `SHA1Data`() helper functions are derived from code written by Poul-Henning Kamp.

# BUGS

This implementation of SHA-1 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 (ie: 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.

November 27, 2018 | NetBSD 9.0