SHA1INIT(3) | Library Functions Manual | SHA1INIT(3)

# NAME

`SHA1Init`, `SHA1Update`, `SHA1Pad`, `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 u_int8_t *data, size_t len);

void
`SHA1Pad`(SHA1_CTX *context);

void
`SHA1Final`(u_int8_t digest[SHA1_DIGEST_LENGTH], SHA1_CTX *context);

void
`SHA1Transform`(u_int32_t state[5], const u_int8_t buffer[SHA1_BLOCK_LENGTH]);

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

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

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

char *
`SHA1Data`(const u_int8_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.

SHA-1 has been broken; it should only be used where necessary for backward compatibility. The attack on SHA-1 is in the nature of finding “collisions” — that is, multiple inputs which hash to the same value. It is still unlikely for an attacker to be able to determine the exact original input given a hash value.

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.

The `SHA1Pad`() function can be used to apply padding to the message digest as in `SHA1Final`(), but 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 following code fragment will calculate the digest for the string "abc" which is “0xa9993e364706816aba3e25717850c26c9cd0d89d”.

    SHA1_CTX sha;
    u_int8_t results[SHA1_DIGEST_LENGTH];
    char *buf;
    int n;

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

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

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

    u_int8_t output[SHA1_DIGEST_STRING_LENGTH];
    char *buf = "abc";

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

# SEE ALSO

cksum(1), sha1(1), MD5Init(3), RMD160Init(3), SHA256Init(3)

# STANDARDS

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

D. Eastlake and P. Jones, US Secure Hash Algorithm 1 (SHA1), RFC 3174, September 2001.

# HISTORY

The SHA-1 functions appeared in OpenBSD 2.0.

# 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.

June 13, 2025 | Debian