![]() |
![]() |
![]() |
Liboath API Reference Manual | |
---|---|---|---|---|
Top | Description |
#define OATHAPI #define OATH_VERSION #define OATH_VERSION_NUMBER enum oath_rc; int oath_init (void
); int oath_done (void
); const char * oath_check_version (const char *req_version
); int oath_hex2bin (char *hexstr
,char *binstr
,size_t *binlen
); #define OATH_HOTP_LENGTH (digits, checksum) #define OATH_HOTP_DYNAMIC_TRUNCATION int oath_hotp_generate (const char *secret
,size_t secret_length
,uint64_t moving_factor
,unsigned digits
,bool add_checksum
,size_t truncation_offset
,char *output_otp
); int oath_hotp_validate (const char *secret
,size_t secret_length
,uint64_t start_moving_factor
,size_t window
,const char *otp
); int oath_authenticate_usersfile (const char *usersfile
,const char *username
,const char *otp
,size_t window
,const char *passwd
,time_t *last_otp
);
# define OATH_VERSION "1.2.2"
Pre-processor symbol with a string that describe the header file
version number. Used together with oath_check_version()
to verify
header file and run-time library consistency.
# define OATH_VERSION_NUMBER 0x010202
Pre-processor symbol with a hexadecimal value describing the header file version number. For example, when the header version is 1.2.3 this symbol will have the value 0x010203.
typedef enum { OATH_OK = 0, OATH_CRYPTO_ERROR = -1, OATH_INVALID_DIGITS = -2, OATH_PRINTF_ERROR = -3, OATH_INVALID_HEX = -4, OATH_TOO_SMALL_BUFFER = -5, OATH_INVALID_OTP = -6, OATH_REPLAYED_OTP = -7, OATH_BAD_PASSWORD = -8, OATH_INVALID_COUNTER = -9, OATH_INVALID_TIMESTAMP = -10, OATH_NO_SUCH_FILE = -11, OATH_UNKNOWN_USER = -12, OATH_FILE_SEEK_ERROR = -13, OATH_FILE_CREATE_ERROR = -14, OATH_FILE_LOCK_ERROR = -15, OATH_FILE_RENAME_ERROR = -16, OATH_FILE_UNLINK_ERROR = -17, OATH_TIME_ERROR = -18, } oath_rc;
Return codes for OATH functions. All return codes are negative except for the successful code OATH_OK which are guaranteed to be 0. Positive values are reserved for non-error return codes.
Note that the oath_rc enumeration may be extended at a later date to include new return codes.
Successful return | |
Internal error in crypto functions | |
Unsupported number of OTP digits | |
Error from system printf call | |
Hex string is invalid | |
The output buffer is too small | |
The OTP is not valid | |
The OTP has been replayed | |
The password does not match | |
The counter value is corrupt | |
The timestamp is corrupt | |
The supplied filename does not exist | |
Cannot find information about user | |
System error when seeking in file | |
System error when creating file | |
System error when locking file | |
System error when renaming file | |
System error when removing file | |
System error for time manipulation |
const char * oath_check_version (const char *req_version
);
Check OATH library version.
See OATH_VERSION
for a suitable req_version
string.
This function is one of few in the library that can be used without
a successful call to oath_init()
.
|
version string to compare with, or NULL .
|
Returns : |
Check that the version of the library is at
minimum the one given as a string in req_version and return the
actual version string of the library; return NULL if the
condition is not met. If NULL is passed to this function no
check is done and only the version string is returned.
|
int oath_hex2bin (char *hexstr
,char *binstr
,size_t *binlen
);
Convert string with hex data to binary data.
Non-hexadecimal data are not ignored but instead will lead to an
OATH_INVALID_HEX
error.
If binstr
is NULL
, then binlen
will be populated with the
necessary length. If the binstr
buffer is too small,
OATH_TOO_SMALL_BUFFER
is returned and binlen
will contain the
necessary length.
|
input string with hex data |
|
output string that holds binary data, or NULL
|
|
output variable holding needed length of binstr
|
Returns : |
On success, OATH_OK (zero) is returned, otherwise an
error code is returned.
|
#define OATH_HOTP_LENGTH(digits, checksum) (digits + (checksum ? 1 : 0))
|
|
|
int oath_hotp_generate (const char *secret
,size_t secret_length
,uint64_t moving_factor
,unsigned digits
,bool add_checksum
,size_t truncation_offset
,char *output_otp
);
Generate a one-time-password using the HOTP algorithm as described in RFC 4226.
Use a value of OATH_HOTP_DYNAMIC_TRUNCATION
for truncation_offset
unless you really need a specific truncation offset.
To find out the size of the OTP you may use the OATH_HOTP_LENGTH()
macro. The output_otp
buffer must be have room for that length
plus one for the terminating NUL.
Currently only values 6, 7 and 8 for digits
are supported, and the
add_checksum
value is ignored. These restrictions may be lifted
in future versions, although some limitations are inherent in the
protocol.
|
the shared secret string |
|
length of secret
|
|
a counter indicating the current OTP to generate |
|
number of requested digits in the OTP, excluding checksum |
|
whether to add a checksum digit or not |
|
use a specific truncation offset |
|
output buffer, must have room for the output OTP plus zero |
Returns : |
On success, OATH_OK (zero) is returned, otherwise an
error code is returned.
|
int oath_hotp_validate (const char *secret
,size_t secret_length
,uint64_t start_moving_factor
,size_t window
,const char *otp
);
Validate an OTP according to OATH HOTP algorithm per RFC 4226.
Currently only OTP lengths of 6, 7 or 8 digits are supported. This restrictions may be lifted in future versions, although some limitations are inherent in the protocol.
|
the shared secret string |
|
length of secret
|
|
start counter in OTP stream |
|
how many OTPs from start counter to test |
|
the OTP to validate. |
Returns : |
Returns position in OTP window (zero is first position),
or OATH_INVALID_OTP if no OTP was found in OTP window, or an
error code.
|
int oath_authenticate_usersfile (const char *usersfile
,const char *username
,const char *otp
,size_t window
,const char *passwd
,time_t *last_otp
);
Authenticate user named username
with the one-time password otp
and (optional) password passwd
. Credentials are read (and
updated) from a text file named usersfile
.
|
string with user credential filename, in UsersFile format |
|
string with name of user |
|
string with one-time password to authenticate |
|
how many future OTPs to search |
|
string with password, or NULL to disable password checking
|
|
output variable holding last successful authentication |
Returns : |
On successful validation, OATH_OK is returned. If the
supplied otp is the same as the last successfully authenticated
one-time password, OATH_REPLAYED_OTP is returned and the
timestamp of the last authentication is returned in last_otp .
If the one-time password is not found in the indicated search
window, OATH_INVALID_OTP is returned. Otherwise, an error code
is returned.
|