Overview

Description

Boost.Crypt is cryptographic module aiming for FIPS 140-3 certification. The primary goal of this library is to be the safest implemenation, not the fastest.

Warning
 This library is currently uncertified

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

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 11 and later

  • Clang 15 and later

  • Visual Studio 2019 (14.2) 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

Namespace

  • compat Any time you see the namespace compat it is an alias to either std:: or cuda::std:: depending on the compiler being used

Types

  • boost::crypt::expected - either an alias to tl::expected or cuda::std::expected depending on context.

Structures and Classes

Hashers

SHA1
SHA2 Family of Hashers

Enums

Constants

  • None

Concepts

Macros

See: Configuration Macros

State

The state enum class allows you to verify the validity of the state of an 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

  • insufficient_entropy - The input entropy + nonce length is not at least 3/2 security strength

  • out_of_memory - ENOMEM returned by memory allocation

  • requires_reseed - The number of cycles an object has been used exceeded the design amount

  • uninitialized - An object has not been initialized properly before use

  • state_error - A misuse has occurred such as a hasher object was not reinitialized after calling .get_digest(). The simple solution is to call .init() and try again.

namespace boost::crypt {

enum class state
{
    success,                    // no issues
    null,                       // nullptr as parameter
    input_too_long,             // input data too long (exceeded size_t)
    insufficient_entropy,       // Entropy + Nonce length was not at least 3/2 security strength
    out_of_memory,              // Memory exhaustion reported by a function
    requires_reseed,            // The number of cycles has exceeded the specified amount
    uninitialized,              // Random bits can not be provided since the generator is uninitialized
    requested_too_many_bits,    // 2^19 bits is all that's allowed per request
    state_error                 // added more input after get_digest without re-init
};

} // namespace boost::crypt

SHA1

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

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::crypt {

class sha1_hasher
{
public:
    uisng return_type = compat::array<compat::byte, 20>;

    // Initialize the hasher
    BOOST_CRYPT_GPU_ENABLED constexpr void init() noexcept;

    // Process bytes piecewise
    BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(compat::span<const compat::byte> data) noexcept;

    template <compat::ranges::sized_range Range>
    BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(Range&& data) noexcept;

    // Finalize the calculation of the hash
    BOOST_CRYPT_GPU_ENABLED constexpr state finalize() noexcept;

    // Get the digest
    [[nodiscard]] constexpr expected<return_type, state> get_digest() const noexcept;

    [[nodiscard]] BOOST_CRYPT_GPU_ENABLED_CONSTEXPR state get_digest(compat::span<compat::byte> data) const noexcept;

    template <concepts::writable_output_range Range>
    [[nodiscard]] BOOST_CRYPT_GPU_ENABLED state get_digest(Range&& data) const noexcept;
};

} // namespace boost::crypt

One-Shot Hashing Functions

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>
[[nodiscard]] BOOST_CRYPT_GPU_ENABLED auto sha1(SizedRange&& data) noexcept -> expected<sha1_hasher::return_type, state>;

} // namespace boost::crypt

File Hashing Functions

We also have the ability to scan files and return the sha1 value:

namespace boost::crypt {

template <concepts::file_system_path T>
[[nodiscard]] inline auto sha1_file(const T& filepath) -> expected<sha1_hasher::return_type, state>;

} // namespace boost::crypt

SHA224

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

Hashing Object

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.

namespace boost::crypt {

class sha224_hasher
{
public:
    uisng return_type = compat::array<compat::byte, 28>;

    // Initialize the hasher
    BOOST_CRYPT_GPU_ENABLED constexpr void init() noexcept;

    // Process bytes piecewise
    BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(compat::span<const compat::byte> data) noexcept;

    template <compat::ranges::sized_range Range>
    BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(Range&& data) noexcept;

    // Finalize the calculation of the hash
    BOOST_CRYPT_GPU_ENABLED constexpr state finalize() noexcept;

    // Get the digest
    [[nodiscard]] constexpr expected<return_type, state> get_digest() const noexcept;

    [[nodiscard]] BOOST_CRYPT_GPU_ENABLED_CONSTEXPR state get_digest(compat::span<compat::byte> data) const noexcept;

    template <concepts::writable_output_range Range>
    [[nodiscard]] BOOST_CRYPT_GPU_ENABLED state get_digest(Range&& data) const noexcept;
};

} // namespace boost::crypt

One-Shot Hashing Functions

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>
[[nodiscard]] BOOST_CRYPT_GPU_ENABLED auto sha224(SizedRange&& data) noexcept -> expected<sha224_hasher::return_type, state>;

} // namespace boost::crypt

File Hashing Functions

We also have the ability to scan files and return the sha224 value:

namespace boost::crypt {

template <concepts::file_system_path T>
[[nodiscard]] inline auto sha224_file(const T& filepath) -> expected<sha224_hasher::return_type, state>;

} // namespace boost::crypt

SHA256

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

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::crypt {

class sha256_hasher
{
public:
    uisng return_type = compat::array<compat::byte, 32>;

    // Initialize the hasher
    BOOST_CRYPT_GPU_ENABLED constexpr void init() noexcept;

    // Process bytes piecewise
    BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(compat::span<const compat::byte> data) noexcept;

    template <compat::ranges::sized_range Range>
    BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(Range&& data) noexcept;

    // Finalize the calculation of the hash
    BOOST_CRYPT_GPU_ENABLED constexpr state finalize() noexcept;

    // Get the digest
    [[nodiscard]] constexpr expected<return_type, state> get_digest() const noexcept;

    [[nodiscard]] BOOST_CRYPT_GPU_ENABLED_CONSTEXPR state get_digest(compat::span<compat::byte> data) const noexcept;

    template <concepts::writable_output_range Range>
    [[nodiscard]] BOOST_CRYPT_GPU_ENABLED state get_digest(Range&& data) const noexcept;
};

} // namespace boost::crypt

One-Shot Hashing Functions

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>
[[nodiscard]] BOOST_CRYPT_GPU_ENABLED auto sha256(SizedRange&& data) noexcept -> expected<sha256_hasher::return_type, state>;

} // namespace boost::crypt

File Hashing Functions

We also have the ability to scan files and return the sha256 value:

namespace boost::crypt {

template <concepts::file_system_path T>
[[nodiscard]] inline auto sha256_file(const T& filepath) -> expected<sha256_hasher::return_type, state>;

} // namespace boost::crypt

SHA384

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

Hashing Object

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

namespace boost::crypt {

class sha384_hasher
{
public:
    uisng return_type = compat::array<compat::byte, 48>;

    // Initialize the hasher
    BOOST_CRYPT_GPU_ENABLED constexpr void init() noexcept;

    // Process bytes piecewise
    BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(compat::span<const compat::byte> data) noexcept;

    template <compat::ranges::sized_range Range>
    BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(Range&& data) noexcept;

    // Finalize the calculation of the hash
    BOOST_CRYPT_GPU_ENABLED constexpr state finalize() noexcept;

    // Get the digest
    [[nodiscard]] constexpr expected<return_type, state> get_digest() const noexcept;

    [[nodiscard]] BOOST_CRYPT_GPU_ENABLED_CONSTEXPR state get_digest(compat::span<compat::byte> data) const noexcept;

    template <concepts::writable_output_range Range>
    [[nodiscard]] BOOST_CRYPT_GPU_ENABLED state get_digest(Range&& data) const noexcept;
};

} // namespace boost::crypt

One-Shot Hashing Functions

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>
[[nodiscard]] BOOST_CRYPT_GPU_ENABLED auto sha384(SizedRange&& data) noexcept -> expected<sha384_hasher::return_type, state>;

} // namespace boost::crypt

File Hashing Functions

We also have the ability to scan files and return the sha384 value:

namespace boost::crypt {

template <concepts::file_system_path T>
[[nodiscard]] inline auto sha384_file(const T& filepath) -> expected<sha384_hasher::return_type, state>;

} // namespace boost::crypt

SHA512

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

Hashing Object

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

namespace boost::crypt {

class sha512_hasher
{
public:
    uisng return_type = compat::array<compat::byte, 64>;

    // Initialize the hasher
    BOOST_CRYPT_GPU_ENABLED constexpr void init() noexcept;

    // Process bytes piecewise
    BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(compat::span<const compat::byte> data) noexcept;

    template <compat::ranges::sized_range Range>
    BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(Range&& data) noexcept;

    // Finalize the calculation of the hash
    BOOST_CRYPT_GPU_ENABLED constexpr state finalize() noexcept;

    // Get the digest
    [[nodiscard]] constexpr expected<return_type, state> get_digest() const noexcept;

    [[nodiscard]] BOOST_CRYPT_GPU_ENABLED_CONSTEXPR state get_digest(compat::span<compat::byte> data) const noexcept;

    template <concepts::writable_output_range Range>
    [[nodiscard]] BOOST_CRYPT_GPU_ENABLED state get_digest(Range&& data) const noexcept;
};

} // namespace boost::crypt

One-Shot Hashing Functions

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>
[[nodiscard]] BOOST_CRYPT_GPU_ENABLED auto sha512(SizedRange&& data) noexcept -> expected<sha512_hasher::return_type, state>;

} // namespace boost::crypt

File Hashing Functions

We also have the ability to scan files and return the sha512 value:

namespace boost::crypt {

template <concepts::file_system_path T>
[[nodiscard]] inline auto sha512_file(const T& filepath) -> expected<sha512_hasher::return_type, state>;

} // namespace boost::crypt

SHA512_224

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

Hashing Object

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

namespace boost::crypt {

class sha512_224_hasher
{
public:
    uisng return_type = compat::array<compat::byte, 28>;

    // Initialize the hasher
    BOOST_CRYPT_GPU_ENABLED constexpr void init() noexcept;

    // Process bytes piecewise
    BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(compat::span<const compat::byte> data) noexcept;

    template <compat::ranges::sized_range Range>
    BOOST_CRYPT_GPU_ENABLED constexpr state process_bytes(Range&& data) noexcept;

    // Finalize the calculation of the hash
    BOOST_CRYPT_GPU_ENABLED constexpr state finalize() noexcept;

    // Get the digest
    [[nodiscard]] constexpr expected<return_type, state> get_digest() const noexcept;

    [[nodiscard]] BOOST_CRYPT_GPU_ENABLED_CONSTEXPR state get_digest(compat::span<compat::byte> data) const noexcept;

    template <concepts::writable_output_range Range>
    [[nodiscard]] BOOST_CRYPT_GPU_ENABLED state get_digest(Range&& data) const noexcept;
};

} // namespace boost::crypt

One-Shot Hashing Functions

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>
[[nodiscard]] BOOST_CRYPT_GPU_ENABLED auto sha512_224(SizedRange&& data) noexcept -> expected<sha512_224_hasher::return_type, state>;

} // namespace boost::crypt

File Hashing Functions

We also have the ability to scan files and return the sha512_224 value:

namespace boost::crypt {

template <concepts::file_system_path T>
[[nodiscard]] inline auto sha512_224_file(const T& filepath) -> expected<sha512_224_hasher::return_type, state>;

} // namespace boost::crypt

Concepts

The following are the defintions of the concepts used throughout the library to ensure consistency.

File System Path

Used for the one-shot hashing of files. Allows a diverse range of ways to specify the file path. This concept is disabled on CUDA because there is no std::ifstream on that platform.

namespace boost::crypt::concepts {

#ifndef BOOST_CRYPT_HAS_CUDA

template <typename T>
concept file_system_path =
    std::is_convertible_v<T, std::string> ||
    std::is_convertible_v<T, std::string_view> ||
    std::is_convertible_v<T, const char*> ||
    std::is_same_v<std::remove_cvref_t<T>, std::filesystem::path> ||
    std::is_same_v<std::remove_cvref_t<T>, char*>;

#endif

} // namespace boost::crypt::concepts

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.

namespace boost::crypt::concepts {

template <typename Range>
concept writable_output_range = compat::output_range<Range, compat::range_value_t<Range>> &&
                                compat::sized_range<Range> &&
                                compat::is_trivially_copyable_v<compat::range_value_t<Range>>;

} // namespace boost::crypt::concepts

Configuration Macros

User Configurable Macros

  • None at this time

Automatic Configuration Macros

  • BOOST_CRYPT_HAS_CUDA: This is defined when compiling with NVCC regardless of the host compiler.

References

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

This documentation is copyright 2024 - 2025 Matt Borland and Chris Kormanyos and is distributed under the Boost Software License, Version 1.0.