Botan::Stateful_Key_Index_Registry Class Reference

#include <stateful_key_index_registry.h>

Classes
class	KeyId

Public Member Functions
uint64_t	current_index (const KeyId &key_id)
Stateful_Key_Index_Registry &	operator= (const Stateful_Key_Index_Registry &)=delete
Stateful_Key_Index_Registry &	operator= (Stateful_Key_Index_Registry &&)=delete
uint64_t	remaining_operations (const KeyId &key_id)
std::optional< uint64_t >	reserve_next_index (const KeyId &key_id)
void	set_index_lower_bound (const KeyId &key_id, uint64_t min)
	Stateful_Key_Index_Registry (const Stateful_Key_Index_Registry &)=delete
	Stateful_Key_Index_Registry (Stateful_Key_Index_Registry &&)=delete
	~Stateful_Key_Index_Registry ()

Static Public Member Functions
static Stateful_Key_Index_Registry &	global ()

Detailed Description

A process-wide registry mapping stateful key identity to a shared monotonic counter. Ensures that independent copies of the same key material (e.g. deserialized separately) share a single leaf index, preventing catastrophic one-time signature reuse.

The same key material used with different algorithm parameters is tracked independently, since the parameters are part of the key identity. The maximum operation count is a function of the identity.

Used by XMSS and HSS-LMS.

If this registry or a key identity is inherited across fork(), it fails closed and refuses to issue further indices in the child process.

Definition at line 36 of file stateful_key_index_registry.h.

Constructor & Destructor Documentation

Stateful_Key_Index_Registry() [1/2]

Botan::Stateful_Key_Index_Registry::Stateful_Key_Index_Registry ( const Stateful_Key_Index_Registry & )

delete

References Stateful_Key_Index_Registry().

Referenced by global(), operator=(), operator=(), Stateful_Key_Index_Registry(), Stateful_Key_Index_Registry(), and ~Stateful_Key_Index_Registry().

Stateful_Key_Index_Registry() [2/2]

Botan::Stateful_Key_Index_Registry::Stateful_Key_Index_Registry ( Stateful_Key_Index_Registry && )

delete

References Stateful_Key_Index_Registry().

~Stateful_Key_Index_Registry()

Botan::Stateful_Key_Index_Registry::~Stateful_Key_Index_Registry ( )

default

References Stateful_Key_Index_Registry().

Member Function Documentation

current_index()

uint64_t Botan::Stateful_Key_Index_Registry::current_index

(

const KeyId &

key_id

)

Return the current counter

Definition at line 122 of file stateful_key_index_registry.cpp.

                                                                       {
   const lock_guard_type<mutex_type> lock(m_mutex);
   auto idx = this->lookup(key_id);
   return idx->second;
}

References Botan::lock().

Referenced by Botan::HSS_LMS_PrivateKeyInternal::to_bytes().

global()

Stateful_Key_Index_Registry & Botan::Stateful_Key_Index_Registry::global ( )

static

Retrieve the process-wide instance

Definition at line 18 of file stateful_key_index_registry.cpp.

                                                                 {
   static Stateful_Key_Index_Registry g_registry;
   return g_registry;
}

References Stateful_Key_Index_Registry().

Referenced by Botan::HSS_LMS_PrivateKeyInternal::remaining_operations(), Botan::HSS_LMS_PrivateKeyInternal::set_idx(), and Botan::HSS_LMS_PrivateKeyInternal::to_bytes().

operator=() [1/2]

Stateful_Key_Index_Registry & Botan::Stateful_Key_Index_Registry::operator= ( const Stateful_Key_Index_Registry & )

delete

References Stateful_Key_Index_Registry().

operator=() [2/2]

Stateful_Key_Index_Registry & Botan::Stateful_Key_Index_Registry::operator= ( Stateful_Key_Index_Registry && )

delete

References Stateful_Key_Index_Registry().

remaining_operations()

uint64_t Botan::Stateful_Key_Index_Registry::remaining_operations

(

const KeyId &

key_id

)

If the current counter is >= the key's maximum returns 0, otherwise maximum - counter

Definition at line 146 of file stateful_key_index_registry.cpp.

                                                                              {
   const lock_guard_type<mutex_type> lock(m_mutex);
   const uint64_t idx = this->lookup(key_id)->second;
   const uint64_t max = key_id.max_operations();
 
   if(idx >= max) {
      return 0;
   } else {
      return max - idx;
   }
}

References Botan::lock(), and Botan::Stateful_Key_Index_Registry::KeyId::max_operations().

reserve_next_index()

std::optional< uint64_t > Botan::Stateful_Key_Index_Registry::reserve_next_index

(

const KeyId &

key_id

)

Reserve and return the next counter value, or nullopt if the counter has already reached the key's maximum. The counter never increments past the maximum, so it cannot wrap, and an exhausted key remains exhausted.

Definition at line 128 of file stateful_key_index_registry.cpp.

                                                                                         {
   const lock_guard_type<mutex_type> lock(m_mutex);
   auto idx = this->lookup(key_id);
   const uint64_t cur = idx->second;
   if(cur >= key_id.max_operations()) {
      return std::nullopt;
   }
   idx->second = cur + 1;
   return cur;
}

References Botan::lock(), and Botan::Stateful_Key_Index_Registry::KeyId::max_operations().

set_index_lower_bound()

void Botan::Stateful_Key_Index_Registry::set_index_lower_bound	(	const KeyId &	key_id,
		uint64_t	min )

Set the counter to at least min (but if already higher it will retain its current value)

Definition at line 139 of file stateful_key_index_registry.cpp.

                                                                                         {
   BOTAN_ARG_CHECK(min <= key_id.max_operations(), "Index lower bound exceeds maximum operation count");
   const lock_guard_type<mutex_type> lock(m_mutex);
   auto idx = this->lookup(key_id);
   idx->second = std::max(idx->second, min);
}

References BOTAN_ARG_CHECK, Botan::lock(), and Botan::Stateful_Key_Index_Registry::KeyId::max_operations().

Referenced by Botan::HSS_LMS_PrivateKeyInternal::set_idx().

---

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

• src/lib/pubkey/stateful_key_index/stateful_key_index_registry.h
• src/lib/pubkey/stateful_key_index/stateful_key_index_registry.cpp