.\" DO NOT MODIFY THIS FILE!  It was generated by gdoc.
.TH "oath_authenticate_usersfile" 3 "2.6.7" "liboath" "liboath"
.SH NAME
oath_authenticate_usersfile \- API function
.SH SYNOPSIS
.B #include <oath.h>
.sp
.BI "int oath_authenticate_usersfile(const char * " usersfile ", const char * " username ", const char * " otp ", size_t " window ", const char * " passwd ", time_t * " last_otp ");"
.SH ARGUMENTS
.IP "const char * usersfile" 12
string with user credential filename, in UsersFile format
.IP "const char * username" 12
string with name of user
.IP "const char * otp" 12
string with one\-time password to authenticate
.IP "size_t window" 12
how many past/future OTPs to search
.IP "const char * passwd" 12
string with password, or NULL to disable password checking
.IP "time_t * last_otp" 12
output variable holding last successful authentication
.SH "DESCRIPTION"
Authenticate user named \fIusername\fP with the one\-time password \fIotp\fP
and (optional) password \fIpasswd\fP.  Credentials are read (and
updated) from a text file named \fIusersfile\fP.

Note that for TOTP the usersfile will only record the last OTP and
use that to make sure more recent OTPs have not been seen yet when
validating a new OTP.  That logics relies on using the same search
window for the same user.
.SH "RETURNS"
On successful validation, \fBOATH_OK\fP is returned.  If the
supplied \fIotp\fP is the same as the last successfully authenticated
one\-time password, \fBOATH_REPLAYED_OTP\fP is returned and the
timestamp of the last authentication is returned in \fIlast_otp\fP.
If the one\-time password is not found in the indicated search
window, \fBOATH_INVALID_OTP\fP is returned.  Otherwise, an error code
is returned.
.SH "REPORTING BUGS"
Report bugs to <oath-toolkit-help@nongnu.org>.
liboath home page: https://www.nongnu.org/oath-toolkit/
General help using GNU software: http://www.gnu.org/gethelp/
.SH COPYRIGHT
Copyright \(co 2009-2020 Simon Josefsson.
.br
Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved.