From cfbbd43378d54078955bbb1bc68b6ea31b144f8f Mon Sep 17 00:00:00 2001 From: Matt Borland Date: Thu, 6 Feb 2025 11:24:56 -0500 Subject: [PATCH 1/4] Update hash drbg docs --- doc/crypt.adoc | 4 +- doc/crypt/hash_drbg.adoc | 121 +++++++++++++++++---------------------- 2 files changed, 54 insertions(+), 71 deletions(-) diff --git a/doc/crypt.adoc b/doc/crypt.adoc index f7ab0e27..ed141dda 100644 --- a/doc/crypt.adoc +++ b/doc/crypt.adoc @@ -50,9 +50,9 @@ include::crypt/shake128.adoc[] include::crypt/shake256.adoc[] include::crypt/hmac.adoc[] -//// -include::crypt/hash_drbg.adoc[] +include::crypt/hash_drbg.adoc[] +//// include::crypt/hmac_drbg.adoc[] //// include::crypt/concepts.adoc[] diff --git a/doc/crypt/hash_drbg.adoc b/doc/crypt/hash_drbg.adoc index 0833b70a..00b087a2 100644 --- a/doc/crypt/hash_drbg.adoc +++ b/doc/crypt/hash_drbg.adoc @@ -48,7 +48,7 @@ using sha1_hash_drbg_t = hash_drbg; BOOST_CRYPT_EXPORT using sha1_hash_drbg_pr = drbg::sha1_hash_drbg_t; -// So on for each hasher available with te correct presets +// So on for each hasher available with the correct presets namespace drbg { @@ -66,79 +66,60 @@ namespace drbg { // 256: SHA-256, SHA-512/256 // 384: SHA-384 // 512: SHA-512 -template +template class hash_drbg { public: - BOOST_CRYPT_GPU_ENABLED constexpr hash_drbg() noexcept = default; - - #ifdef BOOST_CRYPT_HAS_CXX20_CONSTEXPR - BOOST_CRYPT_GPU_ENABLED constexpr ~hash_drbg() noexcept - { - destroy(); - } - #endif - - template - BOOST_CRYPT_GPU_ENABLED constexpr auto init(ForwardIter1 entropy, boost::crypt::size_t entropy_size, ForwardIter2 nonce = nullptr, boost::crypt::size_t nonce_size = 0U, ForwardIter3 personalization = nullptr, boost::crypt::size_t personalization_size = 0U) noexcept -> state; - - template - BOOST_CRYPT_GPU_ENABLED constexpr auto init(const Container1& entropy) noexcept -> state; - - template - BOOST_CRYPT_GPU_ENABLED constexpr auto init(const Container1& entropy, const Container2& nonce) noexcept -> state; - - template - BOOST_CRYPT_GPU_ENABLED constexpr auto init(const Container1& entropy, const Container2& nonce, const Container3& personalization) noexcept -> state; - - #ifdef BOOST_CRYPT_HAS_STRING_VIEW - constexpr auto init(std::string_view entropy) noexcept -> state; - - constexpr auto init(std::string_view entropy, std::string_view nonce) noexcept -> state; - - constexpr auto init(std::string_view entropy, std::string_view nonce, std::string_view personalization) noexcept -> state; - #endif - - #ifdef BOOST_CRYPT_HAS_SPAN - template - constexpr auto init(std::span entropy) noexcept -> state; - - template - constexpr auto init(std::span entropy, std::span nonce) noexcept -> state; - - template - constexpr auto init(std::span entropy, std::span nonce, std::span personalization) noexcept -> state; - #endif - - template - BOOST_CRYPT_GPU_ENABLED constexpr auto reseed(ForwardIter1 entropy, boost::crypt::size_t entropy_size, - ForwardIter2 additional_input = nullptr, boost::crypt::size_t additional_input_size = 0U) noexcept -> state; - - template - BOOST_CRYPT_GPU_ENABLED constexpr auto reseed(const Container1& entropy) noexcept -> state; - - template - BOOST_CRYPT_GPU_ENABLED constexpr auto reseed(const Container1& entropy, const Container2& additional_input) noexcept -> state; - - #ifdef BOOST_CRYPT_HAS_STRING_VIEW - constexpr auto reseed(const std::string_view entropy) noexcept -> state; - - constexpr auto reseed(const std::string_view entropy, const std::string_view additional_input) noexcept -> state; - #endif // BOOST_CRYPT_HAS_STRING_VIEW - - #ifdef BOOST_CRYPT_HAS_SPAN - template - constexpr auto reseed(std::span entropy) noexcept -> state; - - template - constexpr auto reseed(std::span entropy, std::span additional_input) noexcept -> state; - #endif // BOOST_CRYPT_HAS_SPAN - - template - BOOST_CRYPT_GPU_ENABLED constexpr auto generate(ForwardIter1 data, boost::crypt::size_t requested_bits ForwardIter2 additional_data_1 = nullptr, boost::crypt::size_t additional_data_1_size = 0U, ForwardIter3 additional_data_2 = nullptr, boost::crypt::size_t additional_data_2_size = 0U) noexcept -> state; +public: - BOOST_CRYPT_GPU_ENABLED constexpr auto destroy() noexcept; + BOOST_CRYPT_GPU_ENABLED_CONSTEXPR hash_drbg() noexcept = default; + + BOOST_CRYPT_GPU_ENABLED_CONSTEXPR ~hash_drbg() noexcept; + + template + BOOST_CRYPT_GPU_ENABLED_CONSTEXPR auto init( + compat::span entropy, + compat::span nonce = compat::span{}, + compat::span personalization = compat::span{}) noexcept -> state; + + template > + BOOST_CRYPT_GPU_ENABLED auto init( + SizedRange1&& entropy, + SizedRange2&& nonce = compat::span {}, + SizedRange3&& personalization = compat::span {}) noexcept -> state; + + template + BOOST_CRYPT_GPU_ENABLED_CONSTEXPR auto reseed( + compat::span entropy, + compat::span additional_input = compat::span{}) noexcept -> state; + + template > + BOOST_CRYPT_GPU_ENABLED auto reseed( + SizedRange1&& entropy, + SizedRange2&& additional_input = compat::span {}) noexcept -> state; + + template + BOOST_CRYPT_GPU_ENABLED_CONSTEXPR auto generate( + compat::span return_data, compat::size_t requested_bits, + compat::span additional_data1 = compat::span {}, + [[maybe_unused]] compat::span additional_data2 = compat::span {}) noexcept -> state; + + template , + concepts::sized_range SizedRange3 = compat::span> + BOOST_CRYPT_GPU_ENABLED auto generate( + SizedRange1&& return_data, compat::size_t requested_bits, + SizedRange2&& additional_data1 = compat::span{}, + [[maybe_unused]] SizedRange3&& additional_data2 = compat::span{}) noexcept -> state; }; } // namespace drbg @@ -146,3 +127,5 @@ public: } // namespace boost ---- + +IMPORTANT: In the generate methods if you are using a prediction resistant DRBG you are required at add additional entropy as `addtional_data1` and optionally add personalization with `additional_data2`. These are both optional with a non-prediction resistant DRBG. From b8ce03c7bab9fdf25b95b08c3b580e2938449051 Mon Sep 17 00:00:00 2001 From: Matt Borland Date: Thu, 6 Feb 2025 11:25:55 -0500 Subject: [PATCH 2/4] Add hash drbgs to API reference --- doc/crypt/api_reference.adoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/crypt/api_reference.adoc b/doc/crypt/api_reference.adoc index ebb992dd..4a944246 100644 --- a/doc/crypt/api_reference.adoc +++ b/doc/crypt/api_reference.adoc @@ -45,7 +45,6 @@ https://www.boost.org/LICENSE_1_0.txt === Hash-Based Message Authentication Codes (HMAC) - <> -//// === Deterministic Random Bit Generators (DRBG) ==== Hash-Based ===== Non-Prediction Resistant @@ -73,7 +72,7 @@ https://www.boost.org/LICENSE_1_0.txt - <> - <> - <> - +//// ==== HMAC-Based ===== Non-Prediction Resistant - <> From 4a4371a57354cb3dc3ff6e864e9e1215c2d7e596 Mon Sep 17 00:00:00 2001 From: Matt Borland Date: Thu, 6 Feb 2025 11:30:52 -0500 Subject: [PATCH 3/4] Update HMAC DRBG docs page --- doc/crypt/hmac_drbg.adoc | 109 ++++++++++++++++----------------------- 1 file changed, 44 insertions(+), 65 deletions(-) diff --git a/doc/crypt/hmac_drbg.adoc b/doc/crypt/hmac_drbg.adoc index e927e668..fa9d713d 100644 --- a/doc/crypt/hmac_drbg.adoc +++ b/doc/crypt/hmac_drbg.adoc @@ -60,75 +60,52 @@ namespace drbg { // 256: SHA-256, SHA-512/256 // 384: SHA-384 // 512: SHA-512 -template +template class hmac_drbg { public: - BOOST_CRYPT_GPU_ENABLED constexpr hmac_drbg() = default; - - template - BOOST_CRYPT_GPU_ENABLED constexpr auto init(ForwardIter1 entropy, boost::crypt::size_t entropy_size, ForwardIter2 nonce = nullptr, boost::crypt::size_t nonce_size = 0, ForwardIter3 personalization = nullptr, boost::crypt::size_t personalization_size = 0) noexcept -> state; - - template - BOOST_CRYPT_GPU_ENABLED constexpr auto init(const Container1& entropy, const Container2& nonce, const Container3& personalization) noexcept -> state; - - template - BOOST_CRYPT_GPU_ENABLED constexpr auto init(const Container1& entropy, const Container2& nonce) noexcept -> state; - - template - BOOST_CRYPT_GPU_ENABLED constexpr auto init(const Container1& entropy) noexcept -> state; - - #ifdef BOOST_CRYPT_HAS_STRING_VIEW - constexpr auto init(std::string_view entropy) noexcept -> state; - constexpr auto init(std::string_view entropy, std::string_view nonce) noexcept -> state; - constexpr auto init(std::string_view entropy, std::string_view nonce, std::string_view personalization) noexcept -> state; - #endif - - #ifdef BOOST_CRYPT_HAS_SPAN - template - constexpr auto init(std::span entropy) noexcept -> state; - - template - constexpr auto init(std::span entropy, std::span nonce) noexcept -> state; - - template - constexpr auto init(std::span entropy, std::span nonce, std::span personalization) noexcept -> state; - #endif - - template - BOOST_CRYPT_GPU_ENABLED constexpr auto reseed(ForwardIter1 entropy, boost::crypt::size_t entropy_size, ForwardIter2 additional_input = nullptr, boost::crypt::size_t additional_input_size = 0) noexcept -> state; - - template - BOOST_CRYPT_GPU_ENABLED constexpr auto reseed(const Container1& entropy) noexcept -> state; - - template - BOOST_CRYPT_GPU_ENABLED constexpr auto reseed(const Container1& entropy, const Container2& additional_input) noexcept -> state; - - #ifdef BOOST_CRYPT_HAS_STRING_VIEW - constexpr auto reseed(std::string_view entropy) noexcept -> state; - constexpr auto reseed(std::string_view entropy, std::string_view additional_input) noexcept -> state; - #endif - - #ifdef BOOST_CRYPT_HAS_SPAN - template - constexpr auto reseed(std::span entropy) noexcept -> state; - - template - constexpr auto reseed(std::span entropy, std::span additional_input) noexcept -> state; - #endif - - template - BOOST_CRYPT_GPU_ENABLED constexpr auto generate(ForwardIter1 data, boost::crypt::size_t requested_bits, ForwardIter2 additional_data_1 = nullptr, boost::crypt::size_t additional_data_1_size = 0, ForwardIter3 additional_data_2 = nullptr, boost::crypt::size_t additional_data_2_size = 0) noexcept -> state; - - template - BOOST_CRYPT_GPU_ENABLED constexpr auto generate(Container1& data) noexcept -> state; - - template - BOOST_CRYPT_GPU_ENABLED constexpr auto generate(Container1& data, const Container2& additional_data_1) noexcept -> state; - - template - BOOST_CRYPT_GPU_ENABLED constexpr auto generate(Container1& data, const Container2& additional_data_1, const Container3& additional_data_2) noexcept -> state; + BOOST_CRYPT_GPU_ENABLED_CONSTEXPR hmac_drbg() noexcept = default; + BOOST_CRYPT_GPU_ENABLED_CONSTEXPR ~hmac_drbg() noexcept; + + template + BOOST_CRYPT_GPU_ENABLED_CONSTEXPR auto init( + compat::span entropy, + compat::span nonce = compat::span {}, + compat::span personalization = compat::span{}) noexcept -> state; + + template , + concepts::sized_range SizedRange3 = compat::span> + BOOST_CRYPT_GPU_ENABLED auto init( + SizedRange1&& entropy, + SizedRange2&& nonce = compat::span{}, + SizedRange3&& personalization = compat::span{}) noexcept -> state; + + template + BOOST_CRYPT_GPU_ENABLED_CONSTEXPR auto reseed( + compat::span entropy, + compat::span additional_input = compat::span{}) noexcept -> state; + + template > + BOOST_CRYPT_GPU_ENABLED auto reseed( + SizedRange1&& entropy, + SizedRange2&& additional_data = compat::span{}) noexcept -> state; + + template + BOOST_CRYPT_GPU_ENABLED_CONSTEXPR auto generate( + compat::span return_data, compat::size_t requested_bits, + compat::span additional_data_1 = compat::span{}, + compat::span additional_data_2 = compat::span{}) noexcept -> state; + + template , + concepts::sized_range SizedRange3 = compat::span> + BOOST_CRYPT_GPU_ENABLED auto generate( + SizedRange1&& return_data, compat::size_t requested_bits, + SizedRange2&& additional_data_1 = compat::span{}, + SizedRange3&& additional_data_2 = compat::span{}) noexcept -> state; }; @@ -137,3 +114,5 @@ public: } // namespace boost ---- + +IMPORTANT: In the generate methods if you are using a prediction resistant DRBG you are required at add additional entropy as `addtional_data_1` and optionally add personalization with `additional_data_2`. These are both optional with a non-prediction resistant DRBG. From b061a33ba78b39aec3eac5111ed6a1d4aa61043e Mon Sep 17 00:00:00 2001 From: Matt Borland Date: Thu, 6 Feb 2025 11:31:20 -0500 Subject: [PATCH 4/4] Add to master and API reference --- doc/crypt.adoc | 4 ++-- doc/crypt/api_reference.adoc | 3 +-- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/doc/crypt.adoc b/doc/crypt.adoc index ed141dda..9f4dbdbe 100644 --- a/doc/crypt.adoc +++ b/doc/crypt.adoc @@ -52,9 +52,9 @@ include::crypt/shake256.adoc[] include::crypt/hmac.adoc[] include::crypt/hash_drbg.adoc[] -//// + include::crypt/hmac_drbg.adoc[] -//// + include::crypt/concepts.adoc[] include::crypt/config.adoc[] diff --git a/doc/crypt/api_reference.adoc b/doc/crypt/api_reference.adoc index 4a944246..0d6295bf 100644 --- a/doc/crypt/api_reference.adoc +++ b/doc/crypt/api_reference.adoc @@ -72,7 +72,7 @@ https://www.boost.org/LICENSE_1_0.txt - <> - <> - <> -//// + ==== HMAC-Based ===== Non-Prediction Resistant - <> @@ -99,7 +99,6 @@ https://www.boost.org/LICENSE_1_0.txt - <> - <> - <> -//// == Enums