While there, remove .Tn from man pages. Also remove an obsolete comment about the 80386. MFC after: 1 week Sponsored by: Klara, Inc. Reviewed by: kevans, allanjude Differential Revision: https://reviews.freebsd.org/D38373
265 lines
7.0 KiB
Groff
265 lines
7.0 KiB
Groff
.\"
|
|
.\" ----------------------------------------------------------------------------
|
|
.\" "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
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd February 3, 2023
|
|
.Dt SHA512 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm SHA512_Init ,
|
|
.Nm SHA512_Update ,
|
|
.Nm SHA512_Final ,
|
|
.Nm SHA512_End ,
|
|
.Nm SHA512_File ,
|
|
.Nm SHA512_FileChunk ,
|
|
.Nm SHA512_Data ,
|
|
.Nm SHA384_Init ,
|
|
.Nm SHA384_Update ,
|
|
.Nm SHA384_Final ,
|
|
.Nm SHA384_End ,
|
|
.Nm SHA384_File ,
|
|
.Nm SHA384_FileChunk ,
|
|
.Nm SHA384_Data ,
|
|
.Nm SHA512_224_Init ,
|
|
.Nm SHA512_224_Update ,
|
|
.Nm SHA512_224_Final ,
|
|
.Nm SHA512_224_End ,
|
|
.Nm SHA512_224_File ,
|
|
.Nm SHA512_224_FileChunk ,
|
|
.Nm SHA512_224_Data
|
|
.Nm SHA512_256_Init ,
|
|
.Nm SHA512_256_Update ,
|
|
.Nm SHA512_256_Final ,
|
|
.Nm SHA512_256_End ,
|
|
.Nm SHA512_256_File ,
|
|
.Nm SHA512_256_FileChunk ,
|
|
.Nm SHA512_256_Data
|
|
.Nd calculate the FIPS 180-4 ``SHA-512'' family of message digests
|
|
.Sh LIBRARY
|
|
.Lb libmd
|
|
.Sh SYNOPSIS
|
|
.In sys/types.h
|
|
.In sha512.h
|
|
.Ft void
|
|
.Fn SHA512_Init "SHA512_CTX *context"
|
|
.Ft void
|
|
.Fn SHA512_Update "SHA512_CTX *context" "const unsigned char *data" "size_t len"
|
|
.Ft void
|
|
.Fn SHA512_Final "unsigned char digest[64]" "SHA512_CTX *context"
|
|
.Ft "char *"
|
|
.Fn SHA512_End "SHA512_CTX *context" "char *buf"
|
|
.Ft "char *"
|
|
.Fn SHA512_File "const char *filename" "char *buf"
|
|
.Ft "char *"
|
|
.Fn SHA512_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
|
|
.Ft "char *"
|
|
.Fn SHA512_Data "const unsigned char *data" "unsigned int len" "char *buf"
|
|
.In sha384.h
|
|
.Ft void
|
|
.Fn SHA384_Init "SHA384_CTX *context"
|
|
.Ft void
|
|
.Fn SHA384_Update "SHA384_CTX *context" "const unsigned char *data" "size_t len"
|
|
.Ft void
|
|
.Fn SHA384_Final "unsigned char digest[48]" "SHA384_CTX *context"
|
|
.Ft "char *"
|
|
.Fn SHA384_End "SHA384_CTX *context" "char *buf"
|
|
.Ft "char *"
|
|
.Fn SHA384_File "const char *filename" "char *buf"
|
|
.Ft "char *"
|
|
.Fn SHA384_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
|
|
.Ft "char *"
|
|
.Fn SHA384_Data "const unsigned char *data" "unsigned int len" "char *buf"
|
|
.In sha512t.h
|
|
.Ft void
|
|
.Fn SHA512_224_Init "SHA512_CTX *context"
|
|
.Ft void
|
|
.Fn SHA512_224_Update "SHA512_CTX *context" "const unsigned char *data" "size_t len"
|
|
.Ft void
|
|
.Fn SHA512_224_Final "unsigned char digest[32]" "SHA512_CTX *context"
|
|
.Ft "char *"
|
|
.Fn SHA512_224_End "SHA512_CTX *context" "char *buf"
|
|
.Ft "char *"
|
|
.Fn SHA512_224_File "const char *filename" "char *buf"
|
|
.Ft "char *"
|
|
.Fn SHA512_224_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
|
|
.Ft "char *"
|
|
.Fn SHA512_224_Data "const unsigned char *data" "unsigned int len" "char *buf"
|
|
.Ft void
|
|
.Fn SHA512_256_Init "SHA512_CTX *context"
|
|
.Ft void
|
|
.Fn SHA512_256_Update "SHA512_CTX *context" "const unsigned char *data" "size_t len"
|
|
.Ft void
|
|
.Fn SHA512_256_Final "unsigned char digest[32]" "SHA512_CTX *context"
|
|
.Ft "char *"
|
|
.Fn SHA512_256_End "SHA512_CTX *context" "char *buf"
|
|
.Ft "char *"
|
|
.Fn SHA512_256_File "const char *filename" "char *buf"
|
|
.Ft "char *"
|
|
.Fn SHA512_256_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
|
|
.Ft "char *"
|
|
.Fn SHA512_256_Data "const unsigned char *data" "unsigned int len" "char *buf"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Li SHA512_
|
|
functions calculate a 512-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 SHA512_Init ,
|
|
.Fn SHA512_Update ,
|
|
and
|
|
.Fn SHA512_Final
|
|
functions are the core functions.
|
|
Allocate an
|
|
.Vt SHA512_CTX ,
|
|
initialize it with
|
|
.Fn SHA512_Init ,
|
|
run over the data with
|
|
.Fn SHA512_Update ,
|
|
and finally extract the result using
|
|
.Fn SHA512_Final ,
|
|
which will also erase the
|
|
.Vt SHA512_CTX .
|
|
.Pp
|
|
.Fn SHA512_End
|
|
is a wrapper for
|
|
.Fn SHA512_Final
|
|
which converts the return value to a 129-character
|
|
(including the terminating '\e0')
|
|
ASCII string which represents the 512 bits in hexadecimal.
|
|
.Pp
|
|
.Fn SHA512_File
|
|
calculates the digest of a file, and uses
|
|
.Fn SHA512_End
|
|
to return the result.
|
|
If the file cannot be opened, a null pointer is returned.
|
|
.Fn SHA512_FileChunk
|
|
is similar to
|
|
.Fn SHA512_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 SHA512_FileChunk
|
|
calculates the digest from
|
|
.Fa offset
|
|
to the end of file.
|
|
.Fn SHA512_Data
|
|
calculates the digest of a chunk of data in memory, and uses
|
|
.Fn SHA512_End
|
|
to return the result.
|
|
.Pp
|
|
When using
|
|
.Fn SHA512_End ,
|
|
.Fn SHA512_File ,
|
|
or
|
|
.Fn SHA512_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 129 characters of buffer space.
|
|
.Pp
|
|
The
|
|
.Li SHA384_ ,
|
|
.Li SHA512_224 ,
|
|
and
|
|
.Li SHA512_256_
|
|
functions are identical to the
|
|
.Li SHA512_
|
|
functions except they use a different initial hash value and the output is
|
|
truncated to 384, 224, and 256 bits respectively.
|
|
.Pp
|
|
.Fn SHA384_End
|
|
is a wrapper for
|
|
.Fn SHA384_Final
|
|
which converts the return value to a 97-character
|
|
(including the terminating '\e0')
|
|
ASCII string which represents the 384 bits in hexadecimal.
|
|
.Pp
|
|
.Fn SHA512_224_End
|
|
is a wrapper for
|
|
.Fn SHA512_Final
|
|
which converts the return value to a 57-character
|
|
(including the terminating '\e0')
|
|
ASCII string which represents the 224 bits in hexadecimal.
|
|
.Pp
|
|
.Fn SHA512_224_End
|
|
is a wrapper for
|
|
.Fn SHA512_Final
|
|
which converts the return value to a 57-character
|
|
(including the terminating '\e0')
|
|
.Tn ASCII
|
|
string which represents the 224 bits in hexadecimal.
|
|
.Pp
|
|
.Fn SHA512_256_End
|
|
is a wrapper for
|
|
.Fn SHA512_Final
|
|
which converts the return value to a 65-character
|
|
(including the terminating '\e0')
|
|
ASCII string which represents the 256 bits in hexadecimal.
|
|
.Sh ERRORS
|
|
The
|
|
.Fn SHA512_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 SHA512_File
|
|
and
|
|
.Fn SHA512_FileChunk
|
|
may return NULL when underlying
|
|
.Xr open 2 ,
|
|
.Xr fstat 2 ,
|
|
.Xr lseek 2 ,
|
|
or
|
|
.Xr SHA512_End 3
|
|
fail.
|
|
.Sh SEE ALSO
|
|
.Xr md4 3 ,
|
|
.Xr md5 3 ,
|
|
.Xr ripemd 3 ,
|
|
.Xr sha 3 ,
|
|
.Xr sha256 3 ,
|
|
.Xr sha512 3 ,
|
|
.Xr skein 3
|
|
.Sh HISTORY
|
|
These functions appeared in
|
|
.Fx 9.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.
|