.\" This file is in the public domain. .Dd January 2, 2002 .Dt LIBMD5 3 .Os NetBSD 1.2BETA .Sh NAME .Nm md5_init , .Nm md5_process_bytes , .Nm md5_result , .Nm md5_clone , .Nm md5_state , .Nm md5_set_state , .Nm md5_drop .Nd MD5 hashing routines .Sh SYNOPSIS .Fd #include .br .Nm cc .Op Ar arguments .Fl lmd5 .br .Ft void * .Fn md5_init "void" .Ft void .Fn md5_process_bytes "void *handle" "const void *buf" "unsigned int len" .Ft void .Fn md5_result "void *handle" "unsigned char *resbuf" .Ft void * .Fn md5_clone "const void *handle" .Ft int .Fn md5_state "const void *handle" "void *buf" "int bufsize" .Ft int .Fn md5_set_state "void *handle" "const void *buf" "int bufsize" .Ft void .Fn md5_drop "void *handle" .Sh DESCRIPTION These functions perform MD5 hashing (see RFC 1321). .Pp .Fn md5_init returns a .Sy handle , which is opaque to the caller and must be passed to the other functions. It will normally be the first call made. .Fn md5_init takes no arguments, always either creating and returning a new handle or returning a nil pointer if it couldn't allocate the required memory. Multiple handles may be active at once; each handle is an independent hash-in-progress. .Pp .Fn md5_process_bytes is the way one feeds data into a hash operation. It takes the handle of the hash, a pointer to a buffer holding the data to be hashed, and the number of bytes to be hashed. .Pp .Fn md5_result computes the 128-bit MD5 result, the hash of all bytes that have been fed into the hash operation whose handle is passed in. The result is written into the provided .Fa resbuf , which is assumed to be a 16-byte buffer. The handle is also freed and must never be used again (the MD5 algorithm is such that providing .Dq interim hash values, while not conceptually impossible, is relatively difficult). .Pp .Fn md5_clone clones a hash-in-progress, returning a distinct handle equivalent to the one passed as an argument (or a nil pointer if memory allocation failed) \&- that is, they will function equivalently in further calls. This is equivalent to calling .Fn md5_init again and then .Fn md5_process_bytes on the same sequence of bytes that has already been done on the first handle. However, it should be emphasized that after the .Fn md5_clone call, the two handles are as completely independent as any two distinct handles; they are in no way tied together simply because one was obtained as a clone of the other. .Pp .Fn md5_state returns the internal state of a hash-in-progress as a string of bytes. The argument .Fa buf must be a pointer to a buffer to hold the state. .Fa bufsize must be the size of the buffer .Fa buf . The return value is the number of bytes .Fn md5_state would like to place in .Fa buf . If this is no greater than .Fa bufsize , then the returned state is complete and can be used in a later call to .Fn md5_set_state (with .Fa bufsize set to the returned value, if this differs from the value passed to .Fn md5_state ) ; otherwise, .Fa buf ' Ns s contents are indeterminate. If .Fa bufsize is zero, .Fa buf need not be a valid pointer, but the return value is still accurate; this is a simple and fast way to tell how much space to allocate for .Fa buf . The amount of space required may vary, but the library promises that allocating as much space as called for by the return value will always work for a subsequent call, provided no further data are processed on that handle in between. .Pp .Fn md5_set_state takes a pointer to an existing .Fa handle and buffer parameters like .Fa md5_state ' Ns s , and loads the state into the hash-in-progress. If the state shows evidence of having been corrupted, or if it's from an unrecognized version of the library, the call fails, and the return value will be one of these nonzero manifest constants: .Bl -tag -width indent .It Dv MD5_BADVERS The library version number is wrong. .It Dv MD5_CORRUPT The state has been corrupted. Not all corruption will be detected, though some common forms of corruption are checked for. If undetected corruption occurs, the library promises that it will not crash as a result, but the resulting hashes may be garbage (and not necessarily equivalent to any uncorrupted sequence of calls). An bufsize value that is too small counts as corruption; however, it can be larger without harm. .El (This list may grow with future versions; code should be prepared for return values not listed here.) The return value is zero if all goes well. Note that the .Fa bufsize argument to .Fa md5_set_state must be the value returned by the previous .Fa md5_state call, rather than the .Fa bufsize passed to it, if they differ. .Pp .Fn md5_drop discards a hash-in-progress without computing a final hash or storing it anywhere. It is slightly more efficient than calling .Fn md5_result and ignoring the resulting hash, but semantically equivalent. .Sh ERRORS If .Fn md5_init or .Fn md5_clone cannot allocate enough memory for a new handle, it returns a nil pointer. This is the only failure condition possible for it, assuming .Xr malloc 3 conforms to its interface correctly. .Fn md5_process_bytes , .Fn md5_result , .Fn md5_state , .Fn md5_set_state , and .Fn md5_drop .Dq cannot fail ; the only failure modes possible for them are due to passing an invalid handle pointer or data buffer (or due to the malloc arena being corrupted such that .Xr free 3 fails, for .Fn md5_result and .Fn md5_drop ) . Such incorrect calls will not be detected by the MD5 library itself; the effects can range from incorrect hashes to core dumps to silent corruption of memory. .Sh BUGS No provision is made for hashing a number of bits that is not an exact number of bytes. .Pp Code blindly assumes 8-bit .Do char .Dc Ns s. .Sh AUTHOR der Mouse, .Aq mouse@rodents.montreal.qc.ca .