Botan::HSS_LMS_PrivateKeyInternal Class Reference

The internal HSS-LMS private key. More...

#include <hss.h>

Public Member Functions
void	_const_time_poison () const
void	_const_time_unpoison () const
LMS_PrivateKey	hss_derive_root_lms_private_key () const
	Create the HSS root LMS tree's LMS_PrivateKey using the HSS-LMS private key.
	HSS_LMS_PrivateKeyInternal (const HSS_LMS_Params &hss_params, RandomNumberGenerator &rng)
	Create an internal HSS-LMS private key.
const HSS_LMS_Params &	hss_params () const
	Returns the used HSS-LMS parameters.
HSS_Sig_Idx	remaining_operations () const
	Get the number of remaining signatures for this key.
void	set_idx (HSS_Sig_Idx idx) const
	Set the idx of the next signature to generate.
std::vector< uint8_t >	sign (std::span< const uint8_t > msg) const
	Create a HSS-LMS signature.
size_t	signature_size () const
	Returns the size in bytes of a signature created by this key.
secure_vector< uint8_t >	to_bytes () const
	Returns the key in its encoded format.

Static Public Member Functions
static std::shared_ptr< HSS_LMS_PrivateKeyInternal >	from_bytes_or_throw (std::span< const uint8_t > key_bytes)
	Parse a private HSS-LMS key.

Detailed Description

The internal HSS-LMS private key.

Note that the format is not specified in the RFC 8554, and is Botan specific.

Definition at line 127 of file hss.h.

Constructor & Destructor Documentation

HSS_LMS_PrivateKeyInternal()

Botan::HSS_LMS_PrivateKeyInternal::HSS_LMS_PrivateKeyInternal	(	const HSS_LMS_Params &	hss_params,
		RandomNumberGenerator &	rng )

Create an internal HSS-LMS private key.

Parameters

hss_params	The HSS-LMS parameters for the key.
Random Number Generators	The rng to use.

Definition at line 143 of file hss.cpp.

                                                                                                                   :
      m_hss_params(hss_params),
      m_hss_seed(rng.random_vec<LMS_Seed>(m_hss_params.params_at_level(HSS_Level(0)).lms_params().m())),
      m_identifier(rng.random_vec<LMS_Identifier>(LMS_IDENTIFIER_LEN)),
      m_keyid(
         "HSS-LMS", hss_param_encoding(m_hss_params), m_hss_params.max_sig_count().get(), m_hss_seed, m_identifier),
      m_sig_size(HSS_Signature::size(m_hss_params)) {}

References hss_params(), and Botan::LMS_IDENTIFIER_LEN.

Referenced by from_bytes_or_throw().

Member Function Documentation

_const_time_poison()

void Botan::HSS_LMS_PrivateKeyInternal::_const_time_poison ( ) const

inline

Definition at line 204 of file hss.h.

{ CT::poison(m_hss_seed); }

References Botan::CT::poison().

_const_time_unpoison()

void Botan::HSS_LMS_PrivateKeyInternal::_const_time_unpoison ( ) const

inline

Definition at line 206 of file hss.h.

{ CT::unpoison(m_hss_seed); }

References Botan::CT::unpoison().

from_bytes_or_throw()

std::shared_ptr< HSS_LMS_PrivateKeyInternal > Botan::HSS_LMS_PrivateKeyInternal::from_bytes_or_throw ( std::span< const uint8_t > key_bytes )

static

Parse a private HSS-LMS key.

Parameters

key_bytes

The private key bytes to parse.

Returns

The internal HSS-LMS private key.

Exceptions

Decoding_Error

If parsing the private key fails.

Definition at line 165 of file hss.cpp.

                                     {
   if(key_bytes.size() < sizeof(HSS_Level) + sizeof(HSS_Sig_Idx)) {
      throw Decoding_Error("Too few private key bytes.");
   }
   BufferSlicer slicer(key_bytes);
 
   const auto L = load_be<HSS_Level>(slicer.take<sizeof(HSS_Level)>());
   if(L == 0U || L > HSS_MAX_LEVELS) {
      throw Decoding_Error("Invalid number of HSS layers in private HSS-LMS key.");
   }
 
   const auto sig_idx = load_be<HSS_Sig_Idx>(slicer.take<sizeof(HSS_Sig_Idx)>());
 
   std::vector<HSS_LMS_Params::LMS_LMOTS_Params_Pair> params;
   for(size_t layer = 1; layer <= L; ++layer) {
      if(slicer.remaining() < sizeof(LMS_Algorithm_Type) + sizeof(LMOTS_Algorithm_Type)) {
         throw Decoding_Error("Out of bytes while parsing private HSS-LMS key.");
      }
      const auto lms_type = load_be<LMS_Algorithm_Type>(slicer.take<sizeof(LMS_Algorithm_Type)>());
      const auto lmots_type = load_be<LMOTS_Algorithm_Type>(slicer.take<sizeof(LMOTS_Algorithm_Type)>());
      params.push_back({LMS_Params::create_or_throw(lms_type), LMOTS_Params::create_or_throw(lmots_type)});
   }
   const auto& hash_name = params.at(0).lms_params().hash_name();
 
   for(const auto& param : params) {
      const bool invalid_lmots_hash = param.lmots_params().hash_name() != hash_name;
      const bool invalid_lms_hash = param.lms_params().hash_name() != hash_name;
      if(invalid_lmots_hash || invalid_lms_hash) {
         throw Decoding_Error("Inconsistent hash functions are not allowed.");
      }
   }
 
   if(slicer.remaining() < params.at(0).lms_params().m() + LMS_IDENTIFIER_LEN) {
      throw Decoding_Error("Out of bytes while parsing private HSS-LMS key.");
   }
   auto hss_seed = slicer.copy<LMS_Seed>(params.at(0).lms_params().m());
   auto identifier = slicer.copy<LMS_Identifier>(LMS_IDENTIFIER_LEN);
 
   if(!slicer.empty()) {
      throw Decoding_Error("Private HSS-LMS key contains more bytes than expected.");
   }
   auto sk = std::shared_ptr<HSS_LMS_PrivateKeyInternal>(
      new HSS_LMS_PrivateKeyInternal(HSS_LMS_Params(std::move(params)), std::move(hss_seed), std::move(identifier)));
 
   sk->set_idx(sig_idx);
   return sk;
}

References Botan::BufferSlicer::copy(), Botan::LMOTS_Params::create_or_throw(), Botan::LMS_Params::create_or_throw(), Botan::BufferSlicer::empty(), HSS_LMS_PrivateKeyInternal(), Botan::LMS_IDENTIFIER_LEN, Botan::load_be(), Botan::BufferSlicer::remaining(), and Botan::BufferSlicer::take().

Referenced by Botan::HSS_LMS_PrivateKey::HSS_LMS_PrivateKey().

hss_derive_root_lms_private_key()

LMS_PrivateKey Botan::HSS_LMS_PrivateKeyInternal::hss_derive_root_lms_private_key

(

)

const

Create the HSS root LMS tree's LMS_PrivateKey using the HSS-LMS private key.

We use the same generation as the reference implementation (https://github.com/cisco/hash-sigs) with SECRET_METHOD==2.

Returns

The LMS private key

Definition at line 310 of file hss.cpp.

                                                                                 {
   const auto& top_params = hss_params().params_at_level(HSS_Level(0));
   return LMS_PrivateKey(top_params.lms_params(), top_params.lmots_params(), m_identifier, m_hss_seed);
}

References hss_params(), and Botan::HSS_LMS_Params::params_at_level().

Referenced by Botan::HSS_LMS_PublicKeyInternal::create(), and sign().

hss_params()

const HSS_LMS_Params & Botan::HSS_LMS_PrivateKeyInternal::hss_params ( ) const

inline

Returns the used HSS-LMS parameters.

Definition at line 149 of file hss.h.

{ return m_hss_params; }

Referenced by Botan::HSS_LMS_PublicKeyInternal::create(), hss_derive_root_lms_private_key(), HSS_LMS_PrivateKeyInternal(), sign(), and to_bytes().

remaining_operations()

HSS_Sig_Idx Botan::HSS_LMS_PrivateKeyInternal::remaining_operations

(

)

const

Get the number of remaining signatures for this key.

Definition at line 235 of file hss.cpp.

                                                                   {
   return HSS_Sig_Idx(Stateful_Key_Index_Registry::global().remaining_operations(m_keyid));
}

References Botan::Stateful_Key_Index_Registry::global(), and remaining_operations().

Referenced by remaining_operations().

set_idx()

void Botan::HSS_LMS_PrivateKeyInternal::set_idx

(

HSS_Sig_Idx

idx

)

const

Set the idx of the next signature to generate.

Note that creating two signatures with the same index is insecure. The index must be lower than or equal to hss_params().max_sig_count(), with an index == max indicating the key is completely exhausted. The index will never go backward (highest value wins).

The signing state lives in the process-wide Stateful_Key_Index_Registry keyed by the key identity, not in this object, so this leaves *this unchanged and is therefore const.

Definition at line 239 of file hss.cpp.

                                                              {
   // An index equal to max_sig_count is valid and denotes an exhausted key
   if(idx > m_hss_params.max_sig_count()) {
      throw Decoding_Error("HSS-LMS private key index out of bounds");
   }
   Stateful_Key_Index_Registry::global().set_index_lower_bound(m_keyid, idx.get());
}

References Botan::detail::Strong_Base< T >::get(), Botan::Stateful_Key_Index_Registry::global(), and Botan::Stateful_Key_Index_Registry::set_index_lower_bound().

sign()

std::vector< uint8_t > Botan::HSS_LMS_PrivateKeyInternal::sign

(

std::span< const uint8_t >

msg

)

const

Create a HSS-LMS signature.

See RFC 8554 6.2 - Algorithm 8.

For each signature creation the hypertree is computed once again, so no data is stored between multiple signatures. However, storing data between multiple signatures could be an optimization if applications create multiple signatures in one go.

Parameters

msg	The message to sign.

Definition at line 263 of file hss.cpp.

                                                                                    {
   std::vector<uint8_t> sig(HSS_Signature::size(hss_params()));
   BufferStuffer sig_stuffer(sig);
   sig_stuffer.append(store_be(hss_params().L() - 1));
 
   std::vector<LMS_Tree_Node_Idx> q = derive_lms_leaf_indices_from_hss_index(reserve_next_idx(), hss_params());
 
   // Derive LMS private keys and compute buffers
   std::vector<LMS_PrivateKey> lms_key_at_layer;
   std::vector<StrongSpan<LMS_Signature_Bytes>> out_lms_sig_buffer_at_layer;
   std::vector<std::span<uint8_t>> out_child_pk_buffer_at_layer;
   for(HSS_Level layer(0); layer < hss_params().L(); ++layer) {
      // Generate key for current layer
      const HSS_LMS_Params::LMS_LMOTS_Params_Pair& layer_params = hss_params().params_at_level(layer);
      if(layer == HSS_Level(0)) {
         lms_key_at_layer.push_back(hss_derive_root_lms_private_key());
      } else {
         lms_key_at_layer.push_back(
            hss_derive_child_lms_private_key(layer_params, lms_key_at_layer.back(), q.at(layer.get() - 1)));
         out_child_pk_buffer_at_layer.push_back(sig_stuffer.next(LMS_PublicKey::size(layer_params.lms_params())));
      }
      out_lms_sig_buffer_at_layer.push_back(sig_stuffer.next<LMS_Signature_Bytes>(
         LMS_Signature::size(layer_params.lms_params(), layer_params.lmots_params())));
   }
   BOTAN_ASSERT_NOMSG(sig_stuffer.full());
 
   // Sign and write the signature from bottom layer to root layer
   std::vector<uint8_t> current_pk;
   for(int32_t layer_it = hss_params().L().get() - 1; layer_it >= 0; --layer_it) {
      HSS_Level layer(layer_it);
      if(layer == hss_params().L() - 1) {
         current_pk =
            lms_key_at_layer.at(layer.get())
               .sign_and_get_pk(out_lms_sig_buffer_at_layer.at(layer.get()), q.at(layer.get()), LMS_Message(msg))
               .to_bytes();
      } else {
         copy_mem(out_child_pk_buffer_at_layer.at(layer.get()), current_pk);
         current_pk =
            lms_key_at_layer.at(layer.get())
               .sign_and_get_pk(out_lms_sig_buffer_at_layer.at(layer.get()), q.at(layer.get()), LMS_Message(current_pk))
               .to_bytes();
      }
   }
 
   return sig;
}

References Botan::BufferStuffer::append(), BOTAN_ASSERT_NOMSG, Botan::copy_mem(), Botan::BufferStuffer::full(), Botan::detail::Strong_Base< T >::get(), hss_derive_root_lms_private_key(), hss_params(), Botan::HSS_LMS_Params::L(), Botan::HSS_LMS_Params::LMS_LMOTS_Params_Pair::lmots_params(), Botan::HSS_LMS_Params::LMS_LMOTS_Params_Pair::lms_params(), Botan::BufferStuffer::next(), Botan::HSS_LMS_Params::params_at_level(), Botan::HSS_Signature::size(), Botan::LMS_PublicKey::size(), Botan::LMS_Signature::size(), and Botan::store_be().

signature_size()

size_t Botan::HSS_LMS_PrivateKeyInternal::signature_size ( ) const

inline

Returns the size in bytes of a signature created by this key.

Definition at line 202 of file hss.h.

{ return m_sig_size; }

to_bytes()

secure_vector< uint8_t > Botan::HSS_LMS_PrivateKeyInternal::to_bytes

(

)

const

Returns the key in its encoded format.

Definition at line 214 of file hss.cpp.

                                                                  {
   secure_vector<uint8_t> sk_bytes(size());
   BufferStuffer stuffer(sk_bytes);
 
   const uint64_t current_index = Stateful_Key_Index_Registry::global().current_index(m_keyid);
 
   stuffer.append(store_be(hss_params().L()));
   stuffer.append(store_be(current_index));
 
   for(HSS_Level layer(1); layer <= hss_params().L(); ++layer) {
      const auto& params = hss_params().params_at_level(layer - 1);
      stuffer.append(store_be(params.lms_params().algorithm_type()));
      stuffer.append(store_be(params.lmots_params().algorithm_type()));
   }
   stuffer.append(m_hss_seed);
   stuffer.append(m_identifier);
   BOTAN_ASSERT_NOMSG(stuffer.full());
 
   return sk_bytes;
}

References Botan::BufferStuffer::append(), BOTAN_ASSERT_NOMSG, Botan::Stateful_Key_Index_Registry::current_index(), Botan::BufferStuffer::full(), Botan::Stateful_Key_Index_Registry::global(), hss_params(), Botan::HSS_LMS_Params::L(), Botan::HSS_LMS_Params::params_at_level(), and Botan::store_be().

---

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

• src/lib/pubkey/hss_lms/hss.h
• src/lib/pubkey/hss_lms/hss.cpp