1oath_totp_validate4_callback(3)     liboath    oath_totp_validate4_callback(3)
2
3
4

NAME

6       oath_totp_validate4_callback - API function
7

SYNOPSIS

9       #include <oath.h>
10
11       int    oath_totp_validate4_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, int flags, oath_validate_strcmp_function strcmp_otp,  void
15       * strcmp_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       int flags   flags indicating mode, one of oath_totp_flags
46
47       oath_validate_strcmp_function strcmp_otp
48                   function pointer to a strcmp-like function.
49
50       void * strcmp_handle
51                   caller handle to be passed on to strcmp_otp.
52

DESCRIPTION

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

RETURNS

82       Returns  absolute  value of position in OTP window (zero is first posi‐
83       tion), or OATH_INVALID_OTP if no OTP was found in  OTP  window,  or  an
84       error code.
85

SINCE

87       2.6.0
88

REPORTING BUGS

90       Report  bugs  to  <oath-toolkit-help@nongnu.org>.   liboath  home page:
91       http://www.gnu.org/software/liboath/ General help using  GNU  software:
92       http://www.gnu.org/gethelp/
93

95       Copyright © 2009-2020 Simon Josefsson.
96       Copying  and  distribution  of this file, with or without modification,
97       are permitted in any medium  without  royalty  provided  the  copyright
98       notice and this notice are preserved.
99
100
101
102liboath                              2.6.6     oath_totp_validate4_callback(3)
Impressum