Skip to content

Commit c3e2562

Browse files
mborlandmborland
authored
Merge pull request #241 from cppalliance/drbg_docs
Update DRBG docs
2 parents afaf298 + b061a33 commit c3e2562

File tree

4 files changed

+98
-138
lines changed

4 files changed

+98
-138
lines changed

‎doc/crypt.adoc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -50,11 +50,11 @@ include::crypt/shake128.adoc[]
5050
include::crypt/shake256.adoc[]
5151

5252
include::crypt/hmac.adoc[]
53-
////
53+
5454
include::crypt/hash_drbg.adoc[]
5555

5656
include::crypt/hmac_drbg.adoc[]
57-
////
57+
5858
include::crypt/concepts.adoc[]
5959

6060
include::crypt/config.adoc[]

‎doc/crypt/api_reference.adoc‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,6 @@ https://www.boost.org/LICENSE_1_0.txt
4545
=== Hash-Based Message Authentication Codes (HMAC)
4646
- <<hmac, `hmac`>>
4747

48-
////
4948
=== Deterministic Random Bit Generators (DRBG)
5049
==== Hash-Based
5150
===== Non-Prediction Resistant
@@ -100,7 +99,6 @@ https://www.boost.org/LICENSE_1_0.txt
10099
- <<hmac_drbg, `sha3_256_hmac_drbg_pr`>>
101100
- <<hmac_drbg, `sha3_384_hmac_drbg_pr`>>
102101
- <<hmac_drbg, `sha3_512_hmac_drbg_pr`>>
103-
////
104102

105103
== Enums
106104

‎doc/crypt/hash_drbg.adoc‎

Lines changed: 52 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ using sha1_hash_drbg_t = hash_drbg<sha1_hasher, 128U, 160U, prediction_resistanc
4848
BOOST_CRYPT_EXPORT using sha1_hash_drbg = drbg::sha1_hash_drbg_t<false>;
4949
BOOST_CRYPT_EXPORT using sha1_hash_drbg_pr = drbg::sha1_hash_drbg_t<true>;
5050
51-
// So on for each hasher available with te correct presets
51+
// So on for each hasher available with the correct presets
5252
5353
namespace drbg {
5454
@@ -66,83 +66,66 @@ namespace drbg {
6666
// 256: SHA-256, SHA-512/256
6767
// 384: SHA-384
6868
// 512: SHA-512
69-
template <typename HasherType, boost::crypt::size_t max_hasher_security, boost::crypt::size_t outlen, bool prediction_resistance>
69+
template <typename HasherType, compat:size_t max_hasher_security, compat::size_t outlen, bool prediction_resistance>
7070
class hash_drbg
7171
{
7272
public:
7373
74-
BOOST_CRYPT_GPU_ENABLED constexpr hash_drbg() noexcept = default;
75-
76-
#ifdef BOOST_CRYPT_HAS_CXX20_CONSTEXPR
77-
BOOST_CRYPT_GPU_ENABLED constexpr ~hash_drbg() noexcept
78-
{
79-
destroy();
80-
}
81-
#endif
82-
83-
template <typename ForwardIter1, typename ForwardIter2 = boost::crypt::uint8_t*, typename ForwardIter3 = boost::crypt::uint8_t*>
84-
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;
85-
86-
template <typename Container1>
87-
BOOST_CRYPT_GPU_ENABLED constexpr auto init(const Container1& entropy) noexcept -> state;
88-
89-
template <typename Container1, typename Container2>
90-
BOOST_CRYPT_GPU_ENABLED constexpr auto init(const Container1& entropy, const Container2& nonce) noexcept -> state;
91-
92-
template <typename Container1, typename Container2, typename Container3>
93-
BOOST_CRYPT_GPU_ENABLED constexpr auto init(const Container1& entropy, const Container2& nonce, const Container3& personalization) noexcept -> state;
94-
95-
#ifdef BOOST_CRYPT_HAS_STRING_VIEW
96-
constexpr auto init(std::string_view entropy) noexcept -> state;
97-
98-
constexpr auto init(std::string_view entropy, std::string_view nonce) noexcept -> state;
99-
100-
constexpr auto init(std::string_view entropy, std::string_view nonce, std::string_view personalization) noexcept -> state;
101-
#endif
102-
103-
#ifdef BOOST_CRYPT_HAS_SPAN
104-
template <typename T, std::size_t extent>
105-
constexpr auto init(std::span<T, extent> entropy) noexcept -> state;
106-
107-
template <typename T, std::size_t extent>
108-
constexpr auto init(std::span<T, extent> entropy, std::span<T, extent> nonce) noexcept -> state;
109-
110-
template <typename T, std::size_t extent>
111-
constexpr auto init(std::span<T, extent> entropy, std::span<T, extent> nonce, std::span<T, extent> personalization) noexcept -> state;
112-
#endif
113-
114-
template <typename ForwardIter1, typename ForwardIter2 = boost::crypt::uint8_t*>
115-
BOOST_CRYPT_GPU_ENABLED constexpr auto reseed(ForwardIter1 entropy, boost::crypt::size_t entropy_size,
116-
ForwardIter2 additional_input = nullptr, boost::crypt::size_t additional_input_size = 0U) noexcept -> state;
117-
118-
template <typename Container1>
119-
BOOST_CRYPT_GPU_ENABLED constexpr auto reseed(const Container1& entropy) noexcept -> state;
120-
121-
template <typename Container1, typename Container2>
122-
BOOST_CRYPT_GPU_ENABLED constexpr auto reseed(const Container1& entropy, const Container2& additional_input) noexcept -> state;
123-
124-
#ifdef BOOST_CRYPT_HAS_STRING_VIEW
125-
constexpr auto reseed(const std::string_view entropy) noexcept -> state;
126-
127-
constexpr auto reseed(const std::string_view entropy, const std::string_view additional_input) noexcept -> state;
128-
#endif // BOOST_CRYPT_HAS_STRING_VIEW
129-
130-
#ifdef BOOST_CRYPT_HAS_SPAN
131-
template <typename T, std::size_t extent>
132-
constexpr auto reseed(std::span<T, extent> entropy) noexcept -> state;
133-
134-
template <typename T, std::size_t extent>
135-
constexpr auto reseed(std::span<T, extent> entropy, std::span<T, extent> additional_input) noexcept -> state;
136-
#endif // BOOST_CRYPT_HAS_SPAN
137-
138-
template <typename ForwardIter1, typename ForwardIter2 = boost::crypt::uint8_t*, typename ForwardIter3 = boost::crypt::uint8_t*>
139-
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;
74+
public:
14075
141-
BOOST_CRYPT_GPU_ENABLED constexpr auto destroy() noexcept;
76+
BOOST_CRYPT_GPU_ENABLED_CONSTEXPR hash_drbg() noexcept = default;
77+
78+
BOOST_CRYPT_GPU_ENABLED_CONSTEXPR ~hash_drbg() noexcept;
79+
80+
template <compat::size_t Extent1,
81+
compat::size_t Extent2 = 0U,
82+
compat::size_t Extent3 = 0U>
83+
BOOST_CRYPT_GPU_ENABLED_CONSTEXPR auto init(
84+
compat::span<const compat::byte, Extent1> entropy,
85+
compat::span<const compat::byte, Extent2> nonce = compat::span<const compat::byte, 0>{},
86+
compat::span<const compat::byte, Extent3> personalization = compat::span<const compat::byte, 0>{}) noexcept -> state;
87+
88+
template <concepts::sized_range SizedRange1,
89+
concepts::sized_range SizedRange2,
90+
concepts::sized_range SizedRange3 = compat::span<const compat::byte, 0U>>
91+
BOOST_CRYPT_GPU_ENABLED auto init(
92+
SizedRange1&& entropy,
93+
SizedRange2&& nonce = compat::span<const compat::byte, 0U> {},
94+
SizedRange3&& personalization = compat::span<const compat::byte, 0U> {}) noexcept -> state;
95+
96+
template <compat::size_t Extent1,
97+
compat::size_t Extent2 = 0U>
98+
BOOST_CRYPT_GPU_ENABLED_CONSTEXPR auto reseed(
99+
compat::span<const compat::byte, Extent1> entropy,
100+
compat::span<const compat::byte, Extent2> additional_input = compat::span<const compat::byte, 0>{}) noexcept -> state;
101+
102+
template <concepts::sized_range SizedRange1,
103+
concepts::sized_range SizedRange2 = compat::span<const compat::byte, 0U>>
104+
BOOST_CRYPT_GPU_ENABLED auto reseed(
105+
SizedRange1&& entropy,
106+
SizedRange2&& additional_input = compat::span<const compat::byte, 0U> {}) noexcept -> state;
107+
108+
template <compat::size_t Extent1,
109+
compat::size_t Extent2 = 0U,
110+
compat::size_t Extent3 = 0U>
111+
BOOST_CRYPT_GPU_ENABLED_CONSTEXPR auto generate(
112+
compat::span<compat::byte, Extent1> return_data, compat::size_t requested_bits,
113+
compat::span<const compat::byte, Extent2> additional_data1 = compat::span<const compat::byte, 0U> {},
114+
[[maybe_unused]] compat::span<const compat::byte, Extent3> additional_data2 = compat::span<const compat::byte, 0U> {}) noexcept -> state;
115+
116+
template <concepts::sized_range SizedRange1,
117+
concepts::sized_range SizedRange2 = compat::span<const compat::byte, 0U>,
118+
concepts::sized_range SizedRange3 = compat::span<const compat::byte, 0U>>
119+
BOOST_CRYPT_GPU_ENABLED auto generate(
120+
SizedRange1&& return_data, compat::size_t requested_bits,
121+
SizedRange2&& additional_data1 = compat::span<const compat::byte, 0U>{},
122+
[[maybe_unused]] SizedRange3&& additional_data2 = compat::span<const compat::byte, 0U>{}) noexcept -> state;
142123
};
143124
144125
} // namespace drbg
145126
} // namespace crypt
146127
} // namespace boost
147128
148129
----
130+
131+
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.

‎doc/crypt/hmac_drbg.adoc‎

Lines changed: 44 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -60,75 +60,52 @@ namespace drbg {
6060
// 256: SHA-256, SHA-512/256
6161
// 384: SHA-384
6262
// 512: SHA-512
63-
template <typename HMACType, boost::crypt::size_t max_hasher_security, boost::crypt::size_t outlen, bool prediction_resistance>
63+
template <typename HMACType, compat::size_t max_hasher_security, compat::size_t outlen, bool prediction_resistance>
6464
class hmac_drbg
6565
{
6666
public:
6767
68-
BOOST_CRYPT_GPU_ENABLED constexpr hmac_drbg() = default;
69-
70-
template <typename ForwardIter1, typename ForwardIter2, typename ForwardIter3 = const boost::crypt::uint8_t*>
71-
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;
72-
73-
template <typename Container1, typename Container2, typename Container3>
74-
BOOST_CRYPT_GPU_ENABLED constexpr auto init(const Container1& entropy, const Container2& nonce, const Container3& personalization) noexcept -> state;
75-
76-
template <typename Container1, typename Container2>
77-
BOOST_CRYPT_GPU_ENABLED constexpr auto init(const Container1& entropy, const Container2& nonce) noexcept -> state;
78-
79-
template <typename Container1>
80-
BOOST_CRYPT_GPU_ENABLED constexpr auto init(const Container1& entropy) noexcept -> state;
81-
82-
#ifdef BOOST_CRYPT_HAS_STRING_VIEW
83-
constexpr auto init(std::string_view entropy) noexcept -> state;
84-
constexpr auto init(std::string_view entropy, std::string_view nonce) noexcept -> state;
85-
constexpr auto init(std::string_view entropy, std::string_view nonce, std::string_view personalization) noexcept -> state;
86-
#endif
87-
88-
#ifdef BOOST_CRYPT_HAS_SPAN
89-
template <typename T, std::size_t extent>
90-
constexpr auto init(std::span<T, extent> entropy) noexcept -> state;
91-
92-
template <typename T, std::size_t extent>
93-
constexpr auto init(std::span<T, extent> entropy, std::span<T, extent> nonce) noexcept -> state;
94-
95-
template <typename T, std::size_t extent>
96-
constexpr auto init(std::span<T, extent> entropy, std::span<T, extent> nonce, std::span<T, extent> personalization) noexcept -> state;
97-
#endif
98-
99-
template <typename ForwardIter1, typename ForwardIter2 = const boost::crypt::uint8_t*>
100-
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;
101-
102-
template <typename Container1>
103-
BOOST_CRYPT_GPU_ENABLED constexpr auto reseed(const Container1& entropy) noexcept -> state;
104-
105-
template <typename Container1, typename Container2>
106-
BOOST_CRYPT_GPU_ENABLED constexpr auto reseed(const Container1& entropy, const Container2& additional_input) noexcept -> state;
107-
108-
#ifdef BOOST_CRYPT_HAS_STRING_VIEW
109-
constexpr auto reseed(std::string_view entropy) noexcept -> state;
110-
constexpr auto reseed(std::string_view entropy, std::string_view additional_input) noexcept -> state;
111-
#endif
112-
113-
#ifdef BOOST_CRYPT_HAS_SPAN
114-
template <typename T, std::size_t extent>
115-
constexpr auto reseed(std::span<T, extent> entropy) noexcept -> state;
116-
117-
template <typename T, std::size_t extent>
118-
constexpr auto reseed(std::span<T, extent> entropy, std::span<T, extent> additional_input) noexcept -> state;
119-
#endif
120-
121-
template <typename ForwardIter1, typename ForwardIter2 = const boost::crypt::uint8_t*, typename ForwardIter3 = const boost::crypt::uint8_t*>
122-
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;
123-
124-
template <typename Container1>
125-
BOOST_CRYPT_GPU_ENABLED constexpr auto generate(Container1& data) noexcept -> state;
126-
127-
template <typename Container1, typename Container2>
128-
BOOST_CRYPT_GPU_ENABLED constexpr auto generate(Container1& data, const Container2& additional_data_1) noexcept -> state;
129-
130-
template <typename Container1, typename Container2, typename Container3>
131-
BOOST_CRYPT_GPU_ENABLED constexpr auto generate(Container1& data, const Container2& additional_data_1, const Container3& additional_data_2) noexcept -> state;
68+
BOOST_CRYPT_GPU_ENABLED_CONSTEXPR hmac_drbg() noexcept = default;
69+
BOOST_CRYPT_GPU_ENABLED_CONSTEXPR ~hmac_drbg() noexcept;
70+
71+
template <compat::size_t Extent1, compat::size_t Extent2 = 0U, compat::size_t Extent3 = 0U>
72+
BOOST_CRYPT_GPU_ENABLED_CONSTEXPR auto init(
73+
compat::span<const compat::byte, Extent1> entropy,
74+
compat::span<const compat::byte, Extent2> nonce = compat::span<const compat::byte, 0U> {},
75+
compat::span<const compat::byte, Extent3> personalization = compat::span<const compat::byte, 0U>{}) noexcept -> state;
76+
77+
template <concepts::sized_range SizedRange1,
78+
concepts::sized_range SizedRange2 = compat::span<const compat::byte, 0U>,
79+
concepts::sized_range SizedRange3 = compat::span<const compat::byte, 0U>>
80+
BOOST_CRYPT_GPU_ENABLED auto init(
81+
SizedRange1&& entropy,
82+
SizedRange2&& nonce = compat::span<const compat::byte, 0U>{},
83+
SizedRange3&& personalization = compat::span<const compat::byte, 0U>{}) noexcept -> state;
84+
85+
template <compat::size_t Extent1, compat::size_t Extent2 = 0U>
86+
BOOST_CRYPT_GPU_ENABLED_CONSTEXPR auto reseed(
87+
compat::span<const compat::byte, Extent1> entropy,
88+
compat::span<const compat::byte, Extent2> additional_input = compat::span<const compat::byte, 0>{}) noexcept -> state;
89+
90+
template <concepts::sized_range SizedRange1,
91+
concepts::sized_range SizedRange2 = compat::span<const compat::byte, 0U>>
92+
BOOST_CRYPT_GPU_ENABLED auto reseed(
93+
SizedRange1&& entropy,
94+
SizedRange2&& additional_data = compat::span<const compat::byte, 0U>{}) noexcept -> state;
95+
96+
template <compat::size_t Extent1, compat::size_t Extent2 = 0U, compat::size_t Extent3 = 0U>
97+
BOOST_CRYPT_GPU_ENABLED_CONSTEXPR auto generate(
98+
compat::span<compat::byte, Extent1> return_data, compat::size_t requested_bits,
99+
compat::span<const compat::byte, Extent2> additional_data_1 = compat::span<const compat::byte, 0U>{},
100+
compat::span<const compat::byte, Extent3> additional_data_2 = compat::span<const compat::byte, 0U>{}) noexcept -> state;
101+
102+
template <concepts::sized_range SizedRange1,
103+
concepts::sized_range SizedRange2 = compat::span<const compat::byte, 0U>,
104+
concepts::sized_range SizedRange3 = compat::span<const compat::byte, 0U>>
105+
BOOST_CRYPT_GPU_ENABLED auto generate(
106+
SizedRange1&& return_data, compat::size_t requested_bits,
107+
SizedRange2&& additional_data_1 = compat::span<const compat::byte, 0U>{},
108+
SizedRange3&& additional_data_2 = compat::span<const compat::byte, 0U>{}) noexcept -> state;
132109
133110
};
134111
@@ -137,3 +114,5 @@ public:
137114
} // namespace boost
138115
139116
----
117+
118+
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.

0 commit comments

Comments
 (0)