File Coverage

blib/lib/Crypt/OpenPGP/Key.pm

Criterion	Covered	Total	%
statement	156	156	100.0
branch	5	8	62.5
condition	5	9	55.5
subroutine	52	52	100.0
pod	10	12	83.3
total	228	237	96.2

package Crypt::OpenPGP::Key;
use strict;

use Carp qw( confess );
use Crypt::OpenPGP::ErrorHandler;
use base qw( Crypt::OpenPGP::ErrorHandler );

use vars qw( %ALG %ALG_BY_NAME );
%ALG = (
    1 => 'RSA',
    16 => 'ElGamal',
    17 => 'DSA',
);
%ALG_BY_NAME = map { $ALG{$_} => $_ } keys %ALG;

sub new {
    my $class = shift;
    my $alg = shift;
    $alg = $ALG{$alg} || $alg;
    my $pkg = join '::', $class, $alg;
    eval "use $pkg;";
    return $class->error("Unsupported algorithm '$alg': $@") if $@;
    my @valid = $pkg->all_props;
    my %valid = map { $_ => 1 } @valid;
    my $key = bless { __valid => \%valid, __alg => $alg,
                      __alg_id => $ALG_BY_NAME{$alg} }, $pkg;
    $key->init(@_);
}

sub keygen {
    my $class = shift;
    my $alg = shift;
    $alg = $ALG{$alg} || $alg;
    my $pkg = join '::', __PACKAGE__, 'Public', $alg;
    eval "use $pkg;";
    return $class->error("Unsupported algorithm '$alg': $@") if $@;
    my($pub_data, $sec_data) = $pkg->keygen(@_);
    return $class->error("Key generation failed: " . $class->errstr)
        unless $pub_data && $sec_data;
    my $pub_pkg = join '::', __PACKAGE__, 'Public';
    my $pub = $pub_pkg->new($alg, $pub_data);
    my $sec_pkg = join '::', __PACKAGE__, 'Secret';
    my $sec = $sec_pkg->new($alg, $sec_data);
    ($pub, $sec);
}

sub init { $_[0] }

sub check { 1 }

sub alg { $_[0]->{__alg} }
sub alg_id { $_[0]->{__alg_id} }

sub size { 0 }
sub bytesize { int(($_[0]->size + 7) / 8) }

sub public_key { }
sub is_secret { 0 }

sub can_encrypt { 0 }
sub can_sign { 0 }

sub DESTROY { }

use vars qw( $AUTOLOAD );
sub AUTOLOAD {
    my $key = shift;
    (my $meth = $AUTOLOAD) =~ s/.*:://;
    confess "Can't call method $meth on Key $key"
        unless $key->{__valid}{$meth};
    $key->{key_data}->$meth(@_);
}

1;
__END__

=head1 NAME

Crypt::OpenPGP::Key - OpenPGP key factory

=head1 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');

=head1 DESCRIPTION

I<Crypt::OpenPGP::Key> provides base class functionality for all
I<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 I<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
I<Crypt::OpenPGP::Key::Public> or I<Crypt::OpenPGP::Key::Secret>,
depending on whether the key is public or secret, respectively.

=head1 KEY GENERATION

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

Generates a new key-pair of public key algorithm I<$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 I<errstr> to determine the error.

Valid values for type are C<DSA>, C<RSA>, and C<ElGamal>.

I<%arg> can contain:

=over 4

=item * 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
I<Size> should be at least 1024 bits.

This is a required argument.

=item * 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.

I<Verbosity> is 0 by default.

=back

=head1 METHODS

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

=head2 Key Data Access

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

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

    my $q = $dsa_key->q;

The attributes for each public-key algorithm are:

=over 4

=item * RSA

Public key: I<n>, I<e>

Secret key: I<n>, I<e>, I<d>, I<p>, I<q>, I<u>

=item * DSA

Public key: I<p>, I<q>, I<g>, I<y>

Secret key: I<p>, I<q>, I<g>, I<y>, I<x>

=item * ElGamal

Public key: I<p>, I<g>, I<y>

Secret key: I<p>, I<g>, I<y>, I<x>

=back

=head2 $key->check

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

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

=head2 $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 I<p>.

=head2 $key->bytesize

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

=head2 $key->is_secret

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

=head2 $key->public_key

Returns the public part of the key I<$key>. If I<$key> is already a
public key, I<$key> is returned; otherwise a new public key object
(I<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.

=head2 $key->can_encrypt

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

=head2 $key->can_sign

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

=head2 $key->alg

Returns the name of the public key algorithm.

=head2 $key->alg_id

Returns the number ID of the public key algorithm.

=head1 AUTHOR & COPYRIGHTS

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

=cut