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
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).
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.
base64StdPadEncode
data in padded standard base64, as one line: PEM's body, and SCRAM's nonces, salts and proofs (RFC 5802 §5.1).
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).
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.
base64urlEncode
data as unpadded base64url: four characters per three bytes, and two or three for a short final group.
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
textstringrequiredThe 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[]requiredThe buffer holding the text, one character a byte.
starti32requiredWhere in text the base64 starts.
lengthi32requiredHow many characters it is.
returnsi32The 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[]requiredThe 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[]requiredThe buffer holding the bytes to encode; it is read, not changed.
starti32requiredWhere in data the bytes start.
lengthi32requiredHow many bytes to encode.
outu8[]requiredThe buffer the text is written into.
ati32requiredWhere in out the text starts.
returnsi32The 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
textstringrequiredThe 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[]requiredThe bytes to encode; they are read, not changed.
returnsstring
The unpadded base64url text, ceil(4n / 3) characters for n
bytes.

