diff options
Diffstat (limited to 'lib/libmd/sha256.3')
| -rw-r--r-- | lib/libmd/sha256.3 | 208 |
1 files changed, 208 insertions, 0 deletions
diff --git a/lib/libmd/sha256.3 b/lib/libmd/sha256.3 new file mode 100644 index 000000000000..406dfd1b357d --- /dev/null +++ b/lib/libmd/sha256.3 @@ -0,0 +1,208 @@ +.\" +.\" ---------------------------------------------------------------------------- +.\" "THE BEER-WARE LICENSE" (Revision 42): +.\" <phk@FreeBSD.org> wrote this file. As long as you retain this notice you +.\" can do whatever you want with this stuff. If we meet some day, and you think +.\" this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp +.\" ---------------------------------------------------------------------------- +.\" +.\" From: Id: mdX.3,v 1.14 1999/02/11 20:31:49 wollman Exp +.\" +.Dd March 8, 2022 +.Dt SHA256 3 +.Os +.Sh NAME +.Nm SHA224_Init , +.Nm SHA224_Update , +.Nm SHA224_Final , +.Nm SHA224_End , +.Nm SHA224_Fd , +.Nm SHA224_FdChunk , +.Nm SHA224_File , +.Nm SHA224_FileChunk , +.Nm SHA224_Data , +.Nm SHA256_Init , +.Nm SHA256_Update , +.Nm SHA256_Final , +.Nm SHA256_End , +.Nm SHA256_Fd , +.Nm SHA256_FdChunk , +.Nm SHA256_File , +.Nm SHA256_FileChunk , +.Nm SHA256_Data +.Nd calculate the FIPS 180-2 ``SHA-256'' (or SHA-224) message digest +.Sh LIBRARY +.Lb libmd +.Sh SYNOPSIS +.In sys/types.h +.In sha224.h +.Ft void +.Fn SHA224_Init "SHA224_CTX *context" +.Ft void +.Fn SHA224_Update "SHA224_CTX *context" "const unsigned char *data" "size_t len" +.Ft void +.Fn SHA224_Final "unsigned char digest[32]" "SHA224_CTX *context" +.Ft "char *" +.Fn SHA224_End "SHA224_CTX *context" "char *buf" +.Ft "char *" +.Fn SHA224_Fd "int fd" "char *buf" +.Ft "char *" +.Fn SHA224_FdChunk "int fd" "char *buf" "off_t offset" "off_t length" +.Ft "char *" +.Fn SHA224_File "const char *filename" "char *buf" +.Ft "char *" +.Fn SHA224_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" +.Ft "char *" +.Fn SHA224_Data "const unsigned char *data" "unsigned int len" "char *buf" +.In sha256.h +.Ft void +.Fn SHA256_Init "SHA256_CTX *context" +.Ft void +.Fn SHA256_Update "SHA256_CTX *context" "const unsigned char *data" "size_t len" +.Ft void +.Fn SHA256_Final "unsigned char digest[32]" "SHA256_CTX *context" +.Ft "char *" +.Fn SHA256_End "SHA256_CTX *context" "char *buf" +.Ft "char *" +.Fn SHA256_Fd "int fd" "char *buf" +.Ft "char *" +.Fn SHA256_FdChunk "int fd" "char *buf" "off_t offset" "off_t length" +.Ft "char *" +.Fn SHA256_File "const char *filename" "char *buf" +.Ft "char *" +.Fn SHA256_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" +.Ft "char *" +.Fn SHA256_Data "const unsigned char *data" "unsigned int len" "char *buf" +.Sh DESCRIPTION +The +.Li SHA256_ +functions calculate a 256-bit cryptographic checksum (digest) +for any number of input bytes. +A cryptographic checksum is a one-way +hash function; that is, it is computationally impractical to find +the input corresponding to a particular output. +This net result is +a +.Dq fingerprint +of the input-data, which does not disclose the actual input. +.Pp +The +.Fn SHA256_Init , +.Fn SHA256_Update , +and +.Fn SHA256_Final +functions are the core functions. +Allocate an +.Vt SHA256_CTX , +initialize it with +.Fn SHA256_Init , +run over the data with +.Fn SHA256_Update , +and finally extract the result using +.Fn SHA256_Final , +which will also erase the +.Vt SHA256_CTX . +.Pp +.Fn SHA256_End +is a wrapper for +.Fn SHA256_Final +which converts the return value to a 65-character +(including the terminating '\e0') +ASCII string which represents the 256 bits in hexadecimal. +.Pp +.Fn SHA256_File +calculates the digest of a file, and uses +.Fn SHA256_End +to return the result. +If the file cannot be opened, a null pointer is returned. +.Fn SHA256_FileChunk +is similar to +.Fn SHA256_File , +but it only calculates the digest over a byte-range of the file specified, +starting at +.Fa offset +and spanning +.Fa length +bytes. +If the +.Fa length +parameter is specified as 0, or more than the length of the remaining part +of the file, +.Fn SHA256_FileChunk +calculates the digest from +.Fa offset +to the end of file. +.Fn SHA256_Data +calculates the digest of a chunk of data in memory, and uses +.Fn SHA256_End +to return the result. +.Pp +The +.Fn SHA256_Fd +and +.Fn SHA256_FdChunk +functions are identical to their +.Fn SHA256_File +and +.Fn SHA256_FileChunk +counterparts, with the exception that the first argument is an +.Fa fd +instead of a +.Fa filename . +.Pp +When using +.Fn SHA256_End , +.Fn SHA256_File , +or +.Fn SHA256_Data , +the +.Fa buf +argument can be a null pointer, in which case the returned string +is allocated with +.Xr malloc 3 +and subsequently must be explicitly deallocated using +.Xr free 3 +after use. +If the +.Fa buf +argument is non-null it must point to at least 65 characters of buffer space. +.Pp +SHA224 is identical SHA256, except it has slightly different initialization +vectors, and is truncated to a shorter digest. +.Sh ERRORS +The +.Fn SHA256_End +function called with a null buf argument may fail and return NULL if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Insufficient storage space is available. +.El +.Pp +The +.Fn SHA256_File +and +.Fn SHA256_FileChunk +may return NULL when underlying +.Xr open 2 , +.Xr fstat 2 , +.Xr lseek 2 , +or +.Xr SHA256_End 3 +fail. +.Sh SEE ALSO +.Xr md4 3 , +.Xr md5 3 , +.Xr ripemd 3 , +.Xr sha 3 , +.Xr sha512 3 , +.Xr skein 3 +.Sh HISTORY +These functions appeared in +.Fx 6.0 . +.Sh AUTHORS +The core hash routines were implemented by Colin Percival based on +the published FIPS 180-2 standard. +.Sh BUGS +No method is known to exist which finds two files having the same hash value, +nor to find a file with a specific hash value. +There is on the other hand no guarantee that such a method does not exist. |