/ 
Crypt-OpenPGP-1.18
River stage one • 4 direct dependents • 4 total dependents
/ Crypt::OpenPGP::Certificate

NAME

Crypt::OpenPGP::Certificate - PGP Key certificate

SYNOPSIS

use Crypt::OpenPGP::Certificate;

my $dsa_secret_key = Crypt::OpenPGP::Key::Secret->new( 'DSA' );
my $cert = Crypt::OpenPGP::Certificate->new(
    Key => $dsa_secret_key,
    Version => 4,
    Passphrase => 'foobar',
);
my $serialized = $cert->save;

# Unlock the locked certificate (using the passphrase from above)
$cert->unlock( 'foobar' );

DESCRIPTION

Crypt::OpenPGP::Certificate encapsulates a PGP key certificate for any underlying public-key algorithm, for public and secret keys, and for master keys and subkeys. All of these scenarios are handled by the same Certificate class.

A Crypt::OpenPGP::Certificate object wraps around a Crypt::OpenPGP::Key object; the latter implements all public-key algorithm-specific functionality, while the certificate layer manages some meta-data about the key, as well as the mechanisms for locking and unlocking a secret key (using a passphrase).

USAGE

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

Constructs a new PGP key certificate object and returns that object. If no arguments are provided in %arg, the certificate is empty; this is used in parse, for example, to construct an empty object, then fill it with the data in the buffer.

%arg can contain:

  • Key

    The public/secret key object, an object of type Crypt::OpenPGP::Key.

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

  • Version

    The certificate packet version, as defined in the OpenPGP RFC. The two valid values are 3 and 4.

    This argument is optional; if not provided the default is to produce version 4 certificates. You may wish to override this for compatibility with older versions of PGP.

  • Subkey

    A boolean flag: if true, indicates that this certificate is a subkey, not a master key.

    This argument is optional; the default value is 0.

  • Validity

    The number of days that this certificate is valid. This argument only applies when creating a version 3 certificate; version 4 certificates hold this information in a signature.

    This argument is optional; the default value is 0, which means that the certificate never expires.

  • Passphrase

    If you are creating a certificate for a secret key--indicated by whether or not the Key (above) is a secret key--you will need to lock it (that is, encrypt the secret part of the key). The string provided in Passphrase is used as the passphrase to lock the key.

    This argument is required if the certificate holds a secret key.

  • Cipher

    Specifies the symmetric cipher to use when locking (encrypting) the secret part of a secret key. Valid values are any supported symmetric cipher names, which can be found in Crypt::OpenPGP::Cipher.

    This argument is optional; if not specified, DES3 is used.

$cert->save

Serializes the Crypt::OpenPGP::Certificate object $cert into a string of octets, suitable for saving in a keyring file.

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

Given $buffer, a Crypt::OpenPGP::Buffer object holding (or with offset point to) a certificate packet, returns a new object of type Crypt::OpenPGP::Certificate, initialized with the data from the buffer.

$cert->lock($passphrase)

Locks the secret key data by encrypting that data with $passphrase.

Returns true on success, undef on failure; in the case of failure call errstr to get the error message.

$cert->unlock($passphrase)

Uses the passphrase $passphrase to unlock (decrypt) the secret part of the key.

Returns true on success, undef on failure; in the case of failure call errstr to get the error message.

$cert->fingerprint

Returns the key fingerprint as an octet string.

$cert->fingerprint_hex

Returns the key fingerprint as a hex string.

$cert->fingerprint_words

Returns the key fingerprint as a list of English words, where each word represents one octet from the fingerprint. See Crypt::OpenPGP::Words for more details about the encoding.

$cert->key_id

Returns the key ID.

$cert->key_id_hex

Returns the key ID as a hex string.

$cert->key

Returns the algorithm-specific portion of the certificate, the public or secret key object (an object of type Crypt::OpenPGP::Key).

$cert->public_cert

Returns a public version of the certificate, with a public key. If the certificate was already public, the same certificate is returned; if it was a secret certificate, a new Crypt::OpenPGP::Certificate object is created, and the secret key is made into a public version of the key.

$cert->version

Returns the version of the certificate (3 or 4).

$cert->timestamp

Returns the creation date and time (in epoch time).

$cert->validity

Returns the number of days that the certificate is valid for version 3 keys.

$cert->is_secret

Returns true if the certificate holds a secret key, false otherwise.

$cert->is_protected

Returns true if the certificate is locked, false otherwise.

$cert->is_subkey

Returns true if the certificate is a subkey, false otherwise.

$cert->can_encrypt

Returns true if the public key algorithm for the certificate $cert can perform encryption/decryption, false otherwise.

$cert->can_sign

Returns true if the public key algorithm for the certificate $cert can perform signing/verification, false otherwise.

AUTHOR & COPYRIGHTS

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