Botan 3.14.1
Crypto and TLS for C&
Botan::HSS_LMS_PrivateKeyInternal Class Referencefinal

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_paramsThe HSS-LMS parameters for the key.
Random Number GeneratorsThe rng to use.

Definition at line 150 of file hss.cpp.

150 :
151 m_hss_params(hss_params),
152 m_hss_seed(rng.random_vec<LMS_Seed>(m_hss_params.params_at_level(HSS_Level(0)).lms_params().m())),
153 m_identifier(rng.random_vec<LMS_Identifier>(LMS_IDENTIFIER_LEN)),
154 m_keyid(
155 "HSS-LMS", hss_param_encoding(m_hss_params), m_hss_params.max_sig_count().get(), m_hss_seed, m_identifier),
156 m_sig_size(HSS_Signature::size(m_hss_params)) {}
const HSS_LMS_Params & hss_params() const
Returns the used HSS-LMS parameters.
Definition hss.h:149
static size_t size(const HSS_LMS_Params &params)
Returns the size a signature would have in its encoded format.
Definition hss.cpp:448
constexpr size_t LMS_IDENTIFIER_LEN
The length in bytes of the LMS identifier (I).
Definition lms.h:69
Strong< std::vector< uint8_t >, struct LMS_Identifier_ > LMS_Identifier
The identifier of an LMS tree (I in RFC 8554).
Definition lm_ots.h:54
Strong< secure_vector< uint8_t >, struct LMS_SEED_ > LMS_Seed
Seed of the LMS tree, used to generate the LM-OTS private keys.
Definition lm_ots.h:29
Strong< uint32_t, struct HSS_Level_, EnableArithmeticWithPlainNumber > HSS_Level
The HSS layer in the HSS multi tree starting at 0 from the root.
Definition hss.h:35

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.

204{ CT::poison(m_hss_seed); }
constexpr void poison(const T *p, size_t n)
Definition ct_utils.h:56

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.

206{ CT::unpoison(m_hss_seed); }
constexpr void unpoison(const T *p, size_t n)
Definition ct_utils.h:67

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_bytesThe private key bytes to parse.
Returns
The internal HSS-LMS private key.
Exceptions
Decoding_ErrorIf parsing the private key fails.

Definition at line 172 of file hss.cpp.

173 {
174 if(key_bytes.size() < sizeof(HSS_Level) + sizeof(HSS_Sig_Idx)) {
175 throw Decoding_Error("Too few private key bytes.");
176 }
177 BufferSlicer slicer(key_bytes);
178
179 const auto L = load_be<HSS_Level>(slicer.take<sizeof(HSS_Level)>());
180 if(L == 0U || L > HSS_MAX_LEVELS) {
181 throw Decoding_Error("Invalid number of HSS layers in private HSS-LMS key.");
182 }
183
184 const auto sig_idx = load_be<HSS_Sig_Idx>(slicer.take<sizeof(HSS_Sig_Idx)>());
185
186 std::vector<HSS_LMS_Params::LMS_LMOTS_Params_Pair> params;
187 for(size_t layer = 1; layer <= L; ++layer) {
188 if(slicer.remaining() < sizeof(LMS_Algorithm_Type) + sizeof(LMOTS_Algorithm_Type)) {
189 throw Decoding_Error("Out of bytes while parsing private HSS-LMS key.");
190 }
191 const auto lms_type = load_be<LMS_Algorithm_Type>(slicer.take<sizeof(LMS_Algorithm_Type)>());
192 const auto lmots_type = load_be<LMOTS_Algorithm_Type>(slicer.take<sizeof(LMOTS_Algorithm_Type)>());
193 params.push_back({LMS_Params::create_or_throw(lms_type), LMOTS_Params::create_or_throw(lmots_type)});
194 }
195 const auto& hash_name = params.at(0).lms_params().hash_name();
196
197 for(const auto& param : params) {
198 const bool invalid_lmots_hash = param.lmots_params().hash_name() != hash_name;
199 const bool invalid_lms_hash = param.lms_params().hash_name() != hash_name;
200 if(invalid_lmots_hash || invalid_lms_hash) {
201 throw Decoding_Error("Inconsistent hash functions are not allowed.");
202 }
203 }
204
205 if(slicer.remaining() < params.at(0).lms_params().m() + LMS_IDENTIFIER_LEN) {
206 throw Decoding_Error("Out of bytes while parsing private HSS-LMS key.");
207 }
208 auto hss_seed = slicer.copy<LMS_Seed>(params.at(0).lms_params().m());
209 auto identifier = slicer.copy<LMS_Identifier>(LMS_IDENTIFIER_LEN);
210
211 if(!slicer.empty()) {
212 throw Decoding_Error("Private HSS-LMS key contains more bytes than expected.");
213 }
214 auto sk = std::shared_ptr<HSS_LMS_PrivateKeyInternal>(
215 new HSS_LMS_PrivateKeyInternal(HSS_LMS_Params(std::move(params)), std::move(hss_seed), std::move(identifier)));
216
217 sk->set_idx(sig_idx);
218 return sk;
219}
HSS_LMS_PrivateKeyInternal(const HSS_LMS_Params &hss_params, RandomNumberGenerator &rng)
Create an internal HSS-LMS private key.
Definition hss.cpp:150
static LMOTS_Params create_or_throw(LMOTS_Algorithm_Type type)
Create the LM-OTS parameters from a known algorithm type.
Definition lm_ots.cpp:131
static LMS_Params create_or_throw(LMS_Algorithm_Type type)
Create the LMS parameters from a known algorithm type.
Definition lms.cpp:145
LMS_Algorithm_Type
Enum of available LMS algorithm types.
Definition lms.h:32
Strong< uint64_t, struct HSS_Sig_Idx_, EnableArithmeticWithPlainNumber > HSS_Sig_Idx
The index of a node within a specific LMS tree layer.
Definition hss.h:30
LMOTS_Algorithm_Type
Enum of available LM-OTS algorithm types.
Definition lm_ots.h:69
constexpr auto load_be(ParamTs &&... params)
Definition loadstor.h:504

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

317 {
318 const auto& top_params = hss_params().params_at_level(HSS_Level(0));
319 return LMS_PrivateKey(top_params.lms_params(), top_params.lmots_params(), m_identifier, m_hss_seed);
320}
const LMS_LMOTS_Params_Pair & params_at_level(HSS_Level level) const
Returns the LMS an LM-OTS parameters at the specified level of the HSS tree.
Definition hss.h:99

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.

149{ 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 242 of file hss.cpp.

242 {
244}
HSS_Sig_Idx remaining_operations() const
Get the number of remaining signatures for this key.
Definition hss.cpp:242
static Stateful_Key_Index_Registry & global()

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

246 {
247 // An index equal to max_sig_count is valid and denotes an exhausted key
248 if(idx > m_hss_params.max_sig_count()) {
249 throw Decoding_Error("HSS-LMS private key index out of bounds");
250 }
252}
void set_index_lower_bound(const KeyId &key_id, uint64_t min)

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
msgThe message to sign.

Definition at line 270 of file hss.cpp.

270 {
271 std::vector<uint8_t> sig(HSS_Signature::size(hss_params()));
272 BufferStuffer sig_stuffer(sig);
273 sig_stuffer.append(store_be(hss_params().L() - 1));
274
275 std::vector<LMS_Tree_Node_Idx> q = derive_lms_leaf_indices_from_hss_index(reserve_next_idx(), hss_params());
276
277 // Derive LMS private keys and compute buffers
278 std::vector<LMS_PrivateKey> lms_key_at_layer;
279 std::vector<StrongSpan<LMS_Signature_Bytes>> out_lms_sig_buffer_at_layer;
280 std::vector<std::span<uint8_t>> out_child_pk_buffer_at_layer;
281 for(HSS_Level layer(0); layer < hss_params().L(); ++layer) {
282 // Generate key for current layer
283 const HSS_LMS_Params::LMS_LMOTS_Params_Pair& layer_params = hss_params().params_at_level(layer);
284 if(layer == HSS_Level(0)) {
285 lms_key_at_layer.push_back(hss_derive_root_lms_private_key());
286 } else {
287 lms_key_at_layer.push_back(
288 hss_derive_child_lms_private_key(layer_params, lms_key_at_layer.back(), q.at(layer.get() - 1)));
289 out_child_pk_buffer_at_layer.push_back(sig_stuffer.next(LMS_PublicKey::size(layer_params.lms_params())));
290 }
291 out_lms_sig_buffer_at_layer.push_back(sig_stuffer.next<LMS_Signature_Bytes>(
292 LMS_Signature::size(layer_params.lms_params(), layer_params.lmots_params())));
293 }
294 BOTAN_ASSERT_NOMSG(sig_stuffer.full());
295
296 // Sign and write the signature from bottom layer to root layer
297 std::vector<uint8_t> current_pk;
298 for(int32_t layer_it = hss_params().L().get() - 1; layer_it >= 0; --layer_it) {
299 HSS_Level layer(layer_it);
300 if(layer == hss_params().L() - 1) {
301 current_pk =
302 lms_key_at_layer.at(layer.get())
303 .sign_and_get_pk(out_lms_sig_buffer_at_layer.at(layer.get()), q.at(layer.get()), LMS_Message(msg))
304 .to_bytes();
305 } else {
306 copy_mem(out_child_pk_buffer_at_layer.at(layer.get()), current_pk);
307 current_pk =
308 lms_key_at_layer.at(layer.get())
309 .sign_and_get_pk(out_lms_sig_buffer_at_layer.at(layer.get()), q.at(layer.get()), LMS_Message(current_pk))
310 .to_bytes();
311 }
312 }
313
314 return sig;
315}
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:82
HSS_Level L() const
Returns the number of layers the HSS tree has.
Definition hss.h:104
LMS_PrivateKey hss_derive_root_lms_private_key() const
Create the HSS root LMS tree's LMS_PrivateKey using the HSS-LMS private key.
Definition hss.cpp:317
static size_t size(const LMS_Params &lms_params)
The expected size of an LMS public key for given lms_params.
Definition lms.cpp:346
static size_t size(const LMS_Params &lms_params, const LMOTS_Params &lmots_params)
Definition lms.cpp:453
Strong< std::vector< uint8_t >, struct LMS_Signature_Bytes_ > LMS_Signature_Bytes
Raw bytes of an LMS signature.
Definition lms.h:84
constexpr void copy_mem(T *out, const T *in, size_t n)
Definition mem_ops.h:144
Strong< std::vector< uint8_t >, struct LMS_Message_ > LMS_Message
A message that is signed with an LMS tree.
Definition lm_ots.h:59
constexpr auto store_be(ParamTs &&... params)
Definition loadstor.h:745

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.

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

221 {
222 secure_vector<uint8_t> sk_bytes(size());
223 BufferStuffer stuffer(sk_bytes);
224
225 const uint64_t current_index = Stateful_Key_Index_Registry::global().current_index(m_keyid);
226
227 stuffer.append(store_be(hss_params().L()));
228 stuffer.append(store_be(current_index));
229
230 for(HSS_Level layer(1); layer <= hss_params().L(); ++layer) {
231 const auto& params = hss_params().params_at_level(layer - 1);
232 stuffer.append(store_be(params.lms_params().algorithm_type()));
233 stuffer.append(store_be(params.lmots_params().algorithm_type()));
234 }
235 stuffer.append(m_hss_seed);
236 stuffer.append(m_identifier);
237 BOTAN_ASSERT_NOMSG(stuffer.full());
238
239 return sk_bytes;
240}
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128

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: