BigIntegers (Bouncy Castle Library 1.85 API Specification)
Date: 2026-07-12

org.bouncycastle.util

## Class BigIntegers

- java.lang.Object
- - org.bouncycastle.util.BigIntegers

-     public final class BigIntegers
      extends java.lang.Object

  BigInteger utilities.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `BigIntegers.Cache`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.math.BigInteger` | `ONE`
    `static java.math.BigInteger` | `TWO`
    `static java.math.BigInteger` | `ZERO`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `BigIntegers()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static boolean` | `areSecretValuesEqual(int maxLen, java.math.BigInteger a, java.math.BigInteger b)` Compare two non-negative values for equality without an early exit.
    `static byte[]` | `asUnsignedByteArray(java.math.BigInteger value)` Return the passed in value as an unsigned byte array.
    `static void` | `asUnsignedByteArray(java.math.BigInteger value, byte[] buf, int off, int len)` Write the passed in value as unsigned bytes to the specified buffer range, padded with leading zeros as necessary.
    `static byte[]` | `asUnsignedByteArray(int length, java.math.BigInteger value)` Return the passed in value as an unsigned byte array of the specified length, padded with leading zeros as necessary..
    `static byte` | `byteValueExact(java.math.BigInteger x)`
    `static java.math.BigInteger` | `createRandomBigInteger(int bitLength, java.security.SecureRandom random)` Return a positive BigInteger in the range of 0 to 2**bitLength - 1.
    `static java.math.BigInteger` | `createRandomInRange(java.math.BigInteger min, java.math.BigInteger max, java.security.SecureRandom random)` Return a random BigInteger not less than 'min' and not greater than 'max'
    `static java.math.BigInteger` | `createRandomPrime(int bitLength, int certainty, java.security.SecureRandom random)` Return a prime number candidate of the specified bit length.
    `static java.math.BigInteger` | `fromUnsignedByteArray(byte[] buf)`
    `static java.math.BigInteger` | `fromUnsignedByteArray(byte[] buf, int off, int length)`
    `static int` | `getUnsignedByteLength(java.math.BigInteger n)`
    `static boolean` | `hasAnySmallFactors(java.math.BigInteger x)`
    `static int` | `intValueExact(java.math.BigInteger x)`
    `static long` | `longValueExact(java.math.BigInteger x)`
    `static java.math.BigInteger` | `modOddInverse(java.math.BigInteger M, java.math.BigInteger X)`
    `static java.math.BigInteger` | `modOddInverseVar(java.math.BigInteger M, java.math.BigInteger X)`
    `static boolean` | `modOddIsCoprime(java.math.BigInteger M, java.math.BigInteger X)`
    `static boolean` | `modOddIsCoprimeVar(java.math.BigInteger M, java.math.BigInteger X)`
    `static short` | `shortValueExact(java.math.BigInteger x)`
    `static void` | `writeUnsignedByteArray(java.io.OutputStream out, java.math.BigInteger n)`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### ZERO

          public static final java.math.BigInteger ZERO

    - #### ONE

          public static final java.math.BigInteger ONE

    - #### TWO

          public static final java.math.BigInteger TWO

  - ### Constructor Detail

    - #### BigIntegers

          public BigIntegers()

  - ### Method Detail

    - #### asUnsignedByteArray

          public static byte[] asUnsignedByteArray(java.math.BigInteger value)

      Return the passed in value as an unsigned byte array.
      Parameters:
        `value` - the value to be converted.
      Returns:
        a byte array without a leading zero byte if present in the signed encoding.

    - #### asUnsignedByteArray

          public static byte[] asUnsignedByteArray(int length,
                                                   java.math.BigInteger value)

      Return the passed in value as an unsigned byte array of the specified length, padded with leading zeros as necessary..
      Parameters:
        `length` - the fixed length of the result
        `value` - the value to be converted.
      Returns:
        a byte array padded to a fixed length with leading zeros.

    - #### asUnsignedByteArray

          public static void asUnsignedByteArray(java.math.BigInteger value,
                                                 byte[] buf,
                                                 int off,
                                                 int len)

      Write the passed in value as unsigned bytes to the specified buffer range, padded with leading zeros as necessary.
      Parameters:
        `value` - the value to be converted.
        `buf` - the buffer to which the value is written.
        `off` - the start offset in array `buf` at which the data is written.
        `len` - the fixed length of data written (possibly padded with leading zeros).

    - #### createRandomInRange

          public static java.math.BigInteger createRandomInRange(java.math.BigInteger min,
                                                                 java.math.BigInteger max,
                                                                 java.security.SecureRandom random)

      Return a random BigInteger not less than 'min' and not greater than 'max'
      Parameters:
        `min` - the least value that may be generated
        `max` - the greatest value that may be generated
        `random` - the source of randomness
      Returns:
        a random BigInteger value in the range [min,max]

    - #### fromUnsignedByteArray

          public static java.math.BigInteger fromUnsignedByteArray(byte[] buf)

    - #### fromUnsignedByteArray

          public static java.math.BigInteger fromUnsignedByteArray(byte[] buf,
                                                                   int off,
                                                                   int length)

    - #### byteValueExact

          public static byte byteValueExact(java.math.BigInteger x)

    - #### shortValueExact

          public static short shortValueExact(java.math.BigInteger x)

    - #### intValueExact

          public static int intValueExact(java.math.BigInteger x)

    - #### longValueExact

          public static long longValueExact(java.math.BigInteger x)

    - #### areSecretValuesEqual

          public static boolean areSecretValuesEqual(int maxLen,
                                                     java.math.BigInteger a,
                                                     java.math.BigInteger b)

      Compare two non-negative values for equality without an early exit. Both are laid out as unsigned big-endian byte arrays of the fixed public length `maxLen` before the comparison, so the comparison itself is length-uniform.

      Fixed-width encoding drops the two's-complement sign byte that `BigInteger.toByteArray()` prepends when the most-significant bit is set: without that, two values could serialise to different lengths (e.g. 256 vs 257 bytes for a 2048-bit value) purely according to that high bit, and the variable-time comparison would leak it. This is not perfectly constant-time — `java.math.BigInteger` has no constant-time serialisation, so the underlying `toByteArray()` still runs in time proportional to each value's magnitude — but the comparison no longer differs in length on the value's high bit. Intended for secret key material (RSA `d` and the CRT factors, DSA/DH/ElGamal/GOST `x`, EC `d`), which are all non-negative; the temporary unsigned encodings holding that secret material are zeroed before returning.

      Both arguments must be non-null and non-negative; a negative value does not produce a meaningful result (and may throw `IllegalArgumentException`), and a null value throws `NullPointerException`.

      Parameters:
        `maxLen` - the public unsigned byte length both values are encoded to (e.g. from a group order or modulus).
        `a` - the first value, non-null and non-negative.
        `b` - the second value, non-null and non-negative.
      Returns:
        true if `a` and `b` are numerically equal, false otherwise.

    - #### hasAnySmallFactors

          public static boolean hasAnySmallFactors(java.math.BigInteger x)

    - #### modOddInverse

          public static java.math.BigInteger modOddInverse(java.math.BigInteger M,
                                                           java.math.BigInteger X)

    - #### modOddInverseVar

          public static java.math.BigInteger modOddInverseVar(java.math.BigInteger M,
                                                              java.math.BigInteger X)

    - #### modOddIsCoprime

          public static boolean modOddIsCoprime(java.math.BigInteger M,
                                                java.math.BigInteger X)

    - #### modOddIsCoprimeVar

          public static boolean modOddIsCoprimeVar(java.math.BigInteger M,
                                                   java.math.BigInteger X)

    - #### getUnsignedByteLength

          public static int getUnsignedByteLength(java.math.BigInteger n)

    - #### createRandomBigInteger

          public static java.math.BigInteger createRandomBigInteger(int bitLength,
                                                                    java.security.SecureRandom random)

      Return a positive BigInteger in the range of 0 to 2**bitLength - 1.
      Parameters:
        `bitLength` - maximum bit length for the generated BigInteger.
        `random` - a source of randomness.
      Returns:
        a positive BigInteger

    - #### createRandomPrime

          public static java.math.BigInteger createRandomPrime(int bitLength,
                                                               int certainty,
                                                               java.security.SecureRandom random)

      Return a prime number candidate of the specified bit length.
      Parameters:
        `bitLength` - bit length for the generated BigInteger.
        `random` - a source of randomness.
      Returns:
        a positive BigInteger of numBits length

    - #### writeUnsignedByteArray

          public static void writeUnsignedByteArray(java.io.OutputStream out,
                                                    java.math.BigInteger n)
                                             throws java.io.IOException

      Throws:
        `java.io.IOException`