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 (HSS_Sig_Idx idx) const
	Get the idx of the next signature to generate.
void	set_idx (HSS_Sig_Idx idx)
	Set the idx of the next signature to generate.
std::vector< uint8_t >	sign (std::span< const uint8_t > msg)
	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.
rng	The rng to use.

Definition at line 123 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)),
      // LMS doesn't have a single unique parameter code that we can easily use,
      // so algo_params is left as 0
      m_keyid("HSS-LMS", 0, 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 199 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 201 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 146 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 287 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

(

HSS_Sig_Idx

idx

)

const

Get the idx of the next signature to generate.

Definition at line 216 of file hss.cpp.

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

References Botan::detail::Strong_Base< T >::get(), 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

)

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 hss_params().max_sig_count(). The index will never go backward (highest value wins).

Definition at line 220 of file hss.cpp.

                                                        {
   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

)

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 240 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 197 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 195 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