NAME
Crypt::DSA::GMP::Key - DSA key
SYNOPSIS
use Crypt::DSA::GMP::Key;
my $key = Crypt::DSA::GMP::Key->new;
$key->p($p);DESCRIPTION
Crypt::DSA::GMP::Key contains a DSA key, both the public and private portions. Subclasses of Crypt::DSA::GMP::Key implement read and write methods, such that you can store DSA keys on disk, and read them back into your application.
USAGE
Any of the key attributes can be accessed through combination get/set methods. The key attributes are: p, q, g, priv_key, and pub_key. For example:
$key->p($p);
my $p2 = $key->p;All the attributes are Math::BigInt objects. When setting with a non-Math::BigInt object, we will attempt conversion from native integers, numeric strings in base 10 or base 16 (the latter with a 0x prefix), Pari objects, and any object that support stringification to base 10.
$key = Crypt::DSA::GMP::Key->new(%arg)
Creates a new (empty) key object. All of the attributes are initialized to 0.
Alternately, if you provide the Filename parameter (see below), the key will be read from disk. If you provide the Type parameter (mandatory if Filename is provided), be aware that your key will actually be blessed into a subclass of Crypt::DSA::GMP::Key. Specifically, it will be the class implementing the specific read functionality for that type, e.g. Crypt::DSA::GMP::Key::PEM.
Returns the key on success, undef otherwise. (See Password for one reason why new might return undef).
%arg can contain:
Type
The type of file where the key is stored. Currently the only types supported are PEM and SSH2.
A PEM file is an optionally encrypted, ASN.1-encoded object. Support for reading/writing PEM files comes from Convert::PEM. If you don't have this module installed, the new method will die.
An SSH2 file may either be a public key in ssh-dss format, or a private key using the SSH2 format.
This argument is mandatory, if you're either reading the file from disk (i.e. you provide a Filename argument) or you've specified the Content argument.
Filename
The location of the file which contains the key. Requires a Type argument so the decoder knows what type of file it is. You can't specify Content and Filename at the same time.
Content
The serialized version of the key. Requires a Type argument so the decoder knows how to decode it. You can't specify Content and Filename at the same time.
Password
If your key file is encrypted, you'll need to supply a passphrase to decrypt it. You can do that here.
If your passphrase is incorrect, new will return
undef.
$key->write(%arg)
Writes a key (optionally) to disk, using a format that you define with the Type parameter.
If your $key object has a defined priv_key (private key portion), the key will be written as a DSA private key object; otherwise, it will be written out as a public key. Note that not all serialization mechanisms can produce public keys in this version--currently, only PEM public keys are supported.
%arg can include:
Type
The type of file format that you wish to write, e.g. PEM.
This argument is mandatory, unless your $key object is already blessed into a subclass (e.g. Crypt::DSA::GMP::Key::PEM), and you wish to write the file using the same subclass.
Filename
The location of the file on disk where you want the key file to be written.
Password
If you want the key file to be encrypted, provide this argument, and the ASN.1-encoded string will be encrypted using the passphrase as a key.
$key->read(%arg)
Reads a key (optionally) from disk, using a format that you define with the Type parameter.
%arg can include:
Type
The type of file format, e.g. PEM, in which the key is stored. This argument is mandatory.
Filename
The location of the file on disk where the key file exists.
Password
If the key file is encrypted, this argument must be provided.
METHODS
size
Returns the size of the key in bits, which is the size of the large prime p.
sizes
Returns a two entry array (L, N) where L is the bit length of p and N is the bit length of q.
validate
Does simple validation on the key and returns 1 if it passes, and 0 otherwise. This includes:
existence check on p, q, and g
verify primality of p and q
verify q is a factor of p-1
partial validation of g (FIPS 186-4 A.2.2)
existence check of one of priv_key or pub_key
construction or verification of pub_key if priv_key exists
Using the high level Crypt::DSA:::GMP routines, this method is called after key generation, before signing, and before verification. An exception is thrown if the result is not valid.
p
The prime modulus p, with bit length L.
q
A prime divisor of p-1, with bit length N.
g
A generator of a subgroup of order q in the multiplicative group of GF(p). g is in the range [2,p-1].
priv_key
The private key that must remain secret. It is a randomly generated integer in the range [1,q-1].
pub_key
The public key, where pub_key = g ^ priv_key mod p.
AUTHOR & COPYRIGHTS
See Crypt::DSA::GMP for author, copyright, and license information.