Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท crypto

Node.js crypto.randomFill() function

Reference for crypto.randomFill() and randomFillSync() in Node.js: filling an existing buffer or typed array with secure random bytes, offsets, sizes and limits.

crypto.randomFill(buffer[, offset][, size], callback) overwrites part of an existing buffer with bytes from the operating system's cryptographically secure random generator, then calls the callback. crypto.randomFillSync() does the same synchronously and returns the buffer.

Unlike crypto.randomBytes(), which allocates a new Buffer each time, randomFill writes into memory you already own. That is useful when you reuse one buffer for many tokens, or when you need random values in a typed array such as Uint32Array.

NODE
import { randomFillSync } from 'node:crypto';

const buf = Buffer.alloc(16);
randomFillSync(buf);

Try it

Node.js Filling part of a buffer

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Typed arrays and the callback form

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
crypto.randomFill(buffer, callback): void
crypto.randomFill(buffer, offset, callback): void
crypto.randomFill(buffer, offset, size, callback): void
crypto.randomFillSync(buffer, offset?, size?): ArrayBuffer | Buffer | TypedArray | DataView
Name Description
buffer An ArrayBuffer, Buffer, typed array or DataView to overwrite.
offset Index of the first element to fill. Default 0. For typed arrays it counts elements, not bytes.
size How many elements to fill. Default is everything from offset to the end.
callback (err, buf). Called with the same object you passed in.

Returns: randomFillSync returns the object it was given. randomFill returns undefined.

Errors: ERR_OUT_OF_RANGE when offset or size reach past the end of the buffer or exceed 2**31 - 1. ERR_INVALID_ARG_TYPE for arguments that are not buffer-like (a plain array or string, for example), and for a missing callback in the asynchronous form.

Usage notes

  • Same data source as randomBytes. The bytes are suitable for keys, nonces and tokens. Do not use Math.random() for those purposes.
  • No allocation. Reuse one buffer in a hot loop to avoid garbage, but remember that anything you copy out of it must be copied, not referenced.
  • Typed arrays count elements. randomFill(new Uint32Array(4), 1, 2) fills elements 1 and 2, which is 8 bytes.
  • Asynchronous work runs on the libuv thread pool. For small buffers the synchronous form is usually faster overall because it skips the thread hop.
  • Do not pass an array you plan to use before the callback fires. Until the callback runs, the buffer contents are undefined.
  • Bounded random numbers. To get an integer in a range without modulo bias, use crypto.randomInt() instead of reducing filled bytes yourself.
  • Added in Node.js 7.10 and 6.13 (earlier release lines).