/* Copyright 2003-2006, Voltage Security, all rights reserved.
 */

#include "vibecrypto.h"
#include "environment.h"
#include "base.h"
#include "libctx.h"
#include "algobj.h"
#include "mpint.h"
#include "surrender.h"

#ifndef _PRIME_H
#define _PRIME_H

#ifdef __cplusplus
extern "C" {
#endif

/* Generate a prime of bit size primeSizeBits using the sieve and
 * Rabin-Miller tests. The random object will be the source of random
 * bytes and the result will be placed into the prime.
 * <p>The primeSizeBits must be greater than 32. This is almost an
 * arbitrary limit. The code is written so that the length must be
 * greater than or equal to 9, but it is also safer to make sure the
 * length is long enough so that a prime of the exact specified length
 * is found.
 * <p>This function will run the Rabin-Miller test, which is iterative.
 * Some standards call for an iteration count of 8 or 27 or 50. So
 * whoever is calling must indicate the iteration count. It must be at
 * least 8.
 * <p>The leadingBits arg indicates how many of the most significant
 * bits must be set. If the arg is 1, the function will make sure the
 * most significant bit is set, but cannot guarantee any following bits
 * are set (of course, the least significant bit will be set, after
 * all, the prime number will be an odd number). It is possible that
 * the random object happens to generate a value for which the second
 * most significant bit is also set, it's just that the function cannot
 * guarantee any bit other than the most significant. If the arg is 2,
 * the function will make sure the two most significant bits are set.
 * If the leadingBits arg is anything other than 1 or 2, the function
 * will consider it to be 2.
 * <p>The reason for the leadingBits arg is for RSA key pair
 * generation. For example, if the requested RSA modulus size is 1024
 * bits, the key pair generator will generate two 512-bit primes.
 * However, when mulitplying two 512-bit numbers, the result can be
 * 1023 or 1024 bits. If the two most significant bits of each prime
 * are set, then the product will definitely be 1024 bits.
 * <p>The relativePrime arg can be NULL. If so, the function finds a
 * prime. If not, the function will find a prime such that
 * <pre>
 * <code>
 *    prime - 1  is relatively prime with  relativePrime
 * </code>
 * </pre>
 * <p>This is for RSA key pair generation, where the public exponent
 * must be relatively prime with p - 1 and q - 1.
 * <p>The oneRandom flag is there to pass FIPS certification. A FIPS
 * test requires finding the next prime after a random starting point.
 * The code can also try to find a prime close to a random starting
 * point, but if not, just throw away that point and get a new random
 * value.
 * <p>If this function cannot generate a prime, it will return
 * VT_ERROR_NO_PRIME_FOUND.
 * <p>The caller can pass a surrender context if one is available (NULL
 * is allowed). The surrFlag is a VT_SURRENDER_FNCT_ flag (such as
 * VT_SURRENDER_FNCT_DSA_PARAM_GEN) indicating who wants the PQG.
 *
 * @param primeSizeBits The size, in bits, of the prime to generate.
 * @param leadingBits Either 1 or 2, indicates how many of the most
 * significant bits of the prime should be guaranteed to be set.
 * @param oneRandom This flag says to find the next prime after the
 * first random value, or to throw away values and generate new
 * random starting points. If 0 (false/no), use more than one random
 * starting point if necessary. If 1 (true/yes), use only one random
 * starting point.
 * @param random A random object, the source of any random bytes needed.
 * @param surrCtx
 * @param surrFlag A VT_SURRENDER_FNCT_ flag indicating what operation
 * is running, to tell the surrender function who is calling it.
 * @param callNumber The current callNumber of the surrender ctx. The
 * caller should pass the current value at the address given, the
 * function will return the number it eventually reaches at that
 * address.
 * @param relativePrime If NULL, ignored, if not NULL, the function
 * will find a prime such that prime - 1 is relatively prime with this
 * value.
 * @param prime Where the resulting prime will be deposited.
 * @return an int, 0 if the function completed successfully or a
 * non-zero error code.
 */
int VOLT_CALLING_CONV VoltGeneratePrimeRabinMiller VOLT_PROTO_LIST ((
   unsigned int primeSizeBits,
   unsigned int leadingBits,
   unsigned int iterationCount,
   unsigned int oneRandom,
   VtRandomObject random,
   VoltSurrenderCtx *surrCtx,
   unsigned int surrFlag,
   unsigned int *callNumber,
   VoltMpInt *relativePrime,
   VoltMpInt *prime
));

/* Generate a prime of bit size primeSizeBits using the sieve,
 * Rabin-Miller, and Lucas tests. This will follow the technique
 * outlined in section 4.1.2.1 of X9.31.
 * <p>The random object will be the source of random bytes and the
 * result will be placed into the prime.
 * <p>The primeSizeBits must be greater than or equal to 512 and a
 * multiple of 128. This is a requirement of X9.31.
 * <p>The relativePrime arg can be NULL. If so, the function finds a
 * prime. If not, the function will find a prime such that
 * <pre>
 * <code>
 *    prime - 1  is relatively prime with  relativePrime
 * </code>
 * </pre>
 * <p>This is for RSA key pair generation, where the public exponent
 * must be relatively prime with p - 1 and q - 1.
 * <p>If this function cannot generate a prime, it will return
 * VT_ERROR_NO_PRIME_FOUND.
 * <p>The caller can pass a surrender context if one is available (NULL
 * is allowed). The surrFlag is a VT_SURRENDER_FNCT_ flag (such as
 * VT_SURRENDER_FNCT_DSA_PARAM_GEN) indicating who wants the PQG.
 *
 * @param primeSizeBits The size, in bits, of the prime to generate.
 * @param random A random object, the source of any random bytes needed.
 * @param surrCtx
 * @param surrFlag A VT_SURRENDER_FNCT_ flag indicating what operation
 * is running, to tell the surrender function who is calling it.
 * @param callNumber The current callNumber of the surrender ctx. The
 * caller should pass the current value at the address given, the
 * function will return the number it eventually reaches at that
 * address.
 * @param relativePrime If NULL, ignored, if not NULL, the function
 * will find a prime such that prime - 1 is relatively prime with this
 * value.
 * @param prime Where the resulting prime will be deposited.
 * @return an int, 0 if the function completed successfully or a
 * non-zero error code.
 */
int VOLT_CALLING_CONV VoltGeneratePrimeX931 VOLT_PROTO_LIST ((
   unsigned int primeSizeBits,
   VtRandomObject random,
   VoltSurrenderCtx *surrCtx,
   unsigned int surrFlag,
   unsigned int *callNumber,
   VoltMpInt *relativePrime,
   VoltMpInt *prime
));

/* Generate a prime of bit size primeSizeBits using the technique
 * outlined in FIPS 186-2, appendix 2. This will perform steps 1 - 5 of
 * section 2.1 in appendix 2.
 * <p>This function currently operates only when primeSizeBits is 160.
 * <p>The routine will use the Rabin-Miller test to determine if a
 * number is prime.
 * <p>The caller must pass in a SEED buffer large enough to hold
 * primeSizeBits. For example, if primeSizeBits is 160, the SEED buffer
 * must be at least 20 bytes. This function will not check the validity
 * of the SEED argument, it is the responsibility of the caller to make
 * sure SEED is a valid buffer (not NULL) and big enough. Upon return,
 * the SEED buffer will contain the original SEED used to generate the
 * prime. The function will set the unsigned int at seedLen to be the
 * number of bytes placed into the SEED buffer. Once again, this
 * function will not check the validity of the seedLen input argument,
 * it is the responsibility of the caller to pass in a valid pointer.
 * <p>If this function cannot generate a prime, it will return
 * VT_ERROR_NO_PRIME_FOUND.
 *
 * @param primeSizeBits The size, in bits, of the prime to generate.
 * @param random A random object, the source of any random bytes needed.
 * @param SEED The buffer into which the function will place the FIPS
 * SEED value.
 * @param seedLen The address where the function will deposit the
 * length, in bytes, of SEED. That is, it will be the number of bytes
 * placed into the SEED buffer.
 * @param prime Where the resulting prime will be deposited.
 * @return an int, 0 if the function completed successfully or a
 * non-zero error code.
 */
int VOLT_CALLING_CONV VoltGeneratePrimeFips VOLT_PROTO_LIST ((
   unsigned int primeSizeBits,
   VtRandomObject random,
   unsigned char *SEED,
   unsigned int *seedLen,
   VoltMpInt *prime
));

/* Generate a prime of bit size primeSizeBits using the technique
 * outlined in X9.42, annex B (section B.1.2). This will perform steps
 * 1 - 8.
 * <p>This function currently operates only when primeSizeBits is 160.
 * <p>The routine will use the Rabin-Miller test to determine if a
 * number is prime.
 * <p>The caller must pass in a SEED buffer large enough to hold
 * primeSizeBits. For example, if primeSizeBits is 160, the SEED buffer
 * must be at least 20 bytes. This function will not check the validity
 * of the SEED argument, it is the responsibility of the caller to make
 * sure SEED is a valid buffer (not NULL) and big enough. Upon return,
 * the SEED buffer will contain the original SEED used to generate the
 * prime. The function will set the unsigned int at seedLen to be the
 * number of bytes placed into the SEED buffer. Once again, this
 * function will not check the validity of the seedLen input argument,