1.\" $NetBSD: sha1.3,v 1.6 2010/04/05 21:27:01 joerg Exp $ 2.\" $OpenBSD: sha1.3,v 1.9 1998/03/07 22:18:12 millert Exp $ 3.\" 4.\" Copyright (c) 1997, 2004 Todd C. Miller <Todd.Miller@courtesan.com> 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17.\" 18.\" See http://csrc.nist.gov/fips/fip180-1.txt for the detailed standard 19.\" 20.Dd July 10, 1997 21.Dt SHA1 3 22.Os 23.Sh NAME 24.Nm SHA1Init , 25.Nm SHA1Update , 26.Nm SHA1Final , 27.Nm SHA1Transform , 28.Nm SHA1End , 29.Nm SHA1File , 30.Nm SHA1Data 31.Nd calculate the NIST Secure Hash Algorithm 32.Sh SYNOPSIS 33.In sys/types.h 34.In sha1.h 35.Ft void 36.Fn SHA1Init "SHA1_CTX *context" 37.Ft void 38.Fn SHA1Update "SHA1_CTX *context" "const uint8_t *data" "u_int len" 39.Ft void 40.Fn SHA1Final "uint8_t digest[20]" "SHA1_CTX *context" 41.Ft void 42.Fn SHA1Transform "uint32_t state[5]" "uint8_t buffer[64]" 43.Ft "char *" 44.Fn SHA1End "SHA1_CTX *context" "char *buf" 45.Ft "char *" 46.Fn SHA1File "char *filename" "char *buf" 47.Ft "char *" 48.Fn SHA1Data "uint8_t *data" "size_t len" "char *buf" 49.Sh DESCRIPTION 50The SHA1 functions implement the NIST Secure Hash Algorithm (SHA-1), 51FIPS PUB 180-1. 52SHA-1 is used to generate a condensed representation 53of a message called a message digest. 54The algorithm takes a 55message less than 2^64 bits as input and produces a 160-bit digest 56suitable for use as a digital signature. 57.Pp 58The SHA1 functions are considered to be more secure than the 59.Xr md4 3 60and 61.Xr md5 3 62functions with which they share a similar interface. 63.Pp 64The 65.Fn SHA1Init 66function initializes a SHA1_CTX 67.Ar context 68for use with 69.Fn SHA1Update , 70and 71.Fn SHA1Final . 72The 73.Fn SHA1Update 74function adds 75.Ar data 76of length 77.Ar len 78to the SHA1_CTX specified by 79.Ar context . 80.Fn SHA1Final 81is called when all data has been added via 82.Fn SHA1Update 83and stores a message digest in the 84.Ar digest 85parameter. 86When a null pointer is passed to 87.Fn SHA1Final 88as first argument only the final padding will be applied and the 89current context can still be used with 90.Fn SHA1Update . 91.Pp 92The 93.Fn SHA1Transform 94function is used by 95.Fn SHA1Update 96to hash 512-bit blocks and forms the core of the algorithm. 97Most programs should use the interface provided by 98.Fn SHA1Init , 99.Fn SHA1Update 100and 101.Fn SHA1Final 102instead of calling 103.Fn SHA1Transform 104directly. 105.Pp 106The 107.Fn SHA1End 108function is a front end for 109.Fn SHA1Final 110which converts the digest into an 111.Tn ASCII 112representation of the 160 bit digest in hexadecimal. 113.Pp 114The 115.Fn SHA1File 116function calculates the digest for a file and returns the result via 117.Fn SHA1End . 118If 119.Fn SHA1File 120is unable to open the file a NULL pointer is returned. 121.Pp 122The 123.Fn SHA1Data 124function 125calculates the digest of an arbitrary string and returns the result via 126.Fn SHA1End . 127.Pp 128For each of the 129.Fn SHA1End , 130.Fn SHA1File , 131and 132.Fn SHA1Data 133functions the 134.Ar buf 135parameter should either be a string of at least 41 characters in 136size or a NULL pointer. 137In the latter case, space will be dynamically 138allocated via 139.Xr malloc 3 140and should be freed using 141.Xr free 3 142when it is no longer needed. 143.Sh EXAMPLES 144The follow code fragment will calculate the digest for 145the string "abc" which is ``0xa9993e36476816aba3e25717850c26c9cd0d89d''. 146.Bd -literal -offset indent 147SHA1_CTX sha; 148uint8_t results[20]; 149char *buf; 150int n; 151 152buf = "abc"; 153n = strlen(buf); 154SHA1Init(\*[Am]sha); 155SHA1Update(\*[Am]sha, (uint8_t *)buf, n); 156SHA1Final(results, \*[Am]sha); 157 158/* Print the digest as one long hex value */ 159printf("0x"); 160for (n = 0; n \*[Lt] 20; n++) 161 printf("%02x", results[n]); 162putchar('\en'); 163.Ed 164.Pp 165Alternately, the helper functions could be used in the following way: 166.Bd -literal -offset indent 167SHA1_CTX sha; 168uint8_t output[41]; 169char *buf = "abc"; 170 171printf("0x%s", SHA1Data(buf, strlen(buf), output)); 172.Ed 173.Sh SEE ALSO 174.\" .Xr sha1 1 , 175.Xr md5 1 , 176.Xr md4 3 , 177.Xr md5 3 178.Pp 179.Rs 180.%A J. Burrows 181.%T The Secure Hash Standard 182.%O FIPS PUB 180-1 183.Re 184.Sh HISTORY 185The SHA-1 functions appeared in 186.Nx 1.4 . 187.Sh AUTHORS 188This implementation of SHA-1 was written by Steve Reid. 189.Pp 190The 191.Fn SHA1End , 192.Fn SHA1File , 193and 194.Fn SHA1Data 195helper functions are derived from code written by Poul-Henning Kamp. 196.Sh BUGS 197This implementation of SHA-1 has not been validated by NIST 198and as such is not in official compliance with the standard. 199.Pp 200If a message digest is to be copied to a multi-byte type (ie: 201an array of five 32-bit integers) it will be necessary to 202perform byte swapping on little endian machines such as the i386, alpha, 203and VAX. 204