nish/crypto/base64url

RFC 4648 §5 base64url, unpadded, as JWS and the relay's grants spell a key or a tag inside a URL or a header.

import {
  base64StdPadDecode,
  base64StdPadDecodedLength,
  base64StdPadEncode,
  base64StdPadEncodeInto,
  base64urlDecode,
  base64urlEncode,
} from "nish/crypto/base64url";
import { base64urlEncode, base64urlDecode } from "nish/crypto/base64url";

const text: string = base64urlEncode(tag); // no `=` padding
const back: u8[] | null = base64urlDecode(text); // null for any other spelling

The alphabet is A-Z a-z 0-9 - _, and there is no =: the length of the text already says how many bytes the last group holds (RFC 4648 §3.2 lets a specification that knows its lengths drop the padding, and RFC 7515 §2 does).

The module also holds RFC 4648 §4 standard base64 — + and /, padded with = — as base64StdPadEncode and base64StdPadDecode, for PEM (nish/crypto/x509) and SCRAM (nish/net/postgres), and as base64StdPadEncodeInto and base64StdPadDecodedLength, which read and write a caller's buffer and allocate nothing, for the WebSocket handshake (nish/net/websocket). It is as strict and as constant-time as the URL alphabet, by the same masks, and it refuses a = anywhere but the last one or two characters of a text whose length is a multiple of four. They are not nish/base64's base64Encode, which encodes only, indexes its alphabet and is for pixels; the StdPad names keep the two apart in the program's one namespace.

Decoding is strict, so that each byte string has exactly one spelling

base64urlDecode answers null for a = anywhere, for any character outside the alphabet (whitespace included), for a length of 1 mod 4 — six bits, not a byte — for a final character whose unused low bits are not zero (RFC 4648 §3.5), and for a text longer than 2^31 - 1 bytes. A lenient decoder would let AB and AA both mean 00, and a token compared or cached by its text would then have two identities.

Neither direction indexes or branches on the data

What is encoded here is usually a key, a nonce or a MAC, and a lookup table indexed by a secret sextet leaves its trace in the cache. So a sextet becomes a character, and a character a sextet, by arithmetic on range masks: (lo - 1 - c) & (c - hi - 1) is negative exactly when lo <= c <= hi, and an arithmetic shift by 31 turns that sign into an all-ones or all-zeros mask.

A malformed character is not refused where it is found either: the verdict is ORed into one word and read once, after the whole text. The text's length is public and is tested first.

Private helpers share the importing program's flat symbol namespace (docs/wp26-stdlib.md §3e), which is why each one carries the module's name.

Functions

base64StdPadDecode

The bytes of padded standard base64 text, or null unless it is the one canonical spelling of them: a whole number of four-character groups, = only as the last one or two characters, every other character in the alphabet, and the bits the padding leaves over all zero (RFC 4648 §3.5). The empty text is the spelling of no bytes (RFC 4648 §10). Where the padding is depends on the length alone; the characters themselves are read by masks and judged once, after the last.

const base64StdPadDecode: (text: string) => u8[] | null
textstringrequired

The padded standard base64 text, with no line breaks or whitespace.

returnsu8[] | null

A fresh array of the decoded bytes, or null when text is not their canonical padded spelling.

base64StdPadDecodedLength

How many bytes the padded standard base64 in text[start .. start + length) decodes to, or -1 unless it is their one canonical spelling, by base64StdPadDecode's rules and its masks; nothing is decoded or allocated. A WebSocket server checks a handshake's Sec-WebSocket-Key this way, where it lies in the request (RFC 6455 §4.2.1, item 5). A range outside text panics.

const base64StdPadDecodedLength: (
  text: u8[],
  start: i32,
  length: i32,
) => i32
textu8[]required

The buffer holding the text, one character a byte.

starti32required

Where in text the base64 starts.

lengthi32required

How many characters it is.

returnsi32

The decoded length, or -1 when the text is not canonical.

base64StdPadEncode

data in padded standard base64, as one line: PEM's body, and SCRAM's nonces, salts and proofs (RFC 5802 §5.1). One = closes a final group of two bytes, two a group of one. An array longer than 2^31 - 1 bytes panics.

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

The bytes to encode; they are read, not changed.

returnsstring

The padded standard base64 text, 4 × ceil(n / 3) characters for n bytes, with no line breaks.

base64StdPadEncodeInto

base64StdPadEncode of data[start .. start + length), written into out from at as the bytes of its characters, allocating nothing: the WebSocket accept key that a server writes for every handshake (RFC 6455 §4.2.2). A range outside data, or text that does not fit in out from at, panics.

const base64StdPadEncodeInto: (
  data: u8[],
  start: i32,
  length: i32,
  out: u8[],
  at: i32,
) => i32
datau8[]required

The buffer holding the bytes to encode; it is read, not changed.

starti32required

Where in data the bytes start.

lengthi32required

How many bytes to encode.

outu8[]required

The buffer the text is written into.

ati32required

Where in out the text starts.

returnsi32

The index in out just past the text, at + 4 × ceil(length / 3).

base64urlDecode

The bytes text spells in unpadded base64url, or null when it is not the one canonical spelling of any byte string — see the module comment for the five refusals.

Each group of four characters becomes one 24-bit word, six bits a character, which splits into three bytes; a short final group of two or three characters fills the top of the word and gives one or two.

const base64urlDecode: (text: string) => u8[] | null
textstringrequired

The unpadded base64url text, usually from a peer.

returnsu8[] | null

A fresh array of the decoded bytes, or null when text is not the canonical spelling of any bytes.

base64urlEncode

data as unpadded base64url: four characters per three bytes, and two or three for a short final group.

Bytes go into a bit accumulator eight at a time and come out six at a time, so one index walks the input and the only branches are on how many bits are waiting — which depends on the position, never on the bytes. An array longer than 2^31 - 1 bytes panics.

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

The bytes to encode; they are read, not changed.

returnsstring

The unpadded base64url text, ceil(4n / 3) characters for n bytes.