1.\" 2.\" Copyright (c) 2000 Poul-Henning Kamp <phk@FreeBSD.org> 3.\" 4.\" Permission to use, copy, modify, and distribute this software for any 5.\" purpose with or without fee is hereby granted, provided that the above 6.\" copyright notice and this permission notice appear in all copies. 7.\" 8.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 9.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 10.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 11.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 12.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 13.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 14.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 15.\" 16.\" If we meet some day, and you think this stuff is worth it, you 17.\" can buy me a beer in return. Poul-Henning Kamp 18.\" 19.\" $OpenBSD: MD5Init.3,v 1.2 2019/12/05 21:45:05 jmc Exp $ 20.\" 21.Dd $Mdocdate: December 5 2019 $ 22.Dt MD5INIT 3 23.Os 24.Sh NAME 25.Nm MD5Init , 26.Nm MD5Update , 27.Nm MD5Pad , 28.Nm MD5Final , 29.Nm MD5Transform , 30.Nm MD5End , 31.Nm MD5File , 32.Nm MD5FileChunk , 33.Nm MD5Data 34.Nd calculate MD5 message digest 35.Sh SYNOPSIS 36.In sys/types.h 37.In md5.h 38.Ft void 39.Fn MD5Init "MD5_CTX *context" 40.Ft void 41.Fn MD5Update "MD5_CTX *context" "const u_int8_t *data" "size_t len" 42.Ft void 43.Fn MD5Pad "MD5_CTX *context" 44.Ft void 45.Fn MD5Final "u_int8_t digest[MD5_DIGEST_LENGTH]" "MD5_CTX *context" 46.Ft void 47.Fn MD5Transform "u_int32_t state[4]" "u_int8_t block[MD5_BLOCK_LENGTH]" 48.Ft "char *" 49.Fn MD5End "MD5_CTX *context" "char *buf" 50.Ft "char *" 51.Fn MD5File "const char *filename" "char *buf" 52.Ft "char *" 53.Fn MD5FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" 54.Ft "char *" 55.Fn MD5Data "const u_int8_t *data" "size_t len" "char *buf" 56.Sh DESCRIPTION 57The MD5 functions calculate a 128-bit cryptographic checksum (digest) 58for any number of input bytes. 59A cryptographic checksum is a one-way 60hash-function, that is, you cannot find (except by exhaustive search) 61the input corresponding to a particular output. 62This net result is a 63.Dq fingerprint 64of the input-data, which doesn't disclose the actual input. 65.Pp 66MD5 has been broken; it should only be used where necessary for 67backward compatibility. 68The attack on MD5 is in the nature of finding 69.Dq collisions 70\(em that is, multiple inputs which hash to the same value. 71It is still unlikely for an attacker to be able to determine the exact 72original input given a hash value. 73.Pp 74The 75.Fn MD5Init , 76.Fn MD5Update , 77and 78.Fn MD5Final 79functions are the core functions. 80Allocate an 81.Vt MD5_CTX , 82initialize it with 83.Fn MD5Init , 84run over the data with 85.Fn MD5Update , 86and finally extract the result using 87.Fn MD5Final . 88.Pp 89The 90.Fn MD5Pad 91function can be used to apply padding to the message digest as in 92.Fn MD5Final , 93but the current context can still be used with 94.Fn MD5Update . 95.Pp 96The 97.Fn MD5Transform 98function is used by 99.Fn MD5Update 100to hash 512-bit blocks and forms the core of the algorithm. 101Most programs should use the interface provided by 102.Fn MD5Init , 103.Fn MD5Update 104and 105.Fn MD5Final 106instead of calling 107.Fn MD5Transform 108directly. 109.Pp 110.Fn MD5End 111is a wrapper for 112.Fn MD5Final 113which converts the return value to an MD5_DIGEST_STRING_LENGTH-character 114(including the terminating '\e0') 115ASCII string which represents the 128 bits in hexadecimal. 116.Pp 117.Fn MD5File 118calculates the digest of a file, and uses 119.Fn MD5End 120to return the result. 121If the file cannot be opened, a null pointer is returned. 122.Pp 123.Fn MD5FileChunk 124behaves like 125.Fn MD5File 126but calculates the digest only for that portion of the file starting at 127.Fa offset 128and continuing for 129.Fa length 130bytes or until end of file is reached, whichever comes first. 131A zero 132.Fa length 133can be specified to read until end of file. 134A negative 135.Fa length 136or 137.Fa offset 138will be ignored. 139.Fn MD5Data 140calculates the digest of a chunk of data in memory, and uses 141.Fn MD5End 142to return the result. 143.Pp 144When using 145.Fn MD5End , 146.Fn MD5File , 147.Fn MD5FileChunk , 148or 149.Fn MD5Data , 150the 151.Ar buf 152argument can be a null pointer, in which case the returned string 153is allocated with 154.Xr malloc 3 155and subsequently must be explicitly deallocated using 156.Xr free 3 157after use. 158If the 159.Ar buf 160argument is non-null it must point to at least MD5_DIGEST_STRING_LENGTH 161characters of buffer space. 162.Sh SEE ALSO 163.Xr cksum 1 , 164.Xr md5 1 , 165.Xr RMD160Init 3 , 166.Xr SHA1Init 3 , 167.Xr SHA256Init 3 168.Rs 169.%A H. Dobbertin 170.%D 1995 171.%J CryptoBytes 172.%N 1(3):5 173.%T Alf Swindles Ann 174.Re 175.Rs 176.%A MJ. B. Robshaw 177.%D November 12, 1996 178.%J RSA Laboratories Bulletin 179.%N 4 180.%T On Recent Results for MD4 and MD5 181.Re 182.Rs 183.%A Hans Dobbertin 184.%T Cryptanalysis of MD5 Compress 185.Re 186.Sh STANDARDS 187.Rs 188.%A R. Rivest 189.%D April 1992 190.%R RFC 1321 191.%T The MD5 Message Digest Algorithm 192.Re 193.Sh HISTORY 194These functions appeared in 195.Ox 2.0 . 196.Sh AUTHORS 197.An -nosplit 198The original MD5 routines were developed by 199RSA Data Security, Inc., and published in the above references. 200This code is derived from a public domain implementation written by 201.An Colin Plumb . 202.Pp 203The 204.Fn MD5End , 205.Fn MD5File , 206.Fn MD5FileChunk , 207and 208.Fn MD5Data 209helper functions are derived from code written by 210.An Poul-Henning Kamp . 211.Sh BUGS 212Collisions have been found for the full version of MD5. 213The use of the SHA2 functions is recommended instead. 214