1oath_totp_validate3_callback(3)     liboath    oath_totp_validate3_callback(3)
2
3
4

NAME

6       oath_totp_validate3_callback - API function
7

SYNOPSIS

9       #include <oath.h>
10
11       int    oath_totp_validate3_callback(const   char   *   secret,   size_t
12       secret_length, time_t now, unsigned time_step_size,  time_t  start_off‐
13       set,  unsigned  digits,  size_t  window,  int  *  otp_pos,  uint64_t  *
14       otp_counter,  oath_validate_strcmp_function  strcmp_otp,  void  *  str‐
15       cmp_handle);
16

ARGUMENTS

18       const char * secret
19                   the shared secret string
20
21       size_t secret_length
22                   length of secret
23
24       time_t now  Unix time value to compute TOTP for
25
26       unsigned time_step_size
27                   time step system parameter (typically 30)
28
29       time_t start_offset
30                   Unix  time  of when to start counting time steps (typically
31                   0)
32
33       unsigned digits
34                   number of requested digits in the OTP
35
36       size_t window
37                   how many OTPs after start counter to test
38
39       int * otp_pos
40                   output search position in search window (may be NULL).
41
42       uint64_t * otp_counter
43                   counter value used to calculate OTP value (may be NULL).
44
45       oath_validate_strcmp_function strcmp_otp
46                   function pointer to a strcmp-like function.
47
48       void * strcmp_handle
49                   caller handle to be passed on to strcmp_otp.
50

DESCRIPTION

52       Validate an OTP according to OATH TOTP algorithm per RFC 6238.
53
54       Validation is implemented by generating a number of potential OTPs  and
55       performing  a call to the strcmp_otp function, to compare the potential
56       OTP against the given otp.  It has the following prototype:
57
58       int  (*oath_validate_strcmp_function)   (void   *handle,   const   char
59       *test_otp);
60
61       The  function  should  be similar to strcmp in that it return 0 only on
62       matches.  It differs by permitting use  of  negative  return  codes  as
63       indication of internal failures in the callback.  Positive values indi‐
64       cate OTP mismatch.
65
66       This callback interface is useful when you cannot compare OTPs directly
67       using  normal  strcmp,  but instead for example only have a hashed OTP.
68       You would then typically pass in the hashed OTP  in  the  strcmp_handle
69       and  let  your implementation of strcmp_otp hash the test_otp OTP using
70       the same hash, and then compare the results.
71
72       Currently only OTP lengths of 6, 7 or 8  digits  are  supported.   This
73       restrictions  may  be  lifted in future versions, although some limita‐
74       tions are inherent in the protocol.
75

RETURNS

77       Returns absolute value of position in OTP window (zero is  first  posi‐
78       tion),  or  OATH_INVALID_OTP  if  no OTP was found in OTP window, or an
79       error code.
80

SINCE

82       2.4.0
83

REPORTING BUGS

85       Report bugs  to  <oath-toolkit-help@nongnu.org>.   liboath  home  page:
86       http://www.gnu.org/software/liboath/  General  help using GNU software:
87       http://www.gnu.org/gethelp/
88

90       Copyright © 2009-2020 Simon Josefsson.
91       Copying and distribution of this file, with  or  without  modification,
92       are  permitted  in  any  medium  without royalty provided the copyright
93       notice and this notice are preserved.
94
95
96
97liboath                              2.6.6     oath_totp_validate3_callback(3)
Impressum