## nightly pumpkin

A cryptographically secure prime number generator

### 7 releases(3 stable)

Uses old Rust 2015

 2.0.1 Mar 19, 2018 May 11, 2016 May 5, 2016 Oct 29, 2015 Oct 21, 2015

#1165 in Cryptography

28KB
387 lines

# Pumpkin

A random number generator for generating large prime numbers, suitable for cryptography.

## What's up with the name?

Since I began writing this library around Halloween of 2015, I wanted to choose a name that was vaguely related to the holiday. Because "pumpkin" and "prime" both begin with the letter 'p', I decided to use that.

## Purpose

`pumpkin` is a cryptographically-secure, random number generator, useful for generating large prime numbers (at least 512-bits long). On the back-end, `pumpkin` uses the wonderful ramp library for storing the large numbers. `pumpkin` generates primes very quickly. In our testing, primes were generated anywhere between 1s and 5s on average, though of course your mileage may vary.

## Installation

Add the following to your `Cargo.toml` file:

``````pumpkin = "2.0.*"
``````

Note that `pumpkin` requires the `nightly` Rust compiler.

## Example

``````extern crate pumpkin;

use pumpkin::Prime;

fn main() {
let p = Prime::new(2048); // Generate a new 2048-bit prime number
let q = Prime::new(2048);
let e = p * q;

println!("{}", e);

/*
* 75222035638256552797269351238215022250546763213674706... Some massive
* 4096-bit number.
*/
}
``````

You can also initialize your own `OsRng` and generate `Prime`s from that.

``````extern crate pumpkin;
extern crate rand;

use pumpkin::Prime;

use rand::OsRng;

fn main() {
let mut rngesus = match OsRng::new() {
Ok(rng) => rng,
Err(e) => panic!("Error trying to initializing RNG: {}", e)
};

let p = Prime::from_rng(2048, &mut rngesus);
let q = Prime::from_rng(2048, &mut rngesus);

let e = p * q;

println!("{}", e);

/*
* 75222035638256552797269351238215022250546763213674706... Some massive
* 4096-bit number.
*/
}
``````

## Explanation

`Primes` are generated in much the same way as primes generated by `GnuPG`:

1. Create a large candidate number of a given bit-length. All `Primes` must be at least 512-bits long.

2. Divide the candidate number by the first 1,000 prime numbers.

3. Test the candidate number with Fermat's Little Theorem.

4. Finally, run five iterations of the Miller-Rabin Primality Test.

`Primes` are seeded by `rand::OsRng`, which receives its entropy via the operating system's entropy source (such as `/dev/urandom`). Thus, because we can be confident that the generated candidate number is truly random (or as close to truly random as the user can hope), we don't need to do more than five iterations of the Miller-Rabin test to ensure primality.

`Primes` are simple "newtype" structs; that is, it is a tuple-like struct surrounding `ramp's` `Int` type. `Primes` have all of the basic algebraic and logical operators implemented, thus allowing you to do any operation that you would require.

## Contributing

`pumpkin` is dual-licenced under the MIT and Unlicense. Should you wish to contribute updates to the project, please consider signing the included `WAVER` file with your cryptographic digital signature (as allowed by your country's laws). Doing so will release your changes back into the public domain to be used freely by all. I did so with this project, and it would mean a lot if you did too!

To sign the `WAIVER`, execute the following commands:

``````\$ gpg -sba -u \$YOUR_SIGNING_KEY WAIVER
\$ cat WAIVER.asc >> WAIVER.sigs && rm WAIVER.asc
``````

~1–1.3MB
~24K SLoC