////
Copyright 2025 Christian Mazakas
Distributed under the Boost Software License, Version 1.0.
https://www.boost.org/LICENSE_1_0.txt
////

[#ref_sha3]
# <boost/hash2/sha3.hpp>
:idprefix: ref_sha3_

```
#include <boost/hash2/digest.hpp>
#include <boost/hash2/hmac.hpp>

namespace boost {
namespace hash2 {

class sha3_256;
class sha3_224;
class sha3_512;
class sha3_384;

class shake_128;
class shake_256;

using hmac_sha3_256 = hmac<sha3_256>;
using hmac_sha3_224 = hmac<sha3_224>;
using hmac_sha3_512 = hmac<sha3_512>;
using hmac_sha3_384 = hmac<sha3_384>;

} // namespace hash2
} // namespace boost
```

This header implements the https://csrc.nist.gov/pubs/fips/202/final[SHA-3] family of functions.

The fixed-digest hash functions (`sha3_256`, `sha3_224`, `sha3_512`, `sha3_384`) all use the same constants internally and are initialized the same way.
The only differences between them are the size of the message digest and the size of the input block. Otherwise, digests are all gathered in the same way
which is by truncating the bottom portion of the 1600-bit state.

The `shake_128` and `shake_256` functions are similar to the fixed-digest functions except they use a different delimiter to denote finalization of the
digest and extending the output has defined behavior, unlike the default pseudorandom behavior used elsewhere in the library. But they work similarly
in that truncations of the 1600-bit state are returned as the digest.

## sha3_256

```
class sha3_256
{
    using result_type = digest<32>;

    static constexpr std::size_t block_size = 136; // ( 1600 - 2 * 256 ) / 8 => 136

    constexpr sha3_256();
    constexpr explicit sha3_256( std::uint64_t seed );
    sha3_256( void const* p, std::size_t n );
    constexpr sha3_256( unsigned char const* p, std::size_t n );

    void update( void const* p, std::size_t n );
    constexpr void update( unsigned char const* p, std::size_t n );

    constexpr result_type result();
};
```

### Constructors

```
constexpr sha3_256();
```

Default constructor.

Effects: ::
  Initializes the internal state of the SHA3-256 algorithm to its initial values.

```
constexpr explicit sha3_256( std::uint64_t seed );
```

Constructor taking an integer seed value.

Effects: ::
  Initializes the state as if by default construction, then if `seed` is not zero, performs `update(p, 8); result();` where `p` points to a little-endian representation of the value of `seed`.

Remarks: ::
  By convention, if `seed` is zero, the effect of this constructor is the same as default construction.

```
sha3_256( void const* p, std::size_t n );
constexpr sha3_256( unsigned char const* p, std::size_t n );
```

Constructor taking a byte sequence seed.

Effects: ::
  Initializes the state as if by default construction, then if `n` is not zero, performs `update(p, n); result()`.

Remarks: ::
  By convention, if `n` is zero, the effect of this constructor is the same as default construction.

### update

```
void update( void const* p, std::size_t n );
constexpr void update( unsigned char const* p, std::size_t n );
```

Effects: ::
  Updates the internal state of the SHA3-256 algorithm from the byte sequence `[p, p+n)`.

Remarks: ::
  Consecutive calls to `update` are equivalent to a single call with the concatenated byte sequences of the individual calls.

### result

```
constexpr result_type result();
```

Effects: ::
  Pads the accumulated message and finalizes the digest.

Returns: ::
  The leftmost 256 bits of the Keccak-1600 state formed from the byte sequences of the preceding calls to `update`.

Remarks: ::
  Repeated calls to `result()` return a pseudorandom sequence of `result_type` values, effectively extending the output.

## sha3_224

The SHA3-224 algorithm is identical to the SHA3-256 algorithm described above.

The only differences are the size of the input block and the size of the message digest, which is:
```
using result_type = digest<28>;
static constexpr std::size_t block_size = 144; // ( 1600 - 2 * 224 ) / 8 => 144
```

Otherwise, all other operations and constants are identical.

The message digest is obtained by truncating the final results of the Keccak-1600 algorithm to its leftmost 224 bits.

## sha3_512

The SHA3-512 algorithm is identical to the SHA3-256 algorithm described above.

The only differences are the size of the input block and the size of the message digest, which is:
```
using result_type = digest<64>;
static constexpr std::size_t block_size = 72; // ( 1600 - 2 * 512 ) / 8 => 72
```

Otherwise, all other operations and constants are identical.

The message digest is obtained by truncating the final results of the Keccak-1600 algorithm to its leftmost 512 bits.

## sha3_384

The SHA3-384 algorithm is identical to the SHA3-256 algorithm described above.

The only differences are the size of the input block and the size of the message digest, which is:
```
using result_type = digest<48>;
static constexpr std::size_t block_size = 104; // ( 1600 - 2 * 384 ) / 8 => 104
```

Otherwise, all other operations and constants are identical.

The message digest is obtained by truncating the final results of the Keccak-1600 algorithm to its leftmost 384 bits.

## shake_128

```
class shake_128
{
    using result_type = digest<168>;

    static constexpr std::size_t block_size = 168; // ( 1600 - 2 * 128 ) / 8 => 168

    constexpr shake_128();
    constexpr explicit shake_128( std::uint64_t seed );
    shake_128( void const* p, std::size_t n );
    constexpr shake_128( unsigned char const* p, std::size_t n );

    void update( void const* p, std::size_t n );
    constexpr void update( unsigned char const* p, std::size_t n );

    constexpr result_type result();
};
```

### Constructors

```
constexpr shake_128();
```

Default constructor.

Effects: ::
  Initializes the internal state of the SHAKE128 algorithm to its initial values.

```
constexpr explicit shake_128( std::uint64_t seed );
```

Constructor taking an integer seed value.

Effects: ::
  Initializes the state as if by default construction, then if `seed` is not zero, performs `update(p, 8); result();` where `p` points to a little-endian representation of the value of `seed`.

Remarks: ::
  By convention, if `seed` is zero, the effect of this constructor is the same as default construction.

```
shake_128( void const* p, std::size_t n );
constexpr shake_128( unsigned char const* p, std::size_t n );
```

Constructor taking a byte sequence seed.

Effects: ::
  Initializes the state as if by default construction, then if `n` is not zero, performs `update(p, n); result()`.

Remarks: ::
  By convention, if `n` is zero, the effect of this constructor is the same as default construction.

### update

```
void update( void const* p, std::size_t n );
constexpr void update( unsigned char const* p, std::size_t n );
```

Effects: ::
  Updates the internal state of the SHAKE128 algorithm from the byte sequence `[p, p+n)`.

Remarks: ::
  Consecutive calls to `update` are equivalent to a single call with the concatenated byte sequences of the individual calls.

### result

```
constexpr result_type result();
```

Effects: ::
  Pads the accumulated message and finalizes the digest.

Returns: ::
  The truncated portion of the 1600-bit state up to the specified rate `r`, which is the `block_size`, as specified in step 8 of Algorithm 8 in https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf[FIPS 202].

Remarks: ::
  Repeated calls to `result()` extend the output of the hash function in a defined manner. Calling `update()` will reset the current finalization process.

## shake_256

The SHAKE256 algorithm is identical to the SHAKE128 algorithm described above.

The only differences are the size of the input block and the size of the message digest, which is:
```
using result_type = digest<136>;
static constexpr std::size_t block_size = 136; // ( 1600 - 2 * 256 ) / 8 => 136
```

Otherwise, all other operations and constants are identical.

The message digest is similarly extended by repeated `result()` calls and any calls to `update()` reset the finalization process.
