Shake and hmac docs

doc/crypt.adoc

@@ -4,7 +4,6 @@ Distributed under the Boost Software License, Version 1.0.
 https://www.boost.org/LICENSE_1_0.txt
 ////
 
-= Crypt: A Modern Cryptographic Module in C++20
 :toc: left
 :toclevels: 4
 :idprefix:
@@ -15,6 +14,9 @@ https://www.boost.org/LICENSE_1_0.txt
 
 :leveloffset: +1
 
+= Crypt: A Modern Cryptographic Module in C++20
+Matt Borland and Chris Kormanyos
+
 include::crypt/overview.adoc[]
 
 include::crypt/api_reference.adoc[]
@@ -42,9 +44,13 @@ include::crypt/sha3_256.adoc[]
 include::crypt/sha3_384.adoc[]
 
 include::crypt/sha3_512.adoc[]
-////
-include::crypt/hmac.adoc[]
 
+include::crypt/shake128.adoc[]
+
+include::crypt/shake256.adoc[]
+
+include::crypt/hmac.adoc[]
+////
 include::crypt/hash_drbg.adoc[]
 
 include::crypt/hmac_drbg.adoc[]

doc/crypt/api_reference.adoc

@@ -26,7 +26,6 @@ https://www.boost.org/LICENSE_1_0.txt
 ==== SHA2 Family of Hashers
 - <<sha224_hasher, `sha224_hasher`>>
 
-////
 - <<sha256_hasher, `sha256_hasher`>>
 - <<sha384_hasher, `sha384_hasher`>>
 - <<sha512_hasher, `sha512_hasher`>>
@@ -39,9 +38,14 @@ https://www.boost.org/LICENSE_1_0.txt
 - <<sha3_384_hasher, `sha3_384_hasher`>>
 - <<sha3_512_hasher, `sha3_512_hasher`>>
 
+==== Extendable-Output Functions
+- <<shake128_hasher, `shake128_hasher`>>
+- <<shake256_hasher, `shake256_hasher`>>
+
 === Hash-Based Message Authentication Codes (HMAC)
 - <<hmac, `hmac`>>
 
+////
 === Deterministic Random Bit Generators (DRBG)
 ==== Hash-Based
 ===== Non-Prediction Resistant

doc/crypt/concepts.adoc

@@ -8,7 +8,7 @@ https://www.boost.org/LICENSE_1_0.txt
 = Concepts
 :idprefix: concepts_
 
-The following are the defintions of the concepts used throughout the library to ensure consistency.
+The following are the definitions of the concepts used throughout the library to ensure consistency.
 
 [#file_system_path]
 == File System Path
@@ -36,7 +36,7 @@ concept file_system_path =
 } // namespace boost::crypt::concepts
 ----
 
-[#writable_output_range]
+[#writeable_output_range]
 == Writeable Output Range
 
 This concept is used to define the ranges that we can write to such as the `get_digest(Range&& data)` function of the hashers.

doc/crypt/hmac.adoc

@@ -24,10 +24,11 @@ boost::crypt::hmac<boost::crypt::sha512_hasher> hmac;
 const auto state_1 {hmac.init("key", 3)};
 BOOST_TEST(state_1 == boost::crypt::state::success);
 
-const char* msg {"The quick brown fox jumps over the lazy dog"};
-const auto state_2 {hmac.process_bytes(msg, std::strlen(msg))};
+std::string msg {"The quick brown fox jumps over the lazy dog"};
+const auto state_2 {hmac.process_bytes(msg)};
 BOOST_TEST(state_2 == boost::crypt::state::success);
 
+hmac.finalize();
 const auto res {hmac.get_digest()};
 ----
 
@@ -40,26 +41,31 @@ Continuing from our above example:
 [source, c++]
 ----
 boost::crypt::hmac<boost::crypt::sha512_hasher> hmac;
-const auto state_1 {hmac.init("key", 3)};
+const auto state_1 {hmac.init(std::string{"key"})};
 BOOST_TEST(state_1 == boost::crypt::state::success);
 
-const char* msg {"The quick brown fox jumps over the lazy dog"};
-const auto state_2 {hmac.process_bytes(msg, std::strlen(msg))};
+std::string msg {"The quick brown fox jumps over the lazy dog"};
+const auto state_2 {hmac.process_bytes(msg)};
 BOOST_TEST(state_2 == boost::crypt::state::success);
 
+BOOST_TEST(hmac.finalize() == boost::crypt::state::success);
+
 const auto res {hmac.get_digest()};
 
 const auto outer_key {hmac.get_outer_key()};
 const auto inner_key {hmac.get_inner_key()};
 
 // Do some stuff
 
-boost::crypt::hmac<boost::crypt::sha512_hasher> hmac2(inner_key, outer_key);
+boost::crypt::hmac<boost::crypt::sha512_hasher> hmac2;
+
+hmac2.init_from_keys(inner_key, outer_key);
 
-const char* msg2 {"The quick brown fox jumps over the lazy dog"};
-const auto state_3 {hmac2.process_bytes(msg, std::strlen(msg))};
+std::string msg2 {"The quick brown fox jumps over the lazy dog"};
+const auto state_3 {hmac2.process_bytes(msg)};
 BOOST_TEST(state_3 == boost::crypt::state::success);
 
+hmac2.finalize();
 const auto res2 {hmac2.get_digest()};
 ----
 
@@ -80,40 +86,46 @@ class hmac
 {
 public:
 
-    static constexpr boost::crypt::size_t block_size_ {HasherType::block_size};
+    static constexpr boost::crypt::size_t block_size {HasherType::block_size};
     using return_type = typename HasherType::return_type;
-    using key_type = boost::crypt::array<boost::crypt::uint8_t, block_size_>;
+    using key_type = compat::array<compat::byte, block_size>;
+
+BOOST_CRYPT_GPU_ENABLED_CONSTEXPR hmac() noexcept = default;
+
+    template <compat::size_t Extent = compat::dynamic_extent>
+    explicit BOOST_CRYPT_GPU_ENABLED_CONSTEXPR hmac(const compat::span<const compat::byte, Extent> key) noexcept;
 
-    BOOST_CRYPT_GPU_ENABLED constexpr hmac() noexcept = default;
+    BOOST_CRYPT_GPU_ENABLED_CONSTEXPR ~hmac() noexcept;
 
-    template <typename ForwardIter>
-    BOOST_CRYPT_GPU_ENABLED constexpr hmac(ForwardIter key, boost::crypt::size_t size) noexcept;
+    BOOST_CRYPT_GPU_ENABLED_CONSTEXPR auto init_from_keys(const key_type& inner_key,
+                                                          const key_type& outer_key) noexcept -> state;
 
-    template <typename Container>
-    BOOST_CRYPT_GPU_ENABLED constexpr hmac(const Container& c) noexcept;
+    template <compat::size_t Extent = compat::dynamic_extent>
+    BOOST_CRYPT_GPU_ENABLED_CONSTEXPR auto init(compat::span<const compat::byte, Extent> data) noexcept -> state;
 
-    BOOST_CRYPT_GPU_ENABLED constexpr hmac(const key_type& inner_key, const key_type& outer_key) noexcept;
+    template <concepts::sized_range SizedRange>
+    BOOST_CRYPT_GPU_ENABLED auto init(SizedRange&& data) noexcept -> state;
 
-    template <typename ForwardIter>
-    BOOST_CRYPT_GPU_ENABLED constexpr auto init(ForwardIter key, boost::crypt::size_t size) noexcept -> state;
+    template <compat::size_t Extent = compat::dynamic_extent>
+    BOOST_CRYPT_GPU_ENABLED_CONSTEXPR auto process_bytes(compat::span<const compat::byte, Extent> data) noexcept -> state;
 
-    template <typename Container>
-    BOOST_CRYPT_GPU_ENABLED constexpr auto init(const Container& c) noexcept -> state;
+    template <concepts::sized_range SizedRange>
+    BOOST_CRYPT_GPU_ENABLED auto process_bytes(SizedRange&& data) noexcept -> state;
 
-    template <typename Container>
-    BOOST_CRYPT_GPU_ENABLED constexpr auto init_from_keys(const Container& inner_key, const Container& outer_key) noexcept -> state;
+    BOOST_CRYPT_GPU_ENABLED_CONSTEXPR auto finalize() noexcept -> state;
 
-    template <typename ForwardIter>
-    BOOST_CRYPT_GPU_ENABLED constexpr auto process_bytes(ForwardIter data, boost::crypt::size_t size) noexcept -> state;
+    [[nodiscard]] BOOST_CRYPT_GPU_ENABLED_CONSTEXPR auto get_digest() const noexcept -> compat::expected<return_type, state>;
 
-    template <typename Container>
-    BOOST_CRYPT_GPU_ENABLED constexpr auto process_bytes(const Container& c) noexcept -> state;
+    template <compat::size_t Extent = compat::dynamic_extent>
+    [[nodiscard]] BOOST_CRYPT_GPU_ENABLED_CONSTEXPR
+    auto get_digest(compat::span<compat::byte, Extent> data) const noexcept -> state;
 
-    BOOST_CRYPT_GPU_ENABLED constexpr auto get_digest() noexcept -> return_type;
+    template <concepts::writable_output_range Range>
+    [[nodiscard]] BOOST_CRYPT_GPU_ENABLED auto get_digest(Range&& data) const noexcept -> state;
 
-    BOOST_CRYPT_GPU_ENABLED constexpr auto get_outer_key() noexcept -> key_type;
+    [[nodiscard]] BOOST_CRYPT_GPU_ENABLED_CONSTEXPR auto get_outer_key() const noexcept -> key_type;
 
-    BOOST_CRYPT_GPU_ENABLED constexpr auto get_inner_key() noexcept -> key_type;
+    [[nodiscard]] BOOST_CRYPT_GPU_ENABLED_CONSTEXPR auto get_inner_key() const noexcept -> key_type;
 
 } //namespace crypt
 } //namespace boost

doc/crypt/sha1.adoc

@@ -33,7 +33,7 @@ public:
     // Process bytes piecewise
     BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(compat::span<const compat::byte> data) noexcept;
 
-    template <compat::ranges::sized_range Range>
+    template <concepts::sized_range Range>
     BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(Range&& data) noexcept;
 
     // Finalize the calculation of the hash
@@ -59,7 +59,7 @@ namespace boost::crypt {
 
 [[nodiscard]] BOOST_CRYPT_GPU_ENABLED constexpr auto sha1(compat::span<const compat::byte> data) noexcept -> expected<sha1_hasher::return_type, state>;
 
-template <compat::ranges::sized_range SizedRange>
+template <concepts::sized_range SizedRange>
 [[nodiscard]] BOOST_CRYPT_GPU_ENABLED auto sha1(SizedRange&& data) noexcept -> expected<sha1_hasher::return_type, state>;
 
 } // namespace boost::crypt

doc/crypt/sha224.adoc

@@ -33,7 +33,7 @@ public:
     // Process bytes piecewise
     BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(compat::span<const compat::byte> data) noexcept;
 
-    template <compat::ranges::sized_range Range>
+    template <concepts::sized_range Range>
     BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(Range&& data) noexcept;
 
     // Finalize the calculation of the hash
@@ -59,7 +59,7 @@ namespace boost::crypt {
 
 [[nodiscard]] BOOST_CRYPT_GPU_ENABLED constexpr auto sha224(compat::span<const compat::byte> data) noexcept -> expected<sha224_hasher::return_type, state>;
 
-template <compat::ranges::sized_range SizedRange>
+template <concepts::sized_range SizedRange>
 [[nodiscard]] BOOST_CRYPT_GPU_ENABLED auto sha224(SizedRange&& data) noexcept -> expected<sha224_hasher::return_type, state>;
 
 } // namespace boost::crypt

doc/crypt/sha256.adoc

@@ -33,7 +33,7 @@ public:
     // Process bytes piecewise
     BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(compat::span<const compat::byte> data) noexcept;
 
-    template <compat::ranges::sized_range Range>
+    template <concepts::sized_range Range>
     BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(Range&& data) noexcept;
 
     // Finalize the calculation of the hash
@@ -59,7 +59,7 @@ namespace boost::crypt {
 
 [[nodiscard]] BOOST_CRYPT_GPU_ENABLED constexpr auto sha256(compat::span<const compat::byte> data) noexcept -> expected<sha256_hasher::return_type, state>;
 
-template <compat::ranges::sized_range SizedRange>
+template <concepts::sized_range SizedRange>
 [[nodiscard]] BOOST_CRYPT_GPU_ENABLED auto sha256(SizedRange&& data) noexcept -> expected<sha256_hasher::return_type, state>;
 
 } // namespace boost::crypt

doc/crypt/sha384.adoc

@@ -33,7 +33,7 @@ public:
     // Process bytes piecewise
     BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(compat::span<const compat::byte> data) noexcept;
 
-    template <compat::ranges::sized_range Range>
+    template <concepts::sized_range Range>
     BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(Range&& data) noexcept;
 
     // Finalize the calculation of the hash
@@ -59,7 +59,7 @@ namespace boost::crypt {
 
 [[nodiscard]] BOOST_CRYPT_GPU_ENABLED constexpr auto sha384(compat::span<const compat::byte> data) noexcept -> expected<sha384_hasher::return_type, state>;
 
-template <compat::ranges::sized_range SizedRange>
+template <concepts::sized_range SizedRange>
 [[nodiscard]] BOOST_CRYPT_GPU_ENABLED auto sha384(SizedRange&& data) noexcept -> expected<sha384_hasher::return_type, state>;
 
 } // namespace boost::crypt

doc/crypt/sha3_224.adoc

@@ -33,7 +33,7 @@ public:
     // Process bytes piecewise
     BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(compat::span<const compat::byte> data) noexcept;
 
-    template <compat::ranges::sized_range Range>
+    template <concepts::sized_range Range>
     BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(Range&& data) noexcept;
 
     // Finalize the calculation of the hash
@@ -59,7 +59,7 @@ namespace boost::crypt {
 
 [[nodiscard]] BOOST_CRYPT_GPU_ENABLED constexpr auto sha3_224(compat::span<const compat::byte> data) noexcept -> expected<sha3_224_hasher::return_type, state>;
 
-template <compat::ranges::sized_range SizedRange>
+template <concepts::sized_range SizedRange>
 [[nodiscard]] BOOST_CRYPT_GPU_ENABLED auto sha3_224(SizedRange&& data) noexcept -> expected<sha3_224_hasher::return_type, state>;
 
 } // namespace boost::crypt

doc/crypt/sha3_256.adoc

@@ -33,7 +33,7 @@ public:
     // Process bytes piecewise
     BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(compat::span<const compat::byte> data) noexcept;
 
-    template <compat::ranges::sized_range Range>
+    template <concepts::sized_range Range>
     BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(Range&& data) noexcept;
 
     // Finalize the calculation of the hash
@@ -59,7 +59,7 @@ namespace boost::crypt {
 
 [[nodiscard]] BOOST_CRYPT_GPU_ENABLED constexpr auto sha3_256(compat::span<const compat::byte> data) noexcept -> expected<sha3_256_hasher::return_type, state>;
 
-template <compat::ranges::sized_range SizedRange>
+template <concepts::sized_range SizedRange>
 [[nodiscard]] BOOST_CRYPT_GPU_ENABLED auto sha3_256(SizedRange&& data) noexcept -> expected<sha3_256_hasher::return_type, state>;
 
 } // namespace boost::crypt

doc/crypt/sha3_384.adoc

@@ -33,7 +33,7 @@ public:
     // Process bytes piecewise
     BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(compat::span<const compat::byte> data) noexcept;
 
-    template <compat::ranges::sized_range Range>
+    template <concepts::sized_range Range>
     BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(Range&& data) noexcept;
 
     // Finalize the calculation of the hash
@@ -59,7 +59,7 @@ namespace boost::crypt {
 
 [[nodiscard]] BOOST_CRYPT_GPU_ENABLED constexpr auto sha3_384(compat::span<const compat::byte> data) noexcept -> expected<sha3_384_hasher::return_type, state>;
 
-template <compat::ranges::sized_range SizedRange>
+template <concepts::sized_range SizedRange>
 [[nodiscard]] BOOST_CRYPT_GPU_ENABLED auto sha3_384(SizedRange&& data) noexcept -> expected<sha3_384_hasher::return_type, state>;
 
 } // namespace boost::crypt

doc/crypt/sha3_512.adoc

@@ -33,7 +33,7 @@ public:
     // Process bytes piecewise
     BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(compat::span<const compat::byte> data) noexcept;
 
-    template <compat::ranges::sized_range Range>
+    template <concepts::sized_range Range>
     BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(Range&& data) noexcept;
 
     // Finalize the calculation of the hash
@@ -59,7 +59,7 @@ namespace boost::crypt {
 
 [[nodiscard]] BOOST_CRYPT_GPU_ENABLED constexpr auto sha3_512(compat::span<const compat::byte> data) noexcept -> expected<sha3_512_hasher::return_type, state>;
 
-template <compat::ranges::sized_range SizedRange>
+template <concepts::sized_range SizedRange>
 [[nodiscard]] BOOST_CRYPT_GPU_ENABLED auto sha3_512(SizedRange&& data) noexcept -> expected<sha3_512_hasher::return_type, state>;
 
 } // namespace boost::crypt

doc/crypt/sha512.adoc

@@ -33,7 +33,7 @@ public:
     // Process bytes piecewise
     BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(compat::span<const compat::byte> data) noexcept;
 
-    template <compat::ranges::sized_range Range>
+    template <concepts::sized_range Range>
     BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(Range&& data) noexcept;
 
     // Finalize the calculation of the hash
@@ -59,7 +59,7 @@ namespace boost::crypt {
 
 [[nodiscard]] BOOST_CRYPT_GPU_ENABLED constexpr auto sha512(compat::span<const compat::byte> data) noexcept -> expected<sha512_hasher::return_type, state>;
 
-template <compat::ranges::sized_range SizedRange>
+template <concepts::sized_range SizedRange>
 [[nodiscard]] BOOST_CRYPT_GPU_ENABLED auto sha512(SizedRange&& data) noexcept -> expected<sha512_hasher::return_type, state>;
 
 } // namespace boost::crypt

doc/crypt/sha512_224.adoc

@@ -33,7 +33,7 @@ public:
     // Process bytes piecewise
     BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(compat::span<const compat::byte> data) noexcept;
 
-    template <compat::ranges::sized_range Range>
+    template <concepts::sized_range Range>
     BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(Range&& data) noexcept;
 
     // Finalize the calculation of the hash
@@ -59,7 +59,7 @@ namespace boost::crypt {
 
 [[nodiscard]] BOOST_CRYPT_GPU_ENABLED constexpr auto sha512_224(compat::span<const compat::byte> data) noexcept -> expected<sha512_224_hasher::return_type, state>;
 
-template <compat::ranges::sized_range SizedRange>
+template <concepts::sized_range SizedRange>
 [[nodiscard]] BOOST_CRYPT_GPU_ENABLED auto sha512_224(SizedRange&& data) noexcept -> expected<sha512_224_hasher::return_type, state>;
 
 } // namespace boost::crypt

doc/crypt/sha512_256.adoc

@@ -33,7 +33,7 @@ public:
     // Process bytes piecewise
     BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(compat::span<const compat::byte> data) noexcept;
 
-    template <compat::ranges::sized_range Range>
+    template <concepts::sized_range Range>
     BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(Range&& data) noexcept;
 
     // Finalize the calculation of the hash
@@ -59,7 +59,7 @@ namespace boost::crypt {
 
 [[nodiscard]] BOOST_CRYPT_GPU_ENABLED constexpr auto sha512_256(compat::span<const compat::byte> data) noexcept -> expected<sha512_256_hasher::return_type, state>;
 
-template <compat::ranges::sized_range SizedRange>
+template <concepts::sized_range SizedRange>
 [[nodiscard]] BOOST_CRYPT_GPU_ENABLED auto sha512_256(SizedRange&& data) noexcept -> expected<sha512_256_hasher::return_type, state>;
 
 } // namespace boost::crypt