Botan::HSS_LMS_PrivateKeyInternal Class Reference

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

#include <hss.h>

Public Member Functions
HSS_Sig_Idx	get_idx () const
	Get the idx of the next signature to generate.
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.
void	set_idx (HSS_Sig_Idx idx)
	Set the idx of the next signature to generate.
secure_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 125 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 114 of file hss.cpp.

                                                                                                                   :
      m_hss_params(hss_params), m_current_idx(0), m_sig_size(HSS_Signature::size(m_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);
}

References Botan::LMS_IDENTIFIER_LEN, Botan::HSS_LMS_Params::LMS_LMOTS_Params_Pair::lms_params(), Botan::LMS_Params::m(), Botan::HSS_LMS_Params::params_at_level(), and Botan::RandomNumberGenerator::random_vec().

Referenced by from_bytes_or_throw().

Member Function Documentation

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 120 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)});
   }
   std::string hash_name = params.at(0).lms_params().hash_name();
   if(std::any_of(params.begin(), params.end(), [&hash_name](HSS_LMS_Params::LMS_LMOTS_Params_Pair& lms_lmots_params) {
         bool invalid_lmots_hash = lms_lmots_params.lmots_params().hash_name() != hash_name;
         bool invalid_lms_hash = lms_lmots_params.lms_params().hash_name() != hash_name;
         return 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().

get_idx()

HSS_Sig_Idx Botan::HSS_LMS_PrivateKeyInternal::get_idx ( ) const

inline

Get the idx of the next signature to generate.

Definition at line 157 of file hss.h.

{ return m_current_idx; }

Referenced by to_bytes().

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 268 of file hss.cpp.

                                                                                 {
   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 147 of file hss.h.

{ return m_hss_params; }

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

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().

Definition at line 187 of file hss.cpp.

                                                        {
   m_current_idx = idx;
}

sign()

secure_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 221 of file hss.cpp.

                                                                                  {
   secure_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 194 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 168 of file hss.cpp.

                                                                  {
   secure_vector<uint8_t> sk_bytes(size());
   BufferStuffer stuffer(sk_bytes);
 
   stuffer.append(store_be(hss_params().L()));
   stuffer.append(store_be(get_idx()));
 
   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::BufferStuffer::full(), get_idx(), 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