hotp

hotp

Synopsis

#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);

Description

Details

HOTPAPI

#define             HOTPAPI


HOTP_VERSION

# 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.


HOTP_VERSION_MAJOR

# 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.


HOTP_VERSION_MINOR

# 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.


HOTP_VERSION_PATCH

# 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.


HOTP_VERSION_NUMBER

# 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.


enum hotp_rc

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.

HOTP_OK

Successful return

HOTP_CRYPTO_ERROR

Internal error in crypto functions

HOTP_INVALID_DIGITS

Unsupported number of OTP digits

HOTP_PRINTF_ERROR

Error from system printf call

HOTP_INVALID_HEX

Hex string is invalid

HOTP_TOO_SMALL_BUFFER

The output buffer is too small

HOTP_INVALID_OTP

The OTP is not valid

HOTP_REPLAYED_OTP

The OTP has been replayed

HOTP_BAD_PASSWORD

The password does not match

HOTP_INVALID_COUNTER

The counter value is corrupt

HOTP_INVALID_TIMESTAMP

The timestamp is corrupt

HOTP_NO_SUCH_FILE

The supplied filename does not exist

HOTP_UNKNOWN_USER

Cannot find information about user

HOTP_FILE_SEEK_ERROR

System error when seeking in file

HOTP_FILE_CREATE_ERROR

System error when creating file

HOTP_FILE_LOCK_ERROR

System error when locking file

HOTP_FILE_RENAME_ERROR

System error when renaming file

HOTP_FILE_UNLINK_ERROR

System error when removing file

HOTP_TIME_ERROR

System error for time manipulation

HOTP_DYNAMIC_TRUNCATION

#define HOTP_DYNAMIC_TRUNCATION SIZE_MAX


HOTP_OTP_LENGTH()

#define HOTP_OTP_LENGTH(digits, checksum) (digits + (checksum ? 1 : 0))

digits :

checksum :


hotp_init ()

int                 hotp_init                           (void);

Returns :


hotp_done ()

int                 hotp_done                           (void);

Returns :


hotp_check_version ()

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().

req_version :

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.

hotp_hex2bin ()

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.

hexstr :

input string with hex data

binstr :

output string that holds binary data, or NULL

binlen :

output variable holding needed length of binstr

Returns :

On success, HOTP_OK (zero) is returned, otherwise an error code is returned.

hotp_generate_otp ()

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.

secret :

the shared secret string

secret_length :

length of secret

moving_factor :

a counter indicating the current OTP to generate

digits :

number of requested digits in the OTP, excluding checksum

add_checksum :

whether to add a checksum digit or not

truncation_offset :

use a specific truncation offset

output_otp :

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.

hotp_validate_otp ()

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.

secret :

the shared secret string

secret_length :

length of secret

start_moving_factor :

start counter in OTP stream

window :

how many OTPs from start counter to test

otp :

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.

hotp_authenticate_usersfile ()

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.

usersfile :

string with user credential filename, in UsersFile format

username :

string with name of user

otp :

string with one-time password to authenticate

window :

how many future OTPs to search

passwd :

string with password, or NULL to disable password checking

last_otp :

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.