libdecaf_sha3 (libdecaf v3.0.0)

This module is deprecated. Use libdecaf:hash/2, libdecaf:hash_init/1, libdecaf:hash_update/2, and libdecaf:hash_final/1. For SHAKE, use libdecaf:xof/3 and libdecaf:xof_init/1, libdecaf:xof_absorb/2, and libdecaf:xof_squeeze/2..

Deprecated compatibility API for SHA-3 and SHAKE with tagged, immutable states.

New code should use libdecaf:hash/2, libdecaf:hash_init/1, libdecaf:hash_update/2, and libdecaf:hash_final/1 directly. For SHAKE, use libdecaf:xof/3, libdecaf:xof_init/1, libdecaf:xof_absorb/2, and libdecaf:xof_squeeze/2.

This compatibility module keeps {Algorithm, NativeState} wrapped states. Updates return a new state; existing states remain reusable. The new API returns opaque states directly. See the migration guide.

Fixed-output algorithms and their default digest lengths:

sha3_224: 28 bytes.
sha3_256: 32 bytes.
sha3_384: 48 bytes.
sha3_512: 64 bytes.

SHAKE algorithms are shake128, shake256. They require an explicit output length with hash/3, xof/3, or final/2; hash/2 and final/1 accept only fixed-output hashes.

Lengths are in bytes. Fixed-output hashes allow truncation from zero bytes through the algorithm's maximum digest length. Input accepts iodata.

For example, the replacement incremental API needs no wrapper:

State0 = libdecaf:hash_init(sha3_224),
State1 = libdecaf:hash_update(State0, [<<"a">>, <<"bc">>]),
Digest = libdecaf:hash_final(State1),
Digest = libdecaf:hash(sha3_224, <<"abc">>).

Summary

Types

algorithm()

Algorithms accepted by this compatibility module.

hash_algorithm()

Fixed-output algorithms supported by this module.

hash_state()

A legacy {Algorithm, NativeState} tuple for a fixed-output hash.

state()

An immutable tagged hash or SHAKE state returned by init/1 or update/2.

xof_algorithm()

SHAKE algorithms accepted by hash/3, xof/3, and init/1.

xof_state()

A legacy {Algorithm, NativeState} tuple for SHAKE.

Functions

final(State) deprecated

Return a fixed-output digest using the algorithm's default length. The wrapped state remains reusable. SHAKE requires final/2.

final(State, Length) deprecated

Return Length bytes without changing the wrapped state. Fixed-output hashes return a digest prefix and reject lengths above their maximum. SHAKE accepts any nonnegative output length.

hash(Type, Data) deprecated

Hash iodata using the algorithm's default digest length. SHAKE requires an explicit output length with hash/3 or xof/3.

hash(Type, Data, Length) deprecated

Hash iodata and return exactly Length bytes. Fixed-output hashes allow truncation up to their maximum digest length. SHAKE produces the requested number of XOF bytes, including zero.

init(Type) deprecated

Initialize an immutable {Type, NativeState} tuple. Pass the returned tuple to update/2 and final/1,2 in this module. SHAKE states can only be finalized with an explicit output length.

update(State, Data) deprecated

Absorb iodata and return a new {Algorithm, NativeState} tuple. The algorithm tag is preserved and the input tuple remains reusable.

xof(Type, Data, Length) deprecated

Return Length SHAKE bytes from iodata in one call. This preserves the historical xof/3 alias for SHAKE through hash/3.

Types

algorithm()

-type algorithm() :: hash_algorithm() | xof_algorithm().

Algorithms accepted by this compatibility module.

hash_algorithm()

-type hash_algorithm() :: sha3_224 | sha3_256 | sha3_384 | sha3_512.

Fixed-output algorithms supported by this module.

hash_state()

-type hash_state() :: {hash_algorithm(), libdecaf_nif:hash_state()}.

A legacy {Algorithm, NativeState} tuple for a fixed-output hash.

state()

-type state() :: hash_state() | xof_state().

An immutable tagged hash or SHAKE state returned by init/1 or update/2.

xof_algorithm()

-type xof_algorithm() :: shake128 | shake256.

SHAKE algorithms accepted by hash/3, xof/3, and init/1.

xof_state()

-type xof_state() :: {xof_algorithm(), libdecaf_nif:xof_state()}.

A legacy {Algorithm, NativeState} tuple for SHAKE.

Functions

final(State)

This function is deprecated. Use libdecaf:hash_final/1 with an unwrapped hash state..

-spec final(State) -> Digest when State :: hash_state(), Digest :: binary().

Return a fixed-output digest using the algorithm's default length. The wrapped state remains reusable. SHAKE requires final/2.

final(State, Length)

This function is deprecated. Choose the digest length with libdecaf:hash_init/1, then use libdecaf:hash_final/1. For SHAKE, use libdecaf:xof_squeeze/2; it returns {NextState, Output}..

-spec final(State, Length) -> Digest
               when State :: state(), Length :: non_neg_integer(), Digest :: binary().

Return Length bytes without changing the wrapped state. Fixed-output hashes return a digest prefix and reject lengths above their maximum. SHAKE accepts any nonnegative output length.

hash(Type, Data)

This function is deprecated. Use libdecaf:hash/2..

-spec hash(Type, Data) -> Digest when Type :: hash_algorithm(), Data :: iodata(), Digest :: binary().

Hash iodata using the algorithm's default digest length. SHAKE requires an explicit output length with hash/3 or xof/3.

hash(Type, Data, Length)

This function is deprecated. Use libdecaf:hash({Algorithm, Length}, Data). For SHAKE, use libdecaf:xof(Algorithm, Data, Length)..

-spec hash(Type, Data, Length) -> Digest
              when
                  Type :: algorithm(), Data :: iodata(), Length :: non_neg_integer(), Digest :: binary().

Hash iodata and return exactly Length bytes. Fixed-output hashes allow truncation up to their maximum digest length. SHAKE produces the requested number of XOF bytes, including zero.

init(Type)

This function is deprecated. Use libdecaf:hash_init/1 or libdecaf:xof_init/1; retain the unwrapped state..

-spec init(Type) -> State when Type :: algorithm(), State :: state().

Initialize an immutable {Type, NativeState} tuple. Pass the returned tuple to update/2 and final/1,2 in this module. SHAKE states can only be finalized with an explicit output length.

update(State, Data)

This function is deprecated. Use libdecaf:hash_update/2 or libdecaf:xof_absorb/2 with an unwrapped state..

-spec update(State, Data) -> NewState when State :: state(), Data :: iodata(), NewState :: state().

Absorb iodata and return a new {Algorithm, NativeState} tuple. The algorithm tag is preserved and the input tuple remains reusable.

xof(Type, Data, Length)

This function is deprecated. Use libdecaf:xof/3..

-spec xof(Type, Data, Length) -> Output
             when
                 Type :: xof_algorithm(),
                 Data :: iodata(),
                 Length :: non_neg_integer(),
                 Output :: binary().

Return Length SHAKE bytes from iodata in one call. This preserves the historical xof/3 alias for SHAKE through hash/3.