#include <OathStore.h>

Public Member Functions
bool	readAccount (uint16_t slot, OathEntry *out)
	Reads one OATH entry from secure-element storage.
bool	addAccount (uint8_t type, const char name, const char issuer, const char *secretBase32, uint8_t digits, uint32_t period, uint8_t algorithm, uint64_t counter, uint8_t flags=0)
	Adds a new OATH entry from a Base32 secret.
bool	updateAccount (uint16_t slot, uint8_t type, const char name, const char issuer, const char *secretBase32, uint8_t digits, uint32_t period, uint8_t algorithm, uint64_t counter, uint8_t flags=0)
	Updates an existing OATH entry.
bool	deleteAccount (uint16_t slot)
	Deletes account in logical slot.
int	challengeResponse (const char entryName, const uint8_t challenge, size_t clen, uint8_t out, bool touchRequiredOut=nullptr)
	Computes the raw HMAC challenge-response for a CR entry by name.
int	challengeResponseUsbSlot (const uint8_t challenge, size_t clen, uint8_t out, bool *touchRequiredOut=nullptr)
	Computes the raw HMAC challenge-response for the USB-CR slot entry.
bool	findUsbCrSlot (uint16_t *slotOut) const
	Finds the logical slot of the CR entry flagged as the USB-CR slot.
void	clearUsbCrFlagExcept (uint16_t keepSlot)
	Clears the USB-CR-slot flag on every entry except `keepSlot`.
bool	findByName (const char name, uint16_t slotOut) const
	Finds a logical slot index by account name.
int8_t	generateCode (uint16_t slot, char *codeOut, size_t codeOutLen)
	Renders the current code for an entry into `codeOut`.
bool	isTimeValid () const
	Returns whether system time is considered valid for TOTP.
uint8_t	timeRemaining (uint32_t period) const
	Returns seconds remaining in current TOTP time step.
void	setSlotRange (const cdc::core::IModule::SlotRange &range)
	Configures logical-to-physical slot mapping for OATH entries.
uint16_t	capacity () const
bool	toPhysicalSlot (uint16_t logicalIndex, uint16_t *slotOut) const
bool	toLogicalSlot (uint16_t slot, uint16_t *logicalIndexOut) const
bool	hasSlotRange () const
uint8_t	moduleId () const
uint16_t	rmemStart () const
uint16_t	rmemEnd () const

Static Public Member Functions
static OathStore &	instance ()
	Returns singleton OATH store instance.

Static Public Attributes
static constexpr uint8_t	NAME_LEN = 16
static constexpr uint8_t	ISSUER_LEN = 32
static constexpr uint8_t	SECRET_LEN = 64
static constexpr uint8_t	DEFAULT_DIGITS = 6
static constexpr uint32_t	DEFAULT_PERIOD = 30

Detailed Description

Definition at line 55 of file OathStore.h.

Member Function Documentation

◆ addAccount()

bool cdc::mod_2fa::OathStore::addAccount	(	uint8_t	type,
		const char *	name,
		const char *	issuer,
		const char *	secretBase32,
		uint8_t	digits,
		uint32_t	period,
		uint8_t	algorithm,
		uint64_t	counter,
		uint8_t	flags = 0 )

Adds a new OATH entry from a Base32 secret.

Parameters

type	Entry type (OathType).
name	Account label.
issuer	Optional issuer text.
secretBase32	Base32 secret.
digits	Desired output digits.
period	TOTP period in seconds.
algorithm	Hash algorithm identifier.
counter	Initial HOTP counter (ignored for TOTP).
flags	Entry flag bits (OathFlag).

Returns: true on successful write.

Definition at line 289 of file OathStore.cpp.

References cdc::mod_2fa::base32Decode(), flags, LOG_E, LOG_W, name, cdc::hal::ISecureElement::RMEM_NAME_LEN, SECRET_LEN, TAG, cdc::mod_2fa::validateOathParams(), and cdc::mod_2fa::writePayload().

Referenced by cdc::mod_2fa::cmd_totp_add(), cdc::mod_2fa::importOathEntry(), and cdc::mod_2fa::wizardFinish().

◆ capacity()

uint16_t cdc::mod_2fa::OathStore::capacity ( ) const

inline

Definition at line 153 of file OathStore.h.

Referenced by cdc::mod_2fa::ensureListBuffers().

◆ challengeResponse()

int cdc::mod_2fa::OathStore::challengeResponse	(	const char *	entryName,
		const uint8_t *	challenge,
		size_t	clen,
		uint8_t *	out,
		bool *	touchRequiredOut = nullptr )

Computes the raw HMAC challenge-response for a CR entry by name.

Computes the raw HMAC challenge-response for a named CR entry.

Looks up the named entry, requires it to be of type CR, and computes the full untruncated HMAC(secret, challenge) using the entry's algorithm. No dynamic truncation is applied (unlike TOTP/HOTP).

Parameters

entryName	Account label to look up.
challenge	Challenge bytes.
clen	Challenge length in bytes.
out	Output buffer for the digest (must hold at least 32 bytes).
touchRequiredOut	Optional; receives the entry's touch-required flag.

Returns: Response length (20 for SHA1, 32 for SHA256), or -1 on failure or when the named entry is missing or not a CR entry.

Shares the same HMAC engine as TOTP/HOTP via hmacCompute, but returns the full digest without dynamic truncation. SHA512 is rejected here because neither transport carries it and the unified validator already limits CR to SHA1/SHA256 at write time.

Parameters

entryName	Account label to look up.
challenge	Challenge bytes.
clen	Challenge length in bytes.
out	Output digest buffer (>= 32 bytes).
touchRequiredOut	Optional; receives the entry's touch-required flag.

Returns: Digest length, or -1 on failure.

Definition at line 634 of file OathStore.cpp.

References cdc::mod_2fa::OathEntry::algorithm, cdc::mod_2fa::CR, findByName(), cdc::mod_2fa::OathEntry::flags, LOG_W, readAccount(), cdc::mod_2fa::OathEntry::secret, cdc::mod_2fa::OathEntry::secretLen, cdc::mod_2fa::SHA1, cdc::mod_2fa::SHA256, TAG, cdc::mod_2fa::OathFlag::TOUCH_REQUIRED, and cdc::mod_2fa::OathEntry::type.

Referenced by cdc::mod_2fa::ble_chalresp_tick(), cdc::mod_2fa::TwoFaModule::challengeResponse(), challengeResponseUsbSlot(), and cdc::mod_2fa::cmd_chalresp().

◆ challengeResponseUsbSlot()

int cdc::mod_2fa::OathStore::challengeResponseUsbSlot	(	const uint8_t *	challenge,
		size_t	clen,
		uint8_t *	out,
		bool *	touchRequiredOut = nullptr )

Computes the raw HMAC challenge-response for the USB-CR slot entry.

Resolves the single CR entry flagged OathFlag::USB_CR_SLOT (the designated YubiKey slot-2 responder for the USB OTP-HID transport) and computes its untruncated HMAC(secret, challenge). No touch gate is applied here; the caller withholds the response until confirmed.

Parameters

challenge	Challenge bytes.
clen	Challenge length in bytes.
out	Output buffer for the digest (must hold at least 32 bytes).
touchRequiredOut	Optional; receives the entry's touch-required flag.

Returns: Response length (20 for SHA1, 32 for SHA256), or -1 when no entry is designated or computation fails.

Parameters

challenge	Challenge bytes.
clen	Challenge length in bytes.
out	Output digest buffer (>= 32 bytes).
touchRequiredOut	Optional; receives the entry's touch-required flag.

Returns: Digest length, or -1 on failure.

Definition at line 721 of file OathStore.cpp.

References challengeResponse(), findUsbCrSlot(), cdc::mod_2fa::OathEntry::name, and readAccount().

Referenced by cdc::mod_2fa::TwoFaModule::challengeResponseUsbSlot().

◆ clearUsbCrFlagExcept()

void cdc::mod_2fa::OathStore::clearUsbCrFlagExcept ( uint16_t keepSlot )

Clears the USB-CR-slot flag on every entry except keepSlot.

Enforces the "exactly one USB-CR responder" invariant: when an entry is designated, any previously designated entry is demoted.

Parameters

keepSlot	Logical slot to keep designated (use 0xFFFF to clear all).
keepSlot	Logical slot to keep designated (0xFFFF clears all).

Definition at line 741 of file OathStore.cpp.

Referenced by cdc::mod_2fa::wizardFinish().

◆ deleteAccount()

bool cdc::mod_2fa::OathStore::deleteAccount ( uint16_t slot )

Deletes account in logical slot.

Parameters

slot	Logical slot index.

Returns: true on successful erase.

Definition at line 370 of file OathStore.cpp.

References cdc::core::TropicStorage::eraseSlot(), cdc::hal::getSecureElementInstance(), cdc::core::TropicStorage::instance(), cdc::hal::OK, and toPhysicalSlot().

Referenced by cdc::mod_2fa::cmd_totp_del().

◆ findByName()

bool cdc::mod_2fa::OathStore::findByName	(	const char *	name,
		uint16_t *	slotOut ) const

Finds a logical slot index by account name.

Finds the logical slot index of an entry by account name.

Parameters

name	Account label to search for.
slotOut	Receives the logical slot index on success.

Returns: true if an entry with that name exists.

Parameters

name	Account label to search for.
slotOut	Receives the logical slot index on success.

Returns: true if an entry with that name was found.

Definition at line 586 of file OathStore.cpp.

References cdc::core::TropicStorage::forEachSlot(), cdc::core::TropicStorage::instance(), instance(), name, cdc::hal::ISecureElement::RMEM_NAME_LEN, and toLogicalSlot().

Referenced by challengeResponse(), and cdc::mod_2fa::importOathEntry().

◆ findUsbCrSlot()

bool cdc::mod_2fa::OathStore::findUsbCrSlot ( uint16_t * slotOut ) const

Finds the logical slot of the CR entry flagged as the USB-CR slot.

Finds the logical slot of the entry flagged as the USB-CR responder.

Parameters

slotOut Receives the logical slot index on success.

Returns: true if a USB-CR-designated entry exists.

Parameters

slotOut Receives the logical slot index on success.

Returns: true if a USB-CR-designated CR entry exists.

Definition at line 679 of file OathStore.cpp.

References cdc::mod_2fa::CR, cdc::mod_2fa::OathEntry::flags, cdc::core::TropicStorage::forEachSlot(), cdc::core::TropicStorage::instance(), instance(), readAccount(), toLogicalSlot(), cdc::mod_2fa::OathEntry::type, and cdc::mod_2fa::OathFlag::USB_CR_SLOT.

Referenced by challengeResponseUsbSlot().

◆ generateCode()

int8_t cdc::mod_2fa::OathStore::generateCode	(	uint16_t	slot,
		char *	codeOut,
		size_t	codeOutLen )

Renders the current code for an entry into codeOut.

Generates a formatted code string for an account slot.

For TOTP this uses the wall-clock time step; for HOTP it consumes and persists the moving counter (incremented and written back to the slot).

Parameters

slot	Logical slot index.
codeOut	Output buffer (must hold at least 9 bytes for 8-digit codes).
codeOutLen	Size of `codeOut` in bytes.

Returns: Remaining seconds in the current TOTP step, 0 for HOTP, or -1 on failure.

Parameters

slot	Logical slot index.
codeOut	Output text buffer.
codeOutLen	Output buffer size.

Returns: Remaining seconds for the current TOTP step, 0 for HOTP, or -1 on failure.

Definition at line 520 of file OathStore.cpp.

References cdc::mod_2fa::OathEntry::algorithm, cdc::mod_2fa::OathEntry::counter, DEFAULT_PERIOD, cdc::mod_2fa::OathEntry::digits, cdc::mod_2fa::formatCode(), cdc::mod_2fa::HOTP, isTimeValid(), LOG_E, cdc::mod_2fa::OathEntry::period, readAccount(), cdc::mod_2fa::OathEntry::secret, cdc::mod_2fa::OathEntry::secretLen, TAG, timeRemaining(), and cdc::mod_2fa::OathEntry::type.

Referenced by cdc::mod_2fa::cmd_totp_get().

◆ hasSlotRange()

bool cdc::mod_2fa::OathStore::hasSlotRange ( ) const

inline

Definition at line 160 of file OathStore.h.

Referenced by cdc::mod_2fa::TwoFaModule::exportBackup().

◆ instance()

OathStore & cdc::mod_2fa::OathStore::instance ( )

static

Returns singleton OATH store instance.

Returns: Store singleton reference.

Definition at line 149 of file OathStore.cpp.

Referenced by cdc::mod_2fa::ble_chalresp_tick(), cdc::mod_2fa::TwoFaModule::challengeResponse(), cdc::mod_2fa::TwoFaModule::challengeResponseUsbSlot(), clearUsbCrFlagExcept(), cdc::mod_2fa::cmd_chalresp(), cdc::mod_2fa::cmd_totp_add(), cdc::mod_2fa::cmd_totp_del(), cdc::mod_2fa::cmd_totp_get(), cdc::mod_2fa::cmd_totp_list(), cdc::mod_2fa::ensureListBuffers(), cdc::mod_2fa::TwoFaModule::exportBackup(), findByName(), cdc::mod_2fa::findSlotByIndex(), findUsbCrSlot(), cdc::mod_2fa::importOathEntry(), cdc::mod_2fa::TwoFaModule::init(), cdc::mod_2fa::rebuildList(), cdc::mod_2fa::wizardEdit(), cdc::mod_2fa::wizardFinish(), and cdc::mod_2fa::writePayload().

◆ isTimeValid()

bool cdc::mod_2fa::OathStore::isTimeValid ( ) const

Returns whether system time is considered valid for TOTP.

Returns: true when date is at least year 2024.

Definition at line 573 of file OathStore.cpp.

Referenced by generateCode().

◆ moduleId()

uint8_t cdc::mod_2fa::OathStore::moduleId ( ) const

inline

Definition at line 161 of file OathStore.h.

Referenced by cdc::mod_2fa::TwoFaModule::exportBackup(), and cdc::mod_2fa::writePayload().

◆ readAccount()

bool cdc::mod_2fa::OathStore::readAccount	(	uint16_t	slot,
		OathEntry *	out )

Reads one OATH entry from secure-element storage.

Parameters

slot	Logical slot index.
out	Output entry structure.

Returns: true on successful read.

Definition at line 168 of file OathStore.cpp.

Referenced by challengeResponse(), challengeResponseUsbSlot(), cdc::mod_2fa::TwoFaModule::exportBackup(), findUsbCrSlot(), and generateCode().

◆ rmemEnd()

uint16_t cdc::mod_2fa::OathStore::rmemEnd ( ) const

inline

Definition at line 163 of file OathStore.h.

Referenced by cdc::mod_2fa::TwoFaModule::exportBackup().

◆ rmemStart()

uint16_t cdc::mod_2fa::OathStore::rmemStart ( ) const

inline

Definition at line 162 of file OathStore.h.

Referenced by cdc::mod_2fa::TwoFaModule::exportBackup().

◆ setSlotRange()

void cdc::mod_2fa::OathStore::setSlotRange ( const cdc::core::IModule::SlotRange & range )

Configures logical-to-physical slot mapping for OATH entries.

Parameters

range Slot range descriptor (RMEM fields are consumed).

Definition at line 158 of file OathStore.cpp.

References setSlotRange().

Referenced by cdc::mod_2fa::TwoFaModule::init(), and setSlotRange().

◆ timeRemaining()

uint8_t cdc::mod_2fa::OathStore::timeRemaining ( uint32_t period ) const

Returns seconds remaining in current TOTP time step.

Parameters

period TOTP period in seconds.

Returns: Remaining seconds.

Definition at line 564 of file OathStore.cpp.

References DEFAULT_PERIOD.

Referenced by generateCode().

◆ toLogicalSlot()

bool cdc::mod_2fa::OathStore::toLogicalSlot	(	uint16_t	slot,
		uint16_t *	logicalIndexOut ) const

inline

Definition at line 157 of file OathStore.h.

Referenced by cdc::mod_2fa::TwoFaModule::exportBackup(), findByName(), and findUsbCrSlot().

◆ toPhysicalSlot()

bool cdc::mod_2fa::OathStore::toPhysicalSlot	(	uint16_t	logicalIndex,
		uint16_t *	slotOut ) const

inline

Definition at line 154 of file OathStore.h.

Referenced by deleteAccount(), readAccount(), and updateAccount().

◆ updateAccount()

bool cdc::mod_2fa::OathStore::updateAccount	(	uint16_t	slot,
		uint8_t	type,
		const char *	name,
		const char *	issuer,
		const char *	secretBase32,
		uint8_t	digits,
		uint32_t	period,
		uint8_t	algorithm,
		uint64_t	counter,
		uint8_t	flags = 0 )

Updates an existing OATH entry.

Parameters

slot	Logical slot index.
type	Entry type (OathType).
name	Account label.
issuer	Optional issuer text.
secretBase32	Base32 secret.
digits	Desired output digits.
period	TOTP period in seconds.
algorithm	Hash algorithm identifier.
counter	HOTP counter (ignored for TOTP).
flags	Entry flag bits (OathFlag).

Returns: true on successful update.

Definition at line 337 of file OathStore.cpp.

References cdc::mod_2fa::base32Decode(), flags, LOG_E, LOG_W, name, cdc::hal::ISecureElement::RMEM_NAME_LEN, SECRET_LEN, TAG, toPhysicalSlot(), cdc::mod_2fa::validateOathParams(), and cdc::mod_2fa::writePayload().

Referenced by cdc::mod_2fa::importOathEntry(), and cdc::mod_2fa::wizardFinish().

Member Data Documentation

◆ DEFAULT_DIGITS

uint8_t cdc::mod_2fa::OathStore::DEFAULT_DIGITS = 6

staticconstexpr

Definition at line 60 of file OathStore.h.

Referenced by cdc::mod_2fa::cmd_totp_add(), readAccount(), cdc::mod_2fa::validateOathParams(), cdc::mod_2fa::wizardStart(), and cdc::mod_2fa::writePayload().

◆ DEFAULT_PERIOD

uint32_t cdc::mod_2fa::OathStore::DEFAULT_PERIOD = 30

staticconstexpr

Definition at line 61 of file OathStore.h.

Referenced by cdc::mod_2fa::cmd_totp_add(), generateCode(), readAccount(), timeRemaining(), cdc::mod_2fa::validateOathParams(), cdc::mod_2fa::wizardStart(), and cdc::mod_2fa::writePayload().

◆ ISSUER_LEN

uint8_t cdc::mod_2fa::OathStore::ISSUER_LEN = 32

staticconstexpr

Definition at line 58 of file OathStore.h.

Referenced by cdc::mod_2fa::cmd_totp_add(), and cdc::mod_2fa::onWizardSecret().

◆ NAME_LEN

uint8_t cdc::mod_2fa::OathStore::NAME_LEN = 16

staticconstexpr

Definition at line 57 of file OathStore.h.

Referenced by cdc::mod_2fa::cmd_chalresp(), cdc::mod_2fa::cmd_totp_add(), cdc::mod_2fa::onWizardType(), and cdc::mod_2fa::wizardEdit().

◆ SECRET_LEN

uint8_t cdc::mod_2fa::OathStore::SECRET_LEN = 64

staticconstexpr

Definition at line 59 of file OathStore.h.

Referenced by addAccount(), and updateAccount().

The documentation for this class was generated from the following files:

components/mod_2fa/include/mod_2fa/OathStore.h
components/mod_2fa/src/OathStore.cpp

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Function Documentation

◆ addAccount()

◆ capacity()

◆ challengeResponse()

◆ challengeResponseUsbSlot()

◆ clearUsbCrFlagExcept()

◆ deleteAccount()

◆ findByName()

◆ findUsbCrSlot()

◆ generateCode()

◆ hasSlotRange()

◆ instance()

◆ isTimeValid()

◆ moduleId()

◆ readAccount()

◆ rmemEnd()

◆ rmemStart()

◆ setSlotRange()

◆ timeRemaining()

◆ toLogicalSlot()

◆ toPhysicalSlot()

◆ updateAccount()

Member Data Documentation

◆ DEFAULT_DIGITS

◆ DEFAULT_PERIOD

◆ ISSUER_LEN

◆ NAME_LEN

◆ SECRET_LEN