nish/crypto/sha256

SHA-256 as FIPS 180-4 §6.2 defines it, in pure Nish.

import {
  SHA256_BLOCK,
  SHA256_SIZE,
  Sha256,
  sha256,
} from "nish/crypto/sha256";
import { sha256, Sha256 } from "nish/crypto/sha256";

const whole: u8[] = sha256(message);

const h = new Sha256();
h.update(first, 0, toI32(first.length));
const soFar: u8[] = h.copy().digest();
h.update(second, 0, toI32(second.length));
const all: u8[] = h.digest();

Two shapes, because they answer two different callers. sha256(data) is the one-shot form for a message that is already in one buffer. Sha256 is the streaming form, and it exists for TLS 1.3: a handshake hashes its transcript as the messages arrive and needs the hash of the transcript so far at several points, which is what copy() is for — take a copy, digest the copy, and keep feeding the original.

Input is a window (buf, off, len) over a u8[], so a caller hashing one record out of a larger receive buffer does not copy it out first. A digest is always a fresh 32-byte u8[].

Every word is a u32, whose arithmetic is defined to wrap, so the additions modulo 2^32 that the specification asks for are plain + with no masking. Nothing here branches or indexes on the message: the only branches are on lengths and loop counters, which a hash does not keep secret.

Every read is checked: nothing here imports nish:unsafe, so hashing never makes a caller reach unsafe, which --deny unsafe refuses (the SCRAM in std/net/postgres.ts is one such caller). sha256Compress instead orders its reads so that the optimiser can fold a block's bounds checks into one.

Written from the specification, not ported from another implementation.

Functions

sha256

The SHA-256 digest of all of data, as a fresh 32-byte array.

An array longer than 2^31 - 1 bytes panics. A window's length is an i32, and under --number-mode f64 toI32 of a longer length saturates, so hashing toI32(data.length) bytes would answer the digest of a prefix: one digest for every message that shares its first 2^31 - 1 bytes. The length is compared as the number it is, before any toI32.

const sha256: (data: u8[]) => u8[]
datau8[]required

The whole message; it is read, not changed.

returnsu8[]

A fresh 32-byte digest.

Classes

Sha256

A SHA-256 computation in progress: the hash value H of FIPS 180-4 §6.2 after every whole block absorbed so far, and the bytes of the block not yet whole.

update may be called any number of times with windows of any length, and the digest does not depend on where the message was split. digest pads the message (§5.1.1), runs the last block or two, and ends the computation: the padding is written into this hasher's own state, so a second digest, a later update or a copy would carry the padding as message, and all three panic instead of answering a wrong value. copy first when the computation has to go on.

class Sha256
Member
new Sha256() A hasher at the start of an empty message (FIPS 180-4 §5.3.3's initial hash value).
block: u8[] The pending bytes of the current block; the first fill of them are live.
schedule: u32[] W_0 .. W_63, the message schedule of §6.2.2 step 1. It carries nothing from one block to the next and is a field only so that a long message allocates it once rather than once per block.
state: u32[] H_0 .. H_7, the eight words of the intermediate hash value (§6.2.2 step 4).
copy(): Sha256 An independent hasher at the same point in the same message: updating or digesting either one leaves the other as it was. This is how a caller takes the hash of a prefix and keeps going.
digest(): u8[] The 32-byte message digest (FIPS 180-4 §6.2.2, the final H^(N) in big-endian order), in a fresh array. Ends the computation.
digestInto(out: u8[], at: i32): void Writes the 32-byte message digest (FIPS 180-4 §6.2.2, the final H^(N) in big-endian order) at out[at .. at + 32) and ends the computation, with nothing allocated. A window outside out panics before anything is written or the hasher is finished, rather than writing the part of the digest that fits. A second digest or digestInto panics, and so does an update after it.
update(data: u8[], off: i32, len: i32): void Absorbs data[off .. off + len). A window outside data panics rather than hashing a short read, since a digest over the wrong bytes looks exactly like a digest over the right ones.

Constants

64

SHA256_BLOCK: i32

The length of a message block in bytes (FIPS 180-4 §1, "Block Size").

32

SHA256_SIZE: i32

The length of a digest in bytes (FIPS 180-4 §1, "Message Digest Size").