libutil: md5 functions.

2010-07-16 00:06:00 +00:00 · 2010-07-16 00:06:00 +00:00 · 117bac1e2d
commit 117bac1e2d
parent 6c66933f90
5 changed files with 669 additions and 1 deletions
--- a/include/minix/md5.h
+++ b/include/minix/md5.h
@ -0,0 +1,54 @@
+/*	$NetBSD: md5.h,v 1.5 2008/10/08 14:28:14 joerg Exp $	*/
+
+/*
+ * This file is derived from the RSA Data Security, Inc. MD5 Message-Digest
+ * Algorithm and has been modified by Jason R. Thorpe <thorpej@NetBSD.ORG>
+ * for portability and formatting.
+ */
+
+/*
+ * Copyright (C) 1991-2, RSA Data Security, Inc. Created 1991. All
+ * rights reserved.
+ *
+ * License to copy and use this software is granted provided that it
+ * is identified as the "RSA Data Security, Inc. MD5 Message-Digest
+ * Algorithm" in all material mentioning or referencing this software
+ * or this function.
+ * 
+ * License is also granted to make and use derivative works provided
+ * that such works are identified as "derived from the RSA Data
+ * Security, Inc. MD5 Message-Digest Algorithm" in all material
+ * mentioning or referencing the derived work.
+ * 
+ * RSA Data Security, Inc. makes no representations concerning either
+ * the merchantability of this software or the suitability of this
+ * software for any particular purpose. It is provided "as is"
+ * without express or implied warranty of any kind.
+ * 
+ * These notices must be retained in any copies of any part of this
+ * documentation and/or software.
+ */
+
+#ifndef _NBCOMPAT_SYS_MD5_H_
+#define _NBCOMPAT_SYS_MD5_H_
+
+#include <stdint.h>
+
+#define MD5_DIGEST_LENGTH		16
+#define MD5_DIGEST_STRING_LENGTH	33
+
+/* MD5 context. */
+typedef struct MD5Context {
+	uint32_t state[4];	/* state (ABCD) */
+	uint32_t count[2];	/* number of bits, modulo 2^64 (lsb first) */
+	unsigned char buffer[64]; /* input buffer */
+} MD5_CTX;
+
+void	MD5Init(MD5_CTX *);
+void	MD5Update(MD5_CTX *, const unsigned char *, unsigned int);
+void	MD5Final(unsigned char[16], MD5_CTX *);
+char	*MD5End(MD5_CTX *, char *);
+char	*MD5File(const char *, char *);
+char	*MD5Data(const unsigned char *, unsigned int, char *);
+
+#endif /* !_NBCOMPAT_SYS_MD5_H_ */
--- a/lib/libutil/md5c.c
+++ b/lib/libutil/md5c.c
@ -0,0 +1,379 @@
+/*	$NetBSD: md5c.c,v 1.7 2008/10/06 12:36:20 joerg Exp $	*/
+
+/*
+ * This file is derived from the RSA Data Security, Inc. MD5 Message-Digest
+ * Algorithm and has been modified by Jason R. Thorpe <thorpej@NetBSD.org>
+ * for portability and formatting.
+ */
+
+/*
+ * Copyright (C) 1991-2, RSA Data Security, Inc. Created 1991. All
+ * rights reserved.
+ *
+ * License to copy and use this software is granted provided that it
+ * is identified as the "RSA Data Security, Inc. MD5 Message-Digest
+ * Algorithm" in all material mentioning or referencing this software
+ * or this function.
+ *
+ * License is also granted to make and use derivative works provided
+ * that such works are identified as "derived from the RSA Data
+ * Security, Inc. MD5 Message-Digest Algorithm" in all material
+ * mentioning or referencing the derived work.
+ *
+ * RSA Data Security, Inc. makes no representations concerning either
+ * the merchantability of this software or the suitability of this
+ * software for any particular purpose. It is provided "as is"
+ * without express or implied warranty of any kind.
+ *
+ * These notices must be retained in any copies of any part of this
+ * documentation and/or software.
+ */
+
+#if defined(_KERNEL) || defined(_STANDALONE)
+#include <lib/libkern/libkern.h>
+#include <sys/param.h>
+#include <sys/md5.h>
+#define _DIAGASSERT(x)	(void)0
+#else
+#if 0
+#include "namespace.h"
+#endif
+#include <sys/types.h>
+#include <assert.h>
+#include <string.h>
+#include <minix/md5.h>
+#endif /* _KERNEL || _STANDALONE */
+
+#if HAVE_NBTOOL_CONFIG_H
+#include "nbtool_config.h"
+#endif
+
+#ifndef __minix
+#if defined(HAVE_MEMSET)
+#define ZEROIZE(d, l)		memset((d), 0, (l)) 
+#else 
+# if defined(HAVE_BZERO)
+#define ZEROIZE(d, l)		bzero((d), (l))
+# else
+#error You need either memset or bzero 
+# endif 
+#endif
+#else
+#define ZEROIZE(d, l)		memset((d), 0, (l)) 
+#endif
+
+#define _DIAGASSERT assert
+
+typedef unsigned char *POINTER;
+typedef uint16_t UINT2;
+typedef uint32_t UINT4;
+
+/*
+ * Constants for MD5Transform routine.
+ */
+#define S11 7
+#define S12 12
+#define S13 17
+#define S14 22
+#define S21 5
+#define S22 9
+#define S23 14
+#define S24 20
+#define S31 4
+#define S32 11
+#define S33 16
+#define S34 23
+#define S41 6
+#define S42 10
+#define S43 15
+#define S44 21
+
+#if 0
+#if !defined(_KERNEL) && !defined(_STANDALONE) && defined(__weak_alias)
+__weak_alias(MD5Init,_MD5Init)
+__weak_alias(MD5Update,_MD5Update)
+__weak_alias(MD5Final,_MD5Final)
+#endif
+#endif
+
+static void MD5Transform __P((UINT4 [4], const unsigned char [64]));
+
+static void Encode __P((unsigned char *, UINT4 *, unsigned int));
+static void Decode __P((UINT4 *, const unsigned char *, unsigned int));
+
+/*
+ * Encodes input (UINT4) into output (unsigned char).  Assumes len is
+ * a multiple of 4.
+ */
+static void
+Encode (output, input, len)
+	unsigned char *output;
+	UINT4 *input;
+	unsigned int len;
+{
+	unsigned int i, j;
+
+	for (i = 0, j = 0; j < len; i++, j += 4) {
+		output[j] = (unsigned char)(input[i] & 0xff);
+		output[j+1] = (unsigned char)((input[i] >> 8) & 0xff);
+		output[j+2] = (unsigned char)((input[i] >> 16) & 0xff);
+		output[j+3] = (unsigned char)((input[i] >> 24) & 0xff);
+	}
+}
+
+/*
+ * Decodes input (unsigned char) into output (UINT4).  Assumes len is
+ * a multiple of 4.
+ */
+static void
+Decode (output, input, len)
+	UINT4 *output;
+	const unsigned char *input;
+	unsigned int len;
+{
+	unsigned int i, j;
+
+	for (i = 0, j = 0; j < len; i++, j += 4)
+		output[i] = ((UINT4)input[j]) | (((UINT4)input[j+1]) << 8) |
+		    (((UINT4)input[j+2]) << 16) | (((UINT4)input[j+3]) << 24);
+}
+
+static const unsigned char PADDING[64] = {
+	0x80, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+	0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+	0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
+};
+
+/*
+ * F, G, H and I are basic MD5 functions.
+ */
+#define F(x, y, z)	(((x) & (y)) | ((~x) & (z)))
+#define G(x, y, z)	(((x) & (z)) | ((y) & (~z)))
+#define H(x, y, z)	((x) ^ (y) ^ (z))
+#define I(x, y, z)	((y) ^ ((x) | (~z)))
+
+/*
+ * ROTATE_LEFT rotates x left n bits.
+ */
+#define ROTATE_LEFT(x, n)	(((x) << (n)) | ((x) >> (32-(n))))
+
+/*
+ * FF, GG, HH, and II transformations for rounds 1, 2, 3, and 4.
+ * Rotation is separate from addition to prevent recomputation.
+ */
+#define FF(a, b, c, d, x, s, ac) { \
+	(a) += F ((b), (c), (d)) + (x) + (UINT4)(ac); \
+	(a) = ROTATE_LEFT ((a), (s)); \
+	(a) += (b); \
+}
+
+#define GG(a, b, c, d, x, s, ac) { \
+	(a) += G ((b), (c), (d)) + (x) + (UINT4)(ac); \
+	(a) = ROTATE_LEFT ((a), (s)); \
+	(a) += (b); \
+}
+
+#define HH(a, b, c, d, x, s, ac) { \
+	(a) += H ((b), (c), (d)) + (x) + (UINT4)(ac); \
+	(a) = ROTATE_LEFT ((a), (s)); \
+	(a) += (b); \
+}
+
+#define II(a, b, c, d, x, s, ac) { \
+	(a) += I ((b), (c), (d)) + (x) + (UINT4)(ac); \
+	(a) = ROTATE_LEFT ((a), (s)); \
+	(a) += (b); \
+}
+
+/*
+ * MD5 initialization. Begins an MD5 operation, writing a new context.
+ */
+void
+MD5Init(context)
+	MD5_CTX *context;		/* context */
+{
+
+	_DIAGASSERT(context != 0);
+
+	context->count[0] = context->count[1] = 0;
+
+	/* Load magic initialization constants. */
+	context->state[0] = 0x67452301;
+	context->state[1] = 0xefcdab89;
+	context->state[2] = 0x98badcfe;
+	context->state[3] = 0x10325476;
+}
+
+/*
+ * MD5 block update operation.  Continues an MD5 message-digest
+ * operation, processing another message block, and updating the
+ * context.
+ */
+void
+MD5Update(context, input, inputLen)
+	MD5_CTX *context;		/* context */
+	const unsigned char *input;	/* input block */
+	unsigned int inputLen;		/* length of input block */
+{
+	unsigned int i, idx, partLen;
+
+	_DIAGASSERT(context != 0);
+	_DIAGASSERT(input != 0);
+
+	/* Compute number of bytes mod 64 */
+	idx = (unsigned int)((context->count[0] >> 3) & 0x3F);
+
+	/* Update number of bits */
+	if ((context->count[0] += ((UINT4)inputLen << 3))
+	    < ((UINT4)inputLen << 3))
+		context->count[1]++;
+	context->count[1] += ((UINT4)inputLen >> 29);
+
+	partLen = 64 - idx;
+
+	/* Transform as many times as possible. */
+	if (inputLen >= partLen) {
+		/* LINTED const castaway ok */
+		memcpy((POINTER)&context->buffer[idx],
+		    (POINTER)input, partLen);
+		MD5Transform(context->state, context->buffer);
+
+		for (i = partLen; i + 63 < inputLen; i += 64)
+			MD5Transform(context->state, &input[i]);
+
+		idx = 0;
+	} else
+		i = 0;
+
+	/* Buffer remaining input */
+	/* LINTED const castaway ok */
+	memcpy((POINTER)&context->buffer[idx], (POINTER)&input[i],
+	    inputLen - i);
+}
+
+/*
+ * MD5 finalization.  Ends an MD5 message-digest operation, writing the
+ * message digest and zeroing the context.
+ */
+void
+MD5Final(digest, context)
+	unsigned char digest[16];	/* message digest */
+	MD5_CTX *context;		/* context */
+{
+	unsigned char bits[8];
+	unsigned int idx, padLen;
+
+	_DIAGASSERT(digest != 0);
+	_DIAGASSERT(context != 0);
+
+	/* Save number of bits */
+	Encode(bits, context->count, 8);
+
+	/* Pad out to 56 mod 64. */
+	idx = (unsigned int)((context->count[0] >> 3) & 0x3f);
+	padLen = (idx < 56) ? (56 - idx) : (120 - idx);
+	MD5Update (context, PADDING, padLen);
+
+	/* Append length (before padding) */
+	MD5Update(context, bits, 8);
+
+	/* Store state in digest */
+	Encode(digest, context->state, 16);
+
+	/* Zeroize sensitive information. */
+	ZEROIZE((POINTER)(void *)context, sizeof(*context));
+}
+
+/*
+ * MD5 basic transformation. Transforms state based on block.
+ */
+static void
+MD5Transform(state, block)
+	UINT4 state[4];
+	const unsigned char block[64];
+{
+	UINT4 a = state[0], b = state[1], c = state[2], d = state[3], x[16];
+
+	Decode(x, block, 64);
+
+	/* Round 1 */
+	FF (a, b, c, d, x[ 0], S11, 0xd76aa478); /* 1 */
+	FF (d, a, b, c, x[ 1], S12, 0xe8c7b756); /* 2 */
+	FF (c, d, a, b, x[ 2], S13, 0x242070db); /* 3 */
+	FF (b, c, d, a, x[ 3], S14, 0xc1bdceee); /* 4 */
+	FF (a, b, c, d, x[ 4], S11, 0xf57c0faf); /* 5 */
+	FF (d, a, b, c, x[ 5], S12, 0x4787c62a); /* 6 */
+	FF (c, d, a, b, x[ 6], S13, 0xa8304613); /* 7 */
+	FF (b, c, d, a, x[ 7], S14, 0xfd469501); /* 8 */
+	FF (a, b, c, d, x[ 8], S11, 0x698098d8); /* 9 */
+	FF (d, a, b, c, x[ 9], S12, 0x8b44f7af); /* 10 */
+	FF (c, d, a, b, x[10], S13, 0xffff5bb1); /* 11 */
+	FF (b, c, d, a, x[11], S14, 0x895cd7be); /* 12 */
+	FF (a, b, c, d, x[12], S11, 0x6b901122); /* 13 */
+	FF (d, a, b, c, x[13], S12, 0xfd987193); /* 14 */
+	FF (c, d, a, b, x[14], S13, 0xa679438e); /* 15 */
+	FF (b, c, d, a, x[15], S14, 0x49b40821); /* 16 */
+
+	/* Round 2 */
+	GG (a, b, c, d, x[ 1], S21, 0xf61e2562); /* 17 */
+	GG (d, a, b, c, x[ 6], S22, 0xc040b340); /* 18 */
+	GG (c, d, a, b, x[11], S23, 0x265e5a51); /* 19 */
+	GG (b, c, d, a, x[ 0], S24, 0xe9b6c7aa); /* 20 */
+	GG (a, b, c, d, x[ 5], S21, 0xd62f105d); /* 21 */
+	GG (d, a, b, c, x[10], S22,  0x2441453); /* 22 */
+	GG (c, d, a, b, x[15], S23, 0xd8a1e681); /* 23 */
+	GG (b, c, d, a, x[ 4], S24, 0xe7d3fbc8); /* 24 */
+	GG (a, b, c, d, x[ 9], S21, 0x21e1cde6); /* 25 */
+	GG (d, a, b, c, x[14], S22, 0xc33707d6); /* 26 */
+	GG (c, d, a, b, x[ 3], S23, 0xf4d50d87); /* 27 */
+	GG (b, c, d, a, x[ 8], S24, 0x455a14ed); /* 28 */
+	GG (a, b, c, d, x[13], S21, 0xa9e3e905); /* 29 */
+	GG (d, a, b, c, x[ 2], S22, 0xfcefa3f8); /* 30 */
+	GG (c, d, a, b, x[ 7], S23, 0x676f02d9); /* 31 */
+	GG (b, c, d, a, x[12], S24, 0x8d2a4c8a); /* 32 */
+
+	/* Round 3 */
+	HH (a, b, c, d, x[ 5], S31, 0xfffa3942); /* 33 */
+	HH (d, a, b, c, x[ 8], S32, 0x8771f681); /* 34 */
+	HH (c, d, a, b, x[11], S33, 0x6d9d6122); /* 35 */
+	HH (b, c, d, a, x[14], S34, 0xfde5380c); /* 36 */
+	HH (a, b, c, d, x[ 1], S31, 0xa4beea44); /* 37 */
+	HH (d, a, b, c, x[ 4], S32, 0x4bdecfa9); /* 38 */
+	HH (c, d, a, b, x[ 7], S33, 0xf6bb4b60); /* 39 */
+	HH (b, c, d, a, x[10], S34, 0xbebfbc70); /* 40 */
+	HH (a, b, c, d, x[13], S31, 0x289b7ec6); /* 41 */
+	HH (d, a, b, c, x[ 0], S32, 0xeaa127fa); /* 42 */
+	HH (c, d, a, b, x[ 3], S33, 0xd4ef3085); /* 43 */
+	HH (b, c, d, a, x[ 6], S34,  0x4881d05); /* 44 */
+	HH (a, b, c, d, x[ 9], S31, 0xd9d4d039); /* 45 */
+	HH (d, a, b, c, x[12], S32, 0xe6db99e5); /* 46 */
+	HH (c, d, a, b, x[15], S33, 0x1fa27cf8); /* 47 */
+	HH (b, c, d, a, x[ 2], S34, 0xc4ac5665); /* 48 */
+
+	/* Round 4 */
+	II (a, b, c, d, x[ 0], S41, 0xf4292244); /* 49 */
+	II (d, a, b, c, x[ 7], S42, 0x432aff97); /* 50 */
+	II (c, d, a, b, x[14], S43, 0xab9423a7); /* 51 */
+	II (b, c, d, a, x[ 5], S44, 0xfc93a039); /* 52 */
+	II (a, b, c, d, x[12], S41, 0x655b59c3); /* 53 */
+	II (d, a, b, c, x[ 3], S42, 0x8f0ccc92); /* 54 */
+	II (c, d, a, b, x[10], S43, 0xffeff47d); /* 55 */
+	II (b, c, d, a, x[ 1], S44, 0x85845dd1); /* 56 */
+	II (a, b, c, d, x[ 8], S41, 0x6fa87e4f); /* 57 */
+	II (d, a, b, c, x[15], S42, 0xfe2ce6e0); /* 58 */
+	II (c, d, a, b, x[ 6], S43, 0xa3014314); /* 59 */
+	II (b, c, d, a, x[13], S44, 0x4e0811a1); /* 60 */
+	II (a, b, c, d, x[ 4], S41, 0xf7537e82); /* 61 */
+	II (d, a, b, c, x[11], S42, 0xbd3af235); /* 62 */
+	II (c, d, a, b, x[ 2], S43, 0x2ad7d2bb); /* 63 */
+	II (b, c, d, a, x[ 9], S44, 0xeb86d391); /* 64 */
+
+	state[0] += a;
+	state[1] += b;
+	state[2] += c;
+	state[3] += d;
+
+	/* Zeroize sensitive information. */
+	ZEROIZE((POINTER)(void *)x, sizeof (x));
+}
+
--- a/lib/libutil/md5hl.c
+++ b/lib/libutil/md5hl.c
@ -0,0 +1,105 @@
+/*	$NetBSD: mdXhl.c,v 1.2 2008/10/06 12:36:20 joerg Exp $	*/
+
+/*
+ * ----------------------------------------------------------------------------
+ * "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
+ * ----------------------------------------------------------------------------
+ *
+ * from FreeBSD Id: mdXhl.c,v 1.8 1996/10/25 06:48:12 bde Exp
+ */
+
+/*
+ * Modifed April 29, 1997 by Jason R. Thorpe <thorpej@NetBSD.org>
+ */
+
+#include <sys/types.h>
+
+#include <assert.h>
+#include <fcntl.h>
+#include <errno.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <sys/cdefs.h>
+#include <minix/md5.h>
+
+#define MDALGORITHM MD5
+#define	CONCAT(x,y)	__CONCAT(x,y)
+#define	MDNAME(x)	CONCAT(MDALGORITHM,x)
+
+#define _DIAGASSERT assert
+
+char *
+MDNAME(End)(ctx, buf)
+	MDNAME(_CTX) *ctx;
+	char *buf;
+{
+	int i;
+	unsigned char digest[16];
+	static const char hex[]="0123456789abcdef";
+
+	_DIAGASSERT(ctx != 0);
+
+	if (buf == NULL)
+		buf = malloc(33);
+	if (buf == NULL)
+		return (NULL);
+
+	MDNAME(Final)(digest, ctx);
+
+	for (i = 0; i < 16; i++) {
+		buf[i+i] = hex[(uint32_t)digest[i] >> 4];
+		buf[i+i+1] = hex[digest[i] & 0x0f];
+	}
+
+	buf[i+i] = '\0';
+	return (buf);
+}
+
+char *
+MDNAME(File)(filename, buf)
+	const char *filename;
+	char *buf;
+{
+	unsigned char buffer[BUFSIZ];
+	MDNAME(_CTX) ctx;
+	int f, i, j;
+
+	_DIAGASSERT(filename != 0);
+	/* buf may be NULL */
+
+	MDNAME(Init)(&ctx);
+	f = open(filename, O_RDONLY, 0666);
+	if (f < 0)
+		return NULL;
+
+	while ((i = read(f, buffer, sizeof(buffer))) > 0)
+		MDNAME(Update)(&ctx, buffer, (unsigned int)i);
+
+	j = errno;
+	close(f);
+	errno = j;
+
+	if (i < 0)
+		return NULL;
+
+	return (MDNAME(End)(&ctx, buf));
+}
+
+char *
+MDNAME(Data)(data, len, buf)
+	const unsigned char *data;
+	unsigned int len;
+	char *buf;
+{
+	MDNAME(_CTX) ctx;
+
+	_DIAGASSERT(data != 0);
+
+	MDNAME(Init)(&ctx);
+	MDNAME(Update)(&ctx, data, len);
+	return (MDNAME(End)(&ctx, buf));
+}
--- a/man/man3/Makefile
+++ b/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>
--- a/man/man3/md5.3
+++ b/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.