Streaming-capable SipHash-1-3 and SipHash-2-4 Implementation

1.8 · active · verified Mon Apr 13

The siphash24 library provides a C-based, streaming-capable implementation of SipHash-1-3 and SipHash-2-4 variants for Python. It offers an interface compatible with Python's standard `hashlib` module, enhancing it with an `intdigest()` method for integer hash values. The current version is 1.8, with releases occurring several times a year to support new Python versions and address minor updates.

Warnings

gotcha The `digest()` method returns a `bytes` object, while the `intdigest()` method returns a Python `int` object. Ensure you use the correct method based on your expected output type.
Fix: Use `hash_obj.digest()` for `bytes` output or `hash_obj.intdigest()` for `int` output.
breaking Prior to version 1.6, the `hexdigest()` method returned a `bytes` object. Starting with version 1.6, `hexdigest()` consistently returns a `str` object for consistency with `hashlib`.
Fix: Update your code to expect a `str` return type from `hexdigest()`. If you need `bytes`, encode the string manually (e.g., `.encode('utf-8')`).
gotcha Instances of `siphash24` hash objects are not thread-safe. If a single hash object is modified concurrently by multiple threads, external synchronization primitives (e.g., `threading.Lock`) must be used to prevent race conditions.
Fix: Use a separate hash object per thread or implement explicit locking mechanisms when sharing hash objects across threads.
gotcha The SipHash algorithm requires a 16-byte key. While `siphash24` will zero-pad shorter keys, it is best practice to always provide a 16-byte `bytes-like` object for the key to ensure predictable and secure hashing behavior.
Fix: Always provide a 16-byte key as a `bytes-like` object. For example, `b'your_16_byte_key'`.

Install

pip install siphash24 Latest stable version

Imports

siphash24
```
import siphash24
```
Imports the module itself, which provides functions and hashlib-compatible classes.
siphash13
```
import siphash24
```
The siphash13 function is accessed via the top-level siphash24 module, e.g., siphash24.siphash13().

Quickstart

Demonstrates how to use both SipHash-2-4 (streaming) and SipHash-1-3 (one-shot) variants. It highlights the `hashlib`-compatible interface methods (`update`, `digest`, `hexdigest`) and the library's extended `intdigest` method. Keys are managed via environment variables for security best practice.

import siphash24
import os

# SipHash-2-4 example (recommended variant)
key = os.environ.get('SIPHASH_KEY_24', 'a' * 16).encode('utf-8') # 16-byte key
message = b'hello world'

h = siphash24.siphash24(key=key)
h.update(message)
hash_digest = h.digest()
hash_int = h.intdigest()
hash_hex = h.hexdigest()

print(f"SipHash-2-4 digest: {hash_digest.hex()}")
print(f"SipHash-2-4 int digest: {hash_int}")
print(f"SipHash-2-4 hex digest: {hash_hex}")

# SipHash-1-3 example
key_13 = os.environ.get('SIPHASH_KEY_13', 'b' * 16).encode('utf-8') # 16-byte key
m_13 = siphash24.siphash13(key=key_13, data=b'another message')
print(f"SipHash-1-3 digest (one-shot): {m_13.digest().hex()}")

view raw JSON →