1.\" $NetBSD: sha2.3,v 1.5 2009/05/26 08:04:12 joerg Exp $ 2.\" $OpenBSD: sha2.3,v 1.11 2004/06/22 01:57:29 jfb Exp $ 3.\" 4.\" Copyright (c) 2003, 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.\" Sponsored in part by the Defense Advanced Research Projects 19.\" Agency (DARPA) and Air Force Research Laboratory, Air Force 20.\" Materiel Command, USAF, under agreement number F39502-99-1-0512. 21.\" 22.\" See http://www.nist.gov/sha/ for the detailed standard 23.\" 24.Dd May 20, 2009 25.Dt SHA2 3 26.Os 27.Sh NAME 28.Nm SHA256_Init , 29.Nm SHA256_Update , 30.Nm SHA256_Pad , 31.Nm SHA256_Final , 32.Nm SHA256_Transform , 33.Nm SHA256_End , 34.Nm SHA256_File , 35.Nm SHA256_FileChunk , 36.Nm SHA256_Data 37.Nd calculate the NIST Secure Hash Standard (version 2) 38.Sh SYNOPSIS 39.In sys/types.h 40.In sha2.h 41.Ft void 42.Fn SHA224_Init "SHA224_CTX *context" 43.Ft void 44.Fn SHA224_Update "SHA224_CTX *context" "const uint8_t *data" "size_t len" 45.Ft void 46.Fn SHA224_Pad "SHA224_CTX *context" 47.Ft void 48.Fn SHA224_Final "uint8_t digest[SHA224_DIGEST_LENGTH]" "SHA224_CTX *context" 49.Ft void 50.Fn SHA224_Transform "uint32_t state[8]" "const uint8_t buffer[SHA224_BLOCK_LENGTH]" 51.Ft "char *" 52.Fn SHA224_End "SHA224_CTX *context" "char *buf" 53.Ft "char *" 54.Fn SHA224_File "const char *filename" "char *buf" 55.Ft "char *" 56.Fn SHA224_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" 57.Ft "char *" 58.Fn SHA224_Data "uint8_t *data" "size_t len" "char *buf" 59.Ft void 60.Fn SHA256_Init "SHA256_CTX *context" 61.Ft void 62.Fn SHA256_Update "SHA256_CTX *context" "const uint8_t *data" "size_t len" 63.Ft void 64.Fn SHA256_Pad "SHA256_CTX *context" 65.Ft void 66.Fn SHA256_Final "uint8_t digest[SHA256_DIGEST_LENGTH]" "SHA256_CTX *context" 67.Ft void 68.Fn SHA256_Transform "uint32_t state[8]" "const uint8_t buffer[SHA256_BLOCK_LENGTH]" 69.Ft "char *" 70.Fn SHA256_End "SHA256_CTX *context" "char *buf" 71.Ft "char *" 72.Fn SHA256_File "const char *filename" "char *buf" 73.Ft "char *" 74.Fn SHA256_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" 75.Ft "char *" 76.Fn SHA256_Data "uint8_t *data" "size_t len" "char *buf" 77.Ft void 78.Fn SHA384_Init "SHA384_CTX *context" 79.Ft void 80.Fn SHA384_Update "SHA384_CTX *context" "const uint8_t *data" "size_t len" 81.Ft void 82.Fn SHA384_Pad "SHA384_CTX *context" 83.Ft void 84.Fn SHA384_Final "uint8_t digest[SHA384_DIGEST_LENGTH]" "SHA384_CTX *context" 85.Ft void 86.Fn SHA384_Transform "uint64_t state[8]" "const uint8_t buffer[SHA384_BLOCK_LENGTH]" 87.Ft "char *" 88.Fn SHA384_End "SHA384_CTX *context" "char *buf" 89.Ft "char *" 90.Fn SHA384_File "char *filename" "char *buf" 91.Ft "char *" 92.Fn SHA384_FileChunk "char *filename" "char *buf" "off_t offset" "off_t length" 93.Ft "char *" 94.Fn SHA384_Data "uint8_t *data" "size_t len" "char *buf" 95.Ft void 96.Fn SHA512_Init "SHA512_CTX *context" 97.Ft void 98.Fn SHA512_Update "SHA512_CTX *context" "const uint8_t *data" "size_t len" 99.Ft void 100.Fn SHA512_Pad "SHA512_CTX *context" 101.Ft void 102.Fn SHA512_Final "uint8_t digest[SHA512_DIGEST_LENGTH]" "SHA512_CTX *context" 103.Ft void 104.Fn SHA512_Transform "uint64_t state[8]" "const uint8_t buffer[SHA512_BLOCK_LENGTH]" 105.Ft "char *" 106.Fn SHA512_End "SHA512_CTX *context" "char *buf" 107.Ft "char *" 108.Fn SHA512_File "char *filename" "char *buf" 109.Ft "char *" 110.Fn SHA512_FileChunk "char *filename" "char *buf" "off_t offset" "off_t length" 111.Ft "char *" 112.Fn SHA512_Data "uint8_t *data" "size_t len" "char *buf" 113.Sh DESCRIPTION 114The SHA2 functions implement the NIST Secure Hash Standard, 115FIPS PUB 180-2. 116The SHA2 functions are used to generate a condensed representation of a 117message called a message digest, suitable for use as a digital signature. 118There are four families of functions, with names corresponding to 119the number of bits in the resulting message digest. 120The SHA-224 and SHA-256 functions are limited to processing a message of less 121than 2^64 bits as input. 122The SHA-384 and SHA-512 functions can process a message of at most 2^128 - 1 123bits as input. 124.Pp 125The SHA2 functions are considered to be more secure than the 126.Xr sha1 3 127functions with which they share a similar interface. 128The 224, 256, 384, and 512-bit versions of SHA2 share the same interface. 129For brevity, only the 256-bit variants are described below. 130.Pp 131The 132.Fn SHA256_Init 133function initializes a SHA256_CTX 134.Ar context 135for use with 136.Fn SHA256_Update , 137and 138.Fn SHA256_Final . 139The 140.Fn SHA256_Update 141function adds 142.Ar data 143of length 144.Ar len 145to the SHA256_CTX specified by 146.Ar context . 147.Fn SHA256_Final 148is called when all data has been added via 149.Fn SHA256_Update 150and stores a message digest in the 151.Ar digest 152parameter. 153.Pp 154The 155.Fn SHA256_Pad 156function can be used to apply padding to the message digest as in 157.Fn SHA256_Final , 158but the current context can still be used with 159.Fn SHA256_Update . 160.Pp 161The 162.Fn SHA256_Transform 163function is used by 164.Fn SHA256_Update 165to hash 512-bit blocks and forms the core of the algorithm. 166Most programs should use the interface provided by 167.Fn SHA256_Init , 168.Fn SHA256_Update , 169and 170.Fn SHA256_Final 171instead of calling 172.Fn SHA256_Transform 173directly. 174.Pp 175The 176.Fn SHA256_End 177function is a front end for 178.Fn SHA256_Final 179which converts the digest into an 180.Tn ASCII 181representation of the digest in hexadecimal. 182.Pp 183The 184.Fn SHA256_File 185function calculates the digest for a file and returns the result via 186.Fn SHA256_End . 187If 188.Fn SHA256_File 189is unable to open the file, a 190.Dv NULL 191pointer is returned. 192.Pp 193.Fn SHA256_FileChunk 194behaves like 195.Fn SHA256_File 196but calculates the digest only for that portion of the file starting at 197.Fa offset 198and continuing for 199.Fa length 200bytes or until end of file is reached, whichever comes first. 201A zero 202.Fa length 203can be specified to read until end of file. 204A negative 205.Fa length 206or 207.Fa offset 208will be ignored. 209.Pp 210The 211.Fn SHA256_Data 212function 213calculates the digest of an arbitrary string and returns the result via 214.Fn SHA256_End . 215.Pp 216For each of the 217.Fn SHA256_End , 218.Fn SHA256_File , 219.Fn SHA256_FileChunk , 220and 221.Fn SHA256_Data 222functions the 223.Ar buf 224parameter should either be a string large enough to hold the resulting digest 225(e.g., 226.Ev SHA224_DIGEST_STRING_LENGTH , 227.Ev SHA256_DIGEST_STRING_LENGTH , 228.Ev SHA384_DIGEST_STRING_LENGTH , 229or 230.Ev SHA512_DIGEST_STRING_LENGTH , 231depending on the function being used) 232or a 233.Dv NULL 234pointer. 235In the latter case, space will be dynamically allocated via 236.Xr malloc 3 237and should be freed using 238.Xr free 3 239when it is no longer needed. 240.Sh EXAMPLES 241The following code fragment will calculate the SHA-256 digest for the string 242.Qq abc , 243which is 244.Dq 0xba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad . 245.Bd -literal -offset indent 246SHA256_CTX ctx; 247uint8_t results[SHA256_DIGEST_LENGTH]; 248char *buf; 249int n; 250 251buf = "abc"; 252n = strlen(buf); 253SHA256_Init(\*[Am]ctx); 254SHA256_Update(\*[Am]ctx, (uint8_t *)buf, n); 255SHA256_Final(results, \*[Am]ctx); 256 257/* Print the digest as one long hex value */ 258printf("0x"); 259for (n = 0; n \*[Lt] SHA256_DIGEST_LENGTH; n++) 260 printf("%02x", results[n]); 261putchar('\en'); 262.Ed 263.Pp 264Alternately, the helper functions could be used in the following way: 265.Bd -literal -offset indent 266SHA256_CTX ctx; 267uint8_t output[SHA256_DIGEST_STRING_LENGTH]; 268char *buf = "abc"; 269 270printf("0x%s\en", SHA256_Data(buf, strlen(buf), output)); 271.Ed 272.Sh SEE ALSO 273.Xr cksum 1 , 274.Xr md4 3 , 275.Xr md5 3 , 276.Xr rmd160 3 , 277.Xr sha1 3 278.Rs 279.%T Secure Hash Standard 280.%O FIPS PUB 180-2 281.Re 282.Sh HISTORY 283The SHA2 functions appeared in 284.Ox 3.4 285and 286.Nx 3.0 . 287.Sh AUTHORS 288This implementation of the SHA functions was written by Aaron D. Gifford. 289.Pp 290The 291.Fn SHA256_End , 292.Fn SHA256_File , 293.Fn SHA256_FileChunk , 294and 295.Fn SHA256_Data 296helper functions are derived from code written by Poul-Henning Kamp. 297.Sh CAVEATS 298This implementation of the Secure Hash Standard has not been validated by 299NIST and as such is not in official compliance with the standard. 300.Pp 301If a message digest is to be copied to a multi-byte type (i.e.: 302an array of five 32-bit integers) it will be necessary to 303perform byte swapping on little endian machines such as the i386, alpha, 304and vax. 305