Index: head/lib/libmd/mdX.3 =================================================================== --- head/lib/libmd/mdX.3 (revision 348071) +++ head/lib/libmd/mdX.3 (revision 348072) @@ -1,193 +1,213 @@ .\" .\" ---------------------------------------------------------------------------- .\" "THE BEER-WARE LICENSE" (Revision 42): .\" 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 .\" ---------------------------------------------------------------------------- .\" .\" $FreeBSD$ .\" -.Dd July 20, 2018 +.Dd May 21, 2019 .Dt MDX 3 .Os .Sh NAME .Nm MDXInit , .Nm MDXUpdate , .Nm MDXPad , .Nm MDXFinal , .Nm MDXEnd , .Nm MDXFile , .Nm MDXFileChunk , .Nm MDXData .Nd calculate the RSA Data Security, Inc., ``MDX'' message digest .Sh LIBRARY .Lb libmd .Sh SYNOPSIS .In sys/types.h .In mdX.h .Ft void .Fn MDXInit "MDX_CTX *context" .Ft void .Fn MDXUpdate "MDX_CTX *context" "const void *data" "unsigned int len" .Ft void .Fn MDXPad "MDX_CTX *context" .Ft void .Fn MDXFinal "unsigned char digest[16]" "MDX_CTX *context" .Ft "char *" .Fn MDXEnd "MDX_CTX *context" "char *buf" .Ft "char *" .Fn MDXFile "const char *filename" "char *buf" .Ft "char *" .Fn MDXFileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" .Ft "char *" .Fn MDXData "const void *data" "unsigned int len" "char *buf" .Sh DESCRIPTION The MDX functions calculate a 128-bit cryptographic checksum (digest) for any number of input bytes. A cryptographic checksum is a one-way hash-function, that is, you cannot find (except by exhaustive search) 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 MD4 is the fastest and MD5 is somewhat slower. MD4 has now been broken; it should only be used where necessary for backward compatibility. MD5 has not yet (1999-02-11) been broken, but sufficient attacks have been made that its security is in some doubt. The attacks on both MD4 and MD5 are both in the nature of finding .Dq collisions \[en] that is, multiple inputs which hash to the same value; it is still unlikely for an attacker to be able to determine the exact original input given a hash value. .Pp The .Fn MDXInit , .Fn MDXUpdate , and .Fn MDXFinal functions are the core functions. Allocate an .Vt MDX_CTX , initialize it with .Fn MDXInit , run over the data with .Fn MDXUpdate , and finally extract the result using .Fn MDXFinal , which will also erase the .Vt MDX_CTX . .Pp The .Fn MDXPad function can be used to pad message data in same way as done by .Fn MDXFinal without terminating calculation. .Pp The .Fn MDXEnd function is a wrapper for .Fn MDXFinal which converts the return value to a 33-character (including the terminating '\e0') .Tn ASCII string which represents the 128 bits in hexadecimal. .Pp The .Fn MDXFile function calculates the digest of a file, and uses .Fn MDXEnd to return the result. If the file cannot be opened, a null pointer is returned. The .Fn MDXFileChunk function is similar to .Fn MDXFile , 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 MDXFileChunk calculates the digest from .Fa offset to the end of file. The .Fn MDXData function calculates the digest of a chunk of data in memory, and uses .Fn MDXEnd to return the result. .Pp When using .Fn MDXEnd , .Fn MDXFile , or .Fn MDXData , 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 33 characters of buffer space. +.Sh ERRORS +The +.Fn MDXEnd +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 MDXFile +and +.Fn MDXFileChunk +may return NULL when underlying +.Xr open 2 , +.Xr fstat 2 , +.Xr lseek 2 , +or +.Xr MDXEnd 2 +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 .Rs .%A R. Rivest .%T The MD4 Message-Digest Algorithm .%O RFC 1186 .Re .Rs .%A R. Rivest .%T The MD5 Message-Digest Algorithm .%O RFC 1321 .Re .Rs .%A H. Dobbertin .%T Alf Swindles Ann .%J CryptoBytes .%N 1(3):5 .%D 1995 .Re .Rs .%A MJ. B. Robshaw .%T On Recent Results for MD2, MD4 and MD5 .%J RSA Laboratories Bulletin .%N 4 .%D November 12, 1996 .Re .Sh HISTORY These functions appeared in .Fx 2.0 . .Sh AUTHORS The original MDX routines were developed by .Tn RSA Data Security, Inc., and published in the above references. This code is derived directly from these implementations by .An Poul-Henning Kamp Aq Mt phk@FreeBSD.org . .Pp Phk ristede runen. .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. Index: head/lib/libmd/ripemd.3 =================================================================== --- head/lib/libmd/ripemd.3 (revision 348071) +++ head/lib/libmd/ripemd.3 (revision 348072) @@ -1,145 +1,165 @@ .\" .\" ---------------------------------------------------------------------------- .\" "THE BEER-WARE LICENSE" (Revision 42): .\" 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 July 20, 2018 .Dt RIPEMD 3 .Os .Sh NAME .Nm RIPEMD160_Init , .Nm RIPEMD160_Update , .Nm RIPEMD160_Final , .Nm RIPEMD160_End , .Nm RIPEMD160_File , .Nm RIPEMD160_FileChunk , .Nm RIPEMD160_Data .Nd calculate the RIPEMD160 message digest .Sh LIBRARY .Lb libmd .Sh SYNOPSIS .In sys/types.h .In ripemd.h .Ft void .Fn RIPEMD160_Init "RIPEMD160_CTX *context" .Ft void .Fn RIPEMD160_Update "RIPEMD160_CTX *context" "const unsigned char *data" "unsigned int len" .Ft void .Fn RIPEMD160_Final "unsigned char digest[20]" "RIPEMD160_CTX *context" .Ft "char *" .Fn RIPEMD160_End "RIPEMD160_CTX *context" "char *buf" .Ft "char *" .Fn RIPEMD160_File "const char *filename" "char *buf" .Ft "char *" .Fn RIPEMD160_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" .Ft "char *" .Fn RIPEMD160_Data "const unsigned char *data" "unsigned int len" "char *buf" .Sh DESCRIPTION The .Li RIPEMD160_ functions calculate a 160-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 RIPEMD160_Init , .Fn RIPEMD160_Update , and .Fn RIPEMD160_Final functions are the core functions. Allocate an .Vt RIPEMD160_CTX , initialize it with .Fn RIPEMD160_Init , run over the data with .Fn RIPEMD160_Update , and finally extract the result using .Fn RIPEMD160_Final , which will also erase the .Vt RIPEMD160_CTX . .Pp The .Fn RIPEMD160_End function is a wrapper for .Fn RIPEMD160_Final which converts the return value to a 41-character (including the terminating '\e0') .Tn ASCII string which represents the 160 bits in hexadecimal. .Pp The .Fn RIPEMD160_File function calculates the digest of a file, and uses .Fn RIPEMD160_End to return the result. If the file cannot be opened, a null pointer is returned. The .Fn RIPEMD160_FileChunk function is similar to .Fn RIPEMD160_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 RIPEMD160_FileChunk calculates the digest from .Fa offset to the end of file. The .Fn RIPEMD160_Data function calculates the digest of a chunk of data in memory, and uses .Fn RIPEMD160_End to return the result. .Pp When using .Fn RIPEMD160_End , .Fn RIPEMD160_File , or .Fn RIPEMD160_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 41 characters of buffer space. +.Sh ERRORS +The +.Fn RIPEMD160_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 RIPEMD160_File +and +.Fn RIPEMD160_FileChunk +may return NULL when underlying +.Xr open 2 , +.Xr fstat 2 , +.Xr lseek 2 , +or +.Xr RIPEMD160_End 2 +fail. .Sh SEE ALSO .Xr md4 3 , .Xr md5 3 , .Xr sha 3 , .Xr sha256 3 , .Xr sha512 3 , .Xr skein 3 .Sh HISTORY These functions appeared in .Fx 4.0 . .Sh AUTHORS The core hash routines were implemented by Eric Young based on the published .Tn RIPEMD160 specification. .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. Index: head/lib/libmd/sha.3 =================================================================== --- head/lib/libmd/sha.3 (revision 348071) +++ head/lib/libmd/sha.3 (revision 348072) @@ -1,188 +1,208 @@ .\" .\" ---------------------------------------------------------------------------- .\" "THE BEER-WARE LICENSE" (Revision 42): .\" 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 July 20, 2018 +.Dd May 21, 2019 .Dt SHA 3 .Os .Sh NAME .Nm SHA_Init , .Nm SHA_Update , .Nm SHA_Final , .Nm SHA_End , .Nm SHA_File , .Nm SHA_FileChunk , .Nm SHA_Data , .Nm SHA1_Init , .Nm SHA1_Update , .Nm SHA1_Final , .Nm SHA1_End , .Nm SHA1_File , .Nm SHA1_FileChunk , .Nm SHA1_Data .Nd calculate the FIPS 160 and 160-1 ``SHA'' message digests .Sh LIBRARY .Lb libmd .Sh SYNOPSIS .In sys/types.h .In sha.h .Ft void .Fn SHA_Init "SHA_CTX *context" .Ft void .Fn SHA_Update "SHA_CTX *context" "const unsigned char *data" "size_t len" .Ft void .Fn SHA_Final "unsigned char digest[20]" "SHA_CTX *context" .Ft "char *" .Fn SHA_End "SHA_CTX *context" "char *buf" .Ft "char *" .Fn SHA_File "const char *filename" "char *buf" .Ft "char *" .Fn SHA_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" .Ft "char *" .Fn SHA_Data "const unsigned char *data" "unsigned int len" "char *buf" .Ft void .Fn SHA1_Init "SHA_CTX *context" .Ft void .Fn SHA1_Update "SHA_CTX *context" "const unsigned char *data" "size_t len" .Ft void .Fn SHA1_Final "unsigned char digest[20]" "SHA_CTX *context" .Ft "char *" .Fn SHA1_End "SHA_CTX *context" "char *buf" .Ft "char *" .Fn SHA1_File "const char *filename" "char *buf" .Ft "char *" .Fn SHA1_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" .Ft "char *" .Fn SHA1_Data "const unsigned char *data" "unsigned int len" "char *buf" .Sh DESCRIPTION The .Li SHA_ and .Li SHA1_ functions calculate a 160-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 .Tn SHA (or .Tn SHA-0 ) is the original Secure Hash Algorithm specified in .Tn FIPS 160. It was quickly proven insecure, and has been superseded by .Tn SHA-1 . .Tn SHA-0 is included for compatibility purposes only. .Pp The .Fn SHA1_Init , .Fn SHA1_Update , and .Fn SHA1_Final functions are the core functions. Allocate an .Vt SHA_CTX , initialize it with .Fn SHA1_Init , run over the data with .Fn SHA1_Update , and finally extract the result using .Fn SHA1_Final , which will also erase the .Vt SHA_CTX . .Pp .Fn SHA1_End is a wrapper for .Fn SHA1_Final which converts the return value to a 41-character (including the terminating '\e0') .Tn ASCII string which represents the 160 bits in hexadecimal. .Pp .Fn SHA1_File calculates the digest of a file, and uses .Fn SHA1_End to return the result. If the file cannot be opened, a null pointer is returned. .Fn SHA1_FileChunk is similar to .Fn SHA1_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 SHA1_FileChunk calculates the digest from .Fa offset to the end of file. .Fn SHA1_Data calculates the digest of a chunk of data in memory, and uses .Fn SHA1_End to return the result. .Pp When using .Fn SHA1_End , .Fn SHA1_File , or .Fn SHA1_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 41 characters of buffer space. +.Sh ERRORS +The +.Fn SHA1_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 SHA1_File +and +.Fn SHA1_FileChunk +may return NULL when underlying +.Xr open 2 , +.Xr fstat 2 , +.Xr lseek 2 , +or +.Xr SHA1_End 2 +fail. .Sh SEE ALSO .Xr md4 3 , .Xr md5 3 , .Xr ripemd 3 , .Xr sha256 3 , .Xr sha512 3 , .Xr skein 3 .Sh HISTORY These functions appeared in .Fx 4.0 . .Sh AUTHORS The core hash routines were implemented by Eric Young based on the published .Tn FIPS standards. .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. .Pp The .Tn IA32 (Intel) implementation of .Tn SHA-1 makes heavy use of the .Ql bswapl instruction, which is not present on the original 80386. Attempts to use .Tn SHA-1 on those processors will cause an illegal instruction trap. (Arguably, the kernel should simply emulate this instruction.) Index: head/lib/libmd/sha256.3 =================================================================== --- head/lib/libmd/sha256.3 (revision 348071) +++ head/lib/libmd/sha256.3 (revision 348072) @@ -1,167 +1,187 @@ .\" .\" ---------------------------------------------------------------------------- .\" "THE BEER-WARE LICENSE" (Revision 42): .\" 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 July 20, 2018 .Dt SHA256 3 .Os .Sh NAME .Nm SHA224_Init , .Nm SHA224_Update , .Nm SHA224_Final , .Nm SHA224_End , .Nm SHA224_File , .Nm SHA224_FileChunk , .Nm SHA224_Data , .Nm SHA256_Init , .Nm SHA256_Update , .Nm SHA256_Final , .Nm SHA256_End , .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_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_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') .Tn 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 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 2 +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 .Tn 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. Index: head/lib/libmd/sha512.3 =================================================================== --- head/lib/libmd/sha512.3 (revision 348071) +++ head/lib/libmd/sha512.3 (revision 348072) @@ -1,212 +1,232 @@ .\" .\" ---------------------------------------------------------------------------- .\" "THE BEER-WARE LICENSE" (Revision 42): .\" 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 July 20, 2018 +.Dd May 21, 2019 .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_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_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') .Tn 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_ 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 bits 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') .Tn ASCII string which represents the 384 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') .Tn 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 2 +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 .Tn 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. Index: head/lib/libmd/skein.3 =================================================================== --- head/lib/libmd/skein.3 (revision 348071) +++ head/lib/libmd/skein.3 (revision 348072) @@ -1,216 +1,236 @@ .\"- .\" Copyright (c) 2016 Allan Jude .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" -.Dd May 28, 2016 +.Dd May 21, 2019 .Dt SKEIN 3 .Os .Sh NAME .Nm SKEIN256_Init , .Nm SKEIN256_Update , .Nm SKEIN256_Final , .Nm SKEIN256_End , .Nm SKEIN256_File , .Nm SKEIN256_FileChunk , .Nm SKEIN256_Data , .Nm SKEIN512_Init , .Nm SKEIN512_Update , .Nm SKEIN512_Final , .Nm SKEIN512_End , .Nm SKEIN512_File , .Nm SKEIN512_FileChunk , .Nm SKEIN512_Data , .Nm SKEIN1024_Init , .Nm SKEIN1024_Update , .Nm SKEIN1024_Final , .Nm SKEIN1024_End , .Nm SKEIN1024_File , .Nm SKEIN1024_FileChunk , .Nm SKEIN1024_Data .Nd calculate the ``SKEIN'' family of message digests .Sh LIBRARY .Lb libmd .Sh SYNOPSIS .In sys/types.h .In skein.h .Ft void .Fn SKEIN256_Init "SKEIN256_CTX *context" .Ft void .Fn SKEIN256_Update "SKEIN256_CTX *context" "const unsigned char *data" "size_t len" .Ft void .Fn SKEIN256_Final "unsigned char digest[32]" "SKEIN256_CTX *context" .Ft "char *" .Fn SKEIN256_End "SKEIN256_CTX *context" "char *buf" .Ft "char *" .Fn SKEIN256_File "const char *filename" "char *buf" .Ft "char *" .Fn SKEIN256_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" .Ft "char *" .Fn SKEIN256_Data "const unsigned char *data" "unsigned int len" "char *buf" .Ft void .Fn SKEIN512_Init "SKEIN512_CTX *context" .Ft void .Fn SKEIN512_Update "SKEIN512_CTX *context" "const unsigned char *data" "size_t len" .Ft void .Fn SKEIN512_Final "unsigned char digest[64]" "SKEIN512_CTX *context" .Ft "char *" .Fn SKEIN512_End "SKEIN512_CTX *context" "char *buf" .Ft "char *" .Fn SKEIN512_File "const char *filename" "char *buf" .Ft "char *" .Fn SKEIN512_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" .Ft "char *" .Fn SKEIN512_Data "const unsigned char *data" "unsigned int len" "char *buf" .Ft void .Fn SKEIN1024_Init "SKEIN1024_CTX *context" .Ft void .Fn SKEIN1024_Update "SKEIN1024_CTX *context" "const unsigned char *data" "size_t len" .Ft void .Fn SKEIN1024_Final "unsigned char digest[128]" "SKEIN1024_CTX *context" .Ft "char *" .Fn SKEIN1024_End "SKEIN1024_CTX *context" "char *buf" .Ft "char *" .Fn SKEIN1024_File "const char *filename" "char *buf" .Ft "char *" .Fn SKEIN1024_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" .Ft "char *" .Fn SKEIN1024_Data "const unsigned char *data" "unsigned int len" "char *buf" .Sh DESCRIPTION .Li Skein is a new family of cryptographic hash functions based on the .Li Threefish large-block cipher. Its design combines speed, security, simplicity, and a great deal of flexibility in a modular package that is easy to analyze. .Li Skein is defined for three different internal state sizes\(em256 bits, 512 bits, and 1024 bits\(emand any output size. This allows Skein to be a drop-in replacement for the entire SHA family of hash functions. .Pp The .Fn SKEIN256_Init , .Fn SKEIN256_Update , and .Fn SKEIN256_Final functions are the core functions. Allocate an .Vt SKEIN256_CTX , initialize it with .Fn SKEIN256_Init , run over the data with .Fn SKEIN256_Update , and finally extract the result using .Fn SKEIN256_Final , which will also erase the .Vt SKEIN256_CTX . .Pp .Fn SKEIN256_End is a wrapper for .Fn SKEIN256_Final which converts the return value to a 33-character (including the terminating '\e0') .Tn ASCII string which represents the 256 bits in hexadecimal. .Pp .Fn SKEIN256_File calculates the digest of a file, and uses .Fn SKEIN256_End to return the result. If the file cannot be opened, a null pointer is returned. .Fn SKEIN256_FileChunk is similar to .Fn SKEIN256_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 SKEIN256_FileChunk calculates the digest from .Fa offset to the end of file. .Fn SKEIN256_Data calculates the digest of a chunk of data in memory, and uses .Fn SKEIN256_End to return the result. .Pp When using .Fn SKEIN256_End , .Fn SKEIN256_File , or .Fn SKEIN256_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 33 characters of buffer space. .Pp The .Li SKEIN512_ and .Li SKEIN1024_ functions are similar to the .Li SKEIN256_ functions except they produce a 512-bit, 65 character, or 1024-bit, 129 character, output. +.Sh ERRORS +The +.Fn SKEIN256_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 SKEIN256_File +and +.Fn SKEIN256_FileChunk +may return NULL when underlying +.Xr open 2 , +.Xr fstat 2 , +.Xr lseek 2 , +or +.Xr SKEIN256_End 2 +fail. .Sh SEE ALSO .Xr md4 3 , .Xr md5 3 , .Xr ripemd 3 , .Xr sha 3 , .Xr sha256 3 , .Xr sha512 3 .Sh HISTORY These functions appeared in .Fx 11.0 . .Sh AUTHORS .An -nosplit The core hash routines were imported from version 1.3 of the optimized Skein reference implementation written by .An Doug Whiting as submitted to the NSA SHA-3 contest. The algorithms were developed by .An Niels Ferguson , .An Stefan Lucks , .An Bruce Schneier , .An Doug Whiting , .An Mihir Bellare , .An Tadayoshi Kohno , .An Jon Callas, and .An Jesse Walker .