oath_authenticate_usersfile(3)

📦
version 2.6.15 · 5 versions
, in arch rolling, nixpkgs unstable

🎀 oath_authenticate_usersfile(3) — liboath edition 🎀

💖 NAME 💖

oath_authenticate_usersfile — API function, bestie. That’s the whole name vibe. ✨

✨ SYNOPSIS ✨

okay so here’s the exact signature, no cap:

#include <oath.h>

int oath_authenticate_usersfile(const char * usersfile, const char *
       username, const char * otp, size_t window, const char * passwd, time_t *
       last_otp);

🦋 ARGUMENTS 🦋

  • const char * usersfile — a string with the user credential filename, in UsersFile format. Think: where the receipts live. 🧾
  • const char * username — a string with the name of the user. Main character identified. 👑
  • const char * otp — a string with the one-time password to authenticate. The little secret code era. 🔥
  • size_t window — how many past/future OTPs to search. Yes, it’s giving “look around the timeline.” ⏳
  • const char * passwd — a string with the password, or NULL to disable password checking. Choose your fighter. 💅
  • time_t * last_otp — output variable holding last successful authentication. The receipt of the last successful slay. 🫶

🌸 DESCRIPTION 🌸

Authenticate user named username with the one-time password otp and (optional) password passwd. Credentials are read (and updated) from a text file named usersfile. 💖

TOTP bestie note: 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 logic relies on using the same search window for the same user. 🌀

🔥 RETURNS 🔥

On successful validation, OATH_OK is returned. Slay. ✅

If the supplied otp is the same as the last successfully authenticated one-time password, OATH_REPLAYED_OTP is returned and the timestamp of the last authentication is returned in last_otp. Replay detected, bestie. 🚨

If the one-time password is not found in the indicated search window, OATH_INVALID_OTP is returned. Not in this timeline. 😭

Otherwise, an error code is returned. Mystery little gremlin error energy. 💀

🐛 REPORTING BUGS 🐛

Report bugs to <oath-toolkit-help@nongnu.org>. liboath home page: https://oath-toolkit.codeberg.page/ General help using GNU software: http://www.gnu.org/gethelp/ 🫶

Copyright © 2009-2026 Simon Josefsson. 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. 📜

— signed off from liboath 2.6.15, with © 2009-2026 energy · bye bestie, go authenticate responsibly 💅🫶

📦 where this page comes from