@h0llyw00dzz/crypto-rand/dist/math_helper.d.ts

Cryptographically secure random utilities for Node.js and browsers

/**
 * [Miller-Rabin primality test](https://en.wikipedia.org/wiki/Miller%E2%80%93Rabin_primality_test)
 *
 * **Note:** If you understand how this works, it's unlike the situation described in Wikipedia: "For instance, in 2018, Albrecht et al.
 * were able to construct composite numbers that many cryptographic libraries, such as OpenSSL and GNU GMP, declared as prime,
 * demonstrating that these libraries were not implemented with an adversarial context in mind." ¯\_(ツ)_/¯
 *
 * @param n - The number to test for primality
 * @param k - The number of iterations for the test (a.k.a accuracy 🎯)
 * @param getRandomBytes - Function to generate random bytes (defaults to crypto.randomBytes)
 * @param enhanced - Whether to use the enhanced [FIPS](https://en.wikipedia.org/wiki/Federal_Information_Processing_Standards) version
 * @returns A boolean indicating whether the number is probably prime
 */
export declare function isProbablePrime(n: bigint, k: number, getRandomBytes?: (size: number) => Buffer | Uint8Array, enhanced?: boolean): boolean;
/**
 * Enhanced implementation of the [Miller-Rabin primality test](https://en.wikipedia.org/wiki/Miller%E2%80%93Rabin_primality_test) following [FIPS 186-5](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf) standard
 *
 * This function implements the enhanced version of the [Miller-Rabin primality test](https://en.wikipedia.org/wiki/Miller%E2%80%93Rabin_primality_test)
 * as specified in the [FIPS 186-5](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf) standard.
 * It provides stronger guarantees than the standard [Miller-Rabin primality test](https://en.wikipedia.org/wiki/Miller%E2%80%93Rabin_primality_test) by including additional
 * checks such as [GCD](https://en.wikipedia.org/wiki/Greatest_common_divisor) verification between random witnesses and the tested number.
 *
 * @param n - The number to test for primality
 * @param k - The number of iterations for the test (higher values increase accuracy)
 * @param getRandomBytes - Function to generate random bytes for witness selection
 * @returns A boolean indicating whether the number is probably prime according to [FIPS 186-5](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf) criteria
 */
export declare function isProbablePrimeEnhanced(n: bigint, k: number, getRandomBytes?: (size: number) => Buffer | Uint8Array): boolean;
/**
 * [Modular exponentiation](https://en.wikipedia.org/wiki/Modular_exponentiation): baseᵉˣᵖᵒⁿᵉⁿᵗ mod modulus
 *
 * @param base - The base value
 * @param exponent - The exponent value
 * @param modulus - The modulus value
 * @returns The result of the modular exponentiation
 */
export declare function modPow(base: bigint, exponent: bigint, modulus: bigint): bigint;
/**
 * Calculate the [modular multiplicative inverse](https://en.wikipedia.org/wiki/Modular_multiplicative_inverse) using the [Extended Euclidean Algorithm](https://en.wikipedia.org/wiki/Extended_Euclidean_algorithm)
 *
 * **Note:** This is a helper function primarily intended for testing purposes.
 * Not recommended for production use as it may be vulnerable to timing attacks.
 *
 * @param a - The number to find the inverse for
 * @param m - The modulus
 * @returns The [modular multiplicative inverse](https://en.wikipedia.org/wiki/Modular_multiplicative_inverse) inverse of a modulo m
 */
export declare function modInverse(a: bigint, m: bigint): bigint;
/**
 * Async version of [Miller-Rabin primality test](https://en.wikipedia.org/wiki/Miller%E2%80%93Rabin_primality_test)
 *
 * **Note:** If you understand how this works, it's unlike the situation described in Wikipedia: "For instance, in 2018, Albrecht et al.
 * were able to construct composite numbers that many cryptographic libraries, such as OpenSSL and GNU GMP, declared as prime,
 * demonstrating that these libraries were not implemented with an adversarial context in mind." ¯\_(ツ)_/¯
 *
 * @param n - The number to test for primality
 * @param k - The number of iterations for the test (a.k.a accuracy 🎯)
 * @param getRandomBytesAsync - Async function to generate random bytes
 * @param enhanced - Whether to use the enhanced [FIPS](https://en.wikipedia.org/wiki/Federal_Information_Processing_Standards) version
 * @returns A Promise that resolves to a boolean indicating whether the number is probably prime
 */
export declare function isProbablePrimeAsync(n: bigint, k: number, getRandomBytesAsync: (size: number) => Promise<Buffer | Uint8Array>, enhanced?: boolean): Promise<boolean>;
/**
 * Asynchronous implementation of the enhanced [Miller-Rabin primality test](https://en.wikipedia.org/wiki/Miller%E2%80%93Rabin_primality_test) following [FIPS 186-5](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf) standard
 *
 * This function is the asynchronous version of `isProbablePrimeEnhanced`, implementing the enhanced
 * version of the [Miller-Rabin primality test](https://en.wikipedia.org/wiki/Miller%E2%80%93Rabin_primality_test) as specified in the
 * [FIPS 186-5](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf) standard.
 * It provides stronger guarantees than the standard [Miller-Rabin primality test](https://en.wikipedia.org/wiki/Miller%E2%80%93Rabin_primality_test) by including additional
 * checks such as [GCD](https://en.wikipedia.org/wiki/Greatest_common_divisor) verification between random witnesses and the tested number.
 *
 * @param n - The number to test for primality
 * @param k - The number of iterations for the test (higher values increase accuracy)
 * @param getRandomBytesAsync - Async function to generate random bytes for witness selection
 * @returns A Promise that resolves to a boolean indicating whether the number is probably prime according to [FIPS 186-5](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf) criteria
 */
export declare function isProbablePrimeEnhancedAsync(n: bigint, k: number, getRandomBytesAsync: (size: number) => Promise<Buffer | Uint8Array>): Promise<boolean>;
/**
 * Calculate the [greatest common divisor](https://en.wikipedia.org/wiki/Greatest_common_divisor) (GCD) of two numbers using the [Euclidean algorithm](https://en.wikipedia.org/wiki/Greatest_common_divisor#Euclidean_algorithm)
 *
 * @param a - First number
 * @param b - Second number
 * @returns The greatest common divisor of a and b
 */
export declare function gcd(a: bigint, b: bigint): bigint;