oath_totp_validate2_callback(3)

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

💅 oath_totp_validate2_callback(3) — the liboath glow-up

okay so bestie, welcome to the manual page for oath_totp_validate2_callback(3). it lives in liboath, it's the fancy callback-flavored version of TOTP validation, and honestly? it's giving main character energy for anyone who can't just strcmp two strings like a normie. let's get into it ✨

🌸 NAME 🌸

oath_totp_validate2_callback — an API function. that's it, that's the name, she's an API function and she's iconic 💖

🎀 SYNOPSIS 🎀

#include <oath.h>

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

like, look at all those parameters. she has range. 🦋

✨ ARGUMENTS ✨

okay so here's the whole cast, in order, no skips, no cuts 🫶

  • const char * secret — the shared secret string. the actual tea. 🍓
  • size_t secret_length — how long that secret is, in all its glory.
  • time_t now — the Unix time value we're computing TOTP for. basically "what time do we think it is".
  • unsigned time_step_size — the time step system parameter. typically 30. classic. ⏰
  • time_t start_offset — the Unix time of when to start counting time steps. typically 0.
  • unsigned digits — how many digits you want in the OTP. (more on the valid numbers below, bestie 👀)
  • size_t window — how many OTPs after the start counter to test. your search zone 💅
  • int * otp_pos — output search position in the search window. may be NULL. yes, NULL is allowed, she's flexible.
  • oath_validate_strcmp_function strcmp_otp — a function pointer to a strcmp-like function. we love a pluggable vibe.
  • void * strcmp_handle — caller handle that gets passed on through to strcmp_otp. it's the little bag you hand over. 🎀

💜 DESCRIPTION 💜

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

the way validation works: she generates a whole bunch of potential OTPs and then calls your strcmp_otp function to compare each potential OTP against the given otp. it's like a lineup but for codes. 🕵️‍♀️

that callback has the following prototype:

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

here's the vibe check on the return value: your function should be similar to strcmp in that it returns 0 only on matches. but it differs — and this is the important part, ngl — by permitting use of negative return codes as an indication of internal failures in the callback. positive values mean the OTP didn't match. so like: 0 = slay, negative = something broke on your end 😭, positive = nope, not it 💀

lowkey the whole reason this callback interface exists: you might not be able to compare OTPs directly using normal strcmp. maybe you only have a hashed OTP, for example. in that case you'd typically pass the hashed OTP in the strcmp_handle, let your implementation of strcmp_otp hash the test_otp OTP using that same hash, and then compare the results. matching hashes, matching vibes. ✨

also, real talk: currently only OTP lengths of 6, 7 or 8 digits are supported. those restrictions may be lifted in future versions, although — and this is the caveat, bestie — some limitations are inherent in the protocol. so don't come for her, it's the protocol's fault 🙈

👑 RETURNS 👑

she returns the absolute value of 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 menu. 🍓

⭐ SINCE ⭐

1.10.0 — she's been around, she's got history, she's a legacy icon. 💅

🦋 REPORTING BUGS 🦋

found something cursed? 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 like, go off, just keep the receipts 🧚

okay that's the whole page, no notes, you ate that 💖 this was the oath_totp_validate2_callback(3) page from liboath, version 2.6.15 — mwah, go validate some OTPs bestie, ily 🫶🎀

📦 where this page comes from