The q* stdlib docs

qcrypto: cryptographic hashing

qcrypto provides cryptographic hashing implemented entirely from scratch with zero third-party dependencies: SHA-256 and HMAC-SHA-256 (FIPS 180-4 / RFC 2104), plus SHA-1. The two public QQL built-ins, crypto.sha256 and crypto.hmac_sha256, return lowercase hex strings. The crate also exports a richer set of library helpers used across the DMS — a CSPRNG, constant-time comparison, PBKDF2 password hashing, and HMAC request signing.

Public QQL built-ins#

Function	Arguments	Returns	Behavior
crypto.sha256	data (Str or Bytes)	Str (64 hex chars)	SHA-256 digest, lowercase hex.
crypto.hmac_sha256	key, message	Str (64 hex chars)	HMAC-SHA-256 of message under key, lowercase hex.

Both read their arguments as bytes: a Str is taken as its UTF-8 bytes, a Bytes value is used directly, and anything else is treated as empty. The output is always lowercase hex.

Algorithms and correctness#

SHA-256 and SHA-1 are implemented to FIPS 180-4 with standard padding and big-endian length. The implementations are verified against published test vectors: SHA-256 of the empty string is e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 and of "abc" is ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad. HMAC-SHA-256 matches RFC 4231 test case 1.

Library helpers (Rust API, not QQL)#

Beyond the two built-ins, qcrypto exports functions other crates call directly. These are not reachable from QQL but underpin authentication across the DMS.

sha256_hex / hmac_sha256_hex / sha1_hex / sha1_raw: Direct digest helpers returning lowercase hex (or raw 20 bytes for sha1_raw).
random_bytes(n): n bytes of OS entropy from /dev/urandom, with a splitmix64 clock-seeded fallback if it is unavailable. Used for salts, session tokens, and API-key nonces.
ct_eq / ct_eq_str: Constant-time equality: compares in time depending only on length, never short-circuiting on the first differing byte. Unequal lengths return false.
pbkdf2_hmac_sha256(password, salt, iterations, dklen): PBKDF2-HMAC-SHA-256 (RFC 8018 §5.2), iterations clamped to >= 1.
password_hash / password_verify: Hash a password with a fresh random salt at 600,000 iterations, producing pbkdf2$<iters>$<salt_b64>$<dk_b64>; verify re-derives and compares in constant time.
canonical_request / sort_query / sign_request / verify_request: Stateless API-key request signing: build a canonical string, HMAC-sign it, and verify in constant time.

Constant	Value	Meaning
PBKDF2_DEFAULT_ITERATIONS	600000	Default work factor for new password hashes (OWASP 2023+ floor).
PBKDF2_SALT_LEN	16	Salt length in bytes.
PBKDF2_DK_LEN	32	Derived-key length in bytes (a full SHA-256 block).

Resource budget#

The crypto.sha256 and crypto.hmac_sha256 built-ins declare an empty resource request — block-based hashing is bounded, lightweight work.

Example#

SHA-256 of "abc" returns its canonical 64-char lowercase-hex digest.

Request

crypto.sha256("abc")

# wire form:
{ "0": { "Str": "abc" } }

Response

{ "result": { "Str": "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad" } }

Output

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Request

crypto.hmac_sha256("key", "msg")

Response

{ "result": { "Str": "<64 lowercase hex chars>" } }

Output

a 64-character lowercase hex string