Botan::XMSS_Parameters Class Reference

#include <xmss_parameters.h>

Public Types
enum	xmss_algorithm_t {   XMSS_SHA2_10_256 = 0x00000001 , XMSS_SHA2_16_256 = 0x00000002 , XMSS_SHA2_20_256 = 0x00000003 , XMSS_SHA2_10_512 = 0x00000004 ,   XMSS_SHA2_16_512 = 0x00000005 , XMSS_SHA2_20_512 = 0x00000006 , XMSS_SHAKE_10_256 = 0x00000007 , XMSS_SHAKE_16_256 = 0x00000008 ,   XMSS_SHAKE_20_256 = 0x00000009 , XMSS_SHAKE_10_512 = 0x0000000a , XMSS_SHAKE_16_512 = 0x0000000b , XMSS_SHAKE_20_512 = 0x0000000c ,   XMSS_SHA2_10_192 = 0x0000000d , XMSS_SHA2_16_192 = 0x0000000e , XMSS_SHA2_20_192 = 0x0000000f , XMSS_SHAKE256_10_256 = 0x00000010 ,   XMSS_SHAKE256_16_256 = 0x00000011 , XMSS_SHAKE256_20_256 = 0x00000012 , XMSS_SHAKE256_10_192 = 0x00000013 , XMSS_SHAKE256_16_192 = 0x00000014 ,   XMSS_SHAKE256_20_192 = 0x00000015 }

Public Member Functions
size_t	element_size () const
size_t	estimated_strength () const
const std::string	hash_function_name () const
size_t	hash_id_size () const
size_t	len () const
const std::string	name () const
xmss_algorithm_t	oid () const
bool	operator== (const XMSS_Parameters &p) const
XMSS_WOTS_Parameters::ots_algorithm_t	ots_oid () const
size_t	raw_legacy_private_key_size () const
size_t	raw_private_key_size () const
size_t	raw_public_key_size () const
size_t	total_number_of_signatures () const
size_t	tree_height () const
size_t	wots_parameter () const
	XMSS_Parameters (std::string_view algo_name)
	XMSS_Parameters (xmss_algorithm_t oid)

Static Public Member Functions
static xmss_algorithm_t	xmss_id_from_string (std::string_view algo_name)

Detailed Description

Descibes a signature method for XMSS, as defined in: [1] XMSS: Extended Hash-Based Signatures, Request for Comments: 8391 Release: May 2018. https://datatracker.ietf.org/doc/rfc8391/ [2] Recommendation for Stateful Hash-Based Signature Schemes NIST Special Publication 800-208 Release: October 2020. https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-208.pdf

Definition at line 137 of file xmss_parameters.h.

Member Enumeration Documentation

xmss_algorithm_t

enum Botan::XMSS_Parameters::xmss_algorithm_t

Enumerator
XMSS_SHA2_10_256
XMSS_SHA2_16_256
XMSS_SHA2_20_256
XMSS_SHA2_10_512
XMSS_SHA2_16_512
XMSS_SHA2_20_512
XMSS_SHAKE_10_256
XMSS_SHAKE_16_256
XMSS_SHAKE_20_256
XMSS_SHAKE_10_512
XMSS_SHAKE_16_512
XMSS_SHAKE_20_512
XMSS_SHA2_10_192
XMSS_SHA2_16_192
XMSS_SHA2_20_192
XMSS_SHAKE256_10_256
XMSS_SHAKE256_16_256
XMSS_SHAKE256_20_256
XMSS_SHAKE256_10_192
XMSS_SHAKE256_16_192
XMSS_SHAKE256_20_192

Definition at line 140 of file xmss_parameters.h.

         {
         // from RFC 8391
         XMSS_SHA2_10_256 = 0x00000001,
         XMSS_SHA2_16_256 = 0x00000002,
         XMSS_SHA2_20_256 = 0x00000003,
 
         // from RFC 8391 but not approved by NIST SP.800-208
         // (see footnote on page 16)
         XMSS_SHA2_10_512 = 0x00000004,
         XMSS_SHA2_16_512 = 0x00000005,
         XMSS_SHA2_20_512 = 0x00000006,
         XMSS_SHAKE_10_256 = 0x00000007,
         XMSS_SHAKE_16_256 = 0x00000008,
         XMSS_SHAKE_20_256 = 0x00000009,
         XMSS_SHAKE_10_512 = 0x0000000a,
         XMSS_SHAKE_16_512 = 0x0000000b,
         XMSS_SHAKE_20_512 = 0x0000000c,
 
         // from NIST SP.800-208
         XMSS_SHA2_10_192 = 0x0000000d,
         XMSS_SHA2_16_192 = 0x0000000e,
         XMSS_SHA2_20_192 = 0x0000000f,
         XMSS_SHAKE256_10_256 = 0x00000010,
         XMSS_SHAKE256_16_256 = 0x00000011,
         XMSS_SHAKE256_20_256 = 0x00000012,
         XMSS_SHAKE256_10_192 = 0x00000013,
         XMSS_SHAKE256_16_192 = 0x00000014,
         XMSS_SHAKE256_20_192 = 0x00000015,
         };

Constructor & Destructor Documentation

XMSS_Parameters() [1/2]

Botan::XMSS_Parameters::XMSS_Parameters ( std::string_view  algo_name )

explicit

Definition at line 68 of file xmss_parameters.cpp.

   : XMSS_Parameters(XMSS_Parameters::xmss_id_from_string(param_set))
   {
   }

XMSS_Parameters() [2/2]

Botan::XMSS_Parameters::XMSS_Parameters ( xmss_algorithm_t  oid )

explicit

Definition at line 73 of file xmss_parameters.cpp.

   : m_oid(oid)
   {
   switch(oid)
      {
      case XMSS_SHA2_10_256:
         m_element_size = 32;
         m_hash_id_size = 32;
         m_w = 16;
         m_len = 67;
         m_tree_height = 10;
         m_name = "XMSS-SHA2_10_256";
         m_hash_name = "SHA-256";
         m_strength = 256;
         m_wots_oid = XMSS_WOTS_Parameters::ots_algorithm_t::WOTSP_SHA2_256;
         break;
      case XMSS_SHA2_16_256:
         m_element_size = 32;
         m_hash_id_size = 32;
         m_w = 16;
         m_len = 67;
         m_tree_height = 16;
         m_name = "XMSS-SHA2_16_256";
         m_hash_name = "SHA-256";
         m_strength = 256;
         m_wots_oid = XMSS_WOTS_Parameters::ots_algorithm_t::WOTSP_SHA2_256;
         break;
      case XMSS_SHA2_20_256:
         m_element_size = 32;
         m_hash_id_size = 32;
         m_w = 16;
         m_len = 67;
         m_tree_height = 20;
         m_name = "XMSS-SHA2_20_256";
         m_hash_name = "SHA-256";
         m_strength = 256;
         m_wots_oid = XMSS_WOTS_Parameters::ots_algorithm_t::WOTSP_SHA2_256;
         break;
      case XMSS_SHA2_10_512:
         m_element_size = 64;
         m_hash_id_size = 64;
         m_w = 16;
         m_len = 131;
         m_tree_height = 10;
         m_name = "XMSS-SHA2_10_512";
         m_hash_name = "SHA-512";
         m_strength = 512;
         m_wots_oid = XMSS_WOTS_Parameters::ots_algorithm_t::WOTSP_SHA2_512;
         break;
      case XMSS_SHA2_16_512:
         m_element_size = 64;
         m_hash_id_size = 64;
         m_w = 16;
         m_len = 131;
         m_tree_height = 16;
         m_name = "XMSS-SHA2_16_512";
         m_hash_name = "SHA-512";
         m_strength = 512;
         m_wots_oid = XMSS_WOTS_Parameters::ots_algorithm_t::WOTSP_SHA2_512;
         break;
      case XMSS_SHA2_20_512:
         m_element_size = 64;
         m_hash_id_size = 64;
         m_w = 16;
         m_len = 131;
         m_tree_height = 20;
         m_name = "XMSS-SHA2_20_512";
         m_hash_name = "SHA-512";
         m_strength = 512;
         m_wots_oid = XMSS_WOTS_Parameters::ots_algorithm_t::WOTSP_SHA2_512;
         break;
      case XMSS_SHAKE_10_256:
         m_element_size = 32;
         m_hash_id_size = 32;
         m_w = 16;
         m_len = 67;
         m_tree_height = 10;
         m_name = "XMSS-SHAKE_10_256";
         m_hash_name = "SHAKE-128(256)";
         m_strength = 256;
         m_wots_oid = XMSS_WOTS_Parameters::ots_algorithm_t::WOTSP_SHAKE_256;
         break;
      case XMSS_SHAKE_16_256:
         m_element_size = 32;
         m_hash_id_size = 32;
         m_w = 16;
         m_len = 67;
         m_tree_height = 16;
         m_name = "XMSS-SHAKE_16_256";
         m_hash_name = "SHAKE-128(256)";
         m_strength = 256;
         m_wots_oid = XMSS_WOTS_Parameters::ots_algorithm_t::WOTSP_SHAKE_256;
         break;
      case XMSS_SHAKE_20_256:
         m_element_size = 32;
         m_hash_id_size = 32;
         m_w = 16;
         m_len = 67;
         m_tree_height = 20;
         m_name = "XMSS-SHAKE_20_256";
         m_hash_name = "SHAKE-128(256)";
         m_strength = 256;
         m_wots_oid = XMSS_WOTS_Parameters::ots_algorithm_t::WOTSP_SHAKE_256;
         break;
      case XMSS_SHAKE_10_512:
         m_element_size = 64;
         m_hash_id_size = 64;
         m_w = 16;
         m_len = 131;
         m_tree_height = 10;
         m_name = "XMSS-SHAKE_10_512";
         m_hash_name = "SHAKE-256(512)";
         m_strength = 512;
         m_wots_oid = XMSS_WOTS_Parameters::ots_algorithm_t::WOTSP_SHAKE_512;
         break;
      case XMSS_SHAKE_16_512:
         m_element_size = 64;
         m_hash_id_size = 64;
         m_w = 16;
         m_len = 131;
         m_tree_height = 16;
         m_name = "XMSS-SHAKE_16_512";
         m_hash_name = "SHAKE-256(512)";
         m_strength = 512;
         m_wots_oid = XMSS_WOTS_Parameters::ots_algorithm_t::WOTSP_SHAKE_512;
         break;
      case XMSS_SHAKE_20_512:
         m_element_size = 64;
         m_hash_id_size = 64;
         m_w = 16;
         m_len = 131;
         m_tree_height = 20;
         m_name = "XMSS-SHAKE_20_512";
         m_hash_name = "SHAKE-256(512)";
         m_strength = 512;
         m_wots_oid = XMSS_WOTS_Parameters::ots_algorithm_t::WOTSP_SHAKE_512;
         break;
      case XMSS_SHA2_10_192:
         m_element_size = 24;
         m_hash_id_size = 4;
         m_w = 16;
         m_len = 51;
         m_tree_height = 10;
         m_name = "XMSS-SHA2_10_192";
         m_hash_name = "Truncated(SHA-256,192)";
         m_strength = 192;
         m_wots_oid = XMSS_WOTS_Parameters::ots_algorithm_t::WOTSP_SHA2_192;
         break;
      case XMSS_SHA2_16_192:
         m_element_size = 24;
         m_hash_id_size = 4;
         m_w = 16;
         m_len = 51;
         m_tree_height = 16;
         m_name = "XMSS-SHA2_16_192";
         m_hash_name = "Truncated(SHA-256,192)";
         m_strength = 192;
         m_wots_oid = XMSS_WOTS_Parameters::ots_algorithm_t::WOTSP_SHA2_192;
         break;
      case XMSS_SHA2_20_192:
         m_element_size = 24;
         m_hash_id_size = 4;
         m_w = 16;
         m_len = 51;
         m_tree_height = 20;
         m_name = "XMSS-SHA2_20_192";
         m_hash_name = "Truncated(SHA-256,192)";
         m_strength = 192;
         m_wots_oid = XMSS_WOTS_Parameters::ots_algorithm_t::WOTSP_SHA2_192;
         break;
      case XMSS_SHAKE256_10_256:
         m_element_size = 32;
         m_hash_id_size = 32;
         m_w = 16;
         m_len = 67;
         m_tree_height = 10;
         m_name = "XMSS-SHAKE256_10_256";
         m_hash_name = "SHAKE-256(256)";
         m_strength = 256;
         m_wots_oid = XMSS_WOTS_Parameters::ots_algorithm_t::WOTSP_SHAKE_256_256;
         break;
      case XMSS_SHAKE256_16_256:
         m_element_size = 32;
         m_hash_id_size = 32;
         m_w = 16;
         m_len = 67;
         m_tree_height = 16;
         m_name = "XMSS-SHAKE256_16_256";
         m_hash_name = "SHAKE-256(256)";
         m_strength = 256;
         m_wots_oid = XMSS_WOTS_Parameters::ots_algorithm_t::WOTSP_SHAKE_256_256;
         break;
      case XMSS_SHAKE256_20_256:
         m_element_size = 32;
         m_hash_id_size = 32;
         m_w = 16;
         m_len = 67;
         m_tree_height = 20;
         m_name = "XMSS-SHAKE256_20_256";
         m_hash_name = "SHAKE-256(256)";
         m_strength = 256;
         m_wots_oid = XMSS_WOTS_Parameters::ots_algorithm_t::WOTSP_SHAKE_256_256;
         break;
      case XMSS_SHAKE256_10_192:
         m_element_size = 24;
         m_hash_id_size = 4;
         m_w = 16;
         m_len = 51;
         m_tree_height = 10;
         m_name = "XMSS-SHAKE256_10_192";
         m_hash_name = "SHAKE-256(192)";
         m_strength = 192;
         m_wots_oid = XMSS_WOTS_Parameters::ots_algorithm_t::WOTSP_SHAKE_256_192;
         break;
      case XMSS_SHAKE256_16_192:
         m_element_size = 24;
         m_hash_id_size = 4;
         m_w = 16;
         m_len = 51;
         m_tree_height = 16;
         m_name = "XMSS-SHAKE256_16_192";
         m_hash_name = "SHAKE-256(192)";
         m_strength = 192;
         m_wots_oid = XMSS_WOTS_Parameters::ots_algorithm_t::WOTSP_SHAKE_256_192;
         break;
      case XMSS_SHAKE256_20_192:
         m_element_size = 24;
         m_hash_id_size = 4;
         m_w = 16;
         m_len = 51;
         m_tree_height = 20;
         m_name = "XMSS-SHAKE256_20_192";
         m_hash_name = "SHAKE-256(192)";
         m_strength = 192;
         m_wots_oid = XMSS_WOTS_Parameters::ots_algorithm_t::WOTSP_SHAKE_256_192;
         break;
 
      default:
         throw Not_Implemented("Algorithm id does not match any known XMSS algorithm id:" + std::to_string(oid));
      }
   }

References oid(), Botan::XMSS_WOTS_Parameters::WOTSP_SHA2_192, Botan::XMSS_WOTS_Parameters::WOTSP_SHA2_256, Botan::XMSS_WOTS_Parameters::WOTSP_SHA2_512, Botan::XMSS_WOTS_Parameters::WOTSP_SHAKE_256, Botan::XMSS_WOTS_Parameters::WOTSP_SHAKE_256_192, Botan::XMSS_WOTS_Parameters::WOTSP_SHAKE_256_256, Botan::XMSS_WOTS_Parameters::WOTSP_SHAKE_512, XMSS_SHA2_10_192, XMSS_SHA2_10_256, XMSS_SHA2_10_512, XMSS_SHA2_16_192, XMSS_SHA2_16_256, XMSS_SHA2_16_512, XMSS_SHA2_20_192, XMSS_SHA2_20_256, XMSS_SHA2_20_512, XMSS_SHAKE256_10_192, XMSS_SHAKE256_10_256, XMSS_SHAKE256_16_192, XMSS_SHAKE256_16_256, XMSS_SHAKE256_20_192, XMSS_SHAKE256_20_256, XMSS_SHAKE_10_256, XMSS_SHAKE_10_512, XMSS_SHAKE_16_256, XMSS_SHAKE_16_512, XMSS_SHAKE_20_256, and XMSS_SHAKE_20_512.

Member Function Documentation

element_size()

size_t Botan::XMSS_Parameters::element_size ( ) const

inline

Retrieves the uniform length of a message, and the size of each node. This correlates to XMSS parameter "n" defined in [1].

Returns

element length in bytes.

Definition at line 196 of file xmss_parameters.h.

{ return m_element_size; }

Referenced by Botan::XMSS_Common_Ops::randomize_tree_hash(), Botan::XMSS_Signature_Operation::signature_length(), Botan::XMSS_PrivateKey::XMSS_PrivateKey(), Botan::XMSS_PublicKey::XMSS_PublicKey(), and Botan::XMSS_Signature::XMSS_Signature().

estimated_strength()

size_t Botan::XMSS_Parameters::estimated_strength ( ) const

inline

Returns the estimated pre-quantum security level of the chosen algorithm.

Definition at line 239 of file xmss_parameters.h.

         {
         return m_strength;
         }

hash_function_name()

const std::string Botan::XMSS_Parameters::hash_function_name ( ) const

inline

Definition at line 184 of file xmss_parameters.h.

         {
         return m_hash_name;
         }

Referenced by Botan::XMSS_Hash::XMSS_Hash().

hash_id_size()

size_t Botan::XMSS_Parameters::hash_id_size ( ) const

inline

Retrieves the length of the hash identifier (domain separator) in bytes. See definition of toByte() in RFC 8391 Section 2.4 and the concrete definitions of hash functions in Section 5.1 where this parameter is always equal to the output length of the underlying hash primitive. Also see NIST SP.800-208 where instantiations utilizing truncated hashes use shorter hash IDs.

Definition at line 206 of file xmss_parameters.h.

{ return m_hash_id_size; }

len()

size_t Botan::XMSS_Parameters::len ( ) const

inline

Definition at line 226 of file xmss_parameters.h.

{ return m_len; }

Referenced by Botan::XMSS_Common_Ops::create_l_tree(), and Botan::XMSS_Signature::XMSS_Signature().

name()

const std::string Botan::XMSS_Parameters::name ( ) const

inline

Returns

XMSS registry name for the chosen parameter set.

Definition at line 179 of file xmss_parameters.h.

         {
         return m_name;
         }

oid()

xmss_algorithm_t Botan::XMSS_Parameters::oid ( ) const

inline

Definition at line 228 of file xmss_parameters.h.

{ return m_oid; }

Referenced by Botan::create_private_key(), Botan::XMSS_Verification_Operation::is_valid_signature(), Botan::XMSS_PublicKey::raw_public_key(), and XMSS_Parameters().

operator==()

bool Botan::XMSS_Parameters::operator== ( const XMSS_Parameters &  p ) const

inline

Definition at line 262 of file xmss_parameters.h.

         {
         return m_oid == p.m_oid;
         }

ots_oid()

XMSS_WOTS_Parameters::ots_algorithm_t Botan::XMSS_Parameters::ots_oid ( ) const

inline

Definition at line 230 of file xmss_parameters.h.

         {
         return m_wots_oid;
         }

raw_legacy_private_key_size()

size_t Botan::XMSS_Parameters::raw_legacy_private_key_size ( ) const

inline

Definition at line 249 of file xmss_parameters.h.

         {
         return raw_public_key_size() +
                sizeof(uint32_t) +
                2 * element_size();
         }

raw_private_key_size()

size_t Botan::XMSS_Parameters::raw_private_key_size ( ) const

inline

Definition at line 256 of file xmss_parameters.h.

         {
         return raw_legacy_private_key_size()
                + 1 /* identifier for WOTS+ key derivation method */;
         }

raw_public_key_size()

size_t Botan::XMSS_Parameters::raw_public_key_size ( ) const

inline

Definition at line 244 of file xmss_parameters.h.

         {
         return sizeof(uint32_t) + 2 * element_size();
         }

Referenced by Botan::XMSS_PublicKey::XMSS_PublicKey().

total_number_of_signatures()

size_t Botan::XMSS_Parameters::total_number_of_signatures ( ) const

inline

Returns

total number of signatures allowed for this XMSS instance

Definition at line 216 of file xmss_parameters.h.

{ return size_t(1) << tree_height(); }

Referenced by Botan::XMSS_Signature::XMSS_Signature().

tree_height()

size_t Botan::XMSS_Parameters::tree_height ( ) const

inline

Returns

The height (number of levels - 1) of the tree

Definition at line 211 of file xmss_parameters.h.

{ return m_tree_height; }

Referenced by Botan::XMSS_Signature::XMSS_Signature().

wots_parameter()

size_t Botan::XMSS_Parameters::wots_parameter ( ) const

inline

The Winternitz parameter.

Returns

numeric base used for internal representation of data.

Definition at line 224 of file xmss_parameters.h.

{ return m_w; }

xmss_id_from_string()

XMSS_Parameters::xmss_algorithm_t Botan::XMSS_Parameters::xmss_id_from_string ( std::string_view  algo_name )

static

Definition at line 20 of file xmss_parameters.cpp.

   {
   if(param_set == "XMSS-SHA2_10_256")
      { return XMSS_SHA2_10_256; }
   if(param_set == "XMSS-SHA2_16_256")
      { return XMSS_SHA2_16_256; }
   if(param_set == "XMSS-SHA2_20_256")
      { return XMSS_SHA2_20_256; }
   if(param_set == "XMSS-SHA2_10_512")
      { return XMSS_SHA2_10_512; }
   if(param_set == "XMSS-SHA2_16_512")
      { return XMSS_SHA2_16_512; }
   if(param_set == "XMSS-SHA2_20_512")
      { return XMSS_SHA2_20_512; }
   if(param_set == "XMSS-SHAKE_10_256")
      { return XMSS_SHAKE_10_256; }
   if(param_set == "XMSS-SHAKE_16_256")
      { return XMSS_SHAKE_16_256; }
   if(param_set == "XMSS-SHAKE_20_256")
      { return XMSS_SHAKE_20_256; }
   if(param_set == "XMSS-SHAKE_10_512")
      { return XMSS_SHAKE_10_512; }
   if(param_set == "XMSS-SHAKE_16_512")
      { return XMSS_SHAKE_16_512; }
   if(param_set == "XMSS-SHAKE_20_512")
      { return XMSS_SHAKE_20_512; }
   if(param_set == "XMSS-SHA2_10_192")
      { return XMSS_SHA2_10_192; }
   if(param_set == "XMSS-SHA2_16_192")
      { return XMSS_SHA2_16_192; }
   if(param_set == "XMSS-SHA2_20_192")
      { return XMSS_SHA2_20_192; }
   if(param_set == "XMSS-SHAKE256_10_256")
      { return XMSS_SHAKE256_10_256; }
   if(param_set == "XMSS-SHAKE256_16_256")
      { return XMSS_SHAKE256_16_256; }
   if(param_set == "XMSS-SHAKE256_20_256")
      { return XMSS_SHAKE256_20_256; }
   if(param_set == "XMSS-SHAKE256_10_192")
      { return XMSS_SHAKE256_10_192; }
   if(param_set == "XMSS-SHAKE256_16_192")
      { return XMSS_SHAKE256_16_192; }
   if(param_set == "XMSS-SHAKE256_20_192")
      { return XMSS_SHAKE256_20_192; }
 
   throw Lookup_Error(fmt("Unknown XMSS algorithm param '{}'", param_set));
   }

References Botan::fmt(), XMSS_SHA2_10_192, XMSS_SHA2_10_256, XMSS_SHA2_10_512, XMSS_SHA2_16_192, XMSS_SHA2_16_256, XMSS_SHA2_16_512, XMSS_SHA2_20_192, XMSS_SHA2_20_256, XMSS_SHA2_20_512, XMSS_SHAKE256_10_192, XMSS_SHAKE256_10_256, XMSS_SHAKE256_16_192, XMSS_SHAKE256_16_256, XMSS_SHAKE256_20_192, XMSS_SHAKE256_20_256, XMSS_SHAKE_10_256, XMSS_SHAKE_10_512, XMSS_SHAKE_16_256, XMSS_SHAKE_16_512, XMSS_SHAKE_20_256, and XMSS_SHAKE_20_512.

---

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

• src/lib/pubkey/xmss/xmss_parameters.h
• src/lib/pubkey/xmss/xmss_parameters.cpp