SHA1(3) Library Functions Manual SHA1(3)

# [NAME](#NAME)

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

# [LIBRARY](#LIBRARY)

Message Digest (MD4, MD5, etc.) Support Library (libmd, -lmd)

# [SYNOPSIS](#SYNOPSIS)

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

`void`  
`SHA1Init`(`SHA1_CTX *context`);

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

`void`  
`SHA1Pad`(`SHA1_CTX *context`);

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

`void`  
`SHA1Transform`(`uint32_t state[5]`, `const uint8_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 uint8_t *data`, `size_t len`, `char *buf`);

# [DESCRIPTION](#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.

While the SHA1 functions are considered to be more secure than the [md4(3)](/man/os/libmd/md4.3) and [md5(3)](/man/os/libmd/md5.3) functions with which they share a similar interface, they are considered insecure as of 2005, and as of 2020 chosen-prefix attacks have become practical, thus these must not be used in cryptographic contexts.

The [`SHA1Init`](#SHA1Init)() function initializes a SHA1\_CTX `context` for use with [`SHA1Update`](#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`](#SHA1Pad)() function can be used to apply padding to the message digest as in [`SHA1Final`](#SHA1Final)(), but the current context can still be used with `SHA1Update`().

The [`SHA1Transform`](#SHA1Transform)() function is used by [`SHA1Update`](#SHA1Update~2)() 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`](#SHA1End)() function is a front end for [`SHA1Final`](#SHA1Final~2)() which converts the digest into an ASCII representation of the 160 bit digest in hexadecimal.

The [`SHA1File`](#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`](#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`](#SHA1Data)() function calculates the digest of an arbitrary string and returns the result via `SHA1End`().

For each of the [`SHA1End`](#SHA1End~2)(), `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)](/man/os/libmd/malloc.3) and should be freed using [free(3)](/man/os/libmd/free.3) when it is no longer needed.

# [EXAMPLES](#EXAMPLES)

The follow code fragment will calculate the digest for the string "abc" which is \`\`0xa9993e364706816aba3e25717850c26c9cd0d89d''.

```
SHA1_CTX sha;
uint8_t results[SHA1_DIGEST_LENGTH];
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 < SHA1_DIGEST_LENGTH; n++)
	printf("%02x", results[n]);
putchar('\n');
```

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

```
uint8_t output[SHA1_DIGEST_STRING_LENGTH];
char *buf = "abc";

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

# [SEE ALSO](#SEE_ALSO)

[cksum(1)](/man/os/libmd/cksum.1), [sha1(1)](/man/os/libmd/sha1.1), [md4(3)](/man/os/libmd/md4.3), [md5(3)](/man/os/libmd/md5.3), [rmd160(3)](/man/os/libmd/rmd160.3), [sha2(3)](/man/os/libmd/sha2.3)

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

D. Eastlake and P. Jones, US Secure Hash Algorithm 1, RFC 3174.

# [HISTORY](#HISTORY)

The SHA-1 functions appeared in OpenBSD 2.0.

# [AUTHORS](#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.

# [CAVEATS](#CAVEATS)

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.

February 13, 2008 Linux 4.19.0-gvisor

---

Document: SHA1Init(3) from libmd 1.3.0-r2 (Chainguard OS)
Source: https://gitlab.freedesktop.org/libbsd/libmd.git