From 901d293146654e078b6fe3016f57ec957f29c1b9 Mon Sep 17 00:00:00 2001
From: Matt Borland <matt@mattborland.com>
Date: Thu, 17 Oct 2024 15:44:48 -0400
Subject: [PATCH] Add SHA1 documentation

---
 doc/crypt.adoc           |   2 +
 doc/crypt/reference.adoc |   2 +
 doc/crypt/sha1.adoc      | 115 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 119 insertions(+)
 create mode 100644 doc/crypt/sha1.adoc

diff --git a/doc/crypt.adoc b/doc/crypt.adoc
index 093e482..28eb78f 100644
--- a/doc/crypt.adoc
+++ b/doc/crypt.adoc
@@ -21,6 +21,8 @@ include::crypt/api_reference.adoc[]
 
 include::crypt/md5.adoc[]
 
+include::crypt/sha1.adoc[]
+
 include::crypt/config.adoc[]
 
 include::crypt/reference.adoc[]
diff --git a/doc/crypt/reference.adoc b/doc/crypt/reference.adoc
index 87d49fc..844bce8 100644
--- a/doc/crypt/reference.adoc
+++ b/doc/crypt/reference.adoc
@@ -13,3 +13,5 @@ The following books, papers and blog posts serve as the basis for the algorithms
 :linkattrs:
 
 - Ronald L. Rivest, https://www.ietf.org/rfc/rfc1321.txt[RFC 1321:  The MD5 Message-Digest Algorithm], 1992
+
+- Donald E. Eastlake and Paul E. Jones, https://datatracker.ietf.org/doc/html/rfc3174[RFC 3174:  US Secure Hash Algorithm 1 (SHA1)], 2001
diff --git a/doc/crypt/sha1.adoc b/doc/crypt/sha1.adoc
new file mode 100644
index 0000000..0e55346
--- /dev/null
+++ b/doc/crypt/sha1.adoc
@@ -0,0 +1,115 @@
+////
+Copyright 2024 Matt Borland
+Distributed under the Boost Software License, Version 1.0.
+https://www.boost.org/LICENSE_1_0.txt
+////
+
+[#sha1]
+:idprefix: sha1_
+
+= SHA1
+
+This library supports SHA1 as described in https://datatracker.ietf.org/doc/html/rfc3174[RFC 3174].
+There is a wide range of acceptable inputs for the base sha1 function:
+
+== Hashing Functions
+
+[source, c++]
+----
+namespace boost {
+namespace crypt {
+
+uisng return_type = boost::crypt::array<uint8_t, 20>;
+
+BOOST_CRYPT_GPU_ENABLED constexpr auto sha1(const char* str) noexcept -> return_type;
+
+BOOST_CRYPT_GPU_ENABLED constexpr auto sha1(const char* str, size_t len) noexcept -> return_type;
+
+BOOST_CRYPT_GPU_ENABLED constexpr auto sha1(const unsigned char* str) noexcept -> return_type;
+
+BOOST_CRYPT_GPU_ENABLED constexpr auto sha1(const unsigned char* str, size_t len) noexcept -> return_type;
+
+BOOST_CRYPT_GPU_ENABLED constexpr auto sha1(const char16_t* str) noexcept -> return_type;
+
+BOOST_CRYPT_GPU_ENABLED constexpr auto sha1(const char16_t* str, size_t len) noexcept -> return_type;
+
+BOOST_CRYPT_GPU_ENABLED constexpr auto sha1(const char32_t* str) noexcept -> return_type;
+
+BOOST_CRYPT_GPU_ENABLED constexpr auto sha1(const char32_t* str, size_t len) noexcept -> return_type;
+
+BOOST_CRYPT_GPU_ENABLED constexpr auto sha1(const wchar_t* str) noexcept -> return_type;
+
+BOOST_CRYPT_GPU_ENABLED constexpr auto sha1(const wchar_t* str, size_t len) noexcept -> return_type;
+
+inline auto sha1(const std::string& str) noexcept -> return_type;
+
+inline auto sha1(const std::u16string& str) noexcept -> return_type;
+
+inline auto sha1(const std::u32string& str) noexcept -> return_type;
+
+inline auto sha1(const std::wstring& str) noexcept -> return_type;
+
+#ifdef BOOST_CRYPT_HAS_STRING_VIEW
+
+inline auto sha1(std::string_view str) noexcept -> return_type;
+
+inline auto sha1(std::u16string_view str) noexcept -> return_type;
+
+inline auto sha1(std::u32string_view str) noexcept -> return_type;
+
+inline auto sha1(std::wstring_view str) noexcept -> return_type;
+
+#endif // BOOST_CRYPT_HAS_STRING_VIEW
+
+} //namespace crypt
+} //namespace boost
+----
+
+== File Hashing Functions
+
+We also have the ability to scan files and return the sha1 value:
+
+[source, c++]
+----
+namespace boost {
+namespace crypt {
+
+uisng return_type = boost::crypt::array<uint8_t, 16>;
+
+inline auto sha1_file(const char* filepath) noexcept -> return_type;
+
+inline auto sha1_file(const std::string& filepath) noexcept -> return_type;
+
+inline auto sha1_file(std::string_view filepath) noexcept -> return_type;
+
+} // namespace crypt
+} // namespace boost
+----
+
+== Hashing Object
+
+[#sha1_hasher]
+Lastly, there is also the ability to create a sha1 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 sha1_hasher
+{
+    init();
+
+    template <typename ByteType>
+    BOOST_CRYPT_GPU_ENABLED constexpr auto process_byte(ByteType byte) noexcept -> void;
+
+    template <typename ForwardIter>
+    BOOST_CRYPT_GPU_ENABLED constexpr auto process_bytes(ForwardIter buffer, size_t byte_count) noexcept -> void;
+
+    constexpr auto get_digest() noexcept -> boost::crypt::array<boost::crypt::uint8_t, 20>;
+};
+
+} // namespace crypt
+} // namespace boost
+----