NAME

Crypt::OpenPGP::Signature - Signature packet

SYNOPSIS

use Crypt::OpenPGP::Signature;

my $sig = Crypt::OpenPGP::Signature->new(
                           Key  => $secret_key,
                           Data => $plaintext,
                           Type => 0x00,
                 );
my $serialized = $sig->save;

my $sig = Crypt::OpenPGP::Signature->parse($buffer);
my $hashed_data = $sig->hash_data($plaintext);

## Look up public key by $sig->key_id to get $cert, then...

my $is_valid_sig = $cert->key->verify($sig, $hashed_data);

DESCRIPTION

Crypt::OpenPGP::Signature implements PGP signature packets and provides functionality for hashing PGP packets to obtain message digests; these digests are then signed by the secret key to form a signature.

Crypt::OpenPGP::Signature reads and writes both version 3 and version 4 signatures, along with the signature subpackets found in version 4 (see Crypt::OpenPGP::Signature::SubPacket).

USAGE

Crypt::OpenPGP::Signature->new( %arg )

Creates a new signature packet object and returns that object. If there are no arguments in %arg, the object is created empty; this is used, for example, in parse (below), to create an empty packet which is then filled from the data in the buffer.

If you wish to initialize a non-empty object, %arg can contain:

• Data

  A PGP packet object of some kind. Currently the two supported objects are Crypt::OpenPGP::Certificate objects, to create self-signatures for keyrings, and Crypt::OpenPGP::Plaintext objects, for signatures on blocks of data.

  This argument is required (for a non-empty packet).

• Key

  A secret-key certificate that can be used to sign the data. In other words an object of type Crypt::OpenPGP::Certificate that holds a secret key.

  This argument is required.

• Version

  The packet format version of the signature. Valid values are either 3 or 4; version 4 signatures are the default, but will be incompatible with older PGP implementations; for example, PGP2 will only read version 3 signatures; PGP5 can read version 4 signatures, but only on signatures of data packets (not on key signatures).

  This argument is optional; the default is version 4.

• Type

  Specifies the type of signature (data, key, etc.). Valid values can be found in the OpenPGP RFC, section 5.2.1.

  This argument is optional; the default is 0x00, signature of a binary document.

• Digest

  The digest algorithm to use when generating the digest of the data to be signed. See the documentation for Crypt::OpenPGP::Digest for a list of valid values.

  This argument is optional; the default is SHA1.

$sig->save

Serializes the signature packet and returns a string of octets.

Crypt::OpenPGP::Signature->parse($buffer)

Given $buffer, a Crypt::OpenPGP::Buffer object holding (or with offset pointing to) a signature packet, returns a new Crypt::OpenPGP::Signature object, initialized with the signature data in the buffer.

$sig->hash_data(@data)

Prepares a digital hash of the packets in @data; the hashing method depends on the type of packets in @data, and the hashing algorithm used depends on the algorithm associated with the Crypt::OpenPGP::Signature object $sig. This digital hash is then signed to produce the signature itself.

You generally do not need to use this method unless you have not passed in the Data parameter to new (above).

There are two possible packet types that can be included in @data:

• Key Certificate and User ID

  An OpenPGP keyblock contains a key certificate and a signature of the public key and user ID made by the secret key. This is called a self-signature. To produce a self-signature, @data should contain two packet objects: a Crypt::OpenPGP::Certificate object and a Crypt::OpenPGP::UserID object. For example:

  my $hash = $sig->hash_data($cert, $id)
      or die $sig->errstr;

• Plaintext

  To sign a piece of plaintext, pass in a Crypt::OpenPGP::Plaintext object. This is a standard OpenPGP signature.

  my $pt = Crypt::OpenPGP::Plaintext->new( Data => 'foo bar' );
  my $hash = $sig->hash_data($pt)
      or die $sig->errstr;

$sig->key_id

Returns the ID of the key that created the signature.

$sig->timestamp

Returns the time that the signature was created in Unix epoch time (seconds since 1970).

$sig->digest

Returns a Crypt::OpenPGP::Digest object representing the digest algorithm used by the signature.

AUTHOR & COPYRIGHTS

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