Crypt: A Modern Cryptographic Module in C++14

Overview

Description

Boost.Crypt is cryptographic module aiming for FIPS 140-3 certification.

Warning

This library is currently uncertified

The library is header-only, has no dependencies, and requires C++14.

Motivation

This library will be a ground-up, modern, and memory safe implementation of standard cryptographic routines. Since it is header only and has no dependencies it is trivial to integrate into any project. It also offers native CUDA support to massively parallelize these routines (such as hashing thousands of files simultaneously)

Use Cases

Anywhere where security is needed.

Supported Compilers

Boost.Crypt is tested natively on Ubuntu (x86_64, s390x, and aarch64), macOS (x86_64, and Apple Silicon), and Windows (x32 and x64); as well as emulated PPC64LE and STM32 using QEMU with the following compilers:

GCC 7 and later
Clang 6 and later
Visual Studio 2017 and later
Intel OneAPI DPC++ 2024.2 and later
CUDA Toolkit 12.5 and later (Both NVCC and NVRTC)

Tested on Github Actions and Drone. Coverage can be found on Codecov.

API Reference

Constants

None

Macros

See: Configuration Macros

Hasher State

The hasher state enum class allows you to verify the validity of the state of a hasher object. The following are the possible states:

success - The hasher is proceeding without issue
null - A null pointer was passed to hasher
input_too_long - The number of bytes passed to the hasher object has exceeded the range of size_t
state_error - This occurs if hasher object was not reinitialized after calling .get_digest(). The simple solution is to call .init() and try again.

namespace boost {
namespace crypt {

enum class hasher_state : boost::crypt::uint8_t
{
    success,            // no issues
    null,               // nullptr as parameter
    input_too_long,     // input data too long (exceeded size_t)
    state_error         // added more input after get_digest without re-init
};

} // namespace crypt
} // namespace boost

MD5

This library supports MD5 as described in RFC 1321. There is a wide range of acceptable inputs for the base md5 function:

Hashing Functions

namespace boost {
namespace crypt {

uisng return_type = boost::crypt::array<uint8_t, 16>;

BOOST_CRYPT_GPU_ENABLED constexpr auto md5(const char* str) noexcept -> return_type;

BOOST_CRYPT_GPU_ENABLED constexpr auto md5(const char* str, size_t len) noexcept -> return_type;

BOOST_CRYPT_GPU_ENABLED constexpr auto md5(const unsigned char* str) noexcept -> return_type;

BOOST_CRYPT_GPU_ENABLED constexpr auto md5(const unsigned char* str, size_t len) noexcept -> return_type;

BOOST_CRYPT_GPU_ENABLED constexpr auto md5(const char16_t* str) noexcept -> return_type;

BOOST_CRYPT_GPU_ENABLED constexpr auto md5(const char16_t* str, size_t len) noexcept -> return_type;

BOOST_CRYPT_GPU_ENABLED constexpr auto md5(const char32_t* str) noexcept -> return_type;

BOOST_CRYPT_GPU_ENABLED constexpr auto md5(const char32_t* str, size_t len) noexcept -> return_type;

BOOST_CRYPT_GPU_ENABLED constexpr auto md5(const wchar_t* str) noexcept -> return_type;

BOOST_CRYPT_GPU_ENABLED constexpr auto md5(const wchar_t* str, size_t len) noexcept -> return_type;

inline auto md5(const std::string& str) noexcept -> return_type;

inline auto md5(const std::u16string& str) noexcept -> return_type;

inline auto md5(const std::u32string& str) noexcept -> return_type;

inline auto md5(const std::wstring& str) noexcept -> return_type;

#ifdef BOOST_CRYPT_HAS_STRING_VIEW

inline auto md5(std::string_view str) noexcept -> return_type;

inline auto md5(std::u16string_view str) noexcept -> return_type;

inline auto md5(std::u32string_view str) noexcept -> return_type;

inline auto md5(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>
constexpr 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 constexpr 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 MD5 value:

namespace boost {
namespace crypt {

uisng return_type = boost::crypt::array<uint8_t, 16>;

inline auto md5_file(const char* filepath) noexcept -> return_type;

inline auto md5_file(const std::string& filepath) noexcept -> return_type;

inline auto md5_file(std::string_view filepath) noexcept -> return_type;

} // namespace crypt
} // namespace boost

Hashing Object

Lastly, there is also the ability to create a MD5 hashing object and feed it bytes as the user parses them. This class does not use any dynamic memory allocation.

namespace boost {
namespace crypt {

class md5_hasher
{
    uisng return_type = boost::crypt::array<uint8_t, 16>;

    void init();

    template <typename ByteType>
    BOOST_CRYPT_GPU_ENABLED constexpr auto process_byte(ByteType byte) noexcept -> hasher_state;

    template <typename ForwardIter>
    BOOST_CRYPT_GPU_ENABLED constexpr auto process_bytes(ForwardIter buffer, size_t byte_count) noexcept -> hasher_state;

    constexpr auto get_digest() noexcept -> return_type;
};

} // namespace crypt
} // namespace boost

SHA1

This library supports SHA1 as described in RFC 3174. There is a wide range of acceptable inputs for the base sha1 function:

Hashing Functions

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

#ifdef BOOST_CRYPT_HAS_SPAN

template <typename T, std::size_t extent>
constexpr 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 constexpr 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 sha1 value:

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

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.

namespace boost {
namespace crypt {

class sha1_hasher
{
    uisng return_type = boost::crypt::array<uint8_t, 20>;

    void init();

    template <typename ByteType>
    BOOST_CRYPT_GPU_ENABLED constexpr auto process_byte(ByteType byte) noexcept -> hasher_state;

    template <typename ForwardIter>
    BOOST_CRYPT_GPU_ENABLED constexpr auto process_bytes(ForwardIter buffer, size_t byte_count) noexcept -> hasher_state;

    constexpr auto get_digest() noexcept -> boost::crypt::array<boost::crypt::uint8_t, 20>;
};

} // namespace crypt
} // namespace boost

SHA256

This library supports sha256 as described in RFC 6234. There is a wide range of acceptable inputs for the base sha256 function:

Hashing Functions

namespace boost {
namespace crypt {

uisng return_type = boost::crypt::array<uint8_t, 32>;

BOOST_CRYPT_GPU_ENABLED constexpr auto sha256(const char* str) noexcept -> return_type;

BOOST_CRYPT_GPU_ENABLED constexpr auto sha256(const char* str, size_t len) noexcept -> return_type;

BOOST_CRYPT_GPU_ENABLED constexpr auto sha256(const unsigned char* str) noexcept -> return_type;

BOOST_CRYPT_GPU_ENABLED constexpr auto sha256(const unsigned char* str, size_t len) noexcept -> return_type;

BOOST_CRYPT_GPU_ENABLED constexpr auto sha256(const char16_t* str) noexcept -> return_type;

BOOST_CRYPT_GPU_ENABLED constexpr auto sha256(const char16_t* str, size_t len) noexcept -> return_type;

BOOST_CRYPT_GPU_ENABLED constexpr auto sha256(const char32_t* str) noexcept -> return_type;

BOOST_CRYPT_GPU_ENABLED constexpr auto sha256(const char32_t* str, size_t len) noexcept -> return_type;

BOOST_CRYPT_GPU_ENABLED constexpr auto sha256(const wchar_t* str) noexcept -> return_type;

BOOST_CRYPT_GPU_ENABLED constexpr auto sha256(const wchar_t* str, size_t len) noexcept -> return_type;

inline auto sha256(const std::string& str) noexcept -> return_type;

inline auto sha256(const std::u16string& str) noexcept -> return_type;

inline auto sha256(const std::u32string& str) noexcept -> return_type;

inline auto sha256(const std::wstring& str) noexcept -> return_type;

#ifdef BOOST_CRYPT_HAS_STRING_VIEW

inline auto sha256(std::string_view str) noexcept -> return_type;

inline auto sha256(std::u16string_view str) noexcept -> return_type;

inline auto sha256(std::u32string_view str) noexcept -> return_type;

inline auto sha256(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>
constexpr 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 constexpr 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 sha256 value:

namespace boost {
namespace crypt {

uisng return_type = boost::crypt::array<uint8_t, 16>;

inline auto sha256_file(const char* filepath) noexcept -> return_type;

inline auto sha256_file(const std::string& filepath) noexcept -> return_type;

inline auto sha256_file(std::string_view filepath) noexcept -> return_type;

} // namespace crypt
} // namespace boost

Hashing Object

Lastly, there is also the ability to create a sha256 hashing object and feed it bytes as the user parses them. This class does not use any dynamic memory allocation.

namespace boost {
namespace crypt {

class sha256_hasher
{
    uisng return_type = boost::crypt::array<uint8_t, 32>;

    void init();

    template <typename ByteType>
    BOOST_CRYPT_GPU_ENABLED constexpr auto process_byte(ByteType byte) noexcept -> hasher_state;

    template <typename ForwardIter>
    BOOST_CRYPT_GPU_ENABLED constexpr auto process_bytes(ForwardIter buffer, size_t byte_count) noexcept -> hasher_state;

    constexpr auto get_digest() noexcept -> return_type;
};

} // namespace crypt
} // namespace boost

Configuration Macros

User Configurable Macros

The following configuration macros are available:

None at this time

Automatic Configuration Macros

BOOST_CRYPT_HAS_STRING_VIEW: This is defined when compiling with at least C++17 and your standard library has a complete implementation of <string_view>.
BOOST_CRYPT_HAS_SPAN: This is defined when compiling with at least C++20 and your standard library has a complete implementation of <span>.
BOOST_CRYPT_HAS_CUDA: This is defined when compiling with either NVCC or NVRTC regardless of the host compiler.

References

The following books, papers and blog posts serve as the basis for the algorithms used in the library:

Ronald L. Rivest, RFC 1321: The MD5 Message-Digest Algorithm, 1992
Donald E. Eastlake and Paul E. Jones, RFC 3174: US Secure Hash Algorithm 1 (SHA1), 2001

Crypt: A Modern Cryptographic Module in C++14

Overview

Description

Motivation

Use Cases

Supported Compilers

API Reference

Types

Structures and Classes

Enums

Constants

Macros

Hasher State

MD5

Hashing Functions

File Hashing Functions

Hashing Object

SHA1

Hashing Functions

File Hashing Functions

Hashing Object

SHA256

Hashing Functions

File Hashing Functions

Hashing Object

Configuration Macros

User Configurable Macros

Automatic Configuration Macros

References

Copyright and License