Crypt-OpenPGP
view release on metacpan or search on metacpan
If an error occurs, the return value will be "undef", and the error
message can be obtained by calling *errstr* on the *Crypt::OpenPGP*
object.
*%args* can contain:
* Data
The data to be "handled". This should be a simple scalar containing
an arbitrary amount of data.
*Data* is optional; if unspecified, you should specify a filename
(see *Filename*, below).
* Filename
The path to a file to "handle".
*Filename* is optional; if unspecified, you should specify the data
in *Data*, above. If both *Data* and *Filename* are specified, the
data in *Data* overrides that in *Filename*.
* PassphraseCallback
If the data is encrypted, you will need to supply *handle* with the
proper passphrase to unlock the private key, or the password to
decrypt the symmetrically-encrypted data (depending on the method of
encryption used). If you do not specify this parameter, this default
passphrase callback will be used:
sub _default_passphrase_cb {
my($cert) = @_;
my $prompt;
if ($cert) {
$prompt = sprintf qq(
You need a passphrase to unlock the secret key for
user "%s".
%d-bit %s key, ID %s
Enter passphrase: ), $cert->uid,
$cert->key->size,
$cert->key->alg,
substr($cert->key_id_hex, -8, 8);
} else {
$prompt = "Enter passphrase: ";
}
_prompt($prompt, '', 1);
}
If you do specify this parameter, make sure that your callback
function can handle both asymmetric and symmetric encryption.
See the *PassphraseCallback* parameter for *decrypt*, below.
$pgp->encrypt( %args )
Encrypts a block of data. The encryption is actually done with a
symmetric cipher; the key for the symmetric cipher is then encrypted
with either the public key of the recipient or using a passphrase that
you enter. The former case is using public-key cryptography, the latter,
standard symmetric ciphers. In the first case, the session key can only
be unlocked by someone with the corresponding secret key; in the second,
it can only be unlocked by someone who knows the passphrase.
Given the parameter *SignKeyID* (see below), *encrypt* will first sign
the message before encrypting it, adding a Signature packet to the
encrypted plaintext.
Returns a block of data containing two PGP packets: the encrypted
symmetric key and the encrypted data.
On failure returns "undef".
*%args* can contain:
* Compat
Specifies the PGP compatibility setting. See *COMPATIBILITY*, above.
* Data
The plaintext to be encrypted. This should be a simple scalar
containing an arbitrary amount of data.
*Data* is optional; if unspecified, you should specify a filename
(see *Filename*, below).
* Filename
The path to a file to encrypt.
*Filename* is optional; if unspecified, you should specify the data
in *Data*, above. If both *Data* and *Filename* are specified, the
data in *Data* overrides that in *Filename*.
* Recipients
The intended recipients of the encrypted message. In other words,
either the key IDs or user IDs of the public keys that should be
used to encrypt the message. Each recipient specified should be
either a key ID--an 8-digit or 16-digit hexadecimal number--or part
of a user ID that can be used to look up the user's public key in
your keyring. Examples:
8-digit hex key ID: 123ABC45
16-digit hex key ID: 678DEF90123ABC45
(Part of) User ID: foo@bar
Note that the 8-digit hex key ID is the last 8 digits of the (long)
16-digit hex key ID.
If you wish to encrypt the message for multiple recipients, the
value of *Recipients* should be a reference to a list of recipients
(as defined above). For each recipient in the list, the public key
will be looked up in your public keyring, and an encrypted session
key packet will be added to the encrypted message.
This argument is optional; if not provided you should provide the
*Passphrase* option (below) to perform symmetric-key encryption when
encrypting the session key.
* KeyID
Either this argument or *SigFile* is required.
* Data
Specifies the original signed data.
If the signature (in either *Signature* or *SigFile*) is a detached
signature, either *Data* or *Files* is a mandatory argument.
* Files
Specifies a list of files comprising the original signed data. The
value should be a reference to a list of file paths; if there is
only one file, the value can be specified as a scalar string, rather
than a reference to a list.
If the signature (in either *Signature* or *SigFile*) is a detached
signature, either *Data* or *Files* is a mandatory argument.
$pgp->keygen( %args )
NOTE: this interface is alpha and could change in future releases!
Generates a public/secret PGP keypair. Returns two keyblocks (objects of
type *Crypt::OpenPGP::KeyBlock*), a public and a secret keyblock,
respectively. A keyblock is essentially a block of keys, subkeys,
signatures, and user ID PGP packets.
*%args* can contain:
* Type
The type of key to generate. Currently there are two valid values:
"RSA" and "DSA". "ElGamal" key generation is not supported at the
moment.
This is a required argument.
* Size
Bitsize of the key to be generated. This should be an even integer;
there is no low end currently implemented in *Crypt::OpenPGP*, but
for the sake of security *Size* should be at least 1024 bits.
This is a required argument.
* Identity
A string that identifies the owner of the key. Typically this is the
combination of the user's name and an email address; for example,
Foo Bar <foo@bar.com>
The *Identity* is used to build a User ID packet that is stored in
each of the returned keyblocks.
This is a required argument.
* Passphrase
String with which the secret key will be encrypted. When read in
from disk, the key can then only be unlocked using this string.
This is a required argument.
* Version
Specifies the key version; defaults to version 4 keys. You should
only set this to version 3 if you know why you are doing so (for
backwards compatibility, most likely). Version 3 keys only support
RSA.
* Verbosity
Set to a true value to enable a status display during key
generation; since key generation is a relatively lengthy process, it
is helpful to have an indication that some action is occurring.
*Verbosity* is 0 by default.
ERROR HANDLING
If an error occurs in any of the above methods, the method will return
"undef". You should then call the method *errstr* to determine the
source of the error:
$pgp->errstr
In the case that you do not yet have a *Crypt::OpenPGP* object (that is,
if an error occurs while creating a *Crypt::OpenPGP* object), the error
can be obtained as a class method:
Crypt::OpenPGP->errstr
For example, if you try to decrypt some encrypted text, and you do not
give a passphrase to unlock your secret key:
my $pt = $pgp->decrypt( Filename => "encrypted_data" )
or die "Decryption failed: ", $pgp->errstr;
SAMPLES/TUTORIALS
Take a look at bin/pgplet for an example of usage of *Crypt::OpenPGP*.
It gives you an example of using the four main major methods (*encrypt*,
*sign*, *decrypt*, and *verify*), as well as the various parameters to
those methods. It also demonstrates usage of the callback parameters
(eg. *PassphraseCallback*).
bin/pgplet currently does not have any documentation, but its interface
mirrors that of *gpg*.
LICENSE
Crypt::OpenPGP is free software; you may redistribute it and/or modify
it under the same terms as Perl itself.
AUTHOR & COPYRIGHT
Except where otherwise noted, Crypt::OpenPGP is Copyright 2001 Benjamin
Trott, cpan@stupidfool.org. All rights reserved.
REFERENCES
1 RFC4880 - OpenPGP Message Format (2007).
http://www.faqs.org/rfcs/rfc4880.html
( run in 1.928 second using v1.01-cache-2.11-cpan-39bf76dae61 )