Skip to content

Update DRBG docs #241

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mborland merged 4 commits into from
Feb 6, 2025
Merged

Update DRBG docs #241

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
cfbbd43
Update hash drbg docs
mborland Feb 6, 2025
b8ce03c
Add hash drbgs to API reference
mborland Feb 6, 2025
4a4371a
Update HMAC DRBG docs page
mborland Feb 6, 2025
b061a33
Add to master and API reference
mborland Feb 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions doc/crypt.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,11 +50,11 @@ include::crypt/shake128.adoc[]
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[]
Expand Down
2 changes: 0 additions & 2 deletions doc/crypt/api_reference.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,6 @@ https://www.boost.org/LICENSE_1_0.txt
=== Hash-Based Message Authentication Codes (HMAC)
- <<hmac, `hmac`>>

////
=== Deterministic Random Bit Generators (DRBG)
==== Hash-Based
===== Non-Prediction Resistant
Expand Down Expand Up @@ -100,7 +99,6 @@ https://www.boost.org/LICENSE_1_0.txt
- <<hmac_drbg, `sha3_256_hmac_drbg_pr`>>
- <<hmac_drbg, `sha3_384_hmac_drbg_pr`>>
- <<hmac_drbg, `sha3_512_hmac_drbg_pr`>>
////

== Enums

Expand Down
121 changes: 52 additions & 69 deletions doc/crypt/hash_drbg.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ using sha1_hash_drbg_t = hash_drbg<sha1_hasher, 128U, 160U, prediction_resistanc
BOOST_CRYPT_EXPORT using sha1_hash_drbg = drbg::sha1_hash_drbg_t<false>;
BOOST_CRYPT_EXPORT using sha1_hash_drbg_pr = drbg::sha1_hash_drbg_t<true>;

// So on for each hasher available with te correct presets
// So on for each hasher available with the correct presets

namespace drbg {

Expand All @@ -66,83 +66,66 @@ namespace drbg {
// 256: SHA-256, SHA-512/256
// 384: SHA-384
// 512: SHA-512
template <typename HasherType, boost::crypt::size_t max_hasher_security, boost::crypt::size_t outlen, bool prediction_resistance>
template <typename HasherType, compat:size_t max_hasher_security, compat::size_t outlen, bool prediction_resistance>
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 <typename ForwardIter1, typename ForwardIter2 = boost::crypt::uint8_t*, typename ForwardIter3 = boost::crypt::uint8_t*>
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 <typename Container1>
BOOST_CRYPT_GPU_ENABLED constexpr auto init(const Container1& entropy) noexcept -> state;

template <typename Container1, typename Container2>
BOOST_CRYPT_GPU_ENABLED constexpr auto init(const Container1& entropy, const Container2& nonce) noexcept -> state;

template <typename Container1, typename Container2, typename Container3>
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 <typename T, std::size_t extent>
constexpr auto init(std::span<T, extent> entropy) noexcept -> state;

template <typename T, std::size_t extent>
constexpr auto init(std::span<T, extent> entropy, std::span<T, extent> nonce) noexcept -> state;

template <typename T, std::size_t extent>
constexpr auto init(std::span<T, extent> entropy, std::span<T, extent> nonce, std::span<T, extent> personalization) noexcept -> state;
#endif

template <typename ForwardIter1, typename ForwardIter2 = boost::crypt::uint8_t*>
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 <typename Container1>
BOOST_CRYPT_GPU_ENABLED constexpr auto reseed(const Container1& entropy) noexcept -> state;

template <typename Container1, typename Container2>
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 <typename T, std::size_t extent>
constexpr auto reseed(std::span<T, extent> entropy) noexcept -> state;

template <typename T, std::size_t extent>
constexpr auto reseed(std::span<T, extent> entropy, std::span<T, extent> additional_input) noexcept -> state;
#endif // BOOST_CRYPT_HAS_SPAN

template <typename ForwardIter1, typename ForwardIter2 = boost::crypt::uint8_t*, typename ForwardIter3 = boost::crypt::uint8_t*>
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 <compat::size_t Extent1,
compat::size_t Extent2 = 0U,
compat::size_t Extent3 = 0U>
BOOST_CRYPT_GPU_ENABLED_CONSTEXPR auto init(
compat::span<const compat::byte, Extent1> entropy,
compat::span<const compat::byte, Extent2> nonce = compat::span<const compat::byte, 0>{},
compat::span<const compat::byte, Extent3> personalization = compat::span<const compat::byte, 0>{}) noexcept -> state;

template <concepts::sized_range SizedRange1,
concepts::sized_range SizedRange2,
concepts::sized_range SizedRange3 = compat::span<const compat::byte, 0U>>
BOOST_CRYPT_GPU_ENABLED auto init(
SizedRange1&& entropy,
SizedRange2&& nonce = compat::span<const compat::byte, 0U> {},
SizedRange3&& personalization = compat::span<const compat::byte, 0U> {}) noexcept -> state;

template <compat::size_t Extent1,
compat::size_t Extent2 = 0U>
BOOST_CRYPT_GPU_ENABLED_CONSTEXPR auto reseed(
compat::span<const compat::byte, Extent1> entropy,
compat::span<const compat::byte, Extent2> additional_input = compat::span<const compat::byte, 0>{}) noexcept -> state;

template <concepts::sized_range SizedRange1,
concepts::sized_range SizedRange2 = compat::span<const compat::byte, 0U>>
BOOST_CRYPT_GPU_ENABLED auto reseed(
SizedRange1&& entropy,
SizedRange2&& additional_input = compat::span<const compat::byte, 0U> {}) noexcept -> state;

template <compat::size_t Extent1,
compat::size_t Extent2 = 0U,
compat::size_t Extent3 = 0U>
BOOST_CRYPT_GPU_ENABLED_CONSTEXPR auto generate(
compat::span<compat::byte, Extent1> return_data, compat::size_t requested_bits,
compat::span<const compat::byte, Extent2> additional_data1 = compat::span<const compat::byte, 0U> {},
[[maybe_unused]] compat::span<const compat::byte, Extent3> additional_data2 = compat::span<const compat::byte, 0U> {}) noexcept -> state;

template <concepts::sized_range SizedRange1,
concepts::sized_range SizedRange2 = compat::span<const compat::byte, 0U>,
concepts::sized_range SizedRange3 = compat::span<const compat::byte, 0U>>
BOOST_CRYPT_GPU_ENABLED auto generate(
SizedRange1&& return_data, compat::size_t requested_bits,
SizedRange2&& additional_data1 = compat::span<const compat::byte, 0U>{},
[[maybe_unused]] SizedRange3&& additional_data2 = compat::span<const compat::byte, 0U>{}) noexcept -> state;
};

} // namespace drbg
} // namespace crypt
} // 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.
109 changes: 44 additions & 65 deletions doc/crypt/hmac_drbg.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,75 +60,52 @@ namespace drbg {
// 256: SHA-256, SHA-512/256
// 384: SHA-384
// 512: SHA-512
template <typename HMACType, boost::crypt::size_t max_hasher_security, boost::crypt::size_t outlen, bool prediction_resistance>
template <typename HMACType, compat::size_t max_hasher_security, compat::size_t outlen, bool prediction_resistance>
class hmac_drbg
{
public:

BOOST_CRYPT_GPU_ENABLED constexpr hmac_drbg() = default;

template <typename ForwardIter1, typename ForwardIter2, typename ForwardIter3 = const boost::crypt::uint8_t*>
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 <typename Container1, typename Container2, typename Container3>
BOOST_CRYPT_GPU_ENABLED constexpr auto init(const Container1& entropy, const Container2& nonce, const Container3& personalization) noexcept -> state;

template <typename Container1, typename Container2>
BOOST_CRYPT_GPU_ENABLED constexpr auto init(const Container1& entropy, const Container2& nonce) noexcept -> state;

template <typename Container1>
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 <typename T, std::size_t extent>
constexpr auto init(std::span<T, extent> entropy) noexcept -> state;

template <typename T, std::size_t extent>
constexpr auto init(std::span<T, extent> entropy, std::span<T, extent> nonce) noexcept -> state;

template <typename T, std::size_t extent>
constexpr auto init(std::span<T, extent> entropy, std::span<T, extent> nonce, std::span<T, extent> personalization) noexcept -> state;
#endif

template <typename ForwardIter1, typename ForwardIter2 = const boost::crypt::uint8_t*>
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 <typename Container1>
BOOST_CRYPT_GPU_ENABLED constexpr auto reseed(const Container1& entropy) noexcept -> state;

template <typename Container1, typename Container2>
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 <typename T, std::size_t extent>
constexpr auto reseed(std::span<T, extent> entropy) noexcept -> state;

template <typename T, std::size_t extent>
constexpr auto reseed(std::span<T, extent> entropy, std::span<T, extent> additional_input) noexcept -> state;
#endif

template <typename ForwardIter1, typename ForwardIter2 = const boost::crypt::uint8_t*, typename ForwardIter3 = const boost::crypt::uint8_t*>
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 <typename Container1>
BOOST_CRYPT_GPU_ENABLED constexpr auto generate(Container1& data) noexcept -> state;

template <typename Container1, typename Container2>
BOOST_CRYPT_GPU_ENABLED constexpr auto generate(Container1& data, const Container2& additional_data_1) noexcept -> state;

template <typename Container1, typename Container2, typename Container3>
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 <compat::size_t Extent1, compat::size_t Extent2 = 0U, compat::size_t Extent3 = 0U>
BOOST_CRYPT_GPU_ENABLED_CONSTEXPR auto init(
compat::span<const compat::byte, Extent1> entropy,
compat::span<const compat::byte, Extent2> nonce = compat::span<const compat::byte, 0U> {},
compat::span<const compat::byte, Extent3> personalization = compat::span<const compat::byte, 0U>{}) noexcept -> state;

template <concepts::sized_range SizedRange1,
concepts::sized_range SizedRange2 = compat::span<const compat::byte, 0U>,
concepts::sized_range SizedRange3 = compat::span<const compat::byte, 0U>>
BOOST_CRYPT_GPU_ENABLED auto init(
SizedRange1&& entropy,
SizedRange2&& nonce = compat::span<const compat::byte, 0U>{},
SizedRange3&& personalization = compat::span<const compat::byte, 0U>{}) noexcept -> state;

template <compat::size_t Extent1, compat::size_t Extent2 = 0U>
BOOST_CRYPT_GPU_ENABLED_CONSTEXPR auto reseed(
compat::span<const compat::byte, Extent1> entropy,
compat::span<const compat::byte, Extent2> additional_input = compat::span<const compat::byte, 0>{}) noexcept -> state;

template <concepts::sized_range SizedRange1,
concepts::sized_range SizedRange2 = compat::span<const compat::byte, 0U>>
BOOST_CRYPT_GPU_ENABLED auto reseed(
SizedRange1&& entropy,
SizedRange2&& additional_data = compat::span<const compat::byte, 0U>{}) noexcept -> state;

template <compat::size_t Extent1, compat::size_t Extent2 = 0U, compat::size_t Extent3 = 0U>
BOOST_CRYPT_GPU_ENABLED_CONSTEXPR auto generate(
compat::span<compat::byte, Extent1> return_data, compat::size_t requested_bits,
compat::span<const compat::byte, Extent2> additional_data_1 = compat::span<const compat::byte, 0U>{},
compat::span<const compat::byte, Extent3> additional_data_2 = compat::span<const compat::byte, 0U>{}) noexcept -> state;

template <concepts::sized_range SizedRange1,
concepts::sized_range SizedRange2 = compat::span<const compat::byte, 0U>,
concepts::sized_range SizedRange3 = compat::span<const compat::byte, 0U>>
BOOST_CRYPT_GPU_ENABLED auto generate(
SizedRange1&& return_data, compat::size_t requested_bits,
SizedRange2&& additional_data_1 = compat::span<const compat::byte, 0U>{},
SizedRange3&& additional_data_2 = compat::span<const compat::byte, 0U>{}) noexcept -> state;

};

Expand All @@ -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.