Crypt::OpenPGP::Key(3)

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.