Oregami
Repositories/oxedyne/fe2o3

oxedyne/fe2o3/fe2o3_crypto/js/pad.mjs

4.7 KiB, 1 run

created by r1870400018:76439, which is this file's identity for as long as the history lasts, whatever it is later renamed to

download · who wrote it · its history

1// pad.mjs -- the JavaScript twin of `fe2o3_crypto::pad` (fe2o3_crypto/src/pad.rs).
2//
3// `padmeLen` is Padmé, Algorithm 1 of Nikitin et al., "Reducing Metadata Leakage from Encrypted
4// Files and Communication with PURBs" (PoPETs 2019, arXiv 1806.03160, §4.4). A frame is
5// `u32 big-endian body length ‖ body ‖ zeros`, its whole length rounded by a rule and never below
6// the rule's floor; `unpad` needs no rule. Pad before sealing and unpad after opening. Both
7// twins are held to `fe2o3_crypto/tests/data/padme_vectors.txt`.
8
9export const PREFIX_LEN = 4; // fixed: the frame format, a u32 big-endian body length
10const U32_MAX = 0xffffffff; // fixed: the prefix is a u32
11const U64_MAX = (1n << 64n) - 1n; // fixed: the Rust twin's u64 range
12
13function big(x, what) {
14 if (typeof x === 'bigint') return x;
15 if (Number.isSafeInteger(x) && x >= 0) return BigInt(x);
16 throw new RangeError(what + ' must be a non-negative safe integer or a BigInt, not ' + x);
17}
18
19// A BigInt in gives a BigInt out; a Number in gives a Number, refused past 2^53 − 1.
20function back(v, asBig, what) {
21 if (v > U64_MAX) throw new RangeError(what + ' overflows 64 bits');
22 if (asBig) return v;
23 if (v > BigInt(Number.MAX_SAFE_INTEGER)) throw new RangeError(what + ' is past 2^53 − 1; pass a BigInt');
24 return Number(v);
25}
26
27function bitLen(v) { return v === 0n ? 0n : BigInt(v.toString(2).length); }
28
29// Padmé's padded length for `len` bytes; below 2 the length stands, as in the Rust twin.
30export function padmeLen(len) {
31 const asBig = typeof len === 'bigint';
32 const l = big(len, 'len');
33 if (l < 2n) return back(l, asBig, 'padmeLen');
34 const e = bitLen(l) - 1n; // ⌊log₂ L⌋, the exponent
35 const s = bitLen(e); // ⌊log₂ E⌋ + 1, the bits that hold E
36 const m = (1n << (e - s)) - 1n; // low bits forced to zero
37 return back((l + m) & ~m, asBig, 'padmeLen(' + l + ')');
38}
39
40// A rule as configured: `{ rule: 'padme' | 'pow2' | 'block', floor, block }`, the shape of the
41// Rust `PadConfig` (defaults padme, 256, 1 MiB). `block` is read only by `block`.
42export const PAD_DEFAULT = Object.freeze({ rule: 'padme', floor: 256, block: 1048576 });
43
44export function padRule(cfg = PAD_DEFAULT) {
45 const c = { ...PAD_DEFAULT, ...cfg };
46 if (c.rule !== 'padme' && c.rule !== 'pow2' && c.rule !== 'block') {
47 throw new RangeError('The pad rule ' + JSON.stringify(c.rule) + ' is not one of padme, pow2 or block');
48 }
49 if (c.rule === 'block' && big(c.block, 'block') === 0n) {
50 throw new RangeError("The pad rule 'block' needs 'block' of at least one byte");
51 }
52 return Object.freeze(c);
53}
54
55// The rounded length of a frame of `len` bytes, the prefix included.
56export function round(rule, len) {
57 const asBig = typeof len === 'bigint';
58 const l = big(len, 'len');
59 const floor = big(rule.floor, 'floor');
60 let got;
61 if (rule.rule === 'padme') {
62 got = big(padmeLen(l), 'padme');
63 } else if (rule.rule === 'pow2') {
64 got = 1n;
65 while (got < l) got <<= 1n;
66 } else if (rule.rule === 'block') {
67 const b = big(rule.block, 'block');
68 if (b === 0n) throw new RangeError('A block pad rule needs a block of at least one byte');
69 got = ((l + b - 1n) / b) * b;
70 } else {
71 throw new RangeError('Unknown pad rule ' + JSON.stringify(rule.rule));
72 }
73 return back(got > floor ? got : floor, asBig, 'round(' + l + ')');
74}
75
76// The length of the frame `pad` makes for a body of `bodyLen` bytes.
77export function framedLen(rule, bodyLen) {
78 const n = big(bodyLen, 'bodyLen');
79 if (n > BigInt(U32_MAX)) throw new RangeError('A body of ' + n + " bytes is over the frame's u32 length prefix");
80 const got = round(rule, n + BigInt(PREFIX_LEN));
81 return typeof bodyLen === 'bigint' ? got : Number(got);
82}
83
84// `body` (a Uint8Array) framed and padded: its length as a big-endian u32, the body, then zeros.
85export function pad(rule, body) {
86 const total = framedLen(rule, body.length);
87 const out = new Uint8Array(total);
88 new DataView(out.buffer).setUint32(0, body.length, false);
89 out.set(body, PREFIX_LEN);
90 return out;
91}
92
93// The body inside a frame `pad` made, as a view onto it. Throws when the frame is shorter than
94// its prefix, the prefix claims more than the frame holds, or the fill is not all zeros.
95export function unpad(frame) {
96 if (frame.length < PREFIX_LEN) {
97 throw new RangeError('A padded frame of ' + frame.length + ' bytes is shorter than its ' + PREFIX_LEN + '-byte length prefix');
98 }
99 const n = new DataView(frame.buffer, frame.byteOffset, frame.byteLength).getUint32(0, false);
100 const end = PREFIX_LEN + n;
101 if (end > frame.length) throw new RangeError('A padded frame of ' + frame.length + ' bytes claims a body of ' + n + ' bytes');
102 for (let i = end; i < frame.length; i++) {
103 if (frame[i] !== 0) throw new RangeError("A padded frame's fill after its " + n + '-byte body is not all zeros');
104 }
105 return frame.subarray(PREFIX_LEN, end);
106}