Merge remote-tracking branch 'offical/master'

core/c/c.odin

@@ -104,3 +104,13 @@ NULL           :: rawptr(uintptr(0))
 NDEBUG         :: !ODIN_DEBUG
 
 CHAR_BIT :: 8
+
+// Since there are no types in C with an alignment larger than that of
+// max_align_t, which cannot be larger than sizeof(long double) as any other
+// exposed type wouldn't be valid C, the maximum alignment possible in a
+// strictly conformant C implementation is 16 on the platforms we care about.
+// The choice of 4096 bytes for storage of this type is more than enough on all
+// relevant platforms.
+va_list :: struct #align(16) {
+	_: [4096]u8,
+}

core/c/libc/stdarg.odin

@@ -4,6 +4,8 @@ package libc
 
 import "base:intrinsics"
 
+import "core:c"
+
 @(private="file")
 @(default_calling_convention="none")
 foreign _ {
@@ -12,15 +14,7 @@ foreign _ {
 	@(link_name="llvm.va_copy")  _va_copy  :: proc(dst, src: ^i8) ---
 }
 
-// Since there are no types in C with an alignment larger than that of
-// max_align_t, which cannot be larger than sizeof(long double) as any other
-// exposed type wouldn't be valid C, the maximum alignment possible in a
-// strictly conformant C implementation is 16 on the platforms we care about.
-// The choice of 4096 bytes for storage of this type is more than enough on all
-// relevant platforms.
-va_list :: struct #align(16) {
-	_: [4096]u8,
-}
+va_list :: c.va_list
 
 va_start :: #force_inline proc(ap: ^va_list, _: any) {
 	_va_start(cast(^i8)ap)

core/crypto/_sha3/sha3.odin

@@ -7,8 +7,12 @@ package _sha3
     List of contributors:
         zhibog, dotbmp:  Initial implementation.
 
-    Implementation of the Keccak hashing algorithm, standardized as SHA3 in <https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf>
-    To use the original Keccak padding, set the is_keccak bool to true, otherwise it will use SHA3 padding.
+    Implementation of the Keccak hashing algorithm, standardized as SHA3
+    in <https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf>.
+
+    As the only difference between the legacy Keccak and SHA3 is the domain
+    separation byte, set dsbyte to the appropriate value to pick the desired
+    algorithm.
 */
 
 import "core:math/bits"
@@ -16,47 +20,56 @@ import "core:mem"
 
 ROUNDS :: 24
 
+RATE_128 :: 1344 / 8 // ONLY for SHAKE128.
 RATE_224 :: 1152 / 8
 RATE_256 :: 1088 / 8
 RATE_384 :: 832 / 8
 RATE_512 :: 576 / 8
 
+DS_KECCAK :: 0x01
+DS_SHA3 :: 0x06
+DS_SHAKE :: 0x1f
+DS_CSHAKE :: 0x04
+
 Context :: struct {
-	st:        struct #raw_union {
+	st:             struct #raw_union {
 		b: [200]u8,
 		q: [25]u64,
 	},
-	pt:        int,
-	rsiz:      int,
-	mdlen:     int,
-	is_keccak: bool,
-
+	pt:             int,
+	rsiz:           int,
+	mdlen:          int,
+	dsbyte:         byte,
 	is_initialized: bool,
 	is_finalized:   bool, // For SHAKE (unlimited squeeze is allowed)
 }
 
+@(private)
+keccakf_rndc := [?]u64 {
+	0x0000000000000001, 0x0000000000008082, 0x800000000000808a,
+	0x8000000080008000, 0x000000000000808b, 0x0000000080000001,
+	0x8000000080008081, 0x8000000000008009, 0x000000000000008a,
+	0x0000000000000088, 0x0000000080008009, 0x000000008000000a,
+	0x000000008000808b, 0x800000000000008b, 0x8000000000008089,
+	0x8000000000008003, 0x8000000000008002, 0x8000000000000080,
+	0x000000000000800a, 0x800000008000000a, 0x8000000080008081,
+	0x8000000000008080, 0x0000000080000001, 0x8000000080008008,
+}
+
+@(private)
+keccakf_rotc := [?]int {
+	1, 3, 6, 10, 15, 21, 28, 36, 45, 55, 2, 14,
+	27, 41, 56, 8, 25, 43, 62, 18, 39, 61, 20, 44,
+}
+
+@(private)
+keccakf_piln := [?]i32 {
+	10, 7, 11, 17, 18, 3, 5, 16, 8, 21, 24, 4,
+	15, 23, 19, 13, 12, 2, 20, 14, 22, 9, 6, 1,
+}
+
+@(private)
 keccakf :: proc "contextless" (st: ^[25]u64) {
-	keccakf_rndc := [?]u64 {
-		0x0000000000000001, 0x0000000000008082, 0x800000000000808a,
-		0x8000000080008000, 0x000000000000808b, 0x0000000080000001,
-		0x8000000080008081, 0x8000000000008009, 0x000000000000008a,
-		0x0000000000000088, 0x0000000080008009, 0x000000008000000a,
-		0x000000008000808b, 0x800000000000008b, 0x8000000000008089,
-		0x8000000000008003, 0x8000000000008002, 0x8000000000000080,
-		0x000000000000800a, 0x800000008000000a, 0x8000000080008081,
-		0x8000000000008080, 0x0000000080000001, 0x8000000080008008,
-	}
-
-	keccakf_rotc := [?]int {
-		1, 3, 6, 10, 15, 21, 28, 36, 45, 55, 2, 14,
-		27, 41, 56, 8, 25, 43, 62, 18, 39, 61, 20, 44,
-	}
-
-	keccakf_piln := [?]i32 {
-		10, 7, 11, 17, 18, 3, 5, 16, 8, 21, 24, 4,
-		15, 23, 19, 13, 12, 2, 20, 14, 22, 9, 6, 1,
-	}
-
 	i, j, r: i32 = ---, ---, ---
 	t: u64 = ---
 	bc: [5]u64 = ---
@@ -140,9 +153,6 @@ final :: proc(ctx: ^Context, hash: []byte, finalize_clone: bool = false) {
 	assert(ctx.is_initialized)
 
 	if len(hash) < ctx.mdlen {
-		if ctx.is_keccak {
-			panic("crypto/keccac: invalid destination digest size")
-		}
 		panic("crypto/sha3: invalid destination digest size")
 	}
 
@@ -152,13 +162,9 @@ final :: proc(ctx: ^Context, hash: []byte, finalize_clone: bool = false) {
 		clone(&tmp_ctx, ctx)
 		ctx = &tmp_ctx
 	}
-	defer(reset(ctx))
+	defer (reset(ctx))
 
-	if ctx.is_keccak {
-		ctx.st.b[ctx.pt] ~= 0x01
-	} else {
-		ctx.st.b[ctx.pt] ~= 0x06
-	}
+	ctx.st.b[ctx.pt] ~= ctx.dsbyte
 
 	ctx.st.b[ctx.rsiz - 1] ~= 0x80
 	keccakf(&ctx.st.q)
@@ -183,7 +189,7 @@ shake_xof :: proc(ctx: ^Context) {
 	assert(ctx.is_initialized)
 	assert(!ctx.is_finalized)
 
-	ctx.st.b[ctx.pt] ~= 0x1F
+	ctx.st.b[ctx.pt] ~= ctx.dsbyte
 	ctx.st.b[ctx.rsiz - 1] ~= 0x80
 	keccakf(&ctx.st.q)
 	ctx.pt = 0

core/crypto/_sha3/sp800_185.odin

@@ -0,0 +1,145 @@
+package _sha3
+
+import "core:encoding/endian"
+import "core:math/bits"
+
+init_cshake :: proc(ctx: ^Context, n, s: []byte, sec_strength: int) {
+	ctx.mdlen = sec_strength / 8
+
+	// No domain separator is equivalent to vanilla SHAKE.
+	if len(n) == 0 && len(s) == 0 {
+		ctx.dsbyte = DS_SHAKE
+		init(ctx)
+		return
+	}
+
+	ctx.dsbyte = DS_CSHAKE
+	init(ctx)
+	bytepad(ctx, [][]byte{n, s}, rate_cshake(sec_strength))
+}
+
+final_cshake :: proc(ctx: ^Context, dst: []byte, finalize_clone: bool = false) {
+	ctx := ctx
+	if finalize_clone {
+		tmp_ctx: Context
+		clone(&tmp_ctx, ctx)
+		ctx = &tmp_ctx
+	}
+	defer reset(ctx)
+
+	encode_byte_len(ctx, len(dst), false) // right_encode
+	shake_xof(ctx)
+	shake_out(ctx, dst)
+}
+
+rate_cshake :: #force_inline proc(sec_strength: int) -> int {
+	switch sec_strength {
+	case 128:
+		return RATE_128
+	case 256:
+		return RATE_256
+	}
+
+	panic("crypto/sha3: invalid security strength")
+}
+
+// right_encode and left_encode are defined to support 0 <= x < 2^2040
+// however, the largest value we will ever need to encode is `max(int) * 8`.
+//
+// This is unfortunate as the extreme upper edge is larger than
+// `max(u64)`.  While such values are impractical at present,
+// they are possible (ie: https://arxiv.org/pdf/quant-ph/9908043.pdf).
+//
+// Thus we support 0 <= x < 2^128.
+
+@(private)
+_PAD: [RATE_128]byte // Biggest possible value of w per spec.
+
+bytepad :: proc(ctx: ^Context, x_strings: [][]byte, w: int) {
+	// 1. z = left_encode(w) || X.
+	z_hi: u64
+	z_lo := left_right_encode(ctx, 0, u64(w), true)
+	for x in x_strings {
+		// All uses of bytepad in SP 800-185 use the output from
+		// one or more encode_string values for `X`.
+		hi, lo := encode_string(ctx, x)
+
+		carry: u64
+		z_lo, carry = bits.add_u64(z_lo, lo, 0)
+		z_hi, carry = bits.add_u64(z_hi, hi, carry)
+
+		// This isn't actually possible, at least with the currently
+		// defined SP 800-185 routines.
+		if carry != 0 {
+			panic("crypto/sha3: bytepad input length overflow")
+		}
+	}
+
+	// We skip this step as we are doing a byte-oriented implementation
+	// rather than a bit oriented one.
+	//
+	// 2. while len(z) mod 8 ≠ 0:
+	//    z = z || 0
+
+	// 3. while (len(z)/8) mod w ≠ 0:
+	//    z = z || 00000000
+	z_len := u128(z_hi) << 64 | u128(z_lo)
+	z_rem := int(z_len % u128(w))
+	pad := _PAD[:w - z_rem]
+
+	// We just add the padding to the state, instead of returning z.
+	//
+	// 4. return z.
+	update(ctx, pad)
+}
+
+encode_string :: #force_inline proc(ctx: ^Context, s: []byte) -> (u64, u64) {
+	l := encode_byte_len(ctx, len(s), true) // left_encode
+	update(ctx, s)
+
+	lo, hi := bits.add_u64(l, u64(len(s)), 0)
+
+	return hi, lo
+}
+
+encode_byte_len :: #force_inline proc(ctx: ^Context, l: int, is_left: bool) -> u64 {
+	hi, lo := bits.mul_u64(u64(l), 8)
+	return left_right_encode(ctx, hi, lo, is_left)
+}
+
+@(private)
+left_right_encode :: proc(ctx: ^Context, hi, lo: u64, is_left: bool) -> u64 {
+	HI_OFFSET :: 1
+	LO_OFFSET :: HI_OFFSET + 8
+	RIGHT_OFFSET :: LO_OFFSET + 8
+	BUF_LEN :: RIGHT_OFFSET + 1
+
+	buf: [BUF_LEN]byte // prefix + largest uint + postfix
+
+	endian.unchecked_put_u64be(buf[HI_OFFSET:], hi)
+	endian.unchecked_put_u64be(buf[LO_OFFSET:], lo)
+
+	// 2. Strip leading `0x00` bytes.
+	off: int
+	for off = HI_OFFSET; off < RIGHT_OFFSET - 1; off = off + 1 {// Note: Minimum size is 1, not 0.
+		if buf[off] != 0 {
+			break
+		}
+	}
+	n := byte(RIGHT_OFFSET - off)
+
+	// 3. Prefix (left_encode) or postfix (right_encode) the length in bytes.
+	b: []byte
+	switch is_left {
+	case true:
+		buf[off - 1] = n // n | x
+		b = buf[off - 1:RIGHT_OFFSET]
+	case false:
+		buf[RIGHT_OFFSET] = n // x | n
+		b = buf[off:]
+	}
+
+	update(ctx, b)
+
+	return u64(len(b))
+}

core/crypto/chacha20/chacha20.odin

@@ -1,11 +1,21 @@
+/*
+package chacha20 implements the ChaCha20 and XChaCha20 stream ciphers.
+
+See:
+- https://datatracker.ietf.org/doc/html/rfc8439
+- https://datatracker.ietf.org/doc/draft-irtf-cfrg-xchacha/03/
+*/
 package chacha20
 
 import "core:encoding/endian"
 import "core:math/bits"
 import "core:mem"
 
+// KEY_SIZE is the (X)ChaCha20 key size in bytes.
 KEY_SIZE :: 32
+// NONCE_SIZE is the ChaCha20 nonce size in bytes.
 NONCE_SIZE :: 12
+// XNONCE_SIZE is the XChaCha20 nonce size in bytes.
 XNONCE_SIZE :: 24
 
 @(private)
@@ -19,25 +29,26 @@ _STATE_SIZE_U32 :: 16
 _ROUNDS :: 20
 
 @(private)
-_SIGMA_0 : u32 : 0x61707865
+_SIGMA_0: u32 : 0x61707865
 @(private)
-_SIGMA_1 : u32 : 0x3320646e
+_SIGMA_1: u32 : 0x3320646e
 @(private)
-_SIGMA_2 : u32 : 0x79622d32
+_SIGMA_2: u32 : 0x79622d32
 @(private)
-_SIGMA_3 : u32 : 0x6b206574
+_SIGMA_3: u32 : 0x6b206574
 
+// Context is a ChaCha20 or XChaCha20 instance.
 Context :: struct {
-	_s: [_STATE_SIZE_U32]u32,
-
-	_buffer: [_BLOCK_SIZE]byte,
-	_off: int,
-
+	_s:              [_STATE_SIZE_U32]u32,
+	_buffer:         [_BLOCK_SIZE]byte,
+	_off:            int,
 	_is_ietf_flavor: bool,
 	_is_initialized: bool,
 }
 
-init :: proc (ctx: ^Context, key, nonce: []byte) {
+// init inititializes a Context for ChaCha20 or XChaCha20 with the provided
+// key and nonce.
+init :: proc(ctx: ^Context, key, nonce: []byte) {
 	if len(key) != KEY_SIZE {
 		panic("crypto/chacha20: invalid ChaCha20 key size")
 	}
@@ -89,7 +100,8 @@ init :: proc (ctx: ^Context, key, nonce: []byte) {
 	ctx._is_initialized = true
 }
 
-seek :: proc (ctx: ^Context, block_nr: u64) {
+// seek seeks the (X)ChaCha20 stream counter to the specified block.
+seek :: proc(ctx: ^Context, block_nr: u64) {
 	assert(ctx._is_initialized)
 
 	if ctx._is_ietf_flavor {
@@ -103,7 +115,10 @@ seek :: proc (ctx: ^Context, block_nr: u64) {
 	ctx._off = _BLOCK_SIZE
 }
 
-xor_bytes :: proc (ctx: ^Context, dst, src: []byte) {
+// xor_bytes XORs each byte in src with bytes taken from the (X)ChaCha20
+// keystream, and writes the resulting output to dst.  Dst and src MUST
+// alias exactly or not at all.
+xor_bytes :: proc(ctx: ^Context, dst, src: []byte) {
 	assert(ctx._is_initialized)
 
 	// TODO: Enforcing that dst and src alias exactly or not at all
@@ -147,7 +162,8 @@ xor_bytes :: proc (ctx: ^Context, dst, src: []byte) {
 	}
 }
 
-keystream_bytes :: proc (ctx: ^Context, dst: []byte) {
+// keystream_bytes fills dst with the raw (X)ChaCha20 keystream output.
+keystream_bytes :: proc(ctx: ^Context, dst: []byte) {
 	assert(ctx._is_initialized)
 
 	dst := dst
@@ -180,7 +196,9 @@ keystream_bytes :: proc (ctx: ^Context, dst: []byte) {
 	}
 }
 
-reset :: proc (ctx: ^Context) {
+// reset sanitizes the Context.  The Context must be re-initialized to
+// be used again.
+reset :: proc(ctx: ^Context) {
 	mem.zero_explicit(&ctx._s, size_of(ctx._s))
 	mem.zero_explicit(&ctx._buffer, size_of(ctx._buffer))
 
@@ -188,7 +206,7 @@ reset :: proc (ctx: ^Context) {
 }
 
 @(private)
-_do_blocks :: proc (ctx: ^Context, dst, src: []byte, nr_blocks: int) {
+_do_blocks :: proc(ctx: ^Context, dst, src: []byte, nr_blocks: int) {
 	// Enforce the maximum consumed keystream per nonce.
 	//
 	// While all modern "standard" definitions of ChaCha20 use

core/crypto/chacha20poly1305/chacha20poly1305.odin

@@ -1,3 +1,10 @@
+/*
+package chacha20poly1305 implements the AEAD_CHACHA20_POLY1305 Authenticated
+Encryption with Additional Data algorithm.
+
+See:
+- https://www.rfc-editor.org/rfc/rfc8439
+*/
 package chacha20poly1305
 
 import "core:crypto"
@@ -6,8 +13,11 @@ import "core:crypto/poly1305"
 import "core:encoding/endian"
 import "core:mem"
 
+// KEY_SIZE is the chacha20poly1305 key size in bytes.
 KEY_SIZE :: chacha20.KEY_SIZE
+// NONCE_SIZE is the chacha20poly1305 nonce size in bytes.
 NONCE_SIZE :: chacha20.NONCE_SIZE
+// TAG_SIZE is the chacha20poly1305 tag size in bytes.
 TAG_SIZE :: poly1305.TAG_SIZE
 
 @(private)
@@ -49,6 +59,8 @@ _update_mac_pad16 :: #force_inline proc (ctx: ^poly1305.Context, x_len: int) {
 	}
 }
 
+// encrypt encrypts the plaintext and authenticates the aad and ciphertext,
+// with the provided key and nonce, stores the output in ciphertext and tag.
 encrypt :: proc (ciphertext, tag, key, nonce, aad, plaintext: []byte) {
 	_validate_common_slice_sizes(tag, key, nonce, aad, plaintext)
 	if len(ciphertext) != len(plaintext) {
@@ -95,6 +107,11 @@ encrypt :: proc (ciphertext, tag, key, nonce, aad, plaintext: []byte) {
 	poly1305.final(&mac_ctx, tag) // Implicitly sanitizes context.
 }
 
+// decrypt authenticates the aad and ciphertext, and decrypts the ciphertext,
+// with the provided key, nonce, and tag, and stores the output in plaintext,
+// returning true iff the authentication was successful.
+//
+// If authentication fails, the destination plaintext buffer will be zeroed.
 decrypt :: proc (plaintext, tag, key, nonce, aad, ciphertext: []byte) -> bool {
 	_validate_common_slice_sizes(tag, key, nonce, aad, ciphertext)
 	if len(ciphertext) != len(plaintext) {

core/crypto/hkdf/hkdf.odin

@@ -0,0 +1,103 @@
+/*
+package hkdf implements the HKDF HMAC-based Extract-and-Expand Key
+Derivation Function.
+
+See: https://www.rfc-editor.org/rfc/rfc5869
+*/
+package hkdf
+
+import "core:crypto/hash"
+import "core:crypto/hmac"
+import "core:mem"
+
+// extract_and_expand derives output keying material (OKM) via the
+// HKDF-Extract and HKDF-Expand algorithms, with the specified has
+// function, salt, input keying material (IKM), and optional info.
+// The dst buffer must be less-than-or-equal to 255 HMAC tags.
+extract_and_expand :: proc(algorithm: hash.Algorithm, salt, ikm, info, dst: []byte) {
+	h_len := hash.DIGEST_SIZES[algorithm]
+
+	tmp: [hash.MAX_DIGEST_SIZE]byte
+	prk := tmp[:h_len]
+	defer mem.zero_explicit(raw_data(prk), h_len)
+
+	extract(algorithm, salt, ikm, prk)
+	expand(algorithm, prk, info, dst)
+}
+
+// extract derives a pseudorandom key (PRK) via the HKDF-Extract algorithm,
+// with the specified hash function, salt, and input keying material (IKM).
+// It requires that the dst buffer be the HMAC tag size for the specified
+// hash function.
+extract :: proc(algorithm: hash.Algorithm, salt, ikm, dst: []byte) {
+	// PRK = HMAC-Hash(salt, IKM)
+	hmac.sum(algorithm, dst, ikm, salt)
+}
+
+// expand derives output keying material (OKM) via the HKDF-Expand algorithm,
+// with the specified hash function, pseudorandom key (PRK), and optional
+// info.  The dst buffer must be less-than-or-equal to 255 HMAC tags.
+expand :: proc(algorithm: hash.Algorithm, prk, info, dst: []byte) {
+	h_len := hash.DIGEST_SIZES[algorithm]
+
+	// (<= 255*HashLen)
+	dk_len := len(dst)
+	switch {
+	case dk_len == 0:
+		return
+	case dk_len > h_len * 255:
+		panic("crypto/hkdf: derived key too long")
+	case:
+	}
+
+	// The output OKM is calculated as follows:
+	//
+	// N = ceil(L/HashLen)
+	// T = T(1) | T(2) | T(3) | ... | T(N)
+	// OKM = first L octets of T
+	//
+	// where:
+	// T(0) = empty string (zero length)
+	// T(1) = HMAC-Hash(PRK, T(0) | info | 0x01)
+	// T(2) = HMAC-Hash(PRK, T(1) | info | 0x02)
+	// T(3) = HMAC-Hash(PRK, T(2) | info | 0x03)
+	// ...
+
+	n := dk_len / h_len
+	r := dk_len % h_len
+
+	base: hmac.Context
+	defer hmac.reset(&base)
+
+	hmac.init(&base, algorithm, prk)
+
+	dst_blk := dst
+	prev: []byte
+
+	for i in 1 ..= n {
+		_F(&base, prev, info, i, dst_blk[:h_len])
+
+		prev = dst_blk[:h_len]
+		dst_blk = dst_blk[h_len:]
+	}
+
+	if r > 0 {
+		tmp: [hash.MAX_DIGEST_SIZE]byte
+		blk := tmp[:h_len]
+		defer mem.zero_explicit(raw_data(blk), h_len)
+
+		_F(&base, prev, info, n + 1, blk)
+		copy(dst_blk, blk)
+	}
+}
+
+@(private)
+_F :: proc(base: ^hmac.Context, prev, info: []byte, i: int, dst_blk: []byte) {
+	prf: hmac.Context
+
+	hmac.clone(&prf, base)
+	hmac.update(&prf, prev)
+	hmac.update(&prf, info)
+	hmac.update(&prf, []byte{u8(i)})
+	hmac.final(&prf, dst_blk)
+}

core/crypto/hmac/hmac.odin

@@ -11,7 +11,7 @@ import "core:crypto/hash"
 import "core:mem"
 
 // sum will compute the HMAC with the specified algorithm and key
-// over msg, and write the computed digest to dst.  It requires that
+// over msg, and write the computed tag to dst.  It requires that
 // the dst buffer is the tag size.
 sum :: proc(algorithm: hash.Algorithm, dst, msg, key: []byte) {
 	ctx: Context
@@ -78,6 +78,18 @@ final :: proc(ctx: ^Context, dst: []byte) {
 	hash.final(&ctx._o_hash, dst)
 }
 
+// clone clones the Context other into ctx.
+clone :: proc(ctx, other: ^Context) {
+	if ctx == other {
+		return
+	}
+
+	hash.clone(&ctx._o_hash, &other._o_hash)
+	hash.clone(&ctx._i_hash, &other._i_hash)
+	ctx._tag_sz = other._tag_sz
+	ctx._is_initialized = other._is_initialized
+}
+
 // reset sanitizes the Context.  The Context must be re-initialized to
 // be used again.
 reset :: proc(ctx: ^Context) {

core/crypto/kmac/kmac.odin

@@ -0,0 +1,116 @@
+/*
+package kmac implements the KMAC MAC algorithm.
+
+See:
+- https://nvlpubs.nist.gov/nistpubs/specialpublications/nist.sp.800-185.pdf
+*/
+package kmac
+
+import "../_sha3"
+import "core:crypto"
+import "core:crypto/shake"
+
+// MIN_KEY_SIZE_128 is the minimum key size for KMAC128 in bytes.
+MIN_KEY_SIZE_128 :: 128 / 8
+// MIN_KEY_SIZE_256 is the minimum key size for KMAC256 in bytes.
+MIN_KEY_SIZE_256 :: 256 / 8
+
+// MIN_TAG_SIZE is the absolute minimum tag size for KMAC in bytes (8.4.2).
+// Most callers SHOULD use at least 128-bits if not 256-bits for the tag
+// size.
+MIN_TAG_SIZE :: 32 / 8
+
+// sum will compute the KMAC with the specified security strength,
+// key, and domain separator over msg, and write the computed digest to
+// dst.
+sum :: proc(sec_strength: int, dst, msg, key, domain_sep: []byte) {
+	ctx: Context
+
+	_init_kmac(&ctx, key, domain_sep, sec_strength)
+	update(&ctx, msg)
+	final(&ctx, dst)
+}
+
+// verify will verify the KMAC tag computed with the specified security
+// strength, key and domain separator over msg and return true iff the
+// tag is valid.
+verify :: proc(sec_strength: int, tag, msg, key, domain_sep: []byte, allocator := context.temp_allocator) -> bool {
+	derived_tag := make([]byte, len(tag), allocator)
+
+	sum(sec_strength, derived_tag, msg, key, domain_sep)
+
+	return crypto.compare_constant_time(derived_tag, tag) == 1
+}
+
+// Context is a KMAC instance.
+Context :: distinct shake.Context
+
+// init_128 initializes a Context for KMAC28.  This routine will panic if
+// the key length is less than MIN_KEY_SIZE_128.
+init_128 :: proc(ctx: ^Context, key, domain_sep: []byte) {
+	_init_kmac(ctx, key, domain_sep, 128)
+}
+
+// init_256 initializes a Context for KMAC256.  This routine will panic if
+// the key length is less than MIN_KEY_SIZE_256.
+init_256 :: proc(ctx: ^Context, key, domain_sep: []byte) {
+	_init_kmac(ctx, key, domain_sep, 256)
+}
+
+// update adds more data to the Context.
+update :: proc(ctx: ^Context, data: []byte) {
+	assert(ctx.is_initialized)
+
+	shake.write(transmute(^shake.Context)(ctx), data)
+}
+
+// final finalizes the Context, writes the tag to dst, and calls reset
+// on the Context.  This routine will panic if the dst length is less than
+// MIN_TAG_SIZE.
+final :: proc(ctx: ^Context, dst: []byte) {
+	assert(ctx.is_initialized)
+	defer reset(ctx)
+
+	if len(dst) < MIN_TAG_SIZE {
+		panic("crypto/kmac: invalid KMAC tag_size, too short")
+	}
+
+	_sha3.final_cshake(transmute(^_sha3.Context)(ctx), dst)
+}
+
+// clone clones the Context other into ctx.
+clone :: proc(ctx, other: ^Context) {
+	if ctx == other {
+		return
+	}
+
+	shake.clone(transmute(^shake.Context)(ctx), transmute(^shake.Context)(other))
+}
+
+// reset sanitizes the Context.  The Context must be re-initialized to
+// be used again.
+reset :: proc(ctx: ^Context) {
+	if !ctx.is_initialized {
+		return
+	}
+
+	shake.reset(transmute(^shake.Context)(ctx))
+}
+
+@(private)
+_init_kmac :: proc(ctx: ^Context, key, s: []byte, sec_strength: int) {
+	if ctx.is_initialized {
+		reset(ctx)
+	}
+
+	if len(key) < sec_strength / 8 {
+		panic("crypto/kmac: invalid KMAC key, too short")
+	}
+
+	ctx_ := transmute(^_sha3.Context)(ctx)
+	_sha3.init_cshake(ctx_, N_KMAC, s, sec_strength)
+	_sha3.bytepad(ctx_, [][]byte{key}, _sha3.rate_cshake(sec_strength))
+}
+
+@(private)
+N_KMAC := []byte{'K', 'M', 'A', 'C'}

core/crypto/legacy/keccak/keccak.odin

@@ -65,7 +65,7 @@ init_512 :: proc(ctx: ^Context) {
 
 @(private)
 _init :: proc(ctx: ^Context) {
-	ctx.is_keccak = true
+	ctx.dsbyte = _sha3.DS_KECCAK
 	_sha3.init(transmute(^_sha3.Context)(ctx))
 }
 

core/crypto/pbkdf2/pbkdf2.odin

@@ -0,0 +1,122 @@
+/*
+package pbkdf2 implements the PBKDF2 password-based key derivation function.
+
+See: https://www.rfc-editor.org/rfc/rfc2898
+*/
+package pbkdf2
+
+import "core:crypto/hash"
+import "core:crypto/hmac"
+import "core:encoding/endian"
+import "core:mem"
+
+// derive invokes PBKDF2-HMAC with the specified hash algorithm, password,
+// salt, iteration count, and outputs the derived key to dst.
+derive :: proc(
+	hmac_hash: hash.Algorithm,
+	password: []byte,
+	salt: []byte,
+	iterations: u32,
+	dst: []byte,
+) {
+	h_len := hash.DIGEST_SIZES[hmac_hash]
+
+	// 1. If dkLen > (2^32 - 1) * hLen, output "derived key too long"
+	// and stop.
+
+	dk_len := len(dst)
+	switch {
+	case dk_len == 0:
+		return
+	case u64(dk_len) > u64(max(u32)) * u64(h_len):
+		// This is so beyond anything that is practical or reasonable,
+		// so just panic instead of returning an error.
+		panic("crypto/pbkdf2: derived key too long")
+	case:
+	}
+
+	// 2. Let l be the number of hLen-octet blocks in the derived key,
+	// rounding up, and let r be the number of octets in the last block.
+
+	l := dk_len / h_len // Don't need to round up.
+	r := dk_len % h_len
+
+	// 3. For each block of the derived key apply the function F defined
+	// below to the password P, the salt S, the iteration count c, and
+	// the block index to compute the block.
+	//
+	// 4. Concatenate the blocks and extract the first dkLen octets to
+	// produce a derived key DK.
+	//
+	// 5. Output the derived key DK.
+
+	// Each iteration of F is always `PRF (P, ...)`, so instantiate the
+	// PRF, and clone since memcpy is faster than having to re-initialize
+	// HMAC repeatedly.
+
+	base: hmac.Context
+	defer hmac.reset(&base)
+
+	hmac.init(&base, hmac_hash, password)
+
+	// Process all of the blocks that will be written directly to dst.
+	dst_blk := dst
+	for i in 1 ..= l { 	// F expects i starting at 1.
+		_F(&base, salt, iterations, u32(i), dst_blk[:h_len])
+		dst_blk = dst_blk[h_len:]
+	}
+
+	// Instead of rounding l up, just proceass the one extra block iff
+	// r != 0.
+	if r > 0 {
+		tmp: [hash.MAX_DIGEST_SIZE]byte
+		blk := tmp[:h_len]
+		defer mem.zero_explicit(raw_data(blk), h_len)
+
+		_F(&base, salt, iterations, u32(l + 1), blk)
+		copy(dst_blk, blk)
+	}
+}
+
+@(private)
+_F :: proc(base: ^hmac.Context, salt: []byte, c: u32, i: u32, dst_blk: []byte) {
+	h_len := len(dst_blk)
+
+	tmp: [hash.MAX_DIGEST_SIZE]byte
+	u := tmp[:h_len]
+	defer mem.zero_explicit(raw_data(u), h_len)
+
+	// F (P, S, c, i) = U_1 \xor U_2 \xor ... \xor U_c
+	//
+	// where
+	//
+	// U_1 = PRF (P, S || INT (i)) ,
+	// U_2 = PRF (P, U_1) ,
+	// ...
+	// U_c = PRF (P, U_{c-1}) .
+	//
+	// Here, INT (i) is a four-octet encoding of the integer i, most
+	// significant octet first.
+
+	prf: hmac.Context
+
+	// U_1: PRF (P, S || INT (i))
+	hmac.clone(&prf, base)
+	hmac.update(&prf, salt)
+	endian.unchecked_put_u32be(u, i) // Use u as scratch space.
+	hmac.update(&prf, u[:4])
+	hmac.final(&prf, u)
+	copy(dst_blk, u)
+
+	// U_2 ... U_c: U_n = PRF (P, U_(n-1))
+	for _ in 1 ..< c {
+		hmac.clone(&prf, base)
+		hmac.update(&prf, u)
+		hmac.final(&prf, u)
+
+		// XOR dst_blk and u.
+		for v, i in u {
+			dst_blk[i] ~= v
+		}
+	}
+}

core/crypto/poly1305/poly1305.odin

@@ -1,3 +1,9 @@
+/*
+package poly1305 implements the Poly1305 one-time MAC algorithm.
+
+See:
+- https://datatracker.ietf.org/doc/html/rfc8439
+*/
 package poly1305
 
 import "core:crypto"
@@ -5,13 +11,20 @@ import field "core:crypto/_fiat/field_poly1305"
 import "core:encoding/endian"
 import "core:mem"
 
+// KEY_SIZE is the Poly1305 key size in bytes.
 KEY_SIZE :: 32
+// TAG_SIZE is the Poly1305 tag size in bytes.
 TAG_SIZE :: 16
 
 @(private)
 _BLOCK_SIZE :: 16
 
-sum :: proc (dst, msg, key: []byte) {
+// sum will compute the Poly1305 MAC with the key over msg, and write
+// the computed tag to dst.  It requires that the dst buffer is the tag
+// size.
+//
+// The key SHOULD be unique and MUST be unpredictable for each invocation.
+sum :: proc(dst, msg, key: []byte) {
 	ctx: Context = ---
 
 	init(&ctx, key)
@@ -19,9 +32,12 @@ sum :: proc (dst, msg, key: []byte) {
 	final(&ctx, dst)
 }
 
-verify :: proc (tag, msg, key: []byte) -> bool {
+// verify will verify the Poly1305 tag computed with the key over msg and
+// return true iff the tag is valid.  It requires that the tag is correctly
+// sized.
+verify :: proc(tag, msg, key: []byte) -> bool {
 	ctx: Context = ---
-	derived_tag: [16]byte = ---
+	derived_tag: [TAG_SIZE]byte = ---
 
 	init(&ctx, key)
 	update(&ctx, msg)
@@ -30,18 +46,19 @@ verify :: proc (tag, msg, key: []byte) -> bool {
 	return crypto.compare_constant_time(derived_tag[:], tag) == 1
 }
 
+// Context is a Poly1305 instance.
 Context :: struct {
-	_r: field.Tight_Field_Element,
-	_a: field.Tight_Field_Element,
-	_s: field.Tight_Field_Element,
-
-	_buffer: [_BLOCK_SIZE]byte,
-	_leftover: int,
-
+	_r:              field.Tight_Field_Element,
+	_a:              field.Tight_Field_Element,
+	_s:              field.Tight_Field_Element,
+	_buffer:         [_BLOCK_SIZE]byte,
+	_leftover:       int,
 	_is_initialized: bool,
 }
 
-init :: proc (ctx: ^Context, key: []byte) {
+// init initializes a Context with the specified key.  The key SHOULD be
+// unique and MUST be unpredictable for each invocation.
+init :: proc(ctx: ^Context, key: []byte) {
 	if len(key) != KEY_SIZE {
 		panic("crypto/poly1305: invalid key size")
 	}
@@ -64,7 +81,8 @@ init :: proc (ctx: ^Context, key: []byte) {
 	ctx._is_initialized = true
 }
 
-update :: proc (ctx: ^Context, data: []byte) {
+// update adds more data to the Context.
+update :: proc(ctx: ^Context, data: []byte) {
 	assert(ctx._is_initialized)
 
 	msg := data
@@ -101,8 +119,11 @@ update :: proc (ctx: ^Context, data: []byte) {
 	}
 }
 
-final :: proc (ctx: ^Context, dst: []byte) {
+// final finalizes the Context, writes the tag to dst, and calls
+// reset on the Context.
+final :: proc(ctx: ^Context, dst: []byte) {
 	assert(ctx._is_initialized)
+	defer reset(ctx)
 
 	if len(dst) != TAG_SIZE {
 		panic("poly1305: invalid destination tag size")
@@ -125,11 +146,11 @@ final :: proc (ctx: ^Context, dst: []byte) {
 	tmp: [32]byte = ---
 	field.fe_to_bytes(&tmp, &ctx._a)
 	copy_slice(dst, tmp[0:16])
-
-	reset(ctx)
 }
 
-reset :: proc (ctx: ^Context) {
+// reset sanitizes the Context.  The Context must be re-initialized to
+// be used again.
+reset :: proc(ctx: ^Context) {
 	mem.zero_explicit(&ctx._r, size_of(ctx._r))
 	mem.zero_explicit(&ctx._a, size_of(ctx._a))
 	mem.zero_explicit(&ctx._s, size_of(ctx._s))
@@ -139,7 +160,7 @@ reset :: proc (ctx: ^Context) {
 }
 
 @(private)
-_blocks :: proc (ctx: ^Context, msg: []byte, final := false) {
+_blocks :: proc(ctx: ^Context, msg: []byte, final := false) {
 	n: field.Tight_Field_Element = ---
 	final_byte := byte(!final)
 

core/crypto/sha3/sha3.odin

@@ -67,6 +67,7 @@ init_512 :: proc(ctx: ^Context) {
 
 @(private)
 _init :: proc(ctx: ^Context) {
+	ctx.dsbyte = _sha3.DS_SHA3
 	_sha3.init(transmute(^_sha3.Context)(ctx))
 }
 

core/crypto/shake/shake.odin

@@ -1,10 +1,11 @@
 /*
-package shake implements the SHAKE XOF algorithm family.
+package shake implements the SHAKE and cSHAKE XOF algorithm families.
 
 The SHA3 hash algorithm can be found in the crypto/sha3.
 
 See:
 - https://nvlpubs.nist.gov/nistpubs/fips/nist.fips.202.pdf
+- https://nvlpubs.nist.gov/nistpubs/specialpublications/nist.sp.800-185.pdf
 */
 package shake
 
@@ -18,24 +19,27 @@ package shake
 
 import "../_sha3"
 
-// Context is a SHAKE128 or SHAKE256 instance.
+// Context is a SHAKE128, SHAKE256, cSHAKE128, or cSHAKE256 instance.
 Context :: distinct _sha3.Context
 
 // init_128 initializes a Context for SHAKE128.
 init_128 :: proc(ctx: ^Context) {
-	ctx.mdlen = 128 / 8
-	_init(ctx)
+	_sha3.init_cshake(transmute(^_sha3.Context)(ctx), nil, nil, 128)
 }
 
 // init_256 initializes a Context for SHAKE256.
 init_256 :: proc(ctx: ^Context) {
-	ctx.mdlen = 256 / 8
-	_init(ctx)
+	_sha3.init_cshake(transmute(^_sha3.Context)(ctx), nil, nil, 256)
 }
 
-@(private)
-_init :: proc(ctx: ^Context) {
-	_sha3.init(transmute(^_sha3.Context)(ctx))
+// init_cshake_128 initializes a Context for cSHAKE128.
+init_cshake_128 :: proc(ctx: ^Context, domain_sep: []byte) {
+	_sha3.init_cshake(transmute(^_sha3.Context)(ctx), nil, domain_sep, 128)
+}
+
+// init_cshake_256 initializes a Context for cSHAKE256.
+init_cshake_256 :: proc(ctx: ^Context, domain_sep: []byte) {
+	_sha3.init_cshake(transmute(^_sha3.Context)(ctx), nil, domain_sep, 256)
 }
 
 // write writes more data into the SHAKE instance.  This MUST not be called

core/crypto/tuplehash/tuplehash.odin

@@ -0,0 +1,66 @@
+/*
+package tuplehash implements the TupleHash and TupleHashXOF algorithms.
+
+See:
+- https://nvlpubs.nist.gov/nistpubs/specialpublications/nist.sp.800-185.pdf
+*/
+package tuplehash
+
+import "../_sha3"
+
+// Context is a TupleHash or TupleHashXOF instance.
+Context :: distinct _sha3.Context
+
+// init_128 initializes a Context for TupleHash128 or TupleHashXOF128.
+init_128 :: proc(ctx: ^Context, domain_sep: []byte) {
+	_sha3.init_cshake(transmute(^_sha3.Context)(ctx), N_TUPLEHASH, domain_sep, 128)
+}
+
+// init_256 initializes a Context for TupleHash256 or TupleHashXOF256.
+init_256 :: proc(ctx: ^Context, domain_sep: []byte) {
+	_sha3.init_cshake(transmute(^_sha3.Context)(ctx), N_TUPLEHASH, domain_sep, 256)
+}
+
+// write_element writes a tuple element into the TupleHash or TupleHashXOF
+// instance.  This MUST not be called after any reads have been done, and
+// any attempts to do so will panic.
+write_element :: proc(ctx: ^Context, data: []byte) {
+	_, _ = _sha3.encode_string(transmute(^_sha3.Context)(ctx), data)
+}
+
+// final finalizes the Context, writes the digest to hash, and calls
+// reset on the Context.
+//
+// Iff finalize_clone is set, final will work on a copy of the Context,
+// which is useful for for calculating rolling digests.
+final :: proc(ctx: ^Context, hash: []byte, finalize_clone: bool = false) {
+	_sha3.final_cshake(transmute(^_sha3.Context)(ctx), hash, finalize_clone)
+}
+
+// read reads output from the TupleHashXOF instance.  There is no practical
+// upper limit to the amount of data that can be read from TupleHashXOF.
+// After read has been called one or more times, further calls to
+// write_element will panic.
+read :: proc(ctx: ^Context, dst: []byte) {
+	ctx_ := transmute(^_sha3.Context)(ctx)
+	if !ctx.is_finalized {
+		_sha3.encode_byte_len(ctx_, 0, false) // right_encode
+		_sha3.shake_xof(ctx_)
+	}
+
+	_sha3.shake_out(ctx_, dst)
+}
+
+// clone clones the Context other into ctx.
+clone :: proc(ctx, other: ^Context) {
+	_sha3.clone(transmute(^_sha3.Context)(ctx), transmute(^_sha3.Context)(other))
+}
+
+// reset sanitizes the Context.  The Context must be re-initialized to
+// be used again.
+reset :: proc(ctx: ^Context) {
+	_sha3.reset(transmute(^_sha3.Context)(ctx))
+}
+
+@(private)
+N_TUPLEHASH := []byte{'T', 'u', 'p', 'l', 'e', 'H', 'a', 's', 'h'}

core/crypto/x25519/x25519.odin

@@ -1,9 +1,18 @@
+/*
+package x25519 implements the X25519 (aka curve25519) Elliptic-Curve
+Diffie-Hellman key exchange protocol.
+
+See:
+- https://www.rfc-editor.org/rfc/rfc7748
+*/
 package x25519
 
 import field "core:crypto/_fiat/field_curve25519"
 import "core:mem"
 
+// SCALAR_SIZE is the size of a X25519 scalar (private key) in bytes.
 SCALAR_SIZE :: 32
+// POINT_SIZE is the size of a X25519 point (public key/shared secret) in bytes.
 POINT_SIZE :: 32
 
 @(private)
@@ -14,11 +23,11 @@ _scalar_bit :: #force_inline proc "contextless" (s: ^[32]byte, i: int) -> u8 {
 	if i < 0 {
 		return 0
 	}
-	return (s[i>>3] >> uint(i&7)) & 1
+	return (s[i >> 3] >> uint(i & 7)) & 1
 }
 
 @(private)
-_scalarmult :: proc (out, scalar, point: ^[32]byte) {
+_scalarmult :: proc(out, scalar, point: ^[32]byte) {
 	// Montgomery pseduo-multiplication taken from Monocypher.
 
 	// computes the scalar product
@@ -26,7 +35,7 @@ _scalarmult :: proc (out, scalar, point: ^[32]byte) {
 	field.fe_from_bytes(&x1, point)
 
 	// computes the actual scalar product (the result is in x2 and z2)
-	x2, x3, z2, z3: field.Tight_Field_Element =  ---, ---, ---, ---
+	x2, x3, z2, z3: field.Tight_Field_Element = ---, ---, ---, ---
 	t0, t1: field.Loose_Field_Element = ---, ---
 
 	// Montgomery ladder
@@ -38,7 +47,7 @@ _scalarmult :: proc (out, scalar, point: ^[32]byte) {
 	field.fe_one(&z3)
 
 	swap: int
-	for pos := 255-1; pos >= 0; pos = pos - 1 	{
+	for pos := 255 - 1; pos >= 0; pos = pos - 1 {
 		// constant time conditional swap before ladder step
 		b := int(_scalar_bit(scalar, pos))
 		swap ~= b // xor trick avoids swapping at the end of the loop
@@ -94,7 +103,9 @@ _scalarmult :: proc (out, scalar, point: ^[32]byte) {
 	mem.zero_explicit(&t1, size_of(t1))
 }
 
-scalarmult :: proc (dst, scalar, point: []byte) {
+// scalarmult "multiplies" the provided scalar and point, and writes the
+// resulting point to dst.
+scalarmult :: proc(dst, scalar, point: []byte) {
 	if len(scalar) != SCALAR_SIZE {
 		panic("crypto/x25519: invalid scalar size")
 	}
@@ -123,7 +134,9 @@ scalarmult :: proc (dst, scalar, point: []byte) {
 	mem.zero_explicit(&d, size_of(d))
 }
 
-scalarmult_basepoint :: proc (dst, scalar: []byte) {
+// scalarmult_basepoint "multiplies" the provided scalar with the X25519
+// base point and writes the resulting point to dst.
+scalarmult_basepoint :: proc(dst, scalar: []byte) {
 	// TODO/perf: Switch to using a precomputed table.
 	scalarmult(dst, scalar, _BASE_POINT[:])
 }

core/encoding/json/marshal.odin

@@ -51,6 +51,11 @@ Marshal_Options :: struct {
 	// NOTE: This will temp allocate and sort a list for each map.
 	sort_maps_by_key: bool,
 
+	// Output enum value's name instead of its underlying value.
+	//
+	// NOTE: If a name isn't found it'll use the underlying value.
+	use_enum_names: bool,
+
 	// Internal state
 	indentation: int,
 	mjson_skipped_first_braces_start: bool,
@@ -365,8 +370,10 @@ marshal_to_writer :: proc(w: io.Writer, v: any, opt: ^Marshal_Options) -> (err:
 		opt_write_start(w, opt, '{') or_return
 		
 		for name, i in info.names {
+			json_name := reflect.struct_tag_get(reflect.Struct_Tag(info.tags[i]), "json")
+
 			opt_write_iteration(w, opt, i) or_return
-			if json_name := string(reflect.struct_tag_get(auto_cast info.tags[i], "json")); json_name != "" {
+			if json_name != "" {
 				opt_write_key(w, opt, json_name) or_return
 			} else {
 				opt_write_key(w, opt, name) or_return
@@ -380,6 +387,11 @@ marshal_to_writer :: proc(w: io.Writer, v: any, opt: ^Marshal_Options) -> (err:
 		opt_write_end(w, opt, '}') or_return
 
 	case runtime.Type_Info_Union:
+		if len(info.variants) == 0 || v.data == nil {
+			io.write_string(w, "null") or_return
+			return nil
+		}
+
 		tag_ptr := uintptr(v.data) + info.tag_offset
 		tag_any := any{rawptr(tag_ptr), info.tag_type.id}
 
@@ -404,7 +416,16 @@ marshal_to_writer :: proc(w: io.Writer, v: any, opt: ^Marshal_Options) -> (err:
 		}
 
 	case runtime.Type_Info_Enum:
-		return marshal_to_writer(w, any{v.data, info.base.id}, opt)
+		if !opt.use_enum_names || len(info.names) == 0 {
+			return marshal_to_writer(w, any{v.data, info.base.id}, opt)
+		} else {
+			name, found := reflect.enum_name_from_value_any(v)
+			if found {
+				return marshal_to_writer(w, name, opt)
+			} else {
+				return marshal_to_writer(w, any{v.data, info.base.id}, opt)
+			}
+		}
 
 	case runtime.Type_Info_Bit_Set:
 		is_bit_set_different_endian_to_platform :: proc(ti: ^runtime.Type_Info) -> bool {

core/encoding/json/parser.odin

@@ -204,8 +204,8 @@ parse_array :: proc(p: ^Parser) -> (value: Value, err: Error) {
 }
 
 @(private)
-bytes_make :: proc(size, alignment: int, allocator: mem.Allocator) -> (bytes: []byte, err: Error) {
-	b, berr := mem.alloc_bytes(size, alignment, allocator)
+bytes_make :: proc(size, alignment: int, allocator: mem.Allocator, loc := #caller_location) -> (bytes: []byte, err: Error) {
+	b, berr := mem.alloc_bytes(size, alignment, allocator, loc)
 	if berr != nil {
 		if berr == .Out_Of_Memory {
 			err = .Out_Of_Memory
@@ -217,9 +217,9 @@ bytes_make :: proc(size, alignment: int, allocator: mem.Allocator) -> (bytes: []
 	return
 }
 
-clone_string :: proc(s: string, allocator: mem.Allocator) -> (str: string, err: Error) {
+clone_string :: proc(s: string, allocator: mem.Allocator, loc := #caller_location) -> (str: string, err: Error) {
 	n := len(s)
-	b := bytes_make(n+1, 1, allocator) or_return
+	b := bytes_make(n+1, 1, allocator, loc) or_return
 	copy(b, s)
 	if len(b) > n {
 		b[n] = 0
@@ -290,7 +290,7 @@ parse_object :: proc(p: ^Parser) -> (value: Value, err: Error) {
 
 
 // IMPORTANT NOTE(bill): unquote_string assumes a mostly valid string
-unquote_string :: proc(token: Token, spec: Specification, allocator := context.allocator) -> (value: string, err: Error) {
+unquote_string :: proc(token: Token, spec: Specification, allocator := context.allocator, loc := #caller_location) -> (value: string, err: Error) {
 	get_u2_rune :: proc(s: string) -> rune {
 		if len(s) < 4 || s[0] != '\\' || s[1] != 'x' {
 			return -1
@@ -359,7 +359,7 @@ unquote_string :: proc(token: Token, spec: Specification, allocator := context.a
 		i += w
 	}
 	if i == len(s) {
-		return clone_string(s, allocator)
+		return clone_string(s, allocator, loc)
 	}
 
 	b := bytes_make(len(s) + 2*utf8.UTF_MAX, 1, allocator) or_return

core/encoding/json/unmarshal.odin

@@ -6,6 +6,7 @@ import "core:reflect"
 import "core:strconv"
 import "core:strings"
 import "base:runtime"
+import "base:intrinsics"
 
 Unmarshal_Data_Error :: enum {
 	Invalid_Data,
@@ -368,11 +369,17 @@ unmarshal_object :: proc(p: ^Parser, v: any, end_token: Token_Kind) -> (err: Unm
 			unmarshal_expect_token(p, .Colon)						
 			
 			fields := reflect.struct_fields_zipped(ti.id)
-			
-			runtime.DEFAULT_TEMP_ALLOCATOR_TEMP_GUARD(ignore = context.temp_allocator == context.allocator)
 
-			field_used := make([]bool, len(fields), context.temp_allocator)
-			
+			field_test :: #force_inline proc "contextless" (field_used: [^]byte, index: int) -> bool {
+				prev_set := field_used[index/8] & byte(index&7) != 0
+				field_used[index/8] |= byte(index&7)
+				return prev_set
+			}
+
+			field_used_bytes := (len(fields)+7)/8
+			field_used := intrinsics.alloca(field_used_bytes, 1)
+			intrinsics.mem_zero(field_used, field_used_bytes)
+
 			use_field_idx := -1
 			
 			for field, field_idx in fields {
@@ -393,10 +400,9 @@ unmarshal_object :: proc(p: ^Parser, v: any, end_token: Token_Kind) -> (err: Unm
 			}
 			
 			if use_field_idx >= 0 {
-				if field_used[use_field_idx] {
+				if field_test(field_used, use_field_idx) {
 					return .Multiple_Use_Field
 				}
-				field_used[use_field_idx] = true
 				offset := fields[use_field_idx].offset
 				type := fields[use_field_idx].type
 				name := fields[use_field_idx].name
@@ -411,6 +417,12 @@ unmarshal_object :: proc(p: ^Parser, v: any, end_token: Token_Kind) -> (err: Unm
 				continue struct_loop
 			} else {
 				// allows skipping unused struct fields
+
+				// NOTE(bill): prevent possible memory leak if a string is unquoted
+				allocator := p.allocator
+				defer p.allocator = allocator
+				p.allocator = mem.nil_allocator()
+
 				parse_value(p) or_return
 				if parse_comma(p) {
 					break struct_loop

core/mem/allocators.odin

@@ -84,11 +84,11 @@ arena_allocator_proc :: proc(allocator_data: rawptr, mode: Allocator_Mode,
 	case .Free_All:
 		arena.offset = 0
 
-    case .Resize:
-        return default_resize_bytes_align(byte_slice(old_memory, old_size), size, alignment, arena_allocator(arena))
+	case .Resize:
+		return default_resize_bytes_align(byte_slice(old_memory, old_size), size, alignment, arena_allocator(arena))
 
-    case .Resize_Non_Zeroed:
-        return default_resize_bytes_align_non_zeroed(byte_slice(old_memory, old_size), size, alignment, arena_allocator(arena))
+	case .Resize_Non_Zeroed:
+		return default_resize_bytes_align_non_zeroed(byte_slice(old_memory, old_size), size, alignment, arena_allocator(arena))
 
 	case .Query_Features:
 		set := (^Allocator_Mode_Set)(old_memory)
@@ -860,3 +860,282 @@ panic_allocator :: proc() -> Allocator {
 		data = nil,
 	}
 }
+
+
+
+
+
+
+Buddy_Block :: struct #align(align_of(uint)) {
+	size:    uint,
+	is_free: bool,
+}
+
+@(require_results)
+buddy_block_next :: proc(block: ^Buddy_Block) -> ^Buddy_Block {
+	return (^Buddy_Block)(([^]byte)(block)[block.size:])
+}
+
+@(require_results)
+buddy_block_split :: proc(block: ^Buddy_Block, size: uint) -> ^Buddy_Block {
+	block := block
+	if block != nil && size != 0 {
+		// Recursive Split
+		for size < block.size {
+			sz := block.size >> 1
+			block.size = sz
+			block = buddy_block_next(block)
+			block.size = sz
+			block.is_free = true
+		}
+		if size <= block.size {
+			return block
+		}
+	}
+	// Block cannot fit the requested allocation size
+	return nil
+}
+
+buddy_block_coalescence :: proc(head, tail: ^Buddy_Block) {
+	for {
+		// Keep looping until there are no more buddies to coalesce
+		block := head
+		buddy := buddy_block_next(block)
+
+		no_coalescence := true
+		for block < tail && buddy < tail { // make sure the buddies are within the range
+			if block.is_free && buddy.is_free && block.size == buddy.size {
+				// Coalesce buddies into one
+				block.size <<= 1
+				block = buddy_block_next(block)
+				if block < tail {
+					buddy = buddy_block_next(block)
+					no_coalescence = false
+				}
+			} else if block.size < buddy.size {
+				// The buddy block is split into smaller blocks
+				block = buddy
+				buddy = buddy_block_next(buddy)
+			} else {
+				block = buddy_block_next(buddy)
+				if block < tail {
+					// Leave the buddy block for the next iteration
+					buddy = buddy_block_next(block)
+				}
+			}
+		}
+
+		if no_coalescence {
+			return
+		}
+	}
+}
+
+
+@(require_results)
+buddy_block_find_best :: proc(head, tail: ^Buddy_Block, size: uint) -> ^Buddy_Block {
+	assert(size != 0)
+
+	best_block: ^Buddy_Block
+	block := head                    // left
+	buddy := buddy_block_next(block) // right
+
+	// The entire memory section between head and tail is free,
+	// just call 'buddy_block_split' to get the allocation
+	if buddy == tail && block.is_free {
+		return buddy_block_split(block, size)
+	}
+
+	// Find the block which is the 'best_block' to requested allocation sized
+	for block < tail && buddy < tail { // make sure the buddies are within the range
+		// If both buddies are free, coalesce them together
+		// NOTE: this is an optimization to reduce fragmentation
+		//       this could be completely ignored
+		if block.is_free && buddy.is_free && block.size == buddy.size {
+			block.size <<= 1
+			if size <= block.size && (best_block == nil || block.size <= best_block.size) {
+				best_block = block
+			}
+
+			block = buddy_block_next(buddy)
+			if block < tail {
+				// Delay the buddy block for the next iteration
+				buddy = buddy_block_next(block)
+			}
+			continue
+		}
+
+
+		if block.is_free && size <= block.size &&
+		   (best_block == nil || block.size <= best_block.size) {
+			best_block = block
+		}
+
+		if buddy.is_free && size <= buddy.size &&
+		   (best_block == nil || buddy.size < best_block.size) {
+			// If each buddy are the same size, then it makes more sense
+			// to pick the buddy as it "bounces around" less
+			best_block = buddy
+		}
+
+		if (block.size <= buddy.size) {
+			block = buddy_block_next(buddy)
+			if (block < tail) {
+				// Delay the buddy block for the next iteration
+				buddy = buddy_block_next(block)
+			}
+		} else {
+			// Buddy was split into smaller blocks
+			block = buddy
+			buddy = buddy_block_next(buddy)
+		}
+	}
+
+	if best_block != nil {
+		// This will handle the case if the 'best_block' is also the perfect fit
+		return buddy_block_split(best_block, size)
+	}
+
+	// Maybe out of memory
+	return nil
+}
+
+
+Buddy_Allocator :: struct {
+	head: ^Buddy_Block,
+	tail: ^Buddy_Block,
+	alignment: uint,
+}
+
+@(require_results)
+buddy_allocator :: proc(b: ^Buddy_Allocator) -> Allocator {
+	return Allocator{
+		procedure = buddy_allocator_proc,
+		data      = b,
+	}
+}
+
+buddy_allocator_init :: proc(b: ^Buddy_Allocator, data: []byte, alignment: uint) {
+	assert(data != nil)
+	assert(is_power_of_two(uintptr(len(data))))
+	assert(is_power_of_two(uintptr(alignment)))
+
+	alignment := alignment
+	if alignment < size_of(Buddy_Block) {
+		alignment = size_of(Buddy_Block)
+	}
+
+	ptr := raw_data(data)
+	assert(uintptr(ptr) % uintptr(alignment) == 0, "data is not aligned to minimum alignment")
+
+	b.head = (^Buddy_Block)(ptr)
+
+	b.head.size = len(data)
+	b.head.is_free = true
+
+	b.tail = buddy_block_next(b.head)
+
+	b.alignment = alignment
+}
+
+@(require_results)
+buddy_block_size_required :: proc(b: ^Buddy_Allocator, size: uint) -> uint {
+	size := size
+	actual_size := b.alignment
+	size += size_of(Buddy_Block)
+	size = align_forward_uint(size, b.alignment)
+
+	for size > actual_size {
+		actual_size <<= 1
+	}
+
+	return actual_size
+}
+
+@(require_results)
+buddy_allocator_alloc :: proc(b: ^Buddy_Allocator, size: uint, zeroed: bool) -> ([]byte, Allocator_Error) {
+	if size != 0 {
+		actual_size := buddy_block_size_required(b, size)
+
+		found := buddy_block_find_best(b.head, b.tail, actual_size)
+		if found != nil {
+			// Try to coalesce all the free buddy blocks and then search again
+			buddy_block_coalescence(b.head, b.tail)
+			found = buddy_block_find_best(b.head, b.tail, actual_size)
+		}
+		if found == nil {
+			return nil, .Out_Of_Memory
+		}
+		found.is_free = false
+
+		data := ([^]byte)(found)[b.alignment:][:size]
+		if zeroed {
+			zero_slice(data)
+		}
+		return data, nil
+	}
+	return nil, nil
+}
+
+buddy_allocator_free :: proc(b: ^Buddy_Allocator, ptr: rawptr) -> Allocator_Error {
+	if ptr != nil {
+		if !(b.head <= ptr && ptr <= b.tail) {
+			return .Invalid_Pointer
+		}
+
+		block := (^Buddy_Block)(([^]byte)(ptr)[-b.alignment:])
+		block.is_free = true
+
+		buddy_block_coalescence(b.head, b.tail)
+	}
+	return nil
+}
+
+buddy_allocator_proc :: proc(allocator_data: rawptr, mode: Allocator_Mode,
+                             size, alignment: int,
+                             old_memory: rawptr, old_size: int,loc := #caller_location) -> ([]byte, Allocator_Error) {
+
+	b := (^Buddy_Allocator)(allocator_data)
+
+	switch mode {
+	case .Alloc, .Alloc_Non_Zeroed:
+		return buddy_allocator_alloc(b, uint(size), mode == .Alloc)
+	case .Resize:
+		return default_resize_bytes_align(byte_slice(old_memory, old_size), size, alignment, buddy_allocator(b))
+	case .Resize_Non_Zeroed:
+		return default_resize_bytes_align_non_zeroed(byte_slice(old_memory, old_size), size, alignment, buddy_allocator(b))
+	case .Free:
+		return nil, buddy_allocator_free(b, old_memory)
+	case .Free_All:
+
+		alignment := b.alignment
+		head := ([^]byte)(b.head)
+		tail := ([^]byte)(b.tail)
+		data := head[:ptr_sub(tail, head)]
+		buddy_allocator_init(b, data, alignment)
+
+	case .Query_Features:
+		set := (^Allocator_Mode_Set)(old_memory)
+		if set != nil {
+			set^ = {.Query_Features, .Alloc, .Alloc_Non_Zeroed, .Resize, .Resize_Non_Zeroed, .Free, .Free_All, .Query_Info}
+		}
+		return nil, nil
+
+	case .Query_Info:
+		info := (^Allocator_Query_Info)(old_memory)
+		if info != nil && info.pointer != nil {
+			ptr := old_memory
+			if !(b.head <= ptr && ptr <= b.tail) {
+				return nil, .Invalid_Pointer
+			}
+
+			block := (^Buddy_Block)(([^]byte)(ptr)[-b.alignment:])
+			info.size = int(block.size)
+			info.alignment = int(b.alignment)
+			return byte_slice(info, size_of(info^)), nil
+		}
+		return nil, nil
+	}
+
+	return nil, nil
+}

core/mem/mutex_allocator.odin

@@ -0,0 +1,33 @@
+//+build !freestanding
+package mem
+
+import "core:sync"
+
+Mutex_allocator :: struct {
+	backing: Allocator,
+	mutex:   sync.Mutex,
+}
+
+mutex_allocator_init :: proc(m: ^Mutex_allocator, backing_allocator: Allocator) {
+	m.backing = backing_allocator
+	m.mutex = {}
+}
+
+
+@(require_results)
+mutex_allocator :: proc(m: ^Mutex_allocator) -> Allocator {
+	return Allocator{
+		procedure = mutex_allocator_proc,
+		data = m,
+	}
+}
+
+mutex_allocator_proc :: proc(allocator_data: rawptr, mode: Allocator_Mode,
+                             size, alignment: int,
+                             old_memory: rawptr, old_size: int, loc := #caller_location) -> (result: []byte, err: Allocator_Error) {
+	m := (^Mutex_allocator)(allocator_data)
+
+	sync.mutex_guard(&m.mutex)
+	return m.backing.procedure(m.backing.data, mode, size, alignment, old_memory, old_size, loc)
+}
+

core/mem/virtual/arena_util.odin

@@ -0,0 +1,67 @@
+package mem_virtual
+
+import "base:runtime"
+_ :: runtime
+
+// The `new` procedure allocates memory for a type `T` from a `virtual.Arena`. The second argument is a type,
+// not a value, and the value return is a pointer to a newly allocated value of that type using the specified allocator.
+@(require_results)
+new :: proc(arena: ^Arena, $T: typeid, loc := #caller_location) -> (ptr: ^T, err: Allocator_Error) {
+	return new_aligned(arena, T, align_of(T), loc)
+}
+
+// The `new_aligned` procedure allocates memory for a type `T` from a `virtual.Arena` with a specified `alignment`.
+// The second argument is a type, not a value, and the value return is a pointer to a newly allocated value of
+// that type using the specified allocator.
+@(require_results)
+new_aligned :: proc(arena: ^Arena, $T: typeid, alignment: uint, loc := #caller_location) -> (ptr: ^T, err: Allocator_Error) {
+	data := arena_alloc(arena, size_of(T), alignment, loc) or_return
+	ptr = (^T)(raw_data(data))
+	return
+}
+
+// `make_slice` allocates and initializes a slice. Like `new`, the second argument is a type, not a value.
+// Unlike `new`, `make`'s return value is the same as the type of its argument, not a pointer to it.
+//
+// Note: Prefer using the procedure group `make`.
+@(require_results)
+make_slice :: proc(arena: ^Arena, $T: typeid/[]$E, #any_int len: int, loc := #caller_location) -> (T, Allocator_Error) {
+	return make_aligned(arena, T, len, align_of(E), loc)
+}
+
+// `make_aligned` allocates and initializes a slice. Like `new`, the second argument is a type, not a value.
+// Unlike `new`, `make`'s return value is the same as the type of its argument, not a pointer to it.
+//
+// Note: Prefer using the procedure group `make`.
+@(require_results)
+make_aligned :: proc(arena: ^Arena, $T: typeid/[]$E, #any_int len: int, alignment: uint, loc := #caller_location) -> (T, Allocator_Error) {
+	runtime.make_slice_error_loc(loc, len)
+	data, err := arena_alloc(arena, size_of(E)*uint(len), alignment, loc)
+	if data == nil && size_of(E) != 0 {
+		return nil, err
+	}
+	s := ([^]E)(raw_data(data))[:len]
+	return T(s), err
+}
+
+
+// `make_multi_pointer` allocates and initializes a dynamic array. Like `new`, the second argument is a type, not a value.
+// Unlike `new`, `make`'s return value is the same as the type of its argument, not a pointer to it.
+//
+// This is "similar" to doing `raw_data(make([]E, len, allocator))`.
+//
+// Note: Prefer using the procedure group `make`.
+@(require_results)
+make_multi_pointer :: proc(arena: ^Arena, $T: typeid/[^]$E, #any_int len: int, loc := #caller_location) -> (T, Allocator_Error) {
+	runtime.make_slice_error_loc(loc, len)
+	data, err := arena_alloc(arena, size_of(E)*uint(len), align_of(E), loc)
+	if data == nil && size_of(E) != 0 {
+		return nil, err
+	}
+	return (T)(raw_data(data)), err
+}
+
+make :: proc{
+	make_slice,
+	make_multi_pointer,
+}