diff --git a/src/lib/libc/hash/SHA256Init.3 b/src/lib/libc/hash/SHA256Init.3 index ef95d23b..278c1cad 100644 --- a/src/lib/libc/hash/SHA256Init.3 +++ b/src/lib/libc/hash/SHA256Init.3 @@ -1,46 +1,351 @@ -# $OpenBSD: SHA256Init.3,v 1.1 2019/08/30 22:20:43 deraadt Exp $ +.\" $OpenBSD: SHA256Init.3,v 1.2 2019/12/04 18:28:38 deraadt Exp $ +.\" +.\" Copyright (c) 2003, 2004 Todd C. Miller +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" Sponsored in part by the Defense Advanced Research Projects +.\" Agency (DARPA) and Air Force Research Laboratory, Air Force +.\" Materiel Command, USAF, under agreement number F39502-99-1-0512. +.\" +.\" See http://www.nist.gov/sha/ for the detailed standard +.\" +.Dd $Mdocdate: December 4 2019 $ +.Dt SHA256INIT 3 +.Os +.Sh NAME +.Nm SHA224Init , +.Nm SHA224Update , +.Nm SHA224Pad , +.Nm SHA224Final , +.Nm SHA224Transform , +.Nm SHA224End , +.Nm SHA224File , +.Nm SHA224FileChunk , +.Nm SHA224Data , +.Nm SHA256Init , +.Nm SHA256Update , +.Nm SHA256Pad , +.Nm SHA256Final , +.Nm SHA256Transform , +.Nm SHA256End , +.Nm SHA256File , +.Nm SHA256FileChunk , +.Nm SHA256Data , +.Nm SHA384Init , +.Nm SHA384Update , +.Nm SHA384Pad , +.Nm SHA384Final , +.Nm SHA384Transform , +.Nm SHA384End , +.Nm SHA384File , +.Nm SHA384FileChunk , +.Nm SHA384Data , +.Nm SHA512Init , +.Nm SHA512Update , +.Nm SHA512Pad , +.Nm SHA512Final , +.Nm SHA512Transform , +.Nm SHA512End , +.Nm SHA512File , +.Nm SHA512FileChunk , +.Nm SHA512Data , +.Nm SHA512_256Init , +.Nm SHA512_256Update , +.Nm SHA512_256Pad , +.Nm SHA512_256Final , +.Nm SHA512_256Transform , +.Nm SHA512_256End , +.Nm SHA512_256File , +.Nm SHA512_256FileChunk , +.Nm SHA512_256Data +.Nd calculate the NIST Secure Hash Standard (version 2) +.Sh SYNOPSIS +.In sys/types.h +.In sha2.h +.Ft void +.Fn SHA224Init "SHA2_CTX *context" +.Ft void +.Fn SHA224Update "SHA2_CTX *context" "const u_int8_t *data" "size_t len" +.Ft void +.Fn SHA224Pad "SHA2_CTX *context" +.Ft void +.Fn SHA224Final "u_int8_t digest[SHA224_DIGEST_LENGTH]" "SHA2_CTX *context" +.Ft void +.Fn SHA224Transform "u_int32_t state[8]" "const u_int8_t buffer[SHA224_BLOCK_LENGTH]" +.Ft "char *" +.Fn SHA224End "SHA2_CTX *context" "char *buf" +.Ft "char *" +.Fn SHA224File "const char *filename" "char *buf" +.Ft "char *" +.Fn SHA224FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" +.Ft "char *" +.Fn SHA224Data "const u_int8_t *data" "size_t len" "char *buf" +.Ft void +.Fn SHA256Init "SHA2_CTX *context" +.Ft void +.Fn SHA256Update "SHA2_CTX *context" "const u_int8_t *data" "size_t len" +.Ft void +.Fn SHA256Pad "SHA2_CTX *context" +.Ft void +.Fn SHA256Final "u_int8_t digest[SHA256_DIGEST_LENGTH]" "SHA2_CTX *context" +.Ft void +.Fn SHA256Transform "u_int32_t state[8]" "const u_int8_t buffer[SHA256_BLOCK_LENGTH]" +.Ft "char *" +.Fn SHA256End "SHA2_CTX *context" "char *buf" +.Ft "char *" +.Fn SHA256File "const char *filename" "char *buf" +.Ft "char *" +.Fn SHA256FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" +.Ft "char *" +.Fn SHA256Data "const u_int8_t *data" "size_t len" "char *buf" +.Ft void +.Fn SHA384Init "SHA2_CTX *context" +.Ft void +.Fn SHA384Update "SHA2_CTX *context" "const u_int8_t *data" "size_t len" +.Ft void +.Fn SHA384Pad "SHA2_CTX *context" +.Ft void +.Fn SHA384Final "u_int8_t digest[SHA384_DIGEST_LENGTH]" "SHA2_CTX *context" +.Ft void +.Fn SHA384Transform "u_int64_t state[8]" "const u_int8_t buffer[SHA384_BLOCK_LENGTH]" +.Ft "char *" +.Fn SHA384End "SHA2_CTX *context" "char *buf" +.Ft "char *" +.Fn SHA384File "const char *filename" "char *buf" +.Ft "char *" +.Fn SHA384FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" +.Ft "char *" +.Fn SHA384Data "const u_int8_t *data" "size_t len" "char *buf" +.Ft void +.Fn SHA512Init "SHA2_CTX *context" +.Ft void +.Fn SHA512Update "SHA2_CTX *context" "const u_int8_t *data" "size_t len" +.Ft void +.Fn SHA512Pad "SHA2_CTX *context" +.Ft void +.Fn SHA512Final "u_int8_t digest[SHA512_DIGEST_LENGTH]" "SHA2_CTX *context" +.Ft void +.Fn SHA512Transform "u_int64_t state[8]" "const u_int8_t buffer[SHA512_BLOCK_LENGTH]" +.Ft "char *" +.Fn SHA512End "SHA2_CTX *context" "char *buf" +.Ft "char *" +.Fn SHA512File "const char *filename" "char *buf" +.Ft "char *" +.Fn SHA512FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" +.Ft "char *" +.Fn SHA512Data "const u_int8_t *data" "size_t len" "char *buf" +.Ft void +.Fn SHA512_256Init "SHA2_CTX *context" +.Ft void +.Fn SHA512_256Update "SHA2_CTX *context" "const u_int8_t *data" "size_t len" +.Ft void +.Fn SHA512_256Pad "SHA2_CTX *context" +.Ft void +.Fn SHA512_256Final "u_int8_t digest[SHA512_256_DIGEST_LENGTH]" "SHA2_CTX *context" +.Ft void +.Fn SHA512_256Transform "u_int64_t state[8]" "const u_int8_t buffer[SHA512_256_BLOCK_LENGTH]" +.Ft "char *" +.Fn SHA512_256End "SHA2_CTX *context" "char *buf" +.Ft "char *" +.Fn SHA512_256File "const char *filename" "char *buf" +.Ft "char *" +.Fn SHA512_256FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" +.Ft "char *" +.Fn SHA512_256Data "const u_int8_t *data" "size_t len" "char *buf" +.Sh DESCRIPTION +The SHA2 functions implement the NIST Secure Hash Standard, +FIPS PUB 180-2. +The SHA2 functions are used to generate a condensed representation of a +message called a message digest, suitable for use as a digital signature. +There are four families of functions, with names corresponding to +the number of bits in the resulting message digest. +The SHA-224 and SHA-256 functions are limited to processing a message of less +than 2^64 bits as input. +The SHA-384 and SHA-512 functions can process a message of at most 2^128 - 1 +bits as input. +.Pp +The SHA2 functions are considered to be more secure than the +.Xr sha1 3 +functions with which they share a similar interface. +The 224, 256, 384, and 512-bit versions of SHA2 share the same interface. +SHA512/256, a truncated version of SHA512, is also supported. +For brevity, only the 256-bit variants are described below. +.Pp +The +.Fn SHA256Init +function initializes a SHA2_CTX +.Fa context +for use with +.Fn SHA256Update +and +.Fn SHA256Final . +The +.Fn SHA256Update +function adds +.Fa data +of length +.Fa len +to the SHA2_CTX specified by +.Fa context . +.Fn SHA256Final +is called when all data has been added via +.Fn SHA256Update +and stores a message digest in the +.Fa digest +parameter. +.Pp +The +.Fn SHA256Pad +function can be used to apply padding to the message digest as in +.Fn SHA256Final , +but the current context can still be used with +.Fn SHA256Update . +.Pp +The +.Fn SHA256Transform +function is used by +.Fn SHA256Update +to hash 512-bit blocks and forms the core of the algorithm. +Most programs should use the interface provided by +.Fn SHA256Init , +.Fn SHA256Update , +and +.Fn SHA256Final +instead of calling +.Fn SHA256Transform +directly. +.Pp +The +.Fn SHA256End +function is a front end for +.Fn SHA256Final +which converts the digest into an +.Tn ASCII +representation of the digest in hexadecimal. +.Pp +The +.Fn SHA256File +function calculates the digest for a file and returns the result via +.Fn SHA256End . +If +.Fn SHA256File +is unable to open the file, a +.Dv NULL +pointer is returned. +.Pp +.Fn SHA256FileChunk +behaves like +.Fn SHA256File +but calculates the digest only for that portion of the file starting at +.Fa offset +and continuing for +.Fa length +bytes or until end of file is reached, whichever comes first. +A zero +.Fa length +can be specified to read until end of file. +A negative +.Fa length +or +.Fa offset +will be ignored. +.Pp +The +.Fn SHA256Data +function +calculates the digest of an arbitrary string and returns the result via +.Fn SHA256End . +.Pp +For each of the +.Fn SHA256End , +.Fn SHA256File , +.Fn SHA256FileChunk , +and +.Fn SHA256Data +functions the +.Fa buf +parameter should either be a string large enough to hold the resulting digest +(e.g.\& +.Dv SHA224_DIGEST_STRING_LENGTH , +.Dv SHA256_DIGEST_STRING_LENGTH , +.Dv SHA384_DIGEST_STRING_LENGTH , +.Dv SHA512_DIGEST_STRING_LENGTH , +or +.Dv SHA512_256_DIGEST_STRING_LENGTH , +depending on the function being used) +or a +.Dv NULL +pointer. +In the latter case, space will be dynamically allocated via +.Xr malloc 3 +and should be freed using +.Xr free 3 +when it is no longer needed. +.Sh EXAMPLES +The following code fragment will calculate the SHA-256 digest for the string +.Qq abc , +which is +.Dq 0xba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad . +.Bd -literal -offset indent +SHA2_CTX ctx; +u_int8_t results[SHA256_DIGEST_LENGTH]; +char *buf; +int n; -# hash functions -.PATH: ${LIBCSRCDIR}/hash +buf = "abc"; +n = strlen(buf); +SHA256Init(&ctx); +SHA256Update(&ctx, (u_int8_t *)buf, n); +SHA256Final(results, &ctx); -HELPER= md5hl.c rmd160hl.c sha1hl.c sha224hl.c sha256hl.c sha384hl.c sha512hl.c sha512_256hl.c -SRCS+= md5.c rmd160.c sha1.c sha2.c ${HELPER} siphash.c -MAN+= MD5Init.3 RMD160Init.3 SHA1Init.3 SHA256Init.3 SipHash24_Init.3 +/* Print the digest as one long hex value */ +printf("0x"); +for (n = 0; n \*(Lt SHA256_DIGEST_LENGTH; n++) + printf("%02x", results[n]); +putchar('\en'); +.Ed +.Pp +Alternately, the helper functions could be used in the following way: +.Bd -literal -offset indent +u_int8_t output[SHA256_DIGEST_STRING_LENGTH]; +char *buf = "abc"; -CLEANFILES+= ${HELPER} - -md5hl.c: helper.c - sed -e 's/hashinc/md5.h/g' -e 's/HASH/MD5/g' $> > $@ - -rmd160hl.c: helper.c - sed -e 's/hashinc/rmd160.h/g' -e 's/HASH/RMD160/g' $> > $@ - -sha1hl.c: helper.c - sed -e 's/hashinc/sha1.h/g' -e 's/HASH/SHA1/g' $> > $@ - -sha224hl.c: helper.c - sed -e 's/hashinc/sha2.h/g' \ - -e 's/HASH/SHA224/g' \ - -e 's/SHA[0-9][0-9][0-9]_CTX/SHA2_CTX/g' $> > $@ - -sha256hl.c: helper.c - sed -e 's/hashinc/sha2.h/g' \ - -e 's/HASH/SHA256/g' \ - -e 's/SHA[0-9][0-9][0-9]_CTX/SHA2_CTX/g' $> > $@ - -sha384hl.c: helper.c - sed -e 's/hashinc/sha2.h/g' \ - -e 's/HASH/SHA384/g' \ - -e 's/SHA[0-9][0-9][0-9]_CTX/SHA2_CTX/g' $> > $@ - -sha512hl.c: helper.c - sed -e 's/hashinc/sha2.h/g' \ - -e 's/HASH/SHA512/g' \ - -e 's/SHA[0-9][0-9][0-9]_CTX/SHA2_CTX/g' $> > $@ - -sha512_256hl.c: helper.c - sed -e 's/hashinc/sha2.h/g' \ - -e 's/HASH/SHA512_256/g' \ - -e 's/SHA512_256_CTX/SHA2_CTX/g' $> > $@ - -beforedepend: md5hl.c rmd160hl.c sha1hl.c sha256hl.c sha384hl.c sha512hl.c sha512_256hl.c +printf("0x%s\en", SHA256Data(buf, strlen(buf), output)); +.Ed +.Sh SEE ALSO +.Xr cksum 1 , +.Xr sha256 1 , +.Xr MD5Init 3 , +.Xr RMD160Init 3 , +.Xr SHA1Init 3 +.Rs +.%T Secure Hash Standard +.%O FIPS PUB 180-2 +.Re +.Sh HISTORY +The SHA2 functions appeared in +.Ox 3.4 . +.Sh AUTHORS +.An -nosplit +This implementation of the SHA functions was written by +.An Aaron D. Gifford . +.Pp +The +.Fn SHA256End , +.Fn SHA256File , +.Fn SHA256FileChunk , +and +.Fn SHA256Data +helper functions are derived from code written by +.An Poul-Henning Kamp .