diff --git a/src/lib/libc/hash/mdX.3 b/src/lib/libc/hash/mdX.3 new file mode 100644 index 00000000..cb6f0550 --- /dev/null +++ b/src/lib/libc/hash/mdX.3 @@ -0,0 +1,184 @@ +.\" +.\" ---------------------------------------------------------------------------- +.\" "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 +.\" ---------------------------------------------------------------------------- +.\" +.\" $OpenBSD: mdX.3,v 1.1 2004/04/28 16:55:46 millert Exp $ +.\" +.Dd October 9, 1996 +.Dt MDX 3 +.Os +.Sh NAME +.Nm MDXInit , +.Nm MDXUpdate , +.Nm MDXFinal , +.Nm MDXTransform , +.Nm MDXEnd , +.Nm MDXFile , +.Nm MDXData +.Nd calculate the RSA Data Security, Inc., ``MDX'' message digest +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Ft void +.Fn MDXInit "MDX_CTX *context" +.Ft void +.Fn MDXUpdate "MDX_CTX *context" "const unsigned char *data" "unsigned int len" +.Ft void +.Fn MDXFinal "u_int8_t digest[MDX_DIGEST_LENGTH]" "MDX_CTX *context" +.Ft void +.Fn MDXTransform "u_int32_t state[4]" "u_int8_t block[MDX_BLOCK_LENGTH]" +.Ft "char *" +.Fn MDXEnd "MDX_CTX *context" "char buf[MDX_DIGEST_STRING_LENGTH]" +.Ft "char *" +.Fn MDXFile "char *filename" "char buf[MDX_DIGEST_STRING_LENGTH]" +.Ft "char *" +.Fn MDXData "const u_int8_t *data" "unsigned int len" "char buf[MDX_DIGEST_STRING_LENGTH]" +.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 doesn't disclose the actual input. +.Pp +MD4 has been broken; it should only be used where necessary for +backward compatibility. +MD5 has not yet (1999-02-11) been broken, but recent attacks have cast +some doubt on its security properties. +The attacks on both MD4 and MD5 +are both in the nature of finding +.Dq collisions +\- 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 MDX_CTX, initialize it with +.Fn MDXInit , +run over the data with +.Fn MDXUpdate , +and finally extract the result using +.Fn MDXFinal . +When a null pointer is passed to +.Fn MDXFinal +as first argument only the final padding will be applied and the +current context can still be used with +.Fn MDXUpdate . +.Pp +The +.Fn MDXTransform +function is used by +.Fn MDXUpdate +to hash 512-bit blocks and forms the core of the algorithm. +Most programs should use the interface provided by +.Fn MDXInit , +.Fn MDXUpdate +and +.Fn MDXFinal +instead of calling +.Fn MDXTransform +directly. +.Pp +.Fn MDXEnd +is a wrapper for +.Fn MDXFinal +which converts the return value to an MDX_DIGEST_STRING_LENGTH-character +(including the terminating '\e0') +.Tn ASCII +string which represents the 128 bits in hexadecimal. +.Pp +.Fn MDXFile +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. +.Fn MDXData +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 +.Ar 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 +.Ar buf +argument is non-null it must point to at least MDX_DIGEST_STRING_LENGTH +characters of buffer space. +.Sh SEE ALSO +.Xr mdY 3 , +.Xr rmd160 3 , +.Xr sha1, 3 +.Xr sha2 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 RSA Laboratories +.%T Frequently Asked Questions About today's Cryptography +.%O \& +.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 MD4 and MD5 +.%J RSA Laboratories Bulletin +.%N 4 +.%D November 12, 1996 +.Re +.Rs +.%A Hans Dobbertin +.%T Cryptanalysis of MD5 Compress +.Re +.Sh HISTORY +These functions appeared in +.Ox 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 from a public domain implementation by Colin Plumb. +.Pp +The +.Fn MDXEnd , +.Fn MDXFile , +and +.Fn MDXData +helper functions were written by Poul-Henning Kamp. +.Sh BUGS +Hans Dobbertin has shown collisions for the full version of MD4 and +found a collision in the compress function of MD5. +The use of SHA or RIPEMD-160 is recommended instead.