Merge pull request #91 from cppalliance/docs

Update docs with SHA2 and 3
cppalliance · Nov 6, 2024 · 9811cb3 · 9811cb3
2 parents 11695ef + 28fa6f5
commit 9811cb3
Show file tree

Hide file tree

Showing 7 changed files with 805 additions and 0 deletions.
diff --git a/doc/crypt.adoc b/doc/crypt.adoc
@@ -25,6 +25,8 @@ include::crypt/md5.adoc[]
 
 include::crypt/sha1.adoc[]
 
+include::crypt/sha224.adoc[]
+
 include::crypt/sha256.adoc[]
 
 include::crypt/sha384.adoc[]
@@ -35,6 +37,14 @@ include::crypt/sha512_224.adoc[]
 
 include::crypt/sha512_256.adoc[]
 
+include::crypt/sha3_224.adoc[]
+
+include::crypt/sha3_256.adoc[]
+
+include::crypt/sha3_384.adoc[]
+
+include::crypt/sha3_512.adoc[]
+
 include::crypt/config.adoc[]
 
 include::crypt/reference.adoc[]

diff --git a/doc/crypt/api_reference.adoc b/doc/crypt/api_reference.adoc
@@ -15,13 +15,23 @@ https://www.boost.org/LICENSE_1_0.txt
 == Structures and Classes
 
 - <<md5_hasher, `md5_hasher`>>
+
 - <<sha1_hasher, `sha1_hasher`>>
+
+=== SHA2 Family
+- <<sha224_hasher, `sha224_hasher`>>
 - <<sha256_hasher, `sha256_hasher`>>
 - <<sha384_hasher, `sha384_hasher`>>
 - <<sha512_hasher, `sha512_hasher`>>
 - <<sha512_224_hasher, `sha512_224_hasher`>>
 - <<sha512_256_hasher, `sha512_256_hasher`>>
 
+=== SHA3 Family
+- <<sha3_224_hasher, `sha3_224_hasher`>>
+- <<sha3_256_hasher, `sha3_256_hasher`>>
+- <<sha3_384_hasher, `sha3_384_hasher`>>
+- <<sha3_512_hasher, `sha3_512_hasher`>>
+
 == Enums
 
 - <<hasher_state, `hasher_state`>>

diff --git a/doc/crypt/sha224.adoc b/doc/crypt/sha224.adoc
@@ -0,0 +1,157 @@
+////
+Copyright 2024 Matt Borland
+Distributed under the Boost Software License, Version 1.0.
+https://www.boost.org/LICENSE_1_0.txt
+////
+
+[#sha224]
+:idprefix: sha224_
+
+= SHA224
+
+This library supports sha224 as described in https://datatracker.ietf.org/doc/html/rfc6234[RFC 6234].
+There is a wide range of acceptable inputs for the base sha224 function:
+
+== Hashing Functions
+
+[source, c++]
+----
+namespace boost {
+namespace crypt {
+
+uisng return_type = boost::crypt::array<uint8_t, 32>;
+
+BOOST_CRYPT_GPU_ENABLED inline auto sha224(const char* str) noexcept -> return_type;
+
+BOOST_CRYPT_GPU_ENABLED inline auto sha224(const char* str, size_t len) noexcept -> return_type;
+
+BOOST_CRYPT_GPU_ENABLED inline auto sha224(const unsigned char* str) noexcept -> return_type;
+
+BOOST_CRYPT_GPU_ENABLED inline auto sha224(const unsigned char* str, size_t len) noexcept -> return_type;
+
+BOOST_CRYPT_GPU_ENABLED inline auto sha224(const char16_t* str) noexcept -> return_type;
+
+BOOST_CRYPT_GPU_ENABLED inline auto sha224(const char16_t* str, size_t len) noexcept -> return_type;
+
+BOOST_CRYPT_GPU_ENABLED inline auto sha224(const char32_t* str) noexcept -> return_type;
+
+BOOST_CRYPT_GPU_ENABLED inline auto sha224(const char32_t* str, size_t len) noexcept -> return_type;
+
+BOOST_CRYPT_GPU_ENABLED inline auto sha224(const wchar_t* str) noexcept -> return_type;
+
+BOOST_CRYPT_GPU_ENABLED inline auto sha224(const wchar_t* str, size_t len) noexcept -> return_type;
+
+inline auto sha224(const std::string& str) noexcept -> return_type;
+
+inline auto sha224(const std::u16string& str) noexcept -> return_type;
+
+inline auto sha224(const std::u32string& str) noexcept -> return_type;
+
+inline auto sha224(const std::wstring& str) noexcept -> return_type;
+
+#ifdef BOOST_CRYPT_HAS_STRING_VIEW
+
+inline auto sha224(std::string_view str) noexcept -> return_type;
+
+inline auto sha224(std::u16string_view str) noexcept -> return_type;
+
+inline auto sha224(std::u32string_view str) noexcept -> return_type;
+
+inline auto sha224(std::wstring_view str) noexcept -> return_type;
+
+#endif // BOOST_CRYPT_HAS_STRING_VIEW
+
+#ifdef BOOST_CRYPT_HAS_SPAN
+
+template <typename T, std::size_t extent>
+inline auto md5(std::span<T, extent> data) noexcept -> return_type;
+
+#endif // BOOST_CRYPT_HAS_SPAN
+
+#ifdef BOOST_CRYPT_HAS_CUDA
+
+template <typename T, boost::crypt::size_t extent>
+BOOST_CRYPT_GPU_ENABLED inline auto md5(cuda::std::span<T, extent> data) noexcept -> return_type;
+
+#endif // BOOST_CRYPT_HAS_CUDA
+
+} //namespace crypt
+} //namespace boost
+----
+
+== File Hashing Functions
+
+We also have the ability to scan files and return the sha224 value:
+
+[source, c++]
+----
+namespace boost {
+namespace crypt {
+
+uisng return_type = boost::crypt::array<uint8_t, 32>;
+
+inline auto sha224_file(const char* filepath) noexcept -> return_type;
+
+inline auto sha224_file(const std::string& filepath) noexcept -> return_type;
+
+inline auto sha224_file(std::string_view filepath) noexcept -> return_type;
+
+} // namespace crypt
+} // namespace boost
+----
+
+== Hashing Object
+
+[#sha224_hasher]
+Lastly, there is also the ability to create a sha224 hashing object and feed it bytes as the user parses them.
+This class does not use any dynamic memory allocation.
+
+[source, c++]
+----
+namespace boost {
+namespace crypt {
+
+class sha224_hasher
+{
+    uisng return_type = boost::crypt::array<uint8_t, 32>;
+
+    void init();
+
+    template <typename ByteType>
+    BOOST_CRYPT_GPU_ENABLED inline auto process_byte(ByteType byte) noexcept -> hasher_state;
+
+    template <typename ForwardIter>
+    BOOST_CRYPT_GPU_ENABLED inline auto process_bytes(ForwardIter buffer, size_t byte_count) noexcept -> hasher_state;
+
+    #ifdef BOOST_CRYPT_HAS_STRING_VIEW
+
+    inline auto process_bytes(std::string_view str) noexcept -> hasher_state;
+
+    inline auto process_bytes(std::u16string_view str) noexcept -> hasher_state;
+
+    inline auto process_bytes(std::u32string_view str) noexcept -> hasher_state;
+
+    inline auto process_bytes(std::wstring_view str) noexcept -> hasher_state;
+
+    #endif // BOOST_CRYPT_HAS_STRING_VIEW
+
+    #ifdef BOOST_CRYPT_HAS_SPAN
+
+    template <typename T, boost::crypt::size_t extent>
+    inline auto process_bytes(std::span<T, extent> data) noexcept -> hasher_state;
+
+    #endif // BOOST_CRYPT_HAS_SPAN
+
+    #ifdef BOOST_CRYPT_HAS_CUDA
+
+    template <typename T, boost::crypt::size_t extent>
+    BOOST_CRYPT_GPU_ENABLED inline auto process_bytes(cuda::std::span<T, extent> data) noexcept -> hasher_state;
+
+    #endif // BOOST_CRYPT_HAS_CUDA
+
+    inline auto get_digest() noexcept -> return_type;
+};
+
+} // namespace crypt
+} // namespace boost
+----
diff --git a/doc/crypt/sha3_224.adoc b/doc/crypt/sha3_224.adoc
@@ -0,0 +1,157 @@
+////
+Copyright 2024 Matt Borland
+Distributed under the Boost Software License, Version 1.0.
+https://www.boost.org/LICENSE_1_0.txt
+////
+
+[#sha3_224]
+:idprefix: sha3_224_
+
+= SHA3_224
+
+This library supports sha3_224 as described in https://doi.org/10.6028/NIST.FIPS.202[SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions].
+There is a wide range of acceptable inputs for the base sha3_224 function:
+
+== Hashing Functions
+
+[source, c++]
+----
+namespace boost {
+namespace crypt {
+
+uisng return_type = boost::crypt::array<uint8_t, 28>;
+
+BOOST_CRYPT_GPU_ENABLED inline auto sha3_224(const char* str) noexcept -> return_type;
+
+BOOST_CRYPT_GPU_ENABLED inline auto sha3_224(const char* str, size_t len) noexcept -> return_type;
+
+BOOST_CRYPT_GPU_ENABLED inline auto sha3_224(const unsigned char* str) noexcept -> return_type;
+
+BOOST_CRYPT_GPU_ENABLED inline auto sha3_224(const unsigned char* str, size_t len) noexcept -> return_type;
+
+BOOST_CRYPT_GPU_ENABLED inline auto sha3_224(const char16_t* str) noexcept -> return_type;
+
+BOOST_CRYPT_GPU_ENABLED inline auto sha3_224(const char16_t* str, size_t len) noexcept -> return_type;
+
+BOOST_CRYPT_GPU_ENABLED inline auto sha3_224(const char32_t* str) noexcept -> return_type;
+
+BOOST_CRYPT_GPU_ENABLED inline auto sha3_224(const char32_t* str, size_t len) noexcept -> return_type;
+
+BOOST_CRYPT_GPU_ENABLED inline auto sha3_224(const wchar_t* str) noexcept -> return_type;
+
+BOOST_CRYPT_GPU_ENABLED inline auto sha3_224(const wchar_t* str, size_t len) noexcept -> return_type;
+
+inline auto sha3_224(const std::string& str) noexcept -> return_type;
+
+inline auto sha3_224(const std::u16string& str) noexcept -> return_type;
+
+inline auto sha3_224(const std::u32string& str) noexcept -> return_type;
+
+inline auto sha3_224(const std::wstring& str) noexcept -> return_type;
+
+#ifdef BOOST_CRYPT_HAS_STRING_VIEW
+
+inline auto sha3_224(std::string_view str) noexcept -> return_type;
+
+inline auto sha3_224(std::u16string_view str) noexcept -> return_type;
+
+inline auto sha3_224(std::u32string_view str) noexcept -> return_type;
+
+inline auto sha3_224(std::wstring_view str) noexcept -> return_type;
+
+#endif // BOOST_CRYPT_HAS_STRING_VIEW
+
+#ifdef BOOST_CRYPT_HAS_SPAN
+
+template <typename T, std::size_t extent>
+inline auto md5(std::span<T, extent> data) noexcept -> return_type;
+
+#endif // BOOST_CRYPT_HAS_SPAN
+
+#ifdef BOOST_CRYPT_HAS_CUDA
+
+template <typename T, boost::crypt::size_t extent>
+BOOST_CRYPT_GPU_ENABLED inline auto md5(cuda::std::span<T, extent> data) noexcept -> return_type;
+
+#endif // BOOST_CRYPT_HAS_CUDA
+
+} //namespace crypt
+} //namespace boost
+----
+
+== File Hashing Functions
+
+We also have the ability to scan files and return the sha3_224 value:
+
+[source, c++]
+----
+namespace boost {
+namespace crypt {
+
+uisng return_type = boost::crypt::array<uint8_t, 28>;
+
+inline auto sha3_224_file(const char* filepath) noexcept -> return_type;
+
+inline auto sha3_224_file(const std::string& filepath) noexcept -> return_type;
+
+inline auto sha3_224_file(std::string_view filepath) noexcept -> return_type;
+
+} // namespace crypt
+} // namespace boost
+----
+
+== Hashing Object
+
+[#sha3_224_hasher]
+Lastly, there is also the ability to create a sha3_224 hashing object and feed it bytes as the user parses them.
+This class does not use any dynamic memory allocation.
+
+[source, c++]
+----
+namespace boost {
+namespace crypt {
+
+class sha3_224_hasher
+{
+    uisng return_type = boost::crypt::array<uint8_t, 28>;
+
+    void init();
+
+    template <typename ByteType>
+    BOOST_CRYPT_GPU_ENABLED inline auto process_byte(ByteType byte) noexcept -> hasher_state;
+
+    template <typename ForwardIter>
+    BOOST_CRYPT_GPU_ENABLED inline auto process_bytes(ForwardIter buffer, size_t byte_count) noexcept -> hasher_state;
+
+    #ifdef BOOST_CRYPT_HAS_STRING_VIEW
+
+    inline auto process_bytes(std::string_view str) noexcept -> hasher_state;
+
+    inline auto process_bytes(std::u16string_view str) noexcept -> hasher_state;
+
+    inline auto process_bytes(std::u32string_view str) noexcept -> hasher_state;
+
+    inline auto process_bytes(std::wstring_view str) noexcept -> hasher_state;
+
+    #endif // BOOST_CRYPT_HAS_STRING_VIEW
+
+    #ifdef BOOST_CRYPT_HAS_SPAN
+
+    template <typename T, boost::crypt::size_t extent>
+    inline auto process_bytes(std::span<T, extent> data) noexcept -> hasher_state;
+
+    #endif // BOOST_CRYPT_HAS_SPAN
+
+    #ifdef BOOST_CRYPT_HAS_CUDA
+
+    template <typename T, boost::crypt::size_t extent>
+    BOOST_CRYPT_GPU_ENABLED inline auto process_bytes(cuda::std::span<T, extent> data) noexcept -> hasher_state;
+
+    #endif // BOOST_CRYPT_HAS_CUDA
+
+    inline auto get_digest() noexcept -> return_type;
+};
+
+} // namespace crypt
+} // namespace boost
+----