AnyEvent-GnuPG
view release on metacpan or search on metacpan
lib/AnyEvent/GnuPG.pm view on Meta::CPAN
sub sign {
shift->sign_cb(@_)->recv;
}
sub sign_cb {
my ( $self, %args ) = @_;
my $cv = _condvar( delete $args{cb} );
my $options = [];
my $passphrase = $args{passphrase} || "";
push @$options, "--armor" if $args{armor};
push @$options, "--local-user", $args{"local-user"}
if defined $args{"local-user"};
$self->{input} = $args{plaintext} || $args{input};
$self->{output} = $args{output};
if ( $args{clearsign} ) {
$self->_command("clearsign");
}
elsif ( $args{"detach-sign"} ) {
$self->_command("detach-sign");
}
else {
$self->_command("sign");
}
$self->_options($options);
$self->_args( [] );
my $proc = $self->_run_gnupg($cv);
$proc->finish unless $self->{input};
$self->_parse_status(
$cv,
need_passphrase => sub {
unless ( defined $passphrase ) {
return $self->_abort_gnupg( "passphrase required", $cv );
}
},
get_hidden => sub {
$self->_send_command($passphrase);
},
sig_created => sub {
$self->_end_gnupg( sub { $cv->send } );
},
);
$cv;
}
sub clearsign {
my $self = shift;
$self->sign( @_, clearsign => 1 );
}
sub clearsign_cb {
my $self = shift;
$self->sign_cb( @_, clearsign => 1 );
}
sub verify {
shift->verify_cb(@_)->recv;
}
sub verify_cb {
my ( $self, %args ) = @_;
my $cv = _condvar( delete $args{cb} );
return _croak( $cv, "missing signature argument" ) unless $args{signature};
my $files = [];
if ( $args{file} ) {
$args{file} = [ $args{file} ] unless ref $args{file};
@$files = ( $args{signature}, @{ $args{file} } );
}
else {
$self->{input} = $args{signature};
}
my $options = [];
push @$options, "--auto-key-locate", $args{"auto-key-locate"}
if defined $args{"auto-key-locate"};
push @$options, "--keyserver", $args{"keyserver"}
if defined $args{"keyserver"};
my @verify_options = ();
push @verify_options => 'pka-lookups' if $args{'pka-loopups'};
push @verify_options => 'pka-trust-increase' if $args{'pka-trust-increase'};
push @$options => ( '--verify-options' => join( ',' => @verify_options ) )
if @verify_options;
$self->_command("verify");
$self->_options($options);
$self->_args($files);
my $proc = $self->_run_gnupg($cv);
$proc->finish unless $self->{input};
my $sig = { trust => TRUST_UNDEFINED, };
$self->_parse_status(
$cv,
sig_id => sub {
( $sig->{sigid}, $sig->{data}, $sig->{timestamp} ) = @_;
},
goodsig => sub {
( $sig->{keyid}, $sig->{user} ) = @_;
},
validsig => sub {
( $sig->{fingerprint} ) = @_;
$self->_end_gnupg( sub { $cv->send } );
},
policy_url => sub {
( $sig->{policy_url} ) = @_;
},
trust_never => sub {
$sig->{trust} = TRUST_NEVER;
},
trust_marginal => sub {
$sig->{trust} = TRUST_MARGINAL;
},
trust_fully => sub {
$sig->{trust} = TRUST_FULLY;
},
trust_ultimate => sub {
$sig->{trust} = TRUST_ULTIMATE;
},
);
$cv;
}
sub decrypt {
shift->decrypt_cb(@_)->recv;
}
sub decrypt_cb {
my ( $self, %args ) = @_;
my $cv = _condvar( delete $args{cb} );
$self->{input} = $args{ciphertext} || $args{input};
$self->{output} = $args{output};
$self->_command("decrypt");
$self->_options( [] );
$self->_args( [] );
my $proc = $self->_run_gnupg($cv);
$proc->finish unless $self->{input};
my $passphrase = $args{passphrase} || "";
my $sig = { trust => TRUST_UNDEFINED, };
lib/AnyEvent/GnuPG.pm view on Meta::CPAN
policy_url => sub {
( $sig->{policy_url} ) = @_;
},
trust_never => sub {
$sig->{trust} = TRUST_NEVER;
},
trust_marginal => sub {
$sig->{trust} = TRUST_MARGINAL;
},
trust_fully => sub {
$sig->{trust} = TRUST_FULLY;
},
trust_ultimate => sub {
$sig->{trust} = TRUST_ULTIMATE;
},
);
$cv;
}
1;
__END__
=pod
=head1 NAME
AnyEvent::GnuPG - AnyEvent-based interface to the GNU Privacy Guard
=head1 VERSION
version 1.001
=head1 SYNOPSIS
use AnyEvent::GnuPG qw( :algo );
my $gpg = AnyEvent::GnuPG->new();
$gpg->encrypt(
plaintext => "file.txt",
output => "file.gpg",
armor => 1,
sign => 1,
passphrase => $secret
);
$gpg->decrypt(
ciphertext => "file.gpg",
output => "file.txt"
);
$gpg->clearsign(
plaintext => "file.txt",
output => "file.txt.asc",
passphrase => $secret,
armor => 1,
);
$gpg->verify(
signature => "file.txt.asc",
file => "file.txt"
);
$gpg->gen_key(
name => "Joe Blow",
comment => "My GnuPG key",
passphrase => $secret,
);
=head1 DESCRIPTION
AnyEvent::GnuPG is a perl interface to the GNU Privacy Guard. It uses the shared memory coprocess interface that gpg provides for its wrappers. It tries its best to map the interactive interface of the gpg to a more programmatic model.
=head1 METHODS
=head2 new(%params)
You create a new AnyEvent::GnuPG wrapper object by invoking its new method. (How original!). The module will try to finds the B<gpg> program in your path and will croak if it can't find it. Here are the parameters that it accepts:
=over 4
=item * gnupg_path
Path to the B<gpg> program.
=item * options
Path to the options file for B<gpg>. If not specified, it will use the default one (usually F<~/.gnupg/options>).
=item * homedir
Path to the B<gpg> home directory. This is the directory that contains the default F<options> file, the public and private key rings as well as the trust database.
=back
Example:
my $gpg = AnyEvent::GnuPG->new();
=head2 version
This method returns the current gpg version as list.
my @version = $gpg->version;
# returns ( 1, 4, 18 ) for example
=head2 version_cb
Asynchronous variant of L</version>.
=head2 gen_key(%params)
This methods is used to create a new gpg key pair. The methods croaks if there is an error. It is a good idea to press random keys on the keyboard while running this methods because it consumes a lot of entropy from the computer. Here are the paramet...
=over 4
=item * algo
This is the algorithm use to create the key. Can be I<DSA_ELGAMAL>, I<DSA>, I<RSA_RSA> or I<RSA>. It defaults to I<DSA_ELGAMAL>. To import those constant in your name space, use the I<:algo> tag.
lib/AnyEvent/GnuPG.pm view on Meta::CPAN
);
=head2 encrypt_cb(%params[, cb => $callback|$condvar])
Asynchronous variant of L</encrypt>.
=head2 sign(%params)
This method is used create a signature for a file or stream of data.
This method croaks on errors. Parameters:
=over 4
=item * plaintext
This argument specifies what to sign. It can be either a file name or anything else that L<AnyEvent::Proc/pull> accepts.
=item * output
This optional argument specifies where the signature will be output. It can be either a file name or anything else that L<AnyEvent::Proc/pipe> accepts.
=item * armor
If this parameter is set to true, the signature will be ASCII armored.
=item * passphrase
This parameter contains the secret that should be used to decrypt the private key.
=item * local-user
This parameter is used to specified the private key that will be used to make the signature. If left unspecified, the default user will be used.
=item * detach-sign
If set to true, a digest of the data will be signed rather than the whole file.
=back
Example:
$gpg->sign(
plaintext => "file.txt",
output => "file.txt.asc",
armor => 1
);
=head2 sign_cb(%params[, cb => $callback|$condvar])
Asynchronous variant of L</sign>.
=head2 clearsign(%params)
This methods clearsign a message. The output will contains the original message with a signature appended. It takes the same parameters as the L</sign> method.
=head2 clearsign_cb(%params[, cb => $callback|$condvar])
Asynchronous variant of L</clearsign>.
=head2 verify(%params)
This method verifies a signature against the signed message. The methods croaks if the signature is invalid or an error is encountered. If the signature is valid, it returns an hash with the signature parameters. Here are the method's parameters:
=over 4
=item * signature
If the message and the signature are in the same file (i.e. a clearsigned message), this parameter can be either a file name or anything else that L<AnyEvent::Proc/pull> accepts.
If the signature doesn't follows the message, than it must be the name of the file that contains the signature and the parameter I<file> must be used to name the signed data.
=item * file
This is the name of a file or an ArrayRef of file names that contains the signed data.
=back
When the signature is valid, here are the elements of the hash that is returned by the method:
=over 4
=item * sigid
The signature id. This can be used to protect against replay attack.
=item * date
The data at which the signature has been made.
=item * timestamp
The epoch timestamp of the signature.
=item * keyid
The key id used to make the signature.
=item * user
The userid of the signer.
=item * fingerprint
The fingerprint of the signature.
=item * trust
The trust value of the public key of the signer. Those are values that can be imported in your namespace with the :trust tag. They are (TRUST_UNDEFINED, TRUST_NEVER, TRUST_MARGINAL, TRUST_FULLY, TRUST_ULTIMATE).
=back
Example:
my $sig = $gpg->verify(
signature => "file.txt.asc",
file => "file.txt"
);
=head2 verify_cb(%params[, cb => $callback|$condvar])
Asynchronous variant of L</verify>.
=head2 decrypt(%params)
This method decrypts an encrypted message. It croaks, if there is an error while decrypting the message. If the message was signed, this method also verifies the signature. If decryption is sucessful, the method either returns the valid signature par...
=over 4
=item * ciphertext
This optional parameter contains either the name of the file containing the ciphertext or a reference to a file handle containing the ciphertext.
=item * output
This optional parameter determines where the plaintext will be stored. It can be either a file name or anything else that L<AnyEvent::Proc/pipe> accepts.
=item * symmetric
This should be set to true, if the message is encrypted using symmetric cryptography.
=item * passphrase
The passphrase that should be used to decrypt the message (in the case of a message encrypted using a symmetric cipher) or the secret that will unlock the private key that should be used to decrypt the message.
=back
Example:
$gpg->decrypt(
ciphertext => "file.gpg",
output => "file.txt",
passphrase => $secret
);
=head2 decrypt_cb(%params[, cb => $callback|$condvar])
Asynchronous variant of L</decrypt>.
=head1 API OVERVIEW
The API is accessed through methods on a AnyEvent::GnuPG object which is a wrapper around the B<gpg> program. All methods takes their argument using named parameters, and errors are returned by throwing an exception (using croak). If you wan't to cat...
This modules uses L<AnyEvent::Proc>. For input data, all of L<AnyEvent::Proc/pull> and for output data, all of L<AnyEvent::Proc/pipe> possible handle types are allowed.
The code is based on L<GnuPG> with API compatibility except that L<GnuPG::Tie> is B<not> ported.
=head2 CALLBACKS AND CONDITION VARIABLES
Every method has a callback variant, suffixed with I<_cb>. These methods accept an optional parameter called I<cb>, which can be a CodeRef or an L<AnyEvent>::CondVar and returns a condvar.
$gpg->method_cb(%params, cb => sub {
my $result = shift->recv; # croaks on error
...
});
my $cv = $gpg->method_cb(%params);
my $result = $cv->recv; # croaks on error
...
The non-callback variants are all wrapper methods, looking something like this:
( run in 2.067 seconds using v1.01-cache-2.11-cpan-13bb782fe5a )