oath_totp_validate4(3)

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

💅 oath_totp_validate4(3) — the liboath glow-up 🎀

okay so bestie, welcome to oath_totp_validate4 💖 this one lives in liboath (that's the manual we're in, iykyk) and it's the function that checks whether somebody's TOTP code is actually valid. no cap, it's giving "bouncer at the club checking IDs" energy. let's get into it ✨

🌸 SYNOPSIS 🌸

#include <oath.h>

int oath_totp_validate4(const char * secret, size_t secret_length,
time_t now, unsigned time_step_size, time_t start_offset, size_t window,
int * otp_pos, uint64_t * otp_counter, int flags, const char * otp);

literally that whole signature. yes it's a lot of arguments. she's high-maintenance and we love her for it 💅

🦋 ARGUMENTS 🦋

okay so here's the roster, everyone gets their moment:

  • const char * secret — the shared secret string. the sacred text. the little password-in-a-string that both sides know 🤫
  • size_t secret_length — length of secret. yeah, she needs to be told explicitly, no guessing ✨
  • time_t now — Unix time value to validate TOTP for. like, what time even is it ⏰
  • unsigned time_step_size — time step system parameter (typically 30). so like, how many seconds per step, and 30 is the vibe 🌈
  • time_t start_offset — Unix time of when to start counting time steps (typically 0). where the clock-steps begin counting from 🕰️
  • size_t window — how many OTPs after/before start OTP to test. the search radius, bestie 🔍
  • int * otp_pos — output search position in search window (may be NULL). where in the window it hit 🎯
  • uint64_t * otp_counter — counter value used to calculate OTP value (may be NULL). the counter that did the math 🧮
  • int flags — flags indicating mode, one of oath_totp_flags. the settings dropdown 🎛️
  • const char * otp — the OTP to validate. the code being judged 👑

✨ DESCRIPTION ✨

So what does she do? She validates an OTP according to the OATH TOTP algorithm per RFC 6238 💖 iconic spec, no notes.

Currently only OTP lengths of 6, 7 or 8 digits are supported. and like, that's a restriction — she's saying "this may be lifted in future versions", although some limitations are inherent in the protocol. so don't come for her, it's a protocol thing 😭

The flags parameter may be used to change the MAC function, for example OATH_TOTP_HMAC_SHA256 or OATH_TOTP_HMAC_SHA512. so you can swap the whole MAC vibe, slay 🔥

👑 RETURNS 👑

Returns 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. so: a position, a rejection, or a problem. three moods 💀

⭐ SINCE ⭐

2.6.0 — she's been here a minute, respect the veteran 🫶

🐛 REPORTING BUGS 🐛

Found a bug? Report bugs to <oath-toolkit-help@nongnu.org> 💌. liboath home page: https://oath-toolkit.codeberg.page/ and general help using GNU software: http://www.gnu.org/gethelp/. go off, they wanna hear it ✨

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. fr fr, that's the license, be cool about it 💜

k bye bestie, go validate some OTPs and stan RFC 6238 for me 🌸🦋🎀 — this has been liboath 2.6.15, signing off, oath_totp_validate4(3) style 💅✨

📦 where this page comes from