oath_totp_validate_callback(3)

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

💅 oath_totp_validate_callback(3) — the liboath era

okay so bestie, you found the page for oath_totp_validate_callback, and honestly? it's giving "the smartest function in the group chat." it lives in liboath, and it's the one you call when you need to check whether somebody's TOTP code is actually correct. let's get into it ✨

🌸 NAME 🌸

oath_totp_validate_callback — an API function. that's it, that's the name. it validates TOTP OTPs, but with a callback twist. 🎀

✨ SYNOPSIS ✨

#include <oath.h>

int oath_totp_validate_callback(const char * secret, size_t
secret_length, time_t now, unsigned time_step_size, time_t start_offset,
unsigned digits, size_t window, oath_validate_strcmp_function
strcmp_otp, void * strcmp_handle);

like, look at all those parameters. she's thorough. 💅

🦋 ARGUMENTS 🦋

every single one, bestie, no skipping:

  • const char * secret — the shared secret string. the actual secret-secret. 🤫
  • size_t secret_length — how long that secret is, obviously.
  • time_t now — the Unix time value to compute the TOTP for.
  • unsigned time_step_size — the time step system parameter. typically 30. that's the classic. ⏰
  • time_t start_offset — the Unix time of when to start counting time steps. typically 0.
  • unsigned digits — the number of requested digits in the OTP.
  • size_t window — how many OTPs after the start counter to test. so like, how far forward we're willing to look. 👀
  • oath_validate_strcmp_function strcmp_otp — a function pointer to a strcmp-like function. yes, a callback. we love a callback. 🫶
  • void * strcmp_handle — the caller handle that gets passed on to strcmp_otp. hand it over, girl.

💖 DESCRIPTION 💖

so what does she actually do? she validates an OTP according to the OATH TOTP algorithm, per RFC 6238. periodt.

here's the vibe: validation happens by generating a bunch of potential OTPs and then calling your strcmp_otp function to compare each potential OTP against the given otp. so it's like a little lineup of candidates and your callback does the judging. 🔍

the callback has this prototype, exactly:

int (*oath_validate_strcmp_function) (void *handle, const char
*test_otp);

your function should be similar to strcmp in that it returns 0 only on a match. but here's where she's different, and this is important, ngl: negative return codes are permitted as an indication of internal failures in the callback. positive values indicate OTP mismatch. so like, 0 = slay, negative = something broke inside you, positive = nope, wrong code. 💀

this callback interface is genuinely iconic when you cannot compare OTPs directly using a normal strcmp. like, say you only have a hashed OTP. in that case you'd typically pass in the hashed OTP inside strcmp_handle, and let your implementation of strcmp_otp hash the test_otp OTP using the same hash, and then compare the results. hashing both sides, comparing hashes, chef's kiss. 🧚

⚠️ heads up: currently only OTP lengths of 6, 7 or 8 digits are supported. these restrictions may be lifted in future versions, although some limitations are inherent in the protocol. so don't come for her about 9 digits, it's a protocol thing. 😭

⭐ RETURNS ⭐

she returns the position in the OTP window (zero is the first position), or OATH_INVALID_OTP if no OTP was found in the OTP window, or an error code. that's the whole deal. 🌈

👑 SINCE 👑

1.6.0. she's been around. a real veteran. 💜

🙈 REPORTING BUGS 🙈

found a bug? don't suffer in silence, bestie — report bugs to <oath-toolkit-help@nongnu.org>. 📧

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. so yes, share it, just keep the receipts. 🧾

okay and one last cute little sign-off: this adorable page comes to you from liboath, version 2.6.15 — the oath_totp_validate_callback(3) manual page itself. go forth and validate those OTPs, bestie, you're gonna ate. 🎀💅✨

📦 where this page comes from