NAME

Crypt::DSA::GMP::KeyChain - DSA key generation system

SYNOPSIS

    use Crypt::DSA::GMP::KeyChain;
    my $keychain = Crypt::DSA::GMP::KeyChain->new;

    my $key = $keychain->generate_params(
                    Size      => 512,
                    Seed      => $seed,
                    Verbosity => 1,
              );

    $keychain->generate_keys($key);

DESCRIPTION

Crypt::DSA::GMP::KeyChain is a lower-level interface to key generation than the "keygen" in Crypt::DSA::GMP method. It allows you to separately generate the p, q, and g key parameters, given an optional starting seed, bit sizes for p and q, and which standard to follow for construction.

You can then call generate_keys to generate the public and private portions of the key.

USAGE

$keychain = Crypt::DSA::GMP::KeyChain->new

Constructs and returns a new Crypt::DSA::GMP::KeyChain object. At the moment this isn't particularly useful in itself, other than being the object you need in order to call the other methods.

The standard to follow may be given in this call, where it will be used in all methods unless overridden.

$key = $keychain->generate_params(%arg)

Generates a set of DSA parameters: the p, q, and g values of the key. This involves finding primes, and as such it can be a relatively long process.

When invoked in scalar context, returns a new Crypt::DSA::GMP::Key object.

In list context, returns the new Crypt::DSA::GMP::Key object along with: the value of the internal counter when a suitable prime p was found; the value of h when g was derived; and the value of the seed (a 20-byte or 32-byte string) when q was found. These values aren't particularly useful in normal circumstances, but they could be useful.

%arg can contain:

• Standard

  Indicates which standard is to be followed. By default, FIPS 186-2 is used, which maintains backward compatibility with the Crypt::DSA Perl code and old OpenSSL versions. If FIPS 186-3 or FIPS 186-4 is given, then the FIPS 186-4 key generation will be used.

  The important changes made:

    - Using SHA-2 rather than SHA-1 for the CSPRNG.  This produces
      better quality random data for prime generation.
    - Allows I<N> to vary between 1 and 512 rather than fixed at 160.
    - The default size for I<N> when not specified is 256 if I<L> is
      2048 or larger, 160 otherwise.
    - In L<Crypt::DSA::GMP>, the signing and verification will use
      SHA-2 256 for signing and verification when I<N> E<lt>= 256,
      and SHA-2 512 otherwise.  The old standard used SHA-1.

  where N is the bit size of q, and L is the bit size of p. These correspond to the QSize and Size arguments.

  The recommended primality tests from FIPS 186-4 are always performed, since they are more stringent than the older standard and have no negative impact on the result.

• Size

  The size in bits of the p value to generate. The minimum allowable value is 256, and must also be at least 8 bits larger than the size of q (defaults to 160, see QSize).

  For any use where security is a concern, 1024 bits should be considered a minimum size. NIST SP800-57 (July 2012) considers 1024 bit DSA using SHA-1 to be deprecated, with 2048 or more bits using SHA-2 to be acceptable.

  This argument is mandatory.

• QSize

  The size in bits of the q value to generate. For the default FIPS 186-2 standard, this must always be 160. If the FIPS 186-4 standard is used, then this may be in the range 1 to 512 (values less than 160 are strongly discouraged).

  If not specified, q will be 160 bits if either the default FIPS 186-2 standard is used or if Size is less than 2048. If FIPS 186-4 is used and Size is 2048 or larger, then q will be 256.

• Seed

  A seed with which q generation will begin. If this seed does not lead to a suitable prime, it will be discarded, and a new random seed chosen in its place, until a suitable prime can be found.

  A seed that is shorter than the size of q will be immediately discarded.

  This is entirely optional, and if not provided a random seed will be generated automatically. Do not use this option unless you have a specific need for a starting seed.

• Verbosity

  Should be either 0 or 1. A value of 1 will give you a progress meter during p and q generation -- this can be useful, since the process can be relatively long.

  The default is 0.

• Prove

  Should be 0, 1, P, or Q. If defined and true, then both the primes for p and q will be proven primes. Setting to the string P or Q will result in just that prime being proven.

  Using this flag will guarantee the values are prime, which is valuable if security is extremely important. The current implementation constructs random primes using the method A.1.1.1, then ensures they are prime by constructing and verifying a primality proof, rather than using a constructive method such as the Maurer or Shawe-Taylor algorithms. The time for proof will depend on the platform and the Size parameter. Proving q should take 100 milliseconds or less, but p can take a very long time if over 1024 bits.

  The default is 0, which means the standard FIPS 186-4 probable prime tests are done.

$keychain->generate_keys($key)

Generates the public and private portions of the key $key, a Crypt::DSA::GMP::Key object.

AUTHOR & COPYRIGHT

See Crypt::DSA::GMP for author, copyright, and license information.