Generating random values
Since this package attempts to reduce the biases involved, APIs can be comparatively slow. APIs that require a secure random source require an RandomReader
implementation as its parameter. See Defining a RandomReader.
Random integers
Use generateRandomInteger()
or generateRandomIntegerNumber()
to generate random integers between 0 (inclusive) and maximum (exclusive).
import { generateRandomInteger, generateRandomIntegerNumber } from "oslo/crypto";
// random number from 0 to 9
const num: bigint = generateRandomInteger(random, 10n);
const num: number = generateRandomIntegerNumber(random, 10);
Random strings
Use generateRandomString()
to generate random strings with a predefined set of characters. This also requires a RandomReader
function.
import { generateRandomString } from "oslo/crypto";
// 10-characters long string consisting of upper case letters
const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
generateRandomString(random, alphabet, 10);
Defining a RandomReader
RandomReader
should use a cryptographically secure random source.
Using the global Web Crypto API
The Web Crypto API is globally available in most modern runtimes, including Node.js 20+, Bun, Deno, and Cloudflare Workers.
import type { RandomReader } from "@oslojs/crypto/random";
const random: RandomReader = {
read(bytes: Uint8Array): void {
crypto.getRandomValues(bytes);
}
};
Using Node's Crypto module
An implementation of the Web Crypto API can be imported in Node.js 18+.
import { webcrypto } from "node:crypto";
import type { RandomReader } from "@oslojs/crypto/random";
const random: RandomReader = {
read(bytes: Uint8Array): void {
webcrypto.getRandomValues(bytes);
}
};
import { getRandomValues } from "node:crypto";
import type { RandomReader } from "@oslojs/crypto/random";
const random: RandomReader = {
read(bytes: Uint8Array): void {
getRandomValues(bytes);
}
};
Use fillRandomSync()
for older versions of Node.js.
import { fillRandomSync } from "node:crypto";
import type { RandomReader } from "@oslojs/crypto/random";
const random: RandomReader = {
read(bytes: Uint8Array) {
fillRandomSync(bytes);
}
};