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

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 0

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 0x010000

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

This function initializes the HOTP library. Every user of this library needs to call this function before using other functions. You should call hotp_done() when use of the HOTP library is no longer needed.

Note that this function may also initialize Libgcrypt, if the HOTP library is built with libgcrypt support and libgcrypt has not been initialized before. Thus if you want to manually initialize libgcrypt you must do it before calling this function. This is useful in cases you want to disable libgcrypt's internal lockings etc.

Returns :

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

hotp_done ()

int                 hotp_done                           (void);

This function deinitializes the HOTP library, which were initialized using hotp_init(). After calling this function, no other HOTP library function may be called except for to re-initialize the library using hotp_init().

Returns :

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

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.