NAME

Crypt::OpenPGP::Key - OpenPGP key factory

SYNOPSIS

    use Crypt::OpenPGP::Key;
    my($pub, $sec) = Crypt::OpenPGP::Key->keygen('DSA', Size => 1024);
    use Crypt::OpenPGP::Key::Public;
    my $pubkey = Crypt::OpenPGP::Key::Public->new('DSA');
    use Crypt::OpenPGP::Key::Secret;
    my $seckey = Crypt::OpenPGP::Key::Secret->new('RSA');

DESCRIPTION

Crypt::OpenPGP::Key provides base class functionality for all Crypt::OpenPGP public and secret keys. It functions as a factory class for key generation and key instantiation.

The only time you will ever use Crypt::OpenPGP::Key directly is to generate a key-pair; in all other scenarios--for example, when instantiating a new key object--you should use either Crypt::OpenPGP::Key::Public or Crypt::OpenPGP::Key::Secret, depending on whether the key is public or secret, respectively.

KEY GENERATION

Crypt::OpenPGP::Key->keygen( $type, %arg )

Generates a new key-pair of public key algorithm $type. Returns a public and a secret key, each blessed into the appropriate implementation class. Returns an empty list on failure, in which case you should call the class method errstr to determine the error.

Valid values for type are DSA, RSA, and ElGamal.

%arg can contain:

* Size

Bitsize of the key to be generated. This should be an even integer; there is no low end currently set, but for the sake of security Size should be at least 1024 bits.

This is a required argument.

* Verbosity

Set to a true value to enable a status display during key generation; since key generation is a relatively length process, it is helpful to have an indication that some action is occurring.

Verbosity is 0 by default.

METHODS

Crypt::OpenPGP::Key is not meant to be used directly (unless you are generating keys; see KEY GENERATION, above); instead you should use the subclasses of this module. There are, however, useful interface methods that are shared by all subclasses.

Key Data Access

Each public-key algorithm has different key data associated with it. For example, a public DSA key has 4 attributes: p, q, g, and y. A secret DSA key has the same attributes as a public key, and in addition it has an attribute x.

All of the key data attributes can be accessed by calling methods of the same name on the Key object. For example:

    my $q = $dsa_key->q;

The attributes for each public-key algorithm are:

* RSA

Public key: n, e

Secret key: n, e, d, p, q, u

* DSA

Public key: p, q, g, y

Secret key: p, q, g, y, x

* ElGamal

Public key: p, g, y

Secret key: p, g, y, x

$key->check

Check the key data to determine if it is valid. For example, an RSA secret key would multiply the values of p and q and verify that the product is equal to the value of n. Returns true if the key is valid, false otherwise.

Not all public key algorithm implementations implement a check method; for those that don't, check will always return true.

$key->size

Returns the "size" of the key. The definition of "size" depends on the public key algorithm; for example, DSA defines the size of a key as the bitsize of the value of p.

$key->bytesize

Whereas size will return a bitsize of the key, bytesize returns the size in bytes. This value is defined as int((bitsize(key)+7)/8).

$key->is_secret

Returns true if the key $key is a secret key, false otherwise.

$key->public_key

Returns the public part of the key $key. If $key is already a public key, $key is returned; otherwise a new public key object (Crypt::OpenPGP::Key::Public) is constructed, and the public values from the secret key are copied into the public key. The new public key is returned.

$key->can_encrypt

Returns true if the key algorithm has encryption/decryption capabilities, false otherwise.

$key->can_sign

Returns true if the key algorithm has signing/verification capabilities, false otherwise.

$key->alg

Returns the name of the public key algorithm.

$key->alg_id

Returns the number ID of the public key algorithm.

AUTHOR & COPYRIGHTS

Please see the Crypt::OpenPGP manpage for author, copyright, and license information.