libutil: md5 functions.

man/man3/Makefile

@@ -12,7 +12,7 @@ MAN=	abort.3 abs.3 assert.3 atof.3 bstring.3 configfile.3 \
 	readv.3 realpath.3 regex.3 remainder.3 resolver.3 scanf.3 \
 	servxcheck.3 setbuf.3 setjmp.3 sigset.3 sleep.3 stdarg.3 \
 	stdio.3 string.3 strtol.3 syslog.3 system.3 termcap.3 \
-	termios.3 time2posix.3 ttyname.3 ttyslot.3 ungetc.3 fetch.3
+	termios.3 time2posix.3 ttyname.3 ttyslot.3 ungetc.3 fetch.3 md5.3
 
 .include <bsd.man.mk>
 .include <bsd.subdir.mk>

man/man3/md5.3

@@ -0,0 +1,130 @@
+.\"
+.\" ----------------------------------------------------------------------------
+.\" "THE BEER-WARE LICENSE" (Revision 42):
+.\" <phk@login.dkuug.dk> 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: md5.3,v 1.10 2007/05/31 19:19:29 jmc Exp $
+.\"
+.Dd $Mdocdate: May 31 2007 $
+.Dt MD5 3
+.Os
+.Sh NAME
+.Nm MD5Init ,
+.Nm MD5Update ,
+.Nm MD5Final ,
+.Nm MD5End ,
+.Nm MD5File ,
+.Nm MD5Data
+.Nd calculate the RSA Data Security, Inc., ``MD5'' message digest
+.Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <minix/md5.h>
+.Ft void
+.Fn MD5Init "MD5_CTX *context"
+.Ft void
+.Fn MD5Update "MD5_CTX *context" "const u_int8_t *data" "size_t len"
+.Ft void
+.Fn MD5Final "u_int8_t digest[MD5_DIGEST_LENGTH]" "MD5_CTX *context"
+.Ft "char *"
+.Fn MD5End "MD5_CTX *context" "char *buf"
+.Ft "char *"
+.Fn MD5File "const char *filename" "char *buf"
+.Ft "char *"
+.Fn MD5Data "const u_int8_t *data" "size_t len" "char *buf"
+.Sh DESCRIPTION
+The MD5 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
+The
+.Fn MD5Init ,
+.Fn MD5Update ,
+and
+.Fn MD5Final
+functions are the core functions.
+Allocate an MD5_CTX, initialize it with
+.Fn MD5Init ,
+run over the data with
+.Fn MD5Update ,
+and finally extract the result using
+.Fn MD5Final .
+.Pp
+.Fn MD5End
+is a wrapper for
+.Fn MD5Final
+which converts the return value to an MD5_DIGEST_STRING_LENGTH-character
+(including the terminating '\e0')
+.Tn ASCII
+string which represents the 128 bits in hexadecimal.
+.Pp
+.Fn MD5File
+calculates the digest of a file, and uses
+.Fn MD5End
+to return the result.
+If the file cannot be opened, a null pointer is returned.
+.Pp
+.Fn MD5Data
+calculates the digest of a chunk of data in memory, and uses
+.Fn MD5End
+to return the result.
+.Pp
+When using
+.Fn MD5End ,
+.Fn MD5File ,
+or
+.Fn MD5Data ,
+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 MD5_DIGEST_STRING_LENGTH
+characters of buffer space.
+.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 \&<http://www.rsa.com/rsalabs/faq/>
+.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 BUGS
+Collisions have been found for the full version of MD5.