tfac.h File Reference

2FA (Two-Factor Authentication) for C using TOTP/HOTP. More...

#include <time.h>
#include <stdint.h>
#include <stddef.h>

Include dependency graph for tfac.h:

Go to the source code of this file.

Classes
struct	tfac_token
struct	tfac_secret
struct	tfac_version_number

Macros
#define	TFAC_API
#define	TFAC_MAX_DIGITS   18
#define	TFAC_MAX_SECRET_KEY_SIZE   256
#define	TFAC_DEFAULT_HASH_ALGO   0
#define	TFAC_DEFAULT_DIGITS   6
#define	TFAC_DEFAULT_STEPS   30

Enumerations
enum	tfac_hash_algo { TFAC_SHA1 = 0 , TFAC_SHA224 = 1 , TFAC_SHA256 = 2 }

Functions
TFAC_API struct tfac_secret	tfac_generate_secret ()
TFAC_API struct tfac_token	tfac_totp (const char *secret_key_base32, uint8_t digits, uint8_t steps, enum tfac_hash_algo hash_algo)
TFAC_API uint64_t	tfac_totp_raw (const uint8_t *secret_key, size_t secret_key_length, uint8_t digits, uint8_t steps, enum tfac_hash_algo hash_algo, time_t utc)
TFAC_API uint8_t	tfac_verify_totp (const char *secret_key_base32, const char *totp, uint8_t digits, uint8_t steps, enum tfac_hash_algo hash_algo)
TFAC_API struct tfac_token	tfac_hotp (const char *secret_key_base32, uint8_t digits, uint64_t counter, enum tfac_hash_algo hash_algo)
TFAC_API uint64_t	tfac_hotp_raw (const uint8_t *secret_key, size_t secret_key_length, uint8_t digits, uint64_t counter, enum tfac_hash_algo hash_algo)
TFAC_API struct tfac_version_number	tfac_get_version_number ()

Detailed Description

2FA (Two-Factor Authentication) for C using TOTP/HOTP.

Author

Raphael Beck

Macro Definition Documentation

TFAC_DEFAULT_DIGITS

#define TFAC_DEFAULT_DIGITS   6

Default amount of token digits for typical Google Authenticator tokens (6 digits).

TFAC_DEFAULT_HASH_ALGO

#define TFAC_DEFAULT_HASH_ALGO   0

The default hash algorithm to use for the HMAC is SHA-1.

TFAC_DEFAULT_STEPS

#define TFAC_DEFAULT_STEPS   30

Default step count for typical Google Authenticator token formats (30 seconds).

TFAC_MAX_DIGITS

#define TFAC_MAX_DIGITS   18

The maximum amount of digits in the output token.

Any digits parameter passed to the hotp/totp functions that exceeds this value is clamped to it.

TFAC_MAX_SECRET_KEY_SIZE

#define TFAC_MAX_SECRET_KEY_SIZE   256

Maximum size of 2FA secrets. Keys that exceed this length will be truncated!

Enumeration Type Documentation

tfac_hash_algo

enum tfac_hash_algo

The hash algorithm to use for the HMAC (default is SHA-1).

Function Documentation

tfac_generate_secret()

TFAC_API struct tfac_secret tfac_generate_secret

(

)

Generate a random 2FA secret to use for HOTP/TOTP token generation.

Returns

tfac_secret instance containing both the base32-encoded as well as the raw secret key bytes.

tfac_get_version_number()

TFAC_API struct tfac_version_number tfac_get_version_number

(

)

Gets the current TFAC library version number.

Returns

A tfac_version_number instance containing raw numbers as well as a nicely formatted string (in the format of MAJOR.MINOR.HOTFIX ).

tfac_hotp()

TFAC_API struct tfac_token tfac_hotp	(	const char *	secret_key_base32,
		uint8_t	digits,
		uint64_t	counter,
		enum tfac_hash_algo	hash_algo
	)

Generate an HOTP using a given secret key (which is a base32-encoded, NUL-terminated string).

Parameters

secret_key_base32	The base32-encoded, NUL-terminated string containing the secret key to use for generating the token.
digits	How many digits should the output token contain? If unsure, pass TFAC_DEFAULT_DIGITS.
counter	The counter value to use for HOTP generation (64-bit unsigned integer).
hash_algo	Which hashing algorithm to use for the HMAC: default is SHA-1 (TFAC_DEFAULT_HASH_ALGO).

Returns

The HOTP token.

tfac_hotp_raw()

TFAC_API uint64_t tfac_hotp_raw	(	const uint8_t *	secret_key,
		size_t	secret_key_length,
		uint8_t	digits,
		uint64_t	counter,
		enum tfac_hash_algo	hash_algo
	)

Raw HOTP generator function: this returns the raw, unsigned integer behind an HOTP token.

Leading zeros won't (obviously) be included, so if the generated TOTP happens to be "000420" this will return 420.

Parameters

secret_key	The byte array containing the 2FA secret key to use for generating the token.
secret_key_length	Length of the secret_key byte array.
digits	How many digits should the output token contain? If unsure, pass TFAC_DEFAULT_DIGITS (which is 6).
counter	The counter value to use for HOTP generation (64-bit unsigned integer).
hash_algo	Which hashing algorithm to use for the HMAC: default is SHA-1 (TFAC_DEFAULT_HASH_ALGO).

Returns

The HOTP token as an unsigned 64-bit integer.

tfac_totp()

TFAC_API struct tfac_token tfac_totp	(	const char *	secret_key_base32,
		uint8_t	digits,
		uint8_t	steps,
		enum tfac_hash_algo	hash_algo
	)

Generate a TOTP token using a given secret key (which is a base32-encoded, NUL-terminated string).

Parameters

secret_key_base32	The base32-encoded, NUL-terminated string containing the secret key to use for generating the token.
digits	How many digits should the output token contain? If unsure, pass TFAC_DEFAULT_DIGITS (which is 6).
steps	The step count: default is 30 seconds (TFAC_DEFAULT_STEPS).
hash_algo	Which hashing algorithm to use for the HMAC: default is SHA-1 (TFAC_DEFAULT_HASH_ALGO).

Returns

The TOTP token.

tfac_totp_raw()

TFAC_API uint64_t tfac_totp_raw	(	const uint8_t *	secret_key,
		size_t	secret_key_length,
		uint8_t	digits,
		uint8_t	steps,
		enum tfac_hash_algo	hash_algo,
		time_t	utc
	)

Raw TOTP generator function: this returns the raw, unsigned integer behind a TOTP token.

Leading zeros won't (obviously) be included, so if the generated TOTP happens to be "001502" this will return 1502.

Parameters

secret_key	The byte array containing the 2FA secret key to use for token generation.
secret_key_length	Length of the secret_key byte array.
digits	How many digits should the output token contain? If unsure, pass TFAC_DEFAULT_DIGITS (which is 6).
steps	The step count: default is 30 seconds (TFAC_DEFAULT_STEPS).
hash_algo	Which hashing algorithm to use for the HMAC: default is SHA-1 (TFAC_DEFAULT_HASH_ALGO).
utc	The UTC timestamp for which to generate the TOTP. Pass time(0) to generate a currently valid token!

Returns

The TOTP token as an unsigned 64-bit integer.

tfac_verify_totp()

TFAC_API uint8_t tfac_verify_totp	(	const char *	secret_key_base32,
		const char *	totp,
		uint8_t	digits,
		uint8_t	steps,
		enum tfac_hash_algo	hash_algo
	)

Verifies a TOTP using the given secret_key_base32. If the token is validated successfully, it is obliterated and cannot be validated again: further tries will fail.

Parameters

secret_key_base32	The 2FA secret (Base32-encoded, NUL-terminated string).
totp	The token to verify.
digits	How many digits the token to validate is supposed to contain.
steps	The steps parameter that was used to generate the token,
hash_algo	The hash algorithm that the token was created with (default is SHA-1: TFAC_DEFAULT_HASH_ALGO).

Returns

1 if the token was valid; 0 if verification failed or if the token has already been used.