| 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.1"
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 0x010201
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.
|