oath_totp_validate3_callback(3)

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

✨ oath_totp_validate3_callback(3) ✨

okay so bestie, welcome to the oath_totp_validate3_callback page 💅 this lil icon lives in the liboath manual, section 3, and she's here to let you validate a TOTP without ever comparing the OTPs directly. yes, that's the whole vibe. let's get into it 🫶

🌸 NAME 🌸

oath_totp_validate3_callback — the API function 💖 (yes literally that's her whole job description, she's booked and busy)

🎀 SYNOPSIS 🎀

#include <oath.h>

int oath_totp_validate3_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, uint64_t * otp_counter,
oath_validate_strcmp_function strcmp_otp, void * strcmp_handle);

not me counting the arguments... there's eleven of them bestie, ELEVEN, she is not subtle 💀

🦋 ARGUMENTS 🦋

  • const char * secret — the shared secret string, the whole reason we're here ✨
  • size_t secret_length — how long that secret is, in case she's shy about her length 👀
  • time_t now — the Unix time value you wanna compute the TOTP for 🕰️
  • unsigned time_step_size — the time step system parameter (typically 30, like, the standard one bestie)
  • time_t start_offset — Unix time of when to start counting time steps (typically 0, so like, the beginning of time fr)
  • unsigned digits — how many digits you want in the OTP 🔢
  • size_t window — how many OTPs after the start counter to test — that's your search window 🌈
  • int * otp_pos — output search position in the search window (may be NULL). lowkey optional, highkey useful 💅
  • uint64_t * otp_counter — the counter value used to calculate the OTP value (may be NULL too, no pressure)
  • oath_validate_strcmp_function strcmp_otp — a function pointer to a strcmp-like function 🧚
  • void * strcmp_handle — the caller handle that gets passed on to strcmp_otp, hand it over bestie 🫱

💜 DESCRIPTION 💜

So what she actually does: she validates an OTP according to the OATH TOTP algorithm per RFC 6238 📜✨ periodt, that's the spec.

Validation is implemented by generating a number of potential OTPs and performing a call to the strcmp_otp function, to compare the potential OTP against the given otp. It has the following prototype:

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

The way that function should behave: it should be similar to strcmp in that it returns 0 only on matches 🎯. But she differs — she also permits use of negative return codes as an indication of internal failures in the callback 😭. And positive values indicate OTP mismatch. so like:

  • 0 → slay, it matched 👑
  • negative → something broke inside the callback, that's a her-problem not a you-problem 🙈
  • positive → nope, mismatch 💀

This callback interface is useful when you cannot compare OTPs directly using normal strcmp, but instead for example only have a hashed OTP 🔐. You would then typically pass in the hashed OTP in the strcmp_handle and let your implementation of strcmp_otp hash the test_otp OTP using the same hash, and then compare the results. it's giving "compare the hashes, not the secrets" energy and honestly? iconic.

Currently only OTP lengths of 6, 7 or 8 digits are supported. This restrictions may be lifted in future versions, although some limitations are inherent in the protocol. so no, you cannot do 4 digits, do not come for her 💅

⭐ RETURNS ⭐

Returns the absolute value of position in OTP window (zero is first position), or OATH_INVALID_OTP if no OTP was found in the OTP window, or an error code 🫶

🌈 SINCE 🌈

2.4.0 — she's been here a minute, respect the resume 💖

🍓 REPORTING BUGS 🍓

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. no cap, that's the actual license text, keep it intact bestie 🎀

so yeah, that's her 💜 eleven arguments, one callback, zero direct OTP comparisons — main character energy fr fr. go validate some TOTPs, iykyk 🦋✨

— with love from liboath, version 2.6.15 🌸 (that's the source and version, noted with a cute lil sign-off instead of a boring footer line, you're welcome 💅)

📦 where this page comes from