Debian Codegraph @

liboath/gtk-doc/html/liboath-oath.h.html

raw
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html>
3 <head>
4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5 <title>oath.h: OATH Library (liboath) Manual</title>
6 <meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
7 <link rel="home" href="index.html" title="OATH Library (liboath) Manual">
8 <link rel="up" href="intro.html" title="Liboath API Reference Manual">
9 <link rel="prev" href="intro.html" title="Liboath API Reference Manual">
10 <link rel="next" href="api-index-full.html" title="API Index">
11 <meta name="generator" content="GTK-Doc V1.34.0 (XML mode)">
12 <link rel="stylesheet" href="style.css" type="text/css">
13 </head>
14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
16 <td width="100%" align="left" class="shortcuts"></td>
17 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
18 <td><a accesskey="u" href="intro.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
19 <td><a accesskey="p" href="intro.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
20 <td><a accesskey="n" href="api-index-full.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
21 </tr></table>
22 <div class="refentry">
23 <a name="liboath-oath.h"></a><div class="titlepage"></div>
24 <div class="refnamediv">
25 <h2><span class="refentrytitle"><a name="liboath-oath.h.top_of_page"></a>oath.h</span></h2>
26 <p>oath.h — liboath declarations</p>
27 </div>
28 <div class="refsect1">
29 <a name="liboath-oath.h.functions"></a><h2>Functions</h2>
30 <div class="informaltable"><table class="informaltable" width="100%" border="0">
31 <colgroup>
32 <col width="150px" class="functions_proto_type">
33 <col class="functions_proto_name">
34 </colgroup>
35 <tbody>
36 <tr>
37 <td class="function_type">
38 <a class="link" href=""><span class="returnvalue">int</span></a>
39 </td>
40 <td class="function_name">
41 <a class="link" href="liboath-oath.h.html#oath-init" title="oath_init ()">oath_init</a> <span class="c_punctuation">()</span>
42 </td>
43 </tr>
44 <tr>
45 <td class="function_type">
46 <a class="link" href=""><span class="returnvalue">int</span></a>
47 </td>
48 <td class="function_name">
49 <a class="link" href="liboath-oath.h.html#oath-done" title="oath_done ()">oath_done</a> <span class="c_punctuation">()</span>
50 </td>
51 </tr>
52 <tr>
53 <td class="function_type">const <a class="link" href=""><span class="returnvalue">char</span></a> *
54 </td>
55 <td class="function_name">
56 <a class="link" href="liboath-oath.h.html#oath-check-version" title="oath_check_version ()">oath_check_version</a> <span class="c_punctuation">()</span>
57 </td>
58 </tr>
59 <tr>
60 <td class="function_type">const <a class="link" href=""><span class="returnvalue">char</span></a> *
61 </td>
62 <td class="function_name">
63 <a class="link" href="liboath-oath.h.html#oath-strerror" title="oath_strerror ()">oath_strerror</a> <span class="c_punctuation">()</span>
64 </td>
65 </tr>
66 <tr>
67 <td class="function_type">const <a class="link" href=""><span class="returnvalue">char</span></a> *
68 </td>
69 <td class="function_name">
70 <a class="link" href="liboath-oath.h.html#oath-strerror-name" title="oath_strerror_name ()">oath_strerror_name</a> <span class="c_punctuation">()</span>
71 </td>
72 </tr>
73 <tr>
74 <td class="function_type">
75 <a class="link" href=""><span class="returnvalue">int</span></a>
76 </td>
77 <td class="function_name">
78 <a class="link" href="liboath-oath.h.html#oath-hex2bin" title="oath_hex2bin ()">oath_hex2bin</a> <span class="c_punctuation">()</span>
79 </td>
80 </tr>
81 <tr>
82 <td class="function_type">
83 <a class="link" href=""><span class="returnvalue">void</span></a>
84 </td>
85 <td class="function_name">
86 <a class="link" href="liboath-oath.h.html#oath-bin2hex" title="oath_bin2hex ()">oath_bin2hex</a> <span class="c_punctuation">()</span>
87 </td>
88 </tr>
89 <tr>
90 <td class="function_type">
91 <a class="link" href=""><span class="returnvalue">int</span></a>
92 </td>
93 <td class="function_name">
94 <a class="link" href="liboath-oath.h.html#oath-base32-decode" title="oath_base32_decode ()">oath_base32_decode</a> <span class="c_punctuation">()</span>
95 </td>
96 </tr>
97 <tr>
98 <td class="function_type">
99 <a class="link" href=""><span class="returnvalue">int</span></a>
100 </td>
101 <td class="function_name">
102 <a class="link" href="liboath-oath.h.html#oath-base32-encode" title="oath_base32_encode ()">oath_base32_encode</a> <span class="c_punctuation">()</span>
103 </td>
104 </tr>
105 <tr>
106 <td class="define_keyword">#define</td>
107 <td class="function_name">
108 <a class="link" href="liboath-oath.h.html#OATH-HOTP-LENGTH:CAPS" title="OATH_HOTP_LENGTH()">OATH_HOTP_LENGTH</a><span class="c_punctuation">()</span>
109 </td>
110 </tr>
111 <tr>
112 <td class="function_type">
113 <a class="link" href=""><span class="returnvalue">int</span></a>
114 </td>
115 <td class="function_name">
116 <a class="link" href="liboath-oath.h.html#oath-hotp-generate" title="oath_hotp_generate ()">oath_hotp_generate</a> <span class="c_punctuation">()</span>
117 </td>
118 </tr>
119 <tr>
120 <td class="function_type">
121 <a class="link" href=""><span class="returnvalue">int</span></a>
122 </td>
123 <td class="function_name">
124 <a class="link" href="liboath-oath.h.html#oath-hotp-validate" title="oath_hotp_validate ()">oath_hotp_validate</a> <span class="c_punctuation">()</span>
125 </td>
126 </tr>
127 <tr>
128 <td class="function_type">
129 <a class="link" href=""><span class="returnvalue">int</span></a>
130 </td>
131 <td class="function_name">
132 <span class="c_punctuation">(</span><a class="link" href="liboath-oath.h.html#oath-validate-strcmp-function" title="oath_validate_strcmp_function ()">*oath_validate_strcmp_function</a><span class="c_punctuation">)</span> <span class="c_punctuation">()</span>
133 </td>
134 </tr>
135 <tr>
136 <td class="function_type">
137 <a class="link" href=""><span class="returnvalue">int</span></a>
138 </td>
139 <td class="function_name">
140 <a class="link" href="liboath-oath.h.html#oath-hotp-validate-callback" title="oath_hotp_validate_callback ()">oath_hotp_validate_callback</a> <span class="c_punctuation">()</span>
141 </td>
142 </tr>
143 <tr>
144 <td class="function_type">
145 <a class="link" href=""><span class="returnvalue">int</span></a>
146 </td>
147 <td class="function_name">
148 <a class="link" href="liboath-oath.h.html#oath-totp-generate" title="oath_totp_generate ()">oath_totp_generate</a> <span class="c_punctuation">()</span>
149 </td>
150 </tr>
151 <tr>
152 <td class="function_type">
153 <a class="link" href=""><span class="returnvalue">int</span></a>
154 </td>
155 <td class="function_name">
156 <a class="link" href="liboath-oath.h.html#oath-totp-generate2" title="oath_totp_generate2 ()">oath_totp_generate2</a> <span class="c_punctuation">()</span>
157 </td>
158 </tr>
159 <tr>
160 <td class="function_type">
161 <a class="link" href=""><span class="returnvalue">int</span></a>
162 </td>
163 <td class="function_name">
164 <a class="link" href="liboath-oath.h.html#oath-totp-validate" title="oath_totp_validate ()">oath_totp_validate</a> <span class="c_punctuation">()</span>
165 </td>
166 </tr>
167 <tr>
168 <td class="function_type">
169 <a class="link" href=""><span class="returnvalue">int</span></a>
170 </td>
171 <td class="function_name">
172 <a class="link" href="liboath-oath.h.html#oath-totp-validate-callback" title="oath_totp_validate_callback ()">oath_totp_validate_callback</a> <span class="c_punctuation">()</span>
173 </td>
174 </tr>
175 <tr>
176 <td class="function_type">
177 <a class="link" href=""><span class="returnvalue">int</span></a>
178 </td>
179 <td class="function_name">
180 <a class="link" href="liboath-oath.h.html#oath-totp-validate2" title="oath_totp_validate2 ()">oath_totp_validate2</a> <span class="c_punctuation">()</span>
181 </td>
182 </tr>
183 <tr>
184 <td class="function_type">
185 <a class="link" href=""><span class="returnvalue">int</span></a>
186 </td>
187 <td class="function_name">
188 <a class="link" href="liboath-oath.h.html#oath-totp-validate2-callback" title="oath_totp_validate2_callback ()">oath_totp_validate2_callback</a> <span class="c_punctuation">()</span>
189 </td>
190 </tr>
191 <tr>
192 <td class="function_type">
193 <a class="link" href=""><span class="returnvalue">int</span></a>
194 </td>
195 <td class="function_name">
196 <a class="link" href="liboath-oath.h.html#oath-totp-validate3" title="oath_totp_validate3 ()">oath_totp_validate3</a> <span class="c_punctuation">()</span>
197 </td>
198 </tr>
199 <tr>
200 <td class="function_type">
201 <a class="link" href=""><span class="returnvalue">int</span></a>
202 </td>
203 <td class="function_name">
204 <a class="link" href="liboath-oath.h.html#oath-totp-validate3-callback" title="oath_totp_validate3_callback ()">oath_totp_validate3_callback</a> <span class="c_punctuation">()</span>
205 </td>
206 </tr>
207 <tr>
208 <td class="function_type">
209 <a class="link" href=""><span class="returnvalue">int</span></a>
210 </td>
211 <td class="function_name">
212 <a class="link" href="liboath-oath.h.html#oath-totp-validate4" title="oath_totp_validate4 ()">oath_totp_validate4</a> <span class="c_punctuation">()</span>
213 </td>
214 </tr>
215 <tr>
216 <td class="function_type">
217 <a class="link" href=""><span class="returnvalue">int</span></a>
218 </td>
219 <td class="function_name">
220 <a class="link" href="liboath-oath.h.html#oath-totp-validate4-callback" title="oath_totp_validate4_callback ()">oath_totp_validate4_callback</a> <span class="c_punctuation">()</span>
221 </td>
222 </tr>
223 <tr>
224 <td class="function_type">
225 <a class="link" href=""><span class="returnvalue">int</span></a>
226 </td>
227 <td class="function_name">
228 <a class="link" href="liboath-oath.h.html#oath-authenticate-usersfile" title="oath_authenticate_usersfile ()">oath_authenticate_usersfile</a> <span class="c_punctuation">()</span>
229 </td>
230 </tr>
231 </tbody>
232 </table></div>
233 </div>
234 <div class="refsect1">
235 <a name="liboath-oath.h.other"></a><h2>Types and Values</h2>
236 <div class="informaltable"><table class="informaltable" width="100%" border="0">
237 <colgroup>
238 <col width="150px" class="other_proto_type">
239 <col class="other_proto_name">
240 </colgroup>
241 <tbody>
242 <tr>
243 <td class="define_keyword">#define</td>
244 <td class="function_name"><a class="link" href="liboath-oath.h.html#OATHAPI:CAPS" title="OATHAPI">OATHAPI</a></td>
245 </tr>
246 <tr>
247 <td class="define_keyword">#define</td>
248 <td class="function_name"><a class="link" href="liboath-oath.h.html#OATH-VERSION:CAPS" title="OATH_VERSION">OATH_VERSION</a></td>
249 </tr>
250 <tr>
251 <td class="define_keyword">#define</td>
252 <td class="function_name"><a class="link" href="liboath-oath.h.html#OATH-VERSION-NUMBER:CAPS" title="OATH_VERSION_NUMBER">OATH_VERSION_NUMBER</a></td>
253 </tr>
254 <tr>
255 <td class="datatype_keyword">enum</td>
256 <td class="function_name"><a class="link" href="liboath-oath.h.html#oath-rc" title="enum oath_rc">oath_rc</a></td>
257 </tr>
258 <tr>
259 <td class="define_keyword">#define</td>
260 <td class="function_name"><a class="link" href="liboath-oath.h.html#OATH-HOTP-DYNAMIC-TRUNCATION:CAPS" title="OATH_HOTP_DYNAMIC_TRUNCATION">OATH_HOTP_DYNAMIC_TRUNCATION</a></td>
261 </tr>
262 <tr>
263 <td class="define_keyword">#define</td>
264 <td class="function_name"><a class="link" href="liboath-oath.h.html#oath-hotp-validate-strcmp-function" title="oath_hotp_validate_strcmp_function">oath_hotp_validate_strcmp_function</a></td>
265 </tr>
266 <tr>
267 <td class="define_keyword">#define</td>
268 <td class="function_name"><a class="link" href="liboath-oath.h.html#OATH-TOTP-DEFAULT-TIME-STEP-SIZE:CAPS" title="OATH_TOTP_DEFAULT_TIME_STEP_SIZE">OATH_TOTP_DEFAULT_TIME_STEP_SIZE</a></td>
269 </tr>
270 <tr>
271 <td class="define_keyword">#define</td>
272 <td class="function_name"><a class="link" href="liboath-oath.h.html#OATH-TOTP-DEFAULT-START-TIME:CAPS" title="OATH_TOTP_DEFAULT_START_TIME">OATH_TOTP_DEFAULT_START_TIME</a></td>
273 </tr>
274 <tr>
275 <td class="datatype_keyword">enum</td>
276 <td class="function_name"><a class="link" href="liboath-oath.h.html#oath-totp-flags" title="enum oath_totp_flags">oath_totp_flags</a></td>
277 </tr>
278 </tbody>
279 </table></div>
280 </div>
281 <div class="refsect1">
282 <a name="liboath-oath.h.description"></a><h2>Description</h2>
283 <p>The oath.h file contains declarations for the liboath library.</p>
284 </div>
285 <div class="refsect1">
286 <a name="liboath-oath.h.functions_details"></a><h2>Functions</h2>
287 <div class="refsect2">
288 <a name="oath-init"></a><h3>oath_init ()</h3>
289 <a class="indexterm" name="id-1.2.2.6.2.2"></a><pre class="programlisting"><a class="link" href=""><span class="returnvalue">int</span></a>
290 oath_init (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
291 <p>This function initializes the OATH library. Every user of this
292 library needs to call this function before using other functions.
293 You should call <a class="link" href="liboath-oath.h.html#oath-done" title="oath_done ()"><code class="function">oath_done()</code></a> when use of the OATH library is no
294 longer needed.</p>
295 <p>Note that this function may also initialize Libgcrypt, if the OATH
296 library is built with libgcrypt support and libgcrypt has not been
297 initialized before. Thus if you want to manually initialize
298 libgcrypt you must do it before calling this function. This is
299 useful in cases you want to disable libgcrypt's internal lockings
300 etc.</p>
301 <div class="refsect3">
302 <a name="oath-init.returns"></a><h4>Returns</h4>
303 <p> On success, <a class="link" href="liboath-oath.h.html#OATH-OK:CAPS"><code class="literal">OATH_OK</code></a> (zero) is returned, otherwise an
304 error code is returned.</p>
305 </div>
306 </div>
307 <div class="refsect2">
308 <a name="oath-done"></a><h3>oath_done ()</h3>
309 <a class="indexterm" name="id-1.2.2.6.3.2"></a><pre class="programlisting"><a class="link" href=""><span class="returnvalue">int</span></a>
310 oath_done (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
311 <p>This function deinitializes the OATH library, which were
312 initialized using <a class="link" href="liboath-oath.h.html#oath-init" title="oath_init ()"><code class="function">oath_init()</code></a>. After calling this function, no
313 other OATH library function may be called except for to
314 re-initialize the library using <a class="link" href="liboath-oath.h.html#oath-init" title="oath_init ()"><code class="function">oath_init()</code></a>.</p>
315 <div class="refsect3">
316 <a name="oath-done.returns"></a><h4>Returns</h4>
317 <p> On success, <a class="link" href="liboath-oath.h.html#OATH-OK:CAPS"><code class="literal">OATH_OK</code></a> (zero) is returned, otherwise an
318 error code is returned.</p>
319 </div>
320 </div>
321 <div class="refsect2">
322 <a name="oath-check-version"></a><h3>oath_check_version ()</h3>
323 <a class="indexterm" name="id-1.2.2.6.4.2"></a><pre class="programlisting">const <a class="link" href=""><span class="returnvalue">char</span></a> *
324 oath_check_version (<em class="parameter"><code>const <a class="link" href=""><span class="type">char</span></a> *req_version</code></em>);</pre>
325 <p>Check OATH library version.</p>
326 <p>See <a class="link" href="liboath-oath.h.html#OATH-VERSION:CAPS" title="OATH_VERSION"><code class="literal">OATH_VERSION</code></a> for a suitable <em class="parameter"><code>req_version</code></em>
327 string.</p>
328 <p>This function is one of few in the library that can be used without
329 a successful call to <a class="link" href="liboath-oath.h.html#oath-init" title="oath_init ()"><code class="function">oath_init()</code></a>.</p>
330 <div class="refsect3">
331 <a name="oath-check-version.parameters"></a><h4>Parameters</h4>
332 <div class="informaltable"><table class="informaltable" width="100%" border="0">
333 <colgroup>
334 <col width="150px" class="parameters_name">
335 <col class="parameters_description">
336 <col width="200px" class="parameters_annotations">
337 </colgroup>
338 <tbody><tr>
339 <td class="parameter_name"><p>req_version</p></td>
340 <td class="parameter_description"><p>version string to compare with, or NULL.</p></td>
341 <td class="parameter_annotations"> </td>
342 </tr></tbody>
343 </table></div>
344 </div>
345 <div class="refsect3">
346 <a name="oath-check-version.returns"></a><h4>Returns</h4>
347 <p> Check that the version of the library is at
348 minimum the one given as a string in <em class="parameter"><code>req_version</code></em>
349 and return the
350 actual version string of the library; return NULL if the
351 condition is not met. If NULL is passed to this function no
352 check is done and only the version string is returned.</p>
353 </div>
354 </div>
355 <div class="refsect2">
356 <a name="oath-strerror"></a><h3>oath_strerror ()</h3>
357 <a class="indexterm" name="id-1.2.2.6.5.2"></a><pre class="programlisting">const <a class="link" href=""><span class="returnvalue">char</span></a> *
358 oath_strerror (<em class="parameter"><code><a class="link" href=""><span class="type">int</span></a> err</code></em>);</pre>
359 <p>Convert return code to human readable string explanation of the
360 reason for the particular error code.</p>
361 <p>This string can be used to output a diagnostic message to the user.</p>
362 <p>This function is one of few in the library that can be used without
363 a successful call to <a class="link" href="liboath-oath.h.html#oath-init" title="oath_init ()"><code class="function">oath_init()</code></a>.</p>
364 <div class="refsect3">
365 <a name="oath-strerror.parameters"></a><h4>Parameters</h4>
366 <div class="informaltable"><table class="informaltable" width="100%" border="0">
367 <colgroup>
368 <col width="150px" class="parameters_name">
369 <col class="parameters_description">
370 <col width="200px" class="parameters_annotations">
371 </colgroup>
372 <tbody><tr>
373 <td class="parameter_name"><p>err</p></td>
374 <td class="parameter_description"><p>liboath error code</p></td>
375 <td class="parameter_annotations"> </td>
376 </tr></tbody>
377 </table></div>
378 </div>
379 <div class="refsect3">
380 <a name="oath-strerror.returns"></a><h4>Returns</h4>
381 <p> Returns a pointer to a statically allocated string
382 containing an explanation of the error code <em class="parameter"><code>err</code></em>
383 .</p>
384 </div>
385 <p class="since">Since: <a class="link" href="api-index-1-8-0.html#api-index-1.8.0">1.8.0</a></p>
386 </div>
387 <div class="refsect2">
388 <a name="oath-strerror-name"></a><h3>oath_strerror_name ()</h3>
389 <a class="indexterm" name="id-1.2.2.6.6.2"></a><pre class="programlisting">const <a class="link" href=""><span class="returnvalue">char</span></a> *
390 oath_strerror_name (<em class="parameter"><code><a class="link" href=""><span class="type">int</span></a> err</code></em>);</pre>
391 <p>Convert return code to human readable string representing the error
392 code symbol itself. For example, oath_strerror_name(<a class="link" href="liboath-oath.h.html#OATH-OK:CAPS"><code class="literal">OATH_OK</code></a>)
393 returns the string "OATH_OK".</p>
394 <p>This string can be used to output a diagnostic message to the user.</p>
395 <p>This function is one of few in the library that can be used without
396 a successful call to <a class="link" href="liboath-oath.h.html#oath-init" title="oath_init ()"><code class="function">oath_init()</code></a>.</p>
397 <div class="refsect3">
398 <a name="oath-strerror-name.parameters"></a><h4>Parameters</h4>
399 <div class="informaltable"><table class="informaltable" width="100%" border="0">
400 <colgroup>
401 <col width="150px" class="parameters_name">
402 <col class="parameters_description">
403 <col width="200px" class="parameters_annotations">
404 </colgroup>
405 <tbody><tr>
406 <td class="parameter_name"><p>err</p></td>
407 <td class="parameter_description"><p>liboath error code</p></td>
408 <td class="parameter_annotations"> </td>
409 </tr></tbody>
410 </table></div>
411 </div>
412 <div class="refsect3">
413 <a name="oath-strerror-name.returns"></a><h4>Returns</h4>
414 <p> Returns a pointer to a statically allocated string
415 containing a string version of the error code <em class="parameter"><code>err</code></em>
416 , or NULL if
417 the error code is not known.</p>
418 </div>
419 <p class="since">Since: <a class="link" href="api-index-1-8-0.html#api-index-1.8.0">1.8.0</a></p>
420 </div>
421 <div class="refsect2">
422 <a name="oath-hex2bin"></a><h3>oath_hex2bin ()</h3>
423 <a class="indexterm" name="id-1.2.2.6.7.2"></a><pre class="programlisting"><a class="link" href=""><span class="returnvalue">int</span></a>
424 oath_hex2bin (<em class="parameter"><code>const <a class="link" href=""><span class="type">char</span></a> *hexstr</code></em>,
425 <em class="parameter"><code><a class="link" href=""><span class="type">char</span></a> *binstr</code></em>,
426 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> *binlen</code></em>);</pre>
427 <p>Convert string with hex data to binary data.</p>
428 <p>Non-hexadecimal data are not ignored but instead will lead to an
429 <a class="link" href="liboath-oath.h.html#OATH-INVALID-HEX:CAPS"><code class="literal">OATH_INVALID_HEX</code></a> error.</p>
430 <p>If <em class="parameter"><code>binstr</code></em>
431 is NULL, then <em class="parameter"><code>binlen</code></em>
432 will be populated with the
433 necessary length. If the <em class="parameter"><code>binstr</code></em>
434 buffer is too small,
435 <a class="link" href="liboath-oath.h.html#OATH-TOO-SMALL-BUFFER:CAPS"><code class="literal">OATH_TOO_SMALL_BUFFER</code></a> is returned and <em class="parameter"><code>binlen</code></em>
436 will contain the
437 necessary length.</p>
438 <div class="refsect3">
439 <a name="oath-hex2bin.parameters"></a><h4>Parameters</h4>
440 <div class="informaltable"><table class="informaltable" width="100%" border="0">
441 <colgroup>
442 <col width="150px" class="parameters_name">
443 <col class="parameters_description">
444 <col width="200px" class="parameters_annotations">
445 </colgroup>
446 <tbody>
447 <tr>
448 <td class="parameter_name"><p>hexstr</p></td>
449 <td class="parameter_description"><p>input string with hex data</p></td>
450 <td class="parameter_annotations"> </td>
451 </tr>
452 <tr>
453 <td class="parameter_name"><p>binstr</p></td>
454 <td class="parameter_description"><p>output string that holds binary data, or NULL</p></td>
455 <td class="parameter_annotations"> </td>
456 </tr>
457 <tr>
458 <td class="parameter_name"><p>binlen</p></td>
459 <td class="parameter_description"><p>output variable holding needed length of <em class="parameter"><code>binstr</code></em>
460 </p></td>
461 <td class="parameter_annotations"> </td>
462 </tr>
463 </tbody>
464 </table></div>
465 </div>
466 <div class="refsect3">
467 <a name="oath-hex2bin.returns"></a><h4>Returns</h4>
468 <p> On success, <a class="link" href="liboath-oath.h.html#OATH-OK:CAPS"><code class="literal">OATH_OK</code></a> (zero) is returned, otherwise an
469 error code is returned.</p>
470 </div>
471 </div>
472 <div class="refsect2">
473 <a name="oath-bin2hex"></a><h3>oath_bin2hex ()</h3>
474 <a class="indexterm" name="id-1.2.2.6.8.2"></a><pre class="programlisting"><a class="link" href=""><span class="returnvalue">void</span></a>
475 oath_bin2hex (<em class="parameter"><code>const <a class="link" href=""><span class="type">char</span></a> *binstr</code></em>,
476 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> binlen</code></em>,
477 <em class="parameter"><code><a class="link" href=""><span class="type">char</span></a> *hexstr</code></em>);</pre>
478 <p>Convert binary data to NUL-terminated string with hex data. The
479 output <em class="parameter"><code>hexstr</code></em>
480 is allocated by the caller and must have room for at
481 least 2*<em class="parameter"><code>binlen</code></em>
482 +1, to make room for the encoded data and the
483 terminating NUL byte.</p>
484 <div class="refsect3">
485 <a name="oath-bin2hex.parameters"></a><h4>Parameters</h4>
486 <div class="informaltable"><table class="informaltable" width="100%" border="0">
487 <colgroup>
488 <col width="150px" class="parameters_name">
489 <col class="parameters_description">
490 <col width="200px" class="parameters_annotations">
491 </colgroup>
492 <tbody>
493 <tr>
494 <td class="parameter_name"><p>binstr</p></td>
495 <td class="parameter_description"><p>input binary data</p></td>
496 <td class="parameter_annotations"> </td>
497 </tr>
498 <tr>
499 <td class="parameter_name"><p>binlen</p></td>
500 <td class="parameter_description"><p>length of input binary data <em class="parameter"><code>binstr</code></em>
501 </p></td>
502 <td class="parameter_annotations"> </td>
503 </tr>
504 <tr>
505 <td class="parameter_name"><p>hexstr</p></td>
506 <td class="parameter_description"><p>output string with hex data, must have room for 2*<em class="parameter"><code>binlen</code></em>
507 +1.</p></td>
508 <td class="parameter_annotations"> </td>
509 </tr>
510 </tbody>
511 </table></div>
512 </div>
513 <p class="since">Since: <a class="link" href="api-index-1-12-0.html#api-index-1.12.0">1.12.0</a></p>
514 </div>
515 <div class="refsect2">
516 <a name="oath-base32-decode"></a><h3>oath_base32_decode ()</h3>
517 <a class="indexterm" name="id-1.2.2.6.9.2"></a><pre class="programlisting"><a class="link" href=""><span class="returnvalue">int</span></a>
518 oath_base32_decode (<em class="parameter"><code>const <a class="link" href=""><span class="type">char</span></a> *in</code></em>,
519 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> inlen</code></em>,
520 <em class="parameter"><code><a class="link" href=""><span class="type">char</span></a> **out</code></em>,
521 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> *outlen</code></em>);</pre>
522 <p>Decode a base32 encoded string into binary data.</p>
523 <p>Space characters are ignored and pad characters are added if
524 needed. Non-base32 data are not ignored but instead will lead to
525 an <a class="link" href="liboath-oath.h.html#OATH-INVALID-BASE32:CAPS"><code class="literal">OATH_INVALID_BASE32</code></a> error.</p>
526 <p>The <em class="parameter"><code>in</code></em>
527 parameter should contain <em class="parameter"><code>inlen</code></em>
528 bytes of base32 encoded
529 data. The function allocates a new string in *<em class="parameter"><code>out</code></em>
530 to hold the
531 decoded data, and sets *<em class="parameter"><code>outlen</code></em>
532 to the length of the data.</p>
533 <p>If <em class="parameter"><code>out</code></em>
534 is NULL, then *<em class="parameter"><code>outlen</code></em>
535 will be set to what would have been
536 the length of *<em class="parameter"><code>out</code></em>
537 on successful encoding.</p>
538 <p>If the caller is not interested in knowing the length of the output
539 data <em class="parameter"><code>out</code></em>
540 , then <em class="parameter"><code>outlen</code></em>
541 may be set to NULL.</p>
542 <p>It is permitted but useless to have both <em class="parameter"><code>out</code></em>
543 and <em class="parameter"><code>outlen</code></em>
544 NULL.</p>
545 <div class="refsect3">
546 <a name="oath-base32-decode.parameters"></a><h4>Parameters</h4>
547 <div class="informaltable"><table class="informaltable" width="100%" border="0">
548 <colgroup>
549 <col width="150px" class="parameters_name">
550 <col class="parameters_description">
551 <col width="200px" class="parameters_annotations">
552 </colgroup>
553 <tbody>
554 <tr>
555 <td class="parameter_name"><p>in</p></td>
556 <td class="parameter_description"><p>input string with base32 encoded data of length <em class="parameter"><code>inlen</code></em>
557 </p></td>
558 <td class="parameter_annotations"> </td>
559 </tr>
560 <tr>
561 <td class="parameter_name"><p>inlen</p></td>
562 <td class="parameter_description"><p>length of input base32 string <em class="parameter"><code>in</code></em>
563 </p></td>
564 <td class="parameter_annotations"> </td>
565 </tr>
566 <tr>
567 <td class="parameter_name"><p>out</p></td>
568 <td class="parameter_description"><p>pointer to output variable for binary data of length <em class="parameter"><code>outlen</code></em>
569 , or NULL</p></td>
570 <td class="parameter_annotations"> </td>
571 </tr>
572 <tr>
573 <td class="parameter_name"><p>outlen</p></td>
574 <td class="parameter_description"><p>pointer to output variable holding length of <em class="parameter"><code>out</code></em>
575 , or NULL</p></td>
576 <td class="parameter_annotations"> </td>
577 </tr>
578 </tbody>
579 </table></div>
580 </div>
581 <div class="refsect3">
582 <a name="oath-base32-decode.returns"></a><h4>Returns</h4>
583 <p> On success <a class="link" href="liboath-oath.h.html#OATH-OK:CAPS"><code class="literal">OATH_OK</code></a> (zero) is returned,
584 <a class="link" href="liboath-oath.h.html#OATH-INVALID-BASE32:CAPS"><code class="literal">OATH_INVALID_BASE32</code></a> is returned if the input contains non-base32
585 characters, and <a class="link" href="liboath-oath.h.html#OATH-MALLOC-ERROR:CAPS"><code class="literal">OATH_MALLOC_ERROR</code></a> is returned on memory allocation
586 errors.</p>
587 </div>
588 <p class="since">Since: <a class="link" href="api-index-1-12-0.html#api-index-1.12.0">1.12.0</a></p>
589 </div>
590 <div class="refsect2">
591 <a name="oath-base32-encode"></a><h3>oath_base32_encode ()</h3>
592 <a class="indexterm" name="id-1.2.2.6.10.2"></a><pre class="programlisting"><a class="link" href=""><span class="returnvalue">int</span></a>
593 oath_base32_encode (<em class="parameter"><code>const <a class="link" href=""><span class="type">char</span></a> *in</code></em>,
594 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> inlen</code></em>,
595 <em class="parameter"><code><a class="link" href=""><span class="type">char</span></a> **out</code></em>,
596 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> *outlen</code></em>);</pre>
597 <p>Encode binary data into a string with base32 data.</p>
598 <p>The <em class="parameter"><code>in</code></em>
599 parameter should contain <em class="parameter"><code>inlen</code></em>
600 bytes of data to encode.
601 The function allocates a new string in *<em class="parameter"><code>out</code></em>
602 to hold the encoded
603 data, and sets *<em class="parameter"><code>outlen</code></em>
604 to the length of the data. The output
605 string *<em class="parameter"><code>out</code></em>
606 is zero-terminated (ASCII NUL), but the NUL is not
607 counted in *<em class="parameter"><code>outlen</code></em>
608 .</p>
609 <p>If <em class="parameter"><code>out</code></em>
610 is NULL, then *<em class="parameter"><code>outlen</code></em>
611 will be set to what would have been
612 the length of *<em class="parameter"><code>out</code></em>
613 on successful encoding.</p>
614 <p>If the caller is not interested in knowing the length of the output
615 data <em class="parameter"><code>out</code></em>
616 , then <em class="parameter"><code>outlen</code></em>
617 may be set to NULL.</p>
618 <p>It is permitted but useless to have both <em class="parameter"><code>out</code></em>
619 and <em class="parameter"><code>outlen</code></em>
620 NULL.</p>
621 <div class="refsect3">
622 <a name="oath-base32-encode.parameters"></a><h4>Parameters</h4>
623 <div class="informaltable"><table class="informaltable" width="100%" border="0">
624 <colgroup>
625 <col width="150px" class="parameters_name">
626 <col class="parameters_description">
627 <col width="200px" class="parameters_annotations">
628 </colgroup>
629 <tbody>
630 <tr>
631 <td class="parameter_name"><p>in</p></td>
632 <td class="parameter_description"><p>input string with binary data of length <em class="parameter"><code>inlen</code></em>
633 </p></td>
634 <td class="parameter_annotations"> </td>
635 </tr>
636 <tr>
637 <td class="parameter_name"><p>inlen</p></td>
638 <td class="parameter_description"><p>length of input data <em class="parameter"><code>in</code></em>
639 </p></td>
640 <td class="parameter_annotations"> </td>
641 </tr>
642 <tr>
643 <td class="parameter_name"><p>out</p></td>
644 <td class="parameter_description"><p>pointer to newly allocated output string of length <em class="parameter"><code>outlen</code></em>
645 , or NULL</p></td>
646 <td class="parameter_annotations"> </td>
647 </tr>
648 <tr>
649 <td class="parameter_name"><p>outlen</p></td>
650 <td class="parameter_description"><p>pointer to output variable holding length of <em class="parameter"><code>out</code></em>
651 , or NULL</p></td>
652 <td class="parameter_annotations"> </td>
653 </tr>
654 </tbody>
655 </table></div>
656 </div>
657 <div class="refsect3">
658 <a name="oath-base32-encode.returns"></a><h4>Returns</h4>
659 <p> On success <a class="link" href="liboath-oath.h.html#OATH-OK:CAPS"><code class="literal">OATH_OK</code></a> (zero) is returned,
660 <a class="link" href="liboath-oath.h.html#OATH-BASE32-OVERFLOW:CAPS"><code class="literal">OATH_BASE32_OVERFLOW</code></a> is returned if the output would be too large
661 to store, and <a class="link" href="liboath-oath.h.html#OATH-MALLOC-ERROR:CAPS"><code class="literal">OATH_MALLOC_ERROR</code></a> is returned on memory allocation
662 errors.</p>
663 </div>
664 <p class="since">Since: <a class="link" href="api-index-1-12-0.html#api-index-1.12.0">1.12.0</a></p>
665 </div>
666 <div class="refsect2">
667 <a name="OATH-HOTP-LENGTH:CAPS"></a><h3>OATH_HOTP_LENGTH()</h3>
668 <a class="indexterm" name="id-1.2.2.6.11.2"></a><pre class="programlisting"># define OATH_HOTP_LENGTH(digits, checksum) (digits + (checksum ? 1 : 0))
669 </pre>
670 <p>Pre-processor macro to get length of a OTP string.</p>
671 <div class="refsect3">
672 <a name="OATH-HOTP-LENGTH.parameters"></a><h4>Parameters</h4>
673 <div class="informaltable"><table class="informaltable" width="100%" border="0">
674 <colgroup>
675 <col width="150px" class="parameters_name">
676 <col class="parameters_description">
677 <col width="200px" class="parameters_annotations">
678 </colgroup>
679 <tbody>
680 <tr>
681 <td class="parameter_name"><p>digits</p></td>
682 <td class="parameter_description"><p>number of requested digits in the OTP, excluding checksum</p></td>
683 <td class="parameter_annotations"> </td>
684 </tr>
685 <tr>
686 <td class="parameter_name"><p>checksum</p></td>
687 <td class="parameter_description"><p>whether to add a checksum digit or not</p></td>
688 <td class="parameter_annotations"> </td>
689 </tr>
690 </tbody>
691 </table></div>
692 </div>
693 <div class="refsect3">
694 <a name="OATH-HOTP-LENGTH.returns"></a><h4>Returns</h4>
695 <p> Length of generated one-time password.</p>
696 </div>
697 </div>
698 <div class="refsect2">
699 <a name="oath-hotp-generate"></a><h3>oath_hotp_generate ()</h3>
700 <a class="indexterm" name="id-1.2.2.6.12.2"></a><pre class="programlisting"><a class="link" href=""><span class="returnvalue">int</span></a>
701 oath_hotp_generate (<em class="parameter"><code>const <a class="link" href=""><span class="type">char</span></a> *secret</code></em>,
702 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> secret_length</code></em>,
703 <em class="parameter"><code><a class="link" href=""><span class="type">uint64_t</span></a> moving_factor</code></em>,
704 <em class="parameter"><code><a class="link" href=""><span class="type">unsigned </span></a> digits</code></em>,
705 <em class="parameter"><code><a class="link" href=""><span class="type">bool</span></a> add_checksum</code></em>,
706 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> truncation_offset</code></em>,
707 <em class="parameter"><code><a class="link" href=""><span class="type">char</span></a> *output_otp</code></em>);</pre>
708 <p>Generate a one-time-password using the HOTP algorithm as described
709 in RFC 4226.</p>
710 <p>Use a value of <a class="link" href="liboath-oath.h.html#OATH-HOTP-DYNAMIC-TRUNCATION:CAPS" title="OATH_HOTP_DYNAMIC_TRUNCATION"><code class="literal">OATH_HOTP_DYNAMIC_TRUNCATION</code></a> for <em class="parameter"><code>truncation_offset</code></em>
711
712 unless you really need a specific truncation offset.</p>
713 <p>To find out the size of the OTP you may use the <a class="link" href="liboath-oath.h.html#OATH-HOTP-LENGTH:CAPS" title="OATH_HOTP_LENGTH()"><code class="function">OATH_HOTP_LENGTH()</code></a>
714 macro. The <em class="parameter"><code>output_otp</code></em>
715 buffer must be have room for that length
716 plus one for the terminating NUL.</p>
717 <p>Currently only values 6, 7 and 8 for <em class="parameter"><code>digits</code></em>
718 are supported, and the
719 <em class="parameter"><code>add_checksum</code></em>
720 value is ignored. These restrictions may be lifted
721 in future versions, although some limitations are inherent in the
722 protocol.</p>
723 <div class="refsect3">
724 <a name="oath-hotp-generate.parameters"></a><h4>Parameters</h4>
725 <div class="informaltable"><table class="informaltable" width="100%" border="0">
726 <colgroup>
727 <col width="150px" class="parameters_name">
728 <col class="parameters_description">
729 <col width="200px" class="parameters_annotations">
730 </colgroup>
731 <tbody>
732 <tr>
733 <td class="parameter_name"><p>secret</p></td>
734 <td class="parameter_description"><p>the shared secret string</p></td>
735 <td class="parameter_annotations"> </td>
736 </tr>
737 <tr>
738 <td class="parameter_name"><p>secret_length</p></td>
739 <td class="parameter_description"><p>length of <em class="parameter"><code>secret</code></em>
740 </p></td>
741 <td class="parameter_annotations"> </td>
742 </tr>
743 <tr>
744 <td class="parameter_name"><p>moving_factor</p></td>
745 <td class="parameter_description"><p>a counter indicating the current OTP to generate</p></td>
746 <td class="parameter_annotations"> </td>
747 </tr>
748 <tr>
749 <td class="parameter_name"><p>digits</p></td>
750 <td class="parameter_description"><p>number of requested digits in the OTP, excluding checksum</p></td>
751 <td class="parameter_annotations"> </td>
752 </tr>
753 <tr>
754 <td class="parameter_name"><p>add_checksum</p></td>
755 <td class="parameter_description"><p>whether to add a checksum digit or not</p></td>
756 <td class="parameter_annotations"> </td>
757 </tr>
758 <tr>
759 <td class="parameter_name"><p>truncation_offset</p></td>
760 <td class="parameter_description"><p>use a specific truncation offset</p></td>
761 <td class="parameter_annotations"> </td>
762 </tr>
763 <tr>
764 <td class="parameter_name"><p>output_otp</p></td>
765 <td class="parameter_description"><p>output buffer, must have room for the output OTP plus zero</p></td>
766 <td class="parameter_annotations"> </td>
767 </tr>
768 </tbody>
769 </table></div>
770 </div>
771 <div class="refsect3">
772 <a name="oath-hotp-generate.returns"></a><h4>Returns</h4>
773 <p> On success, <a class="link" href="liboath-oath.h.html#OATH-OK:CAPS"><code class="literal">OATH_OK</code></a> (zero) is returned, otherwise an
774 error code is returned.</p>
775 </div>
776 </div>
777 <div class="refsect2">
778 <a name="oath-hotp-validate"></a><h3>oath_hotp_validate ()</h3>
779 <a class="indexterm" name="id-1.2.2.6.13.2"></a><pre class="programlisting"><a class="link" href=""><span class="returnvalue">int</span></a>
780 oath_hotp_validate (<em class="parameter"><code>const <a class="link" href=""><span class="type">char</span></a> *secret</code></em>,
781 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> secret_length</code></em>,
782 <em class="parameter"><code><a class="link" href=""><span class="type">uint64_t</span></a> start_moving_factor</code></em>,
783 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> window</code></em>,
784 <em class="parameter"><code>const <a class="link" href=""><span class="type">char</span></a> *otp</code></em>);</pre>
785 <p>Validate an OTP according to OATH HOTP algorithm per RFC 4226.</p>
786 <p>Currently only OTP lengths of 6, 7 or 8 digits are supported. This
787 restrictions may be lifted in future versions, although some
788 limitations are inherent in the protocol.</p>
789 <div class="refsect3">
790 <a name="oath-hotp-validate.parameters"></a><h4>Parameters</h4>
791 <div class="informaltable"><table class="informaltable" width="100%" border="0">
792 <colgroup>
793 <col width="150px" class="parameters_name">
794 <col class="parameters_description">
795 <col width="200px" class="parameters_annotations">
796 </colgroup>
797 <tbody>
798 <tr>
799 <td class="parameter_name"><p>secret</p></td>
800 <td class="parameter_description"><p>the shared secret string</p></td>
801 <td class="parameter_annotations"> </td>
802 </tr>
803 <tr>
804 <td class="parameter_name"><p>secret_length</p></td>
805 <td class="parameter_description"><p>length of <em class="parameter"><code>secret</code></em>
806 </p></td>
807 <td class="parameter_annotations"> </td>
808 </tr>
809 <tr>
810 <td class="parameter_name"><p>start_moving_factor</p></td>
811 <td class="parameter_description"><p>start counter in OTP stream</p></td>
812 <td class="parameter_annotations"> </td>
813 </tr>
814 <tr>
815 <td class="parameter_name"><p>window</p></td>
816 <td class="parameter_description"><p>how many OTPs after start counter to test</p></td>
817 <td class="parameter_annotations"> </td>
818 </tr>
819 <tr>
820 <td class="parameter_name"><p>otp</p></td>
821 <td class="parameter_description"><p>the OTP to validate.</p></td>
822 <td class="parameter_annotations"> </td>
823 </tr>
824 </tbody>
825 </table></div>
826 </div>
827 <div class="refsect3">
828 <a name="oath-hotp-validate.returns"></a><h4>Returns</h4>
829 <p> Returns position in OTP window (zero is first position),
830 or <a class="link" href="liboath-oath.h.html#OATH-INVALID-OTP:CAPS"><code class="literal">OATH_INVALID_OTP</code></a> if no OTP was found in OTP window, or an
831 error code.</p>
832 </div>
833 </div>
834 <div class="refsect2">
835 <a name="oath-validate-strcmp-function"></a><h3>oath_validate_strcmp_function ()</h3>
836 <a class="indexterm" name="id-1.2.2.6.14.2"></a><pre class="programlisting"><a class="link" href=""><span class="returnvalue">int</span></a>
837 <span class="c_punctuation">(</span>*oath_validate_strcmp_function<span class="c_punctuation">)</span> (<em class="parameter"><code><a class="link" href=""><span class="type">void</span></a> *handle</code></em>,
838 <em class="parameter"><code>const <a class="link" href=""><span class="type">char</span></a> *test_otp</code></em>);</pre>
839 <p>Prototype of strcmp-like function that will be called by
840 <a class="link" href="liboath-oath.h.html#oath-hotp-validate-callback" title="oath_hotp_validate_callback ()"><code class="function">oath_hotp_validate_callback()</code></a> or <a class="link" href="liboath-oath.h.html#oath-totp-validate-callback" title="oath_totp_validate_callback ()"><code class="function">oath_totp_validate_callback()</code></a> to
841 validate OTPs.</p>
842 <p>The function should be similar to strcmp in that it return 0 only
843 on matches. It differs by permitting use of negative return codes
844 as indication of internal failures in the callback. Positive
845 values indicate OTP mismatch.</p>
846 <p>This callback interface is useful when you cannot compare OTPs
847 directly using normal strcmp, but instead for example only have a
848 hashed OTP. You would then typically pass in the hashed OTP in the
849 <em class="parameter"><code>strcmp_handle</code></em>
850 and let your implementation of <em class="parameter"><code>oath_strcmp</code></em>
851 hash the
852 test_otp OTP using the same hash, and then compare the results.</p>
853 <div class="refsect3">
854 <a name="oath-validate-strcmp-function.parameters"></a><h4>Parameters</h4>
855 <div class="informaltable"><table class="informaltable" width="100%" border="0">
856 <colgroup>
857 <col width="150px" class="parameters_name">
858 <col class="parameters_description">
859 <col width="200px" class="parameters_annotations">
860 </colgroup>
861 <tbody>
862 <tr>
863 <td class="parameter_name"><p>handle</p></td>
864 <td class="parameter_description"><p>caller handle as passed to <a class="link" href="liboath-oath.h.html#oath-hotp-validate-callback" title="oath_hotp_validate_callback ()"><code class="function">oath_hotp_validate_callback()</code></a></p></td>
865 <td class="parameter_annotations"> </td>
866 </tr>
867 <tr>
868 <td class="parameter_name"><p>test_otp</p></td>
869 <td class="parameter_description"><p>OTP to match against.</p></td>
870 <td class="parameter_annotations"> </td>
871 </tr>
872 </tbody>
873 </table></div>
874 </div>
875 <div class="refsect3">
876 <a name="oath-validate-strcmp-function.returns"></a><h4>Returns</h4>
877 <p> 0 if and only if <em class="parameter"><code>test_otp</code></em>
878 is identical to the OTP to
879 be validated. Negative value if an internal failure occurs.
880 Positive value if the test_otp simply doesn't match.</p>
881 </div>
882 <p class="since">Since: <a class="link" href="api-index-1-6-0.html#api-index-1.6.0">1.6.0</a></p>
883 </div>
884 <div class="refsect2">
885 <a name="oath-hotp-validate-callback"></a><h3>oath_hotp_validate_callback ()</h3>
886 <a class="indexterm" name="id-1.2.2.6.15.2"></a><pre class="programlisting"><a class="link" href=""><span class="returnvalue">int</span></a>
887 oath_hotp_validate_callback (<em class="parameter"><code>const <a class="link" href=""><span class="type">char</span></a> *secret</code></em>,
888 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> secret_length</code></em>,
889 <em class="parameter"><code><a class="link" href=""><span class="type">uint64_t</span></a> start_moving_factor</code></em>,
890 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> window</code></em>,
891 <em class="parameter"><code><a class="link" href=""><span class="type">unsigned </span></a> digits</code></em>,
892 <em class="parameter"><code><a class="link" href="liboath-oath.h.html#oath-validate-strcmp-function" title="oath_validate_strcmp_function ()"><span class="type">oath_validate_strcmp_function</span></a> strcmp_otp</code></em>,
893 <em class="parameter"><code><a class="link" href=""><span class="type">void</span></a> *strcmp_handle</code></em>);</pre>
894 <p>Validate an OTP according to OATH HOTP algorithm per RFC 4226.</p>
895 <p>Validation is implemented by generating a number of potential OTPs
896 and performing a call to the <em class="parameter"><code>strcmp_otp</code></em>
897 function, to compare the
898 potential OTP against the given <em class="parameter"><code>otp</code></em>
899 . It has the following
900 prototype:</p>
901 <p>int (*oath_validate_strcmp_function) (void *handle, const char *test_otp);</p>
902 <p>The function should be similar to strcmp in that it return 0 only
903 on matches. It differs by permitting use of negative return codes
904 as indication of internal failures in the callback. Positive
905 values indicate OTP mismatch.</p>
906 <p>This callback interface is useful when you cannot compare OTPs
907 directly using normal strcmp, but instead for example only have a
908 hashed OTP. You would then typically pass in the hashed OTP in the
909 <em class="parameter"><code>strcmp_handle</code></em>
910 and let your implementation of <em class="parameter"><code>strcmp_otp</code></em>
911 hash the
912 test_otp OTP using the same hash, and then compare the results.</p>
913 <p>Currently only OTP lengths of 6, 7 or 8 digits are supported. This
914 restrictions may be lifted in future versions, although some
915 limitations are inherent in the protocol.</p>
916 <div class="refsect3">
917 <a name="oath-hotp-validate-callback.parameters"></a><h4>Parameters</h4>
918 <div class="informaltable"><table class="informaltable" width="100%" border="0">
919 <colgroup>
920 <col width="150px" class="parameters_name">
921 <col class="parameters_description">
922 <col width="200px" class="parameters_annotations">
923 </colgroup>
924 <tbody>
925 <tr>
926 <td class="parameter_name"><p>secret</p></td>
927 <td class="parameter_description"><p>the shared secret string</p></td>
928 <td class="parameter_annotations"> </td>
929 </tr>
930 <tr>
931 <td class="parameter_name"><p>secret_length</p></td>
932 <td class="parameter_description"><p>length of <em class="parameter"><code>secret</code></em>
933 </p></td>
934 <td class="parameter_annotations"> </td>
935 </tr>
936 <tr>
937 <td class="parameter_name"><p>start_moving_factor</p></td>
938 <td class="parameter_description"><p>start counter in OTP stream</p></td>
939 <td class="parameter_annotations"> </td>
940 </tr>
941 <tr>
942 <td class="parameter_name"><p>window</p></td>
943 <td class="parameter_description"><p>how many OTPs after start counter to test</p></td>
944 <td class="parameter_annotations"> </td>
945 </tr>
946 <tr>
947 <td class="parameter_name"><p>digits</p></td>
948 <td class="parameter_description"><p>number of requested digits in the OTP</p></td>
949 <td class="parameter_annotations"> </td>
950 </tr>
951 <tr>
952 <td class="parameter_name"><p>strcmp_otp</p></td>
953 <td class="parameter_description"><p>function pointer to a strcmp-like function.</p></td>
954 <td class="parameter_annotations"> </td>
955 </tr>
956 <tr>
957 <td class="parameter_name"><p>strcmp_handle</p></td>
958 <td class="parameter_description"><p>caller handle to be passed on to <em class="parameter"><code>strcmp_otp</code></em>
959 .</p></td>
960 <td class="parameter_annotations"> </td>
961 </tr>
962 </tbody>
963 </table></div>
964 </div>
965 <div class="refsect3">
966 <a name="oath-hotp-validate-callback.returns"></a><h4>Returns</h4>
967 <p> Returns position in OTP window (zero is first position),
968 or <a class="link" href="liboath-oath.h.html#OATH-INVALID-OTP:CAPS"><code class="literal">OATH_INVALID_OTP</code></a> if no OTP was found in OTP window, or an
969 error code.</p>
970 </div>
971 <p class="since">Since: <a class="link" href="api-index-1-4-0.html#api-index-1.4.0">1.4.0</a></p>
972 </div>
973 <div class="refsect2">
974 <a name="oath-totp-generate"></a><h3>oath_totp_generate ()</h3>
975 <a class="indexterm" name="id-1.2.2.6.16.2"></a><pre class="programlisting"><a class="link" href=""><span class="returnvalue">int</span></a>
976 oath_totp_generate (<em class="parameter"><code>const <a class="link" href=""><span class="type">char</span></a> *secret</code></em>,
977 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> secret_length</code></em>,
978 <em class="parameter"><code><a class="link" href=""><span class="type">time_t</span></a> now</code></em>,
979 <em class="parameter"><code><a class="link" href=""><span class="type">unsigned </span></a> time_step_size</code></em>,
980 <em class="parameter"><code><a class="link" href=""><span class="type">time_t</span></a> start_offset</code></em>,
981 <em class="parameter"><code><a class="link" href=""><span class="type">unsigned </span></a> digits</code></em>,
982 <em class="parameter"><code><a class="link" href=""><span class="type">char</span></a> *output_otp</code></em>);</pre>
983 <p>Generate a one-time-password using the time-variant TOTP algorithm
984 described in RFC 6238. The input parameters are taken as time
985 values.</p>
986 <p>The system parameter <em class="parameter"><code>time_step_size</code></em>
987 describes how long the time
988 window for each OTP is. The recommended value is 30 seconds, and
989 you can use the value 0 or the symbol
990 <a class="link" href="liboath-oath.h.html#OATH-TOTP-DEFAULT-TIME-STEP-SIZE:CAPS" title="OATH_TOTP_DEFAULT_TIME_STEP_SIZE"><code class="literal">OATH_TOTP_DEFAULT_TIME_STEP_SIZE</code></a> to indicate this.</p>
991 <p>The system parameter <em class="parameter"><code>start_offset</code></em>
992 denote the Unix time when time
993 steps are started to be counted. The recommended value is 0, to
994 fall back on the Unix epoch) and you can use the symbol
995 <a class="link" href="liboath-oath.h.html#OATH-TOTP-DEFAULT-START-TIME:CAPS" title="OATH_TOTP_DEFAULT_START_TIME"><code class="literal">OATH_TOTP_DEFAULT_START_TIME</code></a> to indicate this.</p>
996 <p>The <em class="parameter"><code>output_otp</code></em>
997 buffer must have room for at least <em class="parameter"><code>digits</code></em>
998
999 characters, plus one for the terminating NUL.</p>
1000 <p>Currently only values 6, 7 and 8 for <em class="parameter"><code>digits</code></em>
1001 are supported. This
1002 restriction may be lifted in future versions.</p>
1003 <div class="refsect3">
1004 <a name="oath-totp-generate.parameters"></a><h4>Parameters</h4>
1005 <div class="informaltable"><table class="informaltable" width="100%" border="0">
1006 <colgroup>
1007 <col width="150px" class="parameters_name">
1008 <col class="parameters_description">
1009 <col width="200px" class="parameters_annotations">
1010 </colgroup>
1011 <tbody>
1012 <tr>
1013 <td class="parameter_name"><p>secret</p></td>
1014 <td class="parameter_description"><p>the shared secret string</p></td>
1015 <td class="parameter_annotations"> </td>
1016 </tr>
1017 <tr>
1018 <td class="parameter_name"><p>secret_length</p></td>
1019 <td class="parameter_description"><p>length of <em class="parameter"><code>secret</code></em>
1020 </p></td>
1021 <td class="parameter_annotations"> </td>
1022 </tr>
1023 <tr>
1024 <td class="parameter_name"><p>now</p></td>
1025 <td class="parameter_description"><p>Unix time value to compute TOTP for</p></td>
1026 <td class="parameter_annotations"> </td>
1027 </tr>
1028 <tr>
1029 <td class="parameter_name"><p>time_step_size</p></td>
1030 <td class="parameter_description"><p>time step system parameter (typically 30)</p></td>
1031 <td class="parameter_annotations"> </td>
1032 </tr>
1033 <tr>
1034 <td class="parameter_name"><p>start_offset</p></td>
1035 <td class="parameter_description"><p>Unix time of when to start counting time steps (typically 0)</p></td>
1036 <td class="parameter_annotations"> </td>
1037 </tr>
1038 <tr>
1039 <td class="parameter_name"><p>digits</p></td>
1040 <td class="parameter_description"><p>number of requested digits in the OTP, excluding checksum</p></td>
1041 <td class="parameter_annotations"> </td>
1042 </tr>
1043 <tr>
1044 <td class="parameter_name"><p>output_otp</p></td>
1045 <td class="parameter_description"><p>output buffer, must have room for the output OTP plus zero</p></td>
1046 <td class="parameter_annotations"> </td>
1047 </tr>
1048 </tbody>
1049 </table></div>
1050 </div>
1051 <div class="refsect3">
1052 <a name="oath-totp-generate.returns"></a><h4>Returns</h4>
1053 <p> On success, <a class="link" href="liboath-oath.h.html#OATH-OK:CAPS"><code class="literal">OATH_OK</code></a> (zero) is returned, otherwise an
1054 error code is returned.</p>
1055 </div>
1056 <p class="since">Since: <a class="link" href="api-index-1-4-0.html#api-index-1.4.0">1.4.0</a></p>
1057 </div>
1058 <div class="refsect2">
1059 <a name="oath-totp-generate2"></a><h3>oath_totp_generate2 ()</h3>
1060 <a class="indexterm" name="id-1.2.2.6.17.2"></a><pre class="programlisting"><a class="link" href=""><span class="returnvalue">int</span></a>
1061 oath_totp_generate2 (<em class="parameter"><code>const <a class="link" href=""><span class="type">char</span></a> *secret</code></em>,
1062 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> secret_length</code></em>,
1063 <em class="parameter"><code><a class="link" href=""><span class="type">time_t</span></a> now</code></em>,
1064 <em class="parameter"><code><a class="link" href=""><span class="type">unsigned </span></a> time_step_size</code></em>,
1065 <em class="parameter"><code><a class="link" href=""><span class="type">time_t</span></a> start_offset</code></em>,
1066 <em class="parameter"><code><a class="link" href=""><span class="type">unsigned </span></a> digits</code></em>,
1067 <em class="parameter"><code><a class="link" href=""><span class="type">int</span></a> flags</code></em>,
1068 <em class="parameter"><code><a class="link" href=""><span class="type">char</span></a> *output_otp</code></em>);</pre>
1069 <p>Generate a one-time-password using the time-variant TOTP algorithm
1070 described in RFC 6238. The input parameters are taken as time
1071 values.</p>
1072 <p>The system parameter <em class="parameter"><code>time_step_size</code></em>
1073 describes how long the time
1074 window for each OTP is. The recommended value is 30 seconds, and
1075 you can use the value 0 or the symbol
1076 <a class="link" href="liboath-oath.h.html#OATH-TOTP-DEFAULT-TIME-STEP-SIZE:CAPS" title="OATH_TOTP_DEFAULT_TIME_STEP_SIZE"><code class="literal">OATH_TOTP_DEFAULT_TIME_STEP_SIZE</code></a> to indicate this.</p>
1077 <p>The system parameter <em class="parameter"><code>start_offset</code></em>
1078 denote the Unix time when time
1079 steps are started to be counted. The recommended value is 0, to
1080 fall back on the Unix epoch) and you can use the symbol
1081 <a class="link" href="liboath-oath.h.html#OATH-TOTP-DEFAULT-START-TIME:CAPS" title="OATH_TOTP_DEFAULT_START_TIME"><code class="literal">OATH_TOTP_DEFAULT_START_TIME</code></a> to indicate this.</p>
1082 <p>The <em class="parameter"><code>output_otp</code></em>
1083 buffer must have room for at least <em class="parameter"><code>digits</code></em>
1084
1085 characters, plus one for the terminating NUL.</p>
1086 <p>Currently only values 6, 7 and 8 for <em class="parameter"><code>digits</code></em>
1087 are supported. This
1088 restriction may be lifted in future versions.</p>
1089 <p>The <em class="parameter"><code>flags</code></em>
1090 parameter may be used to change the MAC function, for
1091 example <a class="link" href="liboath-oath.h.html#OATH-TOTP-HMAC-SHA256:CAPS"><code class="literal">OATH_TOTP_HMAC_SHA256</code></a> or <a class="link" href="liboath-oath.h.html#OATH-TOTP-HMAC-SHA512:CAPS"><code class="literal">OATH_TOTP_HMAC_SHA512</code></a>.</p>
1092 <div class="refsect3">
1093 <a name="oath-totp-generate2.parameters"></a><h4>Parameters</h4>
1094 <div class="informaltable"><table class="informaltable" width="100%" border="0">
1095 <colgroup>
1096 <col width="150px" class="parameters_name">
1097 <col class="parameters_description">
1098 <col width="200px" class="parameters_annotations">
1099 </colgroup>
1100 <tbody>
1101 <tr>
1102 <td class="parameter_name"><p>secret</p></td>
1103 <td class="parameter_description"><p>the shared secret string</p></td>
1104 <td class="parameter_annotations"> </td>
1105 </tr>
1106 <tr>
1107 <td class="parameter_name"><p>secret_length</p></td>
1108 <td class="parameter_description"><p>length of <em class="parameter"><code>secret</code></em>
1109 </p></td>
1110 <td class="parameter_annotations"> </td>
1111 </tr>
1112 <tr>
1113 <td class="parameter_name"><p>now</p></td>
1114 <td class="parameter_description"><p>Unix time value to compute TOTP for</p></td>
1115 <td class="parameter_annotations"> </td>
1116 </tr>
1117 <tr>
1118 <td class="parameter_name"><p>time_step_size</p></td>
1119 <td class="parameter_description"><p>time step system parameter (typically 30)</p></td>
1120 <td class="parameter_annotations"> </td>
1121 </tr>
1122 <tr>
1123 <td class="parameter_name"><p>start_offset</p></td>
1124 <td class="parameter_description"><p>Unix time of when to start counting time steps (typically 0)</p></td>
1125 <td class="parameter_annotations"> </td>
1126 </tr>
1127 <tr>
1128 <td class="parameter_name"><p>digits</p></td>
1129 <td class="parameter_description"><p>number of requested digits in the OTP, excluding checksum</p></td>
1130 <td class="parameter_annotations"> </td>
1131 </tr>
1132 <tr>
1133 <td class="parameter_name"><p>flags</p></td>
1134 <td class="parameter_description"><p>flags indicating mode, one of <a class="link" href="liboath-oath.h.html#oath-totp-flags" title="enum oath_totp_flags"><span class="type">oath_totp_flags</span></a></p></td>
1135 <td class="parameter_annotations"> </td>
1136 </tr>
1137 <tr>
1138 <td class="parameter_name"><p>output_otp</p></td>
1139 <td class="parameter_description"><p>output buffer, must have room for the output OTP plus zero</p></td>
1140 <td class="parameter_annotations"> </td>
1141 </tr>
1142 </tbody>
1143 </table></div>
1144 </div>
1145 <div class="refsect3">
1146 <a name="oath-totp-generate2.returns"></a><h4>Returns</h4>
1147 <p> On success, <a class="link" href="liboath-oath.h.html#OATH-OK:CAPS"><code class="literal">OATH_OK</code></a> (zero) is returned, otherwise an
1148 error code is returned.</p>
1149 </div>
1150 <p class="since">Since: <a class="link" href="api-index-2-6-0.html#api-index-2.6.0">2.6.0</a></p>
1151 </div>
1152 <div class="refsect2">
1153 <a name="oath-totp-validate"></a><h3>oath_totp_validate ()</h3>
1154 <a class="indexterm" name="id-1.2.2.6.18.2"></a><pre class="programlisting"><a class="link" href=""><span class="returnvalue">int</span></a>
1155 oath_totp_validate (<em class="parameter"><code>const <a class="link" href=""><span class="type">char</span></a> *secret</code></em>,
1156 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> secret_length</code></em>,
1157 <em class="parameter"><code><a class="link" href=""><span class="type">time_t</span></a> now</code></em>,
1158 <em class="parameter"><code><a class="link" href=""><span class="type">unsigned </span></a> time_step_size</code></em>,
1159 <em class="parameter"><code><a class="link" href=""><span class="type">time_t</span></a> start_offset</code></em>,
1160 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> window</code></em>,
1161 <em class="parameter"><code>const <a class="link" href=""><span class="type">char</span></a> *otp</code></em>);</pre>
1162 <p>Validate an OTP according to OATH TOTP algorithm per RFC 6238.</p>
1163 <p>Currently only OTP lengths of 6, 7 or 8 digits are supported. This
1164 restrictions may be lifted in future versions, although some
1165 limitations are inherent in the protocol.</p>
1166 <div class="refsect3">
1167 <a name="oath-totp-validate.parameters"></a><h4>Parameters</h4>
1168 <div class="informaltable"><table class="informaltable" width="100%" border="0">
1169 <colgroup>
1170 <col width="150px" class="parameters_name">
1171 <col class="parameters_description">
1172 <col width="200px" class="parameters_annotations">
1173 </colgroup>
1174 <tbody>
1175 <tr>
1176 <td class="parameter_name"><p>secret</p></td>
1177 <td class="parameter_description"><p>the shared secret string</p></td>
1178 <td class="parameter_annotations"> </td>
1179 </tr>
1180 <tr>
1181 <td class="parameter_name"><p>secret_length</p></td>
1182 <td class="parameter_description"><p>length of <em class="parameter"><code>secret</code></em>
1183 </p></td>
1184 <td class="parameter_annotations"> </td>
1185 </tr>
1186 <tr>
1187 <td class="parameter_name"><p>now</p></td>
1188 <td class="parameter_description"><p>Unix time value to validate TOTP for</p></td>
1189 <td class="parameter_annotations"> </td>
1190 </tr>
1191 <tr>
1192 <td class="parameter_name"><p>time_step_size</p></td>
1193 <td class="parameter_description"><p>time step system parameter (typically 30)</p></td>
1194 <td class="parameter_annotations"> </td>
1195 </tr>
1196 <tr>
1197 <td class="parameter_name"><p>start_offset</p></td>
1198 <td class="parameter_description"><p>Unix time of when to start counting time steps (typically 0)</p></td>
1199 <td class="parameter_annotations"> </td>
1200 </tr>
1201 <tr>
1202 <td class="parameter_name"><p>window</p></td>
1203 <td class="parameter_description"><p>how many OTPs after/before start OTP to test</p></td>
1204 <td class="parameter_annotations"> </td>
1205 </tr>
1206 <tr>
1207 <td class="parameter_name"><p>otp</p></td>
1208 <td class="parameter_description"><p>the OTP to validate.</p></td>
1209 <td class="parameter_annotations"> </td>
1210 </tr>
1211 </tbody>
1212 </table></div>
1213 </div>
1214 <div class="refsect3">
1215 <a name="oath-totp-validate.returns"></a><h4>Returns</h4>
1216 <p> Returns absolute value of position in OTP window (zero is
1217 first position), or <a class="link" href="liboath-oath.h.html#OATH-INVALID-OTP:CAPS"><code class="literal">OATH_INVALID_OTP</code></a> if no OTP was found in OTP
1218 window, or an error code.</p>
1219 </div>
1220 <p class="since">Since: <a class="link" href="api-index-1-6-0.html#api-index-1.6.0">1.6.0</a></p>
1221 </div>
1222 <div class="refsect2">
1223 <a name="oath-totp-validate-callback"></a><h3>oath_totp_validate_callback ()</h3>
1224 <a class="indexterm" name="id-1.2.2.6.19.2"></a><pre class="programlisting"><a class="link" href=""><span class="returnvalue">int</span></a>
1225 oath_totp_validate_callback (<em class="parameter"><code>const <a class="link" href=""><span class="type">char</span></a> *secret</code></em>,
1226 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> secret_length</code></em>,
1227 <em class="parameter"><code><a class="link" href=""><span class="type">time_t</span></a> now</code></em>,
1228 <em class="parameter"><code><a class="link" href=""><span class="type">unsigned </span></a> time_step_size</code></em>,
1229 <em class="parameter"><code><a class="link" href=""><span class="type">time_t</span></a> start_offset</code></em>,
1230 <em class="parameter"><code><a class="link" href=""><span class="type">unsigned </span></a> digits</code></em>,
1231 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> window</code></em>,
1232 <em class="parameter"><code><a class="link" href="liboath-oath.h.html#oath-validate-strcmp-function" title="oath_validate_strcmp_function ()"><span class="type">oath_validate_strcmp_function</span></a> strcmp_otp</code></em>,
1233 <em class="parameter"><code><a class="link" href=""><span class="type">void</span></a> *strcmp_handle</code></em>);</pre>
1234 <p>Validate an OTP according to OATH TOTP algorithm per RFC 6238.</p>
1235 <p>Validation is implemented by generating a number of potential OTPs
1236 and performing a call to the <em class="parameter"><code>strcmp_otp</code></em>
1237 function, to compare the
1238 potential OTP against the given <em class="parameter"><code>otp</code></em>
1239 . It has the following
1240 prototype:</p>
1241 <p>int (*oath_validate_strcmp_function) (void *handle, const char *test_otp);</p>
1242 <p>The function should be similar to strcmp in that it return 0 only
1243 on matches. It differs by permitting use of negative return codes
1244 as indication of internal failures in the callback. Positive
1245 values indicate OTP mismatch.</p>
1246 <p>This callback interface is useful when you cannot compare OTPs
1247 directly using normal strcmp, but instead for example only have a
1248 hashed OTP. You would then typically pass in the hashed OTP in the
1249 <em class="parameter"><code>strcmp_handle</code></em>
1250 and let your implementation of <em class="parameter"><code>strcmp_otp</code></em>
1251 hash the
1252 test_otp OTP using the same hash, and then compare the results.</p>
1253 <p>Currently only OTP lengths of 6, 7 or 8 digits are supported. This
1254 restrictions may be lifted in future versions, although some
1255 limitations are inherent in the protocol.</p>
1256 <div class="refsect3">
1257 <a name="oath-totp-validate-callback.parameters"></a><h4>Parameters</h4>
1258 <div class="informaltable"><table class="informaltable" width="100%" border="0">
1259 <colgroup>
1260 <col width="150px" class="parameters_name">
1261 <col class="parameters_description">
1262 <col width="200px" class="parameters_annotations">
1263 </colgroup>
1264 <tbody>
1265 <tr>
1266 <td class="parameter_name"><p>secret</p></td>
1267 <td class="parameter_description"><p>the shared secret string</p></td>
1268 <td class="parameter_annotations"> </td>
1269 </tr>
1270 <tr>
1271 <td class="parameter_name"><p>secret_length</p></td>
1272 <td class="parameter_description"><p>length of <em class="parameter"><code>secret</code></em>
1273 </p></td>
1274 <td class="parameter_annotations"> </td>
1275 </tr>
1276 <tr>
1277 <td class="parameter_name"><p>now</p></td>
1278 <td class="parameter_description"><p>Unix time value to compute TOTP for</p></td>
1279 <td class="parameter_annotations"> </td>
1280 </tr>
1281 <tr>
1282 <td class="parameter_name"><p>time_step_size</p></td>
1283 <td class="parameter_description"><p>time step system parameter (typically 30)</p></td>
1284 <td class="parameter_annotations"> </td>
1285 </tr>
1286 <tr>
1287 <td class="parameter_name"><p>start_offset</p></td>
1288 <td class="parameter_description"><p>Unix time of when to start counting time steps (typically 0)</p></td>
1289 <td class="parameter_annotations"> </td>
1290 </tr>
1291 <tr>
1292 <td class="parameter_name"><p>window</p></td>
1293 <td class="parameter_description"><p>how many OTPs after start counter to test</p></td>
1294 <td class="parameter_annotations"> </td>
1295 </tr>
1296 <tr>
1297 <td class="parameter_name"><p>digits</p></td>
1298 <td class="parameter_description"><p>number of requested digits in the OTP</p></td>
1299 <td class="parameter_annotations"> </td>
1300 </tr>
1301 <tr>
1302 <td class="parameter_name"><p>strcmp_otp</p></td>
1303 <td class="parameter_description"><p>function pointer to a strcmp-like function.</p></td>
1304 <td class="parameter_annotations"> </td>
1305 </tr>
1306 <tr>
1307 <td class="parameter_name"><p>strcmp_handle</p></td>
1308 <td class="parameter_description"><p>caller handle to be passed on to <em class="parameter"><code>strcmp_otp</code></em>
1309 .</p></td>
1310 <td class="parameter_annotations"> </td>
1311 </tr>
1312 </tbody>
1313 </table></div>
1314 </div>
1315 <div class="refsect3">
1316 <a name="oath-totp-validate-callback.returns"></a><h4>Returns</h4>
1317 <p> Returns position in OTP window (zero is first position),
1318 or <a class="link" href="liboath-oath.h.html#OATH-INVALID-OTP:CAPS"><code class="literal">OATH_INVALID_OTP</code></a> if no OTP was found in OTP window, or an
1319 error code.</p>
1320 </div>
1321 <p class="since">Since: <a class="link" href="api-index-1-6-0.html#api-index-1.6.0">1.6.0</a></p>
1322 </div>
1323 <div class="refsect2">
1324 <a name="oath-totp-validate2"></a><h3>oath_totp_validate2 ()</h3>
1325 <a class="indexterm" name="id-1.2.2.6.20.2"></a><pre class="programlisting"><a class="link" href=""><span class="returnvalue">int</span></a>
1326 oath_totp_validate2 (<em class="parameter"><code>const <a class="link" href=""><span class="type">char</span></a> *secret</code></em>,
1327 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> secret_length</code></em>,
1328 <em class="parameter"><code><a class="link" href=""><span class="type">time_t</span></a> now</code></em>,
1329 <em class="parameter"><code><a class="link" href=""><span class="type">unsigned </span></a> time_step_size</code></em>,
1330 <em class="parameter"><code><a class="link" href=""><span class="type">time_t</span></a> start_offset</code></em>,
1331 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> window</code></em>,
1332 <em class="parameter"><code><a class="link" href=""><span class="type">int</span></a> *otp_pos</code></em>,
1333 <em class="parameter"><code>const <a class="link" href=""><span class="type">char</span></a> *otp</code></em>);</pre>
1334 <p>Validate an OTP according to OATH TOTP algorithm per RFC 6238.</p>
1335 <p>Currently only OTP lengths of 6, 7 or 8 digits are supported. This
1336 restrictions may be lifted in future versions, although some
1337 limitations are inherent in the protocol.</p>
1338 <div class="refsect3">
1339 <a name="oath-totp-validate2.parameters"></a><h4>Parameters</h4>
1340 <div class="informaltable"><table class="informaltable" width="100%" border="0">
1341 <colgroup>
1342 <col width="150px" class="parameters_name">
1343 <col class="parameters_description">
1344 <col width="200px" class="parameters_annotations">
1345 </colgroup>
1346 <tbody>
1347 <tr>
1348 <td class="parameter_name"><p>secret</p></td>
1349 <td class="parameter_description"><p>the shared secret string</p></td>
1350 <td class="parameter_annotations"> </td>
1351 </tr>
1352 <tr>
1353 <td class="parameter_name"><p>secret_length</p></td>
1354 <td class="parameter_description"><p>length of <em class="parameter"><code>secret</code></em>
1355 </p></td>
1356 <td class="parameter_annotations"> </td>
1357 </tr>
1358 <tr>
1359 <td class="parameter_name"><p>now</p></td>
1360 <td class="parameter_description"><p>Unix time value to validate TOTP for</p></td>
1361 <td class="parameter_annotations"> </td>
1362 </tr>
1363 <tr>
1364 <td class="parameter_name"><p>time_step_size</p></td>
1365 <td class="parameter_description"><p>time step system parameter (typically 30)</p></td>
1366 <td class="parameter_annotations"> </td>
1367 </tr>
1368 <tr>
1369 <td class="parameter_name"><p>start_offset</p></td>
1370 <td class="parameter_description"><p>Unix time of when to start counting time steps (typically 0)</p></td>
1371 <td class="parameter_annotations"> </td>
1372 </tr>
1373 <tr>
1374 <td class="parameter_name"><p>window</p></td>
1375 <td class="parameter_description"><p>how many OTPs after/before start OTP to test</p></td>
1376 <td class="parameter_annotations"> </td>
1377 </tr>
1378 <tr>
1379 <td class="parameter_name"><p>otp_pos</p></td>
1380 <td class="parameter_description"><p>output search position in search window (may be NULL).</p></td>
1381 <td class="parameter_annotations"> </td>
1382 </tr>
1383 <tr>
1384 <td class="parameter_name"><p>otp</p></td>
1385 <td class="parameter_description"><p>the OTP to validate.</p></td>
1386 <td class="parameter_annotations"> </td>
1387 </tr>
1388 </tbody>
1389 </table></div>
1390 </div>
1391 <div class="refsect3">
1392 <a name="oath-totp-validate2.returns"></a><h4>Returns</h4>
1393 <p> Returns absolute value of position in OTP window (zero is
1394 first position), or <a class="link" href="liboath-oath.h.html#OATH-INVALID-OTP:CAPS"><code class="literal">OATH_INVALID_OTP</code></a> if no OTP was found in OTP
1395 window, or an error code.</p>
1396 </div>
1397 <p class="since">Since: <a class="link" href="api-index-1-10-0.html#api-index-1.10.0">1.10.0</a></p>
1398 </div>
1399 <div class="refsect2">
1400 <a name="oath-totp-validate2-callback"></a><h3>oath_totp_validate2_callback ()</h3>
1401 <a class="indexterm" name="id-1.2.2.6.21.2"></a><pre class="programlisting"><a class="link" href=""><span class="returnvalue">int</span></a>
1402 oath_totp_validate2_callback (<em class="parameter"><code>const <a class="link" href=""><span class="type">char</span></a> *secret</code></em>,
1403 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> secret_length</code></em>,
1404 <em class="parameter"><code><a class="link" href=""><span class="type">time_t</span></a> now</code></em>,
1405 <em class="parameter"><code><a class="link" href=""><span class="type">unsigned </span></a> time_step_size</code></em>,
1406 <em class="parameter"><code><a class="link" href=""><span class="type">time_t</span></a> start_offset</code></em>,
1407 <em class="parameter"><code><a class="link" href=""><span class="type">unsigned </span></a> digits</code></em>,
1408 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> window</code></em>,
1409 <em class="parameter"><code><a class="link" href=""><span class="type">int</span></a> *otp_pos</code></em>,
1410 <em class="parameter"><code><a class="link" href="liboath-oath.h.html#oath-validate-strcmp-function" title="oath_validate_strcmp_function ()"><span class="type">oath_validate_strcmp_function</span></a> strcmp_otp</code></em>,
1411 <em class="parameter"><code><a class="link" href=""><span class="type">void</span></a> *strcmp_handle</code></em>);</pre>
1412 <p>Validate an OTP according to OATH TOTP algorithm per RFC 6238.</p>
1413 <p>Validation is implemented by generating a number of potential OTPs
1414 and performing a call to the <em class="parameter"><code>strcmp_otp</code></em>
1415 function, to compare the
1416 potential OTP against the given <em class="parameter"><code>otp</code></em>
1417 . It has the following
1418 prototype:</p>
1419 <p>int (*oath_validate_strcmp_function) (void *handle, const char *test_otp);</p>
1420 <p>The function should be similar to strcmp in that it return 0 only
1421 on matches. It differs by permitting use of negative return codes
1422 as indication of internal failures in the callback. Positive
1423 values indicate OTP mismatch.</p>
1424 <p>This callback interface is useful when you cannot compare OTPs
1425 directly using normal strcmp, but instead for example only have a
1426 hashed OTP. You would then typically pass in the hashed OTP in the
1427 <em class="parameter"><code>strcmp_handle</code></em>
1428 and let your implementation of <em class="parameter"><code>strcmp_otp</code></em>
1429 hash the
1430 test_otp OTP using the same hash, and then compare the results.</p>
1431 <p>Currently only OTP lengths of 6, 7 or 8 digits are supported. This
1432 restrictions may be lifted in future versions, although some
1433 limitations are inherent in the protocol.</p>
1434 <div class="refsect3">
1435 <a name="oath-totp-validate2-callback.parameters"></a><h4>Parameters</h4>
1436 <div class="informaltable"><table class="informaltable" width="100%" border="0">
1437 <colgroup>
1438 <col width="150px" class="parameters_name">
1439 <col class="parameters_description">
1440 <col width="200px" class="parameters_annotations">
1441 </colgroup>
1442 <tbody>
1443 <tr>
1444 <td class="parameter_name"><p>secret</p></td>
1445 <td class="parameter_description"><p>the shared secret string</p></td>
1446 <td class="parameter_annotations"> </td>
1447 </tr>
1448 <tr>
1449 <td class="parameter_name"><p>secret_length</p></td>
1450 <td class="parameter_description"><p>length of <em class="parameter"><code>secret</code></em>
1451 </p></td>
1452 <td class="parameter_annotations"> </td>
1453 </tr>
1454 <tr>
1455 <td class="parameter_name"><p>now</p></td>
1456 <td class="parameter_description"><p>Unix time value to compute TOTP for</p></td>
1457 <td class="parameter_annotations"> </td>
1458 </tr>
1459 <tr>
1460 <td class="parameter_name"><p>time_step_size</p></td>
1461 <td class="parameter_description"><p>time step system parameter (typically 30)</p></td>
1462 <td class="parameter_annotations"> </td>
1463 </tr>
1464 <tr>
1465 <td class="parameter_name"><p>start_offset</p></td>
1466 <td class="parameter_description"><p>Unix time of when to start counting time steps (typically 0)</p></td>
1467 <td class="parameter_annotations"> </td>
1468 </tr>
1469 <tr>
1470 <td class="parameter_name"><p>digits</p></td>
1471 <td class="parameter_description"><p>number of requested digits in the OTP</p></td>
1472 <td class="parameter_annotations"> </td>
1473 </tr>
1474 <tr>
1475 <td class="parameter_name"><p>window</p></td>
1476 <td class="parameter_description"><p>how many OTPs after start counter to test</p></td>
1477 <td class="parameter_annotations"> </td>
1478 </tr>
1479 <tr>
1480 <td class="parameter_name"><p>otp_pos</p></td>
1481 <td class="parameter_description"><p>output search position in search window (may be NULL).</p></td>
1482 <td class="parameter_annotations"> </td>
1483 </tr>
1484 <tr>
1485 <td class="parameter_name"><p>strcmp_otp</p></td>
1486 <td class="parameter_description"><p>function pointer to a strcmp-like function.</p></td>
1487 <td class="parameter_annotations"> </td>
1488 </tr>
1489 <tr>
1490 <td class="parameter_name"><p>strcmp_handle</p></td>
1491 <td class="parameter_description"><p>caller handle to be passed on to <em class="parameter"><code>strcmp_otp</code></em>
1492 .</p></td>
1493 <td class="parameter_annotations"> </td>
1494 </tr>
1495 </tbody>
1496 </table></div>
1497 </div>
1498 <div class="refsect3">
1499 <a name="oath-totp-validate2-callback.returns"></a><h4>Returns</h4>
1500 <p> Returns absolute value of position in OTP window (zero is
1501 first position), or <a class="link" href="liboath-oath.h.html#OATH-INVALID-OTP:CAPS"><code class="literal">OATH_INVALID_OTP</code></a> if no OTP was found in OTP
1502 window, or an error code.</p>
1503 </div>
1504 <p class="since">Since: <a class="link" href="api-index-1-10-0.html#api-index-1.10.0">1.10.0</a></p>
1505 </div>
1506 <div class="refsect2">
1507 <a name="oath-totp-validate3"></a><h3>oath_totp_validate3 ()</h3>
1508 <a class="indexterm" name="id-1.2.2.6.22.2"></a><pre class="programlisting"><a class="link" href=""><span class="returnvalue">int</span></a>
1509 oath_totp_validate3 (<em class="parameter"><code>const <a class="link" href=""><span class="type">char</span></a> *secret</code></em>,
1510 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> secret_length</code></em>,
1511 <em class="parameter"><code><a class="link" href=""><span class="type">time_t</span></a> now</code></em>,
1512 <em class="parameter"><code><a class="link" href=""><span class="type">unsigned </span></a> time_step_size</code></em>,
1513 <em class="parameter"><code><a class="link" href=""><span class="type">time_t</span></a> start_offset</code></em>,
1514 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> window</code></em>,
1515 <em class="parameter"><code><a class="link" href=""><span class="type">int</span></a> *otp_pos</code></em>,
1516 <em class="parameter"><code><a class="link" href=""><span class="type">uint64_t</span></a> *otp_counter</code></em>,
1517 <em class="parameter"><code>const <a class="link" href=""><span class="type">char</span></a> *otp</code></em>);</pre>
1518 <p>Validate an OTP according to OATH TOTP algorithm per RFC 6238.</p>
1519 <p>Currently only OTP lengths of 6, 7 or 8 digits are supported. This
1520 restrictions may be lifted in future versions, although some
1521 limitations are inherent in the protocol.</p>
1522 <div class="refsect3">
1523 <a name="oath-totp-validate3.parameters"></a><h4>Parameters</h4>
1524 <div class="informaltable"><table class="informaltable" width="100%" border="0">
1525 <colgroup>
1526 <col width="150px" class="parameters_name">
1527 <col class="parameters_description">
1528 <col width="200px" class="parameters_annotations">
1529 </colgroup>
1530 <tbody>
1531 <tr>
1532 <td class="parameter_name"><p>secret</p></td>
1533 <td class="parameter_description"><p>the shared secret string</p></td>
1534 <td class="parameter_annotations"> </td>
1535 </tr>
1536 <tr>
1537 <td class="parameter_name"><p>secret_length</p></td>
1538 <td class="parameter_description"><p>length of <em class="parameter"><code>secret</code></em>
1539 </p></td>
1540 <td class="parameter_annotations"> </td>
1541 </tr>
1542 <tr>
1543 <td class="parameter_name"><p>now</p></td>
1544 <td class="parameter_description"><p>Unix time value to validate TOTP for</p></td>
1545 <td class="parameter_annotations"> </td>
1546 </tr>
1547 <tr>
1548 <td class="parameter_name"><p>time_step_size</p></td>
1549 <td class="parameter_description"><p>time step system parameter (typically 30)</p></td>
1550 <td class="parameter_annotations"> </td>
1551 </tr>
1552 <tr>
1553 <td class="parameter_name"><p>start_offset</p></td>
1554 <td class="parameter_description"><p>Unix time of when to start counting time steps (typically 0)</p></td>
1555 <td class="parameter_annotations"> </td>
1556 </tr>
1557 <tr>
1558 <td class="parameter_name"><p>window</p></td>
1559 <td class="parameter_description"><p>how many OTPs after/before start OTP to test</p></td>
1560 <td class="parameter_annotations"> </td>
1561 </tr>
1562 <tr>
1563 <td class="parameter_name"><p>otp_pos</p></td>
1564 <td class="parameter_description"><p>output search position in search window (may be NULL).</p></td>
1565 <td class="parameter_annotations"> </td>
1566 </tr>
1567 <tr>
1568 <td class="parameter_name"><p>otp_counter</p></td>
1569 <td class="parameter_description"><p>counter value used to calculate OTP value (may be NULL).</p></td>
1570 <td class="parameter_annotations"> </td>
1571 </tr>
1572 <tr>
1573 <td class="parameter_name"><p>otp</p></td>
1574 <td class="parameter_description"><p>the OTP to validate.</p></td>
1575 <td class="parameter_annotations"> </td>
1576 </tr>
1577 </tbody>
1578 </table></div>
1579 </div>
1580 <div class="refsect3">
1581 <a name="oath-totp-validate3.returns"></a><h4>Returns</h4>
1582 <p> Returns absolute value of position in OTP window (zero is
1583 first position), or <a class="link" href="liboath-oath.h.html#OATH-INVALID-OTP:CAPS"><code class="literal">OATH_INVALID_OTP</code></a> if no OTP was found in OTP
1584 window, or an error code.</p>
1585 </div>
1586 <p class="since">Since: <a class="link" href="api-index-2-4-0.html#api-index-2.4.0">2.4.0</a></p>
1587 </div>
1588 <div class="refsect2">
1589 <a name="oath-totp-validate3-callback"></a><h3>oath_totp_validate3_callback ()</h3>
1590 <a class="indexterm" name="id-1.2.2.6.23.2"></a><pre class="programlisting"><a class="link" href=""><span class="returnvalue">int</span></a>
1591 oath_totp_validate3_callback (<em class="parameter"><code>const <a class="link" href=""><span class="type">char</span></a> *secret</code></em>,
1592 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> secret_length</code></em>,
1593 <em class="parameter"><code><a class="link" href=""><span class="type">time_t</span></a> now</code></em>,
1594 <em class="parameter"><code><a class="link" href=""><span class="type">unsigned </span></a> time_step_size</code></em>,
1595 <em class="parameter"><code><a class="link" href=""><span class="type">time_t</span></a> start_offset</code></em>,
1596 <em class="parameter"><code><a class="link" href=""><span class="type">unsigned </span></a> digits</code></em>,
1597 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> window</code></em>,
1598 <em class="parameter"><code><a class="link" href=""><span class="type">int</span></a> *otp_pos</code></em>,
1599 <em class="parameter"><code><a class="link" href=""><span class="type">uint64_t</span></a> *otp_counter</code></em>,
1600 <em class="parameter"><code><a class="link" href="liboath-oath.h.html#oath-validate-strcmp-function" title="oath_validate_strcmp_function ()"><span class="type">oath_validate_strcmp_function</span></a> strcmp_otp</code></em>,
1601 <em class="parameter"><code><a class="link" href=""><span class="type">void</span></a> *strcmp_handle</code></em>);</pre>
1602 <p>Validate an OTP according to OATH TOTP algorithm per RFC 6238.</p>
1603 <p>Validation is implemented by generating a number of potential OTPs
1604 and performing a call to the <em class="parameter"><code>strcmp_otp</code></em>
1605 function, to compare the
1606 potential OTP against the given <em class="parameter"><code>otp</code></em>
1607 . It has the following
1608 prototype:</p>
1609 <p>int (*oath_validate_strcmp_function) (void *handle, const char *test_otp);</p>
1610 <p>The function should be similar to strcmp in that it return 0 only
1611 on matches. It differs by permitting use of negative return codes
1612 as indication of internal failures in the callback. Positive
1613 values indicate OTP mismatch.</p>
1614 <p>This callback interface is useful when you cannot compare OTPs
1615 directly using normal strcmp, but instead for example only have a
1616 hashed OTP. You would then typically pass in the hashed OTP in the
1617 <em class="parameter"><code>strcmp_handle</code></em>
1618 and let your implementation of <em class="parameter"><code>strcmp_otp</code></em>
1619 hash the
1620 test_otp OTP using the same hash, and then compare the results.</p>
1621 <p>Currently only OTP lengths of 6, 7 or 8 digits are supported. This
1622 restrictions may be lifted in future versions, although some
1623 limitations are inherent in the protocol.</p>
1624 <div class="refsect3">
1625 <a name="oath-totp-validate3-callback.parameters"></a><h4>Parameters</h4>
1626 <div class="informaltable"><table class="informaltable" width="100%" border="0">
1627 <colgroup>
1628 <col width="150px" class="parameters_name">
1629 <col class="parameters_description">
1630 <col width="200px" class="parameters_annotations">
1631 </colgroup>
1632 <tbody>
1633 <tr>
1634 <td class="parameter_name"><p>secret</p></td>
1635 <td class="parameter_description"><p>the shared secret string</p></td>
1636 <td class="parameter_annotations"> </td>
1637 </tr>
1638 <tr>
1639 <td class="parameter_name"><p>secret_length</p></td>
1640 <td class="parameter_description"><p>length of <em class="parameter"><code>secret</code></em>
1641 </p></td>
1642 <td class="parameter_annotations"> </td>
1643 </tr>
1644 <tr>
1645 <td class="parameter_name"><p>now</p></td>
1646 <td class="parameter_description"><p>Unix time value to compute TOTP for</p></td>
1647 <td class="parameter_annotations"> </td>
1648 </tr>
1649 <tr>
1650 <td class="parameter_name"><p>time_step_size</p></td>
1651 <td class="parameter_description"><p>time step system parameter (typically 30)</p></td>
1652 <td class="parameter_annotations"> </td>
1653 </tr>
1654 <tr>
1655 <td class="parameter_name"><p>start_offset</p></td>
1656 <td class="parameter_description"><p>Unix time of when to start counting time steps (typically 0)</p></td>
1657 <td class="parameter_annotations"> </td>
1658 </tr>
1659 <tr>
1660 <td class="parameter_name"><p>digits</p></td>
1661 <td class="parameter_description"><p>number of requested digits in the OTP</p></td>
1662 <td class="parameter_annotations"> </td>
1663 </tr>
1664 <tr>
1665 <td class="parameter_name"><p>window</p></td>
1666 <td class="parameter_description"><p>how many OTPs after start counter to test</p></td>
1667 <td class="parameter_annotations"> </td>
1668 </tr>
1669 <tr>
1670 <td class="parameter_name"><p>otp_pos</p></td>
1671 <td class="parameter_description"><p>output search position in search window (may be NULL).</p></td>
1672 <td class="parameter_annotations"> </td>
1673 </tr>
1674 <tr>
1675 <td class="parameter_name"><p>otp_counter</p></td>
1676 <td class="parameter_description"><p>counter value used to calculate OTP value (may be NULL).</p></td>
1677 <td class="parameter_annotations"> </td>
1678 </tr>
1679 <tr>
1680 <td class="parameter_name"><p>strcmp_otp</p></td>
1681 <td class="parameter_description"><p>function pointer to a strcmp-like function.</p></td>
1682 <td class="parameter_annotations"> </td>
1683 </tr>
1684 <tr>
1685 <td class="parameter_name"><p>strcmp_handle</p></td>
1686 <td class="parameter_description"><p>caller handle to be passed on to <em class="parameter"><code>strcmp_otp</code></em>
1687 .</p></td>
1688 <td class="parameter_annotations"> </td>
1689 </tr>
1690 </tbody>
1691 </table></div>
1692 </div>
1693 <div class="refsect3">
1694 <a name="oath-totp-validate3-callback.returns"></a><h4>Returns</h4>
1695 <p> Returns absolute value of position in OTP window (zero is
1696 first position), or <a class="link" href="liboath-oath.h.html#OATH-INVALID-OTP:CAPS"><code class="literal">OATH_INVALID_OTP</code></a> if no OTP was found in OTP
1697 window, or an error code.</p>
1698 </div>
1699 <p class="since">Since: <a class="link" href="api-index-2-4-0.html#api-index-2.4.0">2.4.0</a></p>
1700 </div>
1701 <div class="refsect2">
1702 <a name="oath-totp-validate4"></a><h3>oath_totp_validate4 ()</h3>
1703 <a class="indexterm" name="id-1.2.2.6.24.2"></a><pre class="programlisting"><a class="link" href=""><span class="returnvalue">int</span></a>
1704 oath_totp_validate4 (<em class="parameter"><code>const <a class="link" href=""><span class="type">char</span></a> *secret</code></em>,
1705 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> secret_length</code></em>,
1706 <em class="parameter"><code><a class="link" href=""><span class="type">time_t</span></a> now</code></em>,
1707 <em class="parameter"><code><a class="link" href=""><span class="type">unsigned </span></a> time_step_size</code></em>,
1708 <em class="parameter"><code><a class="link" href=""><span class="type">time_t</span></a> start_offset</code></em>,
1709 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> window</code></em>,
1710 <em class="parameter"><code><a class="link" href=""><span class="type">int</span></a> *otp_pos</code></em>,
1711 <em class="parameter"><code><a class="link" href=""><span class="type">uint64_t</span></a> *otp_counter</code></em>,
1712 <em class="parameter"><code><a class="link" href=""><span class="type">int</span></a> flags</code></em>,
1713 <em class="parameter"><code>const <a class="link" href=""><span class="type">char</span></a> *otp</code></em>);</pre>
1714 <p>Validate an OTP according to OATH TOTP algorithm per RFC 6238.</p>
1715 <p>Currently only OTP lengths of 6, 7 or 8 digits are supported. This
1716 restrictions may be lifted in future versions, although some
1717 limitations are inherent in the protocol.</p>
1718 <p>The <em class="parameter"><code>flags</code></em>
1719 parameter may be used to change the MAC function, for
1720 example <a class="link" href="liboath-oath.h.html#OATH-TOTP-HMAC-SHA256:CAPS"><code class="literal">OATH_TOTP_HMAC_SHA256</code></a> or <a class="link" href="liboath-oath.h.html#OATH-TOTP-HMAC-SHA512:CAPS"><code class="literal">OATH_TOTP_HMAC_SHA512</code></a>.</p>
1721 <div class="refsect3">
1722 <a name="oath-totp-validate4.parameters"></a><h4>Parameters</h4>
1723 <div class="informaltable"><table class="informaltable" width="100%" border="0">
1724 <colgroup>
1725 <col width="150px" class="parameters_name">
1726 <col class="parameters_description">
1727 <col width="200px" class="parameters_annotations">
1728 </colgroup>
1729 <tbody>
1730 <tr>
1731 <td class="parameter_name"><p>secret</p></td>
1732 <td class="parameter_description"><p>the shared secret string</p></td>
1733 <td class="parameter_annotations"> </td>
1734 </tr>
1735 <tr>
1736 <td class="parameter_name"><p>secret_length</p></td>
1737 <td class="parameter_description"><p>length of <em class="parameter"><code>secret</code></em>
1738 </p></td>
1739 <td class="parameter_annotations"> </td>
1740 </tr>
1741 <tr>
1742 <td class="parameter_name"><p>now</p></td>
1743 <td class="parameter_description"><p>Unix time value to validate TOTP for</p></td>
1744 <td class="parameter_annotations"> </td>
1745 </tr>
1746 <tr>
1747 <td class="parameter_name"><p>time_step_size</p></td>
1748 <td class="parameter_description"><p>time step system parameter (typically 30)</p></td>
1749 <td class="parameter_annotations"> </td>
1750 </tr>
1751 <tr>
1752 <td class="parameter_name"><p>start_offset</p></td>
1753 <td class="parameter_description"><p>Unix time of when to start counting time steps (typically 0)</p></td>
1754 <td class="parameter_annotations"> </td>
1755 </tr>
1756 <tr>
1757 <td class="parameter_name"><p>window</p></td>
1758 <td class="parameter_description"><p>how many OTPs after/before start OTP to test</p></td>
1759 <td class="parameter_annotations"> </td>
1760 </tr>
1761 <tr>
1762 <td class="parameter_name"><p>otp_pos</p></td>
1763 <td class="parameter_description"><p>output search position in search window (may be NULL).</p></td>
1764 <td class="parameter_annotations"> </td>
1765 </tr>
1766 <tr>
1767 <td class="parameter_name"><p>otp_counter</p></td>
1768 <td class="parameter_description"><p>counter value used to calculate OTP value (may be NULL).</p></td>
1769 <td class="parameter_annotations"> </td>
1770 </tr>
1771 <tr>
1772 <td class="parameter_name"><p>flags</p></td>
1773 <td class="parameter_description"><p>flags indicating mode, one of <a class="link" href="liboath-oath.h.html#oath-totp-flags" title="enum oath_totp_flags"><span class="type">oath_totp_flags</span></a></p></td>
1774 <td class="parameter_annotations"> </td>
1775 </tr>
1776 <tr>
1777 <td class="parameter_name"><p>otp</p></td>
1778 <td class="parameter_description"><p>the OTP to validate.</p></td>
1779 <td class="parameter_annotations"> </td>
1780 </tr>
1781 </tbody>
1782 </table></div>
1783 </div>
1784 <div class="refsect3">
1785 <a name="oath-totp-validate4.returns"></a><h4>Returns</h4>
1786 <p> Returns absolute value of position in OTP window (zero is
1787 first position), or <a class="link" href="liboath-oath.h.html#OATH-INVALID-OTP:CAPS"><code class="literal">OATH_INVALID_OTP</code></a> if no OTP was found in OTP
1788 window, or an error code.</p>
1789 </div>
1790 <p class="since">Since: <a class="link" href="api-index-2-6-0.html#api-index-2.6.0">2.6.0</a></p>
1791 </div>
1792 <div class="refsect2">
1793 <a name="oath-totp-validate4-callback"></a><h3>oath_totp_validate4_callback ()</h3>
1794 <a class="indexterm" name="id-1.2.2.6.25.2"></a><pre class="programlisting"><a class="link" href=""><span class="returnvalue">int</span></a>
1795 oath_totp_validate4_callback (<em class="parameter"><code>const <a class="link" href=""><span class="type">char</span></a> *secret</code></em>,
1796 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> secret_length</code></em>,
1797 <em class="parameter"><code><a class="link" href=""><span class="type">time_t</span></a> now</code></em>,
1798 <em class="parameter"><code><a class="link" href=""><span class="type">unsigned </span></a> time_step_size</code></em>,
1799 <em class="parameter"><code><a class="link" href=""><span class="type">time_t</span></a> start_offset</code></em>,
1800 <em class="parameter"><code><a class="link" href=""><span class="type">unsigned </span></a> digits</code></em>,
1801 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> window</code></em>,
1802 <em class="parameter"><code><a class="link" href=""><span class="type">int</span></a> *otp_pos</code></em>,
1803 <em class="parameter"><code><a class="link" href=""><span class="type">uint64_t</span></a> *otp_counter</code></em>,
1804 <em class="parameter"><code><a class="link" href=""><span class="type">int</span></a> flags</code></em>,
1805 <em class="parameter"><code><a class="link" href="liboath-oath.h.html#oath-validate-strcmp-function" title="oath_validate_strcmp_function ()"><span class="type">oath_validate_strcmp_function</span></a> strcmp_otp</code></em>,
1806 <em class="parameter"><code><a class="link" href=""><span class="type">void</span></a> *strcmp_handle</code></em>);</pre>
1807 <p>Validate an OTP according to OATH TOTP algorithm per RFC 6238.</p>
1808 <p>Validation is implemented by generating a number of potential OTPs
1809 and performing a call to the <em class="parameter"><code>strcmp_otp</code></em>
1810 function, to compare the
1811 potential OTP against the given <em class="parameter"><code>otp</code></em>
1812 . It has the following
1813 prototype:</p>
1814 <p>int (*oath_validate_strcmp_function) (void *handle, const char *test_otp);</p>
1815 <p>The function should be similar to strcmp in that it return 0 only
1816 on matches. It differs by permitting use of negative return codes
1817 as indication of internal failures in the callback. Positive
1818 values indicate OTP mismatch.</p>
1819 <p>This callback interface is useful when you cannot compare OTPs
1820 directly using normal strcmp, but instead for example only have a
1821 hashed OTP. You would then typically pass in the hashed OTP in the
1822 <em class="parameter"><code>strcmp_handle</code></em>
1823 and let your implementation of <em class="parameter"><code>strcmp_otp</code></em>
1824 hash the
1825 test_otp OTP using the same hash, and then compare the results.</p>
1826 <p>Currently only OTP lengths of 6, 7 or 8 digits are supported. This
1827 restrictions may be lifted in future versions, although some
1828 limitations are inherent in the protocol.</p>
1829 <p>The <em class="parameter"><code>flags</code></em>
1830 parameter may be used to change the MAC function, for
1831 example <a class="link" href="liboath-oath.h.html#OATH-TOTP-HMAC-SHA256:CAPS"><code class="literal">OATH_TOTP_HMAC_SHA256</code></a> or <a class="link" href="liboath-oath.h.html#OATH-TOTP-HMAC-SHA512:CAPS"><code class="literal">OATH_TOTP_HMAC_SHA512</code></a>.</p>
1832 <div class="refsect3">
1833 <a name="oath-totp-validate4-callback.parameters"></a><h4>Parameters</h4>
1834 <div class="informaltable"><table class="informaltable" width="100%" border="0">
1835 <colgroup>
1836 <col width="150px" class="parameters_name">
1837 <col class="parameters_description">
1838 <col width="200px" class="parameters_annotations">
1839 </colgroup>
1840 <tbody>
1841 <tr>
1842 <td class="parameter_name"><p>secret</p></td>
1843 <td class="parameter_description"><p>the shared secret string</p></td>
1844 <td class="parameter_annotations"> </td>
1845 </tr>
1846 <tr>
1847 <td class="parameter_name"><p>secret_length</p></td>
1848 <td class="parameter_description"><p>length of <em class="parameter"><code>secret</code></em>
1849 </p></td>
1850 <td class="parameter_annotations"> </td>
1851 </tr>
1852 <tr>
1853 <td class="parameter_name"><p>now</p></td>
1854 <td class="parameter_description"><p>Unix time value to compute TOTP for</p></td>
1855 <td class="parameter_annotations"> </td>
1856 </tr>
1857 <tr>
1858 <td class="parameter_name"><p>time_step_size</p></td>
1859 <td class="parameter_description"><p>time step system parameter (typically 30)</p></td>
1860 <td class="parameter_annotations"> </td>
1861 </tr>
1862 <tr>
1863 <td class="parameter_name"><p>start_offset</p></td>
1864 <td class="parameter_description"><p>Unix time of when to start counting time steps (typically 0)</p></td>
1865 <td class="parameter_annotations"> </td>
1866 </tr>
1867 <tr>
1868 <td class="parameter_name"><p>digits</p></td>
1869 <td class="parameter_description"><p>number of requested digits in the OTP</p></td>
1870 <td class="parameter_annotations"> </td>
1871 </tr>
1872 <tr>
1873 <td class="parameter_name"><p>window</p></td>
1874 <td class="parameter_description"><p>how many OTPs after start counter to test</p></td>
1875 <td class="parameter_annotations"> </td>
1876 </tr>
1877 <tr>
1878 <td class="parameter_name"><p>otp_pos</p></td>
1879 <td class="parameter_description"><p>output search position in search window (may be NULL).</p></td>
1880 <td class="parameter_annotations"> </td>
1881 </tr>
1882 <tr>
1883 <td class="parameter_name"><p>otp_counter</p></td>
1884 <td class="parameter_description"><p>counter value used to calculate OTP value (may be NULL).</p></td>
1885 <td class="parameter_annotations"> </td>
1886 </tr>
1887 <tr>
1888 <td class="parameter_name"><p>flags</p></td>
1889 <td class="parameter_description"><p>flags indicating mode, one of <a class="link" href="liboath-oath.h.html#oath-totp-flags" title="enum oath_totp_flags"><span class="type">oath_totp_flags</span></a></p></td>
1890 <td class="parameter_annotations"> </td>
1891 </tr>
1892 <tr>
1893 <td class="parameter_name"><p>strcmp_otp</p></td>
1894 <td class="parameter_description"><p>function pointer to a strcmp-like function.</p></td>
1895 <td class="parameter_annotations"> </td>
1896 </tr>
1897 <tr>
1898 <td class="parameter_name"><p>strcmp_handle</p></td>
1899 <td class="parameter_description"><p>caller handle to be passed on to <em class="parameter"><code>strcmp_otp</code></em>
1900 .</p></td>
1901 <td class="parameter_annotations"> </td>
1902 </tr>
1903 </tbody>
1904 </table></div>
1905 </div>
1906 <div class="refsect3">
1907 <a name="oath-totp-validate4-callback.returns"></a><h4>Returns</h4>
1908 <p> Returns absolute value of position in OTP window (zero is
1909 first position), or <a class="link" href="liboath-oath.h.html#OATH-INVALID-OTP:CAPS"><code class="literal">OATH_INVALID_OTP</code></a> if no OTP was found in OTP
1910 window, or an error code.</p>
1911 </div>
1912 <p class="since">Since: <a class="link" href="api-index-2-6-0.html#api-index-2.6.0">2.6.0</a></p>
1913 </div>
1914 <div class="refsect2">
1915 <a name="oath-authenticate-usersfile"></a><h3>oath_authenticate_usersfile ()</h3>
1916 <a class="indexterm" name="id-1.2.2.6.26.2"></a><pre class="programlisting"><a class="link" href=""><span class="returnvalue">int</span></a>
1917 oath_authenticate_usersfile (<em class="parameter"><code>const <a class="link" href=""><span class="type">char</span></a> *usersfile</code></em>,
1918 <em class="parameter"><code>const <a class="link" href=""><span class="type">char</span></a> *username</code></em>,
1919 <em class="parameter"><code>const <a class="link" href=""><span class="type">char</span></a> *otp</code></em>,
1920 <em class="parameter"><code><a class="link" href=""><span class="type">size_t</span></a> window</code></em>,
1921 <em class="parameter"><code>const <a class="link" href=""><span class="type">char</span></a> *passwd</code></em>,
1922 <em class="parameter"><code><a class="link" href=""><span class="type">time_t</span></a> *last_otp</code></em>);</pre>
1923 <p>Authenticate user named <em class="parameter"><code>username</code></em>
1924 with the one-time password <em class="parameter"><code>otp</code></em>
1925
1926 and (optional) password <em class="parameter"><code>passwd</code></em>
1927 . Credentials are read (and
1928 updated) from a text file named <em class="parameter"><code>usersfile</code></em>
1929 .</p>
1930 <p>Note that for TOTP the usersfile will only record the last OTP and
1931 use that to make sure more recent OTPs have not been seen yet when
1932 validating a new OTP. That logics relies on using the same search
1933 window for the same user.</p>
1934 <div class="refsect3">
1935 <a name="oath-authenticate-usersfile.parameters"></a><h4>Parameters</h4>
1936 <div class="informaltable"><table class="informaltable" width="100%" border="0">
1937 <colgroup>
1938 <col width="150px" class="parameters_name">
1939 <col class="parameters_description">
1940 <col width="200px" class="parameters_annotations">
1941 </colgroup>
1942 <tbody>
1943 <tr>
1944 <td class="parameter_name"><p>usersfile</p></td>
1945 <td class="parameter_description"><p>string with user credential filename, in UsersFile format</p></td>
1946 <td class="parameter_annotations"> </td>
1947 </tr>
1948 <tr>
1949 <td class="parameter_name"><p>username</p></td>
1950 <td class="parameter_description"><p>string with name of user</p></td>
1951 <td class="parameter_annotations"> </td>
1952 </tr>
1953 <tr>
1954 <td class="parameter_name"><p>otp</p></td>
1955 <td class="parameter_description"><p>string with one-time password to authenticate</p></td>
1956 <td class="parameter_annotations"> </td>
1957 </tr>
1958 <tr>
1959 <td class="parameter_name"><p>window</p></td>
1960 <td class="parameter_description"><p>how many past/future OTPs to search</p></td>
1961 <td class="parameter_annotations"> </td>
1962 </tr>
1963 <tr>
1964 <td class="parameter_name"><p>passwd</p></td>
1965 <td class="parameter_description"><p>string with password, or NULL to disable password checking</p></td>
1966 <td class="parameter_annotations"> </td>
1967 </tr>
1968 <tr>
1969 <td class="parameter_name"><p>last_otp</p></td>
1970 <td class="parameter_description"><p>output variable holding last successful authentication</p></td>
1971 <td class="parameter_annotations"> </td>
1972 </tr>
1973 </tbody>
1974 </table></div>
1975 </div>
1976 <div class="refsect3">
1977 <a name="oath-authenticate-usersfile.returns"></a><h4>Returns</h4>
1978 <p> On successful validation, <a class="link" href="liboath-oath.h.html#OATH-OK:CAPS"><code class="literal">OATH_OK</code></a> is returned. If the
1979 supplied <em class="parameter"><code>otp</code></em>
1980 is the same as the last successfully authenticated
1981 one-time password, <a class="link" href="liboath-oath.h.html#OATH-REPLAYED-OTP:CAPS"><code class="literal">OATH_REPLAYED_OTP</code></a> is returned and the
1982 timestamp of the last authentication is returned in <em class="parameter"><code>last_otp</code></em>
1983 .
1984 If the one-time password is not found in the indicated search
1985 window, <a class="link" href="liboath-oath.h.html#OATH-INVALID-OTP:CAPS"><code class="literal">OATH_INVALID_OTP</code></a> is returned. Otherwise, an error code
1986 is returned.</p>
1987 </div>
1988 </div>
1989 </div>
1990 <div class="refsect1">
1991 <a name="liboath-oath.h.other_details"></a><h2>Types and Values</h2>
1992 <div class="refsect2">
1993 <a name="OATHAPI:CAPS"></a><h3>OATHAPI</h3>
1994 <a class="indexterm" name="id-1.2.2.7.2.2"></a><pre class="programlisting"># define OATHAPI __attribute__((__visibility__("default")))
1995 </pre>
1996 <p>Symbol holding shared library API visibility decorator.</p>
1997 <p>This is used internally by the library header file and should never
1998 be used or modified by the application.</p>
1999 <p>https://www.gnu.org/software/gnulib/manual/html_node/Exported-Symbols-of-Shared-Libraries.html</p>
2000 </div>
2001 <div class="refsect2">
2002 <a name="OATH-VERSION:CAPS"></a><h3>OATH_VERSION</h3>
2003 <a class="indexterm" name="id-1.2.2.7.3.2"></a><pre class="programlisting"># define OATH_VERSION "2.6.14"
2004 </pre>
2005 <p>Pre-processor symbol with a string that describe the header file
2006 version number. Used together with <a class="link" href="liboath-oath.h.html#oath-check-version" title="oath_check_version ()"><code class="function">oath_check_version()</code></a> to verify
2007 header file and run-time library consistency.</p>
2008 </div>
2009 <div class="refsect2">
2010 <a name="OATH-VERSION-NUMBER:CAPS"></a><h3>OATH_VERSION_NUMBER</h3>
2011 <a class="indexterm" name="id-1.2.2.7.4.2"></a><pre class="programlisting"># define OATH_VERSION_NUMBER 0x02060e00
2012 </pre>
2013 <p>Pre-processor symbol with a hexadecimal value describing the header
2014 file version number. For example, when the header version is 1.2.3
2015 this symbol will have the value 0x01020300. The last two digits
2016 are only used between public releases, and will otherwise be 00.</p>
2017 </div>
2018 <div class="refsect2">
2019 <a name="oath-rc"></a><h3>enum oath_rc</h3>
2020 <a class="indexterm" name="id-1.2.2.7.5.2"></a><p>Return codes for OATH functions. All return codes are negative
2021 except for the successful code <a class="link" href="liboath-oath.h.html#OATH-OK:CAPS"><code class="literal">OATH_OK</code></a> which are guaranteed to be</p>
2022 <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Positive values are reserved for non-error return codes.</p></li></ol></div>
2023 <p>Note that the <a class="link" href="liboath-oath.h.html#oath-rc" title="enum oath_rc"><span class="type">oath_rc</span></a> enumeration may be extended at a later date
2024 to include new return codes.</p>
2025 <div class="refsect3">
2026 <a name="oath-rc.members"></a><h4>Members</h4>
2027 <div class="informaltable"><table class="informaltable" width="100%" border="0">
2028 <colgroup>
2029 <col width="300px" class="enum_members_name">
2030 <col class="enum_members_description">
2031 <col width="200px" class="enum_members_annotations">
2032 </colgroup>
2033 <tbody>
2034 <tr>
2035 <td class="enum_member_name"><p><a name="OATH-OK:CAPS"></a>OATH_OK</p></td>
2036 <td class="enum_member_description">
2037 <p>Successful return</p>
2038 </td>
2039 <td class="enum_member_annotations"> </td>
2040 </tr>
2041 <tr>
2042 <td class="enum_member_name"><p><a name="OATH-CRYPTO-ERROR:CAPS"></a>OATH_CRYPTO_ERROR</p></td>
2043 <td class="enum_member_description">
2044 <p>Internal error in crypto functions</p>
2045 </td>
2046 <td class="enum_member_annotations"> </td>
2047 </tr>
2048 <tr>
2049 <td class="enum_member_name"><p><a name="OATH-INVALID-DIGITS:CAPS"></a>OATH_INVALID_DIGITS</p></td>
2050 <td class="enum_member_description">
2051 <p>Unsupported number of OTP digits</p>
2052 </td>
2053 <td class="enum_member_annotations"> </td>
2054 </tr>
2055 <tr>
2056 <td class="enum_member_name"><p><a name="OATH-PRINTF-ERROR:CAPS"></a>OATH_PRINTF_ERROR</p></td>
2057 <td class="enum_member_description">
2058 <p>Error from system printf call</p>
2059 </td>
2060 <td class="enum_member_annotations"> </td>
2061 </tr>
2062 <tr>
2063 <td class="enum_member_name"><p><a name="OATH-INVALID-HEX:CAPS"></a>OATH_INVALID_HEX</p></td>
2064 <td class="enum_member_description">
2065 <p>Hex string is invalid</p>
2066 </td>
2067 <td class="enum_member_annotations"> </td>
2068 </tr>
2069 <tr>
2070 <td class="enum_member_name"><p><a name="OATH-TOO-SMALL-BUFFER:CAPS"></a>OATH_TOO_SMALL_BUFFER</p></td>
2071 <td class="enum_member_description">
2072 <p>The output buffer is too small</p>
2073 </td>
2074 <td class="enum_member_annotations"> </td>
2075 </tr>
2076 <tr>
2077 <td class="enum_member_name"><p><a name="OATH-INVALID-OTP:CAPS"></a>OATH_INVALID_OTP</p></td>
2078 <td class="enum_member_description">
2079 <p>The OTP is not valid</p>
2080 </td>
2081 <td class="enum_member_annotations"> </td>
2082 </tr>
2083 <tr>
2084 <td class="enum_member_name"><p><a name="OATH-REPLAYED-OTP:CAPS"></a>OATH_REPLAYED_OTP</p></td>
2085 <td class="enum_member_description">
2086 <p>The OTP has been replayed</p>
2087 </td>
2088 <td class="enum_member_annotations"> </td>
2089 </tr>
2090 <tr>
2091 <td class="enum_member_name"><p><a name="OATH-BAD-PASSWORD:CAPS"></a>OATH_BAD_PASSWORD</p></td>
2092 <td class="enum_member_description">
2093 <p>The password does not match</p>
2094 </td>
2095 <td class="enum_member_annotations"> </td>
2096 </tr>
2097 <tr>
2098 <td class="enum_member_name"><p><a name="OATH-INVALID-COUNTER:CAPS"></a>OATH_INVALID_COUNTER</p></td>
2099 <td class="enum_member_description">
2100 <p>The counter value is corrupt</p>
2101 </td>
2102 <td class="enum_member_annotations"> </td>
2103 </tr>
2104 <tr>
2105 <td class="enum_member_name"><p><a name="OATH-INVALID-TIMESTAMP:CAPS"></a>OATH_INVALID_TIMESTAMP</p></td>
2106 <td class="enum_member_description">
2107 <p>The timestamp is corrupt</p>
2108 </td>
2109 <td class="enum_member_annotations"> </td>
2110 </tr>
2111 <tr>
2112 <td class="enum_member_name"><p><a name="OATH-NO-SUCH-FILE:CAPS"></a>OATH_NO_SUCH_FILE</p></td>
2113 <td class="enum_member_description">
2114 <p>The supplied filename does not exist</p>
2115 </td>
2116 <td class="enum_member_annotations"> </td>
2117 </tr>
2118 <tr>
2119 <td class="enum_member_name"><p><a name="OATH-UNKNOWN-USER:CAPS"></a>OATH_UNKNOWN_USER</p></td>
2120 <td class="enum_member_description">
2121 <p>Cannot find information about user</p>
2122 </td>
2123 <td class="enum_member_annotations"> </td>
2124 </tr>
2125 <tr>
2126 <td class="enum_member_name"><p><a name="OATH-FILE-SEEK-ERROR:CAPS"></a>OATH_FILE_SEEK_ERROR</p></td>
2127 <td class="enum_member_description">
2128 <p>System error when seeking in file</p>
2129 </td>
2130 <td class="enum_member_annotations"> </td>
2131 </tr>
2132 <tr>
2133 <td class="enum_member_name"><p><a name="OATH-FILE-CREATE-ERROR:CAPS"></a>OATH_FILE_CREATE_ERROR</p></td>
2134 <td class="enum_member_description">
2135 <p>System error when creating file</p>
2136 </td>
2137 <td class="enum_member_annotations"> </td>
2138 </tr>
2139 <tr>
2140 <td class="enum_member_name"><p><a name="OATH-FILE-LOCK-ERROR:CAPS"></a>OATH_FILE_LOCK_ERROR</p></td>
2141 <td class="enum_member_description">
2142 <p>System error when locking file</p>
2143 </td>
2144 <td class="enum_member_annotations"> </td>
2145 </tr>
2146 <tr>
2147 <td class="enum_member_name"><p><a name="OATH-FILE-RENAME-ERROR:CAPS"></a>OATH_FILE_RENAME_ERROR</p></td>
2148 <td class="enum_member_description">
2149 <p>System error when renaming file</p>
2150 </td>
2151 <td class="enum_member_annotations"> </td>
2152 </tr>
2153 <tr>
2154 <td class="enum_member_name"><p><a name="OATH-FILE-UNLINK-ERROR:CAPS"></a>OATH_FILE_UNLINK_ERROR</p></td>
2155 <td class="enum_member_description">
2156 <p>System error when removing file</p>
2157 </td>
2158 <td class="enum_member_annotations"> </td>
2159 </tr>
2160 <tr>
2161 <td class="enum_member_name"><p><a name="OATH-TIME-ERROR:CAPS"></a>OATH_TIME_ERROR</p></td>
2162 <td class="enum_member_description">
2163 <p>System error for time manipulation</p>
2164 </td>
2165 <td class="enum_member_annotations"> </td>
2166 </tr>
2167 <tr>
2168 <td class="enum_member_name"><p><a name="OATH-STRCMP-ERROR:CAPS"></a>OATH_STRCMP_ERROR</p></td>
2169 <td class="enum_member_description">
2170 <p>A strcmp callback returned an error</p>
2171 </td>
2172 <td class="enum_member_annotations"> </td>
2173 </tr>
2174 <tr>
2175 <td class="enum_member_name"><p><a name="OATH-INVALID-BASE32:CAPS"></a>OATH_INVALID_BASE32</p></td>
2176 <td class="enum_member_description">
2177 <p>Base32 string is invalid</p>
2178 </td>
2179 <td class="enum_member_annotations"> </td>
2180 </tr>
2181 <tr>
2182 <td class="enum_member_name"><p><a name="OATH-BASE32-OVERFLOW:CAPS"></a>OATH_BASE32_OVERFLOW</p></td>
2183 <td class="enum_member_description">
2184 <p>Base32 encoding would overflow</p>
2185 </td>
2186 <td class="enum_member_annotations"> </td>
2187 </tr>
2188 <tr>
2189 <td class="enum_member_name"><p><a name="OATH-MALLOC-ERROR:CAPS"></a>OATH_MALLOC_ERROR</p></td>
2190 <td class="enum_member_description">
2191 <p>Memory allocation failed</p>
2192 </td>
2193 <td class="enum_member_annotations"> </td>
2194 </tr>
2195 <tr>
2196 <td class="enum_member_name"><p><a name="OATH-FILE-FLUSH-ERROR:CAPS"></a>OATH_FILE_FLUSH_ERROR</p></td>
2197 <td class="enum_member_description">
2198 <p>System error when flushing file buffer</p>
2199 </td>
2200 <td class="enum_member_annotations"> </td>
2201 </tr>
2202 <tr>
2203 <td class="enum_member_name"><p><a name="OATH-FILE-SYNC-ERROR:CAPS"></a>OATH_FILE_SYNC_ERROR</p></td>
2204 <td class="enum_member_description">
2205 <p>System error when syncing file to disk</p>
2206 </td>
2207 <td class="enum_member_annotations"> </td>
2208 </tr>
2209 <tr>
2210 <td class="enum_member_name"><p><a name="OATH-FILE-CLOSE-ERROR:CAPS"></a>OATH_FILE_CLOSE_ERROR</p></td>
2211 <td class="enum_member_description">
2212 <p>System error when closing file</p>
2213 </td>
2214 <td class="enum_member_annotations"> </td>
2215 </tr>
2216 <tr>
2217 <td class="enum_member_name"><p><a name="OATH-FILE-CHOWN-ERROR:CAPS"></a>OATH_FILE_CHOWN_ERROR</p></td>
2218 <td class="enum_member_description">
2219 <p>System error when changing file ownership</p>
2220 </td>
2221 <td class="enum_member_annotations"> </td>
2222 </tr>
2223 <tr>
2224 <td class="enum_member_name"><p><a name="OATH-FILE-STAT-ERROR:CAPS"></a>OATH_FILE_STAT_ERROR</p></td>
2225 <td class="enum_member_description">
2226 <p>System error when getting file status</p>
2227 </td>
2228 <td class="enum_member_annotations"> </td>
2229 </tr>
2230 <tr>
2231 <td class="enum_member_name"><p><a name="OATH-LAST-ERROR:CAPS"></a>OATH_LAST_ERROR</p></td>
2232 <td class="enum_member_description">
2233 <p>Meta-error indicating the last error code, for use
2234 when iterating over all error codes or similar.</p>
2235 </td>
2236 <td class="enum_member_annotations"> </td>
2237 </tr>
2238 </tbody>
2239 </table></div>
2240 </div>
2241 </div>
2242 <div class="refsect2">
2243 <a name="OATH-HOTP-DYNAMIC-TRUNCATION:CAPS"></a><h3>OATH_HOTP_DYNAMIC_TRUNCATION</h3>
2244 <a class="indexterm" name="id-1.2.2.7.6.2"></a><pre class="programlisting"># define OATH_HOTP_DYNAMIC_TRUNCATION SIZE_MAX
2245 </pre>
2246 <p>Pre-processor symbol to indicate that no HOTP truncation should
2247 occur, see <a class="link" href="liboath-oath.h.html#oath-hotp-generate" title="oath_hotp_generate ()"><code class="function">oath_hotp_generate()</code></a>.</p>
2248 </div>
2249 <div class="refsect2">
2250 <a name="oath-hotp-validate-strcmp-function"></a><h3>oath_hotp_validate_strcmp_function</h3>
2251 <a class="indexterm" name="id-1.2.2.7.7.2"></a><pre class="programlisting"># define oath_hotp_validate_strcmp_function oath_validate_strcmp_function
2252 </pre>
2253 <p>Pre-processor compatibility definition for
2254 <a class="link" href="liboath-oath.h.html#oath-validate-strcmp-function" title="oath_validate_strcmp_function ()"><code class="function">oath_validate_strcmp_function()</code></a>.</p>
2255 <p class="since">Since: <a class="link" href="api-index-1-4-0.html#api-index-1.4.0">1.4.0</a></p>
2256 </div>
2257 <div class="refsect2">
2258 <a name="OATH-TOTP-DEFAULT-TIME-STEP-SIZE:CAPS"></a><h3>OATH_TOTP_DEFAULT_TIME_STEP_SIZE</h3>
2259 <a class="indexterm" name="id-1.2.2.7.8.2"></a><pre class="programlisting"># define OATH_TOTP_DEFAULT_TIME_STEP_SIZE 30
2260 </pre>
2261 <p>Pre-processor symbol to provide a default value for the TOTP
2262 time-step value, see <a class="link" href="liboath-oath.h.html#oath-totp-generate" title="oath_totp_generate ()"><code class="function">oath_totp_generate()</code></a>.</p>
2263 </div>
2264 <div class="refsect2">
2265 <a name="OATH-TOTP-DEFAULT-START-TIME:CAPS"></a><h3>OATH_TOTP_DEFAULT_START_TIME</h3>
2266 <a class="indexterm" name="id-1.2.2.7.9.2"></a><pre class="programlisting"># define OATH_TOTP_DEFAULT_START_TIME ((time_t) 0)
2267 </pre>
2268 <p>Pre-processor symbol to indicate that you want to use the Unix
2269 epoch as a starting pointer for TOTP, see <a class="link" href="liboath-oath.h.html#oath-totp-generate" title="oath_totp_generate ()"><code class="function">oath_totp_generate()</code></a>.</p>
2270 </div>
2271 <div class="refsect2">
2272 <a name="oath-totp-flags"></a><h3>enum oath_totp_flags</h3>
2273 <a class="indexterm" name="id-1.2.2.7.10.2"></a><p>Flags for <a class="link" href="liboath-oath.h.html#oath-totp-generate2" title="oath_totp_generate2 ()"><code class="function">oath_totp_generate2()</code></a>.</p>
2274 <div class="refsect3">
2275 <a name="oath-totp-flags.members"></a><h4>Members</h4>
2276 <div class="informaltable"><table class="informaltable" width="100%" border="0">
2277 <colgroup>
2278 <col width="300px" class="enum_members_name">
2279 <col class="enum_members_description">
2280 <col width="200px" class="enum_members_annotations">
2281 </colgroup>
2282 <tbody>
2283 <tr>
2284 <td class="enum_member_name"><p><a name="OATH-TOTP-HMAC-SHA256:CAPS"></a>OATH_TOTP_HMAC_SHA256</p></td>
2285 <td class="enum_member_description">
2286 <p>Use HMAC-SHA256 instead of HMAC-SHA1.</p>
2287 </td>
2288 <td class="enum_member_annotations"> </td>
2289 </tr>
2290 <tr>
2291 <td class="enum_member_name"><p><a name="OATH-TOTP-HMAC-SHA512:CAPS"></a>OATH_TOTP_HMAC_SHA512</p></td>
2292 <td class="enum_member_description">
2293 <p>Use HMAC-SHA512 instead of HMAC-SHA1.</p>
2294 </td>
2295 <td class="enum_member_annotations"> </td>
2296 </tr>
2297 </tbody>
2298 </table></div>
2299 </div>
2300 <p class="since">Since: <a class="link" href="api-index-2-6-0.html#api-index-2.6.0">2.6.0</a></p>
2301 </div>
2302 </div>
2303 </div>
2304 <div class="footer">
2305 <hr>Generated by GTK-Doc V1.34.0</div>
2306 </body>
2307 </html>