typedef sz_status_t(*) sz_kernel_hash_t(sz_cptr_t, sz_size_t, sz_u64_t, sz_u64_t *, sz_stream_t);Hashing comes in three flavors: a byte checksum, a seeded single-shot hash, and an incremental streaming state. All produce identical output across every backend and platform, in both single-shot and incremental modes.
sz_status_t sz_bytesum_best(sz_cptr_t text, sz_size_t length, sz_u64_t *checksum, //
sz_capability_t capabilities, sz_stream_t stream);
sz_status_t sz_hash_best(sz_cptr_t text, sz_size_t length, sz_u64_t seed, sz_u64_t *hash, //
sz_capability_t capabilities, sz_stream_t stream);
sz_status_t sz_hash_multiseed_best(sz_cptr_t text, sz_size_t length, sz_u64_t const *seeds, sz_size_t seeds_count,
sz_u64_t *hashes, sz_capability_t capabilities, sz_stream_t stream);sz_hash_best is non-cryptographic, fast for both short and long inputs, passes the SMHasher --extra suite, and uses the AES extensions where present. sz_hash_multiseed_best hashes one input under many seeds at once — for feature hashing, Count-Min sketches, Bloom filters, and MinHash/LSH — by normalizing the input into AES blocks once and replaying cheap per-seed rounds.
Incremental hashing uses an opaque sz_hash_state_t, whose layout every capability shares, so each call may pass its own mask:
sz_status_t sz_hash_state_init_best(sz_hash_state_t *state, sz_u64_t seed, sz_capability_t capabilities, sz_stream_t stream);
sz_status_t sz_hash_state_update_best(sz_hash_state_t *state, sz_cptr_t text, sz_size_t length, //
sz_capability_t capabilities, sz_stream_t stream);
sz_status_t sz_hash_state_digest_best(sz_hash_state_t const *state, sz_u64_t *hash, //
sz_capability_t capabilities, sz_stream_t stream);
sz_bool_t sz_hash_state_equal(sz_hash_state_t const *lhs, sz_hash_state_t const *rhs);A streaming SHA-256 is also provided, producing a 32-byte digest, with hardware backends on x86 SHA-NI, ARM NEON-SHA, and others:
sz_status_t sz_sha256_state_init_best(sz_sha256_state_t *state, sz_capability_t capabilities, sz_stream_t stream);
sz_status_t sz_sha256_state_update_best(sz_sha256_state_t *state, sz_cptr_t text, sz_size_t length, //
sz_capability_t capabilities, sz_stream_t stream);
sz_status_t sz_sha256_state_digest_best(sz_sha256_state_t const *state, sz_u8_t digest[32], //
sz_capability_t capabilities, sz_stream_t stream);The same AES primitives back a reproducible pseudo-random fill, useful with sz_strings_lookup_best for generating random strings over a chosen alphabet:
sz_status_t sz_fill_random_best(sz_ptr_t target, sz_size_t length, sz_u64_t nonce, //
sz_capability_t capabilities, sz_stream_t stream);Example combining a single-shot hash, a streamed hash, and a checksum:
#include <stringzilla/stringzilla.h>
int main(void) {
sz_capability_t capabilities = sz_cap_serial_k;
sz_capabilities_enabled_cpu(&capabilities);
sz_u64_t single = 0;
sz_hash_best("hello world", 11, 42, &single, capabilities, NULL);
sz_hash_state_t state;
sz_u64_t streamed = 0;
sz_hash_state_init_best(&state, 42, capabilities, NULL);
sz_hash_state_update_best(&state, "hello ", 6, capabilities, NULL);
sz_hash_state_update_best(&state, "world", 5, capabilities, NULL);
sz_hash_state_digest_best(&state, &streamed, capabilities, NULL);
assert(streamed == single);
sz_u64_t sum = 0;
sz_bytesum_best("hi", 2, &sum, capabilities, NULL);
assert(sum == 209);
return 0;
}API
Types
sz_kernel_hash_tSignature of the sz_hash_best kernels.
sz_kernel_hash_multiseed_tSignature of the sz_hash_multiseed_best kernels.
typedef sz_status_t(*) sz_kernel_hash_multiseed_t(sz_cptr_t, sz_size_t, sz_u64_t const *, sz_size_t, sz_u64_t *, sz_stream_t);sz_kernel_hash_strings_tSignature of the sz_hash_strings_best kernels.
typedef sz_status_t(*) sz_kernel_hash_strings_t(sz_strings_view_t const *, sz_size_t const *, sz_size_t, sz_u64_t, sz_u64_t *, sz_stream_t);sz_kernel_hash_state_init_tSignature of the sz_hash_state_init_best kernels.
typedef sz_status_t(*) sz_kernel_hash_state_init_t(struct sz_hash_state_t *, sz_u64_t, sz_stream_t);sz_kernel_hash_state_update_tSignature of the sz_hash_state_update_best kernels.
typedef sz_status_t(*) sz_kernel_hash_state_update_t(struct sz_hash_state_t *, sz_cptr_t, sz_size_t, sz_stream_t);sz_kernel_hash_state_digest_tSignature of the sz_hash_state_digest_best kernels.
typedef sz_status_t(*) sz_kernel_hash_state_digest_t(struct sz_hash_state_t const *, sz_u64_t *, sz_stream_t);sz_kernel_bytesum_tSignature of the sz_bytesum_best kernels.
typedef sz_status_t(*) sz_kernel_bytesum_t(sz_cptr_t, sz_size_t, sz_u64_t *, sz_stream_t);sz_kernel_sha256_state_init_tSignature of the sz_sha256_state_init_best kernels.
typedef sz_status_t(*) sz_kernel_sha256_state_init_t(struct sz_sha256_state_t *, sz_stream_t);sz_kernel_sha256_state_update_tSignature of the sz_sha256_state_update_best kernels.
typedef sz_status_t(*) sz_kernel_sha256_state_update_t(struct sz_sha256_state_t *, sz_cptr_t, sz_size_t, sz_stream_t);sz_kernel_sha256_state_digest_tSignature of the sz_sha256_state_digest_best kernels.
typedef sz_status_t(*) sz_kernel_sha256_state_digest_t(struct sz_sha256_state_t const *, sz_u8_t *, sz_stream_t);sz_kernel_sha256_multistate_update_tSignature of the sz_sha256_multistate_update_best kernels.
typedef sz_status_t(*) sz_kernel_sha256_multistate_update_t(struct sz_sha256_state_t *, sz_strings_view_t const *, sz_stream_t);sz_kernel_sha256_multistate_digest_tSignature of the sz_sha256_multistate_digest_best kernels.
typedef sz_status_t(*) sz_kernel_sha256_multistate_digest_t(struct sz_sha256_state_t const *, sz_size_t, sz_u8_t *, sz_stream_t);sz_kernel_aes256_key_init_tSignature of the sz_aes256_key_init_best kernels.
typedef sz_status_t(*) sz_kernel_aes256_key_init_t(struct sz_aes256_key_t *, sz_u8_t const *, sz_stream_t);sz_kernel_aes256_gcm_key_init_tSignature of the sz_aes256_gcm_key_init_best kernels.
typedef sz_status_t(*) sz_kernel_aes256_gcm_key_init_t(struct sz_aes256_gcm_key_t *, sz_u8_t const *, sz_stream_t);sz_kernel_aes256_ctr_xor_tSignature of the sz_aes256_ctr_xor_best kernels.
typedef sz_status_t(*) sz_kernel_aes256_ctr_xor_t(struct sz_aes256_key_t const *, sz_u8_t const *, sz_u64_t, sz_cptr_t, sz_size_t, sz_ptr_t, sz_stream_t);sz_kernel_aes256_gcm_encrypt_tSignature of the sz_aes256_gcm_encrypt_best kernels.
typedef sz_status_t(*) sz_kernel_aes256_gcm_encrypt_t(struct sz_aes256_gcm_key_t const *, sz_u8_t const *, sz_cptr_t, sz_size_t, sz_cptr_t, sz_size_t, sz_ptr_t, sz_u8_t *, sz_stream_t);sz_kernel_aes256_gcm_decrypt_tSignature of the sz_aes256_gcm_decrypt_best kernels.
typedef sz_status_t(*) sz_kernel_aes256_gcm_decrypt_t(struct sz_aes256_gcm_key_t const *, sz_u8_t const *, sz_cptr_t, sz_size_t, sz_cptr_t, sz_size_t, sz_ptr_t, sz_u8_t const *, sz_stream_t);sz_kernel_aes256_gcm_encryptor_init_tSignature of the sz_aes256_gcm_encryptor_init_best kernels.
typedef sz_status_t(*) sz_kernel_aes256_gcm_encryptor_init_t(struct sz_aes256_gcm_encryptor_t *, struct sz_aes256_gcm_key_t const *, sz_u8_t const *, sz_stream_t);sz_kernel_aes256_gcm_encryptor_associate_tSignature of the sz_aes256_gcm_encryptor_associate_best kernels.
typedef sz_status_t(*) sz_kernel_aes256_gcm_encryptor_associate_t(struct sz_aes256_gcm_encryptor_t *, sz_cptr_t, sz_size_t, sz_stream_t);sz_kernel_aes256_gcm_encryptor_update_tSignature of the sz_aes256_gcm_encryptor_update_best kernels.
typedef sz_status_t(*) sz_kernel_aes256_gcm_encryptor_update_t(struct sz_aes256_gcm_encryptor_t *, sz_cptr_t, sz_size_t, sz_ptr_t, sz_stream_t);sz_kernel_aes256_gcm_encryptor_digest_tSignature of the sz_aes256_gcm_encryptor_digest_best kernels.
typedef sz_status_t(*) sz_kernel_aes256_gcm_encryptor_digest_t(struct sz_aes256_gcm_encryptor_t const *, sz_u8_t *, sz_stream_t);sz_kernel_aes256_gcm_decryptor_init_tSignature of the sz_aes256_gcm_decryptor_init_best kernels.
typedef sz_status_t(*) sz_kernel_aes256_gcm_decryptor_init_t(struct sz_aes256_gcm_decryptor_t *, struct sz_aes256_gcm_key_t const *, sz_u8_t const *, sz_stream_t);sz_kernel_aes256_gcm_decryptor_associate_tSignature of the sz_aes256_gcm_decryptor_associate_best kernels.
typedef sz_status_t(*) sz_kernel_aes256_gcm_decryptor_associate_t(struct sz_aes256_gcm_decryptor_t *, sz_cptr_t, sz_size_t, sz_stream_t);sz_kernel_aes256_gcm_decryptor_update_unverified_tSignature of the sz_aes256_gcm_decryptor_update_unverified_best kernels.
typedef sz_status_t(*) sz_kernel_aes256_gcm_decryptor_update_unverified_t(struct sz_aes256_gcm_decryptor_t *, sz_cptr_t, sz_size_t, sz_ptr_t, sz_stream_t);sz_kernel_aes256_gcm_decryptor_verify_tSignature of the sz_aes256_gcm_decryptor_verify_best kernels.
typedef sz_status_t(*) sz_kernel_aes256_gcm_decryptor_verify_t(struct sz_aes256_gcm_decryptor_t const *, sz_u8_t const *, sz_stream_t);Functions
sz_bytesum_bestComputes the 64-bit check-sum of bytes in a string, similar to std::ranges::accumulate.
sz_status_t sz_bytesum_best(
sz_cptr_t text,
sz_size_t length,
sz_u64_t *checksum,
sz_capability_t capabilities,
sz_stream_t stream);Backends
sz_bytesumserialhaswellskylakeicelakeneonsvesve2rvvv128v128relaxedloongsonasxpowervsx
Summing the bytes of "hi", 104 + 105:
#include <stringzilla/stringzilla.h>
int main() {
sz_capability_t capabilities;
sz_u64_t checksum;
sz_capabilities_enabled_cpu(&capabilities);
sz_bytesum_best("hi", 2, &checksum, capabilities, NULL);
return checksum == 209 ? 0 : 1;
}Parameters
text | in | String to aggregate. |
|---|---|---|
length | in | Number of bytes in the text. |
checksum | out | The 64-bit unsigned sum. |
capabilities | in | One device's capabilities, like sz_capabilities_enabled_cpu reports. |
stream | in | Null on the CPU, or the GPU stream of that device to queue on. |
See also
sz_bytesum_serial, sz_bytesum_haswell, sz_bytesum_skylake, sz_bytesum_icelake, sz_bytesum_neon, sz_bytesum_sve, sz_bytesum_sve2, sz_bytesum_v128, sz_bytesum_v128relaxed, sz_bytesum_rvv, sz_bytesum_loongsonasx, sz_bytesum_powervsx
Statuses
sz_missing_kernel_kNo capability incapabilitieshas it.
sz_hash_bestComputes the 64-bit unsigned hash of a string, similar to std::hash in C++.
sz_status_t sz_hash_best(
sz_cptr_t text,
sz_size_t length,
sz_u64_t seed,
sz_u64_t *hash,
sz_capability_t capabilities,
sz_stream_t stream);Backends
sz_hashserialwestmereskylakeicelakeneonaessve2aesrvvrvvcryptov128v128relaxedloongsonasxpowervsx
It's not cryptographically secure, but it's fast and provides a good distribution. It passes the SMHasher suite by Austin Appleby with no collisions, even with the --extra flag. HASH.md explains the algorithm in detail.
Telling two different strings apart:
#include <stringzilla/stringzilla.h>
int main() {
sz_capability_t capabilities;
sz_u64_t first_hash, second_hash;
sz_capabilities_enabled_cpu(&capabilities);
sz_hash_best("hello", 5, 0, &first_hash, capabilities, NULL);
sz_hash_best("world", 5, 0, &second_hash, capabilities, NULL);
return first_hash != second_hash ? 0 : 1;
}Parameters
text | in | String to hash. |
|---|---|---|
length | in | Number of bytes in the text. |
seed | in | 64-bit unsigned seed for the hash. |
hash | out | The 64-bit hash value. |
capabilities | in | One device's capabilities, like sz_capabilities_enabled_cpu reports. |
stream | in | Null on the CPU, or the GPU stream of that device to queue on. |
Notes
The output is the same on all platforms, in both single-shot and incremental modes.
See also
- sz_hash_serial, sz_hash_westmere, sz_hash_skylake, sz_hash_icelake, sz_hash_neonaes, sz_hash_sve2aes, sz_hash_rvv, sz_hash_rvvcrypto, sz_hash_v128, sz_hash_v128relaxed, sz_hash_loongsonasx, sz_hash_powervsx
- sz_hash_state_init_best, sz_hash_state_update_best, sz_hash_state_digest_best
Statuses
sz_missing_kernel_kNo capability incapabilitieshas it.
sz_hash_strings_bestHashes every one of strings[order[i]], or of the first count strings, under one seed, each exactly as sz_hash_best would, for group-by keys, joins and sharding.
sz_status_t sz_hash_strings_best(
sz_strings_view_t const *strings,
sz_size_t const *order,
sz_size_t count,
sz_u64_t seed,
sz_u64_t *hashes,
sz_capability_t capabilities,
sz_stream_t stream);Backends
sz_hash_stringsserialwestmereskylakeicelakeneonaesrvvcryptov128v128relaxedloongsonasxpowervsx
A tape read in its own order loads each window of consecutive keys once and hashes the keys of up to 64 bytes in it from registers, their AES rounds interleaved, while longer keys, orders and the accessor layout hash one string at a time.
Parameters
strings | in | The strings to hash, in any layout. |
|---|---|---|
order | in | Indices into strings, possibly repeated, or null for the first count. |
count | in | Number of strings to hash. |
seed | in | The seed every string is hashed under. |
hashes | out | The count hashes, one per string. |
capabilities | in | One device's capabilities, like sz_capabilities_enabled_cpu reports. |
stream | in | Null on the CPU, or the GPU stream of that device to queue on. |
Statuses
sz_missing_kernel_kNo capability incapabilitieshas it.
sz_hash_multiseed_bestHashes one string under many seeds at once, the "multi-seed" hash.
sz_status_t sz_hash_multiseed_best(
sz_cptr_t text,
sz_size_t length,
sz_u64_t const *seeds,
sz_size_t seeds_count,
sz_u64_t *hashes,
sz_capability_t capabilities,
sz_stream_t stream);Backends
sz_hash_multiseedserialwestmereicelakeneonaesrvvcryptov128v128relaxedpowervsx
Equivalent to hashing with sz_hash_best under each of seeds, but normalizes the input into AES blocks once and replays the cheap per-seed rounds over that prepared form.
Designed for workloads that need several independent hashes of the same (often short) key: feature-hashing & Count-Min sketches for BM25/TF-IDF, Bloom filters, cuckoo hashing, MinHash / SimHash / LSH banding, and rendezvous (HRW) hashing. Two effects make it faster than a loop of sz_hash_best: the branch-heavy load & de-interleave of variable-length short strings is amortized across all seeds, and AES-capable backends advance several seed-lanes per instruction.
Three seeds, the first matching a plain sz_hash_best call:
#include <stringzilla/stringzilla.h>
int main() {
sz_capability_t capabilities;
sz_u64_t seeds[3] = {1, 2, 3}, hashes[3], hash;
sz_capabilities_enabled_cpu(&capabilities);
sz_hash_multiseed_best("token", 5, seeds, 3, hashes, capabilities, NULL);
sz_hash_best("token", 5, 1, &hash, capabilities, NULL);
return hashes[0] == hash ? 0 : 1;
}Parameters
text | in | String to hash. |
|---|---|---|
length | in | Number of bytes in the text. |
seeds | in | Array of seeds_count 64-bit seeds. |
seeds_count | in | Number of seeds, and the number of hashes written to hashes. |
hashes | out | Caller-allocated output buffer of seeds_count 64-bit hashes. |
capabilities | in | One device's capabilities, like sz_capabilities_enabled_cpu reports. |
stream | in | Null on the CPU, or the GPU stream of that device to queue on. |
Notes
Biggest speedups are for length ≤ 64; above that only the input load is shared.
See also
sz_hash_multiseed_serial, sz_hash_multiseed_westmere, sz_hash_multiseed_icelake, sz_hash_multiseed_neonaes, sz_hash_multiseed_rvvcrypto, sz_hash_multiseed_v128, sz_hash_multiseed_v128relaxed, sz_hash_multiseed_powervsx
Statuses
sz_missing_kernel_kNo capability incapabilitieshas it.
sz_hash_state_init_bestInitializes the state for incremental construction of a hash.
sz_status_t sz_hash_state_init_best(
sz_hash_state_t *state,
sz_u64_t seed,
sz_capability_t capabilities,
sz_stream_t stream);Backends
sz_hash_state_initserialwestmereskylakeicelakeneonaessve2aesrvvrvvcryptov128v128relaxedloongsonasxpowervsx
Every backend shares the state layout, so each call of a stream may pass other capabilities.
Parameters
state | out | The state to initialize. |
|---|---|---|
seed | in | The 64-bit unsigned seed for the hash. |
capabilities | in | One device's capabilities, like sz_capabilities_enabled_cpu reports. |
stream | in | Null on the CPU, or the GPU stream of that device to queue on. |
Statuses
sz_missing_kernel_kNo capability incapabilitieshas it.
sz_hash_state_update_bestUpdates the state with new data.
sz_status_t sz_hash_state_update_best(
sz_hash_state_t *state,
sz_cptr_t text,
sz_size_t length,
sz_capability_t capabilities,
sz_stream_t stream);Backends
sz_hash_state_updateserialwestmereskylakeicelakeneonaessve2aesrvvrvvcryptov128v128relaxedloongsonasxpowervsx
Parameters
state | inout | The state to stream. |
|---|---|---|
text | in | The new data to include in the hash. |
length | in | The number of bytes in the new data. |
capabilities | in | One device's capabilities, like sz_capabilities_enabled_cpu reports. |
stream | in | Null on the CPU, or the GPU stream of that device to queue on. |
Statuses
sz_missing_kernel_kNo capability incapabilitieshas it.
sz_hash_state_digest_bestFinalizes the immutable state into the hash.
sz_status_t sz_hash_state_digest_best(
sz_hash_state_t const *state,
sz_u64_t *hash,
sz_capability_t capabilities,
sz_stream_t stream);Backends
sz_hash_state_digestserialwestmereskylakeicelakeneonaessve2aesrvvrvvcryptov128v128relaxedloongsonasxpowervsx
Parameters
state | in | The state to fold. |
|---|---|---|
hash | out | The 64-bit hash value, as sz_hash_best gives for the same bytes and seed. |
capabilities | in | One device's capabilities, like sz_capabilities_enabled_cpu reports. |
stream | in | Null on the CPU, or the GPU stream of that device to queue on. |
Statuses
sz_missing_kernel_kNo capability incapabilitieshas it.
sz_sha256_state_init_bestInitializes the state for incremental SHA256 hashing.
sz_status_t sz_sha256_state_init_best(
sz_sha256_state_t *state,
sz_capability_t capabilities,
sz_stream_t stream);Backends
sz_sha256_state_initserialgoldmontneonsharvvrvvcryptov128loongsonasxpowervsx
Every backend shares the state layout, so each call of a stream may pass other capabilities.
Parameters
state | out | The state to initialize. |
|---|---|---|
capabilities | in | One device's capabilities, like sz_capabilities_enabled_cpu reports. |
stream | in | Null on the CPU, or the GPU stream of that device to queue on. |
Statuses
sz_missing_kernel_kNo capability incapabilitieshas it.
sz_sha256_state_update_bestUpdates the SHA256 state with new data.
sz_status_t sz_sha256_state_update_best(
sz_sha256_state_t *state,
sz_cptr_t text,
sz_size_t length,
sz_capability_t capabilities,
sz_stream_t stream);Backends
sz_sha256_state_updateserialgoldmontneonsharvvrvvcryptov128loongsonasxpowervsx
Parameters
state | inout | The state to update. |
|---|---|---|
text | in | The new data to hash. |
length | in | The number of bytes in the new data. |
capabilities | in | One device's capabilities, like sz_capabilities_enabled_cpu reports. |
stream | in | Null on the CPU, or the GPU stream of that device to queue on. |
Statuses
sz_missing_kernel_kNo capability incapabilitieshas it.
sz_sha256_state_digest_bestFinalizes the SHA256 state into the digest, leaving the state open to more data.
sz_status_t sz_sha256_state_digest_best(
sz_sha256_state_t const *state,
sz_u8_t digest,
sz_capability_t capabilities,
sz_stream_t stream);Backends
sz_sha256_state_digestserialgoldmontneonsharvvrvvcryptov128loongsonasxpowervsx
Parameters
state | in | The state to finalize. |
|---|---|---|
digest | out | Output buffer for the 32-byte (256-bit) digest. |
capabilities | in | One device's capabilities, like sz_capabilities_enabled_cpu reports. |
stream | in | Null on the CPU, or the GPU stream of that device to queue on. |
Statuses
sz_missing_kernel_kNo capability incapabilitieshas it.
sz_sha256_multistate_update_bestAdvances many independent SHA256 states, one message per lane.
sz_status_t sz_sha256_multistate_update_best(
sz_sha256_state_t *states,
sz_strings_view_t const *texts,
sz_capability_t capabilities,
sz_stream_t stream);Backends
sz_sha256_multistate_updateserialgoldmonthaswellskylakeneonsharvvcryptocudarocm
Hashing one message is a serial dependency chain, so a wider instruction set cannot accelerate it. Independent messages compress in parallel lanes, which is what this does: sixteen at a time on AVX-512, eight on AVX2. Supply at least a few kilobytes per lane per call so the lane transposition is amortized; below one 64-byte block per lane it degrades to the single-message path. A zero-length chunk is a no-op for that lane. The states must be distinct, while the chunks may overlap.
Advancing two lanes by one chunk each, then taking both digests:
#include <stringzilla/stringzilla.h>
int main() {
sz_cptr_t chunks[2] = {"hello", "world"};
sz_sha256_state_t states[2];
sz_u8_t digests[2 * STRINGZILLA_SHA256_DIGEST_LENGTH];
sz_strings_view_t texts;
sz_capability_t capabilities;
sz_capabilities_enabled_cpu(&capabilities);
sz_strings_from_null_terminated_strings(chunks, 2, &texts);
sz_sha256_state_init_best(&states[0], capabilities, NULL);
sz_sha256_state_init_best(&states[1], capabilities, NULL);
sz_sha256_multistate_update_best(states, &texts, capabilities, NULL);
sz_sha256_multistate_digest_best(states, 2, digests, capabilities, NULL);
return digests[0] == 0x2c ? 0 : 1;
}Lanes are grouped by vector width and a group advances in lockstep, so it costs as much as its longest member. Inputs sorted by length put similar lengths in the same group, and sz_sort_order_best gives that ordering.
Parameters
states | inout | Array of at least texts->count states, each initialized with sz_sha256_state_init_best. |
|---|---|---|
texts | in | Strings supplying the next chunk of each lane's message, with count lanes; on a GPU, a tape the device addresses, like sz_strings_to_tape_best writes. |
capabilities | in | One device's capabilities, like sz_capabilities_enabled_cpu reports. |
stream | in | Null on the CPU, or the GPU stream of that device to queue on. |
Notes
Every lane is correct whatever its length, but throughput is best sorted by length.
See also
sz_sha256_multistate_update_serial, sz_sha256_multistate_update_goldmont, sz_sha256_multistate_update_haswell, sz_sha256_multistate_update_skylake, sz_sha256_multistate_update_neonsha, sz_sha256_multistate_update_rvvcrypto
Statuses
sz_missing_kernel_kNo capability incapabilitieshas it.
sz_sha256_multistate_digest_bestFinalizes many independent SHA256 states, one digest per lane.
sz_status_t sz_sha256_multistate_digest_best(
sz_sha256_state_t const *states,
sz_size_t states_count,
sz_u8_t *digests,
sz_capability_t capabilities,
sz_stream_t stream);Backends
sz_sha256_multistate_digestserialgoldmonthaswellskylakeneonsharvvcryptocudarocm
Leaves every state unmodified, so a streaming caller can take an interim digest and append more.
Parameters
states | in | Array of states_count states. |
|---|---|---|
states_count | in | Number of states to finalize, which is the lane count. |
digests | out | Output buffer of states_count * STRINGZILLA_SHA256_DIGEST_LENGTH bytes, one big-endian digest per lane, in lane order. |
capabilities | in | One device's capabilities, like sz_capabilities_enabled_cpu reports. |
stream | in | Null on the CPU, or the GPU stream of that device to queue on. |
See also
Statuses
sz_missing_kernel_kNo capability incapabilitieshas it.
sz_hash_find_kernelFinds the hashing kernel of kind, from the best of capabilities.
sz_status_t sz_hash_find_kernel(
sz_kernel_kind_t kind,
sz_capability_t capabilities,
sz_kernel_punned_t *kernel,
sz_capability_t *capability);Parameters
kind | in | The verb whose kernel to find. |
|---|---|---|
capabilities | in | The mask to pick the best capability from. |
kernel | out | The kernel, or null when none of capabilities has it. |
capability | out | The capability the kernel belongs to, or zero. |
Statuses
sz_missing_kernel_ksz_missing_library_kHeader-only.
sz_hash_state_equalCompares the state of two running hashes.
sz_bool_t sz_hash_state_equal(
sz_hash_state_t const *lhs,
sz_hash_state_t const *rhs);Notes
The current content of the ins buffer and its length is ignored.
sz_aes256_key_init_bestExpands a 32-byte secret into the AES-256 round-key schedule.
sz_status_t sz_aes256_key_init_best(
sz_aes256_key_t *key,
sz_u8_t const secret,
sz_capability_t capabilities,
sz_stream_t stream);Backends
sz_aes256_key_initserialwestmereicelakeneonaessve2aesv128relaxedv128rvvcryptopowervsx
Expanding an all-zero secret:
#include <stringzilla/stringzilla.h>
int main() {
sz_u8_t secret[32] = {0};
sz_aes256_key_t key;
sz_capability_t capabilities;
sz_capabilities_enabled_cpu(&capabilities);
return sz_aes256_key_init_best(&key, secret, capabilities, NULL) == sz_success_k ? 0 : 1;
}Parameters
key | out | Receives the expanded schedule. |
|---|---|---|
secret | in | The 32 secret bytes. |
capabilities | in | One device's capabilities, like sz_capabilities_enabled_cpu reports. |
stream | in | Null on the CPU, or the GPU stream of that device to queue on. |
See also
sz_aes256_key_init_serial, sz_aes256_key_init_westmere, sz_aes256_key_init_icelake, sz_aes256_key_init_neonaes, sz_aes256_key_init_sve2aes, sz_aes256_key_init_rvvcrypto, sz_aes256_key_init_v128, sz_aes256_key_init_v128relaxed, sz_aes256_key_init_powervsx
Statuses
sz_missing_kernel_kNo capability incapabilitieshas it.
sz_aes256_ctr_xor_bestExclusive-ors length bytes against the AES-256 counter-mode keystream.
sz_status_t sz_aes256_ctr_xor_best(
sz_aes256_key_t const *key,
sz_u8_t const nonce,
sz_u64_t byte_offset,
sz_cptr_t text,
sz_size_t length,
sz_ptr_t target,
sz_capability_t capabilities,
sz_stream_t stream);Backends
sz_aes256_ctr_xorserialwestmereicelakeneonaessve2aesv128relaxedv128rvvcryptopowervsx
Counter mode is its own inverse, so one call serves both directions. The counter block is the nonce followed by a big-endian 32-bit block index that starts at zero, so block n covers bytes [16n, 16n + 16) and a byte_offset that is not a multiple of 16 simply discards the leading bytes of its first keystream block.
Encrypting a message, then decrypting only its second half:
#include <stringzilla/stringzilla.h>
int main() {
sz_u8_t secret[32] = {0}, nonce[12] = {0};
char plain[64] = "the second half is decrypted on its own", cipher[64], back[64];
sz_aes256_key_t key;
sz_capability_t capabilities;
sz_capabilities_enabled_cpu(&capabilities);
sz_aes256_key_init_best(&key, secret, capabilities, NULL);
sz_aes256_ctr_xor_best(&key, nonce, 0, plain, 64, cipher, capabilities, NULL);
sz_aes256_ctr_xor_best(&key, nonce, 32, cipher + 32, 32, back + 32, capabilities, NULL); // ? Seeks
return back[32] == plain[32] ? 0 : 1;
}Parameters
key | in | The expanded schedule. |
|---|---|---|
nonce | in | The 12 nonce bytes, which must never repeat under one key. |
byte_offset | in | Position of text within the stream, so a caller may start anywhere. |
text | in | The input bytes. |
length | in | Number of bytes to transform. |
target | out | Receives length bytes; may equal text, or must not overlap it at all. |
capabilities | in | One device's capabilities, like sz_capabilities_enabled_cpu reports. |
stream | in | Null on the CPU, or the GPU stream of that device to queue on. |
See also
sz_aes256_ctr_xor_serial, sz_aes256_ctr_xor_westmere, sz_aes256_ctr_xor_icelake, sz_aes256_ctr_xor_neonaes, sz_aes256_ctr_xor_sve2aes, sz_aes256_ctr_xor_rvvcrypto, sz_aes256_ctr_xor_v128, sz_aes256_ctr_xor_v128relaxed, sz_aes256_ctr_xor_powervsx
Statuses
sz_missing_kernel_kNo capability incapabilitieshas it.
sz_aes256_gcm_key_init_bestExpands a 32-byte secret into a schedule and the Galois hash subkey powers.
sz_status_t sz_aes256_gcm_key_init_best(
sz_aes256_gcm_key_t *key,
sz_u8_t const secret,
sz_capability_t capabilities,
sz_stream_t stream);Backends
sz_aes256_gcm_key_initserialwestmereicelakeneonaessve2aesv128relaxedv128rvvcryptopowervsx
The backends are sz_aes256_gcm_key_init_serial, sz_aes256_gcm_key_init_westmere, sz_aes256_gcm_key_init_icelake, sz_aes256_gcm_key_init_neonaes, sz_aes256_gcm_key_init_sve2aes, sz_aes256_gcm_key_init_rvvcrypto, sz_aes256_gcm_key_init_v128, sz_aes256_gcm_key_init_v128relaxed and sz_aes256_gcm_key_init_powervsx, one per target.
Parameters
key | out | Receives the schedule and the powers. |
|---|---|---|
secret | in | The 32 secret bytes. |
capabilities | in | One device's capabilities, like sz_capabilities_enabled_cpu reports. |
stream | in | Null on the CPU, or the GPU stream of that device to queue on. |
Statuses
sz_missing_kernel_kNo capability incapabilitieshas it.
sz_aes256_gcm_encrypt_bestEncrypts and authenticates a whole message in one call.
sz_status_t sz_aes256_gcm_encrypt_best(
sz_aes256_gcm_key_t const *key,
sz_u8_t const nonce,
sz_cptr_t associated,
sz_size_t associated_length,
sz_cptr_t text,
sz_size_t length,
sz_ptr_t target,
sz_u8_t tag,
sz_capability_t capabilities,
sz_stream_t stream);Backends
sz_aes256_gcm_encryptserialwestmereicelakeneonaessve2aesv128relaxedv128rvvcryptopowervsx
Sealing a short message and opening it again:
#include <stringzilla/stringzilla.h>
int main() {
sz_u8_t secret[32] = {0}, nonce[12] = {0}, tag[16];
char plain[5] = "hello", cipher[5], back[5];
sz_aes256_gcm_key_t key;
sz_capability_t capabilities;
sz_capabilities_enabled_cpu(&capabilities);
sz_aes256_gcm_key_init_best(&key, secret, capabilities, NULL);
sz_aes256_gcm_encrypt_best(&key, nonce, NULL, 0, plain, 5, cipher, tag, capabilities, NULL);
sz_status_t status = sz_aes256_gcm_decrypt_best(&key, nonce, NULL, 0, cipher, 5, back, tag, capabilities,
NULL);
return status == sz_success_k ? 0 : 1;
}Parameters
key | in | The expanded key. |
|---|---|---|
nonce | in | The 12 nonce bytes, which must never repeat under one key. |
associated | in | Authenticated, unencrypted bytes like a routing header, or STRINGZILLA_NULL. |
associated_length | in | Number of associated bytes, possibly zero. |
text | in | The plaintext. |
length | in | Number of plaintext bytes. |
target | out | Receives length ciphertext bytes, at text or not overlapping it at all. |
tag | out | Receives the 16-byte authentication tag. |
capabilities | in | One device's capabilities, like sz_capabilities_enabled_cpu reports. |
stream | in | Null on the CPU, or the GPU stream of that device to queue on. |
See also
sz_aes256_gcm_encrypt_serial, sz_aes256_gcm_encrypt_westmere, sz_aes256_gcm_encrypt_icelake, sz_aes256_gcm_encrypt_neonaes, sz_aes256_gcm_encrypt_sve2aes, sz_aes256_gcm_encrypt_rvvcrypto, sz_aes256_gcm_encrypt_v128, sz_aes256_gcm_encrypt_v128relaxed, sz_aes256_gcm_encrypt_powervsx
Statuses
sz_missing_kernel_kNo capability incapabilitieshas it.
sz_aes256_gcm_decrypt_bestVerifies a tag and decrypts a whole message in one call.
sz_status_t sz_aes256_gcm_decrypt_best(
sz_aes256_gcm_key_t const *key,
sz_u8_t const nonce,
sz_cptr_t associated,
sz_size_t associated_length,
sz_cptr_t text,
sz_size_t length,
sz_ptr_t target,
sz_u8_t const tag,
sz_capability_t capabilities,
sz_stream_t stream);Backends
sz_aes256_gcm_decryptserialwestmereicelakeneonaessve2aesv128relaxedv128rvvcryptopowervsx
The comparison runs in time independent of where the tag first differs, and the output is cleared rather than left holding the unauthenticated plaintext, so a caller who ignores the status still cannot act on forged data. Decrypting in place therefore destroys the ciphertext when the tag is rejected, which suits a caller that drops the message anyway and rules out one that must retry.
Parameters
key | in | The expanded key. |
|---|---|---|
nonce | in | The 12 nonce bytes used to encrypt. |
associated | in | Bytes authenticated but not encrypted, or STRINGZILLA_NULL. |
associated_length | in | Number of associated bytes, possibly zero. |
text | in | The ciphertext. |
length | in | Number of ciphertext bytes. |
target | out | Receives length plaintext bytes on success, and zeros on failure; may equal text, or must not overlap it at all. |
tag | in | The 16-byte tag to check. |
capabilities | in | One device's capabilities, like sz_capabilities_enabled_cpu reports. |
stream | in | Null on the CPU, or the GPU stream of that device to queue on. |
See also
sz_aes256_gcm_decrypt_serial, sz_aes256_gcm_decrypt_westmere, sz_aes256_gcm_decrypt_icelake, sz_aes256_gcm_decrypt_neonaes, sz_aes256_gcm_decrypt_sve2aes, sz_aes256_gcm_decrypt_rvvcrypto, sz_aes256_gcm_decrypt_v128, sz_aes256_gcm_decrypt_v128relaxed, sz_aes256_gcm_decrypt_powervsx
Statuses
sz_authentication_failed_kThe tag did not match andtargetis zeroed.sz_missing_kernel_kNo capability incapabilitieshas it and nothing was written.
sz_aes256_gcm_encryptor_init_bestBegins sealing a message delivered in chunks.
sz_status_t sz_aes256_gcm_encryptor_init_best(
sz_aes256_gcm_encryptor_t *encryptor,
sz_aes256_gcm_key_t const *key,
sz_u8_t const nonce,
sz_capability_t capabilities,
sz_stream_t stream);Backends
sz_aes256_gcm_encryptor_initserialwestmereicelakeneonaessve2aesv128relaxedv128rvvcryptopowervsx
Sealing an eight-byte buffer in place:
#include <stringzilla/stringzilla.h>
int main() {
sz_u8_t secret[32] = {0}, nonce[12] = {0}, tag[16], buffer[8] = {0};
sz_aes256_gcm_key_t key;
sz_aes256_gcm_encryptor_t encryptor;
sz_capability_t capabilities;
sz_capabilities_enabled_cpu(&capabilities);
sz_aes256_gcm_key_init_best(&key, secret, capabilities, NULL);
sz_aes256_gcm_encryptor_init_best(&encryptor, &key, nonce, capabilities, NULL);
sz_aes256_gcm_encryptor_update_best(&encryptor, (sz_cptr_t)buffer, 8, (sz_ptr_t)buffer, capabilities, NULL);
sz_aes256_gcm_encryptor_digest_best(&encryptor, tag, capabilities, NULL);
return 0;
}The backends are sz_aes256_gcm_encryptor_init_serial, sz_aes256_gcm_encryptor_init_westmere, sz_aes256_gcm_encryptor_init_icelake, sz_aes256_gcm_encryptor_init_neonaes, sz_aes256_gcm_encryptor_init_sve2aes, sz_aes256_gcm_encryptor_init_rvvcrypto, sz_aes256_gcm_encryptor_init_v128, sz_aes256_gcm_encryptor_init_v128relaxed and sz_aes256_gcm_encryptor_init_powervsx.
Parameters
encryptor | out | The encryptor to initialize. |
|---|---|---|
key | in | The expanded key, copied into encryptor. |
nonce | in | The 12 nonce bytes, which must never repeat under one key. |
capabilities | in | One device's capabilities, like sz_capabilities_enabled_cpu reports. |
stream | in | Null on the CPU, or the GPU stream of that device to queue on. |
Statuses
sz_missing_kernel_kNo capability incapabilitieshas it.
sz_aes256_gcm_encryptor_associate_bestAbsorbs associated data into a seal, authenticated but not encrypted.
sz_status_t sz_aes256_gcm_encryptor_associate_best(
sz_aes256_gcm_encryptor_t *encryptor,
sz_cptr_t text,
sz_size_t length,
sz_capability_t capabilities,
sz_stream_t stream);Backends
sz_aes256_gcm_encryptor_associateserialwestmereicelakeneonaessve2aesv128relaxedv128rvvcryptopowervsx
Parameters
encryptor | inout | The encryptor. |
|---|---|---|
text | in | The associated bytes. |
length | in | Number of associated bytes. |
capabilities | in | One device's capabilities, like sz_capabilities_enabled_cpu reports. |
stream | in | Null on the CPU, or the GPU stream of that device to queue on. |
Notes
All associated data must be absorbed before the first call transforming message bytes.
See also
sz_aes256_gcm_encryptor_associate_serial
Statuses
sz_missing_kernel_kNo capability incapabilitieshas it.
sz_aes256_gcm_encryptor_update_bestEncrypts one chunk and absorbs its ciphertext into the running tag.
sz_status_t sz_aes256_gcm_encryptor_update_best(
sz_aes256_gcm_encryptor_t *encryptor,
sz_cptr_t text,
sz_size_t length,
sz_ptr_t target,
sz_capability_t capabilities,
sz_stream_t stream);Backends
sz_aes256_gcm_encryptor_updateserialwestmereicelakeneonaessve2aesv128relaxedv128rvvcryptopowervsx
Parameters
encryptor | inout | The encryptor. |
|---|---|---|
text | in | The plaintext chunk. |
length | in | Number of bytes in the chunk. |
target | out | Receives length ciphertext bytes, at text or not overlapping it at all. |
capabilities | in | One device's capabilities, like sz_capabilities_enabled_cpu reports. |
stream | in | Null on the CPU, or the GPU stream of that device to queue on. |
See also
sz_aes256_gcm_encryptor_update_serial
Statuses
sz_missing_kernel_kNo capability incapabilitieshas it.
sz_aes256_gcm_encryptor_digest_bestFinalizes a seal and emits its authentication tag.
sz_status_t sz_aes256_gcm_encryptor_digest_best(
sz_aes256_gcm_encryptor_t const *encryptor,
sz_u8_t tag,
sz_capability_t capabilities,
sz_stream_t stream);Backends
sz_aes256_gcm_encryptor_digestserialwestmereicelakeneonaessve2aesv128relaxedv128rvvcryptopowervsx
Parameters
encryptor | in | The encryptor, left unmodified so a caller may keep appending. |
|---|---|---|
tag | out | Receives the 16 tag bytes. |
capabilities | in | One device's capabilities, like sz_capabilities_enabled_cpu reports. |
stream | in | Null on the CPU, or the GPU stream of that device to queue on. |
See also
sz_aes256_gcm_encryptor_digest_serial
Statuses
sz_missing_kernel_kNo capability incapabilitieshas it.
sz_aes256_gcm_decryptor_init_bestBegins opening a message delivered in chunks.
sz_status_t sz_aes256_gcm_decryptor_init_best(
sz_aes256_gcm_decryptor_t *decryptor,
sz_aes256_gcm_key_t const *key,
sz_u8_t const nonce,
sz_capability_t capabilities,
sz_stream_t stream);Backends
sz_aes256_gcm_decryptor_initserialwestmereicelakeneonaessve2aesv128relaxedv128rvvcryptopowervsx
Parameters
decryptor | out | The decryptor to initialize. |
|---|---|---|
key | in | The expanded key, copied into decryptor. |
nonce | in | The 12 nonce bytes the message was sealed under. |
capabilities | in | One device's capabilities, like sz_capabilities_enabled_cpu reports. |
stream | in | Null on the CPU, or the GPU stream of that device to queue on. |
See also
sz_aes256_gcm_decryptor_init_serial
Statuses
sz_missing_kernel_kNo capability incapabilitieshas it.
sz_aes256_gcm_decryptor_associate_bestAbsorbs associated data into an open, authenticated but not encrypted.
sz_status_t sz_aes256_gcm_decryptor_associate_best(
sz_aes256_gcm_decryptor_t *decryptor,
sz_cptr_t text,
sz_size_t length,
sz_capability_t capabilities,
sz_stream_t stream);Backends
sz_aes256_gcm_decryptor_associateserialwestmereicelakeneonaessve2aesv128relaxedv128rvvcryptopowervsx
Parameters
decryptor | inout | The decryptor. |
|---|---|---|
text | in | The associated bytes. |
length | in | Number of associated bytes. |
capabilities | in | One device's capabilities, like sz_capabilities_enabled_cpu reports. |
stream | in | Null on the CPU, or the GPU stream of that device to queue on. |
Notes
All associated data must be absorbed before the first call transforming message bytes.
See also
sz_aes256_gcm_decryptor_associate_serial
Statuses
sz_missing_kernel_kNo capability incapabilitieshas it.
sz_aes256_gcm_decryptor_update_unverified_bestDecrypts one chunk and absorbs its ciphertext into the running tag.
sz_status_t sz_aes256_gcm_decryptor_update_unverified_best(
sz_aes256_gcm_decryptor_t *decryptor,
sz_cptr_t text,
sz_size_t length,
sz_ptr_t target,
sz_capability_t capabilities,
sz_stream_t stream);Backends
sz_aes256_gcm_decryptor_update_unverifiedserialwestmereicelakeneonaessve2aesv128relaxedv128rvvcryptopowervsx
Nothing has verified that this ciphertext is genuine, and a caller that acts on the output before sz_aes256_gcm_decryptor_verify_best succeeds is trusting an attacker's data. Buffer it, or accept that risk knowingly: a streaming decryption cannot avoid it, so the name says so.
Parameters
decryptor | inout | The decryptor. |
|---|---|---|
text | in | The ciphertext chunk. |
length | in | Number of bytes in the chunk. |
target | out | Receives length plaintext bytes, at text or not overlapping it at all. |
capabilities | in | One device's capabilities, like sz_capabilities_enabled_cpu reports. |
stream | in | Null on the CPU, or the GPU stream of that device to queue on. |
Warnings
The emitted bytes are not yet authenticated.
See also
sz_aes256_gcm_decryptor_update_unverified_serial
Statuses
sz_missing_kernel_kNo capability incapabilitieshas it.
sz_aes256_gcm_decryptor_verify_bestFinalizes an open and checks its authentication tag.
sz_status_t sz_aes256_gcm_decryptor_verify_best(
sz_aes256_gcm_decryptor_t const *decryptor,
sz_u8_t const tag,
sz_capability_t capabilities,
sz_stream_t stream);Backends
sz_aes256_gcm_decryptor_verifyserialwestmereicelakeneonaessve2aesv128relaxedv128rvvcryptopowervsx
The comparison runs in time independent of where the tag first differs, so a caller cannot leak the expected tag by timing repeated attempts. Emitting the expected tag and letting the caller compare it would hand that guarantee to code this library does not own.
Parameters
decryptor | in | The decryptor, left unmodified. |
|---|---|---|
tag | in | The 16 tag bytes to check. |
capabilities | in | One device's capabilities, like sz_capabilities_enabled_cpu reports. |
stream | in | Null on the CPU, or the GPU stream of that device to queue on. |
See also
sz_aes256_gcm_decryptor_verify_serial
Statuses
sz_authentication_failed_kThe tag did not match every byte the decryptor absorbed.sz_missing_kernel_kNo capability incapabilitieshas it.
sz_cipher_find_kernelFinds the cipher kernel of kind, from the best of capabilities.
sz_status_t sz_cipher_find_kernel(
sz_kernel_kind_t kind,
sz_capability_t capabilities,
sz_kernel_punned_t *kernel,
sz_capability_t *capability);Parameters
kind | in | The verb whose kernel to find. |
|---|---|---|
capabilities | in | The mask to pick the best capability from. |
kernel | out | The kernel, or null when none of capabilities has it. |
capability | out | The capability the kernel belongs to, or zero. |
Statuses
sz_missing_kernel_ksz_missing_library_kHeader-only.