A start at a man page. Just enough to commit. :)
I have also renamed the C file to pkcs5_pbkdf2.c to reflect the name
of the function.
Index: Makefile
===================================================================
RCS file: /cvs/src/lib/libutil/Makefile,v
retrieving revision 1.34
diff -u -p -r1.34 Makefile
--- Makefile 2 Aug 2012 13:38:39 -0000 1.34
+++ Makefile 5 Sep 2012 19:28:12 -0000
@@ -7,11 +7,12 @@ HDRS= util.h imsg.h
SRCS= check_expire.c duid.c getmaxpartitions.c getrawpartition.c login.c \
login_tty.c logout.c logwtmp.c opendev.c passwd.c pty.c readlabel.c \
login_fbtab.c uucplock.c fparseln.c opendisk.c pidfile.c \
- fmt_scaled.c imsg.c imsg-buffer.c
+ fmt_scaled.c imsg.c imsg-buffer.c pkcs5_pbkdf2.c
MAN= check_expire.3 getmaxpartitions.3 getrawpartition.3 isduid.3 login.3 \
opendev.3 openpty.3 pw_init.3 pw_lock.3 readlabelfs.3 uucplock.3 \
- fparseln.3 opendisk.3 login_fbtab.3 pidfile.3 fmt_scaled.3 imsg_init.3
+ fparseln.3 opendisk.3 login_fbtab.3 pidfile.3 fmt_scaled.3 imsg_init.3 \
+ pkcs5_pbkdf2.3
MLINKS+=imsg_init.3 imsg_read.3
MLINKS+=imsg_init.3 imsg_get.3
Index: pkcs5_pbkdf2.3
===================================================================
RCS file: pkcs5_pbkdf2.3
diff -N pkcs5_pbkdf2.3
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ pkcs5_pbkdf2.3 5 Sep 2012 19:43:52 -0000
@@ -0,0 +1,55 @@
+.\" $OpenBSD: mdoc.template,v 1.12 2010/09/04 08:00:15 jmc Exp $
+.\"
+.\" Copyright (c) 2012 Ted Unangst <[email protected]>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate$
+.Dt pkcs5_pbkdf2 3
+.Os
+.Sh NAME
+.Nm pkcs5_pbkdf2
+.Nd password based key derivation function
+.Sh SYNOPSIS
+.Fd #include <util.h>
+.Ft int
+.Fn pkcs5_pbkdf2 "conat char *pass" "size_t pass_len" "const char *salt" \
+ "size_t salt_len" "u_int8_t *key" "size_t key_len" "u_int rounds"
+.Sh DESCRIPTION
+The
+.Nm
+function converts a password into a key suitable for encryption.
+The password and salt values are combined and repeatedly hashed
+.Ar rounds
+times.
+The repeated hashing is designed to thwart password guessing attacks from
+discovering the key.
+The higher the number of rounds, the slower each attempt will be.
+A minumum value of at least 1000 is recommended.
+.Sh RETURN VALUES
+The
+.Fn pkcs5_pbkdf2
+function returns 0 to indicate success and -1 for failure.
+.\" .Sh EXAMPLES
+.\" .Sh ERRORS
+.Sh SEE ALSO
+.Xr sha1 1
+.Sh STANDARDS
+RFC 2898
+.\" .Sh HISTORY
+.\" .Sh AUTHORS
+.Sh CAVEATS
+The standard allows for different hash functions to be used.
+This implementation only uses
+.Xr sha1 1 .
+.\" .Sh BUGS
