| Libhotp API Reference Manual | ||||
|---|---|---|---|---|
| Top | Description | ||||
#define HOTPAPI #define HOTP_VERSION #define HOTP_VERSION_MAJOR #define HOTP_VERSION_MINOR #define HOTP_VERSION_PATCH #define HOTP_VERSION_NUMBER enum hotp_rc; #define HOTP_DYNAMIC_TRUNCATION #define HOTP_OTP_LENGTH (digits, checksum) int hotp_init (void); int hotp_done (void); const char * hotp_check_version (const char *req_version); int hotp_hex2bin (char *hexstr,char *binstr,size_t *binlen); int hotp_generate_otp (const char *secret,size_t secret_length,uint64_t moving_factor,unsigned digits,bool add_checksum,size_t truncation_offset,char *output_otp); int hotp_validate_otp (const char *secret,size_t secret_length,uint64_t start_moving_factor,size_t window,const char *otp); int hotp_authenticate_usersfile (const char *usersfile,const char *username,const char *otp,size_t window,const char *passwd,time_t *last_otp);
# define HOTP_VERSION "1.0.1"
Pre-processor symbol with a string that describe the header file
version number. Used together with hotp_check_version() to verify
header file and run-time library consistency.
# define HOTP_VERSION_MAJOR 0
Pre-processor symbol with a decimal value that describe the major level of the header file version number. For example, when the header version is 1.2.3 this symbol will be 1.
# define HOTP_VERSION_MINOR 0
Pre-processor symbol with a decimal value that describe the minor level of the header file version number. For example, when the header version is 1.2.3 this symbol will be 2.
# define HOTP_VERSION_PATCH 1
Pre-processor symbol with a decimal value that describe the patch level of the header file version number. For example, when the header version is 1.2.3 this symbol will be 3.
# define HOTP_VERSION_NUMBER 0x010001
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
{
HOTP_OK = 0,
HOTP_CRYPTO_ERROR = -1,
HOTP_INVALID_DIGITS = -2,
HOTP_PRINTF_ERROR = -3,
HOTP_INVALID_HEX = -4,
HOTP_TOO_SMALL_BUFFER = -5,
HOTP_INVALID_OTP = -6,
HOTP_REPLAYED_OTP = -7,
HOTP_BAD_PASSWORD = -8,
HOTP_INVALID_COUNTER = -9,
HOTP_INVALID_TIMESTAMP = -10,
HOTP_NO_SUCH_FILE = -11,
HOTP_UNKNOWN_USER = -12,
HOTP_FILE_SEEK_ERROR = -13,
HOTP_FILE_CREATE_ERROR = -14,
HOTP_FILE_LOCK_ERROR = -15,
HOTP_FILE_RENAME_ERROR = -16,
HOTP_FILE_UNLINK_ERROR = -17,
HOTP_TIME_ERROR = -18,
} hotp_rc;
Return codes for HOTP functions. All return codes are negative except for the successful code HOTP_OK which are guaranteed to be 0. Positive values are reserved for non-error return codes.
Note that the hotp_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 |
#define HOTP_OTP_LENGTH(digits, checksum) (digits + (checksum ? 1 : 0))
|
|
|
const char * hotp_check_version (const char *req_version);
Check HOTP library version.
See HOTP_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 hotp_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 hotp_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
HOTP_INVALID_HEX error.
If binstr is NULL, then binlen will be populated with the
necessary length. If the binstr buffer is too small,
HOTP_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, HOTP_OK (zero) is returned, otherwise an
error code is returned.
|
int hotp_generate_otp (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 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 HOTP_OTP_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, HOTP_OK (zero) is returned, otherwise an
error code is returned.
|
int hotp_validate_otp (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 HOTP_INVALID_OTP if no OTP was found in OTP window, or an
error code.
|
int hotp_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, HOTP_OK is returned. If the
supplied otp is the same as the last successfully authenticated
one-time password, HOTP_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, HOTP_INVALID_OTP is returned. Otherwise, an error code
is returned.
|