Primes (Bouncy Castle Library 1.54 API Specification)
Date: 2015-12-29

org.bouncycastle.math

## Class Primes

- java.lang.Object
- - org.bouncycastle.math.Primes

-     public abstract class Primes
      extends java.lang.Object

  Utility methods for generating primes and testing for primality.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Primes.MROutput` Used to return the output from the Enhanced Miller-Rabin Probabilistic Primality Test
    `static class` | `Primes.STOutput` Used to return the output from the Shawe-Taylor Random_Prime Routine

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `SMALL_FACTOR_LIMIT`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Primes()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Primes.MROutput` | `enhancedMRProbablePrimeTest(java.math.BigInteger candidate, java.security.SecureRandom random, int iterations)` FIPS 186-4 C.3.2 Enhanced Miller-Rabin Probabilistic Primality Test Run several iterations of the Miller-Rabin algorithm with randomly-chosen bases.
    `static Primes.STOutput` | `generateSTRandomPrime(Digest hash, int length, byte[] inputSeed)` FIPS 186-4 C.6 Shawe-Taylor Random_Prime Routine Construct a provable prime number using a hash function.
    `static boolean` | `hasAnySmallFactors(java.math.BigInteger candidate)` A fast check for small divisors, up to some implementation-specific limit.
    `static boolean` | `isMRProbablePrime(java.math.BigInteger candidate, java.security.SecureRandom random, int iterations)` FIPS 186-4 C.3.1 Miller-Rabin Probabilistic Primality Test Run several iterations of the Miller-Rabin algorithm with randomly-chosen bases.
    `static boolean` | `isMRProbablePrimeToBase(java.math.BigInteger candidate, java.math.BigInteger base)` FIPS 186-4 C.3.1 Miller-Rabin Probabilistic Primality Test (to a fixed base).

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

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

- - ### Field Detail

    - #### SMALL_FACTOR_LIMIT

          public static final int SMALL_FACTOR_LIMIT

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Primes

          public Primes()

  - ### Method Detail

    - #### generateSTRandomPrime

          public static Primes.STOutput generateSTRandomPrime(Digest hash,
                                              int length,
                                              byte[] inputSeed)

      FIPS 186-4 C.6 Shawe-Taylor Random_Prime Routine Construct a provable prime number using a hash function.
      Parameters:
        `hash` - the `Digest` instance to use (as "Hash()"). Cannot be null.
        `length` - the length (in bits) of the prime to be generated. Must be at least 2.
        `inputSeed` - the seed to be used for the generation of the requested prime. Cannot be null or empty.
      Returns:
        an `Primes.STOutput` instance containing the requested prime.

    - #### enhancedMRProbablePrimeTest

          public static Primes.MROutput enhancedMRProbablePrimeTest(java.math.BigInteger candidate,
                                                    java.security.SecureRandom random,
                                                    int iterations)

      FIPS 186-4 C.3.2 Enhanced Miller-Rabin Probabilistic Primality Test Run several iterations of the Miller-Rabin algorithm with randomly-chosen bases. This is an alternative to `isMRProbablePrime(BigInteger, SecureRandom, int)` that provides more information about a composite candidate, which may be useful when generating or validating RSA moduli.
      Parameters:
        `candidate` - the `BigInteger` instance to test for primality.
        `random` - the source of randomness to use to choose bases.
        `iterations` - the number of randomly-chosen bases to perform the test for.
      Returns:
        an `Primes.MROutput` instance that can be further queried for details.

    - #### hasAnySmallFactors

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

      A fast check for small divisors, up to some implementation-specific limit.
      Parameters:
        `candidate` - the `BigInteger` instance to test for division by small factors.
      Returns:
        `true` if the candidate is found to have any small factors, `false` otherwise.

    - #### isMRProbablePrime

          public static boolean isMRProbablePrime(java.math.BigInteger candidate,
                                  java.security.SecureRandom random,
                                  int iterations)

      FIPS 186-4 C.3.1 Miller-Rabin Probabilistic Primality Test Run several iterations of the Miller-Rabin algorithm with randomly-chosen bases.
      Parameters:
        `candidate` - the `BigInteger` instance to test for primality.
        `random` - the source of randomness to use to choose bases.
        `iterations` - the number of randomly-chosen bases to perform the test for.
      Returns:
        `false` if any witness to compositeness is found amongst the chosen bases (so `candidate` is definitely NOT prime), or else `true` (indicating primality with some probability dependent on the number of iterations that were performed).

    - #### isMRProbablePrimeToBase

          public static boolean isMRProbablePrimeToBase(java.math.BigInteger candidate,
                                        java.math.BigInteger base)

      FIPS 186-4 C.3.1 Miller-Rabin Probabilistic Primality Test (to a fixed base). Run a single iteration of the Miller-Rabin algorithm against the specified base.
      Parameters:
        `candidate` - the `BigInteger` instance to test for primality.
        `base` - the base value to use for this iteration.
      Returns:
        `false` if the specified base is a witness to compositeness (so `candidate` is definitely NOT prime), or else `true`.