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