From af0c5a4b6c8cc2721317375fb8bd5784ab09c55e Mon Sep 17 00:00:00 2001
From: tedu <tedu@openbsd.org>
Date: Fri, 16 May 2014 21:34:48 +0000
Subject: [PATCH] document crypt_checkpass

---
 lib/libc/crypt/crypt.3 | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/lib/libc/crypt/crypt.3 b/lib/libc/crypt/crypt.3
index 8d5681d67ae..09d1691b5a8 100644
--- a/lib/libc/crypt/crypt.3
+++ b/lib/libc/crypt/crypt.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: crypt.3,v 1.36 2014/05/16 14:12:19 sthen Exp $
+.\" $OpenBSD: crypt.3,v 1.37 2014/05/16 21:34:48 tedu Exp $
 .\"
 .\" FreeSec: libcrypt
 .\"
@@ -52,6 +52,8 @@
 .Ft char *
 .Fn crypt "const char *key" "const char *setting"
 .Ft int
+.Fn crypt_checkpass "const char *password" "const char *hash"
+.Ft int
 .Fn encrypt "char *block" "int flag"
 .Ft int
 .Fn des_setkey "const char *key"
@@ -88,6 +90,17 @@ and a number then a different algorithm is used depending on the number.
 At the moment
 .Ql $2
 chooses Blowfish hashing; see below for more information.
+.Pp
+The
+.Fn crypt_checkpass
+function is provided to simplify checking a user's password.
+If both the hash and the password are the empty string, authentication
+is a success.
+Otherwise, the password is hashed and compared to the provided hash.
+If the hash is NULL, authentication will always fail, but a default
+amount of work is performed to simulate the hashing operation.
+A successful match will return 0.
+A failure will return -1 and set errno.
 .Ss Extended crypt
 The
 .Ar key
-- 
2.20.1