![]() |
![]() |
![]() |
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.
|